@conto_finance/sdk 0.6.1 → 0.6.2-beta.1

package/dist/index.js

@@ -40,13 +40,14 @@ var __accessCheck = (obj, member, msg) => member.has(obj) || __typeError("Cannot
 var __privateGet = (obj, member, getter) => (__accessCheck(obj, member, "read from private field"), getter ? getter.call(obj) : member.get(obj));
 var __privateAdd = (obj, member, value) => member.has(obj) ? __typeError("Cannot add the same private member more than once") : member instanceof WeakSet ? member.add(obj) : member.set(obj, value);
 var __privateSet = (obj, member, value, setter) => (__accessCheck(obj, member, "write to private field"), setter ? setter.call(obj, value) : member.set(obj, value), value);
+var __privateMethod = (obj, member, method) => (__accessCheck(obj, member, "access private method"), method);
 
 // package.json
 var require_package = __commonJS({
   "package.json"(exports2, module2) {
     module2.exports = {
       name: "@conto_finance/sdk",
-      version: "0.6.1",
+      version: "0.6.2-beta.1",
       description: "Conto SDK for AI agent payment authorization",
       main: "./dist/index.js",
       module: "./dist/index.mjs",
@@ -71,10 +72,16 @@ var require_package = __commonJS({
           types: "./dist/checkout-verifier.d.ts",
           import: "./dist/checkout-verifier.mjs",
           require: "./dist/checkout-verifier.js"
+        },
+        "./link-wallet": {
+          types: "./dist/link-wallet.d.ts",
+          import: "./dist/link-wallet.mjs",
+          require: "./dist/link-wallet.js"
         }
       },
       publishConfig: {
-        access: "public"
+        access: "public",
+        tag: "beta"
       },
       engines: {
         node: ">=20.19.0"
@@ -87,7 +94,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/purchases.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 ../../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"
@@ -112,7 +119,7 @@ var require_package = __commonJS({
         email: "support@conto.finance"
       },
       dependencies: {
-        "@sentry/node": "^10.63.0"
+        "@sentry/node": "^10.73.0"
       },
       peerDependencies: {
         "playwright-core": ">=1.50.0"
@@ -168,6 +175,11 @@ __export(index_exports, {
   ControlledExternalCardPaymentTool: () => ControlledExternalCardPaymentTool,
   ExternalCardConfirmationPendingError: () => ExternalCardConfirmationPendingError,
   Giro: () => Conto,
+  LinkCardDeniedError: () => LinkCardDeniedError,
+  LinkCardError: () => LinkCardError,
+  LinkCardExpiredError: () => LinkCardExpiredError,
+  LinkCardTimeoutError: () => LinkCardTimeoutError,
+  LinkWalletUnavailableError: () => LinkWalletUnavailableError,
   OrganizationPurchasesClient: () => OrganizationPurchasesClient,
   OrganizationRecurringPurchasesClient: () => OrganizationRecurringPurchasesClient,
   PurchasesClient: () => PurchasesClient,
@@ -190,18 +202,25 @@ var import_package_version2 = __toESM(require_package_version());
 var import_node_crypto = require("crypto");
 var TERMINAL = /* @__PURE__ */ new Set(["succeeded", "blocked", "failed", "cancelled"]);
 var isFinalPurchaseStatus = (status) => TERMINAL.has(status);
-async function* parseServerSentEvents(body) {
+async function* parseServerSentEvents(body, signal) {
   const reader = body.getReader();
+  const cancel = () => {
+    void reader.cancel().catch(() => {
+    });
+  };
+  signal?.addEventListener("abort", cancel, { once: true });
+  if (signal?.aborted) cancel();
   const decoder = new TextDecoder();
   let buffer = "";
   let frame = { data: [] };
   try {
     while (true) {
       const { value, done } = await reader.read();
-      if (done) break;
+      if (done || signal?.aborted) break;
       buffer += decoder.decode(value, { stream: true });
       let newline;
       while ((newline = buffer.search(/\r?\n/)) >= 0) {
+        if (signal?.aborted) return;
         const line = buffer.slice(0, newline);
         buffer = buffer.slice(newline + (buffer[newline] === "\r" ? 2 : 1));
         if (line === "") {
@@ -220,20 +239,30 @@ async function* parseServerSentEvents(body) {
       }
     }
   } finally {
+    signal?.removeEventListener("abort", cancel);
+    await reader.cancel().catch(() => {
+    });
     reader.releaseLock();
   }
 }
 var sleep = (ms, signal) => new Promise((resolve) => {
-  const timer = setTimeout(resolve, ms);
-  signal?.addEventListener(
-    "abort",
-    () => {
-      clearTimeout(timer);
-      resolve();
-    },
-    { once: true }
-  );
+  if (signal?.aborted) return resolve();
+  const finish = () => {
+    clearTimeout(timer);
+    signal?.removeEventListener("abort", finish);
+    resolve();
+  };
+  const timer = setTimeout(finish, ms);
+  signal?.addEventListener("abort", finish, { once: true });
 });
+function watchRead(pending, signal) {
+  return new Promise((resolve, reject) => {
+    const abort = () => reject(new DOMException("Watch stopped", "AbortError"));
+    signal.addEventListener("abort", abort, { once: true });
+    if (signal.aborted) abort();
+    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);
@@ -372,82 +401,100 @@ var PurchasesClient = class {
     const path = `${__privateGet(this, _base2)}/${requirePurchaseId(id)}`;
     const mode = options.mode ?? "auto";
     const interval = Math.max(500, options.pollIntervalMs ?? 2e3);
-    const deadline = options.maxWaitMs ? Date.now() + options.maxWaitMs : Infinity;
-    let cursor = Math.max(0, options.after ?? 0);
-    let streaming = mode !== "poll";
-    const emit = (event) => {
-      if (event.version <= cursor && event.type !== "purchase.resync") return null;
-      cursor = Math.max(cursor, event.version);
-      return event;
-    };
-    while (!options.signal?.aborted && Date.now() < deadline) {
-      if (streaming) {
-        try {
-          const response = await __privateGet(this, _transport2).openStream(
-            `${path}/events/stream?after=${cursor}`,
-            { signal: options.signal, lastEventId: String(cursor) }
-          );
-          if (!response.body) throw new Error("streaming unavailable");
-          for await (const frame of parseServerSentEvents(response.body)) {
-            if (frame.event === "end") return;
-            if (frame.event === "error") break;
-            if (frame.event === "resync") {
-              const purchase = JSON.parse(frame.data);
-              const event2 = {
-                id: `resync:${purchase.version}`,
-                purchaseId: purchase.id,
-                version: purchase.version,
-                type: "purchase.resync",
-                createdAt: purchase.updatedAt,
-                data: purchase
-              };
-              cursor = purchase.version;
-              yield event2;
-              if (isFinalPurchaseStatus(purchase.status)) return;
+    if (options.maxWaitMs !== void 0 && (!Number.isFinite(options.maxWaitMs) || options.maxWaitMs < 0 || options.maxWaitMs > 2147483647))
+      throw new TypeError("maxWaitMs must be between 0 and 2147483647");
+    if (options.signal?.aborted || options.maxWaitMs === 0) return;
+    const controller = new AbortController();
+    const signal = controller.signal;
+    const abort = () => controller.abort();
+    options.signal?.addEventListener("abort", abort, { once: true });
+    const timeout = options.maxWaitMs === void 0 ? void 0 : setTimeout(abort, options.maxWaitMs);
+    try {
+      let cursor = Math.max(0, options.after ?? 0);
+      let streaming = mode !== "poll";
+      const emit = (event) => {
+        if (event.version <= cursor && event.type !== "purchase.resync") return null;
+        cursor = Math.max(cursor, event.version);
+        return event;
+      };
+      while (!signal.aborted) {
+        if (streaming) {
+          try {
+            const response = await __privateGet(this, _transport2).openStream(
+              `${path}/events/stream?after=${cursor}`,
+              { signal, lastEventId: String(cursor) }
+            );
+            if (!response.body) throw new Error("streaming unavailable");
+            for await (const frame of parseServerSentEvents(response.body, signal)) {
+              if (frame.event === "end") return;
+              if (frame.event === "error") break;
+              if (frame.event === "resync") {
+                const purchase = JSON.parse(frame.data);
+                const event2 = {
+                  id: `resync:${purchase.version}`,
+                  purchaseId: purchase.id,
+                  version: purchase.version,
+                  type: "purchase.resync",
+                  createdAt: purchase.updatedAt,
+                  data: purchase
+                };
+                cursor = purchase.version;
+                yield event2;
+                if (isFinalPurchaseStatus(purchase.status)) return;
+                continue;
+              }
+              if (!frame.data) continue;
+              const event = emit(JSON.parse(frame.data));
+              if (!event) continue;
+              yield event;
+              if (isFinalPurchaseStatus(event.data.status)) return;
+            }
+            await sleep(interval, signal);
+            continue;
+          } catch (error) {
+            if (signal.aborted) return;
+            if (isClientError(error)) throw error;
+            if (mode === "stream") {
+              await sleep(interval, signal);
               continue;
             }
-            if (!frame.data) continue;
-            const event = emit(JSON.parse(frame.data));
-            if (!event) continue;
-            yield event;
-            if (isFinalPurchaseStatus(event.data.status)) return;
+            streaming = false;
           }
-          continue;
+        }
+        let page;
+        try {
+          page = await watchRead(this.events(id, { after: cursor, limit: 100 }), signal);
         } catch (error) {
-          if (options.signal?.aborted) return;
-          if (isClientError(error)) throw error;
-          if (mode === "stream") {
-            await sleep(interval, options.signal);
-            continue;
-          }
-          streaming = false;
+          if (codeOf(error) !== "CURSOR_INVALID") throw error;
+          const purchase = await watchRead(this.get(id), signal);
+          cursor = purchase.version;
+          yield {
+            id: `resync:${purchase.version}`,
+            purchaseId: purchase.id,
+            version: purchase.version,
+            type: "purchase.resync",
+            createdAt: purchase.updatedAt,
+            data: purchase
+          };
+          if (isFinalPurchaseStatus(purchase.status)) return;
+          continue;
         }
+        if (signal.aborted) return;
+        for (const item of page.items) {
+          if (signal.aborted) return;
+          const event = emit(item);
+          if (!event) continue;
+          yield event;
+          if (isFinalPurchaseStatus(event.data.status)) return;
+        }
+        if (!page.hasMore) await sleep(interval, signal);
       }
-      let page;
-      try {
-        page = await this.events(id, { after: cursor, limit: 100 });
-      } catch (error) {
-        if (codeOf(error) !== "CURSOR_INVALID") throw error;
-        const purchase = await this.get(id);
-        cursor = purchase.version;
-        yield {
-          id: `resync:${purchase.version}`,
-          purchaseId: purchase.id,
-          version: purchase.version,
-          type: "purchase.resync",
-          createdAt: purchase.updatedAt,
-          data: purchase
-        };
-        if (isFinalPurchaseStatus(purchase.status)) return;
-        continue;
-      }
-      for (const item of page.items) {
-        const event = emit(item);
-        if (!event) continue;
-        yield event;
-        if (isFinalPurchaseStatus(event.data.status)) return;
-      }
-      if (!page.hasMore) await sleep(interval, options.signal);
+    } catch (error) {
+      if (!signal.aborted) throw error;
+    } finally {
+      if (timeout !== void 0) clearTimeout(timeout);
+      options.signal?.removeEventListener("abort", abort);
+      controller.abort();
     }
   }
 };
@@ -487,13 +534,80 @@ var _client3;
 var AdminPurchasingClient = class {
   constructor(client) {
     __privateAdd(this, _client3);
+    /** Inspect or revoke buyer-approved allowances. Grants remain on the buyer's hosted page. */
+    this.allowances = {
+      /** Returns up to 50 allowances for this buyer, newest first. */
+      list: (params) => __privateGet(this, _client3).request(
+        "GET",
+        `/api/purchasing/allowances?${new URLSearchParams({ buyerId: params.buyerId })}`
+      ),
+      get: (id) => __privateGet(this, _client3).request("GET", `/api/purchasing/allowances/${enc(id)}`),
+      /** Stops future credential release; does not undo payments already submitted. */
+      revoke: (id) => __privateGet(this, _client3).request(
+        "POST",
+        `/api/purchasing/allowances/${enc(id)}/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)}`),
       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: (id) => __privateGet(this, _client3).request("POST", `/api/purchasing/buyers/${enc(id)}/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(
+        "PUT",
+        `/api/purchasing/buyers/${enc(id)}/company-card`,
+        input
+      ),
+      /** The buyer stops paying with your company card. */
+      removeCompanyCard: (id) => __privateGet(this, _client3).request(
+        "DELETE",
+        `/api/purchasing/buyers/${enc(id)}/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(
+        "PUT",
+        `/api/purchasing/buyers/${enc(id)}/context`,
+        context
+      ),
+      /** The snapshot Conto holds, with context null when nothing was pushed. */
+      getKitchenContext: (id) => __privateGet(this, _client3).request(
+        "GET",
+        `/api/purchasing/buyers/${enc(id)}/context`
+      ),
+      clearKitchenContext: (id) => __privateGet(this, _client3).request(
+        "DELETE",
+        `/api/purchasing/buyers/${enc(id)}/context`
+      )
+    };
+    /** Cards your organization pays its buyers' purchases with. Test cards only for now. */
+    this.companyCards = {
+      create: (input) => __privateGet(this, _client3).request("POST", "/api/purchasing/company-cards", input),
+      list: () => __privateGet(this, _client3).request(
+        "GET",
+        "/api/purchasing/company-cards"
+      ),
+      get: (id) => __privateGet(this, _client3).request("GET", `/api/purchasing/company-cards/${enc(id)}`),
+      /** Changes the card's own caps. Each buyer's limits stay as they are. */
+      update: (id, input) => __privateGet(this, _client3).request(
+        "PATCH",
+        `/api/purchasing/company-cards/${enc(id)}`,
+        input
+      ),
+      /** No buyer can start or pay a purchase with the card after this. */
+      remove: (id) => __privateGet(this, _client3).request(
+        "DELETE",
+        `/api/purchasing/company-cards/${enc(id)}`
+      )
     };
     this.paymentMethods = {
       /** A single-use link to the hosted setup page: limits, card and delegation. */
@@ -524,11 +638,8 @@ var AdminPurchasingClient = class {
     };
     this.settings = {
       get: () => __privateGet(this, _client3).request("GET", "/api/purchasing/settings"),
-      update: (input) => __privateGet(this, _client3).request(
-        "PUT",
-        "/api/purchasing/settings",
-        input
-      )
+      /** Changes only the fields you pass. */
+      update: (input) => __privateGet(this, _client3).request("PUT", "/api/purchasing/settings", input)
     };
     __privateSet(this, _client3, client);
     this.purchases = new OrganizationPurchasesClient(client);
@@ -1545,6 +1656,43 @@ var CheckoutApprovalTimeoutError = class extends ContoError {
     this.checkpoint = checkpoint;
   }
 };
+var LinkCardError = class extends ContoError {
+  constructor(input) {
+    super(input.message, {
+      code: input.code,
+      status: 0,
+      retryGuidance: input.retryGuidance ?? (input.holdReleased ? "Start a new purchase with a new idempotency key if the buyer still wants it." : "Call checkout.cancel(error.checkpoint.id) to release the held spend.")
+    });
+    this.name = "LinkCardError";
+    this.checkpoint = input.checkpoint;
+    if (input.linkRequestId) this.linkRequestId = input.linkRequestId;
+    this.holdReleased = input.holdReleased;
+  }
+};
+var LinkCardDeniedError = class extends LinkCardError {
+  constructor(input) {
+    super(input);
+    this.name = "LinkCardDeniedError";
+  }
+};
+var LinkCardExpiredError = class extends LinkCardError {
+  constructor(input) {
+    super(input);
+    this.name = "LinkCardExpiredError";
+  }
+};
+var LinkCardTimeoutError = class extends LinkCardError {
+  constructor(input) {
+    super(input);
+    this.name = "LinkCardTimeoutError";
+  }
+};
+var LinkWalletUnavailableError = class extends LinkCardError {
+  constructor(input) {
+    super(input);
+    this.name = "LinkWalletUnavailableError";
+  }
+};
 function generatedIdempotencyKey(prefix) {
   return `${prefix}_${(0, import_node_crypto3.randomUUID)()}`;
 }
@@ -2665,9 +2813,179 @@ function sleep2(ms, signal) {
     signal?.addEventListener("abort", onAbort, { once: true });
   });
 }
-var _client4;
+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 INSPECT = /* @__PURE__ */ Symbol.for("nodejs.util.inspect.custom");
+function assertPaymentReference(reference) {
+  if (reference === void 0) return;
+  if (reference === null || typeof reference !== "object" || reference.provider !== "LINK" || typeof reference.id !== "string" || !LINK_REQUEST_ID.test(reference.id) || /\d{12,}/.test(reference.id)) {
+    throw checkoutError(
+      'paymentReference must be { provider: "LINK", id } with a Link spend request id',
+      "INVALID_PAYMENT_REFERENCE"
+    );
+  }
+}
+function linkRequestWaiting(request) {
+  return LINK_WAITING_STATUSES.has(request.status) || // 3D Secure: Link continues on its own once the person finishes it.
+  request.status === "requires_action" && request.actionResolution === "auto_resume";
+}
+function usd(amountMinor) {
+  return `$${(amountMinor / 100).toFixed(2)}`;
+}
+function clip(value, maxLength) {
+  const single = value.replace(/\s+/g, " ").trim();
+  return single.length > maxLength ? `${single.slice(0, maxLength - 3).trimEnd()}...` : single;
+}
+function linkCardContext(checkpoint, merchantHost) {
+  const items = checkpoint.cart.lineItems;
+  const listed = items.slice(0, 5).map((item) => `${item.quantity} x ${clip(item.name, 80)}`).join(", ");
+  const more = items.length > 5 ? ` and ${items.length - 5} more` : "";
+  return `Your agent asked for a card to buy ${clip(listed, 300)}${more} from ${clip(checkpoint.merchant.name, 120)} (${merchantHost}) for ${usd(checkpoint.amountMinor)}. Purpose: ${clip(checkpoint.purpose, 200)}. Conto checked this purchase against your rules and approved it. The card is limited to this amount. Approve only if you expect this purchase.`;
+}
+function linkCardRequest(checkpoint) {
+  if (!checkpoint.merchant.checkoutUrl) {
+    throw checkoutError("The checkpoint has no checkout URL", "INVALID_CHECKOUT_CHECKPOINT");
+  }
+  const merchantUrl = new URL(checkpoint.merchant.checkoutUrl);
+  return {
+    amountMinor: checkpoint.amountMinor,
+    currency: "USD",
+    merchantName: checkpoint.merchant.name,
+    merchantUrl: merchantUrl.origin,
+    context: linkCardContext(checkpoint, merchantUrl.hostname),
+    lineItems: checkpoint.cart.lineItems.map((item) => ({
+      name: item.name,
+      quantity: item.quantity,
+      unitAmountMinor: item.unitAmountMinor
+    })),
+    // Conto approved amountMinor, so the Link total is exactly that.
+    totals: [
+      ...checkpoint.cart.totals.filter((total) => total.type !== "total").map((total) => ({ type: total.type, label: total.label, amountMinor: total.amountMinor })),
+      { type: "total", label: "Total", amountMinor: checkpoint.amountMinor }
+    ],
+    // One checkpoint and amount is one Link request, so a retry resumes it.
+    idempotencyKey: `conto_${(0, import_node_crypto3.createHash)("sha256").update(`${checkpoint.id}:${checkpoint.amountMinor}`).digest("hex").slice(0, 40)}`,
+    metadata: { conto_checkpoint: checkpoint.id }
+  };
+}
+function protectLinkCard(card) {
+  const safe = Object.freeze({
+    last4: card.number.slice(-4),
+    ...card.brand ? { brand: card.brand } : {},
+    expMonth: card.expMonth,
+    expYear: card.expYear,
+    ...card.validUntil ? { validUntil: card.validUntil } : {},
+    redacted: true
+  });
+  const result = {
+    number: card.number,
+    securityValue: card.securityValue,
+    expMonth: card.expMonth,
+    expYear: card.expYear,
+    ...card.validUntil ? { validUntil: card.validUntil } : {},
+    last4: card.number.slice(-4),
+    ...card.brand ? { brand: card.brand } : {}
+  };
+  Object.defineProperty(result, "toJSON", { value: () => safe, enumerable: false });
+  Object.defineProperty(result, INSPECT, { value: () => safe, enumerable: false });
+  return Object.freeze(result);
+}
+function errorCode(error) {
+  return error && typeof error === "object" && typeof error.code === "string" ? error.code : void 0;
+}
+function errorReason(error) {
+  return error && typeof error === "object" && typeof error.reason === "string" ? error.reason : void 0;
+}
+function linkFailure(error, signal) {
+  if (error instanceof LinkCardError) {
+    return {
+      kind: error.constructor,
+      code: error.code,
+      message: error.message
+    };
+  }
+  if (errorCode(error) === "LINK_WALLET_UNAVAILABLE") {
+    return {
+      kind: LinkWalletUnavailableError,
+      code: "LINK_WALLET_UNAVAILABLE",
+      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".'
+    };
+  }
+  if (signal?.aborted || errorReason(error) === "aborted") {
+    return {
+      kind: LinkCardError,
+      code: "LINK_CARD_ABORTED",
+      message: "The Link card request was stopped."
+    };
+  }
+  return {
+    kind: LinkCardError,
+    code: "LINK_CARD_FAILED",
+    message: "The Link card request failed."
+  };
+}
+function closedLinkFailure(request) {
+  switch (request.status) {
+    case "denied":
+      return {
+        kind: LinkCardDeniedError,
+        code: "LINK_CARD_DENIED",
+        message: "The person declined the Link card request.",
+        linkClosed: true
+      };
+    case "canceled":
+      return {
+        kind: LinkCardDeniedError,
+        code: "LINK_CARD_DENIED",
+        message: "The Link card request was cancelled in Link.",
+        linkClosed: true
+      };
+    case "expired":
+      return {
+        kind: LinkCardExpiredError,
+        code: "LINK_CARD_EXPIRED",
+        message: "The Link card request expired before the person approved it.",
+        linkClosed: true
+      };
+    case "requires_action":
+      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."
+      };
+    default:
+      return {
+        kind: LinkCardError,
+        code: "LINK_CARD_FAILED",
+        message: "Link did not issue a card for this request.",
+        linkClosed: LINK_CLOSED_STATUSES.has(request.status)
+      };
+  }
+}
+async function closeLinkRequest(wallet, id) {
+  try {
+    await wallet.cancel(id);
+    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);
+  }
+}
+function linkCreatedNothing(error) {
+  return errorCode(error) === "LINK_WALLET_UNAVAILABLE" || errorReason(error) === "invalid_input";
+}
+var LinkFailureSignal = class extends Error {
+  constructor(failure) {
+    super(failure.message);
+    this.failure = failure;
+  }
+};
+var _client4, _CheckoutClient_instances, linkCardFor_fn;
 var CheckoutClient = class {
   constructor(client) {
+    __privateAdd(this, _CheckoutClient_instances);
     __privateAdd(this, _client4);
     __privateSet(this, _client4, client);
   }
@@ -2746,8 +3064,16 @@ var CheckoutClient = class {
     if (!Number.isSafeInteger(input.amountMinor) || input.amountMinor <= 0) {
       throw checkoutError("amountMinor must be a positive integer number of cents");
     }
+    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."
+        });
+      }
       try {
         await this.cancel(checkpoint.id);
       } catch (error) {
@@ -2777,7 +3103,15 @@ var CheckoutClient = class {
         {
           amountMinor: input.amountMinor,
           currency: "USD",
-          ...input.pageUrl ? { pageUrl: input.pageUrl } : {}
+          ...input.lineItems !== void 0 || input.totals !== void 0 ? {
+            cart: checkpointCart(
+              input.amountMinor,
+              input.lineItems ?? current.cart.lineItems,
+              input.totals ?? current.cart.totals
+            )
+          } : {},
+          ...input.pageUrl ? { pageUrl: input.pageUrl } : {},
+          ...input.paymentReference ? { paymentReference: { provider: "LINK", id: input.paymentReference.id } } : {}
         },
         { idempotent: true }
       );
@@ -2792,12 +3126,14 @@ var CheckoutClient = class {
   }
   /** Report what happened after a confirmed checkpoint. Safe to repeat with the same outcome. */
   async reportOutcome(checkpointId, input) {
+    assertPaymentReference(input.paymentReference);
     const result = await __privateGet(this, _client4).request(
       "POST",
       `/api/sdk/checkout-checkpoints/${encodeURIComponent(checkpointId)}/outcome`,
       {
         outcome: input.outcome,
-        ...input.reference ? { reference: input.reference } : {}
+        ...input.reference ? { reference: input.reference } : {},
+        ...input.paymentReference ? { paymentReference: { provider: "LINK", id: input.paymentReference.id } } : {}
       },
       { idempotent: true }
     );
@@ -2823,8 +3159,189 @@ var CheckoutClient = class {
     );
     return result.checkpoint;
   }
+  /**
+   * Get a Stripe Link card for one purchase, issued only after Conto approves
+   * it. Call this at the payment step, once the final total with shipping and
+   * tax is known.
+   *
+   * 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 their Link app.
+   * 3. The card is returned. It never reaches Conto.
+   *
+   * Then fill in the card, call confirm(result.checkpoint, { amountMinor,
+   * paymentReference: result.paymentReference }) right before paying, pay only
+   * if it resolves, and report the outcome. If the final total differs, call
+   * replaceLinkCard() instead of confirming.
+   *
+   * A Conto denial throws before Link is called. When Link declines, expires,
+   * times out, or is unavailable, this cancels the checkpoint to release the
+   * 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.
+   */
+  async getLinkCard(input) {
+    const { wallet, ownerApprovalTimeoutMs, linkApprovalTimeoutMs, signal, ...beginInput } = input;
+    if (!wallet || typeof wallet.createCardRequest !== "function") {
+      throw checkoutError("wallet must be a LinkWallet, such as linkCliWallet()");
+    }
+    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 } : {}
+      });
+    }
+    return __privateMethod(this, _CheckoutClient_instances, linkCardFor_fn).call(this, checkpoint, wallet, linkApprovalTimeoutMs, signal);
+  }
+  /**
+   * 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.
+   */
+  async replaceLinkCard(previous, input) {
+    const { wallet, amountMinor, ownerApprovalTimeoutMs, linkApprovalTimeoutMs, signal } = input;
+    if (!Number.isSafeInteger(amountMinor) || amountMinor <= 0) {
+      throw checkoutError("amountMinor must be a positive integer number of cents");
+    }
+    if (amountMinor === previous.checkpoint.amountMinor) return previous;
+    const old = previous.checkpoint;
+    if (!await closeLinkRequest(wallet, previous.linkRequestId)) {
+      throw new LinkCardError({
+        message: "Conto could not cancel the earlier Link card. Nothing changed. Do not pay.",
+        code: "LINK_CARD_NOT_CANCELLED",
+        checkpoint: old,
+        linkRequestId: previous.linkRequestId,
+        holdReleased: false,
+        retryGuidance: "Try replaceLinkCard again."
+      });
+    }
+    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;
+    }
+    let checkpoint = await this.begin({
+      idempotencyKey: `${old.idempotencyKey.slice(0, 200)}:final-${amountMinor}`,
+      merchant: {
+        id: old.merchant.id,
+        name: old.merchant.name,
+        checkoutUrl: old.merchant.checkoutUrl ?? ""
+      },
+      amountMinor,
+      purpose: old.purpose,
+      ...old.category ? { category: old.category } : {},
+      checkoutMethod: "LINK",
+      lineItems: input.lineItems ?? old.cart.lineItems,
+      totals: input.totals
+    });
+    if (checkpoint.stage === "AWAITING_APPROVAL") {
+      checkpoint = await this.waitForApproval(checkpoint, {
+        ...ownerApprovalTimeoutMs !== void 0 ? { timeoutMs: ownerApprovalTimeoutMs } : {},
+        ...signal ? { signal } : {}
+      });
+    }
+    return __privateMethod(this, _CheckoutClient_instances, linkCardFor_fn).call(this, checkpoint, wallet, linkApprovalTimeoutMs, signal);
+  }
 };
 _client4 = new WeakMap();
+_CheckoutClient_instances = new WeakSet();
+linkCardFor_fn = async function(checkpoint, wallet, linkApprovalTimeoutMs = 10 * 6e4, signal) {
+  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"
+    );
+  }
+  const deadline = Date.now() + linkApprovalTimeoutMs;
+  const call = signal ? { signal } : {};
+  let linkRequestId;
+  let createStarted = false;
+  try {
+    const cardRequest = linkCardRequest(checkpoint);
+    createStarted = true;
+    let request = await wallet.createCardRequest(cardRequest, call);
+    if (!LINK_REQUEST_ID.test(request.id)) {
+      throw new LinkFailureSignal({
+        kind: LinkCardError,
+        code: "LINK_CARD_FAILED",
+        message: "The Link wallet returned an invalid request id."
+      });
+    }
+    linkRequestId = request.id;
+    if (request.amountMinor !== void 0 && request.amountMinor !== checkpoint.amountMinor) {
+      throw new LinkFailureSignal({
+        kind: LinkCardError,
+        code: "LINK_CARD_MISMATCH",
+        message: "Link returned a request for a different amount."
+      });
+    }
+    while (linkRequestWaiting(request)) {
+      const remainingSeconds = Math.floor((deadline - Date.now()) / 1e3);
+      if (remainingSeconds <= 0) {
+        throw new LinkFailureSignal({
+          kind: LinkCardTimeoutError,
+          code: "LINK_CARD_TIMEOUT",
+          message: "The person did not approve the Link card request in time."
+        });
+      }
+      const started = Date.now();
+      request = await wallet.waitForApproval(request.id, {
+        ...call,
+        timeoutSeconds: remainingSeconds
+      });
+      if (linkRequestWaiting(request) && Date.now() - started < 1e3) {
+        await sleep2(1e3, signal);
+      }
+    }
+    if (!LINK_APPROVED_STATUSES.has(request.status)) {
+      throw new LinkFailureSignal(closedLinkFailure(request));
+    }
+    const card = await wallet.retrieveCard(request.id, call);
+    return {
+      checkpoint,
+      card: protectLinkCard(card),
+      linkRequestId: request.id,
+      paymentReference: { provider: "LINK", id: request.id }
+    };
+  } catch (error) {
+    const failure = error instanceof LinkFailureSignal ? error.failure : linkFailure(error, signal);
+    if (!linkRequestId && createStarted && !linkCreatedNothing(error)) {
+      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.`,
+        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."
+      });
+    }
+    if (linkRequestId && !failure.linkClosed && !await closeLinkRequest(wallet, linkRequestId)) {
+      throw new LinkCardError({
+        message: `${failure.message} Conto could not cancel the Link request, so the held spend stays in place. Do not pay.`,
+        code: "LINK_CARD_NOT_CANCELLED",
+        checkpoint,
+        linkRequestId,
+        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)."
+      });
+    }
+    const holdReleased = await this.cancel(checkpoint.id).then(
+      () => 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.`,
+      code: failure.code,
+      checkpoint,
+      ...linkRequestId ? { linkRequestId } : {},
+      holdReleased
+    });
+  }
+};
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   AdminPurchasingClient,
@@ -2845,6 +3362,11 @@ _client4 = new WeakMap();
   ControlledExternalCardPaymentTool,
   ExternalCardConfirmationPendingError,
   Giro,
+  LinkCardDeniedError,
+  LinkCardError,
+  LinkCardExpiredError,
+  LinkCardTimeoutError,
+  LinkWalletUnavailableError,
   OrganizationPurchasesClient,
   OrganizationRecurringPurchasesClient,
   PurchasesClient,