@conto_finance/sdk 0.6.0-beta.2 → 0.6.0

package/README.md

@@ -1,7 +1,7 @@
 # @conto_finance/sdk
 
-Conto is a buyer-side control layer. Integrate it in the agent owner's runtime or payment tools;
-the owner or budget holder sets policy before the agent pays.
+Conto is a buyer-side control layer. Integrate it in the agent owner's runtime or payment tools.
+The owner or budget holder sets policy before the agent pays.
 See [buyer-side control](https://conto.finance/docs/introduction/concepts) for the authorization
 and execution boundary.
 
@@ -66,16 +66,20 @@ Use `conto.checkout` when your agent runs its own checkout. Call Conto right bef
 method opens and again right before the payment is submitted. Conto checks the agent's rules at
 both points and holds the spend in between. Your checkout must stop whenever a call fails.
 
-Checkout checkpoints need SDK 0.6.0-beta.2 or later: `npm install @conto_finance/sdk@beta`.
+Checkout checkpoints need SDK 0.6.0 or later.
 
 ```typescript
-const checkpoint = await conto.checkout.begin({
+let checkpoint = await conto.checkout.begin({
   idempotencyKey: order.id,
   merchant: { id: 'acme-retail', name: 'ACME Retail', checkoutUrl: page.url() },
   amountMinor: 7900,
   purpose: 'Drip coffee maker the shopper chose',
   lineItems: [{ name: 'Drip coffee maker', quantity: 1, unitAmountMinor: 7900 }],
 });
+if (checkpoint.stage === 'AWAITING_APPROVAL') {
+  // The agent's rules need the owner. Throws if the owner rejects or the approval expires.
+  checkpoint = await conto.checkout.waitForApproval(checkpoint, { timeoutMs: 15 * 60_000 });
+}
 // Open Link. The buyer signs in and the final total appears.
 
 const confirmed = await conto.checkout.confirm(checkpoint, {
@@ -87,8 +91,17 @@ const confirmed = await conto.checkout.confirm(checkpoint, {
 await conto.checkout.reportOutcome(confirmed.id, { outcome: 'PAID', reference: orderNumber });
 ```
 
+- Open the payment method only when the stage is `APPROVED`. When the rules require approval,
+  `begin()` returns `AWAITING_APPROVAL`, holds the spend, and asks the owner.
+  `waitForApproval()` resolves to the approved checkpoint, whose 30 minutes to confirm start at
+  the approval. It throws `CheckoutApprovalDeniedError`, `CheckoutApprovalExpiredError`, or
+  `CheckoutApprovalTimeoutError`. After a timeout the spend stays held until you cancel.
 - If the final total differs from the approved one, `confirm()` starts a new checkpoint at the
-  final total, so the rules check the amount actually paid.
+  final total, so the rules check the amount actually paid. If that total needs approval,
+  `confirm()` throws `CheckoutApprovalPendingError`: wait with
+  `waitForApproval(error.checkpoint)`, then confirm the checkpoint it returns.
+- `begin()` throws `CheckoutCheckpointClosedError` when its idempotency key belongs to a
+  checkpoint that already closed. Start a new purchase with a new key.
 - `reportOutcome()` accepts `PAID`, `NOT_PAID`, or `UNKNOWN`. Until an outcome arrives, the spend
   stays counted. Cancel an unconfirmed checkpoint with `conto.checkout.cancel(id)`.
 - Conto records what your checkout reports and does not see the charge. For control at the
@@ -154,6 +167,16 @@ const result = await conto.payments.pay({
 });
 ```
 
+## 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.
+
 ## Protocol Clients
 
 `Conto` also exposes typed helpers for x402 and MPP service payments:
@@ -194,7 +217,7 @@ automatically. The record response then includes `policyBypass: true`, `bypassRe
 `agentFrozen`.
 
 For a Privy-managed EVM wallet, `conto.x402.pay` replaces `preAuthorize`. Pass the same fields
-plus the accepted 402 requirements; when approved, Conto signs the payment and returns the header
+plus the accepted 402 requirements. When approved, Conto signs the payment and returns the header
 to retry with:
 
 ```typescript
@@ -220,82 +243,21 @@ The MPP client mirrors the same shape with `conto.mpp.preAuthorize`, `conto.mpp.
 `conto.mpp.budget`, and `conto.mpp.services`. An MPP session grant is a ceiling: several
 `record` calls with the same `sessionId` may draw it down until it is used up or expires.
 
-## Stripe Link Checkout Commerce (test only)
-
-`LINK_CHECKOUT` is test-only and works only with a merchant enrolled with Conto. It is not a
-general merchant integration. It 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 covers only that enrolled 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 browser checkouts on supported rails (Link, card, Shop Pay, or PayPal), use
 `runGuardedCheckout` with `executionMethod: 'BROWSER_CHECKOUT'`. Other rails and checkout flows are
 not covered. It binds and atomically authorizes one exact Link, card,
 Shop Pay, or PayPal browser action without requiring 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.
+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. The helper owns authorization, one-use claim, the privileged callback, and finalization.
+The
+[Stripe Link guide](https://conto.finance/docs/guides/stripe-link#make-the-check-enforceable)
+describes the runtime boundary and includes an example.
 
 Isolated browser processes can implement `PrivilegedBrowserCheckoutDriver` and use
-`runGuardedCheckoutWithDriver`; the agent model must receive only that guarded wrapper, never the
+`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
@@ -305,7 +267,7 @@ the action's `targetUrl`, allowing Conto's origin trust policy to evaluate them
 
 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.
+project. Store the credential-free binding durably, and never add the provider `connectUrl` to it.
 
 ```typescript
 import {
@@ -357,15 +319,15 @@ 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,
+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.
+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
+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
@@ -377,12 +339,12 @@ For another Playwright or secure CDP provider, use
 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
+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
+`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.
@@ -406,15 +368,15 @@ 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.
+its inventory. The types exported from `@conto_finance/sdk/checkout-verifier` define 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.
+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:
@@ -435,60 +397,6 @@ const proposal = await conto.normalizeCommerceProposal({
 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.
@@ -523,27 +431,6 @@ 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
@@ -556,7 +443,7 @@ active POST verification is not automatically retried.
 The SDK automatically adds an idempotency key to wallet payment authorization
 requests. Provide your own stable `idempotencyKey` when a retry may happen in
 another process or job attempt. External-card approvals always require a stable
-caller-supplied `idempotencyKey`; card approval and confirmation are safe to
+caller-supplied `idempotencyKey`. Card approval and confirmation are safe to
 retry. x402 and MPP pre-authorization calls issue a grant and reserve spend. A retry
 with the same `paymentId` (x402) or `challengeId`/`credentialId` (MPP) returns the
 same live grant instead of reserving again.
@@ -566,7 +453,7 @@ ambiguous failure can be reconciled safely.
 Read-only calls retry transient network failures, `429`, and `5xx` responses. Financial execution
 and other non-idempotent mutations are never retried automatically. If execution times out, call
 `conto.payments.status(requestId)` before attempting it again. A
-`reconciliation_required` status means the execution outcome is ambiguous; do not resend the
+`reconciliation_required` status means the execution outcome is ambiguous. Do not resend the
 payment until an operator has resolved it.
 
 `ContoError` and `ContoAdminError` expose a stable error contract: `code`, `status`, `requestId`,
@@ -602,14 +489,4 @@ try {
 
 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.
+Developer support: [support@conto.finance](mailto:support@conto.finance). Include the package version and request ID. Never include API keys.