@conto_finance/sdk 0.6.0-beta.1 → 0.6.0-beta.2

package/dist/index.js

@@ -46,7 +46,7 @@ var require_package = __commonJS({
   "package.json"(exports2, module2) {
     module2.exports = {
       name: "@conto_finance/sdk",
-      version: "0.6.0-beta.1",
+      version: "0.6.0-beta.2",
       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/link.test.mjs test/link-testing.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/link.test.mjs test/link-testing.test.mjs test/checkout.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"
@@ -159,6 +159,7 @@ __export(index_exports, {
   BrowserActionFinalizationPendingError: () => BrowserActionFinalizationPendingError,
   BrowserCheckoutTargetVerificationError: () => BrowserCheckoutTargetVerificationError,
   CardsClient: () => CardsClient,
+  CheckoutClient: () => CheckoutClient,
   ConnectedCardsClient: () => ConnectedCardsClient,
   Conto: () => Conto,
   ContoAdmin: () => ContoAdmin,
@@ -696,8 +697,11 @@ var AdminCardsClient = class {
     return this.client.request("GET", `/api/external-cards/requests${suffix ? `?${suffix}` : ""}`);
   }
   /**
-   * Resolve a claimed execution after checking the customer's processor or
-   * receipt. Resolving NOT_EXECUTED releases the reserved policy amount.
+   * @deprecated Resolution requires a signed-in user. SDK admin keys and
+   * organization API keys receive HTTP 403 INSUFFICIENT_PERMISSIONS from this
+   * endpoint. Have a signed-in organization owner or admin review the processor
+   * evidence and resolve the request through Conto's authenticated interface.
+   * Retained for source compatibility; this method does not bypass that restriction.
    */
   async resolveRequest(requestId, input) {
     return this.client.request(
@@ -1188,6 +1192,7 @@ var Conto = class {
     assertSecureBaseUrl(this.baseUrl);
     this.timeout = config.timeout || 3e4;
     this.link = new LinkClient(this, config.link);
+    this.checkout = new CheckoutClient(this);
     this.payments = new PaymentsClient(this);
     this.cards = new CardsClient(this);
     this.connectedCards = new ConnectedCardsClient(this);
@@ -2147,17 +2152,147 @@ var MppClient = class {
   }
 };
 var index_default = Conto;
-var _client, _defaults;
+function checkoutError(message, code = "INVALID_CHECKOUT_CHECKPOINT") {
+  return new ContoError(message, { code, status: 0 });
+}
+function checkpointCart(amountMinor, lineItems, totals) {
+  if (!Number.isSafeInteger(amountMinor) || amountMinor <= 0) {
+    throw checkoutError("amountMinor must be a positive integer number of cents");
+  }
+  if (!Array.isArray(lineItems) || lineItems.length === 0) {
+    throw checkoutError("Supply at least one line item");
+  }
+  return {
+    lineItems,
+    totals: totals ?? [{ type: "total", label: "Total", amountMinor }]
+  };
+}
+var _client;
+var CheckoutClient = class {
+  constructor(client) {
+    __privateAdd(this, _client);
+    __privateSet(this, _client, client);
+  }
+  /** First checkpoint. A ContoError means Conto did not approve: stop the checkout. */
+  async begin(input) {
+    const idempotencyKey = input.idempotencyKey?.trim();
+    if (!idempotencyKey || idempotencyKey.length < 8 || idempotencyKey.length > 255) {
+      throw checkoutError(
+        "idempotencyKey must contain 8 to 255 characters",
+        "INVALID_IDEMPOTENCY_KEY"
+      );
+    }
+    if (input.currency !== void 0 && input.currency !== "USD") {
+      throw checkoutError("Only USD checkouts are supported");
+    }
+    const result = await __privateGet(this, _client).request(
+      "POST",
+      "/api/sdk/checkout-checkpoints",
+      {
+        idempotencyKey,
+        merchant: input.merchant,
+        amountMinor: input.amountMinor,
+        currency: "USD",
+        purpose: input.purpose,
+        ...input.category ? { category: input.category } : {},
+        ...input.checkoutMethod ? { checkoutMethod: input.checkoutMethod } : {},
+        cart: checkpointCart(input.amountMinor, input.lineItems, input.totals)
+      },
+      { idempotent: true }
+    );
+    return result.checkpoint;
+  }
+  /**
+   * Second checkpoint, right before the payment is submitted. If the total
+   * changed since begin() (tax or shipping, for example), this cancels the
+   * approved checkpoint and starts a new one at the final total, so the agent's
+   * rules see the amount actually being paid. Pay only if this resolves.
+   */
+  async confirm(checkpoint, input) {
+    if (input.currency !== void 0 && input.currency !== "USD") {
+      throw checkoutError("Only USD checkouts are supported");
+    }
+    if (!Number.isSafeInteger(input.amountMinor) || input.amountMinor <= 0) {
+      throw checkoutError("amountMinor must be a positive integer number of cents");
+    }
+    let current = checkpoint;
+    if (input.amountMinor !== checkpoint.amountMinor) {
+      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);
+        if (!closed) throw error;
+      }
+      current = await this.begin({
+        idempotencyKey: `${checkpoint.idempotencyKey.slice(0, 200)}:final-${input.amountMinor}`,
+        merchant: {
+          id: checkpoint.merchant.id,
+          name: checkpoint.merchant.name,
+          checkoutUrl: checkpoint.merchant.checkoutUrl ?? ""
+        },
+        amountMinor: input.amountMinor,
+        purpose: checkpoint.purpose,
+        ...checkpoint.category ? { category: checkpoint.category } : {},
+        checkoutMethod: checkpoint.checkoutMethod,
+        lineItems: input.lineItems ?? checkpoint.cart.lineItems,
+        totals: input.totals
+      });
+    }
+    const result = await __privateGet(this, _client).request(
+      "POST",
+      `/api/sdk/checkout-checkpoints/${encodeURIComponent(current.id)}/confirm`,
+      {
+        amountMinor: input.amountMinor,
+        currency: "USD",
+        ...input.pageUrl ? { pageUrl: input.pageUrl } : {}
+      },
+      { idempotent: true }
+    );
+    return result.checkpoint;
+  }
+  /** Report what happened after a confirmed checkpoint. Safe to repeat with the same outcome. */
+  async reportOutcome(checkpointId, input) {
+    const result = await __privateGet(this, _client).request(
+      "POST",
+      `/api/sdk/checkout-checkpoints/${encodeURIComponent(checkpointId)}/outcome`,
+      {
+        outcome: input.outcome,
+        ...input.reference ? { reference: input.reference } : {}
+      },
+      { idempotent: true }
+    );
+    return result.checkpoint;
+  }
+  /** Cancel a checkpoint that was not confirmed and release its spend. */
+  async cancel(checkpointId) {
+    const result = await __privateGet(this, _client).request(
+      "POST",
+      `/api/sdk/checkout-checkpoints/${encodeURIComponent(checkpointId)}/cancel`,
+      {},
+      { idempotent: true }
+    );
+    return result.checkpoint;
+  }
+  async get(checkpointId) {
+    const result = await __privateGet(this, _client).request(
+      "GET",
+      `/api/sdk/checkout-checkpoints/${encodeURIComponent(checkpointId)}`
+    );
+    return result.checkpoint;
+  }
+};
+_client = new WeakMap();
+var _client2, _defaults;
 var LinkClient = class {
   constructor(client, defaults) {
-    __privateAdd(this, _client);
+    __privateAdd(this, _client2);
     __privateAdd(this, _defaults);
-    __privateSet(this, _client, client);
+    __privateSet(this, _client2, client);
     __privateSet(this, _defaults, defaults ? { ...defaults } : void 0);
   }
   /** Inspect the configured live path. This is not a payment authorization or provider connectivity test. */
   async setup(input = {}) {
-    return __privateGet(this, _client).getLinkSetup({
+    return __privateGet(this, _client2).getLinkSetup({
       connectionId: input.connectionId ?? __privateGet(this, _defaults)?.connectionId,
       paymentMethodId: input.paymentMethodId ?? __privateGet(this, _defaults)?.paymentMethodId,
       merchantId: input.merchantId
@@ -2165,7 +2300,7 @@ var LinkClient = class {
   }
   /** Read masked LIVE funding sources; never selects a source or initiates payment. */
   async paymentMethods(connectionId) {
-    return __privateGet(this, _client).listStripeLinkPaymentMethods(
+    return __privateGet(this, _client2).listStripeLinkPaymentMethods(
       this.identifier(connectionId ?? __privateGet(this, _defaults)?.connectionId, "connectionId"),
       { mode: "LIVE" }
     );
@@ -2210,7 +2345,7 @@ var LinkClient = class {
         }
       );
     }
-    const result = await __privateGet(this, _client).beginCommerceExecution({
+    const result = await __privateGet(this, _client2).beginCommerceExecution({
       executionMethod: "LINK_PAY_TOKEN",
       connectionId,
       paymentMethodId,
@@ -2237,25 +2372,25 @@ var LinkClient = class {
    */
   async resume(executionId) {
     const id = this.identifier(executionId, "executionId");
-    const current = await __privateGet(this, _client).getCommerceExecution(id);
+    const current = await __privateGet(this, _client2).getCommerceExecution(id);
     this.assertLinkExecution(current);
     if (["AUTHORIZING", "AWAITING_APPROVAL", "ACTION_REQUIRED"].includes(current.execution.status)) {
-      return this.executeIfReady(await __privateGet(this, _client).refreshCommerceExecution(id));
+      return this.executeIfReady(await __privateGet(this, _client2).refreshCommerceExecution(id));
     }
     return this.executeIfReady(current);
   }
   /** Observe and reconcile provider state. This method never submits a payment. */
   async status(executionId) {
     const id = this.identifier(executionId, "executionId");
-    this.assertLinkExecution(await __privateGet(this, _client).getCommerceExecution(id));
-    return this.result(await __privateGet(this, _client).refreshCommerceExecution(id));
+    this.assertLinkExecution(await __privateGet(this, _client2).getCommerceExecution(id));
+    return this.result(await __privateGet(this, _client2).refreshCommerceExecution(id));
   }
   /** Request cancellation of this existing Link payment; never retried automatically. */
   async cancel(executionId) {
     const id = this.identifier(executionId, "executionId");
-    this.assertLinkExecution(await __privateGet(this, _client).getCommerceExecution(id));
+    this.assertLinkExecution(await __privateGet(this, _client2).getCommerceExecution(id));
     try {
-      return this.result(await __privateGet(this, _client).cancelCommerceExecution(id));
+      return this.result(await __privateGet(this, _client2).cancelCommerceExecution(id));
     } catch (error) {
       throw new LinkPaymentExecutionError(id, error);
     }
@@ -2285,7 +2420,7 @@ var LinkClient = class {
     this.assertLinkExecution(result);
     if (result.execution.status !== "READY") return this.result(result);
     try {
-      return this.result(await __privateGet(this, _client).executeCommerceExecution(result.execution.id));
+      return this.result(await __privateGet(this, _client2).executeCommerceExecution(result.execution.id));
     } catch (error) {
       throw new LinkPaymentExecutionError(result.execution.id, error);
     }
@@ -2315,13 +2450,14 @@ var LinkClient = class {
     };
   }
 };
-_client = new WeakMap();
+_client2 = new WeakMap();
 _defaults = new WeakMap();
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   BrowserActionFinalizationPendingError,
   BrowserCheckoutTargetVerificationError,
   CardsClient,
+  CheckoutClient,
   ConnectedCardsClient,
   Conto,
   ContoAdmin,

package/dist/index.mjs

@@ -17,7 +17,7 @@ var require_package = __commonJS({
   "package.json"(exports, module) {
     module.exports = {
       name: "@conto_finance/sdk",
-      version: "0.6.0-beta.1",
+      version: "0.6.0-beta.2",
       description: "Conto SDK for AI agent payment authorization",
       main: "./dist/index.js",
       module: "./dist/index.mjs",
@@ -64,7 +64,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/link.test.mjs test/link-testing.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/link.test.mjs test/link-testing.test.mjs test/checkout.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"
@@ -528,8 +528,11 @@ var AdminCardsClient = class {
     return this.client.request("GET", `/api/external-cards/requests${suffix ? `?${suffix}` : ""}`);
   }
   /**
-   * Resolve a claimed execution after checking the customer's processor or
-   * receipt. Resolving NOT_EXECUTED releases the reserved policy amount.
+   * @deprecated Resolution requires a signed-in user. SDK admin keys and
+   * organization API keys receive HTTP 403 INSUFFICIENT_PERMISSIONS from this
+   * endpoint. Have a signed-in organization owner or admin review the processor
+   * evidence and resolve the request through Conto's authenticated interface.
+   * Retained for source compatibility; this method does not bypass that restriction.
    */
   async resolveRequest(requestId, input) {
     return this.client.request(
@@ -1020,6 +1023,7 @@ var Conto = class {
     assertSecureBaseUrl(this.baseUrl);
     this.timeout = config.timeout || 3e4;
     this.link = new LinkClient(this, config.link);
+    this.checkout = new CheckoutClient(this);
     this.payments = new PaymentsClient(this);
     this.cards = new CardsClient(this);
     this.connectedCards = new ConnectedCardsClient(this);
@@ -1979,17 +1983,147 @@ var MppClient = class {
   }
 };
 var index_default = Conto;
-var _client, _defaults;
+function checkoutError(message, code = "INVALID_CHECKOUT_CHECKPOINT") {
+  return new ContoError(message, { code, status: 0 });
+}
+function checkpointCart(amountMinor, lineItems, totals) {
+  if (!Number.isSafeInteger(amountMinor) || amountMinor <= 0) {
+    throw checkoutError("amountMinor must be a positive integer number of cents");
+  }
+  if (!Array.isArray(lineItems) || lineItems.length === 0) {
+    throw checkoutError("Supply at least one line item");
+  }
+  return {
+    lineItems,
+    totals: totals ?? [{ type: "total", label: "Total", amountMinor }]
+  };
+}
+var _client;
+var CheckoutClient = class {
+  constructor(client) {
+    __privateAdd(this, _client);
+    __privateSet(this, _client, client);
+  }
+  /** First checkpoint. A ContoError means Conto did not approve: stop the checkout. */
+  async begin(input) {
+    const idempotencyKey = input.idempotencyKey?.trim();
+    if (!idempotencyKey || idempotencyKey.length < 8 || idempotencyKey.length > 255) {
+      throw checkoutError(
+        "idempotencyKey must contain 8 to 255 characters",
+        "INVALID_IDEMPOTENCY_KEY"
+      );
+    }
+    if (input.currency !== void 0 && input.currency !== "USD") {
+      throw checkoutError("Only USD checkouts are supported");
+    }
+    const result = await __privateGet(this, _client).request(
+      "POST",
+      "/api/sdk/checkout-checkpoints",
+      {
+        idempotencyKey,
+        merchant: input.merchant,
+        amountMinor: input.amountMinor,
+        currency: "USD",
+        purpose: input.purpose,
+        ...input.category ? { category: input.category } : {},
+        ...input.checkoutMethod ? { checkoutMethod: input.checkoutMethod } : {},
+        cart: checkpointCart(input.amountMinor, input.lineItems, input.totals)
+      },
+      { idempotent: true }
+    );
+    return result.checkpoint;
+  }
+  /**
+   * Second checkpoint, right before the payment is submitted. If the total
+   * changed since begin() (tax or shipping, for example), this cancels the
+   * approved checkpoint and starts a new one at the final total, so the agent's
+   * rules see the amount actually being paid. Pay only if this resolves.
+   */
+  async confirm(checkpoint, input) {
+    if (input.currency !== void 0 && input.currency !== "USD") {
+      throw checkoutError("Only USD checkouts are supported");
+    }
+    if (!Number.isSafeInteger(input.amountMinor) || input.amountMinor <= 0) {
+      throw checkoutError("amountMinor must be a positive integer number of cents");
+    }
+    let current = checkpoint;
+    if (input.amountMinor !== checkpoint.amountMinor) {
+      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);
+        if (!closed) throw error;
+      }
+      current = await this.begin({
+        idempotencyKey: `${checkpoint.idempotencyKey.slice(0, 200)}:final-${input.amountMinor}`,
+        merchant: {
+          id: checkpoint.merchant.id,
+          name: checkpoint.merchant.name,
+          checkoutUrl: checkpoint.merchant.checkoutUrl ?? ""
+        },
+        amountMinor: input.amountMinor,
+        purpose: checkpoint.purpose,
+        ...checkpoint.category ? { category: checkpoint.category } : {},
+        checkoutMethod: checkpoint.checkoutMethod,
+        lineItems: input.lineItems ?? checkpoint.cart.lineItems,
+        totals: input.totals
+      });
+    }
+    const result = await __privateGet(this, _client).request(
+      "POST",
+      `/api/sdk/checkout-checkpoints/${encodeURIComponent(current.id)}/confirm`,
+      {
+        amountMinor: input.amountMinor,
+        currency: "USD",
+        ...input.pageUrl ? { pageUrl: input.pageUrl } : {}
+      },
+      { idempotent: true }
+    );
+    return result.checkpoint;
+  }
+  /** Report what happened after a confirmed checkpoint. Safe to repeat with the same outcome. */
+  async reportOutcome(checkpointId, input) {
+    const result = await __privateGet(this, _client).request(
+      "POST",
+      `/api/sdk/checkout-checkpoints/${encodeURIComponent(checkpointId)}/outcome`,
+      {
+        outcome: input.outcome,
+        ...input.reference ? { reference: input.reference } : {}
+      },
+      { idempotent: true }
+    );
+    return result.checkpoint;
+  }
+  /** Cancel a checkpoint that was not confirmed and release its spend. */
+  async cancel(checkpointId) {
+    const result = await __privateGet(this, _client).request(
+      "POST",
+      `/api/sdk/checkout-checkpoints/${encodeURIComponent(checkpointId)}/cancel`,
+      {},
+      { idempotent: true }
+    );
+    return result.checkpoint;
+  }
+  async get(checkpointId) {
+    const result = await __privateGet(this, _client).request(
+      "GET",
+      `/api/sdk/checkout-checkpoints/${encodeURIComponent(checkpointId)}`
+    );
+    return result.checkpoint;
+  }
+};
+_client = new WeakMap();
+var _client2, _defaults;
 var LinkClient = class {
   constructor(client, defaults) {
-    __privateAdd(this, _client);
+    __privateAdd(this, _client2);
     __privateAdd(this, _defaults);
-    __privateSet(this, _client, client);
+    __privateSet(this, _client2, client);
     __privateSet(this, _defaults, defaults ? { ...defaults } : void 0);
   }
   /** Inspect the configured live path. This is not a payment authorization or provider connectivity test. */
   async setup(input = {}) {
-    return __privateGet(this, _client).getLinkSetup({
+    return __privateGet(this, _client2).getLinkSetup({
       connectionId: input.connectionId ?? __privateGet(this, _defaults)?.connectionId,
       paymentMethodId: input.paymentMethodId ?? __privateGet(this, _defaults)?.paymentMethodId,
       merchantId: input.merchantId
@@ -1997,7 +2131,7 @@ var LinkClient = class {
   }
   /** Read masked LIVE funding sources; never selects a source or initiates payment. */
   async paymentMethods(connectionId) {
-    return __privateGet(this, _client).listStripeLinkPaymentMethods(
+    return __privateGet(this, _client2).listStripeLinkPaymentMethods(
       this.identifier(connectionId ?? __privateGet(this, _defaults)?.connectionId, "connectionId"),
       { mode: "LIVE" }
     );
@@ -2042,7 +2176,7 @@ var LinkClient = class {
         }
       );
     }
-    const result = await __privateGet(this, _client).beginCommerceExecution({
+    const result = await __privateGet(this, _client2).beginCommerceExecution({
       executionMethod: "LINK_PAY_TOKEN",
       connectionId,
       paymentMethodId,
@@ -2069,25 +2203,25 @@ var LinkClient = class {
    */
   async resume(executionId) {
     const id = this.identifier(executionId, "executionId");
-    const current = await __privateGet(this, _client).getCommerceExecution(id);
+    const current = await __privateGet(this, _client2).getCommerceExecution(id);
     this.assertLinkExecution(current);
     if (["AUTHORIZING", "AWAITING_APPROVAL", "ACTION_REQUIRED"].includes(current.execution.status)) {
-      return this.executeIfReady(await __privateGet(this, _client).refreshCommerceExecution(id));
+      return this.executeIfReady(await __privateGet(this, _client2).refreshCommerceExecution(id));
     }
     return this.executeIfReady(current);
   }
   /** Observe and reconcile provider state. This method never submits a payment. */
   async status(executionId) {
     const id = this.identifier(executionId, "executionId");
-    this.assertLinkExecution(await __privateGet(this, _client).getCommerceExecution(id));
-    return this.result(await __privateGet(this, _client).refreshCommerceExecution(id));
+    this.assertLinkExecution(await __privateGet(this, _client2).getCommerceExecution(id));
+    return this.result(await __privateGet(this, _client2).refreshCommerceExecution(id));
   }
   /** Request cancellation of this existing Link payment; never retried automatically. */
   async cancel(executionId) {
     const id = this.identifier(executionId, "executionId");
-    this.assertLinkExecution(await __privateGet(this, _client).getCommerceExecution(id));
+    this.assertLinkExecution(await __privateGet(this, _client2).getCommerceExecution(id));
     try {
-      return this.result(await __privateGet(this, _client).cancelCommerceExecution(id));
+      return this.result(await __privateGet(this, _client2).cancelCommerceExecution(id));
     } catch (error) {
       throw new LinkPaymentExecutionError(id, error);
     }
@@ -2117,7 +2251,7 @@ var LinkClient = class {
     this.assertLinkExecution(result);
     if (result.execution.status !== "READY") return this.result(result);
     try {
-      return this.result(await __privateGet(this, _client).executeCommerceExecution(result.execution.id));
+      return this.result(await __privateGet(this, _client2).executeCommerceExecution(result.execution.id));
     } catch (error) {
       throw new LinkPaymentExecutionError(result.execution.id, error);
     }
@@ -2147,12 +2281,13 @@ var LinkClient = class {
     };
   }
 };
-_client = new WeakMap();
+_client2 = new WeakMap();
 _defaults = new WeakMap();
 export {
   BrowserActionFinalizationPendingError,
   BrowserCheckoutTargetVerificationError,
   CardsClient,
+  CheckoutClient,
   ConnectedCardsClient,
   Conto,
   ContoAdmin,

package/dist/link-testing.d.mts

@@ -1,9 +1,19 @@
-import { LinkPaymentResult, LinkSetupInput, LinkSetupResult, ListStripeLinkPaymentMethodsResult, LinkPaymentInput } from './index.mjs';
+import { CommerceExecution, CommerceExecutionEvidence, LinkPaymentResult, LinkSetupInput, LinkSetupResult, ListStripeLinkPaymentMethodsResult, LinkPaymentInput } from './index.mjs';
 
 type LinkTestScenario = 'approved' | 'denied' | 'expired' | 'interrupted';
+/** Evidence created by the local simulator. It is never a receipt. */
+type SimulatedCommerceExecutionEvidence = CommerceExecutionEvidence & {
+    mode: 'SIMULATED';
+};
+/** Execution record created by the local simulator. It does not exist on any Conto server. */
+type SimulatedCommerceExecution = CommerceExecution & {
+    mode: 'SIMULATED';
+    evidence: SimulatedCommerceExecutionEvidence;
+};
 type SimulatedLinkPaymentResult = LinkPaymentResult & {
     mode: 'SIMULATED';
     settlementVerified: false;
+    execution: SimulatedCommerceExecution;
 };
 interface LinkTestOptions {
     scenario?: LinkTestScenario;
@@ -12,7 +22,9 @@ interface LinkTestOptions {
 }
 /**
  * Create an isolated in-memory test account with the same pay/resume/status API.
- * Approval is explicit through link.approve(), a test-only method. Nothing settles.
+ * Approval is explicit through link.approve(), a test-only method. Like the live
+ * API, an accepted submission is PROCESSING and only a later status() call
+ * reports SETTLED. No money moves, and every result has settlementVerified false.
  */
 declare function createLinkTestClient(options?: LinkTestOptions): {
     mode: "SIMULATED";
@@ -34,4 +46,4 @@ declare function createLinkTestClient(options?: LinkTestOptions): {
     };
 };
 
-export { type LinkTestOptions, type LinkTestScenario, type SimulatedLinkPaymentResult, createLinkTestClient };
+export { type LinkTestOptions, type LinkTestScenario, type SimulatedCommerceExecution, type SimulatedCommerceExecutionEvidence, type SimulatedLinkPaymentResult, createLinkTestClient };

package/dist/link-testing.d.ts

@@ -1,9 +1,19 @@
-import { LinkPaymentResult, LinkSetupInput, LinkSetupResult, ListStripeLinkPaymentMethodsResult, LinkPaymentInput } from './index.js';
+import { CommerceExecution, CommerceExecutionEvidence, LinkPaymentResult, LinkSetupInput, LinkSetupResult, ListStripeLinkPaymentMethodsResult, LinkPaymentInput } from './index.js';
 
 type LinkTestScenario = 'approved' | 'denied' | 'expired' | 'interrupted';
+/** Evidence created by the local simulator. It is never a receipt. */
+type SimulatedCommerceExecutionEvidence = CommerceExecutionEvidence & {
+    mode: 'SIMULATED';
+};
+/** Execution record created by the local simulator. It does not exist on any Conto server. */
+type SimulatedCommerceExecution = CommerceExecution & {
+    mode: 'SIMULATED';
+    evidence: SimulatedCommerceExecutionEvidence;
+};
 type SimulatedLinkPaymentResult = LinkPaymentResult & {
     mode: 'SIMULATED';
     settlementVerified: false;
+    execution: SimulatedCommerceExecution;
 };
 interface LinkTestOptions {
     scenario?: LinkTestScenario;
@@ -12,7 +22,9 @@ interface LinkTestOptions {
 }
 /**
  * Create an isolated in-memory test account with the same pay/resume/status API.
- * Approval is explicit through link.approve(), a test-only method. Nothing settles.
+ * Approval is explicit through link.approve(), a test-only method. Like the live
+ * API, an accepted submission is PROCESSING and only a later status() call
+ * reports SETTLED. No money moves, and every result has settlementVerified false.
  */
 declare function createLinkTestClient(options?: LinkTestOptions): {
     mode: "SIMULATED";
@@ -34,4 +46,4 @@ declare function createLinkTestClient(options?: LinkTestOptions): {
     };
 };
 
-export { type LinkTestOptions, type LinkTestScenario, type SimulatedLinkPaymentResult, createLinkTestClient };
+export { type LinkTestOptions, type LinkTestScenario, type SimulatedCommerceExecution, type SimulatedCommerceExecutionEvidence, type SimulatedLinkPaymentResult, createLinkTestClient };