{"_id":"@allternit/browser-tools","name":"@allternit/browser-tools","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@allternit/browser-tools","version":"0.1.0","description":"Browser automation toolkit for A2R agent task execution","type":"module","main":"./dist/index.js","types":"./dist/index.d.ts","exports":{".":{"import":"./dist/index.js","types":"./dist/index.d.ts"}},"scripts":{"build":"tsc","dev":"tsc --watch","test":"vitest","typecheck":"tsc --noEmit","lint":"eslint src/**/*.ts"},"keywords":["browser","automation","playwright","agent","a2r"],"dependencies":{"playwright":"^1.42.0"},"devDependencies":{"@types/node":"^20.10.0","typescript":"^5.3.0","vitest":"^1.0.0","eslint":"^8.55.0"},"peerDependencies":{"@allternit/mcp-apps-adapter":"workspace:*"},"gitHead":"197c1497d02ffb94fe24fbdc6a6de34e98297159","_id":"@allternit/browser-tools@0.1.0","_nodeVersion":"25.6.1","_npmVersion":"11.9.0","dist":{"integrity":"sha512-J0sF6CtYlnch37zaJTDZkQdRuwI2UPKgKDpmXkdSsYIZp/Zp2u5m99f9yHvF64Pxm84BJg64M2RSGLuCrT0Ipw==","shasum":"cf4a4cd5b15a35a582ad3728058d8e0f5a4bbc3a","tarball":"https://registry.npmjs.org/@allternit/browser-tools/-/browser-tools-0.1.0.tgz","fileCount":67,"unpackedSize":454045,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQCwnpnlAmt/KoFLCC0a/qjNk55wA+eP8dee4mbyirqfcgIhAJhKmiByGfSuPA9GTGv7AkufqnBHUp2Jf0P8/kzm5OL3"}]},"_npmUser":{"name":"allternit","email":"allternitpbc@gmail.com"},"directories":{},"maintainers":[{"name":"allternit","email":"allternitpbc@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/browser-tools_0.1.0_1776018414445_0.7184617474540069"},"_hasShrinkwrap":false}},"time":{"created":"2026-04-12T18:26:54.285Z","0.1.0":"2026-04-12T18:26:54.603Z","modified":"2026-04-12T18:26:54.855Z"},"maintainers":[{"name":"allternit","email":"allternitpbc@gmail.com"}],"description":"Browser automation toolkit for A2R agent task execution","keywords":["browser","automation","playwright","agent","a2r"],"readme":"# @allternit/browser-tools\n\nBrowser automation toolkit for A2R agent task execution. Built on Playwright with integrated safety controls.\n\n## Features\n\n- **Session Management** - Create and manage isolated browser sessions\n- **Navigation Control** - URL navigation with history (back/forward/reload)\n- **DOM Extraction** - Extract text, links, images, forms, tables\n- **Action Execution** - Click, type, select, scroll, hover, press keys\n- **Event Streaming** - Real-time monitoring of navigation, DOM changes, clicks\n- **Safety & Quarantine** - Host allowlists, action approval, audit logging\n- **Screenshot Capture** - Full page or element screenshots\n\n## Installation\n\n```bash\nnpm install @allternit/browser-tools\n# or\npnpm add @allternit/browser-tools\n```\n\n## Quick Start\n\n```typescript\nimport { \n  createSession, \n  navigate, \n  click,\n  type,\n  takeScreenshot,\n  extractContent,\n  eventStreamManager,\n} from '@allternit/browser-tools';\n\n// Create browser session\nconst session = await createSession({\n  viewport: { width: 1280, height: 720 },\n  headless: false,\n});\n\n// Navigate to URL\nawait navigate(session.id, { url: 'https://example.com' });\n\n// Subscribe to events\nconst streamId = eventStreamManager.subscribe(\n  session.id,\n  (event) => console.log(event.type, event.payload),\n  { captureClicks: true, captureNavigation: true }\n);\n\n// Extract page content\nconst content = await extractContent(session.id);\nconsole.log(content.text);\nconsole.log(content.links);\n\n// Perform actions\nawait click(session.id, { selector: '#submit-button' });\nawait type(session.id, { selector: '#search-input', text: 'query' });\n\n// Take screenshot\nconst screenshot = await takeScreenshot(session.id, { fullPage: true });\n\n// Clean up\nawait closeSession(session.id);\n```\n\n## API Reference\n\n### Session Management\n\n```typescript\n// Create session\nconst session = await createSession({\n  viewport?: { width: number; height: number; deviceScaleFactor?: number; isMobile?: boolean };\n  headless?: boolean;\n  incognito?: boolean;\n  userAgent?: string;\n  locale?: string;\n  timezone?: string;\n});\n\n// Close session\nawait closeSession(session.id);\n\n// Get session info\nconst info = await getSessionInfo(session.id);\n```\n\n### Navigation\n\n```typescript\n// Navigate to URL\nawait navigate(session.id, { \n  url: 'https://example.com',\n  waitUntil?: 'load' | 'domcontentloaded' | 'networkidle',\n  timeout?: number,\n});\n\n// History navigation\nawait goBack(session.id);\nawait goForward(session.id);\nawait reload(session.id);\n```\n\n### Content Extraction\n\n```typescript\n// Extract all content\nconst content = await extractContent(session.id, {\n  includeHidden?: boolean;\n  maxLength?: number;\n  includeSelectors?: boolean;\n});\n\n// Find specific element\nconst element = await findElement(session.id, {\n  selector?: string;\n  text?: string;\n  tag?: string;\n  nth?: number;\n});\n```\n\n### Actions\n\n```typescript\n// Click\nawait click(session.id, { \n  selector: '#button',\n  button?: 'left' | 'right' | 'middle';\n  clickCount?: number;\n  waitForNavigation?: boolean;\n});\n\n// Type text\nawait type(session.id, { \n  selector: '#input', \n  text: 'value',\n  clearFirst?: boolean,\n});\n\n// Select dropdown\nawait select(session.id, { \n  selector: '#select',\n  value?: string;\n  label?: string;\n  index?: number;\n});\n\n// Scroll\nawait scroll(session.id, { \n  selector?: string;  // Scroll element into view\n  x?: number;         // Or scroll to coordinates\n  y?: number;\n});\n\n// Hover\nawait hover(session.id, { selector: '#tooltip' });\n\n// Press key\nawait press(session.id, { \n  selector?: string;  // Optional: specific element\n  key: 'Enter',\n  modifiers?: ('alt' | 'ctrl' | 'meta' | 'shift')[];\n});\n\n// Wait\nawait wait(session.id, { \n  selector?: string;\n  state?: 'visible' | 'hidden';\n  time?: number;  // milliseconds\n});\n```\n\n### Event Streaming\n\n```typescript\nimport { eventStreamManager } from '@allternit/browser-tools';\n\n// Subscribe to events\nconst streamId = eventStreamManager.subscribe(\n  sessionId,\n  (event) => {\n    console.log(event.type);      // 'navigation' | 'dom_change' | 'click' | 'input' | 'scroll' | 'screenshot'\n    console.log(event.payload);   // Event-specific data\n  },\n  {\n    captureNavigation: true,\n    captureDOMChanges: true,\n    captureClicks: true,\n    captureInputs: true,\n    captureScrolls: false,\n    captureScreenshots: false,\n    screenshotInterval: 5000,\n  }\n);\n\n// Add additional handler\neventStreamManager.addHandler(streamId, anotherHandler);\n\n// Unsubscribe\neventStreamManager.unsubscribe(streamId);\n```\n\n### Safety & Quarantine\n\n```typescript\nimport { \n  DEFAULT_SAFETY_POLICY,\n  STRICT_SAFETY_POLICY,\n  checkNavigationSafety,\n  quarantineManager,\n} from '@allternit/browser-tools';\n\n// Check navigation safety\nconst result = checkNavigationSafety(url, DEFAULT_SAFETY_POLICY);\nif (!result.allowed) {\n  console.log('Blocked:', result.reason);\n}\n\n// Create quarantine session\nquarantineManager.createSession(sessionId, 'incognito', {\n  allowedHosts: ['example.com'],\n  blockedHosts: ['localhost', '127.0.0.1'],\n  maxNavigationDepth: 10,\n});\n\n// Get audit log\nconst auditLog = quarantineManager.getAuditLog(sessionId);\n```\n\n## Safety Features\n\n### Host Restrictions\n\n```typescript\nconst policy = {\n  allowedHosts: ['*.example.com'],  // Allow all subdomains\n  blockedHosts: ['localhost', '127.0.0.1', '*.internal'],\n  allowedSchemes: ['https:'],        // Only HTTPS\n  maxNavigationDepth: 10,\n};\n```\n\n### Action Approval\n\n```typescript\n// Some actions require approval based on policy\nconst result = checkActionSafety('click', selector, policy);\nif (result.requiresApproval) {\n  // Queue for user approval\n  approvalQueue.requestApproval({\n    id: generateId(),\n    sessionId,\n    action: 'click',\n    target: selector,\n    timestamp: new Date(),\n    expiresAt: new Date(Date.now() + 60000),\n  });\n}\n```\n\n## Browser Support\n\n- Chromium (default)\n- Firefox\n- WebKit\n\n## License\n\nMIT\n","readmeFilename":"README.md","_rev":"1-17627eda47db0dd6c9bdd43dcb07a0f7"}