@conto_finance/sdk 0.8.0 → 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,18 +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.
+  `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`, a retry throws `CHECKOUT_CHECKPOINT_NOT_APPROVED`.
+  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`. Cancel the Link
-  request, then call `conto.checkout.cancel(id)` to release the spend. Otherwise the owner gets a
+  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.
+  `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 }`.
@@ -173,11 +198,20 @@ 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.
+  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.
+  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
@@ -191,10 +225,7 @@ const confirmed = await conto.checkout.confirm(result.checkpoint, {
 
 ## 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`.
+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.
@@ -224,16 +255,14 @@ payments, agent-to-agent payments, payment grants, checkout relay, hosted Stripe
 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.
+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 budgets on a test
-organization first.
+`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 or agent, is in the exact currency. A
+  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.
@@ -241,8 +270,7 @@ organization first.
   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.
+  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()`
@@ -264,10 +292,9 @@ organization first.
   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
+- 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` with that `reasonCode` set. `payments.execute()` has `code`
+  `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

package/dist/index.d.mts

@@ -2961,6 +2961,12 @@ interface CheckoutCheckpoint {
     outcomeReference?: string;
     /** The payment your checkout reported at confirm or outcome, such as a Link spend request. */
     paymentReference?: CheckoutPaymentReference;
+    /**
+     * True when the checkpoint stopped before its confirm while its Link request may still work, so
+     * the stage is OUTCOME_UNKNOWN. Cancel the Link request, then cancel the checkpoint. Absent on a
+     * confirmed checkpoint with no outcome, whose card may be in use: report the outcome instead.
+     */
+    linkRequestOpen?: true;
     /** Outcomes are reported by your checkout. Conto does not verify settlement here. */
     settlementVerified: false;
 }
