@agent-cards/sdk 0.20.0

package/dist/adyen.generated.d.ts

@@ -0,0 +1,24 @@
+/** Adyen Web Sessions payments request, before it consumes an approval.
+ * adyen-web (Drop-in and the Card component in the Sessions flow) posts one
+ * JSON body to /checkoutshopper/v1/sessions/{id}/payments on the merchant's
+ * Adyen host, with `clientKey` as its only query parameter, and carries the
+ * card as four JWE blobs under paymentMethod. Those four blobs are what the
+ * cardholder's device replaces; nothing else in the body is rewritten. Test
+ * and live are separate host families AND separate client-key prefixes, so a
+ * preparation names one of them and the request must agree on both. A body
+ * that pays with a stored card, carries a single encrypted blob, or asks
+ * Adyen to store the card is not the purchase the person approved and never
+ * consumes readiness. This module never rewrites a body.
+ */
+export type AdyenPreparationEnvironment = 'production' | 'sandbox';
+export declare const ADYEN_ENCRYPTED_CARD_FIELDS: readonly ["encryptedCardNumber", "encryptedExpiryMonth", "encryptedExpiryYear", "encryptedSecurityCode"];
+/** Which preparation environment a hostname belongs to: Adyen's test host, one of its live host families, or neither. */
+export declare function adyenPreparationEnvironment(hostname: string): AdyenPreparationEnvironment | null;
+/** The URL a preparation advertises for the approved host family: every registry recognizes it, and it is never a real session. */
+export declare function adyenPreparationUrl(environment: AdyenPreparationEnvironment): string;
+/** A Sessions payments URL on the approved host family whose only query is a client key of that same environment. */
+export declare function isPreparedAdyenUrl(rawUrl: string, environment: AdyenPreparationEnvironment): boolean;
+/** A fresh scheme card carrying the four encrypted fields the device replaces; stored cards, single-blob encryption and store requests never consume consent. */
+export declare function isPreparedAdyenBody(body: string | null | undefined): boolean;
+/** Processor identity, environment and request shape are part of the device's prior consent. */
+export declare function isPreparedAdyenRequest(rawUrl: string, method: string, body: string | null | undefined, environment: AdyenPreparationEnvironment): boolean;

package/dist/adyen.generated.js

