@agent-cards/checkout 0.6.0 → 0.8.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 0.8.0
+
+- Clear an earlier failure or authentication reason when the merchant confirms a completed order. The final checkout state retains the authorization, order and payment mode without carrying a stale error.
+
+- Pass execution routing metadata through authorization and browser attachment with `executionMode`, `grantId` and `merchantOrigin`. The exported `ExecutionMetadata` type describes the result; the matching API and Vault determine whether the user approves the purchase or an existing grant applies. Autopilot execution remains limited to the configured controlled Stripe test flow, with production Autopilot disabled.
+- Share generated processor metadata with the payment core while keeping the published SDK free of runtime package dependencies.
+
+## 0.7.0
+
+- A company can put rules on the Vault purchases it chooses (a merchant list, a currency, a spend cap, a time window) by attaching a named preset to a stored card. A purchase the rules refuse now surfaces as `PresetRefusedError`, a typed decline: at stage `create` no authorization exists and nobody was asked; at stage `pre_replay` the authorization is `declined` with the rule's reason. It carries `code`, `presetName`, `rule`, `preset`, `attachment` (the card with its last four digits) and the rule's own statement; when several presets refuse the same purchase, `refusals` names every one and the other fields are the first. The adapters quiet the page's retry as for any decline, and a create-time refusal is never treated as a permanent misconfiguration.
+- Requires the matching API and Vault release.
+
 ## 0.6.0
 
 - Recognize Paysafe Checkout 1.8's exact hosted tokenization endpoints and preserve its native credential and correlation headers. The matching API registry and Vault deployment are required.

package/README.md