@@ -3741,9 +3747,8 @@ declare class CheckoutApprovalTimeoutError extends ContoError {
     constructor(checkpoint: CheckoutCheckpoint);
 }
 /**
- * getLinkCard() or replaceLinkCard() stopped after Conto approved the purchase.
- * No card was returned. Conto cancelled the checkpoint to release the held
- * spend unless holdReleased is false. Do not pay.
+ * getLinkCard() or replaceLinkCard() stopped, and no card was returned. Do not
+ * pay. Follow retryGuidance, which depends on the code and the stage.
  */
 declare class LinkCardError extends ContoError {
     readonly checkpoint: CheckoutCheckpoint;
@@ -3751,11 +3756,16 @@ declare class LinkCardError extends ContoError {
     /**
      * The Stripe Link page where the person could approve the request, set when
      * the SDK stopped while the request was waiting for them. It works only while
-     * the request is still open in Link. When holdReleased is true, Conto has
-     * already cancelled the request.
+     * the request is still open in Link. With LINK_CARD_NOT_CANCELLED it is set
+     * only when a retry can resume the request. With any other code, the request
+     * is already closed.
      */
     readonly approvalUrl?: string;
-    /** True when Conto cancelled the checkpoint and released the held spend. */
+    /**
+     * True when the checkpoint no longer holds the spend. It says nothing about
+     * the card. With LINK_CARD_NOT_CANCELLED, LINK_CARD_NOT_REPLACED or
+     * LINK_CARD_ABORTED, a card may still work.
+     */
     readonly holdReleased: boolean;
     constructor(input: {
         message: string;
@@ -4224,7 +4234,9 @@ declare class CheckoutClient {
     reportOutcome(checkpointId: string, input: ReportCheckoutOutcomeInput): Promise<CheckoutCheckpoint>;
     /**
      * Cancel a checkpoint that was not confirmed and release its spend. A
-     * checkpoint waiting for the owner can be cancelled too.
+     * checkpoint waiting for the owner can be cancelled too. This does not close
+     * a Link card, which can still work with nothing held behind it, so cancel
+     * the Link request first.
      */
     cancel(checkpointId: string): Promise<CheckoutCheckpoint>;
     get(checkpointId: string): Promise<CheckoutCheckpoint>;
@@ -4252,16 +4264,22 @@ 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 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.
+     * Link request while Conto's approval is open. If its approval ended with the
+     * request open, a retry throws CHECKOUT_CHECKPOINT_NOT_APPROVED. Cancel the Link
+     * request, then the checkpoint. Once a confirm has started, a retry throws
+     * LINK_CARD_NOT_ISSUED. Do not cancel the Link request while a payment may be in
+     * flight. Follow error.retryGuidance, which depends on the stage.
      */
     getLinkCard(input: GetLinkCardInput): Promise<LinkCardResult>;
     /**
      * The final total differs from the one the Link card covers. This cancels
      * the old Link request and checkpoint, begins a checkpoint at the final
      * total (waiting for the owner when a rule requires it), and gets a new card
-     * for it. Confirm the returned checkpoint with the same total.
+     * for it. Confirm the returned checkpoint with the same total. It reads the
+     * checkpoint first. At a stage where a payment may be in flight, or with a
+     * different Link request on record, this throws LINK_CARD_NOT_REPLACED and
+     * leaves the card and the hold alone. After the old card is closed, trying
+     * again with the same input resumes the replacement.
      */
     replaceLinkCard(previous: LinkCardResult, input: ReplaceLinkCardInput): Promise<LinkCardResult>;
 }

package/dist/index.d.ts

@@ -2961,6 +2961,12 @@ interface CheckoutCheckpoint {
     outcomeReference?: string;
     /** The payment your checkout reported at confirm or outcome, such as a Link spend request. */
     paymentReference?: CheckoutPaymentReference;
+    /**
+     * True when the checkpoint stopped before its confirm while its Link request may still work, so
+     * the stage is OUTCOME_UNKNOWN. Cancel the Link request, then cancel the checkpoint. Absent on a
+     * confirmed checkpoint with no outcome, whose card may be in use: report the outcome instead.
+     */
+    linkRequestOpen?: true;
     /** Outcomes are reported by your checkout. Conto does not verify settlement here. */
     settlementVerified: false;
 }
@@ -3741,9 +3747,8 @@ declare class CheckoutApprovalTimeoutError extends ContoError {
     constructor(checkpoint: CheckoutCheckpoint);
 }
 /**
- * getLinkCard() or replaceLinkCard() stopped after Conto approved the purchase.
- * No card was returned. Conto cancelled the checkpoint to release the held
- * spend unless holdReleased is false. Do not pay.
+ * getLinkCard() or replaceLinkCard() stopped, and no card was returned. Do not
+ * pay. Follow retryGuidance, which depends on the code and the stage.
  */
 declare class LinkCardError extends ContoError {
     readonly checkpoint: CheckoutCheckpoint;
@@ -3751,11 +3756,16 @@ declare class LinkCardError extends ContoError {
     /**
      * The Stripe Link page where the person could approve the request, set when
      * the SDK stopped while the request was waiting for them. It works only while
-     * the request is still open in Link. When holdReleased is true, Conto has
-     * already cancelled the request.
+     * the request is still open in Link. With LINK_CARD_NOT_CANCELLED it is set
+     * only when a retry can resume the request. With any other code, the request
+     * is already closed.
      */
     readonly approvalUrl?: string;
-    /** True when Conto cancelled the checkpoint and released the held spend. */
+    /**
+     * True when the checkpoint no longer holds the spend. It says nothing about
+     * the card. With LINK_CARD_NOT_CANCELLED, LINK_CARD_NOT_REPLACED or
+     * LINK_CARD_ABORTED, a card may still work.
+     */
     readonly holdReleased: boolean;
     constructor(input: {
         message: string;
@@ -4224,7 +4234,9 @@ declare class CheckoutClient {
     reportOutcome(checkpointId: string, input: ReportCheckoutOutcomeInput): Promise<CheckoutCheckpoint>;
     /**
      * Cancel a checkpoint that was not confirmed and release its spend. A
-     * checkpoint waiting for the owner can be cancelled too.
+     * checkpoint waiting for the owner can be cancelled too. This does not close
+     * a Link card, which can still work with nothing held behind it, so cancel
+     * the Link request first.
      */
     cancel(checkpointId: string): Promise<CheckoutCheckpoint>;
     get(checkpointId: string): Promise<CheckoutCheckpoint>;
@@ -4252,16 +4264,22 @@ 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 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.
+     * Link request while Conto's approval is open. If its approval ended with the
+     * request open, a retry throws CHECKOUT_CHECKPOINT_NOT_APPROVED. Cancel the Link
+     * request, then the checkpoint. Once a confirm has started, a retry throws
+     * LINK_CARD_NOT_ISSUED. Do not cancel the Link request while a payment may be in
+     * flight. Follow error.retryGuidance, which depends on the stage.
      */
     getLinkCard(input: GetLinkCardInput): Promise<LinkCardResult>;
     /**
      * The final total differs from the one the Link card covers. This cancels
      * the old Link request and checkpoint, begins a checkpoint at the final
      * total (waiting for the owner when a rule requires it), and gets a new card
-     * for it. Confirm the returned checkpoint with the same total.
+     * for it. Confirm the returned checkpoint with the same total. It reads the
+     * checkpoint first. At a stage where a payment may be in flight, or with a
+     * different Link request on record, this throws LINK_CARD_NOT_REPLACED and
+     * leaves the card and the hold alone. After the old card is closed, trying
+     * again with the same input resumes the replacement.
      */
     replaceLinkCard(previous: LinkCardResult, input: ReplaceLinkCardInput): Promise<LinkCardResult>;
 }