@conto_finance/sdk 0.7.0 → 0.8.0

package/README.md

@@ -155,23 +155,124 @@ 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 }`.
+  `approvalUrl` is always an HTTPS link.com address. A `LinkCardError` has it too when the SDK
+  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
+- 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
@@ -317,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
@@ -522,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/chunk-PVMUL3JC.mjs

@@ -0,0 +1,30 @@
+// src/link-approval.ts
+function safeLinkApprovalUrl(value) {
+  if (typeof value !== "string" || value.length === 0 || value.length > 2048) return void 0;
+  let url;
+  try {
+    url = new URL(value);
+  } catch {
+    return void 0;
+  }
+  if (url.protocol !== "https:" || url.username !== "" || url.password !== "" || url.port !== "" || !(url.hostname === "link.com" || url.hostname.endsWith(".link.com"))) {
+    return void 0;
+  }
+  url.hash = "";
+  return url.toString();
+}
+function linkTime(value) {
+  let ms = Number.NaN;
+  if (typeof value === "number" && Number.isFinite(value) && value > 0) {
+    ms = value < 1e12 ? value * 1e3 : value;
+  } else if (typeof value === "string" && value.length > 0 && value.length <= 64) {
+    ms = Date.parse(value);
+  }
+  const date = new Date(ms);
+  return Number.isNaN(date.getTime()) ? void 0 : date.toISOString();
+}
+
+export {
+  safeLinkApprovalUrl,
+  linkTime
+};