@conto_finance/sdk 0.7.1 → 0.8.1

package/dist/index.js

@@ -47,7 +47,7 @@ var require_package = __commonJS({
   "package.json"(exports2, module2) {
     module2.exports = {
       name: "@conto_finance/sdk",
-      version: "0.7.1",
+      version: "0.8.1",
       description: "Conto SDK for AI agent payment authorization",
       main: "./dist/index.js",
       module: "./dist/index.mjs",
@@ -93,7 +93,7 @@ var require_package = __commonJS({
         dev: "tsup --watch",
         lint: "tsc --noEmit",
         test: "npm run lint && npm run test:contract && npm run test:consumer",
-        "test:contract": "npm run build && node --test test/contract.test.mjs test/playwright.test.mjs test/browserbase.test.mjs test/checkout-verifier.test.mjs test/developer-experience.test.mjs test/checkout.test.mjs test/link-wallet.test.mjs test/purchases.test.mjs test/allowances.test.mjs test/purchase-watch-lifecycle.test.mjs ../../examples/link-wallet-agent/verify.test.mjs",
+        "test:contract": "npm run build && node --test test/contract.test.mjs test/playwright.test.mjs test/browserbase.test.mjs test/checkout-verifier.test.mjs test/developer-experience.test.mjs test/checkout.test.mjs test/link-wallet.test.mjs test/purchases.test.mjs test/allowances.test.mjs test/purchase-watch-lifecycle.test.mjs test/spending.test.mjs ../../examples/link-wallet-agent/verify.test.mjs",
         "test:consumer": "npm run build && node --test test/consumer.test.mjs",
         "verify:release": "node scripts/verify-release.mjs",
         prepublishOnly: "npm run verify:release && npm run lint && npm run test:contract && npm run test:consumer"
@@ -157,6 +157,7 @@ var require_package_version = __commonJS({
 var index_exports = {};
 __export(index_exports, {
   AdminPurchasingClient: () => AdminPurchasingClient,
+  AdminSpendingClient: () => AdminSpendingClient,
   BrowserActionFinalizationPendingError: () => BrowserActionFinalizationPendingError,
   BrowserCheckoutTargetVerificationError: () => BrowserCheckoutTargetVerificationError,
   CardsClient: () => CardsClient,
@@ -183,6 +184,7 @@ __export(index_exports, {
   OrganizationRecurringPurchasesClient: () => OrganizationRecurringPurchasesClient,
   PurchasesClient: () => PurchasesClient,
   RecurringPurchasesClient: () => RecurringPurchasesClient,
+  SpendingClient: () => SpendingClient,
   TestCardsClient: () => TestCardsClient,
   canonicalizeBrowserCheckoutTarget: () => canonicalizeBrowserCheckoutTarget,
   createVerifiedBrowserCheckoutDriver: () => createVerifiedBrowserCheckoutDriver,
@@ -288,9 +290,9 @@ function watchRead(pending, signal) {
     pending.then(resolve, reject).finally(() => signal.removeEventListener("abort", abort));
   });
 }
-function requirePurchaseId(id) {
-  if (!/^[a-z0-9]{8,64}$/i.test(id)) throw new TypeError("purchase id is not valid");
-  return encodeURIComponent(id);
+function requirePurchaseId(id2) {
+  if (!/^[a-z0-9]{8,64}$/i.test(id2)) throw new TypeError("purchase id is not valid");
+  return encodeURIComponent(id2);
 }
 function requireCycleKey(key) {
   if (!/^[A-Za-z0-9._:-]{1,100}$/.test(key)) throw new TypeError("cycleKey is not valid");
@@ -310,24 +312,24 @@ var RecurringPurchasesClient = class {
       buyerId ? `${__privateGet(this, _base)}?buyerId=${encodeURIComponent(buyerId)}` : __privateGet(this, _base)
     );
   }
-  async get(id) {
-    return __privateGet(this, _transport).request("GET", `${__privateGet(this, _base)}/${requirePurchaseId(id)}`);
+  async get(id2) {
+    return __privateGet(this, _transport).request("GET", `${__privateGet(this, _base)}/${requirePurchaseId(id2)}`);
   }
   /** Starts one order. The same cycle key returns the same order. */
-  async startCycle(id, cycleKey) {
+  async startCycle(id2, cycleKey) {
     requireCycleKey(cycleKey);
     return __privateGet(this, _transport).request(
       "POST",
-      `${__privateGet(this, _base)}/${requirePurchaseId(id)}/cycles`,
+      `${__privateGet(this, _base)}/${requirePurchaseId(id2)}/cycles`,
       { cycleKey },
       { idempotent: true }
     );
   }
   /** Skips one order, also before it starts. */
-  async skipCycle(id, cycleKey) {
+  async skipCycle(id2, cycleKey) {
     return __privateGet(this, _transport).request(
       "POST",
-      `${__privateGet(this, _base)}/${requirePurchaseId(id)}/cycles/${requireCycleKey(cycleKey)}/skip`
+      `${__privateGet(this, _base)}/${requirePurchaseId(id2)}/cycles/${requireCycleKey(cycleKey)}/skip`
     );
   }
 };
@@ -341,10 +343,10 @@ var OrganizationRecurringPurchasesClient = class extends RecurringPurchasesClien
     __privateSet(this, _client, client);
   }
   /** Stops a repeat order. An order waiting for its payment time closes unpaid. */
-  async cancel(id) {
+  async cancel(id2) {
     return __privateGet(this, _client).request(
       "POST",
-      `/api/purchasing/recurring-purchases/${requirePurchaseId(id)}/cancel`
+      `/api/purchasing/recurring-purchases/${requirePurchaseId(id2)}/cancel`
     );
   }
 };
@@ -381,36 +383,36 @@ var PurchasesClient = class {
     const suffix = query.toString();
     return __privateGet(this, _transport2).request("GET", `${__privateGet(this, _base2)}${suffix ? `?${suffix}` : ""}`);
   }
-  async get(id) {
-    return __privateGet(this, _transport2).request("GET", `${__privateGet(this, _base2)}/${requirePurchaseId(id)}`);
+  async get(id2) {
+    return __privateGet(this, _transport2).request("GET", `${__privateGet(this, _base2)}/${requirePurchaseId(id2)}`);
   }
   /**
    * Answers an open action whose authority is `agent_or_buyer` with the fields
    * it lists. The acknowledgment means recorded; the purchase shows the result.
    * The same answer again returns the same acknowledgment.
    */
-  async respond(id, input) {
+  async respond(id2, input) {
     return __privateGet(this, _transport2).request(
       "POST",
-      `${__privateGet(this, _base2)}/${requirePurchaseId(id)}/responses`,
+      `${__privateGet(this, _base2)}/${requirePurchaseId(id2)}/responses`,
       input,
       { idempotent: true }
     );
   }
-  async events(id, params = {}) {
+  async events(id2, params = {}) {
     const query = new URLSearchParams({ after: String(params.after ?? 0) });
     if (params.limit) query.set("limit", String(params.limit));
-    return __privateGet(this, _transport2).request("GET", `${__privateGet(this, _base2)}/${requirePurchaseId(id)}/events?${query}`);
+    return __privateGet(this, _transport2).request("GET", `${__privateGet(this, _base2)}/${requirePurchaseId(id2)}/events?${query}`);
   }
   /**
    * Requests cancellation. Before payment the purchase stops. Once payment may
    * have been submitted, `cancellationOutcome` is `too_late` and the purchase
    * stays in reconciliation. Nothing is refunded by this call.
    */
-  async cancel(id) {
+  async cancel(id2) {
     return __privateGet(this, _transport2).request(
       "POST",
-      `${__privateGet(this, _base2)}/${requirePurchaseId(id)}/cancel`,
+      `${__privateGet(this, _base2)}/${requirePurchaseId(id2)}/cancel`,
       void 0,
       { idempotent: true }
     );
@@ -422,8 +424,8 @@ var PurchasesClient = class {
    * after a reconnect is dropped. A `purchase.resync` event carries the
    * current purchase when the cursor could not be resumed.
    */
-  async *watch(id, options = {}) {
-    const path = `${__privateGet(this, _base2)}/${requirePurchaseId(id)}`;
+  async *watch(id2, options = {}) {
+    const path = `${__privateGet(this, _base2)}/${requirePurchaseId(id2)}`;
     const mode = options.mode ?? "auto";
     const interval = Math.max(500, options.pollIntervalMs ?? 2e3);
     if (options.maxWaitMs !== void 0 && (!Number.isFinite(options.maxWaitMs) || options.maxWaitMs < 0 || options.maxWaitMs > 2147483647))
@@ -488,10 +490,10 @@ var PurchasesClient = class {
         }
         let page;
         try {
-          page = await watchRead(this.events(id, { after: cursor, limit: 100 }), signal);
+          page = await watchRead(this.events(id2, { after: cursor, limit: 100 }), signal);
         } catch (error) {
           if (codeOf(error) !== "CURSOR_INVALID") throw error;
-          const purchase = await watchRead(this.get(id), signal);
+          const purchase = await watchRead(this.get(id2), signal);
           cursor = purchase.version;
           yield {
             id: `resync:${purchase.version}`,
@@ -546,10 +548,10 @@ var OrganizationPurchasesClient = class extends PurchasesClient {
     return __privateGet(this, _client2).request("GET", `/api/purchasing/purchases${suffix ? `?${suffix}` : ""}`);
   }
   /** A single-use link that opens the purchase's buyer actions on Conto's hosted page. */
-  createActionLink(id, input = {}) {
+  createActionLink(id2, input = {}) {
     return __privateGet(this, _client2).request(
       "POST",
-      `/api/purchasing/purchases/${requirePurchaseId(id)}/action-sessions`,
+      `/api/purchasing/purchases/${requirePurchaseId(id2)}/action-sessions`,
       input
     );
   }
@@ -566,52 +568,52 @@ var AdminPurchasingClient = class {
         "GET",
         `/api/purchasing/allowances?${new URLSearchParams({ buyerId: params.buyerId })}`
       ),
-      get: (id) => __privateGet(this, _client3).request("GET", `/api/purchasing/allowances/${enc(id)}`),
+      get: (id2) => __privateGet(this, _client3).request("GET", `/api/purchasing/allowances/${enc(id2)}`),
       /** Stops future credential release; does not undo payments already submitted. */
-      revoke: (id) => __privateGet(this, _client3).request(
+      revoke: (id2) => __privateGet(this, _client3).request(
         "POST",
-        `/api/purchasing/allowances/${enc(id)}/revoke`
+        `/api/purchasing/allowances/${enc(id2)}/revoke`
       )
     };
     this.buyers = {
       /** Maps one of your users to a buyer with its own agent, or returns the existing one. */
       create: (input) => __privateGet(this, _client3).request("POST", "/api/purchasing/buyers", input),
-      get: (id) => __privateGet(this, _client3).request("GET", `/api/purchasing/buyers/${enc(id)}`),
+      get: (id2) => __privateGet(this, _client3).request("GET", `/api/purchasing/buyers/${enc(id2)}`),
       list: (params = {}) => __privateGet(this, _client3).request("GET", `/api/purchasing/buyers?limit=${params.limit ?? 20}&offset=${params.offset ?? 0}`),
       /** Stops the buyer's agent. Purchases that may already be paid stay visible. */
-      stop: (id) => __privateGet(this, _client3).request("POST", `/api/purchasing/buyers/${enc(id)}/stop`),
+      stop: (id2) => __privateGet(this, _client3).request("POST", `/api/purchasing/buyers/${enc(id2)}/stop`),
       /**
        * Lets the buyer pay with your company card within limits you set for
        * them, or replaces those limits. The buyer must not have their own card.
        */
-      setCompanyCard: (id, input) => __privateGet(this, _client3).request(
+      setCompanyCard: (id2, input) => __privateGet(this, _client3).request(
         "PUT",
-        `/api/purchasing/buyers/${enc(id)}/company-card`,
+        `/api/purchasing/buyers/${enc(id2)}/company-card`,
         input
       ),
       /** The buyer stops paying with your company card. */
-      removeCompanyCard: (id) => __privateGet(this, _client3).request(
+      removeCompanyCard: (id2) => __privateGet(this, _client3).request(
         "DELETE",
-        `/api/purchasing/buyers/${enc(id)}/company-card`
+        `/api/purchasing/buyers/${enc(id2)}/company-card`
       ),
       /**
        * Replaces what the buyer has at home: inventory, usuals, preferences,
        * chosen recipes and their list. The whole snapshot, every time. Needs
        * Conto to enable kitchen context for your organization.
        */
-      setKitchenContext: (id, context) => __privateGet(this, _client3).request(
+      setKitchenContext: (id2, context) => __privateGet(this, _client3).request(
         "PUT",
-        `/api/purchasing/buyers/${enc(id)}/context`,
+        `/api/purchasing/buyers/${enc(id2)}/context`,
         context
       ),
       /** The snapshot Conto holds, with context null when nothing was pushed. */
-      getKitchenContext: (id) => __privateGet(this, _client3).request(
+      getKitchenContext: (id2) => __privateGet(this, _client3).request(
         "GET",
-        `/api/purchasing/buyers/${enc(id)}/context`
+        `/api/purchasing/buyers/${enc(id2)}/context`
       ),
-      clearKitchenContext: (id) => __privateGet(this, _client3).request(
+      clearKitchenContext: (id2) => __privateGet(this, _client3).request(
         "DELETE",
-        `/api/purchasing/buyers/${enc(id)}/context`
+        `/api/purchasing/buyers/${enc(id2)}/context`
       )
     };
     /** Cards your organization pays its buyers' purchases with. Test cards only for now. */
@@ -621,17 +623,17 @@ var AdminPurchasingClient = class {
         "GET",
         "/api/purchasing/company-cards"
       ),
-      get: (id) => __privateGet(this, _client3).request("GET", `/api/purchasing/company-cards/${enc(id)}`),
+      get: (id2) => __privateGet(this, _client3).request("GET", `/api/purchasing/company-cards/${enc(id2)}`),
       /** Changes the card's own caps. Each buyer's limits stay as they are. */
-      update: (id, input) => __privateGet(this, _client3).request(
+      update: (id2, input) => __privateGet(this, _client3).request(
         "PATCH",
-        `/api/purchasing/company-cards/${enc(id)}`,
+        `/api/purchasing/company-cards/${enc(id2)}`,
         input
       ),
       /** No buyer can start or pay a purchase with the card after this. */
-      remove: (id) => __privateGet(this, _client3).request(
+      remove: (id2) => __privateGet(this, _client3).request(
         "DELETE",
-        `/api/purchasing/company-cards/${enc(id)}`
+        `/api/purchasing/company-cards/${enc(id2)}`
       )
     };
     this.paymentMethods = {
@@ -645,9 +647,9 @@ var AdminPurchasingClient = class {
         "GET",
         `/api/purchasing/payment-methods?buyerId=${enc(buyerId)}`
       ),
-      remove: (id) => __privateGet(this, _client3).request(
+      remove: (id2) => __privateGet(this, _client3).request(
         "DELETE",
-        `/api/purchasing/payment-methods/${enc(id)}`
+        `/api/purchasing/payment-methods/${enc(id2)}`
       )
     };
     this.delegations = {
@@ -655,10 +657,10 @@ var AdminPurchasingClient = class {
         "GET",
         `/api/purchasing/delegations?buyerId=${enc(buyerId)}`
       ),
-      get: (id) => __privateGet(this, _client3).request("GET", `/api/purchasing/delegations/${enc(id)}`),
-      revoke: (id) => __privateGet(this, _client3).request(
+      get: (id2) => __privateGet(this, _client3).request("GET", `/api/purchasing/delegations/${enc(id2)}`),
+      revoke: (id2) => __privateGet(this, _client3).request(
         "POST",
-        `/api/purchasing/delegations/${enc(id)}/revoke`
+        `/api/purchasing/delegations/${enc(id2)}/revoke`
       )
     };
     this.settings = {
@@ -688,6 +690,204 @@ function verifyPurchaseWebhook(input) {
   return payload;
 }
 
+// src/spending.ts
+var id = encodeURIComponent;
+var SpendingClient = class {
+  constructor(client) {
+    this.client = client;
+  }
+  /**
+   * CSV of this agent's purchases against budgets in its own organization. Fails with `reasonCode`
+   * `EXPORT_TOO_LARGE` above 10,000 purchases.
+   */
+  exportPurchases() {
+    return this.client.download("/api/sdk/spending/purchases/export");
+  }
+  downloadEvidence(purchaseId, evidenceId) {
+    return this.client.download(
+      `/api/sdk/spending/purchases/${id(purchaseId)}/evidence/${id(evidenceId)}`
+    );
+  }
+  /** The budgets that cover this agent, with what is held, settled and available. */
+  budgets() {
+    return this.client.request("GET", "/api/sdk/budgets");
+  }
+  tasks(cursor) {
+    return this.client.request(
+      "GET",
+      `/api/sdk/tasks${cursor ? `?cursor=${id(cursor)}` : ""}`
+    );
+  }
+  /**
+   * 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) {
+    return this.client.request(
+      "POST",
+      "/api/sdk/tasks",
+      { ...input }
+    );
+  }
+  /** This agent's purchases against budgets in its own organization. Empty when none has applied. */
+  purchases(cursor) {
+    return this.client.request(
+      "GET",
+      `/api/sdk/spending/purchases${cursor ? `?cursor=${id(cursor)}` : ""}`
+    );
+  }
+  purchase(purchaseId) {
+    return this.client.request(
+      "GET",
+      `/api/sdk/spending/purchases/${id(purchaseId)}`
+    );
+  }
+  /**
+   * 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) {
+    return this.client.request("POST", "/api/sdk/spending/purchases/preview", { ...input });
+  }
+  /**
+   * 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, file, filename) {
+    const form = new FormData();
+    form.set("file", file, filename);
+    return this.client.request(
+      "POST",
+      `/api/sdk/spending/purchases/${id(purchaseId)}/evidence`,
+      form
+    );
+  }
+};
+var AdminSpendingClient = class {
+  constructor(client) {
+    this.client = client;
+  }
+  /**
+   * CSV of the organization's purchases against shared budgets. Fails with `reasonCode`
+   * `EXPORT_TOO_LARGE` above 10,000 purchases.
+   */
+  exportPurchases() {
+    return this.client.download("/api/spending/purchases/export");
+  }
+  /**
+   * 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, file, filename) {
+    const form = new FormData();
+    form.set("file", file, filename);
+    return this.client.request(
+      "POST",
+      `/api/spending/purchases/${id(purchaseId)}/evidence`,
+      form
+    );
+  }
+  downloadEvidence(purchaseId, evidenceId) {
+    return this.client.download(
+      `/api/spending/purchases/${id(purchaseId)}/evidence/${id(evidenceId)}`
+    );
+  }
+  budgets() {
+    return this.client.request("GET", "/api/spending/budgets");
+  }
+  /**
+   * 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) {
+    return this.client.request("POST", "/api/spending/budgets", {
+      ...input
+    });
+  }
+  /**
+   * 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, input) {
+    return this.client.request(
+      "PATCH",
+      `/api/spending/budgets/${id(budgetId)}`,
+      input
+    );
+  }
+  /**
+   * 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, input) {
+    return this.client.request(
+      "DELETE",
+      `/api/spending/budgets/${id(budgetId)}?version=${input.version}`
+    );
+  }
+  tasks(cursor) {
+    return this.client.request(
+      "GET",
+      `/api/spending/tasks${cursor ? `?cursor=${id(cursor)}` : ""}`
+    );
+  }
+  /** Approve, reject or close a task. Needs an organization API key with `policies:write`. */
+  decideTask(taskId, input) {
+    return this.client.request(
+      "POST",
+      `/api/spending/tasks/${id(taskId)}/decide`,
+      input
+    );
+  }
+  purchases(cursor) {
+    return this.client.request(
+      "GET",
+      `/api/spending/purchases${cursor ? `?cursor=${id(cursor)}` : ""}`
+    );
+  }
+  purchase(purchaseId) {
+    return this.client.request("GET", `/api/spending/purchases/${id(purchaseId)}`);
+  }
+  /** Record what happened to a purchase. Needs an API key with the `spending:reconcile` scope. */
+  reconcile(purchaseId, input) {
+    return this.client.request(
+      "POST",
+      `/api/spending/purchases/${id(purchaseId)}/reconcile`,
+      input
+    );
+  }
+  accounting(purchaseId, input) {
+    return this.client.request("PATCH", `/api/spending/purchases/${id(purchaseId)}`, input);
+  }
+  /** Record the amount, currency and merchant on a file. Conto does not take them from the file. */
+  reviewEvidence(purchaseId, evidenceId, input) {
+    return this.client.request(
+      "PATCH",
+      `/api/spending/purchases/${id(purchaseId)}/evidence/${id(evidenceId)}`,
+      input
+    );
+  }
+};
+
 // src/http.ts
 var PUBLIC_PAYMENT_REASONS = /* @__PURE__ */ new Set([
   "The available balance is insufficient for this payment.",
@@ -729,7 +929,34 @@ var VALIDATION_FIELDS = /* @__PURE__ */ new Set([
   "walletId",
   "idempotencyKey",
   "txHash",
-  "approvalToken"
+  "approvalToken",
+  "currency",
+  "merchant",
+  "sourceId",
+  "expiresAt",
+  "taskRequestId",
+  "purchaseKey",
+  "permittedMerchants",
+  "permittedSourceIds",
+  "name",
+  "scope",
+  "participantIds",
+  "requiresTask",
+  "period",
+  "periodStart",
+  "periodEnd",
+  "version",
+  "isActive",
+  "decision",
+  "eventKey",
+  "kind",
+  "settledAmount",
+  "refundedAmount",
+  "final",
+  "evidenceRef",
+  "department",
+  "project",
+  "accountingCode"
 ]);
 function customerFieldErrors(body, status) {
   if (![400, 422].includes(status) || !["VALIDATION_ERROR", "INVALID_REQUEST", "INVALID_INPUT"].includes(String(body.code)))
@@ -738,9 +965,7 @@ function customerFieldErrors(body, status) {
   if (!Array.isArray(fields)) return void 0;
   const names = [
     ...new Set(
-      fields.map((item) => record(item).field).filter(
-        (field) => typeof field === "string" && VALIDATION_FIELDS.has(field)
-      )
+      fields.map((item) => record(item).field).filter((field) => typeof field === "string").map((field) => field.split(".")[0]).filter((field) => VALIDATION_FIELDS.has(field))
     )
   ];
   return names.length ? names.map((field) => ({
@@ -883,14 +1108,68 @@ function fallbackRetryGuidance(status) {
 function responseErrorMessage(_data, status) {
   return safeErrorMessage(status);
 }
+var SHARED_REASON_CODES = /* @__PURE__ */ new Set([
+  "AGENT_NOT_AUTHORIZED",
+  "AGENT_UNAVAILABLE",
+  "BUDGET_CURRENCY_UNSUPPORTED",
+  "BUDGET_EXPIRED",
+  "BUDGET_HAS_HOLDS",
+  "BUDGET_PAUSED",
+  "BUYER_LINK_REVOKED",
+  "DUPLICATE_PURCHASE",
+  "ENROLLMENT_RECONCILIATION_REQUIRED",
+  "EVIDENCE_CONFLICT",
+  "EVIDENCE_LIMIT",
+  "EVIDENCE_REQUIRED",
+  "EXECUTION_PATH_NOT_CONNECTED",
+  "EXPORT_TOO_LARGE",
+  "INVALID_AMOUNT",
+  "INVALID_EXPIRY",
+  "INVALID_FILE",
+  "INVALID_PARTICIPANTS",
+  "INVALID_RENEWAL",
+  "INVALID_TASK_STATE",
+  "LEGACY_BUDGET_REQUEST",
+  "LINKED_BUDGET_REQUIRED",
+  "LINKED_TASK_UNSUPPORTED",
+  "MERCHANT_NOT_AUTHORIZED",
+  "NOT_FOUND",
+  "PURCHASE_ALREADY_SUBMITTED",
+  "PURCHASE_CONFLICT",
+  "SETTLED_PURCHASE",
+  "SHARED_BUDGET_EXCEEDED",
+  "SOURCE_CURRENCY_MISMATCH",
+  "SOURCE_NOT_AUTHORIZED",
+  "SOURCE_UNAVAILABLE",
+  "STALE_PAYMENT_EVIDENCE",
+  "STALE_VERSION",
+  "TASK_AUTHORITY_UNAVAILABLE",
+  "TASK_BUDGET",
+  "TASK_EXPIRED",
+  "TASK_REAPPROVAL_REQUIRED",
+  "TASK_REQUIRED",
+  "UNSUPPORTED_BUDGET_PERIOD"
+]);
+var SHARED_NEXT_ACTIONS = /* @__PURE__ */ new Set([
+  "REQUEST_BUDGET_INCREASE",
+  "INSPECT_BUDGETS",
+  "OWNER_RECONCILIATION",
+  "CHECK_STATUS"
+]);
 function responseErrorMetadata(response, data) {
   const body = record(data);
   const code = safeErrorCode(body.code, response.status);
   const bodyRetryAfter = typeof body.retryAfter === "number" || typeof body.retryAfter === "string" ? parseRetryAfter(String(body.retryAfter)) : void 0;
   const reasons = customerPaymentReasons(body.reasons);
+  const details = record(body.details);
+  const reasonCode = typeof details.reasonCode === "string" && SHARED_REASON_CODES.has(details.reasonCode) ? details.reasonCode : void 0;
+  const nextActions = reasonCode && Array.isArray(details.nextActions) ? details.nextActions.filter(
+    (value) => typeof value === "string" && SHARED_NEXT_ACTIONS.has(value)
+  ) : void 0;
   return {
     code,
     status: response.status,
+    ...reasonCode ? { reasonCode, nextActions } : {},
     ...reasons.length > 0 ? { reasons } : {},
     fieldErrors: customerFieldErrors(body, response.status),
     requestId: safeRequestId(
@@ -1033,6 +1312,9 @@ var ContoAdminError = class extends Error {
     this.requestId = metadata.requestId;
     this.retryAfter = metadata.retryAfter;
     this.retryGuidance = metadata.retryGuidance;
+    this.reasonCode = metadata.reasonCode;
+    this.nextActions = metadata.nextActions;
+    this.fieldErrors = metadata.fieldErrors;
   }
 };
 var _orgApiKey;
@@ -1057,6 +1339,7 @@ var ContoAdmin = class {
     this.baseUrl = (config.baseUrl || "https://conto.finance").replace(/\/$/, "");
     assertSecureBaseUrl(this.baseUrl);
     this.timeout = config.timeout || 3e4;
+    this.spending = new AdminSpendingClient(this);
     this.agents = new AgentsClient(this);
     this.wallets = new WalletsClient(this);
     this.cards = new AdminCardsClient(this);
@@ -1097,6 +1380,49 @@ var ContoAdmin = class {
       clearTimeout(timeoutId);
     }
   }
+  /**
+   * Download a file from the Conto API as bytes. It retries like a read, and
+   * failures throw ContoAdminError as request() does.
+   */
+  async download(path) {
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+    try {
+      const response = await fetchWithRetry(
+        `${this.baseUrl}${path}`,
+        {
+          headers: {
+            Authorization: `Bearer ${__privateGet(this, _orgApiKey)}`,
+            "User-Agent": `@conto_finance/sdk-admin/${import_package_version.SDK_PACKAGE_VERSION}`
+          },
+          // A redirect is an error response here, so the key never follows it.
+          redirect: "manual",
+          signal: controller.signal
+        },
+        { retryable: true }
+      );
+      if (!response.ok) {
+        const data = await readResponseData(response);
+        throw new ContoAdminError(
+          responseErrorMessage(data, response.status),
+          responseErrorMetadata(response, data)
+        );
+      }
+      return new Uint8Array(await response.arrayBuffer());
+    } catch (error) {
+      if (error instanceof ContoAdminError) throw error;
+      const timedOut = error instanceof Error && error.name === "AbortError";
+      const failure = new ContoAdminError(timedOut ? "Request timeout" : "Network request failed", {
+        code: timedOut ? "TIMEOUT" : "NETWORK_ERROR",
+        status: 0,
+        retryGuidance: "The request is safe to retry."
+      });
+      Sentry.captureException(failure, { extra: { method: "GET", path } });
+      throw failure;
+    } finally {
+      clearTimeout(timeoutId);
+    }
+  }
   /**
    * 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.
@@ -1114,10 +1440,10 @@ var ContoAdmin = class {
           method: normalizedMethod,
           headers: {
             Authorization: `Bearer ${__privateGet(this, _orgApiKey)}`,
-            "Content-Type": "application/json",
+            ...body instanceof FormData ? {} : { "Content-Type": "application/json" },
             "User-Agent": `@conto_finance/sdk-admin/${import_package_version.SDK_PACKAGE_VERSION}`
           },
-          body: body ? JSON.stringify(body) : void 0,
+          body: body instanceof FormData ? body : body ? JSON.stringify(body) : void 0,
           signal: controller.signal
         },
         { retryable }
@@ -1622,6 +1948,8 @@ var ContoError = class extends Error {
     this.actionUrl = metadata.actionUrl;
     this.fieldErrors = metadata.fieldErrors;
     this.reasons = metadata.reasons;
+    this.reasonCode = metadata.reasonCode;
+    this.nextActions = metadata.nextActions;
     if (diagnostics !== null && typeof diagnostics === "object" && !Array.isArray(diagnostics) && "version" in diagnostics && diagnostics.version === "conto.setup-diagnostics.v1") {
       this.diagnostics = diagnostics;
     }
@@ -1656,7 +1984,13 @@ var BrowserActionFinalizationPendingError = class extends ContoError {
 };
 var CheckoutCheckpointClosedError = class extends ContoError {
   constructor(checkpoint, message = `The checkpoint is ${checkpoint.stage.toLowerCase().replace(/_/g, " ")}. Stop this checkout.`, code = "CHECKOUT_CHECKPOINT_CLOSED") {
-    super(message, { code, status: 0 });
+    super(message, {
+      code,
+      status: 0,
+      ...checkpoint.paymentReference?.provider === "LINK" ? {
+        retryGuidance: "Closing a checkpoint does not close its Link request, so the card may still work. Cancel it with wallet.cancel(error.checkpoint.paymentReference.id). If that call throws, the card may have been used, so do not begin a new purchase. Fix what stopped it and try again, and if Link still refuses, ask the owner to check the order. Once the cancel succeeds, begin a new purchase with a new idempotency key if the buyer still wants it."
+      } : {}
+    });
     this.name = "CheckoutCheckpointClosedError";
     this.checkpoint = checkpoint;
     this.stage = checkpoint.stage;
@@ -1802,6 +2136,7 @@ var Conto = class {
     assertSecureBaseUrl(this.baseUrl);
     this.timeout = config.timeout || 3e4;
     this.checkout = new CheckoutClient(this);
+    this.spending = new SpendingClient(this);
     this.payments = new PaymentsClient(this);
     this.cards = new CardsClient(this);
     this.connectedCards = new ConnectedCardsClient(this);
@@ -2127,6 +2462,49 @@ var Conto = class {
       clearTimeout(timeoutId);
     }
   }
+  /**
+   * Download a file from the Conto API as bytes. It retries like a read, and
+   * failures throw ContoError as request() does.
+   */
+  async download(path) {
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+    try {
+      const response = await fetchWithRetry(
+        `${this.baseUrl}${path}`,
+        {
+          headers: {
+            Authorization: `Bearer ${__privateGet(this, _apiKey)}`,
+            "User-Agent": `@conto_finance/sdk/${import_package_version2.SDK_PACKAGE_VERSION}`
+          },
+          // A redirect is an error response here, so the key never follows it.
+          redirect: "manual",
+          signal: controller.signal
+        },
+        { retryable: true }
+      );
+      if (!response.ok) {
+        const data = await readResponseData(response);
+        throw new ContoError(
+          responseErrorMessage(data, response.status),
+          responseErrorMetadata(response, data)
+        );
+      }
+      return new Uint8Array(await response.arrayBuffer());
+    } catch (error) {
+      if (error instanceof ContoError) throw error;
+      const timedOut = error instanceof Error && error.name === "AbortError";
+      const failure = new ContoError(timedOut ? "Request timeout" : "Network request failed", {
+        code: timedOut ? "TIMEOUT" : "NETWORK_ERROR",
+        status: 0,
+        retryGuidance: "The request is safe to retry."
+      });
+      Sentry2.captureException(failure, { extra: { method: "GET", path } });
+      throw failure;
+    } finally {
+      clearTimeout(timeoutId);
+    }
+  }
   /** Make an authenticated request to the Conto API */
   async request(method, path, body, options = {}) {
     const url = `${this.baseUrl}${path}`;
@@ -2141,10 +2519,10 @@ var Conto = class {
           method: normalizedMethod,
           headers: {
             Authorization: `Bearer ${__privateGet(this, _apiKey)}`,
-            "Content-Type": "application/json",
+            ...body instanceof FormData ? {} : { "Content-Type": "application/json" },
             "User-Agent": `@conto_finance/sdk/${import_package_version2.SDK_PACKAGE_VERSION}`
           },
-          body: body ? JSON.stringify(body) : void 0,
+          body: body instanceof FormData ? body : body ? JSON.stringify(body) : void 0,
           signal: controller.signal
         },
         { retryable, maxRetries: options.maxRetries }
@@ -2505,11 +2883,11 @@ var TestCardsClient = class {
   }
 };
 function approvalRetryGuidance(requestId) {
-  const id = JSON.stringify(requestId);
-  return `An approver in Conto executes the payment when they approve it. After approval, call payments.execute(${id}) or payments.status(${id}) to get the receipt. Do not request the payment again.`;
+  const id2 = JSON.stringify(requestId);
+  return `An approver in Conto executes the payment when they approve it. After approval, call payments.execute(${id2}) or payments.status(${id2}) to get the receipt. Do not request the payment again.`;
 }
 function executeRetryGuidance(code, requestId) {
-  const id = JSON.stringify(requestId);
+  const id2 = JSON.stringify(requestId);
   switch (code) {
     case "APPROVAL_PENDING":
       return approvalRetryGuidance(requestId);
@@ -2520,7 +2898,7 @@ function executeRetryGuidance(code, requestId) {
       return "This payment now needs approval and will not execute. Request a new payment and wait for approval.";
     case "PAYMENT_PROCESSING":
     case "NEEDS_RECONCILIATION":
-      return `Do not execute again. Check payments.status(${id}) for the outcome.`;
+      return `Do not execute again. Check payments.status(${id2}) for the outcome.`;
     default:
       return void 0;
   }
@@ -2824,6 +3202,12 @@ function checkpointCart(amountMinor, lineItems, totals) {
   if (!Array.isArray(lineItems) || lineItems.length === 0) {
     throw checkoutError("Supply at least one line item");
   }
+  if (totals !== void 0 && totals !== null) {
+    const finalTotal = totals.filter((total) => total.type === "total");
+    if (finalTotal.length !== 1 || finalTotal[0].amountMinor !== amountMinor) {
+      throw checkoutError("totals must have one row with type total that equals amountMinor");
+    }
+  }
   return {
     lineItems,
     totals: totals ?? [{ type: "total", label: "Total", amountMinor }]
@@ -2863,6 +3247,13 @@ var LINK_REQUEST_ID = /^lsrq_[A-Za-z0-9]{1,64}$/;
 var LINK_WAITING_STATUSES = /* @__PURE__ */ new Set(["created", "pending_approval"]);
 var LINK_APPROVED_STATUSES = /* @__PURE__ */ new Set(["approved", "submitted", "succeeded"]);
 var LINK_CLOSED_STATUSES = /* @__PURE__ */ new Set(["denied", "expired", "canceled", "failed"]);
+var CLOSED_LINK_RESULTS = /* @__PURE__ */ new WeakSet();
+var CHECKPOINT_RELEASED_STAGES = [
+  "CANCELLED",
+  "EXPIRED",
+  "DENIED",
+  "NOT_PAID"
+];
 var INSPECT = /* @__PURE__ */ Symbol.for("nodejs.util.inspect.custom");
 function assertPaymentReference(reference) {
   if (reference === void 0) return;
@@ -2944,6 +3335,14 @@ function errorCode(error) {
 function errorReason(error) {
   return error && typeof error === "object" && typeof error.reason === "string" ? error.reason : void 0;
 }
+function duplicateGuidance(requestId, owner) {
+  const wait2 = `This purchase cannot start until Link request ${requestId} closes, so do not retry yet.`;
+  const then = "Once it closes, begin this purchase with a new idempotency key if the buyer still wants it.";
+  if (typeof owner !== "string" || !/^[A-Za-z0-9_-]{1,64}$/.test(owner)) {
+    return `${wait2} Finish the other purchase, or wait for Link to close the request. Do not cancel it, because a payment may be in flight. ${then}`;
+  }
+  return `${wait2} It belongs to checkpoint ${owner}, not error.checkpoint, which is this purchase. Read that one with checkout.get("${owner}"). If Conto cannot find it, another agent owns it, so leave the request alone and wait for Link to close it. At APPROVED, finish that purchase, or call wallet.cancel("${requestId}") and then checkout.cancel("${owner}"). At OUTCOME_UNKNOWN with linkRequestOpen true, if the card was used, report PAID with checkout.reportOutcome(), or UNKNOWN if you cannot tell. Otherwise call wallet.cancel("${requestId}") and then checkout.cancel("${owner}"). At CANCELLED, EXPIRED, DENIED, or NOT_PAID, call only wallet.cancel("${requestId}"). At any other stage a payment may be in flight or done, so do not cancel it. If wallet.cancel() throws, the card may have been used, so do not call checkout.cancel() or begin a new purchase. ${then}`;
+}
 function linkFailure(error, signal) {
   if (error instanceof LinkCardError) {
     return {
@@ -2959,6 +3358,24 @@ function linkFailure(error, signal) {
       message: errorReason(error) === "not_logged_in" ? 'link-cli is not logged in on this machine. Run "link-cli auth login".' : 'The Link wallet is not available here. Install link-cli with "npm i -g @stripe/link-cli", then run "link-cli auth login".'
     };
   }
+  const duplicate = error;
+  const duplicateOf = String(duplicate?.duplicateOf);
+  if (errorReason(error) === "invalid_input" && LINK_REQUEST_ID.test(duplicateOf)) {
+    return {
+      kind: LinkCardError,
+      code: "LINK_CARD_DUPLICATE_REQUEST",
+      message: "Link has an open request for another purchase with the same details.",
+      retryGuidance: duplicateGuidance(duplicateOf, duplicate?.duplicateCheckpoint)
+    };
+  }
+  if (errorReason(error) === "cli_failed" && LINK_REQUEST_ID.test(duplicateOf)) {
+    return {
+      kind: LinkCardError,
+      code: "LINK_CARD_FAILED",
+      message: "Link has an open request with the same details and no checkpoint on it, so a retry cannot resume it.",
+      retryGuidance: `Do not retry yet. Link request ${duplicateOf} has the same details and is not this checkout's, so do not cancel it yourself. Ask the person to finish or close it in Link, then retry with the same input. To stop this purchase instead, call checkout.cancel(error.checkpoint.id).`
+    };
+  }
   if (signal?.aborted || errorReason(error) === "aborted") {
     return {
       kind: LinkCardError,
@@ -2999,7 +3416,7 @@ function closedLinkFailure(request) {
       return {
         kind: LinkCardError,
         code: "LINK_CARD_ACTION_REQUIRED",
-        message: "Link needs the person to finish a step in Link before it can issue a card."
+        message: "Link cannot continue this request. The person has to fix a problem in Link before a new request can issue a card."
       };
     default:
       return {
@@ -3010,13 +3427,15 @@ function closedLinkFailure(request) {
       };
   }
 }
-async function closeLinkRequest(wallet, id) {
+async function closeLinkRequest(wallet, id2, onRefused) {
   try {
-    await wallet.cancel(id);
+    await wallet.cancel(id2);
     return true;
-  } catch {
-    const status = await wallet.waitForApproval(id, { timeoutSeconds: 0 }).then((request) => request.status).catch(() => void 0);
-    return status !== void 0 && LINK_CLOSED_STATUSES.has(status);
+  } catch (error) {
+    const status = await Promise.resolve().then(() => wallet.waitForApproval(id2, { timeoutSeconds: 0 })).then((request) => request.status).catch(() => void 0);
+    if (status !== void 0 && LINK_CLOSED_STATUSES.has(status)) return true;
+    onRefused?.(error);
+    return false;
   }
 }
 function assertLinkApprovalCallback(callback) {
@@ -3024,6 +3443,65 @@ function assertLinkApprovalCallback(callback) {
     throw checkoutError("onLinkApproval must be a function");
   }
 }
+function linkCardClosable(checkpoint) {
+  return CHECKPOINT_RELEASED_STAGES.includes(checkpoint.stage) || ["AWAITING_APPROVAL", "APPROVED"].includes(checkpoint.stage) || checkpoint.linkRequestOpen === true;
+}
+var CONFIRMING_GUIDANCE = "Wait a few seconds, then read the checkpoint with checkout.get(). Act only after the stage changes, and do not cancel the Link request before then, because the check can still end in CONFIRMED. If it is still CONFIRMING after a few minutes, stop and ask the owner to record the outcome on the checkout page.";
+var PAID_GUIDANCE = "Do not buy it again.";
+var CONFIRMED_GUIDANCE = "Report what happened with checkout.reportOutcome(), and do not cancel the Link request while a payment may be in flight. If you know no attempt paid or is paying, report NOT_PAID and cancel the Link request with wallet.cancel() so its card cannot be used. The owner can then release the hold, and you can begin a new purchase with a new idempotency key.";
+var LINK_CANCEL_STUCK_GUIDANCE = "If wallet.cancel() keeps failing, stop and do not call checkout.cancel(). The owner gets a review alert after the approval lapses and records the outcome on the checkout page.";
+var LINK_CANCEL_STUCK_NO_RECORD_GUIDANCE = "If wallet.cancel() keeps failing, fix what stopped it, then retry with the same input. Do not call checkout.cancel(). While Conto has no record of this request, the hold ends when the approval lapses, the card may still work, and the owner gets no alert, so tell the owner.";
+var LINK_REQUEST_OPEN_GUIDANCE = `If the card was used, report PAID with checkout.reportOutcome(), or UNKNOWN if you cannot tell, which keeps the spend held until the owner records what happened. Otherwise cancel the Link request with wallet.cancel(error.linkRequestId), then call checkout.cancel(error.checkpoint.id). ${LINK_CANCEL_STUCK_GUIDANCE}`;
+var LINK_ACTION_REQUIRED_GUIDANCE = `A retry cannot resume this request, and Link will not cancel it, but Link closes it on its own. wallet.waitForApproval(error.linkRequestId, { timeoutSeconds: 0 }) returns its actionUrl, where the person can fix the problem. To buy this, begin a new purchase with a new idempotency key once they have. Do not call checkout.cancel() yet. This hold stays until Link closes the request, and then a retry releases it. ${LINK_CANCEL_STUCK_GUIDANCE}`;
+function linkCardNotReplaced(stage) {
+  if (stage === "CONFIRMING") {
+    return {
+      message: "Conto is still checking this checkpoint, so the Link card cannot be replaced yet. Nothing changed. Do not pay this total.",
+      retryGuidance: CONFIRMING_GUIDANCE
+    };
+  }
+  if (stage === "PAID") {
+    return {
+      message: "This purchase is already recorded as paid, so the Link card cannot be replaced. Nothing changed. Do not pay again.",
+      retryGuidance: PAID_GUIDANCE
+    };
+  }
+  return {
+    message: "This checkpoint was already confirmed and a payment may be in flight, so the Link card cannot be replaced. Nothing changed. Do not pay this total.",
+    retryGuidance: CONFIRMED_GUIDANCE
+  };
+}
+function linkCardNotIssued(stage) {
+  if (stage === "CONFIRMING") {
+    return {
+      message: "Conto is still checking this checkpoint, so Link was not asked for a card. Do not pay, and do not cancel its Link request.",
+      retryGuidance: CONFIRMING_GUIDANCE
+    };
+  }
+  if (stage === "PAID") {
+    return {
+      message: "This purchase is already recorded as paid, so Link was not asked for a card. Do not pay again.",
+      retryGuidance: PAID_GUIDANCE
+    };
+  }
+  return {
+    message: "This checkpoint was already confirmed and a payment may be in flight, so Link was not asked for a card. Do not pay again, and do not cancel its Link request.",
+    retryGuidance: CONFIRMED_GUIDANCE
+  };
+}
+function openLinkRequestGuidance(latest) {
+  if (!latest) {
+    return "Read the checkpoint with checkout.get(error.checkpoint.id) before you do anything else. Do not cancel the Link request until you know its stage, because a payment may be in flight. If the stage is CANCELLED, EXPIRED, DENIED, or NOT_PAID, cancel it with wallet.cancel(error.linkRequestId) and do not pay with it. Otherwise retry with the same input, which resumes the request or tells you what to do at that stage.";
+  }
+  if (CHECKPOINT_RELEASED_STAGES.includes(latest.stage)) {
+    return "The checkpoint has closed, so a retry cannot resume this request. Cancel it with wallet.cancel(error.linkRequestId), and do not pay with it.";
+  }
+  if (latest.linkRequestOpen) return LINK_REQUEST_OPEN_GUIDANCE;
+  if (linkCardClosable(latest)) {
+    return `Retry with the same input to resume this Link request. To stop instead, read the checkpoint with checkout.get(). If it is still APPROVED, cancel the request with wallet.cancel(error.linkRequestId) and then call checkout.cancel(error.checkpoint.id). ${latest.paymentReference ? LINK_CANCEL_STUCK_GUIDANCE : LINK_CANCEL_STUCK_NO_RECORD_GUIDANCE}`;
+  }
+  return linkCardNotIssued(latest.stage).retryGuidance;
+}
 function linkCreatedNothing(error) {
   return errorCode(error) === "LINK_WALLET_UNAVAILABLE" || errorReason(error) === "invalid_input";
 }
@@ -3050,7 +3528,7 @@ function notifyLinkApproval(callback, event) {
   } catch {
   }
 }
-var _client4, _CheckoutClient_instances, linkCardFor_fn;
+var _client4, _CheckoutClient_instances, recordLinkRequest_fn, waitForLinkOwner_fn, linkCardFor_fn;
 var CheckoutClient = class {
   constructor(client) {
     __privateAdd(this, _CheckoutClient_instances);
@@ -3135,17 +3613,37 @@ var CheckoutClient = class {
     assertPaymentReference(input.paymentReference);
     let current = checkpoint;
     if (input.amountMinor !== checkpoint.amountMinor) {
-      if (input.paymentReference) {
-        throw new ContoError("The Link card covers the approved total, not this one. Do not pay.", {
-          code: "LINK_CARD_TOTAL_CHANGED",
-          status: 0,
-          retryGuidance: "Call checkout.replaceLinkCard(result, { wallet, amountMinor }) for a card at the final total, then confirm the checkpoint it returns."
-        });
+      if (input.paymentReference ?? checkpoint.paymentReference ?? (await this.get(checkpoint.id)).paymentReference) {
+        let notRecorded = false;
+        if (input.paymentReference && !checkpoint.paymentReference) {
+          notRecorded = await __privateGet(this, _client4).request(
+            "POST",
+            `/api/sdk/checkout-checkpoints/${encodeURIComponent(checkpoint.id)}/payment-reference`,
+            { paymentReference: { provider: "LINK", id: input.paymentReference.id } },
+            { idempotent: true }
+          ).then(
+            () => false,
+            async (error) => {
+              if (!(error instanceof ContoError && error.status === 409)) return true;
+              const latest = await this.get(checkpoint.id).catch(() => void 0);
+              return latest?.paymentReference?.id !== input.paymentReference?.id;
+            }
+          );
+        }
+        const note = notRecorded ? " Conto could not record this Link request, so its hold may end when the approval lapses." : "";
+        throw new ContoError(
+          `The Link card covers the approved total, not this one. Do not pay.${note}`,
+          {
+            code: "LINK_CARD_TOTAL_CHANGED",
+            status: 0,
+            retryGuidance: "Call checkout.replaceLinkCard(result, { wallet, amountMinor }) for a card at the final total, then confirm the checkpoint it returns."
+          }
+        );
       }
       try {
         await this.cancel(checkpoint.id);
       } catch (error) {
-        const closed = error instanceof ContoError && error.status === 409 && ["CANCELLED", "EXPIRED", "DENIED"].includes((await this.get(checkpoint.id)).stage);
+        const closed = error instanceof ContoError && error.status === 409 && CHECKPOINT_RELEASED_STAGES.includes((await this.get(checkpoint.id)).stage);
         if (!closed) throw error;
       }
       current = await this.begin({
@@ -3209,7 +3707,9 @@ var CheckoutClient = class {
   }
   /**
    * 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.
    */
   async cancel(checkpointId) {
     const result = await __privateGet(this, _client4).request(
@@ -3235,9 +3735,10 @@ var CheckoutClient = class {
    * 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,
@@ -3250,7 +3751,11 @@ var CheckoutClient = class {
    * 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. 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.
    */
   async getLinkCard(input) {
     const {
@@ -3267,10 +3772,7 @@ var CheckoutClient = class {
     assertLinkApprovalCallback(onLinkApproval);
     let checkpoint = await this.begin({ ...beginInput, checkoutMethod: "LINK" });
     if (checkpoint.stage === "AWAITING_APPROVAL") {
-      checkpoint = await this.waitForApproval(checkpoint, {
-        ...ownerApprovalTimeoutMs !== void 0 ? { timeoutMs: ownerApprovalTimeoutMs } : {},
-        ...signal ? { signal } : {}
-      });
+      checkpoint = await __privateMethod(this, _CheckoutClient_instances, waitForLinkOwner_fn).call(this, checkpoint, ownerApprovalTimeoutMs, signal);
     }
     return __privateMethod(this, _CheckoutClient_instances, linkCardFor_fn).call(this, checkpoint, wallet, {
       linkApprovalTimeoutMs,
@@ -3282,7 +3784,11 @@ var CheckoutClient = class {
    * 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.
    */
   async replaceLinkCard(previous, input) {
     const {
@@ -3297,23 +3803,73 @@ var CheckoutClient = class {
       throw checkoutError("amountMinor must be a positive integer number of cents");
     }
     assertLinkApprovalCallback(onLinkApproval);
-    if (amountMinor === previous.checkpoint.amountMinor) return previous;
     const old = previous.checkpoint;
-    if (!await closeLinkRequest(wallet, previous.linkRequestId)) {
+    checkpointCart(amountMinor, input.lineItems ?? old.cart.lineItems, input.totals);
+    const current = await this.get(old.id);
+    const released = CHECKPOINT_RELEASED_STAGES.includes(current.stage);
+    if (!linkCardClosable(current)) {
+      throw new LinkCardError({
+        ...linkCardNotReplaced(current.stage),
+        code: "LINK_CARD_NOT_REPLACED",
+        checkpoint: current,
+        linkRequestId: previous.linkRequestId,
+        holdReleased: false
+      });
+    }
+    const recordedRequestId = current.paymentReference?.id;
+    if (recordedRequestId && recordedRequestId !== previous.linkRequestId) {
+      throw new LinkCardError({
+        message: released ? "A different Link request is on record for this checkpoint. The held spend is already released, but either Link card may still work. Do not pay with them." : "A different Link request is on record for this checkpoint, so the Link card cannot be replaced. Nothing changed. Do not pay.",
+        code: "LINK_CARD_NOT_REPLACED",
+        checkpoint: current,
+        linkRequestId: recordedRequestId,
+        holdReleased: released,
+        retryGuidance: released ? `Cancel both ${recordedRequestId} and ${previous.linkRequestId} with wallet.cancel().` : `Use the result for that request, or cancel both ${recordedRequestId} and ${previous.linkRequestId} with wallet.cancel() and then call checkout.cancel(error.checkpoint.id).`
+      });
+    }
+    if (amountMinor === old.amountMinor && !released && !current.linkRequestOpen && !CLOSED_LINK_RESULTS.has(previous)) {
+      return previous;
+    }
+    if (signal?.aborted) {
       throw new LinkCardError({
-        message: "Conto could not cancel the earlier Link card. Nothing changed. Do not pay.",
+        message: released ? "The caller stopped before the Link card was replaced. The held spend is already released, and the earlier Link card may still work. Do not pay with it." : "The caller stopped before the Link card was replaced. Nothing changed. Do not pay.",
+        code: "LINK_CARD_ABORTED",
+        checkpoint: current,
+        linkRequestId: previous.linkRequestId,
+        holdReleased: released,
+        retryGuidance: released ? "Try replaceLinkCard again, or cancel the request with wallet.cancel(error.linkRequestId)." : "Try replaceLinkCard again, or cancel the request with wallet.cancel(error.linkRequestId) and then call checkout.cancel(error.checkpoint.id)."
+      });
+    }
+    let refusal;
+    const oldCardClosed = await closeLinkRequest(wallet, previous.linkRequestId, (error) => {
+      refusal = error;
+    });
+    if (!oldCardClosed) {
+      const walletDown = errorCode(refusal) === "LINK_WALLET_UNAVAILABLE";
+      throw new LinkCardError({
+        message: `${walletDown ? `${linkFailure(refusal).message} ` : ""}${released ? "The held spend is already released, but Conto could not cancel the earlier Link card, so it may still work. Do not pay with it." : "Conto could not cancel the earlier Link card. Nothing changed. Do not pay."}`,
         code: "LINK_CARD_NOT_CANCELLED",
-        checkpoint: old,
+        checkpoint: current,
         linkRequestId: previous.linkRequestId,
-        holdReleased: false,
-        retryGuidance: "Try replaceLinkCard again."
+        holdReleased: released,
+        retryGuidance: `${walletDown ? "Fix the Link wallet first, as the message says. Until then a retry fails the same way. " : ""}${current.linkRequestOpen ? "Try replaceLinkCard again. If the card was already used, report PAID with checkout.reportOutcome(), or UNKNOWN if you cannot tell, which keeps the spend held until the owner records what happened." : released ? "Try replaceLinkCard again, or cancel the request with wallet.cancel(error.linkRequestId) and do not pay with it." : "Try replaceLinkCard again."}`
       });
     }
+    CLOSED_LINK_RESULTS.add(previous);
     try {
       await this.cancel(old.id);
     } catch (error) {
-      const closed = error instanceof ContoError && error.status === 409 && ["CANCELLED", "EXPIRED", "DENIED"].includes((await this.get(old.id)).stage);
-      if (!closed) throw error;
+      const latest = error instanceof ContoError && error.status === 409 ? await this.get(old.id).catch(() => void 0) : void 0;
+      if (!released && (!latest || !CHECKPOINT_RELEASED_STAGES.includes(latest.stage))) {
+        throw new LinkCardError({
+          message: "The earlier Link request is cancelled, but Conto did not release the held spend. Do not confirm or pay.",
+          code: "CHECKPOINT_NOT_CANCELLED",
+          checkpoint: latest ?? current,
+          linkRequestId: previous.linkRequestId,
+          holdReleased: false,
+          retryGuidance: "Try replaceLinkCard again. If the checkpoint was confirmed, report its outcome instead."
+        });
+      }
     }
     let checkpoint = await this.begin({
       idempotencyKey: `${old.idempotencyKey.slice(0, 200)}:final-${amountMinor}`,
@@ -3330,10 +3886,7 @@ var CheckoutClient = class {
       totals: input.totals
     });
     if (checkpoint.stage === "AWAITING_APPROVAL") {
-      checkpoint = await this.waitForApproval(checkpoint, {
-        ...ownerApprovalTimeoutMs !== void 0 ? { timeoutMs: ownerApprovalTimeoutMs } : {},
-        ...signal ? { signal } : {}
-      });
+      checkpoint = await __privateMethod(this, _CheckoutClient_instances, waitForLinkOwner_fn).call(this, checkpoint, ownerApprovalTimeoutMs, signal);
     }
     return __privateMethod(this, _CheckoutClient_instances, linkCardFor_fn).call(this, checkpoint, wallet, {
       linkApprovalTimeoutMs,
@@ -3344,19 +3897,74 @@ var CheckoutClient = class {
 };
 _client4 = new WeakMap();
 _CheckoutClient_instances = new WeakSet();
+recordLinkRequest_fn = async function(checkpoint, linkRequestId) {
+  try {
+    const result = await __privateGet(this, _client4).request(
+      "POST",
+      `/api/sdk/checkout-checkpoints/${encodeURIComponent(checkpoint.id)}/payment-reference`,
+      { paymentReference: { provider: "LINK", id: linkRequestId } },
+      { idempotent: true }
+    );
+    return result.checkpoint;
+  } catch (error) {
+    if (!(error instanceof ContoError)) throw error;
+    throw new LinkFailureSignal({
+      kind: LinkCardError,
+      code: "LINK_CARD_NOT_RECORDED",
+      message: "Conto could not record the Link card request."
+    });
+  }
+};
+waitForLinkOwner_fn = async function(checkpoint, timeoutMs, signal) {
+  try {
+    return await this.waitForApproval(checkpoint, {
+      ...timeoutMs !== void 0 ? { timeoutMs } : {},
+      ...signal ? { signal } : {}
+    });
+  } catch (error) {
+    if (!signal?.aborted || error instanceof ContoError && error !== signal.reason) throw error;
+    const latest = await this.get(checkpoint.id).catch(() => void 0);
+    const linkRequestId = latest?.paymentReference?.id;
+    const released = Boolean(latest && CHECKPOINT_RELEASED_STAGES.includes(latest.stage));
+    throw new LinkCardError({
+      message: released ? "The caller stopped while waiting for the owner, and the held spend is already released. Do not pay." : "The caller stopped while waiting for the owner, and the held spend stays in place. Do not pay.",
+      code: "LINK_CARD_ABORTED",
+      checkpoint: latest ?? checkpoint,
+      ...linkRequestId ? { linkRequestId } : {},
+      holdReleased: released,
+      ...released && !linkRequestId ? {} : {
+        retryGuidance: latest && !linkRequestId && linkCardClosable(latest) ? "Retry with the same input, or call checkout.cancel(error.checkpoint.id) to release the held spend." : openLinkRequestGuidance(latest)
+      }
+    });
+  }
+};
 linkCardFor_fn = async function(checkpoint, wallet, options) {
   const { linkApprovalTimeoutMs = 10 * 6e4, signal, onLinkApproval } = options;
+  if (checkpoint.linkRequestOpen) {
+    throw new LinkCardError({
+      message: `Conto's approval for this checkpoint ended while its Link request may still work (stage ${checkpoint.stage}). Do not pay.`,
+      code: "CHECKOUT_CHECKPOINT_NOT_APPROVED",
+      checkpoint,
+      ...checkpoint.paymentReference ? { linkRequestId: checkpoint.paymentReference.id } : {},
+      holdReleased: false,
+      retryGuidance: LINK_REQUEST_OPEN_GUIDANCE
+    });
+  }
   if (checkpoint.stage !== "APPROVED") {
-    throw checkoutError(
-      `Conto has not approved a card for this checkpoint (stage ${checkpoint.stage}). Do not pay.`,
-      "CHECKOUT_CHECKPOINT_NOT_APPROVED"
-    );
+    throw new LinkCardError({
+      ...linkCardNotIssued(checkpoint.stage),
+      code: "LINK_CARD_NOT_ISSUED",
+      checkpoint,
+      holdReleased: false
+    });
   }
   const deadline = Date.now() + linkApprovalTimeoutMs;
   const call = signal ? { signal } : {};
-  let linkRequestId;
+  const recordedRequestId = checkpoint.paymentReference?.id;
+  let linkRequestId = recordedRequestId;
   let approvalUrl;
   let createStarted = false;
+  let createAnswered = false;
   try {
     const cardRequest = linkCardRequest(checkpoint);
     createStarted = true;
@@ -3369,6 +3977,7 @@ linkCardFor_fn = async function(checkpoint, wallet, options) {
       });
     }
     linkRequestId = request.id;
+    createAnswered = true;
     if (request.amountMinor !== void 0 && request.amountMinor !== checkpoint.amountMinor) {
       throw new LinkFailureSignal({
         kind: LinkCardError,
@@ -3376,6 +3985,14 @@ linkCardFor_fn = async function(checkpoint, wallet, options) {
         message: "Link returned a request for a different amount."
       });
     }
+    checkpoint = await __privateMethod(this, _CheckoutClient_instances, recordLinkRequest_fn).call(this, checkpoint, request.id);
+    if (checkpoint.stage !== "APPROVED") {
+      throw new LinkFailureSignal({
+        kind: LinkCardError,
+        code: "LINK_CARD_NOT_ISSUED",
+        message: "Conto no longer has this checkpoint approved, so no Link card was returned."
+      });
+    }
     if (LINK_WAITING_STATUSES.has(request.status)) {
       const details = linkApprovalDetails(request);
       approvalUrl = details.approvalUrl;
@@ -3414,43 +4031,81 @@ linkCardFor_fn = async function(checkpoint, wallet, options) {
     };
   } catch (error) {
     const failure = error instanceof LinkFailureSignal ? error.failure : linkFailure(error, signal);
-    if (!linkRequestId && createStarted && !linkCreatedNothing(error)) {
+    const latest = createStarted || linkRequestId || !linkCardClosable(checkpoint) ? await this.get(checkpoint.id).catch(() => void 0) : checkpoint;
+    const onRecordId = latest?.paymentReference?.id ?? recordedRequestId;
+    const anotherFlow = !recordedRequestId && onRecordId && onRecordId !== linkRequestId;
+    const alreadyReleased = Boolean(latest && CHECKPOINT_RELEASED_STAGES.includes(latest.stage));
+    const unread = recordedRequestId || linkRequestId && !failure.linkClosed;
+    if (latest ? !linkCardClosable(latest) || anotherFlow : unread) {
+      const extraRequestId = onRecordId && linkRequestId !== onRecordId ? linkRequestId : void 0;
+      const extraOpen = extraRequestId && !failure.linkClosed && !await closeLinkRequest(wallet, extraRequestId);
+      const keptId = onRecordId ?? linkRequestId;
       throw new LinkCardError({
-        message: `${failure.message} Conto could not tell whether Link created the card request, so the held spend stays in place. Do not pay.`,
+        message: alreadyReleased ? `${failure.message} A different Link request is on record, so Conto did not cancel it. The held spend is already released, but its card may still work. Do not pay with it.` : `${failure.message} The checkpoint changed or could not be read, so Conto did not cancel the Link request, and the held spend stays in place${latest || onRecordId || checkpoint.paymentReference ? "" : ", and may be released when the approval lapses"}. Do not pay.`,
         code: "LINK_CARD_NOT_CANCELLED",
-        checkpoint,
-        holdReleased: false,
-        retryGuidance: "Retry with the same input to resume the Link request, or call checkout.cancel(error.checkpoint.id) once you know Link created none."
+        checkpoint: latest ?? checkpoint,
+        ...keptId ? { linkRequestId: keptId } : {},
+        holdReleased: alreadyReleased,
+        retryGuidance: `${extraOpen ? `Cancel ${extraRequestId} with wallet.cancel() first, because it is not the request on record. ` : ""}${openLinkRequestGuidance(latest)}`
       });
     }
-    if (linkRequestId && !failure.linkClosed && !await closeLinkRequest(wallet, linkRequestId)) {
+    if (createStarted && !createAnswered && !linkCreatedNothing(error)) {
+      const blockedBy = !recordedRequestId && !alreadyReleased && failure.retryGuidance;
       throw new LinkCardError({
-        message: `${failure.message} Conto could not cancel the Link request, so the held spend stays in place. Do not pay.`,
+        message: alreadyReleased ? `${failure.message} Conto could not tell whether Link created the card request. The held spend is already released, but ${recordedRequestId ? "the Link request on record" : "a request Link created"} may still work. Do not pay with it.` : blockedBy ? `${failure.message} The held spend stays in place, and may be released when the approval lapses. Do not pay.` : `${failure.message} Conto could not tell whether Link created the card request, so the held spend stays in place${recordedRequestId ? "" : ", and may be released when the approval lapses"}. Do not pay.`,
         code: "LINK_CARD_NOT_CANCELLED",
-        checkpoint,
-        linkRequestId,
-        ...approvalUrl ? { approvalUrl } : {},
-        holdReleased: false,
-        retryGuidance: "Retry with the same input to resume this Link request, or cancel it with wallet.cancel(error.linkRequestId) and then call checkout.cancel(error.checkpoint.id)."
+        checkpoint: latest ?? checkpoint,
+        ...recordedRequestId ? { linkRequestId: recordedRequestId } : {},
+        holdReleased: alreadyReleased,
+        retryGuidance: recordedRequestId ? openLinkRequestGuidance(latest) : alreadyReleased ? "The checkpoint has closed, so a retry cannot resume a Link request. Begin a new purchase with a new idempotency key if the buyer still wants it. If Link then reports a duplicate, follow that error." : blockedBy || "Retry with the same input to resume the Link request, or call checkout.cancel(error.checkpoint.id) once you know Link created none."
       });
     }
-    const holdReleased = await this.cancel(checkpoint.id).then(
-      () => true,
+    const requestsToClose = /* @__PURE__ */ new Set();
+    if (linkRequestId && !failure.linkClosed) requestsToClose.add(linkRequestId);
+    if (recordedRequestId && recordedRequestId !== linkRequestId) {
+      requestsToClose.add(recordedRequestId);
+    }
+    const stillOpen = [];
+    for (const id2 of requestsToClose) {
+      if (!await closeLinkRequest(wallet, id2)) stillOpen.push(id2);
+    }
+    if (stillOpen.length > 0) {
+      const held = onRecordId ? "" : ", and may be released when the approval lapses";
+      const bothOpen = stillOpen.length > 1 ? ` Link requests ${stillOpen.join(" and ")} are both open.` : "";
+      throw new LinkCardError({
+        message: alreadyReleased ? `${failure.message} The held spend is already released, but Conto could not cancel the Link request, so its card may still work.${bothOpen} Do not pay with it.` : `${failure.message} Conto could not cancel the Link request, so the held spend stays in place${held}.${bothOpen} Do not pay.`,
+        code: "LINK_CARD_NOT_CANCELLED",
+        checkpoint: latest ?? checkpoint,
+        // The one on record first, because a card may already be out on it.
+        linkRequestId: onRecordId && stillOpen.includes(onRecordId) ? onRecordId : stillOpen[0],
+        ...approvalUrl && latest?.stage === "APPROVED" ? { approvalUrl } : {},
+        holdReleased: alreadyReleased,
+        retryGuidance: stillOpen.length > 1 ? `Cancel ${stillOpen.join(" and ")} with wallet.cancel()${alreadyReleased ? "" : ", then call checkout.cancel(error.checkpoint.id)"}.` : failure.code === "LINK_CARD_ACTION_REQUIRED" && latest?.stage === "APPROVED" ? LINK_ACTION_REQUIRED_GUIDANCE : openLinkRequestGuidance(latest)
+      });
+    }
+    let cancelled;
+    const holdReleased = alreadyReleased || await this.cancel(checkpoint.id).then(
+      (result) => {
+        cancelled = result;
+        return true;
+      },
       () => false
     );
     throw new failure.kind({
-      message: `${failure.message} ${holdReleased ? "Conto cancelled the checkpoint and released the held spend." : "Conto could not cancel the checkpoint yet."} Do not pay.`,
+      message: `${failure.message} ${alreadyReleased ? "The held spend was already released." : holdReleased ? "Conto cancelled the checkpoint and released the held spend." : "Conto could not cancel the checkpoint yet."} Do not pay.`,
       code: failure.code,
-      checkpoint,
+      checkpoint: cancelled ?? latest ?? checkpoint,
       ...linkRequestId ? { linkRequestId } : {},
       ...linkRequestId && approvalUrl ? { approvalUrl } : {},
-      holdReleased
+      holdReleased,
+      ...holdReleased && failure.retryGuidance ? { retryGuidance: failure.retryGuidance } : {}
     });
   }
 };
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   AdminPurchasingClient,
+  AdminSpendingClient,
   BrowserActionFinalizationPendingError,
   BrowserCheckoutTargetVerificationError,
   CardsClient,
@@ -3477,6 +4132,7 @@ linkCardFor_fn = async function(checkpoint, wallet, options) {
   OrganizationRecurringPurchasesClient,
   PurchasesClient,
   RecurringPurchasesClient,
+  SpendingClient,
   TestCardsClient,
   canonicalizeBrowserCheckoutTarget,
   createVerifiedBrowserCheckoutDriver,