@agent-cards/sdk 0.21.0 → 0.23.0

package/dist/card-endpoint.d.ts

@@ -0,0 +1,298 @@
+/** The SDK's view of a reviewed card endpoint profile: where its card request goes and what may travel with it. */
+export interface CardEndpointProfile {
+    readonly id: string;
+    readonly merchant: string;
+    readonly status: 'observe' | 'enabled';
+    /** The exact https origin of the top-level page the card is typed into. */
+    readonly checkout: string;
+    /**
+     * The exact https origin of the merchant's own card vault frame inside that page, when
+     * the card request is sent from it rather than from the page itself; else null.
+     */
+    readonly frame: string | null;
+    /** The exact https origin the card request goes to. */
+    readonly endpoint: string;
+    readonly method: 'POST';
+    readonly path: string;
+    readonly query: Readonly<Record<string, string>>;
+    /** json_api is a JSON object sent as application/vnd.api+json. */
+    readonly encoding: 'json' | 'json_api' | 'form' | 'multipart';
+    /** A fetch or XHR (null), or a form the page submits as a navigation of the page ('top') or of an iframe ('frame'). */
+    readonly navigation: 'top' | 'frame' | null;
+    readonly session: {
+        readonly cookies: boolean;
+        /** Null for every cookie of the endpoint's jar, or the only names that may travel ('X*' takes every name that starts with X). */
+        readonly cookie_names: readonly string[] | null;
+        readonly headers: readonly string[];
+        readonly required: readonly string[];
+    };
+    readonly response: {
+        readonly headers: readonly string[];
+    };
+    /** True when the card is typed into a frame the merchant's page embeds: the request pauses on that frame's document. */
+    readonly checkout_frame?: boolean;
+    /** Where a body names its payment method, and the values that mean a card: any other method continues untouched. */
+    readonly payment_method?: {
+        readonly at: unknown;
+        readonly card: readonly string[];
+    } | null;
+    /** Requests on the endpoint origin that send the typed card again outside the card request: aborted in every status. */
+    readonly resends?: readonly {
+        readonly method: string;
+        readonly path: string;
+        readonly query: Readonly<Record<string, string>>;
+    }[];
+    /**
+     * The merchant's own record of the order, read from these responses (card-endpoint-facts.ts), and the calls on the
+     * same checkout session that change nothing it holds (inert).
+     */
+    readonly facts?: {
+        readonly reader: string;
+        readonly responses: readonly {
+            readonly method: string;
+            readonly path: string;
+            readonly query: Readonly<Record<string, string>>;
+            readonly format: string;
+        }[];
+        readonly inert: readonly {
+            readonly method: string;
+            readonly path: string;
+            readonly query: Readonly<Record<string, string>>;
+        }[];
+        readonly bind: string;
+    } | null;
+}
+/** One cookie of the endpoint's jar, name and value only. */
+export interface CardEndpointCookie {
+    name: string;
+    value: string;
+}
+/**
+ * What the adapters capture from a paused card request and hand to the create: the
+ * URL, the origin of the page it was paused on, the profile's session headers, the
+ * endpoint's cookies for a cookie profile, a Referer on the origin the request is sent
+ * from (the profile's card vault frame when it names one, else the checkout page), and
+ * the body, which holds only the placeholder card the agent typed. Never a real card,
+ * always cardholder data: it travels only in `merchant_card_endpoint.session`.
+ */
+export interface CardEndpointSession {
+    url: string;
+    page_origin: string;
+    /** For a navigation profile: what the browser said the paused request was. */
+    navigation?: 'top' | 'frame';
+    headers: Record<string, string>;
+    cookies?: CardEndpointCookie[];
+    referer?: string;
+    body: string;
+}
+/** The psp and mode a card endpoint authorization carries; neither is a processor. */
+export declare const CARD_ENDPOINT_PSP: string;
+export declare const CARD_ENDPOINT_MODE: "card_endpoint";
+/**
+ * Why a card endpoint payment was refused before anything was created or sent. Nothing
+ * was charged, and the message names no URL, body or session value.
+ *
+ * - `not_enabled`: this build's copy of the profile does not take payments yet.
+ * - `amount_required`: the attachment names no amount; the agent's amount is the only authority here.
+ * - `approval_required`: the attachment asks for Autopilot; every payment here needs the cardholder's approval.
+ * - `preparation_unsupported`: a prepared checkout cannot pay a merchant's own card endpoint.
+ * - `request_unsupported`: the paused request is not the card request Agentcard reviewed
+ *   (`detail` says what, naming fields, never values).
+ * - `facts_unavailable`: the merchant keeps its own record of the order (profile.facts),
+ *   and this runtime read none for this checkout, or one it cannot place.
+ * - `facts_refused`: the merchant's own record says the order renews on a schedule, or
+ *   that its checkout is in test mode. A total or currency that differs from the agent's
+ *   is an AmountMismatchError instead.
+ *
+ * `not_enabled`, `amount_required`, `approval_required` and `preparation_unsupported`
+ * answer the same way for every request on the attachment, so the adapters stop asking;
+ * the others refuse only the request they are about.
+ */
+export type CardEndpointRefusal = 'not_enabled' | 'amount_required' | 'approval_required' | 'preparation_unsupported' | 'request_unsupported' | 'facts_unavailable' | 'facts_refused';
+export declare class CardEndpointRefusedError extends Error {
+    readonly profile: string;
+    readonly reason: CardEndpointRefusal;
+    readonly detail: string | null;
+    constructor(profile: string, reason: CardEndpointRefusal, detail?: string | null);
+    /** True when every later request on the attachment would be refused the same way. */
+    get permanent(): boolean;
+}
+/** The reviewed profile (any status) whose card request `url` and `method` are exactly, or null. */
+export declare function cardEndpointFor(url: string, method: string): CardEndpointProfile | null;
+/** The reviewed profile with this id, or null. */
+export declare function cardEndpointById(id: string): CardEndpointProfile | null;
+/**
+ * Whether a request to the profile's card endpoint is a card-free payment (the profile's
+ * payment_method names another method in the body): it is never Agentcard's and
+ * continues untouched, in every status. False for anything the rule cannot read, which
+ * is then held to the card request's rules.
+ */
+export declare function cardEndpointPasses(profile: CardEndpointProfile, body: string | null, contentType: string | undefined): boolean;
+/** The reviewed profile (any status) one of whose resend requests `url` and `method` are, or null: the adapters abort it. */
+export declare function cardEndpointResendFor(url: string, method: string): CardEndpointProfile | null;
+/** The origins of the profiles whose merchant keeps its own record of the order: the only responses card-endpoint-facts.ts records. */
+export declare function cardEndpointFactsOrigins(): readonly string[];
+/**
+ * The checkout session a request on the endpoint of a profile with facts belongs to: the
+ * endpoint origin and the profile's card path up to its bind placeholder, written with the
+ * request's own segments, the session payment-core binds the record to
+ * ('https://rekordcloud.onfastspring.com/popup-lexicon/session/<id>'). Null for any other
+ * request. card-endpoint-facts.ts counts what it keeps, and what a checkout lost, by it.
+ * When the paths of two profiles on one origin both fit, the shorter session is the one:
+ * every request on a card request's session then gets the card request's own.
+ */
+export declare function cardEndpointFactsSession(url: string): string | null;
+/** Whether this build's copy of the profile takes payments (enabled, nothing pending, a reviewed HAR, not recurring). */
+export declare function cardEndpointLive(profile: CardEndpointProfile | string): boolean;
+/**
+ * Whether a paused request to the profile's card request URL carries a card, so the
+ * adapters hold it (payment-core merchantCardEndpointCarriesCard): anything at the
+ * profile's card number field, or a Luhn-valid number of 12 to 19 digits anywhere in
+ * the body, however it is written. A body the adapter could not read (null), an empty
+ * one, and any answer the rule cannot give count as carrying one. A post to a
+ * navigation profile carries none only when it also reads under the profile's
+ * encoding, its card fields are empty and it holds no card number anywhere: no run of
+ * 12 to 19 digits, spaces, dots and dashes dropped, that passes the card check digit.
+ * Its page posts such a body for a cancel, another payment method or a bank payment,
+ * and it continues untouched.
+ */
+export declare function cardEndpointCarriesCard(profile: CardEndpointProfile, body: string | null | undefined, contentType: string | undefined): boolean;
+/** Whether a paused body is the card request the profile reviewed (its body rules, never its status). */
+export declare function cardEndpointReviewed(profile: CardEndpointProfile, body: string | null | undefined, contentType: string | undefined): boolean;
+/** What an event may say about a card endpoint request: the profile and the endpoint origin, never the URL's path or query. */
+export declare function cardEndpointDetail(profile: CardEndpointProfile): {
+    profile: string;
+    endpoint: string;
+};
+/**
+ * Fetch.enable patterns covering every profile's card request, in any status: its
+ * origin and path with each `:name` segment and the query as wildcards. A coarse
+ * pre-filter, like cardUrlPatterns for processors; cardEndpointFor is the exact check
+ * each paused request is held to, and anything it refuses continues untouched.
+ */
+export declare function cardEndpointPatterns(): string[];
+/** What an adapter reads off a paused card endpoint request. */
+export interface CardEndpointCapture {
+    url: string;
+    /** The paused request's headers as the browser reports them; the jar's cookies are never among them. */
+    headers: Record<string, string> | undefined;
+    /** The paused body: the placeholder card the agent typed and the rest of the merchant's fields. */
+    body: string;
+    /**
+     * The origin of the page the request was paused on, when it could be read: the
+     * top-level page, or for a 'frame' profile the document of the iframe its form sits in.
+     */
+    pageOrigin: string | undefined;
+    /** For a document request: a navigation of the page ('top') or of an iframe ('frame'). Absent for a fetch or XHR. */
+    navigation?: 'top' | 'frame';
+    /** The endpoint's cookie jar for this URL (HttpOnly included). Read only for a cookie profile. */
+    cookies: () => Promise<CardEndpointCookie[]>;
+}
+/**
+ * The session the create carries for a paused card endpoint request: the profile's own
+ * header names and nothing else, the Referer only when it is a page on the origin the
+ * request is sent from (the profile's card vault frame when it names one, else the
+ * checkout page), the endpoint's cookies only for a cookie profile, and the body. Checked with
+ * the same rules the API and the device run (payment-core
+ * merchantCardEndpointSessionRefusal), so a request they would refuse never leaves this
+ * process: a CardEndpointRefusedError (`request_unsupported`) instead, naming no value.
+ */
+export declare function captureCardEndpointSession(profile: CardEndpointProfile, capture: CardEndpointCapture): Promise<CardEndpointSession>;
+/**
+ * The headers the paused request is answered with: the profile's answer headers the
+ * merchant sent, and never Set-Cookie (cookies reach the browser through
+ * cardEndpointCookies, on the endpoint host only).
+ */
+export declare function cardEndpointAnswerHeaders(profile: CardEndpointProfile, headers: Record<string, string>): Record<string, string>;
+/**
+ * The fixed answer a paused request gets when the cardholder's device withheld the
+ * merchant's answer (it carried the card, or a compressed stream the device cannot
+ * read): an error the merchant's page stops on. The card request was sent; whether
+ * the merchant took the payment is unknown until the order is checked.
+ */
+export declare const CARD_ENDPOINT_WITHHELD_ANSWER: Readonly<{
+    status: number;
+    headers: Readonly<Record<string, string>>;
+    body: string;
+}>;
+/**
+ * The fixed answer for a merchant answer the device withheld because it asks the page
+ * for a step the review refuses (withheld `refused_step_in_response`: FastSpring's EBANX
+ * step, which reads the typed card back and sends it again). The card request was sent,
+ * so the outcome is unknown until the order is checked.
+ */
+export declare const CARD_ENDPOINT_REFUSED_STEP_ANSWER: Readonly<{
+    status: number;
+    headers: Readonly<Record<string, string>>;
+    body: string;
+}>;
+/**
+ * A Set-Cookie value from the merchant's answer, as an adapter writes it into the
+ * agent's browser: host-only on the endpoint host, or on the parent domain its Domain
+ * attribute names when that is a rotation of a cookie the browser already holds there
+ * (`domain`), at the cookie's path, Secure whatever the merchant said (the endpoint is
+ * https-only, so no cookie the SDK writes ever travels over plain http), with its other
+ * flags and expiry. `expires` is seconds since the epoch, absent for a session cookie,
+ * and 1 for a cookie the merchant expired, which the browser then removes.
+ */
+export interface CardEndpointSetCookie {
+    name: string;
+    value: string;
+    /** The endpoint's origin, which a host-only cookie is written for. */
+    origin: string;
+    /** The endpoint's host name. */
+    host: string;
+    /**
+     * The domain (no leading dot) the cookie is written on as a domain cookie: set only
+     * when the merchant's Domain attribute names the endpoint host or a parent of it and
+     * the browser already sends the endpoint a cookie of this name on that domain, so the
+     * write replaces that cookie. Absent for every other cookie, which is host-only.
+     */
+    domain?: string;
+    path: string;
+    /** True for every cookie the SDK writes: see above. */
+    secure: boolean;
+    httpOnly: boolean;
+    sameSite?: 'Strict' | 'Lax' | 'None';
+    expires?: number;
+}
+/**
+ * One cookie the browser sends to the endpoint, as the adapters read the jar
+ * (Network.getCookies or context.cookies()): its name and its domain, which a leading
+ * dot marks as a domain cookie.
+ */
+export interface CardEndpointJarCookie {
+    name: string;
+    domain: string;
+}
+/**
+ * The merchant's Set-Cookie values as cookies to write (parseSetCookie), and how many
+ * could not be written as one (a malformed line, a prefix or a Domain the browser would
+ * refuse, a Domain with the jar unread). `jar` is the endpoint's cookies as the adapter
+ * read them, null when the read failed. Only a profile whose answer may carry cookies
+ * has any.
+ */
+export declare function cardEndpointCookies(profile: CardEndpointProfile, requestUrl: string, setCookies: readonly string[], nowMs?: number, jar?: readonly CardEndpointJarCookie[] | null): {
+    cookies: CardEndpointSetCookie[];
+    skipped: number;
+};
+/**
+ * How a paused navigation is answered from the merchant's answer (payment-core
+ * merchantCardEndpointNavigationAnswer): the page, a 301, 302 or 303 to one https URL,
+ * or refused (a redirect that repeats the post, or a Location that is not one https URL).
+ */
+export declare function cardEndpointNavigationAnswer(profile: CardEndpointProfile, answer: {
+    status: number;
+    headers: Record<string, string>;
+}, requestUrl: string): {
+    kind: 'page';
+} | {
+    kind: 'redirect';
+    status: number;
+    location: string;
+} | {
+    kind: 'refused';
+    reason: 'redirect_repeats_post' | 'redirect_location_invalid';
+};
+/** Why a session is not one the profile lets travel (payment-core merchantCardEndpointSessionRefusal), or null. Names no value. */
+export declare function cardEndpointSessionRefusal(profile: CardEndpointProfile, session: unknown): string | null;