@agent-cards/sdk 0.20.0

package/dist/registry.d.ts

@@ -0,0 +1,145 @@
+/**
+ * Which outbound requests carry a raw card, and where the card sits inside them.
+ *
+ * This is the only merchant-specific knowledge in the system, and it is keyed by
+ * PSP rather than by merchant: every Shopify store shares one entry, every Stripe
+ * site shares another. The list is served from the Agentcard API at runtime so
+ * integrators pick up new processors without shipping a release.
+ */
+export type Encoding = 'json' | 'form';
+/**
+ * How a paused request gets its card. `token` (the default when absent): the
+ * cardholder's device calls the processor and the runtime replays the
+ * processor's response. `cse`: the processor encrypts the card in-page
+ * (Adyen); the device returns ciphertext and the runtime substitutes it into
+ * the paused body and lets the request continue. `hosted_form`: the device
+ * submits the processor's own form and the paused request resolves with no
+ * processor answer (served only to SDKs that ask for it on sync).
+ */
+export type CheckoutMode = 'token' | 'cse' | 'hosted_form';
+export interface Recognizer {
+    /** Stable id, e.g. "shopify" */
+    psp: string;
+    /** Matches the tokenization endpoint. */
+    match: RegExp;
+    /**
+     * Anchored (`^…$`) regex SOURCES for the hostnames this PSP may ever receive
+     * a card on — the server's own allowlist, served next to `match` and carried
+     * through syncRegistry() verbatim.
+     *
+     * Strings, not RegExps, because that is the wire shape and because nothing
+     * here matches with them: they exist so a transport that can only pre-filter
+     * by URL (CDP's `Fetch.enable`, which takes globs) can be armed from the
+     * registry instead of a hardcoded list. Optional so a hand-built registry
+     * (tests, pinning) still type-checks.
+     */
+    hosts?: string[];
+    encoding: Encoding;
+    /**
+     * Request headers that must be replayed verbatim for the merchant to accept
+     * the call (signatures, client tokens). Matched case-insensitively.
+     */
+    passthroughHeaders: RegExp[];
+    /**
+     * Form keys that carry the card number. When present, a request on this
+     * recognizer's endpoints is a card request only if its body carries one of
+     * them: a Stripe confirmation that pays with a method the page already
+     * created (`payment_method=pm_...`) carries none, so there is nothing for
+     * the cardholder to approve. Served by the API and carried through
+     * syncRegistry() verbatim.
+     */
+    cardFields?: string[];
+    /**
+     * The JSON counterpart of cardFields, read on a JSON recognizer only: paths
+     * of object keys and array indices to the members that carry the card
+     * number or the encrypted card, such as ['payment_source', 'card', 'number'].
+     * A request is a card request only if one of them holds a non-empty string
+     * or a number, so a wallet or saved-card payment sent to the same endpoint
+     * is not. Carried through syncRegistry() verbatim.
+     */
+    jsonCardFields?: (string | number)[][];
+    /**
+     * With cardFields or jsonCardFields: the endpoints (regex source over
+     * hostname + pathname, anchored) where a request without a card is routine
+     * and never ours, so it continues untouched; a request without a card
+     * anywhere else is refused.
+     */
+    passWithoutCard?: string;
+    /**
+     * True when the card is encrypted inside the page before the request leaves.
+     * A digit swap is useless here; the vault must re-run the PSP's client-side
+     * crypto instead. Refused locally unless the entry also carries
+     * `mode: 'cse'`, which says the vault does exactly that.
+     */
+    clientSideEncrypted?: boolean;
+    /** How the card reaches the processor; absent means 'token'. Carried verbatim by syncRegistry. */
+    mode?: CheckoutMode;
+    /**
+     * Dark launch: a capability name the API attaches to an entry it serves only
+     * to a client that declared it (?capabilities=). Absent on every entry in
+     * BUILTIN_REGISTRY, because a gated entry is left out of the built-in
+     * fallback. Carried verbatim by syncRegistry for a client that does declare
+     * it, so the SDK never has to act on it.
+     */
+    capability?: string;
+    /**
+     * True when this processor cannot be taken over on an ordinary authorization:
+     * the cardholder must have approved a prepare() first. authorize() refuses
+     * such a request locally, before it prompts, when no preparation is active
+     * (PreparationRequiredError), and the API answers 409 preparation_required.
+     * Absent on every BUILTIN_REGISTRY entry today and carried verbatim by
+     * syncRegistry for a build that reaches a processor which sets it.
+     */
+    preparationRequired?: boolean;
+    /**
+     * Anchored regex SOURCES (a subset of `hosts`) marking the vendor's
+     * SANDBOX/TEST hostnames, so the backend and the device can tell a test host
+     * from a live one. Carried verbatim by syncRegistry; the SDK never matches
+     * with them (recognition still uses `hosts`), so it acts on neither this nor
+     * the pin below. Present in BUILTIN_REGISTRY for the host-separated processors.
+     */
+    sandboxHosts?: string[];
+    /**
+     * True when a processor's host environment is enforced: the API refuses a
+     * create whose host environment disagrees with the row's test/live nature, and
+     * the device sends only documented test cards to a sandbox host. Absent on
+     * every entry today; carried verbatim by syncRegistry, and the SDK never acts
+     * on it.
+     */
+    hostEnvironmentPinned?: boolean;
+}
+import { BUILTIN_REGISTRY } from './builtin-registry.generated.js';
+export { BUILTIN_REGISTRY };
+/** How the recogniser reads a URL. `sandbox`: the client's credentials are sandbox credentials. */
+export interface RecognizerOptions {
+    /**
+     * With sandbox credentials a local fixture store is a store too: `http://127.0.0.1[:port]` and
+     * `http://localhost[:port]` are recognised by their path against each processor's endpoints, so a
+     * request the fixture posts to itself pauses as one to the processor would. Production is unchanged:
+     * https only, no port.
+     */
+    sandbox?: boolean;
+}
+/** True for a plain-http loopback address (`127.0.0.1` or `localhost`, any port); the only http a sandbox recogniser admits. */
+export declare function isLoopbackUrl(parsed: URL): boolean;
+/** The glob patterns that pause every loopback request under a sandbox client; `isCardRequest` is the exact check. */
+export declare const LOOPBACK_URL_PATTERNS: readonly string[];
+export declare function findRecognizer(url: string, registry?: Recognizer[], opts?: RecognizerOptions): Recognizer | null;
+/**
+ * True when this processor cannot be taken over on an ordinary authorization:
+ * the cardholder must have approved a prepare() first (the `preparationRequired`
+ * field above). authorize() applies this before it prompts and refuses with
+ * PreparationRequiredError when no preparation is active; the API answers 409
+ * preparation_required for the same case. This is the SAME rule payment-core's
+ * recognizerRequiresPreparation applies on the server, a strict `=== true`, so a
+ * value that rode in over the wire (syncRegistry spreads the served JSON) cannot
+ * turn a truthy string into a gate. Absent on every BUILTIN_REGISTRY entry, so
+ * this is false for all 24 today.
+ */
+export declare function recognizerRequiresPreparation(rec: Pick<Recognizer, 'preparationRequired'>): boolean;
+/**
+ * Glob url patterns covering every host in `registry` — what to hand
+ * `Fetch.enable` so a card request is ever paused. Deliberately a superset of
+ * the recognizers; isCardRequest is the exact check.
+ */
+export declare function cardUrlPatterns(registry: Recognizer[]): string[];

