@conto_finance/sdk 0.7.0 → 0.8.0

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.0",
+      version: "0.8.0",
       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,
@@ -197,6 +199,32 @@ var Sentry2 = __toESM(require("@sentry/node"));
 var import_node_crypto3 = require("crypto");
 var import_package_version2 = __toESM(require_package_version());
 
+// src/link-approval.ts
+function safeLinkApprovalUrl(value) {
+  if (typeof value !== "string" || value.length === 0 || value.length > 2048) return void 0;
+  let url;
+  try {
+    url = new URL(value);
+  } catch {
+    return void 0;
+  }
+  if (url.protocol !== "https:" || url.username !== "" || url.password !== "" || url.port !== "" || !(url.hostname === "link.com" || url.hostname.endsWith(".link.com"))) {
+    return void 0;
+  }
+  url.hash = "";
+  return url.toString();
+}
+function linkTime(value) {
+  let ms = Number.NaN;
+  if (typeof value === "number" && Number.isFinite(value) && value > 0) {
+    ms = value < 1e12 ? value * 1e3 : value;
+  } else if (typeof value === "string" && value.length > 0 && value.length <= 64) {
+    ms = Date.parse(value);
+  }
+  const date = new Date(ms);
+  return Number.isNaN(date.getTime()) ? void 0 : date.toISOString();
+}
+
 // src/purchases.ts
 var import_node_crypto = require("crypto");
 var TERMINAL = /* @__PURE__ */ new Set(["succeeded", "blocked", "failed", "cancelled"]);
@@ -262,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");
@@ -284,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`
     );
   }
 };
@@ -315,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`
     );
   }
 };
@@ -355,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 }
     );
@@ -396,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))
@@ -462,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}`,
@@ -520,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
     );
   }
@@ -540,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. */
@@ -595,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 = {
@@ -619,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 = {
@@ -629,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 = {
@@ -662,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.",
@@ -703,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)))
@@ -712,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) => ({
@@ -857,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(
@@ -1007,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;
@@ -1031,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);
@@ -1071,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.
@@ -1088,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 }
@@ -1596,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;
     }
@@ -1684,6 +2038,8 @@ var LinkCardError = class extends ContoError {
     this.name = "LinkCardError";
     this.checkpoint = input.checkpoint;
     if (input.linkRequestId) this.linkRequestId = input.linkRequestId;
+    const approvalUrl = safeLinkApprovalUrl(input.approvalUrl);
+    if (approvalUrl) this.approvalUrl = approvalUrl;
     this.holdReleased = input.holdReleased;
   }
 };
@@ -1774,6 +2130,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);
@@ -2099,6 +2456,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}`;
@@ -2113,10 +2513,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 }
@@ -2477,11 +2877,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);
@@ -2492,7 +2892,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;
   }
@@ -2982,15 +3382,20 @@ function closedLinkFailure(request) {
       };
   }
 }
-async function closeLinkRequest(wallet, id) {
+async function closeLinkRequest(wallet, id2) {
   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);
+    const status = await wallet.waitForApproval(id2, { timeoutSeconds: 0 }).then((request) => request.status).catch(() => void 0);
     return status !== void 0 && LINK_CLOSED_STATUSES.has(status);
   }
 }
+function assertLinkApprovalCallback(callback) {
+  if (callback !== void 0 && typeof callback !== "function") {
+    throw checkoutError("onLinkApproval must be a function");
+  }
+}
 function linkCreatedNothing(error) {
   return errorCode(error) === "LINK_WALLET_UNAVAILABLE" || errorReason(error) === "invalid_input";
 }
@@ -3000,7 +3405,24 @@ var LinkFailureSignal = class extends Error {
     this.failure = failure;
   }
 };
