@conto_finance/sdk 0.7.1 → 0.8.1

package/README.md

@@ -106,7 +106,9 @@ await conto.checkout.reportOutcome(confirmed.id, { outcome: 'PAID', reference: o
 - `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)`.
+  stays counted. Cancel an unconfirmed checkpoint with `conto.checkout.cancel(id)`. With a Link
+  card, cancel the Link request first, because the checkpoint cancel releases the spend even if the
+  card still works.
 - 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.
 
@@ -154,8 +156,41 @@ const confirmed = await conto.checkout.confirm(result.checkpoint, {
 - When the person declines in Link, the request expires, the wait passes `linkApprovalTimeoutMs`,
   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.
+  `LinkWalletUnavailableError`. All extend `LinkCardError`. Do not pay. If a Link request is already
+  on record, it closes that first, and if it cannot, it keeps the hold and throws
+  `LINK_CARD_NOT_CANCELLED`. `holdReleased` says whether the checkpoint still holds the spend, not
+  whether the card is closed, so follow `error.retryGuidance` whatever its value.
+- 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` with `linkRequestOpen: true`, a retry throws
+  `CHECKOUT_CHECKPOINT_NOT_APPROVED`. Once a `confirm()` has started, a retry throws
+  `LINK_CARD_NOT_ISSUED` and returns no card. Do not cancel the Link request while a payment may be in
+  flight. Follow `error.retryGuidance`.
+- A request in `requires_action` that Link will not resume cannot be retried or cancelled. Link closes
+  it on its own, and `error.retryGuidance` gives the steps. `LINK_CARD_DUPLICATE_REQUEST` means Link has
+  an open request for another purchase with the same details. `error.retryGuidance` names that request
+  and its checkpoint and gives the steps for each stage. Once it closes, start this one with a new
+  idempotency key. A `signal` that fires during the owner wait throws
+  `LINK_CARD_ABORTED` with the checkpoint, and the spend stays held.
+- `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` with
+  `linkRequestOpen: true`. Cancel the Link request, then call `conto.checkout.cancel(id)` to release
+  the spend. If the card was used, report `PAID`. If you cannot tell, report `UNKNOWN`, which keeps
+  the spend held until the owner records what happened. 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. If the read fails, a confirm has started, or Link
+  cannot cancel a request that is still open, the SDK throws `LINK_CARD_NOT_CANCELLED` instead. Conto
+  may have no record of that request, so the hold can end when the approval lapses while the card may
+  still work. Retry or cancel before then.
+- `linkCliWallet().cancel()` also succeeds when Link already closed the request. If it throws, the
+  card may still work or may have been used, so keep the hold.
+- An owner's not paid decision does not close a Link card, which can work for up to 48 hours. After
+  `CheckoutCheckpointClosedError`, if `error.checkpoint.paymentReference` is set, cancel the request
+  with `wallet.cancel(error.checkpoint.paymentReference.id)` before you start a new purchase. If that
+  call throws, the card may have been used, so do not begin a new purchase.
 - 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 }`.
@@ -163,20 +198,108 @@ const confirmed = await conto.checkout.confirm(result.checkpoint, {
   stopped while the person had not decided.
 - 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
-  cancel the old card and checkpoint and get a card for the final total.
+  digits, the brand, and the expiry. It never appears in an error.
+- 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. `replaceLinkCard()` always
+  reads the checkpoint first. `confirm()` reads it when the total differs and it has no reference,
+  including for checkouts without a Link card, so a saved copy is safe to pass. A `getLinkCard()`
+  retry reads it after a failure, before it closes a request on record. Those reads need
+  `transactions:read`. If the checkpoint was already confirmed, or a different Link request is on
+  record, `replaceLinkCard()` throws `LINK_CARD_NOT_REPLACED` and leaves the card and the hold alone.
+  Report the outcome instead of replacing a card whose payment may be in flight. If the old card
+  closes but Conto does not release the spend, it throws `CHECKPOINT_NOT_CANCELLED`, and trying
+  again is safe. If the total changes again, pass the latest result. Do not run it while another
+  flow may confirm the same checkpoint.
 - 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 Budgets or with `admin.spending`. A budget stops other payment paths for the agents it covers, listed below. 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 stops nothing on other paths. It applies only to a managed wallet payment or connected card draw that names the task, and it refuses that payment or draw while it is paused.
+`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 a budget first on one agent with a Tempo Testnet wallet.
+
+- 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, agent or task, 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()`. A self-custody wallet cannot use a task. When a budget covers the agent, `payments.request()` throws status 409 with `reasonCode` `EXECUTION_PATH_NOT_CONNECTED`. When none does, a request that names a task ends in `DENIED`. `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.
+- Most 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` and `reasonCode` `EXECUTION_PATH_NOT_CONNECTED`. `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 +445,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 +651,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