API Reference

import { Sentinel } from '@isoldex/sentinel';

const sentinel = new Sentinel({
  apiKey: process.env.GEMINI_API_KEY,
  headless: true,
  browser: 'chromium',
  verbose: 1,
  enableCaching: true,
});

await sentinel.init();
// ...
await sentinel.close();

const results = await Sentinel.parallel(
  [
    { url: 'https://site-a.com', goal: 'Extract product name and price' },
    { url: 'https://site-b.com', goal: 'Extract product name and price' },
  ],
  {
    apiKey: process.env.GEMINI_API_KEY,
    concurrency: 2,
    headless: true,
  }
);

// results: ParallelResult[]
results.forEach((r) => {
  if (r.success) console.log(r.data);
  else           console.error(r.error);
});

// Basic
const result = await sentinel.act('click the login button');

// With variables
const result = await sentinel.act('fill email with %email%', {
  variables: { email: 'user@example.com' },
  retries: 3,
});

console.log(result.success);   // true
console.log(result.action);    // 'click'
console.log(result.selector);  // '#login-btn'
console.log(result.attempts);  // 1

// All supported action types:
await sentinel.act('click the submit button');
await sentinel.act('fill the email field with user@example.com');
await sentinel.act('append " (edited)" to the title field');
await sentinel.act('hover over the user avatar');
await sentinel.act('press Enter');
await sentinel.act('select "Germany" from the country dropdown');
await sentinel.act('double-click the image');
await sentinel.act('right-click the file row');
await sentinel.act('scroll down 300 pixels');
await sentinel.act('scroll up');
await sentinel.act('scroll to the footer');

import { z } from 'zod';

// With Zod schema (recommended — gives full TypeScript inference)
const product = await sentinel.extract(
  'Extract product name, price, and rating',
  z.object({
    name:   z.string(),
    price:  z.string(),
    rating: z.number(),
  })
);

// product is typed as { name: string; price: string; rating: number }
console.log(product.name);

// With plain JSON schema
const raw = await sentinel.extract(
  'Extract all review titles',
  { type: 'object', properties: { titles: { type: 'array', items: { type: 'string' } } } }
);

const elements = await sentinel.observe();
// Returns a description of all interactive elements currently visible

const specific = await sentinel.observe('find all buttons in the checkout section');
console.log(specific);
// "checkout-btn: [button] 'Proceed to checkout' at #checkout-form > button.primary
//  back-btn: [button] 'Back to cart' at #checkout-form > button.secondary"

const result = await sentinel.run(
  'Find the cheapest laptop under €500 and add it to the cart',
  {
    maxSteps: 25,
    onStep: (event) => {
      console.log(`[${event.step}/${event.totalSteps}] ${event.action.instruction}`);
      console.log(`  → ${event.action.action} on ${event.action.selector}`);
    },
  }
);

console.log(result.goalAchieved);  // true
console.log(result.totalSteps);    // 14
console.log(result.data);          // { name: '...', price: '€349' }
console.log(result.selectors);     // { addToCartBtn: '#add-to-cart', ... }
console.log(result.message);       // "Goal achieved: ..."

// Save session (cookies + localStorage) for reuse
const sentinel = new Sentinel({
  apiKey: process.env.GEMINI_API_KEY,
  sessionPath: './sessions/github.json',
});

await sentinel.init();

// Check if already logged in
if (await sentinel.hasLoginForm()) {
  await sentinel.act('fill username with myuser');
  await sentinel.act('fill password with %pw%', { variables: { pw: process.env.GH_PASS! } });
  await sentinel.act('click sign in');
  await sentinel.saveSession();
}
// On next run, cookies are restored automatically

// Persist IndexedDB, WebSQL, Service Workers (e.g. WhatsApp Web, Notion)
const sentinel = new Sentinel({
  apiKey:      process.env.GEMINI_API_KEY,
  userDataDir: './profiles/whatsapp',
});

await sentinel.init();
await sentinel.goto('https://web.whatsapp.com');
// QR scan only needed on first run

// Open a new tab
const tabId = await sentinel.newTab('https://example.com');

// Switch to it
await sentinel.switchTab(tabId);

// How many tabs are open?
const count = await sentinel.tabCount();

// Close current tab
await sentinel.closeTab();

// Start recording
await sentinel.startRecording();

// Perform actions normally
await sentinel.goto('https://github.com');
await sentinel.act('click Sign in');
await sentinel.act('fill username');

// Stop and export as TypeScript
const ts   = await sentinel.stopRecording();
const code = await sentinel.exportWorkflowAsCode();
const json = await sentinel.exportWorkflowAsJSON();

// Replay later
await sentinel.replay(JSON.parse(json));

// Enable vision grounding (screenshot fallback for Canvas / Shadow DOM)
const sentinel = new Sentinel({
  apiKey: process.env.GEMINI_API_KEY,
  visionFallback: true,
});

// Take a screenshot (returns Buffer)
const buf = await sentinel.screenshot();

// Describe current screen state
const description = await sentinel.describeScreen();
console.log(description);
// "A checkout page with a total of €349 visible in the top right..."

import { chromium } from 'playwright';
import { Sentinel } from '@isoldex/sentinel';

const browser = await chromium.launch();
const page    = await browser.newPage();

// Extend an existing page object
const ai = await Sentinel.extend(page, { apiKey: process.env.GEMINI_API_KEY });

await page.goto('https://example.com');

// Now use act/extract/observe alongside existing playwright APIs
await ai.act('click the login button');
const data = await ai.extract('get the page title', { title: 'string' });

// Standard Playwright still works
await expect(page.locator('h1')).toBeVisible();

// Listen to events
sentinel.on('action',   (e) => console.log('action:', e));
sentinel.on('navigate', (e) => console.log('navigated to:', e.url));
sentinel.on('close',    ()  => console.log('browser closed'));

// Token usage
const usage = sentinel.getTokenUsage();
console.log(usage);
// { promptTokens: 12400, completionTokens: 840, totalTokens: 13240, estimatedCost: 0.0018 }

// Export all logs
const logs = sentinel.exportLogs();

import {
  SentinelError,
  ActionError,
  ExtractionError,
  NavigationError,
  AgentError,
  NotInitializedError,
} from '@isoldex/sentinel';

try {
  await sentinel.act('click the non-existent button');
} catch (err) {
  if (err instanceof ActionError) {
    console.error('Action failed after', err.attempts, 'attempts');
    console.error('Instruction:', err.instruction);
    console.error('Selector tried:', err.selector);
  }
}