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

package/dist/link-testing.js

@@ -35,6 +35,27 @@ function canonical(value) {
 function fail(code, message, status = 409) {
   throw new import_index.ContoError(message, { code, status });
 }
+var LIVE_API_ERRORS = {
+  POLICY_VIOLATION: {
+    status: 403,
+    message: "The request is not permitted.",
+    retryGuidance: "Verify credentials and permissions before trying again."
+  },
+  NOT_FOUND: {
+    status: 404,
+    message: "The requested resource was not found.",
+    retryGuidance: "Verify the resource identifier before trying again."
+  },
+  CONFLICT: {
+    status: 409,
+    message: "The request conflicts with the current resource state.",
+    retryGuidance: "Check the current resource state before trying again."
+  }
+};
+function liveApiError(code) {
+  const { status, message, retryGuidance } = LIVE_API_ERRORS[code];
+  throw new import_index.ContoError(message, { code, status, retryGuidance });
+}
 function createLinkTestClient(options = {}) {
   const scenario = options.scenario ?? "approved";
   const maximumAmountMinor = options.maximumAmountMinor ?? 5e3;
@@ -50,36 +71,37 @@ function createLinkTestClient(options = {}) {
   const sessionId = (0, import_node_crypto.randomUUID)();
   const read = (id) => {
     const record = records.get(id);
-    if (!record)
-      return fail(
-        "SIMULATED_EXECUTION_NOT_FOUND",
-        "No such execution in this local simulation",
-        404
-      );
+    if (!record) return liveApiError("NOT_FOUND");
     return record;
   };
   const response = (id) => ({
     execution: structuredClone(read(id))
   });
-  const setStatus = (id, status) => {
+  const setStatus = (id, status, providerStatus, evidence = {}) => {
     const record = read(id);
     record.status = status;
-    record.evidence.status = status;
-    record.providerStatus = `SIMULATED_${status}`;
-    record.evidence.providerStatus = record.providerStatus;
+    record.providerStatus = `simulated_${providerStatus}`;
+    Object.assign(record.evidence, evidence, { status, providerStatus: record.providerStatus });
     delete record.approvalUrl;
     return response(id);
   };
   const setup = async (_input = {}) => ({
     version: "conto.link-setup.v1",
     mode: "SIMULATED",
-    configurationStatus: "CONFIGURED",
+    // No live setting was inspected, so the simulator never reports CONFIGURED.
+    configurationStatus: "INCOMPLETE",
     checks: [
       {
         code: "LOCAL_SIMULATION",
         status: "WARNING",
         actor: "developer",
         message: "Local workflow fixture only. No real Link account, Conto policy, checkout, budget, or settlement is tested."
+      },
+      {
+        code: "LIVE_SETUP_NOT_INSPECTED",
+        status: "BLOCKED",
+        actor: "developer",
+        message: "The live Link configuration was not inspected. Call link.setup() on a live Conto client before a real payment."
       }
     ],
     missingScopes: [],
@@ -98,7 +120,7 @@ function createLinkTestClient(options = {}) {
             id: "simulated_method",
             type: "SIMULATED",
             isDefault: true,
-            displayLabel: "Simulated funding source \u2014 no funds",
+            displayLabel: "Simulated funding source (no funds)",
             eligibleCredentialTypes: ["LINK_PAY_TOKEN"]
           }
         ]
@@ -121,16 +143,11 @@ function createLinkTestClient(options = {}) {
       const fingerprint = canonical({ ...input, idempotencyKey: key });
       const prior = intents.get(key);
       if (prior) {
-        if (prior.fingerprint !== fingerprint)
-          return fail("IDEMPOTENCY_CONFLICT", "The key belongs to a different simulated purchase");
+        if (prior.fingerprint !== fingerprint) return liveApiError("CONFLICT");
         return response(prior.id);
       }
       if (scenario === "denied" || input.amountMinor > maximumAmountMinor) {
-        return fail(
-          "COMMERCE_POLICY_DENIED",
-          "The local simulated policy denied this purchase",
-          403
-        );
+        return liveApiError("POLICY_VIOLATION");
       }
       if (records.size >= 1e3)
         return fail(
@@ -139,7 +156,9 @@ function createLinkTestClient(options = {}) {
         );
       const id = `sim_link_${sessionId}_${++sequence}`;
       const status = "AWAITING_APPROVAL";
+      const providerStatus = "simulated_pending_approval";
       const evidence = {
+        mode: "SIMULATED",
         schemaVersion: "conto.commerce-evidence.v1",
         traceId: `sim_trace_${sequence}`,
         executionId: id,
@@ -161,9 +180,10 @@ function createLinkTestClient(options = {}) {
         status,
         deliveryMode: "SERVER_ONLY_ARTIFACT",
         artifactKind: "LINK_PAY_TOKEN",
-        providerStatus: "SIMULATED_AWAITING_APPROVAL"
+        providerStatus
       };
       records.set(id, {
+        mode: "SIMULATED",
         id,
         intentId: evidence.intentId,
         organizationId: evidence.organizationId,
@@ -173,10 +193,10 @@ function createLinkTestClient(options = {}) {
         executionChannel: "BROWSER",
         checkoutMethod: "LINK",
         status,
-        providerStatus: evidence.providerStatus,
+        providerStatus,
         artifactKind: "LINK_PAY_TOKEN",
         deliveryMode: "SERVER_ONLY_ARTIFACT",
-        // Reserved .invalid domain. It cannot approve anything; call the test-only approve() method.
+        // Reserved .invalid domain. It cannot approve anything. Call the test-only approve() method.
         approvalUrl: `https://link-simulation.invalid/approve/${id}`,
         amountMinor: input.amountMinor,
         currency: input.currency,
@@ -191,37 +211,36 @@ function createLinkTestClient(options = {}) {
     async getCommerceExecution(id) {
       return response(id);
     },
+    // Like a live refresh, this observes the provider and never submits a payment.
+    // A submitted simulated checkout is observed as succeeded on the next refresh.
     async refreshCommerceExecution(id) {
+      const { status, providerStatus } = read(id);
+      if (status === "PROCESSING" && providerStatus === "simulated_checkout_submitted")
+        return setStatus(id, "SETTLED", "succeeded");
       return response(id);
     },
     async executeCommerceExecution(id) {
-      if (read(id).status !== "READY")
-        return fail("COMMERCE_EXECUTION_NOT_READY", "The simulated payment is not ready");
+      if (read(id).status !== "READY") return liveApiError("CONFLICT");
       if (scenario === "interrupted") {
-        setStatus(id, "NEEDS_RECONCILIATION");
-        return fail(
-          "SIMULATED_EXECUTION_INTERRUPTED",
-          "Simulated lost execution response; inspect the existing execution",
-          0
-        );
+        setStatus(id, "NEEDS_RECONCILIATION", "checkout_outcome_unknown");
+        throw new import_index.ContoError("Network request failed", { code: "NETWORK_ERROR", status: 0 });
       }
       return {
-        ...setStatus(id, "COMPLETED"),
+        ...setStatus(id, "PROCESSING", "checkout_submitted", {
+          checkoutReference: id.replace(/^sim_link_/, "sim_checkout_")
+        }),
         checkout: {
-          submitted: false,
-          accepted: false,
-          deliveryMode: "SERVER_ONLY_ARTIFACT"
+          submitted: true,
+          deliveryMode: "SERVER_ONLY_ARTIFACT",
+          accepted: true
         }
       };
     },
     async cancelCommerceExecution(id) {
       if (["PROCESSING", "NEEDS_RECONCILIATION", "COMPLETED", "SETTLED"].includes(read(id).status)) {
-        return fail(
-          "SIMULATED_CANCELLATION_UNAVAILABLE",
-          "This simulated execution must be reconciled and cannot be cancelled"
-        );
+        return liveApiError("CONFLICT");
       }
-      return setStatus(id, "CANCELLED");
+      return setStatus(id, "CANCELLED", "canceled");
     }
   };
   const client = new import_index.LinkClient(transport, {
@@ -236,23 +255,25 @@ function createLinkTestClient(options = {}) {
       throw Object.assign(safe, { mode: "SIMULATED", settlementVerified: false });
     }
   };
+  const payment = (operation) => marked(operation);
   return {
     mode: "SIMULATED",
     link: {
       setup: (input) => marked(() => client.setup(input)),
       paymentMethods: () => marked(() => client.paymentMethods()),
-      pay: (input) => marked(() => client.pay(input)),
-      resume: (id) => marked(() => client.resume(id)),
-      status: (id) => marked(() => client.status(id)),
-      cancel: (id) => marked(() => client.cancel(id)),
+      pay: (input) => payment(() => client.pay(input)),
+      resume: (id) => payment(() => client.resume(id)),
+      status: (id) => payment(() => client.status(id)),
+      cancel: (id) => payment(() => client.cancel(id)),
       /** Test-only owner action. Never available on the live Link client. */
-      approve: (id) => marked(async () => {
+      approve: (id) => payment(async () => {
         if (read(id).status !== "AWAITING_APPROVAL")
           return fail(
             "SIMULATED_APPROVAL_UNAVAILABLE",
             "This simulation is not awaiting approval"
           );
-        setStatus(id, scenario === "expired" ? "EXPIRED" : "READY");
+        if (scenario === "expired") setStatus(id, "EXPIRED", "expired");
+        else setStatus(id, "READY", "approved");
         return client.status(id);
       })
     }

package/dist/link-testing.mjs

@@ -16,6 +16,27 @@ function canonical(value) {
 function fail(code, message, status = 409) {
   throw new ContoError(message, { code, status });
 }
+var LIVE_API_ERRORS = {
+  POLICY_VIOLATION: {
+    status: 403,
+    message: "The request is not permitted.",
+    retryGuidance: "Verify credentials and permissions before trying again."
+  },
+  NOT_FOUND: {
+    status: 404,
+    message: "The requested resource was not found.",
+    retryGuidance: "Verify the resource identifier before trying again."
+  },
+  CONFLICT: {
+    status: 409,
+    message: "The request conflicts with the current resource state.",
+    retryGuidance: "Check the current resource state before trying again."
+  }
+};
+function liveApiError(code) {
+  const { status, message, retryGuidance } = LIVE_API_ERRORS[code];
+  throw new ContoError(message, { code, status, retryGuidance });
+}
 function createLinkTestClient(options = {}) {
   const scenario = options.scenario ?? "approved";
   const maximumAmountMinor = options.maximumAmountMinor ?? 5e3;
@@ -31,36 +52,37 @@ function createLinkTestClient(options = {}) {
   const sessionId = randomUUID();
   const read = (id) => {
     const record = records.get(id);
-    if (!record)
-      return fail(
-        "SIMULATED_EXECUTION_NOT_FOUND",
-        "No such execution in this local simulation",
-        404
-      );
+    if (!record) return liveApiError("NOT_FOUND");
     return record;
   };
   const response = (id) => ({
     execution: structuredClone(read(id))
   });
-  const setStatus = (id, status) => {
+  const setStatus = (id, status, providerStatus, evidence = {}) => {
     const record = read(id);
     record.status = status;
-    record.evidence.status = status;
-    record.providerStatus = `SIMULATED_${status}`;
-    record.evidence.providerStatus = record.providerStatus;
+    record.providerStatus = `simulated_${providerStatus}`;
+    Object.assign(record.evidence, evidence, { status, providerStatus: record.providerStatus });
     delete record.approvalUrl;
     return response(id);
   };
   const setup = async (_input = {}) => ({
     version: "conto.link-setup.v1",
     mode: "SIMULATED",
-    configurationStatus: "CONFIGURED",
+    // No live setting was inspected, so the simulator never reports CONFIGURED.
+    configurationStatus: "INCOMPLETE",
     checks: [
       {
         code: "LOCAL_SIMULATION",
         status: "WARNING",
         actor: "developer",
         message: "Local workflow fixture only. No real Link account, Conto policy, checkout, budget, or settlement is tested."
+      },
+      {
+        code: "LIVE_SETUP_NOT_INSPECTED",
+        status: "BLOCKED",
+        actor: "developer",
+        message: "The live Link configuration was not inspected. Call link.setup() on a live Conto client before a real payment."
       }
     ],
     missingScopes: [],
@@ -79,7 +101,7 @@ function createLinkTestClient(options = {}) {
             id: "simulated_method",
             type: "SIMULATED",
             isDefault: true,
-            displayLabel: "Simulated funding source \u2014 no funds",
+            displayLabel: "Simulated funding source (no funds)",
             eligibleCredentialTypes: ["LINK_PAY_TOKEN"]
           }
         ]
@@ -102,16 +124,11 @@ function createLinkTestClient(options = {}) {
       const fingerprint = canonical({ ...input, idempotencyKey: key });
       const prior = intents.get(key);
       if (prior) {
-        if (prior.fingerprint !== fingerprint)
-          return fail("IDEMPOTENCY_CONFLICT", "The key belongs to a different simulated purchase");
+        if (prior.fingerprint !== fingerprint) return liveApiError("CONFLICT");
         return response(prior.id);
       }
       if (scenario === "denied" || input.amountMinor > maximumAmountMinor) {
-        return fail(
-          "COMMERCE_POLICY_DENIED",
-          "The local simulated policy denied this purchase",
-          403
-        );
+        return liveApiError("POLICY_VIOLATION");
       }
       if (records.size >= 1e3)
         return fail(
@@ -120,7 +137,9 @@ function createLinkTestClient(options = {}) {
         );
       const id = `sim_link_${sessionId}_${++sequence}`;
       const status = "AWAITING_APPROVAL";
+      const providerStatus = "simulated_pending_approval";
       const evidence = {
+        mode: "SIMULATED",
         schemaVersion: "conto.commerce-evidence.v1",
         traceId: `sim_trace_${sequence}`,
         executionId: id,
@@ -142,9 +161,10 @@ function createLinkTestClient(options = {}) {
         status,
         deliveryMode: "SERVER_ONLY_ARTIFACT",
         artifactKind: "LINK_PAY_TOKEN",
-        providerStatus: "SIMULATED_AWAITING_APPROVAL"
+        providerStatus
       };
       records.set(id, {
+        mode: "SIMULATED",
         id,
         intentId: evidence.intentId,
         organizationId: evidence.organizationId,
@@ -154,10 +174,10 @@ function createLinkTestClient(options = {}) {
         executionChannel: "BROWSER",
         checkoutMethod: "LINK",
         status,
-        providerStatus: evidence.providerStatus,
+        providerStatus,
         artifactKind: "LINK_PAY_TOKEN",
         deliveryMode: "SERVER_ONLY_ARTIFACT",
-        // Reserved .invalid domain. It cannot approve anything; call the test-only approve() method.
+        // Reserved .invalid domain. It cannot approve anything. Call the test-only approve() method.
         approvalUrl: `https://link-simulation.invalid/approve/${id}`,
         amountMinor: input.amountMinor,
         currency: input.currency,
@@ -172,37 +192,36 @@ function createLinkTestClient(options = {}) {
     async getCommerceExecution(id) {
       return response(id);
     },
+    // Like a live refresh, this observes the provider and never submits a payment.
+    // A submitted simulated checkout is observed as succeeded on the next refresh.
     async refreshCommerceExecution(id) {
+      const { status, providerStatus } = read(id);
+      if (status === "PROCESSING" && providerStatus === "simulated_checkout_submitted")
+        return setStatus(id, "SETTLED", "succeeded");
       return response(id);
     },
     async executeCommerceExecution(id) {
-      if (read(id).status !== "READY")
-        return fail("COMMERCE_EXECUTION_NOT_READY", "The simulated payment is not ready");
+      if (read(id).status !== "READY") return liveApiError("CONFLICT");
       if (scenario === "interrupted") {
-        setStatus(id, "NEEDS_RECONCILIATION");
-        return fail(
-          "SIMULATED_EXECUTION_INTERRUPTED",
-          "Simulated lost execution response; inspect the existing execution",
-          0
-        );
+        setStatus(id, "NEEDS_RECONCILIATION", "checkout_outcome_unknown");
+        throw new ContoError("Network request failed", { code: "NETWORK_ERROR", status: 0 });
       }
       return {
-        ...setStatus(id, "COMPLETED"),
+        ...setStatus(id, "PROCESSING", "checkout_submitted", {
+          checkoutReference: id.replace(/^sim_link_/, "sim_checkout_")
+        }),
         checkout: {
-          submitted: false,
-          accepted: false,
-          deliveryMode: "SERVER_ONLY_ARTIFACT"
+          submitted: true,
+          deliveryMode: "SERVER_ONLY_ARTIFACT",
+          accepted: true
         }
       };
     },
     async cancelCommerceExecution(id) {
       if (["PROCESSING", "NEEDS_RECONCILIATION", "COMPLETED", "SETTLED"].includes(read(id).status)) {
-        return fail(
-          "SIMULATED_CANCELLATION_UNAVAILABLE",
-          "This simulated execution must be reconciled and cannot be cancelled"
-        );
+        return liveApiError("CONFLICT");
       }
-      return setStatus(id, "CANCELLED");
+      return setStatus(id, "CANCELLED", "canceled");
     }
   };
   const client = new LinkClient(transport, {
@@ -217,23 +236,25 @@ function createLinkTestClient(options = {}) {
       throw Object.assign(safe, { mode: "SIMULATED", settlementVerified: false });
     }
   };
+  const payment = (operation) => marked(operation);
   return {
     mode: "SIMULATED",
     link: {
       setup: (input) => marked(() => client.setup(input)),
       paymentMethods: () => marked(() => client.paymentMethods()),
-      pay: (input) => marked(() => client.pay(input)),
-      resume: (id) => marked(() => client.resume(id)),
-      status: (id) => marked(() => client.status(id)),
-      cancel: (id) => marked(() => client.cancel(id)),
+      pay: (input) => payment(() => client.pay(input)),
+      resume: (id) => payment(() => client.resume(id)),
+      status: (id) => payment(() => client.status(id)),
+      cancel: (id) => payment(() => client.cancel(id)),
       /** Test-only owner action. Never available on the live Link client. */
-      approve: (id) => marked(async () => {
+      approve: (id) => payment(async () => {
         if (read(id).status !== "AWAITING_APPROVAL")
           return fail(
             "SIMULATED_APPROVAL_UNAVAILABLE",
             "This simulation is not awaiting approval"
           );
-        setStatus(id, scenario === "expired" ? "EXPIRED" : "READY");
+        if (scenario === "expired") setStatus(id, "EXPIRED", "expired");
+        else setStatus(id, "READY", "approved");
         return client.status(id);
       })
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "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",
@@ -47,7 +47,7 @@
     "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"