-var _client4, _CheckoutClient_instances, linkCardFor_fn;
+function linkApprovalDetails(request) {
+  const approvalUrl = safeLinkApprovalUrl(request.approvalUrl);
+  const approvalExpiresAt = linkTime(request.approvalExpiresAt);
+  return {
+    ...approvalUrl ? { approvalUrl } : {},
+    ...approvalExpiresAt ? { approvalExpiresAt } : {}
+  };
+}
+function notifyLinkApproval(callback, event) {
+  try {
+    const result = callback(Object.freeze(event));
+    if (result !== null && typeof result === "object" && "then" in result) {
+      Promise.resolve(result).catch(() => void 0);
+    }
+  } catch {
+  }
+}
+var _client4, _CheckoutClient_instances, recordLinkRequest_fn, linkCardFor_fn;
 var CheckoutClient = class {
   constructor(client) {
     __privateAdd(this, _CheckoutClient_instances);
@@ -3085,7 +3507,7 @@ var CheckoutClient = class {
     assertPaymentReference(input.paymentReference);
     let current = checkpoint;
     if (input.amountMinor !== checkpoint.amountMinor) {
-      if (input.paymentReference) {
+      if (input.paymentReference ?? checkpoint.paymentReference) {
         throw new ContoError("The Link card covers the approved total, not this one. Do not pay.", {
           code: "LINK_CARD_TOTAL_CHANGED",
           status: 0,
@@ -3185,7 +3607,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.
+   *    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,
@@ -3198,13 +3623,23 @@ 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. Once the stage is OUTCOME_UNKNOWN,
+   * a retry throws CHECKOUT_CHECKPOINT_NOT_APPROVED: cancel the Link request, then
+   * the checkpoint.
    */
   async getLinkCard(input) {
-    const { wallet, ownerApprovalTimeoutMs, linkApprovalTimeoutMs, signal, ...beginInput } = input;
+    const {
+      wallet,
+      ownerApprovalTimeoutMs,
+      linkApprovalTimeoutMs,
+      onLinkApproval,
+      signal,
+      ...beginInput
+    } = input;
     if (!wallet || typeof wallet.createCardRequest !== "function") {
       throw checkoutError("wallet must be a LinkWallet, such as linkCliWallet()");
     }
+    assertLinkApprovalCallback(onLinkApproval);
     let checkpoint = await this.begin({ ...beginInput, checkoutMethod: "LINK" });
     if (checkpoint.stage === "AWAITING_APPROVAL") {
       checkpoint = await this.waitForApproval(checkpoint, {
@@ -3212,7 +3647,11 @@ var CheckoutClient = class {
         ...signal ? { signal } : {}
       });
     }
-    return __privateMethod(this, _CheckoutClient_instances, linkCardFor_fn).call(this, checkpoint, wallet, linkApprovalTimeoutMs, signal);
+    return __privateMethod(this, _CheckoutClient_instances, linkCardFor_fn).call(this, checkpoint, wallet, {
+      linkApprovalTimeoutMs,
+      signal,
+      onLinkApproval
+    });
   }
   /**
    * The final total differs from the one the Link card covers. This cancels
@@ -3221,10 +3660,18 @@ var CheckoutClient = class {
    * for it. Confirm the returned checkpoint with the same total.
    */
   async replaceLinkCard(previous, input) {
-    const { wallet, amountMinor, ownerApprovalTimeoutMs, linkApprovalTimeoutMs, signal } = input;
+    const {
+      wallet,
+      amountMinor,
+      ownerApprovalTimeoutMs,
+      linkApprovalTimeoutMs,
+      onLinkApproval,
+      signal
+    } = input;
     if (!Number.isSafeInteger(amountMinor) || amountMinor <= 0) {
       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)) {
@@ -3263,12 +3710,35 @@ var CheckoutClient = class {
         ...signal ? { signal } : {}
       });
     }
-    return __privateMethod(this, _CheckoutClient_instances, linkCardFor_fn).call(this, checkpoint, wallet, linkApprovalTimeoutMs, signal);
+    return __privateMethod(this, _CheckoutClient_instances, linkCardFor_fn).call(this, checkpoint, wallet, {
+      linkApprovalTimeoutMs,
+      signal,
+      onLinkApproval
+    });
   }
 };
 _client4 = new WeakMap();
 _CheckoutClient_instances = new WeakSet();
-linkCardFor_fn = async function(checkpoint, wallet, linkApprovalTimeoutMs = 10 * 6e4, signal) {
+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."
+    });
+  }
+};
+linkCardFor_fn = async function(checkpoint, wallet, options) {
+  const { linkApprovalTimeoutMs = 10 * 6e4, signal, onLinkApproval } = options;
   if (checkpoint.stage !== "APPROVED") {
     throw checkoutError(
       `Conto has not approved a card for this checkpoint (stage ${checkpoint.stage}). Do not pay.`,
@@ -3278,6 +3748,7 @@ linkCardFor_fn = async function(checkpoint, wallet, linkApprovalTimeoutMs = 10 *
   const deadline = Date.now() + linkApprovalTimeoutMs;
   const call = signal ? { signal } : {};
   let linkRequestId;
+  let approvalUrl;
   let createStarted = false;
   try {
     const cardRequest = linkCardRequest(checkpoint);
@@ -3298,6 +3769,14 @@ linkCardFor_fn = async function(checkpoint, wallet, linkApprovalTimeoutMs = 10 *
         message: "Link returned a request for a different amount."
       });
     }
+    checkpoint = await __privateMethod(this, _CheckoutClient_instances, recordLinkRequest_fn).call(this, checkpoint, request.id);
+    if (LINK_WAITING_STATUSES.has(request.status)) {
+      const details = linkApprovalDetails(request);
+      approvalUrl = details.approvalUrl;
+      if (onLinkApproval) {
+        notifyLinkApproval(onLinkApproval, { checkpoint, linkRequestId: request.id, ...details });
+      }
+    }
     while (linkRequestWaiting(request)) {
       const remainingSeconds = Math.floor((deadline - Date.now()) / 1e3);
       if (remainingSeconds <= 0) {
@@ -3312,6 +3791,7 @@ linkCardFor_fn = async function(checkpoint, wallet, linkApprovalTimeoutMs = 10 *
         ...call,
         timeoutSeconds: remainingSeconds
       });
+      approvalUrl = LINK_WAITING_STATUSES.has(request.status) ? linkApprovalDetails(request).approvalUrl ?? approvalUrl : void 0;
       if (linkRequestWaiting(request) && Date.now() - started < 1e3) {
         await sleep2(1e3, signal);
       }
@@ -3343,6 +3823,7 @@ linkCardFor_fn = async function(checkpoint, wallet, linkApprovalTimeoutMs = 10 *
         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)."
       });
@@ -3356,6 +3837,7 @@ linkCardFor_fn = async function(checkpoint, wallet, linkApprovalTimeoutMs = 10 *
       code: failure.code,
       checkpoint,
       ...linkRequestId ? { linkRequestId } : {},
+      ...linkRequestId && approvalUrl ? { approvalUrl } : {},
       holdReleased
     });
   }
@@ -3363,6 +3845,7 @@ linkCardFor_fn = async function(checkpoint, wallet, linkApprovalTimeoutMs = 10 *
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   AdminPurchasingClient,
+  AdminSpendingClient,
   BrowserActionFinalizationPendingError,
   BrowserCheckoutTargetVerificationError,
   CardsClient,
@@ -3389,6 +3872,7 @@ linkCardFor_fn = async function(checkpoint, wallet, linkApprovalTimeoutMs = 10 *
   OrganizationRecurringPurchasesClient,
   PurchasesClient,
   RecurringPurchasesClient,
+  SpendingClient,
   TestCardsClient,
   canonicalizeBrowserCheckoutTarget,
   createVerifiedBrowserCheckoutDriver,