@agent-cards/checkout 0.9.1 → 0.11.0

package/dist/stripe-checkout.js

@@ -0,0 +1,133 @@
+import { classifyStripeCheckoutRequest, createStripeCheckoutTokenizationStub, encodeStripeCheckoutContext, isStripeCheckoutEndpoint, STRIPE_CHECKOUT_CONTEXT_HEADER, captureStripeCheckoutBilling, attachStripeCheckoutBilling, validateStripeCheckoutIdentity, } from './stripe-checkout.generated.js';
+class StripeCheckoutRejectionError extends Error {
+    stage;
+    reason;
+    phase;
+    constructor(message, stage, reason, phase) {
+        super(message);
+        this.stage = stage;
+        this.reason = reason;
+        this.phase = phase;
+    }
+}
+export function stripeCheckoutReadinessError(reason) {
+    return new StripeCheckoutRejectionError('checkout_interception_not_ready', 'readiness', reason);
+}
+/** A valid competing request must not retire the request that already claimed this step. */
+export class StripeCheckoutClaimConflictError extends StripeCheckoutRejectionError {
+    constructor(phase) {
+        super(phase === 'tokenization' ? 'Native Stripe Checkout preparation is already claimed.'
+            : 'Native Stripe Checkout confirmation is already claimed.', 'claim', phase === 'tokenization' ? 'duplicate_tokenization' : 'duplicate_confirmation', phase);
+    }
+}
+/** The two native browser requests belong to one attachment and one grant.
+ * Processor rules and form transformations live in the generated shared core.
+ * The local stub contains no selected-card data and starts no authorization.
+ */
+export class StripeCheckoutGate {
+    state = 'fresh';
+    billing;
+    binding;
+    constructor(options) {
+        if (!options.stripeCheckout)
+            return;
+        const { sessionId, publishableKey, environment } = options.stripeCheckout;
+        validateStripeCheckoutIdentity({ environment, sessionId, publishableKey });
+        if (options.executionMode !== 'autopilot' || !/^apg_[A-Za-z0-9_-]{1,128}(?![\s\S])/.test(options.grantId ?? '')
+            || !Number.isSafeInteger(options.amount) || Number(options.amount) <= 0 || options.currency !== 'usd')
+            throw new Error('Native Stripe Checkout requires a mode-bound session, grant and numeric USD amount.');
+        this.binding = Object.freeze({ environment, sessionId, publishableKey, amountCents: options.amount,
+            syntheticPaymentMethodId: `pm_agentcard_checkout_${crypto.randomUUID().replaceAll('-', '')}` });
+    }
+    matches(url) { return !!this.binding && isStripeCheckoutEndpoint(url); }
+    isEnabled() { return !!this.binding; }
+    isPrepared() { return this.state !== 'fresh'; }
+    invalidate() { this.state = 'stopped'; this.billing = undefined; }
+    /** Observability only: this endpoint label never participates in a payment decision. */
+    describeRejection(error, rawUrl, stage, phase = 'unknown') {
+        let family = 'other';
+        try {
+            const url = new URL(rawUrl);
+            if (url.origin === 'https://api.stripe.com' && url.pathname === '/v1/payment_methods')
+                family = 'payment_methods';
+            else if (isStripeCheckoutEndpoint(rawUrl))
+                family = 'payment_page_confirm';
+        }
+        catch { /* No untrusted URL or parser error leaves this method. */ }
+        const fallback = {
+            request_read: 'request_unavailable', classification: 'request_validation_failed', claim: 'preparation_unavailable',
+            readiness: 'readiness_unavailable', document: 'document_unavailable', stub_response: 'stub_response_failed',
+        };
+        const rejection = error instanceof StripeCheckoutRejectionError ? error : undefined;
+        return { version: 1, processor: 'stripe', endpoint_family: family,
+            phase: rejection?.phase ?? phase, stage: rejection?.stage ?? stage, reason: rejection?.reason ?? fallback[stage],
+            gate_state: this.state, disposition: error instanceof StripeCheckoutClaimConflictError ? 'active_claim_preserved' : 'checkout_stopped' };
+    }
+    assertClaim(step) {
+        if (this.state !== (step.phase === 'tokenization' ? 'stubbed' : 'submitted'))
+            throw new StripeCheckoutRejectionError('Native Stripe Checkout preparation is unavailable.', 'claim', 'claim_invalidated', step.phase);
+    }
+    /** Check the actual top-level hosted document before preparing either step. */
+    assertDocument(raw) {
+        if (!this.binding)
+            return;
+        const url = new URL(raw);
+        if (url.origin !== 'https://checkout.stripe.com' || url.username || url.password
+            || ![`/c/pay/${this.binding.sessionId}`, `/pay/${this.binding.sessionId}`].includes(url.pathname)) {
+            this.invalidate();
+            throw new StripeCheckoutRejectionError('Native Stripe Checkout document changed.', 'document', 'document_changed');
+        }
+    }
+    claim(request) {
+        if (!this.binding)
+            return null;
+        if (request.method.toUpperCase() !== 'POST')
+            return null;
+        let phase;
+        try {
+            phase = classifyStripeCheckoutRequest(request, this.binding);
+        }
+        catch {
+            throw new StripeCheckoutRejectionError('stripe_checkout_rejected', 'classification', 'request_validation_failed', 'unknown');
+        }
+        if (!phase)
+            return null;
+        const diagnosticPhase = phase.phase === 'tokenization' ? 'tokenization' : phase.phase === 'final' ? 'final' : 'unknown';
+        if (Object.keys(request.headers).some(name => name.toLowerCase() === STRIPE_CHECKOUT_CONTEXT_HEADER))
+            throw new StripeCheckoutRejectionError('Native Stripe Checkout already carries a context.', 'claim', 'context_already_present', diagnosticPhase);
+        if (phase.phase === 'tokenization') {
+            if (this.state === 'stubbed' || this.state === 'submitted')
+                throw new StripeCheckoutClaimConflictError('tokenization');
+            if (this.state !== 'fresh')
+                throw new StripeCheckoutRejectionError('Native Stripe Checkout preparation is unavailable.', 'claim', 'preparation_unavailable', 'tokenization');
+            this.state = 'stopped';
+            let response;
+            try {
+                this.billing = captureStripeCheckoutBilling(request, this.binding);
+                response = createStripeCheckoutTokenizationStub(request, this.binding);
+            }
+            catch {
+                throw new StripeCheckoutRejectionError('stripe_checkout_rejected', 'stub_response', 'stub_response_failed', 'tokenization');
+            }
+            this.state = 'stubbed';
+            return { phase: 'tokenization', response };
+        }
+        if (phase.phase === 'final' && this.state === 'submitted')
+            throw new StripeCheckoutClaimConflictError('final');
+        if (phase.phase !== 'final' || this.state !== 'stubbed')
+            throw new StripeCheckoutRejectionError('Native Stripe Checkout has no matching prepared request.', 'claim', 'preparation_missing', diagnosticPhase);
+        let final;
+        try {
+            final = attachStripeCheckoutBilling(request, this.billing, this.binding);
+        }
+        catch {
+            this.invalidate();
+            throw new StripeCheckoutRejectionError('stripe_checkout_rejected', 'classification', 'request_validation_failed', 'final');
+        }
+        this.state = 'submitted';
+        this.billing = undefined;
+        return { phase: 'final', request: { ...final, headers: { ...final.headers,
+                    [STRIPE_CHECKOUT_CONTEXT_HEADER]: encodeStripeCheckoutContext({ version: 1,
+                        session_id: this.binding.sessionId, synthetic_payment_method_id: this.binding.syntheticPaymentMethodId }) } } };
+    }
+}

