@conto_finance/sdk 0.7.1 → 0.8.0

package/README.md

@@ -155,7 +155,17 @@ const confirmed = await conto.checkout.confirm(result.checkpoint, {
   or `link-cli` is missing or logged out, `getLinkCard()` cancels the checkpoint to release the
   held spend and throws `LinkCardDeniedError`, `LinkCardExpiredError`, `LinkCardTimeoutError`, or
   `LinkWalletUnavailableError`. All extend `LinkCardError`. Do not pay.
-- Retrying with the same input resumes the same checkpoint and Link request.
+- Retrying with the same input resumes the same checkpoint and Link request while Conto's approval
+  is open. That approval lasts 30 minutes. For about 5 to 10 minutes after it lapses, the stage can
+  still read `APPROVED`, so a retry can return the card, but `confirm()` refuses it. Once the stage
+  is `OUTCOME_UNKNOWN`, a retry throws `CHECKOUT_CHECKPOINT_NOT_APPROVED`.
+- `getLinkCard()` and `replaceLinkCard()` tell Conto the Link request ID as soon as Stripe Link
+  creates it. If Conto's approval then lapses, or a rule stops `confirm()`, Conto keeps the spend held,
+  because the card may still work. The checkpoint moves to stage `OUTCOME_UNKNOWN`. Cancel the Link
+  request, then call `conto.checkout.cancel(id)` to release the spend. Otherwise the owner gets a
+  review alert and records what happened. If Conto cannot record the request, the SDK cancels it in
+  Link, then cancels the checkpoint, and throws `LinkCardError` with code `LINK_CARD_NOT_RECORDED`.
+  `holdReleased` says whether the spend was released.
 - Pass `onLinkApproval` to get Stripe Link's approval page, so a person without the Link app can
   approve on the web while signed in to Link. It is called once, after Conto approves and Link
   creates the request, with `{ checkpoint, linkRequestId, approvalUrl, approvalExpiresAt }`.
@@ -164,19 +174,105 @@ const confirmed = await conto.checkout.confirm(result.checkpoint, {
 - The card (`number`, `securityValue` for the CVC, `expMonth`, `expYear`, `validUntil`, `last4`,
   `brand`) stays in this process. Printing or serializing the result shows only the last four
   digits. It never appears in an error.
-- The card covers the approved total, so `confirm()` with a `paymentReference` refuses a
-  different total. Call `conto.checkout.replaceLinkCard(result, { wallet, amountMinor })` to
+- The card covers the approved total, so `confirm()` refuses a different total for a checkpoint from
+  `getLinkCard()` or `onLinkApproval`, even when `paymentReference` is not passed. Call
+  `conto.checkout.replaceLinkCard(result, { wallet, amountMinor })` to
   cancel the old card and checkpoint and get a card for the final total.
 - Any `LinkWallet` works in place of `linkCliWallet()`: it creates a card request, waits for
   approval, retrieves the card, and cancels.
 - The protection holds only when the agent cannot also run `link-cli`, use a shell, or call Link
   with your credentials itself.
 - Pass observed final items and charges to `confirm()` even when the total is unchanged.
-  The server rejects a changed cart against the approved intent. The trusted host must
+  The server checks the items and the final total. Other rows, such as tax and shipping, may
+  differ from the ones passed to `begin()`. The trusted host must
   validate the actual merchant and checkout, own a durable one-use payment dispatch
   claim, and keep card use outside model tools. Replaying a confirmed checkpoint is
   not permission to submit payment again.
 
+## Shared budgets
+
+A shared budget is one limit that several agents draw on. The budget holder sets it in Spending
+controls or with `admin.spending`. Agents no budget covers are not affected, except a buyer linked to
+an owner workspace. Until a budget in that workspace covers it, those paths fail with `reasonCode`
+`LINKED_BUDGET_REQUIRED`.
+
+```typescript
+// Agent key. Nothing on conto.spending can raise a limit, approve a task, or release a hold.
+const { budgets } = await conto.spending.budgets();
+await conto.spending.preview({
+  amount: '40',
+  currency: 'USDC',
+  sourceId: walletId,
+  merchant: recipientAddress,
+});
+
+// Organization API key.
+await admin.spending.createBudget({
+  name: 'Team tools',
+  scope: 'AGENTS',
+  participantIds: [agentA, agentB],
+  amount: '500',
+  currency: 'USDC',
+  period: 'MONTHLY',
+  periodStart: new Date().toISOString(),
+  periodEnd: new Date(Date.now() + 365 * 86_400_000).toISOString(),
+});
+```
+
+**A budget stops other payment paths.** While it exists, it stops x402, MPP, external wallet
+payments, agent-to-agent payments, payment grants, checkout relay, hosted Stripe Link, guarded browser
+checkout (`runGuardedCheckout()`), card overlays and checkout checkpoints, including
+`checkout.getLinkCard()`, for every agent it covers. A paused, expired or not yet started budget still
+stops them. Until its start date, while paused, and after its end date, a budget also refuses the
+managed wallet payments and connected card draws it covers, for those agents. A task's budget does
+neither. It applies only to a managed wallet payment or connected card draw that names the task.
+`updateBudget()` can resume a paused budget or extend an
+expired one, and a start date cannot be changed. To end a budget, call `admin.spending.deleteBudget(id, { version })`. It fails with
+`reasonCode` `BUDGET_HAS_HOLDS` while a purchase holds spend against the budget. Try budgets on a test
+organization first.
+
+- A budget covers purchases in its own currency, so set it to what the wallets pay in: `USDC` on
+  Base, `USDC.e` on Tempo or `pathUSD` on Tempo Testnet. `USD`, `USDC` and `USDC.e` budgets cover one
+  another at par when no budget at that level, workspace or agent, is in the exact currency. A
+  managed wallet payment or connected card draw is refused, whatever the budget's state, when a level
+  has budgets for that agent and none covers its currency. `preview()` gives `reasonCode`
+  `BUDGET_CURRENCY_UNSUPPORTED`. A budget's currency cannot be changed.
+- `preview()` needs a managed wallet linked to the agent, and that wallet's stablecoin as `currency`.
+  It holds nothing and approves nothing, so keep the request, approval and execute flow.
+- When a budget requires a task, ask for one with `conto.spending.requestTask()`. Once the budget
+  holder approves it, pass its id as `context.taskRequestId` on `payments.request()` from a managed
+  wallet, or as `taskRequestId` on `connectedCards.draw()`. With a self-custody wallet,
+  `payments.request()` returns `DENIED`, and `payments.approve()` refuses the task fields.
+- `context.purchaseKey` identifies one purchase. A key cannot be used again, even after its purchase
+  is released, so use a new key for a new attempt.
+- `payments.request()` can return `APPROVED` for a purchase a budget refuses. `payments.execute()`
+  then throws status 409 and code `SHARED_BUDGET_BLOCKED`. With `autoExecute`, the request stays
+  `APPROVED` and nothing is thrown. To see why, call `preview()` with the same `taskRequestId` and
+  `purchaseKey`.
+- `purchases()` lists purchases against budgets in the agent's organization, not Commerce
+  `conto.purchases`. It is empty when none of those budgets has applied. A buyer linked to an owner
+  workspace has no row for a purchase that only an owner budget covered. The owner reads those with
+  `admin.spending.purchases()`.
+- `admin.spending` needs an organization API key. `createBudget()`, `updateBudget()`, `deleteBudget()`
+  and `decideTask()` need `policies:write`. `accounting()`, `attachEvidence()` and `reviewEvidence()`
+  need `transactions:write`. `reconcile()` needs `spending:reconcile`, which Standard keys do not
+  have. An admin SDK key cannot change budgets, decide tasks, or reconcile.
+- `attachEvidence()` takes a PDF, PNG or JPEG of at most 2 MiB, with up to 10 files per purchase. Set
+  the Blob's `type`, for example `new Blob([bytes], { type: 'application/pdf' })`. A Blob with no type,
+  or with a type that does not match the file's first bytes, fails with `reasonCode` `INVALID_FILE`.
+  Conto does not take the amount, currency or merchant from the file. The budget holder enters them
+  with `reviewEvidence()`.
+- `exportPurchases()` returns CSV bytes and fails with `reasonCode` `EXPORT_TOO_LARGE` above 10,000
+  purchases.
+- Budget errors have `code` `POLICY_VIOLATION`, so read `reasonCode` on `ContoError` and
+  `ContoAdminError`. Some also have `nextActions`, such as `SHARED_BUDGET_EXCEEDED` with
+  `REQUEST_BUDGET_INCREASE`. `checkout.begin()`, `getLinkCard()` and `replaceLinkCard()` have `code`
+  `CHECKPOINT_BUDGET_NOT_SUPPORTED` with that `reasonCode` set. `payments.execute()` has `code`
+  `SHARED_BUDGET_BLOCKED` and no `reasonCode`.
+- A `VALIDATION_ERROR` on a spending call usually lists the fields in `fieldErrors`. It does not when
+  the call got a field it does not accept, such as `periodStart` or `currency` on `updateBudget()`. A
+  `payments.request()` validation failure never has `fieldErrors`.
+
 ## External-card Policy Overlay
 
 The admin client registers only a masked card alias and assigns cooperative
@@ -322,9 +418,10 @@ Shop Pay, or PayPal browser action without requiring private provider integratio
 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.
+When a rule requires the owner's approval, `runGuardedCheckout` stops with status 409 and code
+`APPROVAL_REQUIRED`. Checkpoints wait for the owner instead, so for Stripe Link prefer the
+[checkpoints in the Stripe Link guide](https://conto.finance/docs/guides/stripe-link#add-the-checkpoints)
+or `getLinkCard()`.
 
 Isolated browser processes can implement `PrivilegedBrowserCheckoutDriver` and use
 `runGuardedCheckoutWithDriver`. The agent model must receive only that guarded wrapper, never the
@@ -527,7 +624,8 @@ and other non-idempotent mutations are never retried automatically. If execution
 payment until an operator has resolved it.
 
 `ContoError` and `ContoAdminError` expose a stable error contract: `code`, `status`, `requestId`,
-`retryAfter`, and locally generated `retryGuidance` where applicable. Arbitrary server details,
+`retryAfter`, `fieldErrors` on most spending validation failures, `reasonCode` and `nextActions` on a
+budget refusal, and locally generated `retryGuidance` where applicable. Arbitrary server details,
 context, hints, and workflow steps are not forwarded through SDK errors:
 
 ```typescript

package/dist/index.d.mts

@@ -839,6 +839,311 @@ declare function verifyPurchaseWebhook(input: {
     data: PurchaseEvent;
 };
 
+/**
+ * Shared budgets: one limit that several agents draw on, set in Spending controls.
+ *
+ * `conto.spending` uses an agent key. `admin.spending` is for the budget holder and uses an
+ * organization API key. Exact amounts are decimal strings. These APIs never give agents authority
+ * to raise ceilings.
+ */
+/**
+ * File bytes. `new Blob()`, `new File()` and `new Response()` accept them on every supported
+ * TypeScript, with or without the DOM lib.
+ */
+type DownloadBytes = ReturnType<Uint8Array['slice']> & {
+    readonly buffer: ArrayBuffer;
+};
+type SpendingRequester = {
+    download(path: string): Promise<DownloadBytes>;
+    request<T>(method: string, path: string, body?: Record<string, unknown> | FormData): Promise<T>;
+};
+interface BudgetSnapshot {
+    id: string;
+    name: string;
+    scope: string;
+    currency: string;
+    period: 'ONCE' | 'MONTHLY';
+    periodStart: string;
+    periodEnd: string;
+    authorizationStartsAt?: string;
+    authorizationEndsAt?: string;
+    amount: string;
+    held: string;
+    settled: string;
+    refunded: string;
+    available: string;
+    status: string;
+    isActive: boolean;
+    version: number;
+    requiresTask: boolean;
+    taskRequestId: string | null;
+    participantIds?: string[];
+}
+interface TaskInput {
+    purpose: string;
+    amount: string;
+    currency: string;
+    expiresAt: string;
+    permittedMerchants?: string[];
+    permittedSourceIds?: string[];
+}
+interface TaskSnapshot {
+    id: string;
+    purpose: string;
+    status: string;
+    amount: string;
+    currency: string;
+    expiresAt: string;
+    budgetId: string | null;
+    agentId: string;
+    participantIds: string[];
+    permittedMerchants: string[];
+    permittedSourceIds: string[];
+}
+/** A purchase against shared budgets. These are separate from Commerce `conto.purchases`. */
+interface PurchaseSnapshot {
+    id: string;
+    agentId: string;
+    executionReference: string;
+    sourceType: string;
+    sourceId: string;
+    merchant: string;
+    purpose: string;
+    currency: string;
+    authorizedAmount: string;
+    heldAmount: string;
+    settledAmount: string;
+    refundedAmount: string;
+    status: string;
+    enforcementMode: string;
+    verification: string;
+    nextActions: string[];
+    taskRequestId: string | null;
+    department: string | null;
+    project: string | null;
+    accountingCode: string | null;
+    createdAt: string;
+}
+interface PurchaseDetail extends PurchaseSnapshot {
+    events: Array<{
+        id: string;
+        kind: string;
+        createdAt: string;
+        evidenceRef: string;
+        heldAmount: string;
+        settledAmount: string;
+        refundedAmount: string;
+    }>;
+    evidence: Array<{
+        id: string;
+        filename: string;
+        matchStatus: string;
+        createdAt: string;
+    }>;
+}
+interface PreviewInput {
+    amount: string;
+    currency: string;
+    sourceId: string;
+    merchant: string;
+    purpose?: string;
+    taskRequestId?: string;
+    purchaseKey?: string;
+}
+interface BudgetInput {
+    name: string;
+    scope: 'WORKSPACE' | 'AGENT' | 'AGENTS';
+    participantIds?: string[];
+    amount: string;
+    currency: string;
+    period: 'ONCE' | 'MONTHLY';
+    periodStart: string;
+    periodEnd: string;
+    requiresTask?: boolean;
+}
+declare class SpendingClient {
+    private client;
+    constructor(client: SpendingRequester);
+    /**
+     * CSV of this agent's purchases against budgets in its own organization. Fails with `reasonCode`
+     * `EXPORT_TOO_LARGE` above 10,000 purchases.
+     */
+    exportPurchases(): Promise<DownloadBytes>;
+    downloadEvidence(purchaseId: string, evidenceId: string): Promise<DownloadBytes>;
+    /** The budgets that cover this agent, with what is held, settled and available. */
+    budgets(): Promise<{
+        snapshotAt: string;
+        timezone: string;
+        budgets: BudgetSnapshot[];
+        buyerConnection?: {
+            revoked: boolean;
+            participantId: string;
+        };
+    }>;
+    tasks(cursor?: string): Promise<{
+        tasks: TaskSnapshot[];
+        nextCursor: string | null;
+    }>;
+    /**
+     * Ask the budget holder to approve a task budget. Once it is approved, pass its id as
+     * `context.taskRequestId` on `payments.request()` from a managed wallet, or as `taskRequestId` on
+     * `connectedCards.draw()`. A task's budget applies only to a payment or draw that names the task,
+     * and it stops nothing on other paths.
+     */
+    requestTask(input: TaskInput): Promise<{
+        id: string;
+        status: string;
+        nextActions: string[];
+    }>;
+    /** This agent's purchases against budgets in its own organization. Empty when none has applied. */
+    purchases(cursor?: string): Promise<{
+        purchases: PurchaseSnapshot[];
+        nextCursor: string | null;
+    }>;
+    purchase(purchaseId: string): Promise<PurchaseDetail>;
+    /**
+     * Check a purchase against shared budgets before requesting the payment. It holds nothing and
+     * approves nothing. `sourceId` must be a managed wallet linked to this agent, and `currency` must
+     * be that wallet's stablecoin, such as `USDC` on Base, `USDC.e` on Tempo or `pathUSD` on Tempo
+     * Testnet. A purchase the budgets would refuse throws a `ContoError`.
+     */
+    preview(input: PreviewInput): Promise<{
+        budgetCheck: string;
+        configured: boolean;
+        authorizationGranted: false;
+        scope: "SHARED_BUDGET_ONLY";
+        snapshotAt: string;
+        nextActions: string[];
+    }>;
+    /**
+     * Attach a PDF, PNG or JPEG of at most 2 MiB, with up to 10 files per purchase. Set the Blob's
+     * `type` to `application/pdf`, `image/png` or `image/jpeg`. A Blob with no type, or with a type
+     * that does not match the file's first bytes, fails with `reasonCode` `INVALID_FILE`.
+     */
+    attachEvidence(purchaseId: string, file: Blob, filename: string): Promise<{
+        id: string;
+        matchStatus: string;
+    }>;
+}
+declare class AdminSpendingClient {
+    private client;
+    constructor(client: SpendingRequester);
+    /**
+     * CSV of the organization's purchases against shared budgets. Fails with `reasonCode`
+     * `EXPORT_TOO_LARGE` above 10,000 purchases.
+     */
+    exportPurchases(): Promise<DownloadBytes>;
+    /**
+     * Attach a PDF, PNG or JPEG of at most 2 MiB, with up to 10 files per purchase. Set the Blob's
+     * `type` to `application/pdf`, `image/png` or `image/jpeg`. A Blob with no type, or with a type
+     * that does not match the file's first bytes, fails with `reasonCode` `INVALID_FILE`.
+     */
+    attachEvidence(purchaseId: string, file: Blob, filename: string): Promise<{
+        id: string;
+        matchStatus: string;
+    }>;
+    downloadEvidence(purchaseId: string, evidenceId: string): Promise<DownloadBytes>;
+    budgets(): Promise<{
+        snapshotAt: string;
+        timezone: string;
+        budgets: BudgetSnapshot[];
+        buyerConnection?: {
+            revoked: boolean;
+            participantId: string;
+        };
+    }>;
+    /**
+     * Create a shared budget. Needs an organization API key with `policies:write`.
+     *
+     * While a budget exists, it stops x402, MPP, external wallet payments, agent-to-agent payments,
+     * payment grants, checkout relay, hosted Stripe Link, guarded browser checkout
+     * (`runGuardedCheckout()`), card overlays and checkout checkpoints, including
+     * `checkout.getLinkCard()`, for every agent it covers. A paused, expired or not yet started budget
+     * still stops them. Until its start date, while paused, and after its end date, it also refuses
+     * the managed wallet payments and connected card draws it covers, for those agents. A start date
+     * cannot be changed.
+     * `deleteBudget()` ends a budget. Fails with `reasonCode`
+     * `ENROLLMENT_RECONCILIATION_REQUIRED` while the organization or a participating agent has an
+     * open commitment.
+     */
+    createBudget(input: BudgetInput): Promise<{
+        id: string;
+        version: number;
+    }>;
+    /**
+     * Change a budget's amount or active state, or move its end date to a later time in the future.
+     * Needs the budget's current `version`. A task budget can only change its active state. Pausing
+     * stops new purchases on it, and does not lift what it stops on other payment paths.
+     */
+    updateBudget(budgetId: string, input: {
+        version: number;
+        amount?: string;
+        isActive?: boolean;
+        periodEnd?: string;
+    }): Promise<{
+        id: string;
+        version: number;
+    }>;
+    /**
+     * End a budget, so it stops applying on every path. Needs the budget's current `version`. Fails
+     * with `reasonCode` `BUDGET_HAS_HOLDS` while a purchase holds spend against it, and `TASK_BUDGET`
+     * for a task's budget, which ends by closing the task. A linked buyer with no budget left fails
+     * with `reasonCode` `LINKED_BUDGET_REQUIRED`.
+     */
+    deleteBudget(budgetId: string, input: {
+        version: number;
+    }): Promise<{
+        id: string;
+        deleted: true;
+    }>;
+    tasks(cursor?: string): Promise<{
+        tasks: TaskSnapshot[];
+        nextCursor: string | null;
+    }>;
+    /** Approve, reject or close a task. Needs an organization API key with `policies:write`. */
+    decideTask(taskId: string, input: {
+        decision: 'APPROVE' | 'REJECT' | 'CLOSE';
+        amount?: string;
+        participantIds?: string[];
+    }): Promise<{
+        id: string;
+        status: string;
+    }>;
+    purchases(cursor?: string): Promise<{
+        purchases: PurchaseSnapshot[];
+        nextCursor: string | null;
+    }>;
+    purchase(purchaseId: string): Promise<PurchaseDetail>;
+    /** Record what happened to a purchase. Needs an API key with the `spending:reconcile` scope. */
+    reconcile(purchaseId: string, input: {
+        eventKey: string;
+        kind: 'RELEASED' | 'SETTLED' | 'REFUNDED' | 'UNKNOWN';
+        settledAmount?: string;
+        refundedAmount?: string;
+        final?: boolean;
+        evidenceRef: string;
+    }): Promise<PurchaseSnapshot | null>;
+    accounting(purchaseId: string, input: {
+        department: string | null;
+        project: string | null;
+        accountingCode: string | null;
+    }): Promise<{
+        id: string;
+        department: string | null;
+        project: string | null;
+        accountingCode: string | null;
+    }>;
+    /** Record the amount, currency and merchant on a file. Conto does not take them from the file. */
+    reviewEvidence(purchaseId: string, evidenceId: string, input: {
+        amount: string;
+        currency: string;
+        merchant: string;
+    }): Promise<{
+        id: string;
+        matchStatus: string;
+    }>;
+}
+
 interface ApiErrorMetadata {
     code: string;
     status: number;
@@ -851,6 +1156,8 @@ interface ApiErrorMetadata {
         message: string;
     }>;
     reasons?: string[];
+    reasonCode?: string;
+    nextActions?: string[];
 }
 
 /**
@@ -894,6 +1201,9 @@ declare class ContoAdminError extends Error {
     readonly requestId?: string;
     readonly retryAfter?: number;
     readonly retryGuidance?: string;
+    readonly reasonCode?: string;
+    readonly nextActions?: string[];
+    readonly fieldErrors?: ApiErrorMetadata['fieldErrors'];
     constructor(message: string, metadata: ApiErrorMetadata);
 }
 interface PaginationParams {
@@ -1506,6 +1816,7 @@ declare class ContoAdmin {
     #private;
     private baseUrl;
     private timeout;
+    spending: AdminSpendingClient;
     agents: AgentsClient;
     wallets: WalletsClient;
     cards: AdminCardsClient;
@@ -1523,11 +1834,16 @@ declare class ContoAdmin {
         signal?: AbortSignal;
         lastEventId?: string;
     }): Promise<Response>;
+    /**
+     * Download a file from the Conto API as bytes. It retries like a read, and
+     * failures throw ContoAdminError as request() does.
+     */
+    download(path: string): Promise<DownloadBytes>;
     /**
      * Make an authenticated request to the Conto API. Reads retry. A write retries
      * only when `idempotent` says the API deduplicates it, as purchase creation does.
      */
-    request<T>(method: string, path: string, body?: Record<string, unknown>, options?: {
+    request<T>(method: string, path: string, body?: Record<string, unknown> | FormData, options?: {
         idempotent?: boolean;
     }): Promise<T>;
 }
@@ -1858,6 +2174,13 @@ interface PaymentRequestInput {
             currency?: string;
             dueDate?: string;
         };
+        /** An approved shared budget task, from `conto.spending.requestTask()`. */
+        taskRequestId?: string;
+        /**
+         * A stable id for this purchase against shared budgets. A key cannot be used again, even after
+         * its purchase is released, so use a new key for a new attempt.
+         */
+        purchaseKey?: string;
     };
     /** Specific wallet ID to use (optional) */
     walletId?: string;
@@ -2023,7 +2346,8 @@ interface ExternalWalletApprovalInput {
     recipientName?: string;
     purpose?: string;
     category?: string;
-    context?: PaymentRequestInput['context'];
+    /** A self-custody wallet cannot pay against a shared task, so the task fields are refused. */
+    context?: Omit<NonNullable<PaymentRequestInput['context']>, 'taskRequestId' | 'purchaseKey'>;
 }
 interface ExternalWalletApprovalResult {
     approved: boolean;
@@ -2326,6 +2650,10 @@ interface ConnectedCardDrawInput {
     /** Only USD is supported. Defaults to USD. */
     currency?: 'USD';
     merchant: ConnectedCardDrawMerchant;
+    /** Why the agent wants this purchase, up to 500 characters. Shown to the person reviewing it. */
+    purpose?: string;
+    /** An approved task, for a budget that requires one. Naming a task grants nothing. */
+    taskRequestId?: string;
 }
 /**
  * Live single-use card material returned by {@link ConnectedCardsClient.draw}.
@@ -2355,6 +2683,8 @@ interface ConnectedCardDrawResult {
     replayed: boolean;
     decision: 'APPROVED' | 'DENIED' | 'REQUIRES_APPROVAL';
     reasons: string[];
+    /** Present when a budget refused the draw, for example `TASK_REQUIRED`. */
+    reasonCodes?: string[];
     /** Present when the draw outcome is ambiguous and needs reconciliation. */
     reconciliationRequired?: boolean;
     /**
@@ -2454,6 +2784,8 @@ interface TestCardDrawResult {
     replayed: boolean;
     decision: 'APPROVED' | 'DENIED' | 'REQUIRES_APPROVAL';
     reasons: string[];
+    /** Present when a budget refused the draw, for example `TASK_REQUIRED`. */
+    reasonCodes?: string[];
     reconciliationRequired?: boolean;
     /** Present only on the response that issues it. A replay never returns it again. */
     testCredential?: TestCardCredential;
@@ -2585,7 +2917,10 @@ interface ConfirmCheckoutCheckpointInput {
     currency?: 'USD';
     /** Observed final items. Supplied items are checked even when the total is unchanged. */
     lineItems?: CommerceLineItemInput[];
-    /** Observed final charges. Supplied charges are checked even when the total is unchanged. */
+    /**
+     * Observed final charges, such as subtotal, tax and shipping. Conto checks that the final
+     * total matches. The other rows may differ from the ones passed to begin().
+     */
     totals?: CommerceTotalInput[];
     /** Page where the payment is submitted: the merchant's site or the payment method's. */
     pageUrl?: string;
@@ -3338,6 +3673,8 @@ declare class ContoError extends Error {
     readonly actionUrl?: string;
     readonly fieldErrors?: ApiErrorMetadata['fieldErrors'];
     readonly reasons?: string[];
+    readonly reasonCode?: string;
+    readonly nextActions?: string[];
     readonly diagnostics?: SetupDiagnostics;
     constructor(message: string, metadata: ApiErrorMetadata, diagnostics?: unknown);
 }
@@ -3458,6 +3795,7 @@ declare class Conto {
     private timeout;
     /** Lightweight checkpoints before the payment method opens and before payment. */
     checkout: CheckoutClient;
+    spending: SpendingClient;
     payments: PaymentsClient;
     cards: CardsClient;
     connectedCards: ConnectedCardsClient;
@@ -3555,8 +3893,13 @@ declare class Conto {
         signal?: AbortSignal;
         lastEventId?: string;
     }): Promise<Response>;
+    /**
+     * Download a file from the Conto API as bytes. It retries like a read, and
+     * failures throw ContoError as request() does.
+     */
+    download(path: string): Promise<DownloadBytes>;
     /** Make an authenticated request to the Conto API */
-    request<T>(method: string, path: string, body?: Record<string, unknown>, options?: ContoRequestOptions): Promise<T>;
+    request<T>(method: string, path: string, body?: Record<string, unknown> | FormData, options?: ContoRequestOptions): Promise<T>;
 }
 /** Agent client for the cooperative external-card policy overlay. */
 declare class CardsClient {
@@ -3893,9 +4236,10 @@ declare class CheckoutClient {
      * 1. Conto runs checkpoint 1 and holds the spend. When a rule requires the
      *    owner's approval, this waits for it.
      * 2. Only then does the wallet ask Link for a card for exactly the approved
-     *    amount at this merchant. The person approves it in Link. Pass
-     *    onLinkApproval to get Link's approval page, so they can approve on the
-     *    web without the Link app.
+     *    amount at this merchant. Conto records the Link request at once, so the
+     *    hold stays while the card may be usable. The person approves it in
+     *    Link. Pass onLinkApproval to get Link's approval page, so they can
+     *    approve on the web without the Link app.
      * 3. The card is returned. It never reaches Conto.
      *
      * Then fill in the card, call confirm(result.checkpoint, { amountMinor,
@@ -3908,7 +4252,9 @@ declare class CheckoutClient {
      * held spend and throws a LinkCardError. When Conto cannot cancel an open Link
      * request, it keeps the hold and throws LINK_CARD_NOT_CANCELLED with the
      * request id. Retrying with the same input resumes the same checkpoint and
-     * Link request.
+     * Link request while Conto's approval is open. Once the stage is OUTCOME_UNKNOWN,
+     * a retry throws CHECKOUT_CHECKPOINT_NOT_APPROVED: cancel the Link request, then
+     * the checkpoint.
      */
     getLinkCard(input: GetLinkCardInput): Promise<LinkCardResult>;
     /**
@@ -3920,5 +4266,5 @@ declare class CheckoutClient {
     replaceLinkCard(previous: LinkCardResult, input: ReplaceLinkCardInput): Promise<LinkCardResult>;
 }
 
-export { AdminPurchasingClient, BrowserActionFinalizationPendingError, BrowserCheckoutTargetVerificationError, CardsClient, CheckoutApprovalDeniedError, CheckoutApprovalExpiredError, CheckoutApprovalPendingError, CheckoutApprovalTimeoutError, CheckoutCheckpointClosedError, CheckoutClient, ConnectedCardsClient, Conto, ContoAdmin, ContoAdminError, ContoError, ControlledExternalCardPaymentTool, ExternalCardConfirmationPendingError, Conto as Giro, ContoError as GiroError, LinkCardCredential, LinkCardDeniedError, LinkCardError, LinkCardExpiredError, LinkCardTimeoutError, LinkWallet, LinkWalletUnavailableError, OrganizationPurchasesClient, OrganizationRecurringPurchasesClient, PurchasesClient, RecurringPurchasesClient, TestCardsClient, canonicalizeBrowserCheckoutTarget, createVerifiedBrowserCheckoutDriver, Conto as default, fingerprintBrowserCheckoutTarget, isFinalPurchaseStatus, parseServerSentEvents, verifyPurchaseWebhook };
-export type { AdminExternalCardOverlayEnforcement, Agent, AgentCheckoutAction, AgentCheckoutActionKind, AgentExternalCard, AgentSetupResult, AgentStatus, AgentType, AgentWalletLink, ApprovedExternalCardExecution, AssignExternalCardInput, AssignedPolicy, AuthorizeCheckoutActionResult, BeginCheckoutCheckpointInput, BeginCommerceExecutionInput, BrowserActionClaimResult, BrowserActionDispatchObservationInput, BrowserActionFinalizeResult, BrowserCheckoutAction, BrowserCheckoutTargetResolver, BrowserCheckoutTargetSnapshot, BrowserCheckoutTargetVerificationCode, CancellationOutcome, CanonicalBrowserCheckoutTargetSnapshot, ChainType, CheckoutActionAuthorization, CheckoutCheckpoint, CheckoutCheckpointApproval, CheckoutCheckpointMethod, CheckoutCheckpointNextAction, CheckoutCheckpointStage, CheckoutOutcome, CheckoutPaymentReference, CommerceCheckoutMethod, CommerceContextRequirement, CommerceExecution, CommerceExecutionAdapterKind, CommerceExecutionArtifactKind, CommerceExecutionChannel, CommerceExecutionConstraint, CommerceExecutionConstraintCoverage, CommerceExecutionConstraintCoverageLevel, CommerceExecutionDeliveryMode, CommerceExecutionEvidence, CommerceExecutionProvider, CommerceExecutionResult, CommerceExecutionSourceKind, CommerceExecutionStatus, CommerceFactConfidence, CommerceFactProvenanceInput, CommerceFactSource, CommerceFulfillmentInput, CommerceLineItemInput, CommerceProposalFactKey, CommerceProposalMissingFact, CommerceProposalResolution, CommerceProposalState, CommerceSettlementRail, CommerceTotalInput, CommerceTotalType, ComparePolicyVersionsResponse, ConfirmCheckoutCheckpointInput, ConnectedCardBrief, ConnectedCardCredential, ConnectedCardDrawInput, ConnectedCardDrawMerchant, ConnectedCardDrawResult, ConnectedCardDrawable, ConnectedCardListResult, ConnectedCardMandate, ConnectedCardMandateMerchant, ConnectedCardOutcomeReport, ConnectedCardOutcomeReportResult, ConnectedCardReference, ContoAdminConfig, ContoConfig, ContoRequestOptions, ControlledExternalCardPaymentResult, CreateAgentInput, CreatePolicyInput, CreatePolicyRuleInput, CreatePurchaseInput, CreateSdkKeyInput, CreateSdkKeyResult, CreateWalletInput, CustodyType, CustomerCustodyMode, CustomerWalletControlModel, CustomerWalletKeyAccess, DelegationType, ExecuteCommerceExecutionResult, ExternalCard, ExternalCardApprovalInput, ExternalCardApprovalResult, ExternalCardConfirmationInput, ExternalCardConfirmationResult, ExternalCardExecutionClaimResult, ExternalCardExecutionResult, ExternalCardExecutor, ExternalCardOverlayEnforcement, ExternalCardRequestStatusResult, ExternalWalletApprovalInput, ExternalWalletApprovalResult, ExternalWalletConfirmationInput, ExternalWalletConfirmationResult, FreezeAgentInput, GetLinkCardInput, ContoConfig as GiroConfig, GuardCheckoutResult, GuardedBrowserDispatchResult, GuardedCheckoutInput, LinkApprovalCallback, LinkApprovalEvent, LinkCardResult, LinkWalletInput, ListAgentsParams, ListAgentsResponse, ListPoliciesParams, ListPoliciesResponse, ListPolicyVersionsResponse, ListWalletsParams, ListWalletsResponse, MppBudgetResult, MppPreAuthorizeInput, MppPreAuthorizeResult, MppRecordInput, MppRecordResult, NormalizeCommerceProposalInput, OrganizationMember, PaginatedResponse, PaginationParams, PauseExternalCardAssignmentResult, PaymentExecuteResult, PaymentRequestInput, PaymentRequestResult, PaymentStatusResult, Policy, PolicyRule, PolicyType, PolicyVersionChangeType, PolicyVersionDetail, PolicyVersionDiff, PolicyVersionFieldChange, PolicyVersionSnapshot, PolicyVersionSnapshotRule, PolicyVersionSummary, PrivilegedBrowserCheckoutDriver, ProtocolBudgetResult, ProtocolPreAuthorizeResult, ProtocolRecordGrant, ProtocolRecordGrantResult, ProtocolServiceSummary, ProtocolServicesResult, ProveWalletOwnershipInput, ProvisionWalletResult, Purchase, PurchaseAction, PurchaseActionAuthority, PurchaseActionKind, PurchaseAllowance, PurchaseBuyer, PurchaseBuyerCompanyCard, PurchaseBuyerCompanyCardLimits, PurchaseBuyerKitchenContext, PurchaseCompanyCard, PurchaseDelegation, PurchaseEvent, PurchaseEventPage, PurchaseEvidence, PurchaseGrocery, PurchaseGroceryItem, PurchaseGroceryList, PurchaseHostedLink, PurchaseItem, PurchaseKitchenContext, PurchaseKitchenInventoryItem, PurchaseKitchenListItem, PurchaseKitchenPreferences, PurchaseKitchenRecipe, PurchaseKitchenUsual, PurchaseList, PurchaseMoney, PurchasePaymentMethod, PurchasePhase, PurchaseRequest, PurchaseResponseAck, PurchaseStatus, PurchasingCapabilities, PurchasingSettings, RecurringPurchase, RecurringPurchaseCycleResult, RecurringPurchaseCycleStatus, RefreshBalanceResult, RegisterExternalCardInput, ReplaceLinkCardInput, ReportCheckoutOutcomeInput, RollbackPolicyVersionResponse, RuleAction, RuleOperator, RuleType, RunGuardedCheckoutResult, SdkKey, SdkKeyType, SetupCapabilityState, SetupCardDiagnostics, SetupDiagnosticAction, SetupDiagnosticIssue, SetupDiagnosticIssueCode, SetupDiagnostics, SetupWalletDiagnostics, TestCardCredential, TestCardDrawResult, TestCardDrawable, TestCardListResult, TestCardReceipt, TestCheckoutInput, TestCheckoutResult, TestMerchant, TestMerchantProduct, UnfreezeAgentInput, UpdateAgentInput, UpdateExternalCardAssignmentInput, UpdatePolicyInput, UpdatePolicyRuleInput, UpdateWalletInput, VerifiedBrowserCheckoutTarget, WaitForCheckoutApprovalOptions, Wallet, WalletChainBalanceSnapshot, WalletOwnershipChallenge, WalletOwnershipProof, WalletStatus, WalletType, WatchPurchaseOptions, X402Authorization, X402BudgetResult, X402PayInput, X402PayResult, X402PaymentRequirements, X402PreAuthorizeInput, X402PreAuthorizeResult, X402RecordInput, X402RecordResult };
+export { AdminPurchasingClient, AdminSpendingClient, BrowserActionFinalizationPendingError, BrowserCheckoutTargetVerificationError, CardsClient, CheckoutApprovalDeniedError, CheckoutApprovalExpiredError, CheckoutApprovalPendingError, CheckoutApprovalTimeoutError, CheckoutCheckpointClosedError, CheckoutClient, ConnectedCardsClient, Conto, ContoAdmin, ContoAdminError, ContoError, ControlledExternalCardPaymentTool, ExternalCardConfirmationPendingError, Conto as Giro, ContoError as GiroError, LinkCardCredential, LinkCardDeniedError, LinkCardError, LinkCardExpiredError, LinkCardTimeoutError, LinkWallet, LinkWalletUnavailableError, OrganizationPurchasesClient, OrganizationRecurringPurchasesClient, PurchasesClient, RecurringPurchasesClient, SpendingClient, TestCardsClient, canonicalizeBrowserCheckoutTarget, createVerifiedBrowserCheckoutDriver, Conto as default, fingerprintBrowserCheckoutTarget, isFinalPurchaseStatus, parseServerSentEvents, verifyPurchaseWebhook };
+export type { AdminExternalCardOverlayEnforcement, Agent, AgentCheckoutAction, AgentCheckoutActionKind, AgentExternalCard, AgentSetupResult, AgentStatus, AgentType, AgentWalletLink, ApprovedExternalCardExecution, AssignExternalCardInput, AssignedPolicy, AuthorizeCheckoutActionResult, BeginCheckoutCheckpointInput, BeginCommerceExecutionInput, BrowserActionClaimResult, BrowserActionDispatchObservationInput, BrowserActionFinalizeResult, BrowserCheckoutAction, BrowserCheckoutTargetResolver, BrowserCheckoutTargetSnapshot, BrowserCheckoutTargetVerificationCode, BudgetInput, BudgetSnapshot, CancellationOutcome, CanonicalBrowserCheckoutTargetSnapshot, ChainType, CheckoutActionAuthorization, CheckoutCheckpoint, CheckoutCheckpointApproval, CheckoutCheckpointMethod, CheckoutCheckpointNextAction, CheckoutCheckpointStage, CheckoutOutcome, CheckoutPaymentReference, CommerceCheckoutMethod, CommerceContextRequirement, CommerceExecution, CommerceExecutionAdapterKind, CommerceExecutionArtifactKind, CommerceExecutionChannel, CommerceExecutionConstraint, CommerceExecutionConstraintCoverage, CommerceExecutionConstraintCoverageLevel, CommerceExecutionDeliveryMode, CommerceExecutionEvidence, CommerceExecutionProvider, CommerceExecutionResult, CommerceExecutionSourceKind, CommerceExecutionStatus, CommerceFactConfidence, CommerceFactProvenanceInput, CommerceFactSource, CommerceFulfillmentInput, CommerceLineItemInput, CommerceProposalFactKey, CommerceProposalMissingFact, CommerceProposalResolution, CommerceProposalState, CommerceSettlementRail, CommerceTotalInput, CommerceTotalType, ComparePolicyVersionsResponse, ConfirmCheckoutCheckpointInput, ConnectedCardBrief, ConnectedCardCredential, ConnectedCardDrawInput, ConnectedCardDrawMerchant, ConnectedCardDrawResult, ConnectedCardDrawable, ConnectedCardListResult, ConnectedCardMandate, ConnectedCardMandateMerchant, ConnectedCardOutcomeReport, ConnectedCardOutcomeReportResult, ConnectedCardReference, ContoAdminConfig, ContoConfig, ContoRequestOptions, ControlledExternalCardPaymentResult, CreateAgentInput, CreatePolicyInput, CreatePolicyRuleInput, CreatePurchaseInput, CreateSdkKeyInput, CreateSdkKeyResult, CreateWalletInput, CustodyType, CustomerCustodyMode, CustomerWalletControlModel, CustomerWalletKeyAccess, DelegationType, DownloadBytes, ExecuteCommerceExecutionResult, ExternalCard, ExternalCardApprovalInput, ExternalCardApprovalResult, ExternalCardConfirmationInput, ExternalCardConfirmationResult, ExternalCardExecutionClaimResult, ExternalCardExecutionResult, ExternalCardExecutor, ExternalCardOverlayEnforcement, ExternalCardRequestStatusResult, ExternalWalletApprovalInput, ExternalWalletApprovalResult, ExternalWalletConfirmationInput, ExternalWalletConfirmationResult, FreezeAgentInput, GetLinkCardInput, ContoConfig as GiroConfig, GuardCheckoutResult, GuardedBrowserDispatchResult, GuardedCheckoutInput, LinkApprovalCallback, LinkApprovalEvent, LinkCardResult, LinkWalletInput, ListAgentsParams, ListAgentsResponse, ListPoliciesParams, ListPoliciesResponse, ListPolicyVersionsResponse, ListWalletsParams, ListWalletsResponse, MppBudgetResult, MppPreAuthorizeInput, MppPreAuthorizeResult, MppRecordInput, MppRecordResult, NormalizeCommerceProposalInput, OrganizationMember, PaginatedResponse, PaginationParams, PauseExternalCardAssignmentResult, PaymentExecuteResult, PaymentRequestInput, PaymentRequestResult, PaymentStatusResult, Policy, PolicyRule, PolicyType, PolicyVersionChangeType, PolicyVersionDetail, PolicyVersionDiff, PolicyVersionFieldChange, PolicyVersionSnapshot, PolicyVersionSnapshotRule, PolicyVersionSummary, PreviewInput, PrivilegedBrowserCheckoutDriver, ProtocolBudgetResult, ProtocolPreAuthorizeResult, ProtocolRecordGrant, ProtocolRecordGrantResult, ProtocolServiceSummary, ProtocolServicesResult, ProveWalletOwnershipInput, ProvisionWalletResult, Purchase, PurchaseAction, PurchaseActionAuthority, PurchaseActionKind, PurchaseAllowance, PurchaseBuyer, PurchaseBuyerCompanyCard, PurchaseBuyerCompanyCardLimits, PurchaseBuyerKitchenContext, PurchaseCompanyCard, PurchaseDelegation, PurchaseDetail, PurchaseEvent, PurchaseEventPage, PurchaseEvidence, PurchaseGrocery, PurchaseGroceryItem, PurchaseGroceryList, PurchaseHostedLink, PurchaseItem, PurchaseKitchenContext, PurchaseKitchenInventoryItem, PurchaseKitchenListItem, PurchaseKitchenPreferences, PurchaseKitchenRecipe, PurchaseKitchenUsual, PurchaseList, PurchaseMoney, PurchasePaymentMethod, PurchasePhase, PurchaseRequest, PurchaseResponseAck, PurchaseSnapshot, PurchaseStatus, PurchasingCapabilities, PurchasingSettings, RecurringPurchase, RecurringPurchaseCycleResult, RecurringPurchaseCycleStatus, RefreshBalanceResult, RegisterExternalCardInput, ReplaceLinkCardInput, ReportCheckoutOutcomeInput, RollbackPolicyVersionResponse, RuleAction, RuleOperator, RuleType, RunGuardedCheckoutResult, SdkKey, SdkKeyType, SetupCapabilityState, SetupCardDiagnostics, SetupDiagnosticAction, SetupDiagnosticIssue, SetupDiagnosticIssueCode, SetupDiagnostics, SetupWalletDiagnostics, SpendingRequester, TaskInput, TaskSnapshot, TestCardCredential, TestCardDrawResult, TestCardDrawable, TestCardListResult, TestCardReceipt, TestCheckoutInput, TestCheckoutResult, TestMerchant, TestMerchantProduct, UnfreezeAgentInput, UpdateAgentInput, UpdateExternalCardAssignmentInput, UpdatePolicyInput, UpdatePolicyRuleInput, UpdateWalletInput, VerifiedBrowserCheckoutTarget, WaitForCheckoutApprovalOptions, Wallet, WalletChainBalanceSnapshot, WalletOwnershipChallenge, WalletOwnershipProof, WalletStatus, WalletType, WatchPurchaseOptions, X402Authorization, X402BudgetResult, X402PayInput, X402PayResult, X402PaymentRequirements, X402PreAuthorizeInput, X402PreAuthorizeResult, X402RecordInput, X402RecordResult };