@conto_finance/sdk 0.6.0-beta.1 → 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.
 
@@ -60,74 +60,52 @@ if (request.status === 'APPROVED') {
 }
 ```
 
-## Link Pay Token checkout pilot
+## Checkout checkpoints
 
-Install the Link pilot with `npm install @conto_finance/sdk@0.6.0-beta.1` (the `beta` channel).
-For a credential-free local workflow test:
+Use `conto.checkout` when your agent runs its own checkout. Call Conto right before the payment
+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.
 
-```typescript
-import { createLinkTestClient } from '@conto_finance/sdk/link-testing';
-const test = createLinkTestClient({ scenario: 'approved' });
-// Use the purchase shape below, then simulate the owner's approval explicitly.
-const payment = await test.link.pay(purchase);
-await test.link.approve(payment.executionId);
-const result = await test.link.resume(payment.executionId);
-// result.mode === 'SIMULATED'; result.settlementVerified === false
-```
-
-Scenarios include `approved`, `denied`, `expired`, and `interrupted`. This in-memory simulator
-makes no network calls and does not validate real policy, credentials, checkout, or settlement.
-It uses the same SDK workflow helper; the live client has no `approve()` method.
-
-
-SDK 0.6.0-beta.1 adds a one-call payment helper for configured live Link checkouts. The stable
-0.5.5 package does not include this helper.
-This remains an assisted pilot: an operator configures the checkout profile and a signed-in owner
-connects Link and binds it to your agent. Only self-contained USD digital-goods checkouts are
-supported. See the [runnable example](../../examples/link-checkout-sdk/README.md) for package
-installation and the [operator setup](../../docs/STRIPE_LINK_PAY_TOKEN_RUNTIME.md) for prerequisites.
+Checkout checkpoints need SDK 0.6.0 or later.
 
 ```typescript
-const conto = new Conto({
-  apiKey: process.env.CONTO_API_KEY!,
-  link: { connectionId: 'owner_connection_id', paymentMethodId: 'selected_payment_method_id' },
+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, {
+  amountMinor: finalTotal,
+  totals: finalTotals, // tax and shipping, if the total changed
 });
+// Submit the payment, then report what happened.
 
-// Save one idempotency key per purchase before sending. These are illustrative cart values.
-const purchase = {
-  idempotencyKey: 'persisted_order_123',
-  merchantId: 'configured_checkout_profile',
-  checkoutUrl: 'https://shop.example/checkout/order_123',
-  amountMinor: 1200,
-  purpose: 'Purchase a digital report',
-  lineItems: [{ name: 'Digital report', quantity: 1, unitAmountMinor: 1200 }],
-};
-const payment = await conto.link.pay(purchase);
+await conto.checkout.reportOutcome(confirmed.id, { outcome: 'PAID', reference: orderNumber });
 ```
 
-Before paying, call `await conto.link.setup({ merchantId: purchase.merchantId })` with an
-`agents:read` key. It returns versioned checks with the responsible actor and missing payment
-scopes, including owner binding/expiry, deployment profiles, runtime configuration, and the
-active wallet assignment currently required for budget reservations. It runs while the execution
-gate is off, reads metadata only, and never authorizes a purchase. `configurationStatus:
-'CONFIGURED'` is not proof of provider connectivity, policy approval, available funds, or settlement.
-
-Persist `payment.executionId`. When `nextAction` is `APPROVE_IN_LINK`, show `payment.approvalUrl`
-to the owner. After approval, call `await conto.link.resume(payment.executionId)` to continue that
-same purchase. `await conto.link.status(payment.executionId)` refreshes evidence without paying;
-`cancel(id)` requests cancellation. `paymentMethods()` lists masked LIVE funding sources using
-the configured connection. No method returns a Link credential.
-
-`pay()` executes immediately only when the server returns READY. It never polls indefinitely or
-retries an execution write. Policy denial and pending Conto approval throw `ContoError` before
-Link is called. An execution/cancellation error is a `LinkPaymentExecutionError` with the original
-`executionId` and `nextAction: 'RECONCILE'`; inspect `link.status(error.executionId)` before any
-further payment action. Do not create another purchase to recover from an uncertain result.
-
-Supply `totals` when tax, fees, or discounts change the amount from the line-item sum. Server
-checkout verification remains authoritative. `PROCESSING` or `COMPLETED` does not prove
-settlement. The helper simplifies SDK calls; owner login, profile setup, and live validation are
-still required, and separate unrestricted payment tools remain outside this flow.
+- 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. 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
+  moment of payment, pay with a Conto-managed wallet or a card Conto authorizes.
 
 ## External-card Policy Overlay
 
@@ -189,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:
@@ -229,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
@@ -255,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
@@ -340,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 {
@@ -392,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
@@ -412,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.
@@ -441,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:
@@ -470,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.
@@ -558,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
@@ -591,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.
@@ -601,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`,
@@ -637,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.