package/dist/registry.js

@@ -0,0 +1,338 @@
+/**
+ * Which outbound requests carry a raw card, and where the card sits inside them.
+ *
+ * This is the only merchant-specific knowledge in the system, and it is keyed by
+ * PSP rather than by merchant: every Shopify store shares one entry, every Stripe
+ * site shares another. The list is served from the Agentcard API at runtime so
+ * integrators pick up new processors without shipping a release.
+ */
+// Pinned fallback generated from the single shared processor catalog.
+import { BUILTIN_REGISTRY } from './builtin-registry.generated.js';
+export { BUILTIN_REGISTRY };
+/** True for a plain-http loopback address (`127.0.0.1` or `localhost`, any port); the only http a sandbox recogniser admits. */
+export function isLoopbackUrl(parsed) {
+    return parsed.protocol === 'http:' && (parsed.hostname === '127.0.0.1' || parsed.hostname === 'localhost') && !parsed.username && !parsed.password;
+}
+/** The glob patterns that pause every loopback request under a sandbox client; `isCardRequest` is the exact check. */
+export const LOOPBACK_URL_PATTERNS = ['http://127.0.0.1*', 'http://localhost*'];
+/**
+ * The literal hostnames an anchored host regex source names (`^api\\.stripe\\.com$` is `api.stripe.com`);
+ * a source with any other regex construct names none. A loopback path is judged as if it were on each.
+ */
+function literalHosts(sources) {
+    const out = [];
+    for (const source of sources ?? []) {
+        const bare = source.replace(/^\^/, '').replace(/\$$/, '');
+        const literal = bare.replace(/\\\./g, '.');
+        if (/^[a-z0-9.-]+$/i.test(literal) && !/[\\^$*+?()[\]{}|]/.test(bare.replace(/\\\./g, '')))
+            out.push(literal.toLowerCase());
+    }
+    return out;
+}
+export function findRecognizer(url, registry = BUILTIN_REGISTRY, opts = {}) {
+    // Match the way the SERVER does, on the PARSED url — never as a substring of
+    // the raw string. `match` is unanchored, so a raw-string test classifies any
+    // URL that merely CONTAINS a tokenizer endpoint as a card request:
+    //   https://evil.com/?next=https://api.stripe.com/v1/tokens
+    // The server refuses that (its hosts[] are anchored against URL.hostname), so
+    // the request could not be intercepted anyway — but the SDK had already paused
+    // it, and a pause it cannot complete becomes an ABORT. That turns an
+    // integrator's unrelated POST into a failed request.
+    //
+    // hosts[] is synced from the API precisely so the client can apply the server's
+    // own allowlist. Use it when present, and fall back to matching `match`
+    // against "hostname + pathname" (not the query) for a registry served by an
+    // older API that predates the field.
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        return null;
+    }
+    // Decision 178: with sandbox credentials a loopback fixture store is judged by its path, as if it were
+    // on each processor's own host; nothing else about the rule changes, and production never gets here.
+    if (opts.sandbox && isLoopbackUrl(parsed)) {
+        return (registry.find((r) => {
+            const anchored = new RegExp(`^(?:${r.match.source})$`, 'i');
+            return literalHosts(r.hosts).some((host) => anchored.test(`${host}${parsed.pathname}`));
+        }) ?? null);
+    }
+    if (parsed.protocol !== 'https:' || parsed.port || parsed.username || parsed.password)
+        return null;
+    const hostPath = `${parsed.hostname.toLowerCase()}${parsed.pathname}`;
+    return (registry.find((r) => {
+        if (r.hosts && r.hosts.length > 0) {
+            const hostAllowed = r.hosts.some((h) => new RegExp(h, 'i').test(parsed.hostname));
+            if (!hostAllowed)
+                return false;
+        }
+        // FULLY ANCHORED, exactly as the server does it. Unanchored, any EXTENSION
+        // of a valid path is admitted on a legitimate processor host
+        // (api.stripe.com/v1/tokens/anything), which the service then refuses —
+        // and a pause the SDK cannot complete becomes an abort.
+        return new RegExp(`^(?:${r.match.source})$`, 'i').test(hostPath);
+    }) ?? null);
+}
+/**
+ * True when this processor cannot be taken over on an ordinary authorization:
+ * the cardholder must have approved a prepare() first (the `preparationRequired`
+ * field above). authorize() applies this before it prompts and refuses with
+ * PreparationRequiredError when no preparation is active; the API answers 409
+ * preparation_required for the same case. This is the SAME rule payment-core's
+ * recognizerRequiresPreparation applies on the server, a strict `=== true`, so a
+ * value that rode in over the wire (syncRegistry spreads the served JSON) cannot
+ * turn a truthy string into a gate. Absent on every BUILTIN_REGISTRY entry, so
+ * this is false for all 24 today.
+ */
+export function recognizerRequiresPreparation(rec) {
+    return rec.preparationRequired === true;
+}
+// ---------------------------------------------------------------------------
+// Registry -> CDP url patterns
+//
+// `Fetch.enable` takes GLOB url patterns (`*` = any run of characters, `?` =
+// exactly one, `\` escapes), never regexes, so the registry's anchored host
+// regexes have to be widened into globs before a raw-CDP integrator can arm
+// interception with them.
+//
+// These patterns are only a COARSE pre-filter. Every request they pause is
+// re-checked with the real recognizer (VaultClient.isCardRequest) before
+// anything is intercepted, so a pattern that is too BROAD costs one extra
+// continueRequest round-trip, while one that is too NARROW silently drops the
+// card request on the floor and the shopper pays with their own card. Every
+// conversion below therefore WIDENS: anything not expressible as a glob
+// (character classes, groups, quantifiers, lookarounds) becomes `*`.
+// ---------------------------------------------------------------------------
+/**
+ * Glob url patterns covering every host in `registry` — what to hand
+ * `Fetch.enable` so a card request is ever paused. Deliberately a superset of
+ * the recognizers; isCardRequest is the exact check.
+ */
+export function cardUrlPatterns(registry) {
+    const out = new Set();
+    for (const rec of registry ?? []) {
+        for (const pattern of recognizerUrlPatterns(rec))
+            out.add(pattern);
+    }
+    return [...out];
+}
+function recognizerUrlPatterns(rec) {
+    const hosts = Array.isArray(rec?.hosts) ? rec.hosts.filter((h) => typeof h === 'string') : [];
+    if (hosts.length > 0) {
+        // Host text ANYWHERE in the URL, not `*://host/*`. Two reasons: a URL with
+        // userinfo (`https://u:p@host/…`) still has `host` as its hostname so the
+        // registry matches it, and isCardRequest tests `match` unanchored against
+        // the raw URL, so a URL merely carrying the host in its query also
+        // "matches" client-side. Anchoring the scheme would arm narrower than
+        // either check.
+        //
+        // Lowercased because CDP matches these globs case-SENSITIVELY against the
+        // canonical url, and a canonical url's authority is always lowercase (the
+        // URL parser folds it before the request is ever issued) — the same
+        // normalization resolveRecognizerForUrl does with url.hostname. Do not
+        // "fix" this by wildcarding the letters: `*???.??????.???*` matches most of
+        // the web and would pause every request on the page.
+        return hosts.flatMap((h) => regexSourceToGlobs(h)).map((g) => wrap(g).toLowerCase());
+    }
+    // No hosts[] — a registry pinned before the field existed, or hand-built.
+    // Fall back to widening `match`, which is the predicate isCardRequest
+    // actually applies. Path case can matter to a glob (CDP matches
+    // case-sensitively) while a hostname is always lowercased by the URL parser,
+    // so arm both spellings rather than guess.
+    return regexSourceToGlobs(rec?.match?.source ?? '')
+        .map(wrap)
+        .flatMap((g) => (g === g.toLowerCase() ? [g] : [g, g.toLowerCase()]));
+}
+/** `a|b` at the top level is two independent hostnames, so it is two globs. */
+function regexSourceToGlobs(source) {
+    return splitTopLevelAlternation(source).map(branchToGlob);
+}
+function splitTopLevelAlternation(source) {
+    const parts = [];
+    let depth = 0;
+    let inClass = false;
+    let start = 0;
+    for (let i = 0; i < source.length; i++) {
+        const c = source[i];
+        if (c === '\\') {
+            i++;
+            continue;
+        }
+        if (inClass) {
+            if (c === ']')
+                inClass = false;
+            continue;
+        }
+        if (c === '[') {
+            inClass = true;
+            continue;
+        }
+        if (c === '(') {
+            depth++;
+            continue;
+        }
+        if (c === ')') {
+            depth = Math.max(0, depth - 1);
+            continue;
+        }
+        if (c === '|' && depth === 0) {
+            parts.push(source.slice(start, i));
+            start = i + 1;
+        }
+    }
+    parts.push(source.slice(start));
+    return parts;
+}
+/**
+ * One alternation-free regex source -> one glob. Literal characters survive;
+ * every construct that can match more than itself collapses to `*`. An empty
+ * result is `*` on purpose: an empty regex matches every hostname, so the glob
+ * that mirrors it has to match every URL.
+ */
+function branchToGlob(branch) {
+    const atoms = [];
+    let i = 0;
+    while (i < branch.length) {
+        const c = branch[i];
+        let atom;
+        if (c === '^' || c === '$') {
+            i += 1;
+            continue;
+        } // anchors constrain nothing in a glob
+        if (c === '\\') {
+            const next = branch[i + 1] ?? '';
+            i += 2;
+            // \d \w \s \b … are classes/assertions; only escaped punctuation (\., \-)
+            // is a literal character.
+            atom = /[A-Za-z0-9]/.test(next) ? '*' : globEscape(next);
+        }
+        else if (c === '[') {
+            i = skipCharClass(branch, i);
+            atom = '*';
+        }
+        else if (c === '(') {
+            i = skipGroup(branch, i); // groups, non-capturing groups, lookarounds
+            atom = '*';
+        }
+        else if (c === '.') {
+            i += 1;
+            atom = '*';
+        }
+        else if (c === ')' || c === ']') {
+            i += 1; // unbalanced closer: ignore rather than throw
+            continue;
+        }
+        else if (quantifierEnd(branch, i) !== null) {
+            // A quantifier with nothing in front of it. Widen whatever preceded it.
+            i = quantifierEnd(branch, i);
+            if (atoms.length > 0)
+                atoms[atoms.length - 1] = '*';
+            else
+                atoms.push('*');
+            continue;
+        }
+        else {
+            i += 1;
+            atom = globEscape(c);
+        }
+        // `x?` / `x*` / `x+` / `x{2,3}`: the atom is optional or repeatable, so the
+        // only glob that covers every string it accepts is `*`.
+        const after = quantifierEnd(branch, i);
+        if (after !== null) {
+            i = after;
+            atom = '*';
+        }
+        atoms.push(atom);
+    }
+    return collapse(atoms).join('');
+}
+/** Index just past a quantifier at `i`, or null when there isn't one. */
+function quantifierEnd(source, i) {
+    const c = source[i];
+    let end;
+    if (c === '*' || c === '+' || c === '?') {
+        end = i + 1;
+    }
+    else if (c === '{') {
+        const close = source.indexOf('}', i);
+        if (close === -1 || !/^\{\d+(,\d*)?\}$/.test(source.slice(i, close + 1)))
+            return null;
+        end = close + 1;
+    }
+    else {
+        return null;
+    }
+    if (source[end] === '?')
+        end += 1; // lazy quantifier
+    return end;
+}
+function skipCharClass(source, i) {
+    let j = i + 1;
+    if (source[j] === '^')
+        j++;
+    if (source[j] === ']')
+        j++; // a leading `]` is a literal
+    for (; j < source.length; j++) {
+        if (source[j] === '\\') {
+            j++;
+            continue;
+        }
+        if (source[j] === ']')
+            return j + 1;
+    }
+    return source.length;
+}
+function skipGroup(source, i) {
+    let depth = 0;
+    let inClass = false;
+    for (let j = i; j < source.length; j++) {
+        const c = source[j];
+        if (c === '\\') {
+            j++;
+            continue;
+        }
+        if (inClass) {
+            if (c === ']')
+                inClass = false;
+            continue;
+        }
+        if (c === '[') {
+            inClass = true;
+            continue;
+        }
+        if (c === '(') {
+            depth++;
+            continue;
+        }
+        if (c === ')') {
+            depth--;
+            if (depth === 0)
+                return j + 1;
+        }
+    }
+    return source.length;
+}
+/** `*` and `?` are the glob's own wildcards; `\` is its escape. */
+function globEscape(ch) {
+    return ch === '*' || ch === '?' || ch === '\\' ? `\\${ch}` : ch;
+}
+/** `**` matches exactly what `*` does; keep patterns readable. */
+function collapse(atoms) {
+    const out = [];
+    for (const a of atoms) {
+        if (a === '*' && out[out.length - 1] === '*')
+            continue;
+        out.push(a);
+    }
+    return out;
+}
+/** `…host…` -> `*host*`, without doubling a `*` the conversion already emitted. */
+function wrap(glob) {
+    let body = glob;
+    while (body.startsWith('*'))
+        body = body.slice(1);
+    while (body.length > 0 && body.endsWith('*') && !body.endsWith('\\*'))
+        body = body.slice(0, -1);
+    return body.length > 0 ? `*${body}*` : '*';
+}