@@ -54,30 +54,28 @@ await attachToCdp(cdp, pageSessionId, {
   vault,
   user: 'usr_123',                 // whose card should pay
   merchant: 'vanman.shop',
-  amountCents: 583,                // what the user approves, smallest currency unit
+  amount: 583,                     // your hint, an integer in the currency's smallest unit (or a decimal string: '5.83')
   currency: 'usd',                 // "$5.83" is derived for the approval screen
   onApprovalUrl: (url) => sendToUser(url),   // iMessage, SMS, push, your call
 });
 ```
 
-`amount: '$5.83'` (a display string) still works on its own. Pass
-`amountCents` + `currency` when you want the amount enforced: on a Stripe
-PaymentIntent confirm, Agentcard reads the intent back from Stripe at create
-and again right before the cardholder's device replays, a different amount is
-refused with nothing charged, and after the replay the charge is reconciled
-against the approval (`ReplayResponse.amountVerified`, with
-`chargedAmountCents` and `chargedKind`: `captured` for a succeeded intent's
-`amount_received`, `authorized` for a manual-capture intent's
-`amount_capturable`, `none` when nothing is collected yet; plus the
-`checkout_authorization.amount_mismatch` webhook to your server when it
-disagrees). Amounts are Stripe minor units up to 2^53-1. `onEvent` payloads
-name URLs by origin and path only, so a client secret in a paused request's
-query string never reaches your telemetry. When you pass the pair, any
-`amount` string you also pass is
-ignored: Agentcard derives the display string from the number, following
-Stripe's minor units, so the approval screen, the notifications and every
-read show one amount. Tokenization requests carry no amount, so there the
-pair is shown and reported (`amountAuthority: 'display_only'`), not enforced.
+`amount` is your hint: an integer in the currency's smallest unit (583 for
+$5.83), or a decimal string in normal units ('5.83'), with `currency`. The
+processor's own amount is the higher authority: Agentcard reads it from the
+paused request where the processor puts it there, or from the Stripe intent
+the request names, right before the cardholder's device replays, and the
+company's caps are judged on it. A hint lets a bad purchase be refused the
+moment it opens; a hint more than one smallest unit away from the processor's
+amount is refused with nothing charged (`AmountMismatchError`), and after the
+replay the charge is reconciled against the approval
+(`ReplayResponse.amountVerified`, `chargedAmount`, and `chargedKind`:
+`captured` for a succeeded intent's `amount_received`, `authorized` for a
+manual-capture intent's `amount_capturable`, `none` when nothing is collected
+yet; plus the `checkout_authorization.amount_mismatch` webhook to your server
+when the charge disagreed). Every result carries `amountAuthority`:
+`processor`, `agent`, `page`, or `none`. A display string is never sent;
+Agentcard derives it.
 
 Then let your agent click "Pay" like it always does. `attachToCdp` pauses the
 request for approval and resumes it only while the merchant request remains
@@ -129,7 +127,7 @@ Coverage is specific to the processor request format, merchant setup, browser tr
 | Processor | Status |
 |---|---|
 | Shopify | supported, verified end to end |
-| Stripe | tokenization replay and direct card-bearing PaymentIntent confirms are implemented; direct confirms with `amountCents` + `currency` use backend amount verification. Browser token-to-intent continuation is unsupported and held. Validate the exact merchant flow before pilot use |
+| Stripe | tokenization replay and direct card-bearing PaymentIntent confirms are implemented; direct confirms read the intent's amount back from Stripe; a hint sent as `amount` + `currency` must agree with it. Browser token-to-intent continuation is unsupported and held. Validate the exact merchant flow before pilot use |
 | Braintree card tokenization | Prepared checkout supported; one live Haymarket Books ebook purchase with SDK `0.5.0` confirmed merchant fulfillment and SDK `completed` using a merchant receipt resolver. Independent processor capture/settlement, live 3DS and PayPal wallet flows remain unverified. |
 | Checkout.com | supported |
 | VGS Collect (Very Good Security; Wolt) | not supported: VGS's proxy aliases only submissions from its own iframe, so a replay from the cardholder's device is refused by the merchant (verified on Wolt, 2026-09-03). Not recognized, so the agent's browser is not paused there |
@@ -352,7 +350,7 @@ value continues to work. Choose `requireMerchantResult: true` for a pilot:
 
 ```ts
 const checkout = await attachToPlaywright(page, {
-  vault, user, merchant, amountCents, currency,
+  vault, user, merchant, amount, currency,
   requireMerchantResult: true,
   onStateChange: state => recordState(state),
   onUserAction: action => deliverPrivatelyToUser(action),
@@ -395,7 +393,7 @@ Unrecognized merchant-server endpoints remain outside this guard unless listed
 in `paymentEndpoints`; this is not a guarantee against a merchant charging a
 saved token on its own server.
 A direct card-bearing PaymentIntent confirm remains supported with the backend's
-existing amount verification when `amountCents` and `currency` are supplied.
+existing amount verification when `amount` and `currency` are supplied.
 
 Hosted-form submissions also always stay blocked because their payment outcome
 is unverified. `reconcile()` calls the resolver once, coalescing concurrent calls.
@@ -417,7 +415,7 @@ Prepare a Square, Braintree, Worldpay, Bambora or Mercado Pago checkout before t
 ```ts
 const checkout = await attachToPlaywright(page, {
   vault, user: 'your-user-id', merchant: 'Example merchant',
-  amountCents: 100, currency: 'USD',
+  amount: 100, currency: 'USD',
   onApprovalUrl: deliverPrivatelyToCardholder,
 });
 const preparation = await checkout.prepare({
@@ -429,7 +427,7 @@ const preparation = await checkout.prepare({
 await page.getByRole('button', { name: 'Pay', exact: true }).click();
 ```
 
-`prepare()` is available on both Playwright and raw CDP controllers. It requires `amountCents` and `currency`, must precede the first recognized card request, and returns only when the cardholder's device is ready. It delivers the preparation URL through `onApprovalUrl` and `onUserAction`; binding the subsequent authorization sends no second approval link or SMS. The phone page must stay open. Its selected card, merchant origin, declared merchant, amount, currency, processor and environment bind one fresh request. The amount remains `display_only`; a card token does not enforce the merchant's eventual charge amount.
+`prepare()` is available on both Playwright and raw CDP controllers. It requires `amount` and `currency`, must precede the first recognized card request, and returns only when the cardholder's device is ready. It delivers the preparation URL through `onApprovalUrl` and `onUserAction`; binding the subsequent authorization sends no second approval link or SMS. The phone page must stay open. Its selected card, merchant origin, declared merchant, amount, currency, processor and environment bind one fresh request. The amount's authority is `agent`; a card token does not enforce the merchant's eventual charge amount.
 
 | Processor | `environment` | Fresh native request |
 | --- | --- | --- |
@@ -519,3 +517,12 @@ coverage classifications, `recognized_traffic_share` is traffic-weighted, and
 `purchase_success_rate` stays null without observed merchant outcomes. Do not
 substitute the assessor for a browser/merchant validation run or use native
 Kernel adapter coverage as evidence for this SDK's coverage.
+### Autopilot execution metadata
+
+When the cardholder has enabled an eligible spending rule in their vault, the same authorization can run through autopilot. The SDK keeps polling the existing authorization and returns optional `executionMode: 'autopilot' | 'user_approval'` and `grantId` metadata. Older API responses remain supported.
+
+`authorize()` accepts optional `executionMode` and `grantId` routing hints, sent as `execution_mode` and `grant_id`. These never establish permission to spend; the protected payment service checks the cardholder's signed rule. Autopilot suppresses `onApprovalUrl` while it is executing. A definite fallback to user approval delivers the existing authorization's URL once. A lost outcome remains `PaymentOutcomeUnknownError`; it does not create or submit a second payment.
+
+Use `executionMode: 'user_approval'` to require the existing confirmation flow. Without a selected card or grant, the backend can use exactly one eligible rule; ambiguous card selection keeps confirmation. A `grantId` restricts selection to that rule. The initial executor supports only the configured controlled Stripe test flow, and production remains disabled.
+
+The adapters also send the observed top-level HTTPS `merchantOrigin`, such as `https://shop.example`, without a path, query or trailing slash. Direct `authorize()` callers can supply that origin explicitly. It is a routing hint; the protected adapter independently verifies the processor account, payee and amount. If a browser cannot provide its top-level URL, an explicit `merchantOrigin` option can supply the hint; otherwise the regular approval path remains available.

package/dist/braintree.d.ts

@@ -1,10 +1,2 @@
-/** Classify native Braintree GraphQL requests without changing their bytes. */
-export type BraintreeEnvironment = 'production' | 'sandbox';
-export type BraintreeRequestKind = 'configuration' | 'tokenization' | 'invalid';
-export declare function braintreeEnvironment(url: string): BraintreeEnvironment | undefined;
-/** Bounded duplicate-aware JSON for fresh-card preparation bodies. */
-export declare function readTokenizationJson(body: string | null): Record<string, unknown> | null;
-/** Undefined belongs to another processor; invalid Braintree requests stay blocked. */
-export declare function classifyBraintreeRequest(url: string, method: string, body: string | null): BraintreeRequestKind | undefined;
-/** Preparation accepts guest tokenization only; ordinary interception stays broader. */
-export declare function isPreparedBraintreeRequest(body: string | null): boolean;
+export { braintreeEnvironment, classifyBraintreeRequest, isPreparedBraintreeRequest, readTokenizationJson } from './braintree.generated.js';
+export type { BraintreeEnvironment, BraintreeRequestKind } from './braintree.generated.js';

package/dist/braintree.generated.d.ts

@@ -0,0 +1,10 @@
+/** Classify native Braintree GraphQL requests without changing their bytes. */
+export type BraintreeEnvironment = 'production' | 'sandbox';
+export type BraintreeRequestKind = 'configuration' | 'tokenization' | 'invalid';
+export declare function braintreeEnvironment(url: string): BraintreeEnvironment | undefined;
+/** Bounded duplicate-aware JSON for fresh-card preparation bodies. */
+export declare function readTokenizationJson(body: string | null): Record<string, unknown> | null;
+/** Undefined belongs to another processor; invalid Braintree requests stay blocked. */
+export declare function classifyBraintreeRequest(url: string, method: string, body: string | null): BraintreeRequestKind | undefined;
+/** Preparation accepts guest tokenization only; ordinary interception stays broader. */
+export declare function isPreparedBraintreeRequest(body: string | null): boolean;

package/dist/braintree.generated.js

@@ -0,0 +1,302 @@
+const PRODUCTION = 'https://payments.braintree-api.com/graphql';
+const SANDBOX = 'https://payments.sandbox.braintree-api.com/graphql';
+const MAX_BODY_LENGTH = 128 * 1024;
+const MAX_DEPTH = 32;
+const MAX_NODES = 10_000;
+export function braintreeEnvironment(url) {
+    return url === PRODUCTION ? 'production' : url === SANDBOX ? 'sandbox' : undefined;
+}
+function invalid() { throw new Error('invalid_braintree_request'); }
+function record(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+/** JSON.parse discards duplicate keys, so validate keys before using any value. */
+class JsonReader {
+    text;
+    at = 0;
+    nodes = 0;
+    constructor(text) {
+        this.text = text;
+    }
+    read() {
+        const value = this.value(0);
+        this.space();
+        if (this.at !== this.text.length)
+            invalid();
+        return value;
+    }
+    space() {
+        while (' \t\r\n'.includes(this.text[this.at] ?? '\0'))
+            this.at++;
+    }
+    take(expected) {
+        this.space();
+        if (this.text[this.at++] !== expected)
+            invalid();
+    }
+    string() {
+        this.space();
+        const start = this.at;
+        if (this.text[this.at++] !== '"')
+            invalid();
+        while (this.at < this.text.length) {
+            const char = this.text[this.at++];
+            if (char === '\\') {
+                this.at++;
+                continue;
+            }
+            if (char === '"')
+                return JSON.parse(this.text.slice(start, this.at));
+        }
+        return invalid();
+    }
+    value(depth) {
+        if (depth > MAX_DEPTH || ++this.nodes > MAX_NODES)
+            invalid();
+        this.space();
+        const char = this.text[this.at];
+        if (char === '"')
+            return this.string();
+        if (char === '{') {
+            this.at++;
+            const result = Object.create(null);
+            const keys = new Set();
+            this.space();
+            if (this.text[this.at] === '}') {
+                this.at++;
+                return result;
+            }
+            while (true) {
+                const key = this.string();
+                if (keys.has(key))
+                    invalid();
+                keys.add(key);
+                this.take(':');
+                result[key] = this.value(depth + 1);
+                this.space();
+                const next = this.text[this.at++];
+                if (next === '}')
+                    return result;
+                if (next !== ',')
+                    invalid();
+            }
+        }
+        if (char === '[') {
+            this.at++;
+            const result = [];
+            this.space();
+            if (this.text[this.at] === ']') {
+                this.at++;
+                return result;
+            }
+            while (true) {
+                result.push(this.value(depth + 1));
+                this.space();
+                const next = this.text[this.at++];
+                if (next === ']')
+                    return result;
+                if (next !== ',')
+                    invalid();
+            }
+        }
+        for (const [literal, value] of [['true', true], ['false', false], ['null', null]]) {
+            if (this.text.startsWith(literal, this.at)) {
+                this.at += literal.length;
+                return value;
+            }
+        }
+        const number = /^-?(?:0|[1-9][0-9]*)(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?/.exec(this.text.slice(this.at));
+        if (!number)
+            invalid();
+        this.at += number[0].length;
+        const value = Number(number[0]);
+        if (!Number.isFinite(value))
+            invalid();
+        return value;
+    }
+}
+/** Bounded duplicate-aware JSON for fresh-card preparation bodies. */
+export function readTokenizationJson(body) {
+    if (typeof body !== 'string' || body.length === 0 || body.length > MAX_BODY_LENGTH)
+        return null;
+    try {
+        const value = new JsonReader(body).read();
+        return record(value) ? value : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Native operations need names, punctuation and variables, never literals. */
+function lex(query) {
+    const tokens = [];
+    let at = 0;
+    while (at < query.length) {
+        const char = query[at];
+        if (' \t\r\n,'.includes(char)) {
+            at++;
+            continue;
+        }
+        if ('!$():{}'.includes(char)) {
+            tokens.push(char);
+            at++;
+        }
+        else if (/[A-Za-z_]/.test(char)) {
+            const start = at++;
+            while (at < query.length && /[A-Za-z_0-9]/.test(query[at]))
+                at++;
+            tokens.push(query.slice(start, at));
+        }
+        else
+            invalid(); // Includes comments, strings, fragments and directives.
+        if (tokens.length > MAX_NODES)
+            invalid();
+    }
+    return tokens;
+}
+class GraphqlReader {
+    tokens;
+    at = 0;
+    constructor(tokens) {
+        this.tokens = tokens;
+    }
+    peek() { return this.tokens[this.at]; }
+    take(expected) {
+        if (this.tokens[this.at++] !== expected)
+            invalid();
+    }
+    name() {
+        const value = this.tokens[this.at++];
+        if (!value || !/^[A-Za-z_][A-Za-z_0-9]*$/.test(value))
+            invalid();
+        return value;
+    }
+    read() {
+        const kind = this.name();
+        const name = this.name();
+        let inputDefinition = false;
+        if (this.peek() === '(') {
+            // No defaults, alternate types, unused variables or duplicate definitions.
+            for (const token of ['(', '$', 'input', ':', 'TokenizeCreditCardInput', '!', ')'])
+                this.take(token);
+            inputDefinition = true;
+        }
+        const fields = this.selection(0);
+        if (this.at !== this.tokens.length)
+            invalid();
+        return { kind, name, inputDefinition, fields };
+    }
+    selection(depth) {
+        if (depth > MAX_DEPTH)
+            invalid();
+        this.take('{');
+        const fields = [];
+        const names = new Set();
+        while (this.peek() !== '}') {
+            const name = this.name();
+            if (names.has(name))
+                invalid();
+            names.add(name);
+            const args = [];
+            if (this.peek() === '(') {
+                if (depth !== 0)
+                    invalid();
+                this.take('(');
+                const argument = this.name();
+                this.take(':');
+                this.take('$');
+                args.push({ name: argument, variable: this.name() });
+                this.take(')');
+            }
+            const children = this.peek() === '{' ? this.selection(depth + 1) : [];
+            fields.push({ name, arguments: args, fields: children });
+            // Aliases, directives and other punctuation cannot begin the next field.
+        }
+        this.take('}');
+        if (fields.length === 0)
+            invalid();
+        return fields;
+    }
+}
+/** Undefined belongs to another processor; invalid Braintree requests stay blocked. */
+export function classifyBraintreeRequest(url, method, body) {
+    let hostname;
+    try {
+        hostname = new URL(url).hostname;
+    }
+    catch {
+        return undefined;
+    }
+    if (hostname !== 'payments.braintree-api.com' && hostname !== 'payments.sandbox.braintree-api.com')
+        return undefined;
+    if (!braintreeEnvironment(url) || method !== 'POST' || typeof body !== 'string' || body.length === 0 || body.length > MAX_BODY_LENGTH)
+        return 'invalid';
+    try {
+        const envelope = new JsonReader(body).read();
+        if (!record(envelope) || typeof envelope.query !== 'string' || typeof envelope.operationName !== 'string')
+            return 'invalid';
+        if (Object.keys(envelope).some(key => !['query', 'operationName', 'variables', 'clientSdkMetadata'].includes(key)))
+            return 'invalid';
+        if (envelope.clientSdkMetadata !== undefined && !record(envelope.clientSdkMetadata))
+            return 'invalid';
+        const operation = new GraphqlReader(lex(envelope.query)).read();
+        if (operation.name !== envelope.operationName || operation.fields.length !== 1)
+            return 'invalid';
+        const root = operation.fields[0];
+        if (root.fields.length === 0)
+            return 'invalid';
+        const variables = envelope.variables === undefined ? Object.create(null) : envelope.variables;
+        if (!record(variables))
+            return 'invalid';
+        if (operation.kind === 'query' && ['ClientConfiguration', 'ClientConfigurationQuery'].includes(operation.name)
+            && !operation.inputDefinition && root.name === 'clientConfiguration' && root.arguments.length === 0
+            && Object.keys(variables).length === 0)
+            return 'configuration';
+        if (operation.kind !== 'mutation' || operation.name !== 'TokenizeCreditCard' || !operation.inputDefinition
+            || root.name !== 'tokenizeCreditCard' || root.arguments.length !== 1
+            || root.arguments[0].name !== 'input' || root.arguments[0].variable !== 'input'
+            || Object.keys(variables).length !== 1 || !record(variables.input) || !record(variables.input.creditCard))
+            return 'invalid';
+        const card = variables.input.creditCard;
+        if (!['number', 'expirationMonth', 'expirationYear'].every(key => typeof card[key] === 'string' && card[key].trim().length > 0))
+            return 'invalid';
+        if (card.cvv !== undefined && (typeof card.cvv !== 'string' || card.cvv.trim().length === 0))
+            return 'invalid';
+        return 'tokenization';
+    }
+    catch {
+        return 'invalid';
+    }
+}
+/** Preparation accepts guest tokenization only; ordinary interception stays broader. */
+export function isPreparedBraintreeRequest(body) {
+    if (classifyBraintreeRequest(PRODUCTION, 'POST', body) !== 'tokenization')
+        return false;
+    try {
+        const envelope = new JsonReader(body).read();
+        const variables = envelope.variables;
+        const input = variables.input;
+        if (Object.keys(input).some(key => key !== 'creditCard' && key !== 'options'))
+            return false;
+        const card = input.creditCard;
+        if (Object.keys(card).some(key => !['number', 'expirationMonth', 'expirationYear', 'cvv', 'cardholderName', 'billingAddress'].includes(key)))
+            return false;
+        if (Object.entries(card).some(([key, value]) => key !== 'billingAddress' && typeof value !== 'string'))
+            return false;
+        if (card.billingAddress !== undefined) {
+            if (!record(card.billingAddress))
+                return false;
+            const addressKeys = ['postalCode', 'firstName', 'lastName', 'company', 'streetAddress', 'extendedAddress',
+                'locality', 'region', 'countryCodeNumeric', 'countryCodeAlpha2', 'countryCodeAlpha3', 'countryName'];
+            if (Object.entries(card.billingAddress).some(([key, value]) => !addressKeys.includes(key) || typeof value !== 'string'))
+                return false;
+        }
+        // Fingerprint authorization defaults validation on when the option is absent.
+        // Preparation permits only an explicit request for a transient card token.
+        return record(input.options) && Object.keys(input.options).every(key => key === 'validate')
+            && input.options.validate === false;
+    }
+    catch {
+        return false;
+    }
+}