@conto_finance/sdk 0.8.0 → 0.8.1

package/dist/index.mjs

@@ -22,7 +22,7 @@ var require_package = __commonJS({
   "package.json"(exports, module) {
     module.exports = {
       name: "@conto_finance/sdk",
-      version: "0.8.0",
+      version: "0.8.1",
       description: "Conto SDK for AI agent payment authorization",
       main: "./dist/index.js",
       module: "./dist/index.mjs",
@@ -1775,7 +1775,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;
@@ -2987,6 +2993,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 }]
@@ -3026,6 +3038,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;
@@ -3107,6 +3126,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 {
@@ -3122,6 +3149,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,
@@ -3162,7 +3207,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 {
@@ -3173,13 +3218,15 @@ function closedLinkFailure(request) {
       };
   }
 }
-async function closeLinkRequest(wallet, id2) {
+async function closeLinkRequest(wallet, id2, onRefused) {
   try {
     await wallet.cancel(id2);
     return true;
-  } catch {
-    const status = await wallet.waitForApproval(id2, { 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) {
@@ -3187,6 +3234,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";
 }
@@ -3213,7 +3319,7 @@ function notifyLinkApproval(callback, event) {
   } catch {
   }
 }
-var _client4, _CheckoutClient_instances, recordLinkRequest_fn, linkCardFor_fn;
+var _client4, _CheckoutClient_instances, recordLinkRequest_fn, waitForLinkOwner_fn, linkCardFor_fn;
 var CheckoutClient = class {
   constructor(client) {
     __privateAdd(this, _CheckoutClient_instances);
@@ -3298,17 +3404,37 @@ var CheckoutClient = class {
     assertPaymentReference(input.paymentReference);
     let current = checkpoint;
     if (input.amountMinor !== checkpoint.amountMinor) {
-      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,
-          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({
@@ -3372,7 +3498,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(
@@ -3414,9 +3542,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 while Conto's approval is open. Once the stage is OUTCOME_UNKNOWN,
-   * a retry throws CHECKOUT_CHECKPOINT_NOT_APPROVED: cancel the Link request, then
-   * the checkpoint.
+   * Link request while Conto's approval is open. If its approval ended with the
+   * request open, a retry throws CHECKOUT_CHECKPOINT_NOT_APPROVED. Cancel the Link
+   * request, then the checkpoint. Once a confirm has started, a retry throws
+   * LINK_CARD_NOT_ISSUED. Do not cancel the Link request while a payment may be in
+   * flight. Follow error.retryGuidance, which depends on the stage.
    */
   async getLinkCard(input) {
     const {
@@ -3433,10 +3563,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,
@@ -3448,7 +3575,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 {
@@ -3463,23 +3594,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}`,
@@ -3496,10 +3677,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,
@@ -3528,19 +3706,56 @@ recordLinkRequest_fn = async function(checkpoint, linkRequestId) {
     });
   }
 };
+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;
@@ -3553,6 +3768,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,
@@ -3561,6 +3777,13 @@ linkCardFor_fn = async function(checkpoint, wallet, options) {
       });
     }
     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;
@@ -3599,37 +3822,74 @@ 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: 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: 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 (createStarted && !createAnswered && !linkCreatedNothing(error)) {
+      const blockedBy = !recordedRequestId && !alreadyReleased && failure.retryGuidance;
       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} 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,
-        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,
+        ...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."
       });
     }
-    if (linkRequestId && !failure.linkClosed && !await closeLinkRequest(wallet, linkRequestId)) {
+    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: `${failure.message} Conto could not cancel the Link request, so the held spend stays in place. Do not pay.`,
+        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,
-        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,
+        // 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)
       });
     }
-    const holdReleased = await this.cancel(checkpoint.id).then(
-      () => true,
+    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 } : {}
     });
   }
 };

package/dist/link-wallet.d.mts

@@ -49,6 +49,8 @@ interface LinkSpendRequest {
     actionResolution?: string;
     /** Set with requires_action when Link gives the person a page to finish the step. */
     actionUrl?: string;
+    /** The metadata sent with the request, when Link returns it. */
+    metadata?: Record<string, string>;
 }
 /**
  * The single-use virtual card Link issued for an approved request. Live card
@@ -85,7 +87,10 @@ interface LinkWallet {
     waitForApproval(id: string, options?: LinkWaitOptions): Promise<LinkSpendRequest>;
     /** Read the card of an approved request. */
     retrieveCard(id: string, options?: LinkCallOptions): Promise<LinkCardCredential>;
-    /** Cancel a request that is created, pending approval, or approved. */
+    /**
+     * Cancel a request, or confirm Link already closed it. Throws when its card
+     * may still work or may have been used, so keep the hold.
+     */
     cancel(id: string, options?: LinkCallOptions): Promise<void>;
 }
 type LinkWalletErrorReason = 'not_installed' | 'not_logged_in' | 'not_found' | 'not_approved' | 'invalid_input' | 'invalid_response' | 'timed_out' | 'aborted' | 'cli_failed';
@@ -98,7 +103,11 @@ declare class LinkWalletError extends Error {
     readonly reason: LinkWalletErrorReason;
     /** The error code link-cli reported, when it reported a safe one. */
     readonly linkCode?: string;
-    constructor(reason: LinkWalletErrorReason, message: string, linkCode?: string);
+    /** The open Link request with the same details that blocks this one. */
+    readonly duplicateOf?: string;
+    /** The checkpoint Link has on that request, as Link reported it. */
+    readonly duplicateCheckpoint?: string;
+    constructor(reason: LinkWalletErrorReason, message: string, linkCode?: string, duplicateOf?: string, duplicateCheckpoint?: string);
 }
 interface LinkCliWalletOptions {
     /** The link-cli executable. Defaults to `link-cli` on PATH. */

package/dist/link-wallet.d.ts

@@ -49,6 +49,8 @@ interface LinkSpendRequest {
     actionResolution?: string;
     /** Set with requires_action when Link gives the person a page to finish the step. */
     actionUrl?: string;
+    /** The metadata sent with the request, when Link returns it. */
+    metadata?: Record<string, string>;
 }
 /**
  * The single-use virtual card Link issued for an approved request. Live card
@@ -85,7 +87,10 @@ interface LinkWallet {
     waitForApproval(id: string, options?: LinkWaitOptions): Promise<LinkSpendRequest>;
     /** Read the card of an approved request. */
     retrieveCard(id: string, options?: LinkCallOptions): Promise<LinkCardCredential>;
-    /** Cancel a request that is created, pending approval, or approved. */
+    /**
+     * Cancel a request, or confirm Link already closed it. Throws when its card
+     * may still work or may have been used, so keep the hold.
+     */
     cancel(id: string, options?: LinkCallOptions): Promise<void>;
 }
 type LinkWalletErrorReason = 'not_installed' | 'not_logged_in' | 'not_found' | 'not_approved' | 'invalid_input' | 'invalid_response' | 'timed_out' | 'aborted' | 'cli_failed';
@@ -98,7 +103,11 @@ declare class LinkWalletError extends Error {
     readonly reason: LinkWalletErrorReason;
     /** The error code link-cli reported, when it reported a safe one. */
     readonly linkCode?: string;
-    constructor(reason: LinkWalletErrorReason, message: string, linkCode?: string);
+    /** The open Link request with the same details that blocks this one. */
+    readonly duplicateOf?: string;
+    /** The checkpoint Link has on that request, as Link reported it. */
+    readonly duplicateCheckpoint?: string;
+    constructor(reason: LinkWalletErrorReason, message: string, linkCode?: string, duplicateOf?: string, duplicateCheckpoint?: string);
 }
 interface LinkCliWalletOptions {
     /** The link-cli executable. Defaults to `link-cli` on PATH. */