@predicatelabs/sdk 0.99.9

package/dist/browser.d.ts

@@ -0,0 +1,154 @@
+/**
+ * Playwright browser harness with extension loading
+ */
+import { BrowserContext, Page } from 'playwright';
+import { StorageState, Snapshot } from './types';
+import { SnapshotOptions } from './snapshot';
+import { IBrowser } from './protocols/browser-protocol';
+export type PermissionDefault = 'clear' | 'deny' | 'grant';
+export type PermissionPolicy = {
+    default?: PermissionDefault;
+    autoGrant?: string[];
+    geolocation?: {
+        latitude: number;
+        longitude: number;
+        accuracy?: number;
+    };
+    origin?: string;
+};
+export declare function normalizeDomain(domain: string): string;
+export declare function domainMatches(host: string, pattern: string): boolean;
+export declare function extractHost(url: string): string | null;
+export declare function isDomainAllowed(host: string | null, allowed?: string[], prohibited?: string[]): boolean;
+export declare class SentienceBrowser implements IBrowser {
+    private context;
+    private browser;
+    private page;
+    private extensionPath;
+    private userDataDir;
+    private _apiKey?;
+    private _apiUrl?;
+    private headless;
+    private _proxy?;
+    private _userDataDir?;
+    private _storageState?;
+    private _recordVideoDir?;
+    private _recordVideoSize?;
+    private _viewport?;
+    private _deviceScaleFactor?;
+    private _allowedDomains?;
+    private _prohibitedDomains?;
+    private _keepAlive;
+    private _permissionPolicy?;
+    /**
+     * Create a new SentienceBrowser instance
+     *
+     * @param apiKey - Optional API key for server-side processing (Pro/Enterprise tiers)
+     * @param apiUrl - Optional API URL (defaults to https://api.sentienceapi.com if apiKey provided)
+     * @param headless - Whether to run in headless mode (defaults to true in CI, false locally)
+     * @param proxy - Optional proxy server URL (e.g., 'http://user:pass@proxy.example.com:8080')
+     * @param userDataDir - Optional path to user data directory for persistent sessions
+     * @param storageState - Optional storage state to inject (cookies + localStorage)
+     * @param recordVideoDir - Optional directory path to save video recordings
+     * @param recordVideoSize - Optional video resolution as object with 'width' and 'height' keys
+     * @param viewport - Optional viewport size as object with 'width' and 'height' keys
+     * @param deviceScaleFactor - Optional device scale factor to emulate high-DPI (Retina) screens.
+     *                          Examples: 1.0 (default, standard DPI), 2.0 (Retina/high-DPI, like MacBook Pro), 3.0 (very high DPI)
+     *                          If undefined, defaults to 1.0 (standard DPI).
+     * @param allowedDomains - Optional list of allowed domains for navigation.
+     * @param prohibitedDomains - Optional list of prohibited domains for navigation.
+     * @param keepAlive - Keep browser alive after close() (no teardown).
+     */
+    constructor(apiKey?: string, apiUrl?: string, headless?: boolean, proxy?: string, userDataDir?: string, storageState?: string | StorageState | object, recordVideoDir?: string, recordVideoSize?: {
+        width: number;
+        height: number;
+    }, viewport?: {
+        width: number;
+        height: number;
+    }, deviceScaleFactor?: number, allowedDomains?: string[], prohibitedDomains?: string[], keepAlive?: boolean, permissionPolicy?: PermissionPolicy);
+    private applyPermissionPolicy;
+    start(): Promise<void>;
+    goto(url: string): Promise<void>;
+    private waitForExtension;
+    getPage(): Page | null;
+    private _copyRecursive;
+    getApiKey(): string | undefined;
+    getApiUrl(): string | undefined;
+    /**
+     * Take a snapshot of the current page
+     * Implements IBrowser interface
+     */
+    snapshot(options?: SnapshotOptions): Promise<Snapshot>;
+    /**
+     * Parse proxy connection string into Playwright format.
+     *
+     * @param proxyString - Standard format "http://username:password@host:port"
+     *                    or "socks5://user:pass@host:port"
+     * @returns Playwright proxy object or undefined if invalid
+     */
+    private parseProxy;
+    /**
+     * Inject storage state (cookies + localStorage) into browser context.
+     *
+     * @param storageState - Path to JSON file, StorageState object, or plain object
+     */
+    private injectStorageState;
+    /**
+     * Get the browser context (for utilities like saveStorageState)
+     */
+    getContext(): BrowserContext | null;
+    /**
+     * Create SentienceBrowser from an existing Playwright BrowserContext.
+     *
+     * This allows you to use Sentience SDK with a browser context you've already created,
+     * giving you more control over browser initialization.
+     *
+     * @param context - Existing Playwright BrowserContext
+     * @param apiKey - Optional API key for server-side processing
+     * @param apiUrl - Optional API URL (defaults to https://api.sentienceapi.com if apiKey provided)
+     * @returns SentienceBrowser instance configured to use the existing context
+     *
+     * @example
+     * ```typescript
+     * import { chromium } from 'playwright';
+     * import { SentienceBrowser } from '@sentience/sdk';
+     *
+     * const context = await chromium.launchPersistentContext(...);
+     * const browser = SentienceBrowser.fromExisting(context);
+     * await browser.getPage().goto('https://example.com');
+     * ```
+     */
+    static fromExisting(context: BrowserContext, apiKey?: string, apiUrl?: string): Promise<SentienceBrowser>;
+    /**
+     * Create SentienceBrowser from an existing Playwright Page.
+     *
+     * This allows you to use Sentience SDK with a page you've already created,
+     * giving you more control over browser initialization.
+     *
+     * @param page - Existing Playwright Page
+     * @param apiKey - Optional API key for server-side processing
+     * @param apiUrl - Optional API URL (defaults to https://api.sentienceapi.com if apiKey provided)
+     * @returns SentienceBrowser instance configured to use the existing page
+     *
+     * @example
+     * ```typescript
+     * import { chromium } from 'playwright';
+     * import { SentienceBrowser } from '@sentience/sdk';
+     *
+     * const browserInstance = await chromium.launch();
+     * const context = await browserInstance.newContext();
+     * const page = await context.newPage();
+     * await page.goto('https://example.com');
+     *
+     * const browser = SentienceBrowser.fromPage(page);
+     * ```
+     */
+    static fromPage(page: Page, apiKey?: string, apiUrl?: string): SentienceBrowser;
+    close(outputPath?: string): Promise<string | null>;
+}
+/**
+ * Predicate rebrand alias for SentienceBrowser.
+ * Kept as a runtime alias to avoid breaking existing integrations.
+ */
+export declare const PredicateBrowser: typeof SentienceBrowser;
+//# sourceMappingURL=browser.d.ts.map

package/dist/browser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser.d.ts","sourceRoot":"","sources":["../src/browser.ts"],"names":[],"mappings":"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"}