@conto_finance/sdk 0.3.1 → 0.4.0

package/README.md

@@ -19,6 +19,11 @@ npm install @conto_finance/sdk
 An admin SDK key is still an agent SDK key. It keeps the `conto_agent_...` prefix, so it is not a
 drop-in replacement for `ContoAdmin`.
 
+## Verify the connection
+
+Requires Node.js 20.19+. Call `await conto.setup()` to inspect your agent, linked wallets,
+effective policies, and scopes without creating a payment.
+
 ## Agent SDK Quick Start
 
 ```typescript
@@ -113,7 +118,9 @@ const cardAccess = new ContoCardAccess({
 Card Access claims each approved request exactly once before the executor can run. A
 duplicate or uncertain claim cannot invoke the executor again. It remains
 bypassable if another person or tool can access the card, and results are
-self-reported rather than issuer-verified. The legacy `conto.cards.controlled()`
+self-reported rather than issuer-verified. The executor receives the normalized
+purchase `idempotencyKey`; pass it to the payment processor so ambiguous
+processor responses cannot create duplicate charges. The legacy `conto.cards.controlled()`
 helper remains available for compatibility, but new customer-hosted enforcement
 should use the standalone Card Access package. Use
 `admin.cards.listRequests({ status: 'EXECUTING' })` for reconciliation and
@@ -160,6 +167,273 @@ const budget = await conto.x402.budget();
 The MPP client mirrors the same shape with `conto.mpp.preAuthorize`, `conto.mpp.record`,
 `conto.mpp.budget`, and `conto.mpp.services`.
 
+## Stripe Link Checkout Commerce
+
+For a merchant Conto controls, `LINK_CHECKOUT` evaluates policy before creating an ordinary
+Stripe-hosted Checkout Session with card and Link enabled. It needs no private Link SDK permission,
+Link connection, saved payment-method ID, SPT, or LPT.
+
+Commerce execution responses separate the provider-neutral `executionChannel`, optional
+`checkoutMethod`, and optional `settlementRail` from the legacy provider and adapter identifiers.
+For dynamic hosted Checkout, `checkoutMethod` remains absent until settlement observes Link or the
+card fallback; callers must not treat the adapter name as proof that Link was selected.
+
+```typescript
+let { execution } = await conto.beginCommerceExecution({
+  executionMethod: 'LINK_CHECKOUT',
+  idempotencyKey: crypto.randomUUID(),
+  amountMinor: 6400,
+  currency: 'USD',
+  category: 'OFFICE_SUPPLIES',
+  purpose: 'Office supplies',
+  counterparty: {
+    canonicalId: 'conto-demo-office-supply',
+  },
+  cart: {
+    lineItems: [{ name: 'Office supplies', quantity: 1, unitAmountMinor: 6400 }],
+    totals: [{ type: 'total', label: 'Total', amountMinor: 6400 }],
+  },
+  providerPresentation: {
+    approvalSummary: 'Buy office supplies from the configured merchant',
+    lineItemLabels: ['Office supplies'],
+  },
+});
+
+if (execution.status !== 'ACTION_REQUIRED' || !execution.approvalUrl) {
+  throw new Error('Stripe Checkout was not created safely');
+}
+
+if (execution.executionAdapter !== 'LINK_CHECKOUT') {
+  throw new Error('Unexpected commerce execution adapter');
+}
+
+// Hand the temporary capability to a trusted interactive browser/UI. Do not log it.
+await presentCheckoutActionSecurely(execution.approvalUrl);
+
+while (execution.status === 'ACTION_REQUIRED' || execution.status === 'PROCESSING') {
+  ({ execution } = await conto.refreshCommerceExecution(execution.id));
+}
+
+if (execution.status !== 'SETTLED' || execution.evidence.actualPaymentMethod !== 'LINK') {
+  throw new Error('This execution did not settle with Link');
+}
+```
+
+Stripe decides whether Link appears and whether the customer chooses it. Card is an explicit
+fallback, surfaced as `actualPaymentMethod: 'CARD'`; it is a valid payment but not Link evidence.
+The read-only `getCommerceExecution` projection redacts action URLs; use the initial begin result or
+the `payments:confirm` refresh path while action remains required.
+The server resolves the exact merchant name, Stripe account, and return URLs from configuration, so
+the caller cannot redirect the approved purchase. This path controls only that merchant's Conto
+channel, not unrelated Checkout pages or the consumer's Link wallet. See
+`docs/STRIPE_LINK_CHECKOUT_ADAPTER.md` for configuration, webhook, drill, and reconciliation
+requirements.
+
+## Agent checkout guard
+
+For arbitrary third-party merchants, use `runGuardedCheckout` with
+`executionMethod: 'BROWSER_CHECKOUT'`. It binds and atomically authorizes one exact Link, card,
+Shop Pay, or PayPal browser action without requiring merchant or private provider integration. The
+privileged browser executor must be available only through this wrapper; an unrestricted click or
+payment tool would bypass the control. Persist its stable dispatch attempt before calling the helper; it owns authorization,
+one-use claim, the privileged callback, and finalization. See `docs/AGENT_CHECKOUT_GUARD.md` for the
+runtime boundary and example.
+
+Isolated browser processes can implement `PrivilegedBrowserCheckoutDriver` and use
+`runGuardedCheckoutWithDriver`; the agent model must receive only that guarded wrapper, never the
+driver's `dispatch` primitive. Generate `action.targetFingerprint` with
+`fingerprintBrowserCheckoutTarget` during inspection, then wrap the privileged target resolver with
+`createVerifiedBrowserCheckoutDriver`. The wrapper re-hashes the current page, locator, accessible
+name, destination, form action, and disabled state immediately before dispatch and refuses any
+changed target without clicking it. Observed link and form destinations must be explicitly bound as
+the action's `targetUrl`, allowing Conto's origin trust policy to evaluate them before the claim.
+
+For Browserbase, use the first-class provider host. Its binding store must reject duplicate session
+IDs and atomically revoke only an active record matching the supplied organization, agent, and
+project. Store the credential-free binding durably; never add the provider `connectUrl` to it.
+
+```typescript
+import {
+  createBrowserbaseGuardedPlaywrightCheckoutRuntimeHost,
+  createBrowserbaseSessionHandoffAssertion,
+} from '@conto_finance/sdk/browserbase';
+import { chromium } from 'playwright-core';
+
+const host = createBrowserbaseGuardedPlaywrightCheckoutRuntimeHost({
+  conto,
+  browserbase: {
+    apiKey: process.env.BROWSERBASE_API_KEY!,
+    projectId: process.env.BROWSERBASE_PROJECT_ID!,
+    organizationId,
+    agentId,
+    bindingStore: browserbaseSessionBindings,
+    contextId: process.env.BROWSERBASE_CONTEXT_ID,
+    handoffKey: Buffer.from(process.env.CONTO_BROWSER_HANDOFF_KEY!, 'base64'),
+  },
+  connectOverCDP: (connectUrl) => chromium.connectOverCDP(connectUrl),
+  targetStore: {
+    encryptionKey: Buffer.from(process.env.CONTO_BROWSER_TARGET_KEY!, 'base64'),
+    blobStore: durableTargetBlobs,
+  },
+  dispatchAttemptFor: ({ idempotencyKey }) => attempts.loadOrCreate(idempotencyKey),
+  token: process.env.CONTO_BROWSER_RUNTIME_TOKEN!,
+});
+
+const browser = await host.createSession();
+// Give browser.browserSessionId, never a provider connection URL, to the guarded agent runtime.
+
+// Or attach a session created by the customer's trusted Browserbase backend.
+const browserSessionId = customerBrowserbaseSession.id;
+const expiresAt = new Date(Date.now() + 60_000).toISOString();
+const handoffAssertion = createBrowserbaseSessionHandoffAssertion(
+  {
+    browserSessionId,
+    projectId: process.env.BROWSERBASE_PROJECT_ID!,
+    organizationId,
+    agentId,
+    expiresAt,
+  },
+  Buffer.from(process.env.CONTO_BROWSER_HANDOFF_KEY!, 'base64')
+);
+await host.attachSession({ browserSessionId, handoffAssertion });
+export const POST = host.handler;
+```
+
+The Browserbase host exposes `handler`, `createSession`, `attachSession`, `observeSession`,
+`liveViewForSession`, `releaseSession`, `detachSession`, and `close`. `observeSession` returns only a
+bounded page origin/title and visible
+link/button outline; it excludes full page text, DOM, form values, URL paths and queries,
+screenshots, cookies, storage, and provider capabilities. It rechecks ownership and page identity
+after observing.
+`createSession` returns a session ID, active status, and expiry without a connection URL.
+`liveViewForSession` is a privileged operator capability: expose it only behind separate human
+authentication, never as an agent tool. A configured Context persists login state but must remain
+server-side; its durable binding store should prevent concurrent sessions from sharing one Context.
+`releaseSession` atomically revokes Conto ownership before closing the local connection and asking
+Browserbase to release the keep-alive session. Call it when the agent session ends; `close` only
+closes local Playwright connections. `attachSession` accepts only a five-minute HMAC assertion
+binding the exact provider project, Conto organization, agent, session, and expiry. Its matching
+`detachSession` revokes Conto access and closes the local connection without releasing the
+agent-host-owned provider session. Keep the independent 32-byte handoff key and assertions outside
+the model and browser page.
+
+For another Playwright or secure CDP provider, use
+`createGuardedPlaywrightCheckoutRuntimeHost` from `@conto_finance/sdk/playwright`. The generic host
+exposes only `handler`, `observeSession`, `closeSession`, and `close`, keeping discovery, mutation
+primitives, the target store, the Playwright page, and raw dispatch private.
+Lower-level integrations can still compose `createGuardedPlaywrightCheckoutRuntime`, whose façade
+exposes only `discover` and `run`; the raw driver is not returned. Target
+registrations expire after ten minutes by default. The encrypted store persists only ciphertext
+through a small durable blob port, so a runtime restart does not lose an approved
+target or disclose its locator. `dispatchAttemptFor` must atomically return the same persisted ID for
+the same checkout intent. The dispatch result classifies the browser outcome as `NEW_PAGE`,
+`PAGE_NAVIGATION`, or `SAME_PAGE`, but always reports settlement as `UNVERIFIED`; only merchant or
+provider evidence can prove payment. Never expose the page, target store, persisted registrations,
+or provider-derived locator state to the model. The inert positional reference returned by
+`observeSession` is the only locator intended for the model.
+
+The generic CDP registry accepts connection URLs only from exact secure origins and rechecks
+`connectUrlForSession` ownership on every lookup. Revocation closes a cached connection. It caches
+one connection per owned session and requires exactly one open page unless the runtime supplies
+an exact `selectPage` callback. Keep Browserbase API keys and `connectUrl` values in the privileged process.
+Call `closeSession` only when the agent session is finished because closing the Playwright browser
+may end the provider session.
+
+### Verify the exclusive checkout path
+
+Use `@conto_finance/sdk/checkout-verifier` during agent-host onboarding and whenever its tool
+registry changes. The manifest inventories every capability exposed to the model, identifies the
+session ownership boundary, and names the supported checkout methods. The verifier reports
+`ADVISORY` when an unrestricted payment-capable browser tool remains available and `UNVERIFIED`
+when active probes have not run. It reports `ENFORCEABLE` and `canBypass: false` only after the
+complete inventory is isolated and all denial, replay, tamper, alternate-path, and
+ambiguous-dispatch probes pass.
+
+The probe runner belongs to the trusted integration host and must execute against an isolated
+fixture session. A report does not remotely attest an untrusted host or discover tools omitted from
+its inventory. See `docs/CHECKOUT_INTEGRATION_VERIFIER.md` for the manifest, probe, and status
+contract.
+
+The HTTP handler implements the authenticated endpoint consumed by the optional
+`guarded_browser_checkout` MCP tool. It accepts Web `Request` objects, so it can be mounted directly
+in a compatible route or adapted to a Node server. It authenticates before reading the body,
+rejects unknown fields and mismatched cart totals, performs discovery and guarded execution in one
+request, and returns only minimized browser evidence. Use a dedicated random token of at least 32
+characters; the handler rejects Conto API keys.
+
+Organization-specific proposal facts can be sent through the typed normalization call after an
+owner or administrator registers the namespace schema:
+
+```typescript
+const proposal = await conto.normalizeCommerceProposal({
+  proposalKey: 'office-toner-2026-09-02',
+  purpose: 'Purchase toner for operations',
+  extensions: [
+    {
+      namespace: 'acme.procurement.v1',
+      value: { costCenter: 'OPS', project: 'AP_AUTOMATION' },
+    },
+  ],
+});
+```
+
+Conto rejects unregistered namespaces and schema-invalid values before policy evaluation. Accepted
+facts are bound to the schema revision and fingerprint returned on the normalized proposal.
+
+## Stripe Link Sandbox Commerce
+
+The gated Stripe Link sandbox surface uses the agent key for policy evaluation and execution. A
+Link connection must first be created by its user and explicitly bound to the agent through the
+authenticated session API. The agent SDK never receives the Link access token or payment artifact.
+
+```typescript
+const linkContext = await conto.listStripeLinkPaymentMethods(connectionId);
+if (linkContext.organizationId !== expectedOrganizationId) {
+  throw new Error('Agent key belongs to the wrong Conto organization');
+}
+const { paymentMethods } = linkContext;
+
+let { execution } = await conto.beginCommerceExecution({
+  connectionId,
+  paymentMethodId: paymentMethods[0].id,
+  executionMethod: 'STRIPE_PAYMENT_INTENT',
+  idempotencyKey: crypto.randomUUID(),
+  amountMinor: 6400,
+  currency: 'USD',
+  purpose: 'Office supplies',
+  counterparty: {
+    canonicalId: 'conto-demo-office-supply',
+    displayName: 'Conto Demo Office Supply',
+  },
+  cart: {
+    lineItems: [{ name: 'Office supplies', quantity: 1, unitAmountMinor: 6400 }],
+    totals: [{ type: 'total', label: 'Total', amountMinor: 6400 }],
+  },
+  providerPresentation: {
+    approvalSummary: 'Buy office supplies from Conto Demo Office Supply',
+    lineItemLabels: ['Office supplies'],
+  },
+});
+
+if (execution.status === 'AWAITING_APPROVAL') {
+  // Present execution.approvalUrl to the Link user, then poll with refresh.
+  ({ execution } = await conto.refreshCommerceExecution(execution.id));
+}
+
+if (execution.status === 'READY') {
+  const result = await conto.executeCommerceExecution(execution.id);
+  console.log(result.execution.evidence, result.execution.evidenceFingerprint);
+}
+```
+
+Use `getCommerceExecution(id)` for read-only reconciliation and
+`cancelCommerceExecution(id)` to cancel a nonterminal execution. `beginCommerceExecution` safely
+retries with its stable idempotency key, and `refreshCommerceExecution` safely retries observation.
+Checkout execution and cancellation are not transport-retried.
+The Stripe account and Link business-network profile are resolved from server-owned configuration;
+an agent cannot supply or replace them. Use `executionMethod: 'MPP'` only for the optional,
+configured MPP compatibility transport.
+
 ## Admin SDK Quick Start
 
 `ContoAdmin` uses an organization API key (`conto_xxx...`), not an agent SDK key.
@@ -194,6 +468,27 @@ if (frozen) {
 }
 ```
 