@@ -0,0 +1,64 @@
+export const ADYEN_ENCRYPTED_CARD_FIELDS = ['encryptedCardNumber', 'encryptedExpiryMonth', 'encryptedExpiryYear', 'encryptedSecurityCode'];
+const SESSIONS_PAYMENTS = /^\/checkoutshopper\/v1\/sessions\/[A-Za-z0-9_-]{1,256}\/payments$/;
+const TEST_HOST = /^checkoutshopper-test\.adyen\.com$/;
+const LIVE_HOST = /^(?:checkoutshopper-live(?:-[a-z]+)?\.adyen\.com|(?:[a-z0-9-]+\.)*adyenpayments\.com)$/;
+const CLIENT_KEY = /^(test|live)_[A-Za-z0-9]{32}$/;
+const record = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
+const text = (value, max = 4096) => typeof value === 'string' && value.length > 0 && value.length <= max && !/[\u0000-\u001f\u007f]/.test(value);
+/** Which preparation environment a hostname belongs to: Adyen's test host, one of its live host families, or neither. */
+export function adyenPreparationEnvironment(hostname) {
+    const host = hostname.toLowerCase();
+    if (TEST_HOST.test(host))
+        return 'sandbox';
+    if (LIVE_HOST.test(host))
+        return 'production';
+    return null;
+}
+/** The URL a preparation advertises for the approved host family: every registry recognizes it, and it is never a real session. */
+export function adyenPreparationUrl(environment) {
+    return `https://checkoutshopper-${environment === 'production' ? 'live' : 'test'}.adyen.com/checkoutshopper/v1/sessions/prepared/payments`;
+}
+/** A Sessions payments URL on the approved host family whose only query is a client key of that same environment. */
+export function isPreparedAdyenUrl(rawUrl, environment) {
+    let url;
+    try {
+        url = new URL(rawUrl);
+    }
+    catch {
+        return false;
+    }
+    if (url.protocol !== 'https:' || url.port || url.username || url.password || url.hash)
+        return false;
+    if (adyenPreparationEnvironment(url.hostname) !== environment || !SESSIONS_PAYMENTS.test(url.pathname))
+        return false;
+    const names = [...url.searchParams.keys()];
+    if (names.length !== 1 || names[0] !== 'clientKey')
+        return false;
+    const key = url.searchParams.get('clientKey') ?? '';
+    const match = CLIENT_KEY.exec(key);
+    return !!match && match[0] === key && (match[1] === 'live') === (environment === 'production');
+}
+/** A fresh scheme card carrying the four encrypted fields the device replaces; stored cards, single-blob encryption and store requests never consume consent. */
+export function isPreparedAdyenBody(body) {
+    if (typeof body !== 'string' || !body || body.length > 65536)
+        return false;
+    let parsed;
+    try {
+        parsed = JSON.parse(body);
+    }
+    catch {
+        return false;
+    }
+    if (!record(parsed) || parsed.storePaymentMethod === true)
+        return false;
+    const method = parsed.paymentMethod;
+    if (!record(method) || method.type !== 'scheme')
+        return false;
+    if ('storedPaymentMethodId' in method || 'encryptedCard' in method || 'recurringDetailReference' in method)
+        return false;
+    return ADYEN_ENCRYPTED_CARD_FIELDS.every(field => text(method[field]));
+}
+/** Processor identity, environment and request shape are part of the device's prior consent. */
+export function isPreparedAdyenRequest(rawUrl, method, body, environment) {
+    return method.toUpperCase() === 'POST' && isPreparedAdyenUrl(rawUrl, environment) && isPreparedAdyenBody(body);
+}

package/dist/agentcard.d.ts