package/dist/requests.d.ts

@@ -0,0 +1,66 @@
+/**
+ * The request builders registry: `agentcard.checkout.requests.*`. A paused
+ * request is what a purchase pauses on: the processor's card request, with
+ * a placeholder card the Vault replaces at approval. The registry ships
+ * Agentcard's own builders and takes yours at runtime, so a processor or a
+ * request shape Agentcard does not build yet needs no release of this
+ * package.
+ */
+import type { PausedRequest } from './client.js';
+/** One builder: for a processor and a kind of request, turns its input into the paused request. */
+export interface RequestBuilder<I = Record<string, unknown>> {
+    /** The processor as the recognisers name it (`stripe`). */
+    processor: string;
+    /** The request shape (`payment_intent_confirm`, `card_token`, `payment_method`). */
+    kind: string;
+    /** One line on what the request is, for `list()`. */
+    description?: string;
+    build(input: I): PausedRequest;
+}
+/** What `build` takes: the processor, the kind, and the builder's own input beside them. */
+export type BuildInput<I = Record<string, unknown>> = {
+    processor: string;
+    kind: string;
+} & I;
+/**
+ * A real test-mode PaymentIntent your server created for one order. The
+ * paused request confirms it with a placeholder card, from your own origin;
+ * the Vault replaces the card with the person's at approval.
+ */
+export interface MintedIntent {
+    id: string;
+    client_secret: string;
+    publishable_key: string;
+}
+/** The paused Stripe request for an order: `POST /v1/payment_intents/{pi}/confirm` with a placeholder card. */
+export declare function stripePaymentIntentConfirmRequest(input: {
+    origin: string;
+    intent: MintedIntent;
+}): PausedRequest;
+/** The paused Stripe request that tokenizes a card for your server to charge: `POST /v1/tokens` with a placeholder card. */
+export declare function stripeCardTokenRequest(input: {
+    origin: string;
+    publishable_key: string;
+}): PausedRequest;
+/** The paused Stripe request that creates a PaymentMethod for your server to attach or confirm with: `POST /v1/payment_methods` with a placeholder card. */
+export declare function stripePaymentMethodRequest(input: {
+    origin: string;
+    publishable_key: string;
+}): PausedRequest;
+/** The builders this package ships: the Stripe shapes Agentcard completes from a direct create today. */
+export declare const BUILTIN_REQUEST_BUILDERS: readonly RequestBuilder<any>[];
+/** `agentcard.checkout.requests`: the shipped builders plus yours, one registry. */
+export declare class RequestRegistry {
+    private readonly builders;
+    constructor(builtin?: readonly RequestBuilder<any>[]);
+    /** Adds a builder, or replaces the one with the same processor and kind. Refused (`invalid_request_builder`) without a processor, a kind and a `build` function. */
+    register<I>(entry: RequestBuilder<I>): void;
+    /** Every builder, shipped and registered. */
+    list(): RequestBuilder<any>[];
+    /** The builder for a processor and kind, or null. */
+    get(processor: string, kind: string): RequestBuilder<any> | null;
+    /** Builds the paused request. Refused (`unknown_request_kind`) before anything else when no builder names that processor and kind. */
+    build<I = Record<string, unknown>>(input: BuildInput<I>): PausedRequest;
+}
+/** @deprecated Use `agentcard.checkout.requests.build({ processor: 'stripe', kind: 'payment_intent_confirm', origin, intent })`. Kept for one release. */
+export declare function stripePaymentIntentConfirm(origin: string, intent: MintedIntent): PausedRequest;

