@conto_finance/sdk 0.3.1 → 0.5.0

package/dist/browserbase.d.ts

@@ -0,0 +1,141 @@
+import { Browser } from 'playwright-core';
+import { GuardedPlaywrightCheckoutHttpHandler, PlaywrightSessionObservation, GuardedPlaywrightCheckoutClient, PlaywrightCdpSessionRegistryConfig, EncryptedPlaywrightCheckoutTargetStoreConfig, GuardedPlaywrightCheckoutRuntimeConfig } from './playwright.js';
+import './index.js';
+
+/** Exact provider endpoints verified against Browserbase's session API; never use a wildcard. */
+declare const BROWSERBASE_CONNECT_ORIGINS: readonly string[];
+type BrowserbaseSessionStatus = 'PENDING' | 'RUNNING' | 'ERROR' | 'TIMED_OUT' | 'COMPLETED';
+type BrowserbaseSessionBindingState = 'ACTIVE' | 'REVOKED';
+type BrowserbaseSessionLifecycleOwner = 'CONTO_RUNTIME' | 'AGENT_HOST';
+/** Credential-free durable record. Never persist Browserbase connect URLs or API keys here. */
+interface BrowserbaseSessionBinding {
+    browserSessionId: string;
+    organizationId: string;
+    agentId: string;
+    projectId: string;
+    /** Missing legacy values are treated as CONTO_RUNTIME. */
+    lifecycleOwner?: BrowserbaseSessionLifecycleOwner;
+    state: BrowserbaseSessionBindingState;
+    createdAt: string;
+    expiresAt: string;
+}
+/**
+ * Durable ownership port for remote sessions. `create` must reject duplicate IDs and `revoke`
+ * must atomically transition only an ACTIVE record matching every supplied ownership field.
+ */
+interface BrowserbaseSessionBindingStore {
+    create(binding: BrowserbaseSessionBinding): Promise<boolean>;
+    get(browserSessionId: string): Promise<BrowserbaseSessionBinding | null>;
+    revoke(input: {
+        browserSessionId: string;
+        organizationId: string;
+        agentId: string;
+        projectId: string;
+        revokedAt: string;
+    }): Promise<boolean>;
+    /** Required with contextId. Release only after Browserbase confirms the provider session closed. */
+    releaseContextLease?(input: {
+        browserSessionId: string;
+        organizationId: string;
+        agentId: string;
+        projectId: string;
+    }): Promise<boolean>;
+}
+interface BrowserbaseSessionConfig {
+    /** Browserbase credential retained by the privileged runtime. Conto credentials are rejected. */
+    apiKey: string;
+    projectId: string;
+    organizationId: string;
+    agentId: string;
+    bindingStore: BrowserbaseSessionBindingStore;
+    /** Optional 32-byte server-only key required to attach sessions created by an agent host. */
+    handoffKey?: Uint8Array;
+    /** Optional server-only Browserbase Context used to persist Link or merchant authentication. */
+    contextId?: string;
+    /** Browserbase session timeout. Defaults to 900 seconds. */
+    timeoutSeconds?: number;
+    /** Browserbase API request timeout. Defaults to 10 seconds and may not exceed 60 seconds. */
+    requestTimeoutMs?: number;
+    /** Injected for tests or runtimes with an instrumented fetch implementation. */
+    fetch?: typeof fetch;
+    now?: () => Date;
+}
+interface BrowserbaseGuardedPlaywrightCheckoutRuntimeHostConfig {
+    conto: GuardedPlaywrightCheckoutClient;
+    browserbase: BrowserbaseSessionConfig;
+    /** Usually `(url) => chromium.connectOverCDP(url)`. */
+    connectOverCDP(connectUrl: string): Promise<Browser>;
+    selectPage?: PlaywrightCdpSessionRegistryConfig['selectPage'];
+    maxSessions?: number;
+    targetStore: EncryptedPlaywrightCheckoutTargetStoreConfig;
+    dispatchAttemptFor: GuardedPlaywrightCheckoutRuntimeConfig['dispatchAttemptFor'];
+    /** Dedicated service credential. Conto and Browserbase API keys are rejected. */
+    token: string;
+    maxBodyBytes?: number;
+    clickTimeoutMs?: number;
+    popupTimeoutMs?: number;
+    targetTtlMs?: number;
+    now?: () => Date;
+}
+/** Safe session projection for the agent-facing browser launcher. */
+interface BrowserbaseOwnedSession {
+    browserSessionId: string;
+    status: Extract<BrowserbaseSessionStatus, 'PENDING' | 'RUNNING'>;
+    expiresAt: string;
+}
+/** Proof-carrying request from a trusted agent host for an existing Browserbase session. */
+interface BrowserbaseSessionHandoff {
+    browserSessionId: string;
+    handoffAssertion: string;
+}
+/** Safe projection for a session whose provider lifecycle remains owned by the agent host. */
+interface BrowserbaseAttachedSession extends BrowserbaseOwnedSession {
+    lifecycleOwner: 'AGENT_HOST';
+}
+interface BrowserbaseSessionHandoffAssertionInput {
+    browserSessionId: string;
+    projectId: string;
+    organizationId: string;
+    agentId: string;
+    expiresAt: string;
+}
+/** Operator-only capability for a human authentication or challenge handoff. */
+interface BrowserbaseOwnedLiveView {
+    browserSessionId: string;
+    liveViewUrl: string;
+    expiresAt: string;
+}
+/**
+ * Closed Browserbase lifecycle plus guarded checkout façade. It never exposes the provider API
+ * key, CDP connection URL, Playwright page, target store, discovery primitive, or raw dispatch.
+ */
+interface BrowserbaseGuardedPlaywrightCheckoutRuntimeHost {
+    handler: GuardedPlaywrightCheckoutHttpHandler;
+    createSession(): Promise<BrowserbaseOwnedSession>;
+    /** Attaches an existing agent-host session after verifying a short-lived server assertion. */
+    attachSession(input: BrowserbaseSessionHandoff): Promise<BrowserbaseAttachedSession>;
+    /** Read-only, bounded projection of the exact runtime-owned page. */
+    observeSession(browserSessionId: string): Promise<PlaywrightSessionObservation>;
+    /** Returns a short-lived provider capability only to a separately authenticated operator path. */
+    liveViewForSession(browserSessionId: string): Promise<BrowserbaseOwnedLiveView>;
+    /** Revokes Conto ownership first, closes the local connection, then releases Browserbase. */
+    releaseSession(browserSessionId: string): Promise<void>;
+    /** Revokes the Conto binding without ending the externally owned Browserbase session. */
+    detachSession(browserSessionId: string): Promise<void>;
+    /** Closes local Playwright connections. Call releaseSession for each keep-alive provider session. */
+    close(): Promise<void>;
+}
+type BrowserbaseSessionErrorCode = 'BROWSERBASE_CONFIG_INVALID' | 'BROWSERBASE_PROVIDER_UNAVAILABLE' | 'BROWSERBASE_PROVIDER_RESPONSE_INVALID' | 'BROWSERBASE_SESSION_BINDING_FAILED' | 'BROWSERBASE_SESSION_HANDOFF_DISABLED' | 'BROWSERBASE_SESSION_HANDOFF_INVALID' | 'BROWSERBASE_LIVE_VIEW_UNAVAILABLE' | 'BROWSERBASE_SESSION_NOT_OWNED' | 'BROWSERBASE_SESSION_RELEASE_FAILED';
+declare class BrowserbaseSessionError extends Error {
+    readonly code: BrowserbaseSessionErrorCode;
+    constructor(code: BrowserbaseSessionErrorCode, message: string);
+}
+/** Creates a short-lived assertion after the trusted agent host creates its Browserbase session. */
+declare function createBrowserbaseSessionHandoffAssertion(input: BrowserbaseSessionHandoffAssertionInput, keyValue: Uint8Array): string;
+/**
+ * Creates the recommended Browserbase deployment boundary. Provider lifecycle, ownership checks,
+ * remote connection resolution, guarded execution, and cleanup remain in one privileged object.
+ */
+declare function createBrowserbaseGuardedPlaywrightCheckoutRuntimeHost(config: BrowserbaseGuardedPlaywrightCheckoutRuntimeHostConfig): BrowserbaseGuardedPlaywrightCheckoutRuntimeHost;
+
+export { BROWSERBASE_CONNECT_ORIGINS, type BrowserbaseAttachedSession, type BrowserbaseGuardedPlaywrightCheckoutRuntimeHost, type BrowserbaseGuardedPlaywrightCheckoutRuntimeHostConfig, type BrowserbaseOwnedLiveView, type BrowserbaseOwnedSession, type BrowserbaseSessionBinding, type BrowserbaseSessionBindingState, type BrowserbaseSessionBindingStore, type BrowserbaseSessionConfig, BrowserbaseSessionError, type BrowserbaseSessionErrorCode, type BrowserbaseSessionHandoff, type BrowserbaseSessionHandoffAssertionInput, type BrowserbaseSessionLifecycleOwner, type BrowserbaseSessionStatus, createBrowserbaseGuardedPlaywrightCheckoutRuntimeHost, createBrowserbaseSessionHandoffAssertion };