@@ -0,0 +1,72 @@
+/**
+ * The one client: `new Agentcard({ clientId, clientSecret, voice?, sandbox? })`,
+ * with two modules. `checkout` pauses a browser purchase or creates one
+ * directly and replays the processor's answer; `voice` connects a person to
+ * your product once and approves a purchase by voice. One pair of
+ * credentials, one token, one base URL; sandbox and live are decided by the
+ * credentials.
+ */
+import { VaultClient, type AuthorizeInput, type PrepareCheckoutInput, type PreparedCheckout, type ReplayResponse, type RuntimeCancelReason, type VaultClientOptions } from './client.js';
+import { type AttachOptions, type CdpLike } from './cdp.js';
+import type { CheckoutController } from './lifecycle.js';
+import type { CheckoutMode, Recognizer } from './registry.js';
+import type { RequestRegistry } from './requests.js';
+/** `attachToCdp`'s options without the client, which the module supplies. */
+export type CheckoutAttachOptions = Omit<AttachOptions, 'vault'>;
+/**
+ * `agentcard.checkout`: a browser purchase paused and replayed, a purchase
+ * created directly, the recognisers that decide what pauses and the request
+ * builders that shape a direct create. Every verb here is the client's own
+ * under its module name; the client's top-level spellings stay for one release.
+ */
+export declare class CheckoutModule {
+    private readonly client;
+    constructor(client: Agentcard);
+    /**
+     * Arms a CDP session so the page's card request pauses for the cardholder's
+     * approval and resumes with the processor's answer. `syncRegistry()` first,
+     * so the recognisers are the API's current list.
+     */
+    attachToCdp(cdp: CdpLike, pageSessionId: string, opts: CheckoutAttachOptions): Promise<CheckoutController>;
+    /** The same over a Playwright page. */
+    attachToPlaywright(page: unknown, opts: CheckoutAttachOptions): Promise<CheckoutController>;
+    /** Refreshes the recognisers from the API so a new processor works without a redeploy; a failed read keeps the current list. */
+    syncRegistry(): Promise<void>;
+    /** Creates the purchase for a paused request, waits for the approval and returns what to replay into the page. */
+    authorize(input: AuthorizeInput): Promise<ReplayResponse>;
+    /** Approves a purchase before the page's own card request, for processors with a short request deadline. */
+    prepareCheckout(input: PrepareCheckoutInput): Promise<PreparedCheckout>;
+    cancelPreparation(id: string): Promise<void>;
+    /** Withdraws an approval the page will not use, with the runtime's reason. */
+    cancelAuthorization(authorizationId: string, reason?: RuntimeCancelReason): ReturnType<VaultClient['cancelAuthorization']>;
+    /** Asks the API whether a Stripe confirmation that pays with an approved token may continue. */
+    checkStripeContinuation(authorizationId: string, request: {
+        url: string;
+        method: string;
+        headers: Record<string, string>;
+        body: string;
+    }): ReturnType<VaultClient['checkStripeContinuation']>;
+    /** True when this request is a card request a recogniser claims. */
+    isCardRequest(url: string, method?: string): boolean;
+    /** The recogniser that claims a card request, or null. */
+    recognizerOf(url: string, method?: string): Recognizer | null;
+    /** How the card would reach the processor on this request, or null when nothing recognises it. */
+    checkoutModeOf(url: string, method?: string): CheckoutMode | null;
+    /** What happens to a recognised request whose body carries no card. */
+    withoutCard(url: string, body: string | null | undefined): 'continue' | 'refuse' | null;
+    /** The URL patterns a raw CDP connection hands `Fetch.enable`, for the current recognisers. */
+    cardUrlPatterns(): string[];
+    /** The recognisers: the served or built-in list plus yours (`register`, `list`, `find`). */
+    get recognizers(): Agentcard['recognizers'];
+    /** The request builders: the shipped ones plus yours (`register`, `build`, `list`). */
+    get requests(): RequestRegistry;
+}
+/**
+ * The Agentcard client. Construct one per server with your OAuth client
+ * credentials; every module shares its token.
+ */
+export declare class Agentcard extends VaultClient {
+    /** A browser purchase paused and replayed, a purchase created directly, the recognisers and the request builders. */
+    readonly checkout: CheckoutModule;
+    constructor(opts: VaultClientOptions);
+}

package/dist/agentcard.js

