TypeScript SDK Reference

View on GitHub

Complete API reference for the Sentience TypeScript/JavaScript SDK. All functions with parameters, return values, and examples.

Browser Setup

↑ Back to top

new SentienceBrowser(apiKey?, apiUrl?, headless?)

Creates a browser instance with the Sentience extension loaded.

Parameters:

  • • apiKey (string, optional): Your Predicate Systems subscription key
  • • apiUrl (string, optional): Custom API endpoint
  • • headless (boolean, optional): Run browser in headless mode

Example:

import { 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();

Snapshot API

↑ Back to top

snapshot(browser, options?)

Captures the current page state. Returns all interactive elements with semantic information.

Credit Consumption

When using server API, consumes 1 credit per call (metered billing).

Parameters:

  • • browser (SentienceBrowser): Browser instance
  • • options (object, optional): Configuration options:
    • • screenshot (boolean | object): Capture screenshot
    • • limit (number): Maximum elements to return
    • • filter (object): Filter options
    • • use_api (boolean): Force server API or local

Returns:

Promise<Snapshot> with: elements, url, viewport, timestamp

Example:

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 });

Query API

↑ Back to top

find(snapshot, selector)

Finds the single best matching element (by importance score).

Example:

import { find } from '@sentience/sdk';

const button = find(snap, 'role=button text~"Submit"');
if (button) {
  console.log(`Found: ${button.text}`);
}

query(snapshot, selector)

Finds all matching elements (returns array).

Example:

import { query } from '@sentience/sdk';

const allButtons = query(snap, 'role=button');
console.log(`Found ${allButtons.length} buttons`);

Query DSL Operators

=Exact match: 'role=button'
!=Not equal: 'role!=link'
~Contains: 'text~"sign in"'
^=Starts with: 'text^="Add"'
$=Ends with: 'text$="Cart"'
>/<Comparisons: 'importance>500'

Query Examples:

// 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');

Action API

↑ Back to top

click(browser, elementId, useMouse?, takeSnapshot?)

Clicks an element by ID. Uses realistic mouse simulation by default.

Parameters:

  • • browser (SentienceBrowser): Browser instance
  • • elementId (number): Element ID from snapshot
  • • useMouse (boolean, optional): Use Playwright mouse.click()
  • • takeSnapshot (boolean, optional): Capture snapshot after click

Returns:

Promise<ActionResult> with: success, duration_ms, outcome

Example:

import { click } from '@sentience/sdk';

const result = await click(browser, button.id);
if (result.success) {
  console.log(`Click succeeded: ${result.outcome}`);
}

clickRect(browser, rect, highlight?, highlightDuration?, takeSnapshot?)

Clicks at the center of a rectangle with visual feedback.

Example:

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
});

typeText(browser, elementId, text, takeSnapshot?)

Types text into an input field.

Example:

import { typeText } from '@sentience/sdk';

const emailInput = find(snap, 'role=textbox');
await typeText(browser, emailInput.id, 'user@example.com');

press(browser, key)

Presses a keyboard key (Enter, Escape, Tab, etc.).

Example:

import { press } from '@sentience/sdk';

await press(browser, 'Enter');   // Submit form
await press(browser, 'Escape');  // Close modal

Wait API

↑ Back to top

waitFor(browser, selector, timeout?, interval?, useApi?)

Waits for an element to appear. Auto-optimizes polling interval based on API usage.

Parameters:

  • • browser (SentienceBrowser): Browser instance
  • • selector (string): Query DSL selector
  • • timeout (number, optional): Max time in ms (default: 10000)
  • • interval (number, optional): Polling interval in ms
  • • useApi (boolean, optional): Force server or local

Example:

import { 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);

Expect API (Assertions)

expect(browser, selector)

Creates an assertion builder for fluent testing.

Methods:

  • • .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 elements

Example:

import { 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);

Content Reading API

↑ Back to top

read(browser, options?)

Extracts page content as text, markdown, or raw HTML.

Parameters:

  • • options (object, optional):
    • • format (string): "raw", "text", or "markdown"

Example:

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);

Screenshot API

↑ Back to top

screenshot(browser, options?)

Captures a screenshot of the current page.

Parameters:

  • • options (object, optional):
    • • format (string): "png" or "jpeg"
    • • quality (number): JPEG quality (1-100)

Example:

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 });

Next Steps

Quick Start →

Get started in 5 minutes

Python Reference →

View Python SDK docs

Demo Playground →

See examples in action

Previous
Python SDK Reference
Next
Examples