package/examples/preflight/kernel-native/inventory.json

@@ -1,7 +1,7 @@
 {
   "schema_version": 1,
-  "catalog_version": "2026-09-11.2",
-  "catalog_sha256": "367915b082fe3360cd6a9115feaeb8edeb0e8493388cee88557c8a5a12eff821",
+  "catalog_version": "2026-09-14.1",
+  "catalog_sha256": "c5bf9f8f7372def80d2abf0e9f2942c1b33514ed516b66d3f60e98c11d43bf5c",
   "baseline_version": "kernel-native-docs-2026-09-11.1",
   "baseline_sha256": "d86722f49633d8223fccae54cd3d485df4375aee06aa156a273cc689b7c8507c",
   "native_build": null,

package/examples/preflight/kernel-profile.empty.json

@@ -1,7 +1,7 @@
 {
   "schema_version": 1,
   "profile_version": "kernel-template-1",
-  "catalog_version": "2026-09-11.2",
+  "catalog_version": "2026-09-14.1",
   "integration": {
     "id": "kernel_native",
     "version": "example-native-adapter"

package/examples/preflight/mollie-hosted.result.json

@@ -1,7 +1,7 @@
 {
   "snapshot": {
     "schema_version": 1,
-    "catalog_version": "2026-09-11.2",
+    "catalog_version": "2026-09-14.1",
     "signals": [
       {
         "rule_id": "mollie-hosted-credit-card",
@@ -33,7 +33,7 @@
   },
   "result": {
     "schema_version": 1,
-    "catalog_version": "2026-09-11.2",
+    "catalog_version": "2026-09-14.1",
     "integration": {
       "id": "kernel_native",
       "version": "example-native-adapter"

package/examples/preflight/stripe-script.direct.result.json

@@ -1,7 +1,7 @@
 {
   "snapshot": {
     "schema_version": 1,
-    "catalog_version": "2026-09-11.2",
+    "catalog_version": "2026-09-14.1",
     "signals": [
       {
         "rule_id": "stripe-js-v3",
@@ -26,7 +26,7 @@
   },
   "result": {
     "schema_version": 1,
-    "catalog_version": "2026-09-11.2",
+    "catalog_version": "2026-09-14.1",
     "integration": {
       "id": "direct_sdk",
       "version": "bundled"

package/examples/preflight/stripe-script.result.json

@@ -1,7 +1,7 @@
 {
   "snapshot": {
     "schema_version": 1,
-    "catalog_version": "2026-09-11.2",
+    "catalog_version": "2026-09-14.1",
     "signals": [
       {
         "rule_id": "stripe-js-v3",
@@ -26,7 +26,7 @@
   },
   "result": {
     "schema_version": 1,
-    "catalog_version": "2026-09-11.2",
+    "catalog_version": "2026-09-14.1",
     "integration": {
       "id": "kernel_native",
       "version": "example-native-adapter"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-cards/checkout",
-  "version": "0.9.1",
+  "version": "0.11.0",
   "description": "Let browser agents pay with the user's own card, without your infrastructure ever touching card data.",
   "type": "module",
   "main": "dist/index.js",
@@ -27,7 +27,7 @@
     "_comment_build": "The public SDK keeps zero runtime dependencies. Its build vendors deterministic metadata and substitution artifacts from the internal payment core; TypeScript remains pinned.",
     "build": "node ../payment-core/scripts/build.mjs && node scripts/generate-payment-core.mjs && npx -y -p typescript@5.9.3 tsc && node scripts/generate-preflight-contract.mjs",
     "prepublishOnly": "pnpm build",
-    "test": "node test.mjs && node --test lifecycle.test.mjs merchant-abort.test.mjs preparation.test.mjs braintree.test.mjs autopilot.test.mjs payment-core.test.mjs prepared-processor.test.mjs minimum-delay.test.mjs paysafe.test.mjs attachment.test.mjs && node --test preflight-package.test.mjs preflight-collector.test.mjs && node --test kernel-native-qualification.test.mjs",
+    "test": "node test.mjs && node --test lifecycle.test.mjs merchant-abort.test.mjs preparation.test.mjs braintree.test.mjs autopilot.test.mjs stripe-checkout.test.mjs payment-core.test.mjs prepared-processor.test.mjs minimum-delay.test.mjs paysafe.test.mjs attachment.test.mjs mercado-checkout.test.mjs mercado-polling.test.mjs && node --test preflight-package.test.mjs preflight-collector.test.mjs && node --test kernel-native-qualification.test.mjs",
     "test:browser": "node browser.test.mjs && node stripe-browser.test.mjs && node preparation-browser.test.mjs && node owned-shop-browser.test.mjs",
     "check:payment-core": "node scripts/generate-payment-core.mjs --check",
     "test:preflight": "node --test preflight-package.test.mjs preflight-collector.test.mjs kernel-native-qualification.test.mjs",