@@ -0,0 +1,71 @@
+/**
+ * The one client: `new Agentcard({ clientId, clientSecret, voice?, sandbox? })`,
+ * with two modules. `checkout` pauses a browser purchase or creates one
+ * directly and replays the processor's answer; `voice` connects a person to
+ * your product once and approves a purchase by voice. One pair of
+ * credentials, one token, one base URL; sandbox and live are decided by the
+ * credentials.
+ */
+import { VaultClient } from './client.js';
+import { attachToCdp, attachToPlaywright } from './cdp.js';
+/**
+ * `agentcard.checkout`: a browser purchase paused and replayed, a purchase
+ * created directly, the recognisers that decide what pauses and the request
+ * builders that shape a direct create. Every verb here is the client's own
+ * under its module name; the client's top-level spellings stay for one release.
+ */
+export class CheckoutModule {
+    client;
+    constructor(client) {
+        this.client = client;
+    }
+    /**
+     * Arms a CDP session so the page's card request pauses for the cardholder's
+     * approval and resumes with the processor's answer. `syncRegistry()` first,
+     * so the recognisers are the API's current list.
+     */
+    attachToCdp(cdp, pageSessionId, opts) {
+        return attachToCdp(cdp, pageSessionId, { ...opts, vault: this.client });
+    }
+    /** The same over a Playwright page. */
+    attachToPlaywright(page, opts) {
+        return attachToPlaywright(page, { ...opts, vault: this.client });
+    }
+    /** Refreshes the recognisers from the API so a new processor works without a redeploy; a failed read keeps the current list. */
+    syncRegistry() { return this.client.syncRegistry(); }
+    /** Creates the purchase for a paused request, waits for the approval and returns what to replay into the page. */
+    authorize(input) { return this.client.authorize(input); }
+    /** Approves a purchase before the page's own card request, for processors with a short request deadline. */
+    prepareCheckout(input) { return this.client.prepareCheckout(input); }
+    cancelPreparation(id) { return this.client.cancelPreparation(id); }
+    /** Withdraws an approval the page will not use, with the runtime's reason. */
+    cancelAuthorization(authorizationId, reason) { return this.client.cancelAuthorization(authorizationId, reason); }
+    /** Asks the API whether a Stripe confirmation that pays with an approved token may continue. */
+    checkStripeContinuation(authorizationId, request) { return this.client.checkStripeContinuation(authorizationId, request); }
+    /** True when this request is a card request a recogniser claims. */
+    isCardRequest(url, method = 'POST') { return this.client.isCardRequest(url, method); }
+    /** The recogniser that claims a card request, or null. */
+    recognizerOf(url, method = 'POST') { return this.client.recognizerOf(url, method); }
+    /** How the card would reach the processor on this request, or null when nothing recognises it. */
+    checkoutModeOf(url, method = 'POST') { return this.client.checkoutModeOf(url, method); }
+    /** What happens to a recognised request whose body carries no card. */
+    withoutCard(url, body) { return this.client.withoutCard(url, body); }
+    /** The URL patterns a raw CDP connection hands `Fetch.enable`, for the current recognisers. */
+    cardUrlPatterns() { return this.client.cardUrlPatterns(); }
+    /** The recognisers: the served or built-in list plus yours (`register`, `list`, `find`). */
+    get recognizers() { return this.client.recognizers; }
+    /** The request builders: the shipped ones plus yours (`register`, `build`, `list`). */
+    get requests() { return this.client.requests; }
+}
+/**
+ * The Agentcard client. Construct one per server with your OAuth client
+ * credentials; every module shares its token.
+ */
+export class Agentcard extends VaultClient {
+    /** A browser purchase paused and replayed, a purchase created directly, the recognisers and the request builders. */
+    checkout;
+    constructor(opts) {
+        super(opts);
+        this.checkout = new CheckoutModule(this);
+    }
+}

package/dist/api-module.d.ts

@@ -0,0 +1,54 @@
+import type { Languages } from './languages.js';
+/** What the client lends its modules: the shared token, the shared HTTP path, and its settings. */
+export interface ApiTransport {
+    /** The client-credentials bearer, cached and refreshed by the client; an `AgentcardError('oauth_failed')` when the exchange is refused. */
+    bearer(): Promise<string>;
+    /** One authenticated call on the client's path (one 401 refresh, the client's timeout, or `timeoutMs` for a call that waits on a turn); an `AgentcardError` carrying the API's code on refusal. */
+    request<T>(path: string, init?: {
+        method?: string;
+        body?: unknown;
+        headers?: Record<string, string>;
+        timeoutMs?: number;
+    }): Promise<T>;
+    pollIntervalMs: number;
+    /** Deadline for the await calls. Default 60 s. */
+    pollTimeoutMs?: number;
+    /** Test seam: the retry pauses. */
+    backoffMs?: readonly number[];
+    /** The pause between two polls; an app may pass one that also wakes when it returns to the foreground. */
+    wait?: (ms: number) => Promise<void>;
+    /** The languages Agentcard speaks, shared by every module that names one. */
+    languages: Languages;
+}
+export declare abstract class ApiModule {
+    protected readonly t: ApiTransport;
+    protected readonly backoff: readonly number[];
+    protected readonly pollTimeoutMs: number;
+    protected readonly wait: (ms: number) => Promise<void>;
+    protected constructor(t: ApiTransport);
+    /** One call, tried again through a transient failure (no response, 502, 503, 504). */
+    protected request<T>(path: string, init?: {
+        method?: string;
+        body?: unknown;
+        headers?: Record<string, string>;
+        timeoutMs?: number;
+    }): Promise<T>;
+    /**
+     * One read that waits out `slow_down` instead of throwing it: the API names the interval it wants
+     * (`interval`, seconds), the client sleeps that long (never under its own `pollIntervalMs`, never over
+     * thirty seconds) and reads again, for at most two minutes in all, or up to `deadline` when the caller
+     * has one; past either bound the refusal is thrown as it came. Every single read the modules expose goes
+     * through here, so a customer never has to add sleeps around a read.
+     */
+    protected read<T>(path: string, opts?: {
+        deadline?: number;
+        onInterval?: (intervalMs: number) => void;
+    }): Promise<T>;
+    /**
+     * Polls `read` until it returns a value or the deadline; a poll that cannot
+     * reach Agentcard is not an answer. `spacingMs` names the least the request
+     * asks between two reads; the client never polls faster than the larger of
+     * it and its own `pollIntervalMs`.
+     */
+    protected poll<T>(read: () => Promise<T | undefined>, timeoutMs: number | undefined, onDeadline: () => T, spacingMs?: () => number | undefined): Promise<T>;
+}

