@conto_finance/sdk 0.5.5 → 0.6.0-beta.1

package/dist/index.js

@@ -46,7 +46,7 @@ var require_package = __commonJS({
   "package.json"(exports2, module2) {
     module2.exports = {
       name: "@conto_finance/sdk",
-      version: "0.5.5",
+      version: "0.6.0-beta.1",
       description: "Conto SDK for AI agent payment authorization",
       main: "./dist/index.js",
       module: "./dist/index.mjs",
@@ -71,10 +71,16 @@ var require_package = __commonJS({
           types: "./dist/checkout-verifier.d.ts",
           import: "./dist/checkout-verifier.mjs",
           require: "./dist/checkout-verifier.js"
+        },
+        "./link-testing": {
+          types: "./dist/link-testing.d.ts",
+          import: "./dist/link-testing.mjs",
+          require: "./dist/link-testing.js"
         }
       },
       publishConfig: {
-        access: "public"
+        access: "public",
+        tag: "beta"
       },
       engines: {
         node: ">=20.19.0"
@@ -83,11 +89,11 @@ var require_package = __commonJS({
         "dist"
       ],
       scripts: {
-        build: "tsup src/index.ts src/playwright.ts src/browserbase.ts src/checkout-verifier.ts --format cjs,esm --dts",
-        dev: "tsup src/index.ts src/playwright.ts src/browserbase.ts src/checkout-verifier.ts --format cjs,esm --dts --watch",
+        build: "tsup",
+        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: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: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"
@@ -161,6 +167,8 @@ __export(index_exports, {
   ControlledExternalCardPaymentTool: () => ControlledExternalCardPaymentTool,
   ExternalCardConfirmationPendingError: () => ExternalCardConfirmationPendingError,
   Giro: () => Conto,
+  LinkClient: () => LinkClient,
+  LinkPaymentExecutionError: () => LinkPaymentExecutionError,
   TestCardsClient: () => TestCardsClient,
   canonicalizeBrowserCheckoutTarget: () => canonicalizeBrowserCheckoutTarget,
   createVerifiedBrowserCheckoutDriver: () => createVerifiedBrowserCheckoutDriver,
@@ -1053,7 +1061,7 @@ function isValidBrowserActionObservation(value) {
   }
 }
 var ContoError = class extends Error {
-  constructor(message, metadata) {
+  constructor(message, metadata, diagnostics) {
     super(message);
     this.name = "ContoError";
     this.code = metadata.code;
@@ -1064,6 +1072,30 @@ var ContoError = class extends Error {
     this.actionUrl = metadata.actionUrl;
     this.fieldErrors = metadata.fieldErrors;
     this.reasons = metadata.reasons;
+    if (diagnostics !== null && typeof diagnostics === "object" && !Array.isArray(diagnostics) && "version" in diagnostics && diagnostics.version === "conto.setup-diagnostics.v1") {
+      this.diagnostics = diagnostics;
+    }
+  }
+};
+var LinkPaymentExecutionError = class extends ContoError {
+  constructor(executionId, error) {
+    const original = error instanceof ContoError ? error : void 0;
+    super(
+      original?.message ?? "Link execution could not be confirmed",
+      {
+        code: original?.code ?? "LINK_EXECUTION_UNCONFIRMED",
+        status: original?.status ?? 0,
+        requestId: original?.requestId,
+        retryAfter: original?.retryAfter,
+        fieldErrors: original?.fieldErrors,
+        reasons: original?.reasons,
+        retryGuidance: "Call link.status(executionId) to reconcile. Do not create another purchase or retry execution blindly."
+      },
+      original?.diagnostics
+    );
+    this.nextAction = "RECONCILE";
+    this.name = "LinkPaymentExecutionError";
+    this.executionId = executionId;
   }
 };
 var ExternalCardConfirmationPendingError = class extends ContoError {
@@ -1155,6 +1187,7 @@ var Conto = class {
     this.baseUrl = (config.baseUrl || "https://conto.finance").replace(/\/$/, "");
     assertSecureBaseUrl(this.baseUrl);
     this.timeout = config.timeout || 3e4;
+    this.link = new LinkClient(this, config.link);
     this.payments = new PaymentsClient(this);
     this.cards = new CardsClient(this);
     this.connectedCards = new ConnectedCardsClient(this);
@@ -1167,10 +1200,24 @@ var Conto = class {
    * explicitly bound to this agent. No Link token or payment artifact is
    * returned through the agent SDK.
    */
-  async listStripeLinkPaymentMethods(connectionId) {
+  async listStripeLinkPaymentMethods(connectionId, options) {
     return this.request(
       "GET",
-      withQuery("/api/sdk/stripe-link/payment-methods", { connectionId })
+      withQuery("/api/sdk/stripe-link/payment-methods", {
+        connectionId,
+        ...options?.mode ? { mode: options.mode } : {}
+      })
+    );
+  }
+  /** Read live Link configuration diagnostics without retrieving credentials or authorizing payment. */
+  async getLinkSetup(input = {}) {
+    return this.request(
+      "GET",
+      withQuery("/api/sdk/stripe-link/setup", {
+        connectionId: input.connectionId,
+        paymentMethodId: input.paymentMethodId,
+        merchantId: input.merchantId
+      })
     );
   }
   /**
@@ -1466,7 +1513,8 @@ var Conto = class {
       if (!response.ok) {
         throw new ContoError(
           responseErrorMessage(data, response.status),
-          responseErrorMetadata(response, data)
+          responseErrorMetadata(response, data),
+          data !== null && typeof data === "object" && "diagnostics" in data ? data.diagnostics : void 0
         );
       }
       return data;
@@ -2099,6 +2147,176 @@ var MppClient = class {
   }
 };
 var index_default = Conto;
+var _client, _defaults;
+var LinkClient = class {
+  constructor(client, defaults) {
+    __privateAdd(this, _client);
+    __privateAdd(this, _defaults);
+    __privateSet(this, _client, 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({
+      connectionId: input.connectionId ?? __privateGet(this, _defaults)?.connectionId,
+      paymentMethodId: input.paymentMethodId ?? __privateGet(this, _defaults)?.paymentMethodId,
+      merchantId: input.merchantId
+    });
+  }
+  /** Read masked LIVE funding sources; never selects a source or initiates payment. */
+  async paymentMethods(connectionId) {
+    return __privateGet(this, _client).listStripeLinkPaymentMethods(
+      this.identifier(connectionId ?? __privateGet(this, _defaults)?.connectionId, "connectionId"),
+      { mode: "LIVE" }
+    );
+  }
+  /**
+   * Begin one exact intent and execute only if already READY. Otherwise return
+   * the owner's approval action or existing state immediately, without polling.
+   */
+  async pay(input) {
+    const connectionId = this.identifier(
+      input.connectionId ?? __privateGet(this, _defaults)?.connectionId,
+      "connectionId"
+    );
+    const paymentMethodId = this.identifier(
+      input.paymentMethodId ?? __privateGet(this, _defaults)?.paymentMethodId,
+      "paymentMethodId"
+    );
+    if (!Number.isSafeInteger(input.amountMinor) || input.amountMinor <= 0 || input.currency !== void 0 && input.currency !== "USD" || !Array.isArray(input.lineItems) || input.lineItems.length === 0 || typeof input.purpose !== "string" || !input.purpose.trim()) {
+      throw new ContoError("Supply a positive USD amount in cents, purpose, and line items", {
+        code: "INVALID_LINK_PURCHASE",
+        status: 0
+      });
+    }
+    const itemTotal = input.lineItems.reduce((sum, item) => {
+      if (!item || typeof item.name !== "string" || !item.name.trim() || !Number.isSafeInteger(item.quantity) || item.quantity <= 0 || !Number.isSafeInteger(item.unitAmountMinor) || item.unitAmountMinor < 0) {
+        throw new ContoError(
+          "Each line item needs a name, positive integer quantity, and price in cents",
+          {
+            code: "INVALID_LINK_PURCHASE",
+            status: 0
+          }
+        );
+      }
+      return sum + item.quantity * item.unitAmountMinor;
+    }, 0);
+    if (!input.totals && (!Number.isSafeInteger(itemTotal) || itemTotal !== input.amountMinor)) {
+      throw new ContoError(
+        "Supply the exact totals breakdown when the amount differs from the line items",
+        {
+          code: "LINK_TOTALS_REQUIRED",
+          status: 0
+        }
+      );
+    }
+    const result = await __privateGet(this, _client).beginCommerceExecution({
+      executionMethod: "LINK_PAY_TOKEN",
+      connectionId,
+      paymentMethodId,
+      idempotencyKey: input.idempotencyKey,
+      amountMinor: input.amountMinor,
+      currency: input.currency ?? "USD",
+      purpose: input.purpose,
+      category: input.category,
+      counterparty: { canonicalId: input.merchantId, checkoutUrl: input.checkoutUrl },
+      cart: {
+        lineItems: input.lineItems,
+        totals: input.totals ?? [{ type: "total", label: "Total", amountMinor: input.amountMinor }]
+      },
+      providerPresentation: {
+        approvalSummary: input.purpose.trim().slice(0, 500),
+        lineItemLabels: input.lineItems.map((item) => item.name.trim().slice(0, 120))
+      }
+    });
+    return this.executeIfReady(result);
+  }
+  /**
+   * Continue the existing payment after approval. Reads before any mutation and
+   * never submits an execution already processing or requiring reconciliation.
+   */
+  async resume(executionId) {
+    const id = this.identifier(executionId, "executionId");
+    const current = await __privateGet(this, _client).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(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));
+  }
+  /** 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));
+    try {
+      return this.result(await __privateGet(this, _client).cancelCommerceExecution(id));
+    } catch (error) {
+      throw new LinkPaymentExecutionError(id, error);
+    }
+  }
+  identifier(value, field) {
+    if (typeof value !== "string" || !value.trim() || value.length > 255) {
+      throw new ContoError(
+        field === "executionId" ? "executionId is required; use the existing ID returned by link.pay()" : `${field} is required; configure the owner-provisioned Link IDs or supply them explicitly`,
+        {
+          code: "LINK_CONFIGURATION_REQUIRED",
+          status: 0
+        }
+      );
+    }
+    return value.trim();
+  }
+  assertLinkExecution(result) {
+    const execution = result.execution;
+    if (execution?.provider !== "STRIPE_LINK" || execution.executionAdapter !== "STRIPE_LINK" || execution.executionChannel !== "BROWSER" || execution.artifactKind !== void 0 && execution.artifactKind !== "LINK_PAY_TOKEN" || execution.deliveryMode !== void 0 && execution.deliveryMode !== "SERVER_ONLY_ARTIFACT") {
+      throw new ContoError("This execution is not a Link Pay Token checkout", {
+        code: "LINK_EXECUTION_MISMATCH",
+        status: 0
+      });
+    }
+  }
+  async executeIfReady(result) {
+    this.assertLinkExecution(result);
+    if (result.execution.status !== "READY") return this.result(result);
+    try {
+      return this.result(await __privateGet(this, _client).executeCommerceExecution(result.execution.id));
+    } catch (error) {
+      throw new LinkPaymentExecutionError(result.execution.id, error);
+    }
+  }
+  result(result) {
+    this.assertLinkExecution(result);
+    const { execution } = result;
+    const awaitingApproval = ["AUTHORIZING", "AWAITING_APPROVAL", "ACTION_REQUIRED"].includes(
+      execution.status
+    );
+    const nextAction = execution.status === "READY" ? "RESUME" : execution.status === "NEEDS_RECONCILIATION" ? "RECONCILE" : awaitingApproval && execution.approvalUrl ? "APPROVE_IN_LINK" : awaitingApproval || ["DRAFT", "PROCESSING"].includes(execution.status) ? "WAIT" : [
+      "SETTLED",
+      "COMPLETED",
+      "DENIED",
+      "CANCELLED",
+      "FAILED",
+      "RETURNED",
+      "EXPIRED"
+    ].includes(execution.status) ? "NONE" : "RECONCILE";
+    return {
+      executionId: execution.id,
+      status: execution.status,
+      nextAction,
+      ...nextAction === "APPROVE_IN_LINK" ? { approvalUrl: execution.approvalUrl } : {},
+      execution,
+      ..."checkout" in result ? { checkout: result.checkout } : {}
+    };
+  }
+};
+_client = new WeakMap();
+_defaults = new WeakMap();
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   BrowserActionFinalizationPendingError,
@@ -2112,6 +2330,8 @@ var index_default = Conto;
   ControlledExternalCardPaymentTool,
   ExternalCardConfirmationPendingError,
   Giro,
+  LinkClient,
+  LinkPaymentExecutionError,
   TestCardsClient,
   canonicalizeBrowserCheckoutTarget,
   createVerifiedBrowserCheckoutDriver,

package/dist/index.mjs

@@ -17,7 +17,7 @@ var require_package = __commonJS({
   "package.json"(exports, module) {
     module.exports = {
       name: "@conto_finance/sdk",
-      version: "0.5.5",
+      version: "0.6.0-beta.1",
       description: "Conto SDK for AI agent payment authorization",
       main: "./dist/index.js",
       module: "./dist/index.mjs",
@@ -42,10 +42,16 @@ var require_package = __commonJS({
           types: "./dist/checkout-verifier.d.ts",
           import: "./dist/checkout-verifier.mjs",
           require: "./dist/checkout-verifier.js"
+        },
+        "./link-testing": {
+          types: "./dist/link-testing.d.ts",
+          import: "./dist/link-testing.mjs",
+          require: "./dist/link-testing.js"
         }
       },
       publishConfig: {
-        access: "public"
+        access: "public",
+        tag: "beta"
       },
       engines: {
         node: ">=20.19.0"
@@ -54,11 +60,11 @@ var require_package = __commonJS({
         "dist"
       ],
       scripts: {
-        build: "tsup src/index.ts src/playwright.ts src/browserbase.ts src/checkout-verifier.ts --format cjs,esm --dts",
-        dev: "tsup src/index.ts src/playwright.ts src/browserbase.ts src/checkout-verifier.ts --format cjs,esm --dts --watch",
+        build: "tsup",
+        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: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: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"
@@ -887,7 +893,7 @@ function isValidBrowserActionObservation(value) {
   }
 }
 var ContoError = class extends Error {
-  constructor(message, metadata) {
+  constructor(message, metadata, diagnostics) {
     super(message);
     this.name = "ContoError";
     this.code = metadata.code;
@@ -898,6 +904,30 @@ var ContoError = class extends Error {
     this.actionUrl = metadata.actionUrl;
     this.fieldErrors = metadata.fieldErrors;
     this.reasons = metadata.reasons;
+    if (diagnostics !== null && typeof diagnostics === "object" && !Array.isArray(diagnostics) && "version" in diagnostics && diagnostics.version === "conto.setup-diagnostics.v1") {
+      this.diagnostics = diagnostics;
+    }
+  }
+};
+var LinkPaymentExecutionError = class extends ContoError {
+  constructor(executionId, error) {
+    const original = error instanceof ContoError ? error : void 0;
+    super(
+      original?.message ?? "Link execution could not be confirmed",
+      {
+        code: original?.code ?? "LINK_EXECUTION_UNCONFIRMED",
+        status: original?.status ?? 0,
+        requestId: original?.requestId,
+        retryAfter: original?.retryAfter,
+        fieldErrors: original?.fieldErrors,
+        reasons: original?.reasons,
+        retryGuidance: "Call link.status(executionId) to reconcile. Do not create another purchase or retry execution blindly."
+      },
+      original?.diagnostics
+    );
+    this.nextAction = "RECONCILE";
+    this.name = "LinkPaymentExecutionError";
+    this.executionId = executionId;
   }
 };
 var ExternalCardConfirmationPendingError = class extends ContoError {
@@ -989,6 +1019,7 @@ var Conto = class {
     this.baseUrl = (config.baseUrl || "https://conto.finance").replace(/\/$/, "");
     assertSecureBaseUrl(this.baseUrl);
     this.timeout = config.timeout || 3e4;
+    this.link = new LinkClient(this, config.link);
     this.payments = new PaymentsClient(this);
     this.cards = new CardsClient(this);
     this.connectedCards = new ConnectedCardsClient(this);
@@ -1001,10 +1032,24 @@ var Conto = class {
    * explicitly bound to this agent. No Link token or payment artifact is
    * returned through the agent SDK.
    */
-  async listStripeLinkPaymentMethods(connectionId) {
+  async listStripeLinkPaymentMethods(connectionId, options) {
     return this.request(
       "GET",
-      withQuery("/api/sdk/stripe-link/payment-methods", { connectionId })
+      withQuery("/api/sdk/stripe-link/payment-methods", {
+        connectionId,
+        ...options?.mode ? { mode: options.mode } : {}
+      })
+    );
+  }
+  /** Read live Link configuration diagnostics without retrieving credentials or authorizing payment. */
+  async getLinkSetup(input = {}) {
+    return this.request(
+      "GET",
+      withQuery("/api/sdk/stripe-link/setup", {
+        connectionId: input.connectionId,
+        paymentMethodId: input.paymentMethodId,
+        merchantId: input.merchantId
+      })
     );
   }
   /**
@@ -1300,7 +1345,8 @@ var Conto = class {
       if (!response.ok) {
         throw new ContoError(
           responseErrorMessage(data, response.status),
-          responseErrorMetadata(response, data)
+          responseErrorMetadata(response, data),
+          data !== null && typeof data === "object" && "diagnostics" in data ? data.diagnostics : void 0
         );
       }
       return data;
@@ -1933,6 +1979,176 @@ var MppClient = class {
   }
 };
 var index_default = Conto;
+var _client, _defaults;
+var LinkClient = class {
+  constructor(client, defaults) {
+    __privateAdd(this, _client);
+    __privateAdd(this, _defaults);
+    __privateSet(this, _client, 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({
+      connectionId: input.connectionId ?? __privateGet(this, _defaults)?.connectionId,
+      paymentMethodId: input.paymentMethodId ?? __privateGet(this, _defaults)?.paymentMethodId,
+      merchantId: input.merchantId
+    });
+  }
+  /** Read masked LIVE funding sources; never selects a source or initiates payment. */
+  async paymentMethods(connectionId) {
+    return __privateGet(this, _client).listStripeLinkPaymentMethods(
+      this.identifier(connectionId ?? __privateGet(this, _defaults)?.connectionId, "connectionId"),
+      { mode: "LIVE" }
+    );
+  }
+  /**
+   * Begin one exact intent and execute only if already READY. Otherwise return
+   * the owner's approval action or existing state immediately, without polling.
+   */
+  async pay(input) {
+    const connectionId = this.identifier(
+      input.connectionId ?? __privateGet(this, _defaults)?.connectionId,
+      "connectionId"
+    );
+    const paymentMethodId = this.identifier(
+      input.paymentMethodId ?? __privateGet(this, _defaults)?.paymentMethodId,
+      "paymentMethodId"
+    );
+    if (!Number.isSafeInteger(input.amountMinor) || input.amountMinor <= 0 || input.currency !== void 0 && input.currency !== "USD" || !Array.isArray(input.lineItems) || input.lineItems.length === 0 || typeof input.purpose !== "string" || !input.purpose.trim()) {
+      throw new ContoError("Supply a positive USD amount in cents, purpose, and line items", {
+        code: "INVALID_LINK_PURCHASE",
+        status: 0
+      });
+    }
+    const itemTotal = input.lineItems.reduce((sum, item) => {
+      if (!item || typeof item.name !== "string" || !item.name.trim() || !Number.isSafeInteger(item.quantity) || item.quantity <= 0 || !Number.isSafeInteger(item.unitAmountMinor) || item.unitAmountMinor < 0) {
+        throw new ContoError(
+          "Each line item needs a name, positive integer quantity, and price in cents",
+          {
+            code: "INVALID_LINK_PURCHASE",
+            status: 0
+          }
+        );
+      }
+      return sum + item.quantity * item.unitAmountMinor;
+    }, 0);
+    if (!input.totals && (!Number.isSafeInteger(itemTotal) || itemTotal !== input.amountMinor)) {
+      throw new ContoError(
+        "Supply the exact totals breakdown when the amount differs from the line items",
+        {
+          code: "LINK_TOTALS_REQUIRED",
+          status: 0
+        }
+      );
+    }
+    const result = await __privateGet(this, _client).beginCommerceExecution({
+      executionMethod: "LINK_PAY_TOKEN",
+      connectionId,
+      paymentMethodId,
+      idempotencyKey: input.idempotencyKey,
+      amountMinor: input.amountMinor,
+      currency: input.currency ?? "USD",
+      purpose: input.purpose,
+      category: input.category,
+      counterparty: { canonicalId: input.merchantId, checkoutUrl: input.checkoutUrl },
+      cart: {
+        lineItems: input.lineItems,
+        totals: input.totals ?? [{ type: "total", label: "Total", amountMinor: input.amountMinor }]
+      },
+      providerPresentation: {
+        approvalSummary: input.purpose.trim().slice(0, 500),
+        lineItemLabels: input.lineItems.map((item) => item.name.trim().slice(0, 120))
+      }
+    });
+    return this.executeIfReady(result);
+  }
+  /**
+   * Continue the existing payment after approval. Reads before any mutation and
+   * never submits an execution already processing or requiring reconciliation.
+   */
+  async resume(executionId) {
+    const id = this.identifier(executionId, "executionId");
+    const current = await __privateGet(this, _client).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(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));
+  }
+  /** 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));
+    try {
+      return this.result(await __privateGet(this, _client).cancelCommerceExecution(id));
+    } catch (error) {
+      throw new LinkPaymentExecutionError(id, error);
+    }
+  }
+  identifier(value, field) {
+    if (typeof value !== "string" || !value.trim() || value.length > 255) {
+      throw new ContoError(
+        field === "executionId" ? "executionId is required; use the existing ID returned by link.pay()" : `${field} is required; configure the owner-provisioned Link IDs or supply them explicitly`,
+        {
+          code: "LINK_CONFIGURATION_REQUIRED",
+          status: 0
+        }
+      );
+    }
+    return value.trim();
+  }
+  assertLinkExecution(result) {
+    const execution = result.execution;
+    if (execution?.provider !== "STRIPE_LINK" || execution.executionAdapter !== "STRIPE_LINK" || execution.executionChannel !== "BROWSER" || execution.artifactKind !== void 0 && execution.artifactKind !== "LINK_PAY_TOKEN" || execution.deliveryMode !== void 0 && execution.deliveryMode !== "SERVER_ONLY_ARTIFACT") {
+      throw new ContoError("This execution is not a Link Pay Token checkout", {
+        code: "LINK_EXECUTION_MISMATCH",
+        status: 0
+      });
+    }
+  }
+  async executeIfReady(result) {
+    this.assertLinkExecution(result);
+    if (result.execution.status !== "READY") return this.result(result);
+    try {
+      return this.result(await __privateGet(this, _client).executeCommerceExecution(result.execution.id));
+    } catch (error) {
+      throw new LinkPaymentExecutionError(result.execution.id, error);
+    }
+  }
+  result(result) {
+    this.assertLinkExecution(result);
+    const { execution } = result;
+    const awaitingApproval = ["AUTHORIZING", "AWAITING_APPROVAL", "ACTION_REQUIRED"].includes(
+      execution.status
+    );
+    const nextAction = execution.status === "READY" ? "RESUME" : execution.status === "NEEDS_RECONCILIATION" ? "RECONCILE" : awaitingApproval && execution.approvalUrl ? "APPROVE_IN_LINK" : awaitingApproval || ["DRAFT", "PROCESSING"].includes(execution.status) ? "WAIT" : [
+      "SETTLED",
+      "COMPLETED",
+      "DENIED",
+      "CANCELLED",
+      "FAILED",
+      "RETURNED",
+      "EXPIRED"
+    ].includes(execution.status) ? "NONE" : "RECONCILE";
+    return {
+      executionId: execution.id,
+      status: execution.status,
+      nextAction,
+      ...nextAction === "APPROVE_IN_LINK" ? { approvalUrl: execution.approvalUrl } : {},
+      execution,
+      ..."checkout" in result ? { checkout: result.checkout } : {}
+    };
+  }
+};
+_client = new WeakMap();
+_defaults = new WeakMap();
 export {
   BrowserActionFinalizationPendingError,
   BrowserCheckoutTargetVerificationError,
@@ -1945,6 +2161,8 @@ export {
   ControlledExternalCardPaymentTool,
   ExternalCardConfirmationPendingError,
   Conto as Giro,
+  LinkClient,
+  LinkPaymentExecutionError,
   TestCardsClient,
   canonicalizeBrowserCheckoutTarget,
   createVerifiedBrowserCheckoutDriver,

package/dist/link-testing.d.mts

@@ -0,0 +1,37 @@
+import { LinkPaymentResult, LinkSetupInput, LinkSetupResult, ListStripeLinkPaymentMethodsResult, LinkPaymentInput } from './index.mjs';
+
+type LinkTestScenario = 'approved' | 'denied' | 'expired' | 'interrupted';
+type SimulatedLinkPaymentResult = LinkPaymentResult & {
+    mode: 'SIMULATED';
+    settlementVerified: false;
+};
+interface LinkTestOptions {
+    scenario?: LinkTestScenario;
+    /** A local fixture limit, not a real Conto policy or available balance. Defaults to 5000 cents. */
+    maximumAmountMinor?: number;
+}
+/**
+ * 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.
+ */
+declare function createLinkTestClient(options?: LinkTestOptions): {
+    mode: "SIMULATED";
+    link: {
+        setup: (input?: LinkSetupInput) => Promise<LinkSetupResult & {
+            mode: "SIMULATED";
+            settlementVerified: false;
+        }>;
+        paymentMethods: () => Promise<ListStripeLinkPaymentMethodsResult & {
+            mode: "SIMULATED";
+            settlementVerified: false;
+        }>;
+        pay: (input: LinkPaymentInput) => Promise<SimulatedLinkPaymentResult>;
+        resume: (id: string) => Promise<SimulatedLinkPaymentResult>;
+        status: (id: string) => Promise<SimulatedLinkPaymentResult>;
+        cancel: (id: string) => Promise<SimulatedLinkPaymentResult>;
+        /** Test-only owner action. Never available on the live Link client. */
+        approve: (id: string) => Promise<SimulatedLinkPaymentResult>;
+    };
+};
+
+export { type LinkTestOptions, type LinkTestScenario, type SimulatedLinkPaymentResult, createLinkTestClient };