package/dist/requests.js

@@ -0,0 +1,76 @@
+import { AgentcardError } from './voice-types.js';
+/** The placeholder card every builder puts in the request; the Vault replaces it at approval. */
+const PLACEHOLDER = { number: '4242424242424242', exp_month: '12', exp_year: '2030', cvc: '123' };
+/** The paused Stripe request for an order: `POST /v1/payment_intents/{pi}/confirm` with a placeholder card. */
+export function stripePaymentIntentConfirmRequest(input) {
+    return {
+        url: `https://api.stripe.com/v1/payment_intents/${input.intent.id}/confirm`,
+        method: 'POST',
+        headers: { origin: input.origin, 'content-type': 'application/x-www-form-urlencoded' },
+        body: new URLSearchParams({
+            client_secret: input.intent.client_secret,
+            key: input.intent.publishable_key,
+            'payment_method_data[type]': 'card',
+            'payment_method_data[card][number]': PLACEHOLDER.number,
+            'payment_method_data[card][exp_month]': PLACEHOLDER.exp_month,
+            'payment_method_data[card][exp_year]': PLACEHOLDER.exp_year,
+            'payment_method_data[card][cvc]': PLACEHOLDER.cvc,
+        }).toString(),
+    };
+}
+/** The paused Stripe request that tokenizes a card for your server to charge: `POST /v1/tokens` with a placeholder card. */
+export function stripeCardTokenRequest(input) {
+    return {
+        url: 'https://api.stripe.com/v1/tokens',
+        method: 'POST',
+        headers: { origin: input.origin, 'content-type': 'application/x-www-form-urlencoded' },
+        body: new URLSearchParams({ key: input.publishable_key, 'card[number]': PLACEHOLDER.number, 'card[exp_month]': PLACEHOLDER.exp_month, 'card[exp_year]': PLACEHOLDER.exp_year, 'card[cvc]': PLACEHOLDER.cvc }).toString(),
+    };
+}
+/** The paused Stripe request that creates a PaymentMethod for your server to attach or confirm with: `POST /v1/payment_methods` with a placeholder card. */
+export function stripePaymentMethodRequest(input) {
+    return {
+        url: 'https://api.stripe.com/v1/payment_methods',
+        method: 'POST',
+        headers: { origin: input.origin, 'content-type': 'application/x-www-form-urlencoded' },
+        body: new URLSearchParams({ key: input.publishable_key, type: 'card', 'card[number]': PLACEHOLDER.number, 'card[exp_month]': PLACEHOLDER.exp_month, 'card[exp_year]': PLACEHOLDER.exp_year, 'card[cvc]': PLACEHOLDER.cvc }).toString(),
+    };
+}
+/** The builders this package ships: the Stripe shapes Agentcard completes from a direct create today. */
+export const BUILTIN_REQUEST_BUILDERS = [
+    { processor: 'stripe', kind: 'payment_intent_confirm', description: 'Confirms a PaymentIntent your server created; input { origin, intent: { id, client_secret, publishable_key } }.', build: stripePaymentIntentConfirmRequest },
+    { processor: 'stripe', kind: 'card_token', description: 'Tokenizes the card for your server to charge; input { origin, publishable_key }.', build: stripeCardTokenRequest },
+    { processor: 'stripe', kind: 'payment_method', description: 'Creates a PaymentMethod for your server to confirm with; input { origin, publishable_key }.', build: stripePaymentMethodRequest },
+];
+const keyOf = (processor, kind) => `${processor}\u0000${kind}`;
+/** `agentcard.checkout.requests`: the shipped builders plus yours, one registry. */
+export class RequestRegistry {
+    builders = new Map();
+    constructor(builtin = BUILTIN_REQUEST_BUILDERS) {
+        for (const b of builtin)
+            this.builders.set(keyOf(b.processor, b.kind), b);
+    }
+    /** Adds a builder, or replaces the one with the same processor and kind. Refused (`invalid_request_builder`) without a processor, a kind and a `build` function. */
+    register(entry) {
+        if (!entry || typeof entry.processor !== 'string' || !entry.processor || typeof entry.kind !== 'string' || !entry.kind || typeof entry.build !== 'function') {
+            throw new AgentcardError('invalid_request_builder', 'A request builder names processor, kind and build(input).');
+        }
+        this.builders.set(keyOf(entry.processor, entry.kind), entry);
+    }
+    /** Every builder, shipped and registered. */
+    list() { return [...this.builders.values()]; }
+    /** The builder for a processor and kind, or null. */
+    get(processor, kind) { return this.builders.get(keyOf(processor, kind)) ?? null; }
+    /** Builds the paused request. Refused (`unknown_request_kind`) before anything else when no builder names that processor and kind. */
+    build(input) {
+        const { processor, kind, ...rest } = input;
+        const b = this.get(processor, kind);
+        if (!b)
+            throw new AgentcardError('unknown_request_kind', `No request builder for ${processor}/${kind}. Registered: ${this.list().map((x) => `${x.processor}/${x.kind}`).join(', ')}. Register one with checkout.requests.register({ processor, kind, build }).`);
+        return b.build(rest);
+    }
+}
+/** @deprecated Use `agentcard.checkout.requests.build({ processor: 'stripe', kind: 'payment_intent_confirm', origin, intent })`. Kept for one release. */
+export function stripePaymentIntentConfirm(origin, intent) {
+    return stripePaymentIntentConfirmRequest({ origin, intent });
+}

package/dist/spreedly.generated.d.ts

@@ -0,0 +1,10 @@
+declare var SPREEDLY_TOKEN_ENDPOINT: string;
+declare function isSpreedlyTokenRequest(url: any, method?: string): boolean;
+declare function isPreparedSpreedlyRequest(body: any): boolean;
+declare function isSpreedlyRequest(request: any): boolean;
+declare function injectSpreedlyCard(body: any, card: any): {
+    body: string;
+    where: string[];
+};
+declare function sanitizeSpreedlyTokenResponse(body: any): string;
+export { SPREEDLY_TOKEN_ENDPOINT, injectSpreedlyCard, isPreparedSpreedlyRequest, isSpreedlyRequest, isSpreedlyTokenRequest, sanitizeSpreedlyTokenResponse };