package/dist/api-module.js

@@ -0,0 +1,85 @@
+/**
+ * What every module of the client shares: the client's token, the client's
+ * HTTP path, the retry through a transient failure, the read that waits out
+ * `slow_down`, and the poll that stops at a deadline. Constructed by the
+ * client, never on their own.
+ */
+import { isTransient, RETRY_BACKOFF_MS, sleep, withRetries } from './voice-retry.js';
+import { AgentcardError } from './voice-types.js';
+/** The longest one `slow_down` wait, whatever interval the API names. */
+const SLOW_DOWN_WAIT_CAP_MS = 30_000;
+/** The longest a single read waits out `slow_down` in all before the refusal is thrown to the caller. */
+const SLOW_DOWN_TOTAL_CAP_MS = 120_000;
+export class ApiModule {
+    t;
+    backoff;
+    pollTimeoutMs;
+    wait;
+    constructor(t) {
+        this.t = t;
+        this.backoff = t.backoffMs ?? RETRY_BACKOFF_MS;
+        this.pollTimeoutMs = t.pollTimeoutMs ?? 60_000;
+        this.wait = t.wait ?? sleep;
+    }
+    /** One call, tried again through a transient failure (no response, 502, 503, 504). */
+    request(path, init = {}) {
+        return withRetries(() => this.t.request(path, init), this.backoff);
+    }
+    /**
+     * One read that waits out `slow_down` instead of throwing it: the API names the interval it wants
+     * (`interval`, seconds), the client sleeps that long (never under its own `pollIntervalMs`, never over
+     * thirty seconds) and reads again, for at most two minutes in all, or up to `deadline` when the caller
+     * has one; past either bound the refusal is thrown as it came. Every single read the modules expose goes
+     * through here, so a customer never has to add sleeps around a read.
+     */
+    async read(path, opts = {}) {
+        const started = Date.now();
+        for (;;) {
+            try {
+                return await this.request(path);
+            }
+            catch (err) {
+                if (!(err instanceof AgentcardError && err.code === 'slow_down'))
+                    throw err;
+                const named = typeof err.details.interval === 'number' && err.details.interval > 0 ? err.details.interval * 1000 : this.t.pollIntervalMs;
+                opts.onInterval?.(named);
+                const waitMs = Math.min(Math.max(named, this.t.pollIntervalMs), SLOW_DOWN_WAIT_CAP_MS);
+                const now = Date.now();
+                if (now - started + waitMs > SLOW_DOWN_TOTAL_CAP_MS)
+                    throw err;
+                if (opts.deadline !== undefined && now + waitMs > opts.deadline)
+                    throw err;
+                await this.wait(waitMs);
+            }
+        }
+    }
+    /**
+     * Polls `read` until it returns a value or the deadline; a poll that cannot
+     * reach Agentcard is not an answer. `spacingMs` names the least the request
+     * asks between two reads; the client never polls faster than the larger of
+     * it and its own `pollIntervalMs`.
+     */
+    async poll(read, timeoutMs, onDeadline, spacingMs = () => undefined) {
+        const deadline = Date.now() + (timeoutMs ?? this.pollTimeoutMs);
+        let lastFailure = null;
+        for (;;) {
+            try {
+                const v = await read();
+                lastFailure = null;
+                if (v !== undefined)
+                    return v;
+            }
+            catch (err) {
+                if (!isTransient(err))
+                    throw err;
+                lastFailure = err;
+            }
+            if (Date.now() >= deadline) {
+                if (lastFailure)
+                    throw new AgentcardError('unreachable', 'Agentcard did not answer.');
+                return onDeadline();
+            }
+            await this.wait(Math.max(this.t.pollIntervalMs, spacingMs() ?? 0));
+        }
+    }
+}