+### Stripe Link Checkout readiness
+
+Organization administrators can inspect the configured merchant Checkout adapter without calling
+Stripe, then explicitly verify that Conto's configured credential resolves to its configured
+merchant account:
+
+```typescript
+const { readiness } = await admin.paymentRails.getStripeLinkCheckoutReadiness();
+
+if (readiness.canVerify && !readiness.checks.accountVerified) {
+  const verified = await admin.paymentRails.verifyStripeLinkCheckoutAccount();
+  console.log(verified.readiness.status, verified.readiness.verification);
+}
+```
+
+The result contains only mode, booleans, safe status codes, timestamps, and scope statements. It
+never contains merchant/account identifiers, URLs, credentials, hashes, Stripe objects, or raw
+provider errors. Verification proves the configured account match only; Stripe still decides
+whether Link is eligible, displayed, and selected at Checkout. The static GET is retry-safe; the
+active POST verification is not automatically retried.
+
 ## What This Package Covers
 
 - `Conto` for agent-scoped payment flows
@@ -235,8 +530,7 @@ try {
 
 ## What To Use Instead
 
-- Use the REST API docs if you need endpoints that are not wrapped by this package yet, especially
-  external-wallet `approve -> transfer -> confirm` flows.
+- Use `conto.payments.approve()` and `conto.payments.confirm()` for external wallets. Your own signer sends the transfer between those calls. Neither write retries automatically.
 - Use the MCP server if a tool-calling assistant should operate Conto directly.
 
 ## Docs
@@ -250,3 +544,15 @@ try {
 ## License
 
 MIT
+
+Developer support: [support@conto.finance](mailto:support@conto.finance). Include the package version and request ID; never include API keys.
+
+### Connected-card delivery
+
+For an organization with connected cards enabled, `conto.connectedCards.draw()` returns a disposable
+credential exactly once. Keep it in memory and use it at the mandate's merchant before
+`credentialExpiresAt`. Never log or persist it. After receipt, call
+`conto.connectedCards.acknowledgeDelivery(draw.requestId)`. Acknowledgement is idempotent and records
+delivery only, not payment settlement. Replaying the original draw key cannot recover a lost
+credential; check the original outcome before requesting a replacement. Issued capacity stays
+consumed even when checkout fails.

package/dist/browserbase.d.mts

@@ -0,0 +1,139 @@
+import { Browser } from 'playwright-core';
+import { GuardedPlaywrightCheckoutHttpHandler, PlaywrightSessionObservation, GuardedPlaywrightCheckoutClient, PlaywrightCdpSessionRegistryConfig, EncryptedPlaywrightCheckoutTargetStoreConfig, GuardedPlaywrightCheckoutRuntimeConfig } from './playwright.mjs';
+import './index.mjs';
+
+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 { 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 };

package/dist/browserbase.d.ts

@@ -0,0 +1,139 @@
+import { Browser } from 'playwright-core';
+import { GuardedPlaywrightCheckoutHttpHandler, PlaywrightSessionObservation, GuardedPlaywrightCheckoutClient, PlaywrightCdpSessionRegistryConfig, EncryptedPlaywrightCheckoutTargetStoreConfig, GuardedPlaywrightCheckoutRuntimeConfig } from './playwright.js';
+import './index.js';
+
+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 { 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 };