Complete API reference for the Sentience TypeScript/JavaScript SDK. All functions with parameters, return values, and examples.
Creates a browser instance with the Sentience extension loaded.
apiKey (string, optional): Your SentienceAPI subscription keyapiUrl (string, optional): Custom API endpointheadless (boolean, optional): Run browser in headless modeimport { SentienceBrowser } from '@sentience/sdk';
// Free tier (local processing)
const browser = new SentienceBrowser(undefined, undefined, false);
// Pro tier (server-side processing)
const browser = new SentienceBrowser(apiKey, undefined, true);
await browser.start();
// ... use browser
await browser.close();Captures the current page state. Returns all interactive elements with semantic information.
When using server API, consumes 1 credit per call (metered billing).
browser (SentienceBrowser): Browser instanceoptions (object, optional): Configuration options:screenshot (boolean | object): Capture screenshotlimit (number): Maximum elements to returnfilter (object): Filter optionsuse_api (boolean): Force server API or localPromise<Snapshot> with: elements, url, viewport, timestamp
import { snapshot } from '@sentience/sdk';
// Basic snapshot
const snap = await snapshot(browser);
// With options
const snap = await snapshot(browser, {
screenshot: true,
limit: 200,
filter: { min_area: 100 }
});
// Force local (no credits)
const snap = await snapshot(browser, { use_api: false });Finds the single best matching element (by importance score).
import { find } from '@sentience/sdk';
const button = find(snap, 'role=button text~"Submit"');
if (button) {
console.log(`Found: ${button.text}`);
}Finds all matching elements (returns array).
import { query } from '@sentience/sdk';
const allButtons = query(snap, 'role=button');
console.log(`Found ${allButtons.length} buttons`);=Exact match: 'role=button'!=Not equal: 'role!=link'~Contains: 'text~"sign in"'^=Starts with: 'text^="Add"'$=Ends with: 'text$="Cart"'>/<Comparisons: 'importance>500'// Find by role
const button = find(snap, 'role=button');
// Find by text (contains, case-insensitive)
const link = find(snap, 'role=link text~"more info"');
// Multiple conditions (AND)
const primaryBtn = find(snap, 'role=button clickable=true importance>800');
// Spatial filtering
const topLeft = find(snap, 'bbox.x<=100 bbox.y<=200');
// Visibility checks
const visibleLink = find(snap, 'role=link visible=true in_viewport=true');Clicks an element by ID. Uses realistic mouse simulation by default.
browser (SentienceBrowser): Browser instanceelementId (number): Element ID from snapshotuseMouse (boolean, optional): Use Playwright mouse.click()takeSnapshot (boolean, optional): Capture snapshot after clickPromise<ActionResult> with: success, duration_ms, outcome
import { click } from '@sentience/sdk';
const result = await click(browser, button.id);
if (result.success) {
console.log(`Click succeeded: ${result.outcome}`);
}Clicks at the center of a rectangle with visual feedback.
import { clickRect } from '@sentience/sdk';
// Click at coordinates
await clickRect(browser, { x: 100, y: 200, w: 50, h: 30 });
// Click using element bbox
const element = find(snap, 'role=button');
await clickRect(browser, {
x: element.bbox.x,
y: element.bbox.y,
w: element.bbox.width,
h: element.bbox.height
});Types text into an input field.
import { typeText } from '@sentience/sdk';
const emailInput = find(snap, 'role=textbox');
await typeText(browser, emailInput.id, 'user@example.com');Presses a keyboard key (Enter, Escape, Tab, etc.).
import { press } from '@sentience/sdk';
await press(browser, 'Enter'); // Submit form
await press(browser, 'Escape'); // Close modalWaits for an element to appear. Auto-optimizes polling interval based on API usage.
browser (SentienceBrowser): Browser instanceselector (string): Query DSL selectortimeout (number, optional): Max time in ms (default: 10000)interval (number, optional): Polling interval in msuseApi (boolean, optional): Force server or localimport { waitFor, click } from '@sentience/sdk';
// Wait for button
const result = await waitFor(browser, 'role=button text~"Submit"', 5000);
if (result.found) {
await click(browser, result.element.id);
}
// Wait with custom interval (local)
const result = await waitFor(browser, 'role=button', 5000, 500, false);Creates an assertion builder for fluent testing.
.toExist(timeout): Assert element exists.toBeVisible(timeout): Assert element is visible.toHaveText(text, timeout): Assert element contains text.toHaveCount(n, timeout): Assert query returns N elementsimport { expect } from '@sentience/sdk';
// Assertions
await expect(browser, 'role=button text="Submit"').toExist(5000);
await expect(browser, 'role=heading').toBeVisible();
await expect(browser, 'role=button').toHaveText('Submit');
await expect(browser, 'role=link').toHaveCount(10);Extracts page content as text, markdown, or raw HTML.
options (object, optional):format (string): "raw", "text", or "markdown"import { read } from '@sentience/sdk';
// Markdown
const result = await read(browser, { format: 'markdown' });
console.log(result.content);
// Text
const result = await read(browser, { format: 'text' });
console.log(result.content);Captures a screenshot of the current page.
options (object, optional):format (string): "png" or "jpeg"quality (number): JPEG quality (1-100)import { screenshot } from '@sentience/sdk';
import { writeFileSync } from 'fs';
// PNG
const dataUrl = await screenshot(browser, { format: 'png' });
const base64Data = dataUrl.split(',')[1];
const imageData = Buffer.from(base64Data, 'base64');
writeFileSync('screenshot.png', imageData);
// JPEG with quality
const dataUrl = await screenshot(browser, { format: 'jpeg', quality: 85 });