package/dist/attachment.d.ts

@@ -0,0 +1,11 @@
+/** An attachment failure has no payment or browser credentials in its message. */
+export declare class CheckoutAttachmentError extends Error {
+    readonly reason: 'timeout' | 'closed' | 'unavailable';
+    readonly code = "checkout_attachment_failed";
+    constructor(reason: 'timeout' | 'closed' | 'unavailable');
+}
+/** Preserve a known setup cause without exposing raw transport errors. */
+export declare function attachmentFailure(error: unknown): CheckoutAttachmentError;
+export declare function attachmentDeadline(value: number | undefined): number;
+/** Stop waiting, then reject every late continuation before its next command. */
+export declare function withinAttachmentDeadline(arm: (assertActive: () => void) => Promise<void>, timeoutMs: number, signal: AbortSignal): Promise<void>;

package/dist/attachment.js

@@ -0,0 +1,50 @@
+/** An attachment failure has no payment or browser credentials in its message. */
+export class CheckoutAttachmentError extends Error {
+    reason;
+    code = 'checkout_attachment_failed';
+    constructor(reason) {
+        super('Could not attach checkout interception. Close this checkout page and retry in a fresh browser context.');
+        this.reason = reason;
+        this.name = 'CheckoutAttachmentError';
+    }
+}
+/** Preserve a known setup cause without exposing raw transport errors. */
+export function attachmentFailure(error) {
+    return error instanceof CheckoutAttachmentError ? error : new CheckoutAttachmentError('unavailable');
+}
+export function attachmentDeadline(value) {
+    if (value === undefined)
+        return 30_000;
+    if (!Number.isSafeInteger(value) || value <= 0 || value > 300_000) {
+        throw new Error('attachmentTimeoutMs must be an integer between 1 and 300000.');
+    }
+    return value;
+}
+/** Stop waiting, then reject every late continuation before its next command. */
+export async function withinAttachmentDeadline(arm, timeoutMs, signal) {
+    let stopped;
+    let timer;
+    let onAbort = () => { };
+    const assertActive = () => { if (stopped)
+        throw stopped; };
+    const deadline = new Promise((_resolve, reject) => {
+        const stop = (failure) => { stopped ??= failure; reject(stopped); };
+        onAbort = () => stop(attachmentFailure(signal.reason));
+        signal.addEventListener('abort', onAbort, { once: true });
+        if (signal.aborted)
+            onAbort();
+        else
+            timer = setTimeout(() => stop(new CheckoutAttachmentError('timeout')), timeoutMs);
+    });
+    try {
+        await Promise.race([deadline, Promise.resolve().then(() => { assertActive(); return arm(assertActive); })]);
+    }
+    catch (error) {
+        stopped ??= attachmentFailure(error);
+        throw stopped;
+    }
+    finally {
+        clearTimeout(timer);
+        signal.removeEventListener('abort', onAbort);
+    }
+}

package/dist/braintree.d.ts

@@ -0,0 +1,2 @@
+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;