@agent-cards/sdk 0.21.0 → 0.22.0

package/dist/payrails.d.ts

@@ -0,0 +1,133 @@
+import { PAYRAILS_CAPABILITY, PAYRAILS_PSP } from './payrails.generated.js';
+export { PAYRAILS_CAPABILITY, PAYRAILS_PSP };
+/**
+ * How the pre-claim gate reads a POST to a Payrails host: `card` for a card save on a save URL
+ * (data.encryptedData present, payment-core's pause predicate), `card_payment` for a payment that
+ * carries an encrypted card inside paymentComposition, and null for anything else, which continues.
+ */
+export declare function payrailsRequestKind(url: string, method: string, body: string): 'card' | 'card_payment' | null;
+/**
+ * Why a Payrails request was aborted, reported as the `reason` of the `unsupported_checkout` event:
+ *   unsupported_payrails_card_payment  a payment that sends an encrypted card inside
+ *                                      paymentComposition; the attachment holds
+ *   payrails_request_malformed, payrails_not_card_save, payrails_jwe_malformed,
+ *   payrails_future_usage_refused, payrails_card_on_file_consent_required
+ *                                      a card save payment-core's guard refuses; the attachment holds
+ *   payrails_session_unavailable       no captured session matches the save; that request only
+ *   payrails_key_invalid, payrails_key_mismatch
+ *                                      the captured key cannot be the frame's; that request only
+ */
+export type PayrailsUnsupportedReason = 'unsupported_payrails_card_payment' | 'payrails_request_malformed' | 'payrails_not_card_save' | 'payrails_jwe_malformed' | 'payrails_future_usage_refused' | 'payrails_card_on_file_consent_required' | 'payrails_session_unavailable' | 'payrails_key_invalid' | 'payrails_key_mismatch';
+/** Refusals of the save's own shape: the page's next save would be the same, so the attachment holds. */
+export declare const PAYRAILS_HOLDING_REASONS: readonly PayrailsUnsupportedReason[];
+/** What the agent reads when a save's session cannot be bound. Not shown to the cardholder. */
+export declare const PAYRAILS_SESSION_MESSAGE = "Payrails session expired, reload the checkout";
+/** Captured sessions kept per attachment; the oldest is dropped first. */
+export declare const PAYRAILS_CAPTURE_LIMIT = 8;
+/** How long a captured session is kept at all. */
+export declare const PAYRAILS_CAPTURE_TTL_MS: number;
+/** How old a captured session may be when its save pauses: Payrails gives a session key ten minutes. */
+export declare const PAYRAILS_SESSION_MAX_AGE_MS: number;
+/** The largest answer body read for an init payload. */
+export declare const PAYRAILS_INIT_BODY_LIMIT: number;
+/** How long a paused save waits for answer bodies still being read before it binds. */
+export declare const PAYRAILS_PENDING_READ_MS = 1000;
+/** Fetch interception patterns for every Payrails host, armed only for an org the API served Payrails to. */
+export declare const PAYRAILS_GUARD_PATTERNS: readonly string[];
+/** One captured Payrails session: the init payload's binding fields and its key. Never logged. */
+export interface PayrailsSession {
+    readonly token: string;
+    readonly holderReference: string;
+    readonly providerConfigId: string;
+    readonly saveInstrumentHref: string;
+    readonly encryptionPublicKey: string;
+    readonly seenAt: number;
+}
+type SessionFields = Omit<PayrailsSession, 'seenAt'>;
+/** What the create carries beside a Payrails save: the session key its page encrypted under. */
+export interface PayrailsSidecar {
+    readonly encryption_public_key: string;
+}
+/**
+ * Every Payrails init payload one JSON answer body carries: the body itself, or its members one
+ * level down (an object's values or an array's items). An init payload is `{version, data}` whose
+ * `data` decodes to JSON with a token, a holderReference and a vaultConfiguration naming its
+ * providerConfigId, its encryptionPublicKey and a saveInstrument href on a Payrails save URL.
+ */
+export declare function payrailsInitSessions(body: unknown): SessionFields[];
+/** Whether an answer may carry an init payload worth reading: a 2xx XHR or fetch with a JSON type. */
+export declare function payrailsInitCandidate(resourceType: unknown, status: unknown, contentType: unknown): boolean;
+/**
+ * The Payrails sessions one attachment has seen, in memory only: at most PAYRAILS_CAPTURE_LIMIT,
+ * each dropped PAYRAILS_CAPTURE_TTL_MS after it was first seen. Nothing here is ever logged or
+ * reported; the key leaves it only on the create for the one save it binds to.
+ *
+ * The capture runs on the agent's side and trusts nothing it reads: a page can hand it any key.
+ * The binding catches a stale session or a runtime bug. What bounds a key an agent supplies is
+ * elsewhere: the device sends the ciphertext only to a Payrails host, the API holds the token to
+ * the Payrails workspace Agentcard reviewed for the merchant, and the page never sees the
+ * ciphertext the device made.
+ */
+export declare class PayrailsSessionCapture {
+    private sessions;
+    private readonly reads;
+    /** Record the init payloads an answer body carries; how many it carried. Never throws. */
+    observe(body: unknown, now?: number): number;
+    /** An answer body still being read: a save that pauses meanwhile waits for it, briefly. */
+    reading(read: Promise<unknown>): void;
+    /** Whether an answer body is still being read. */
+    get pending(): boolean;
+    /** Wait for the answer bodies being read, at most `ms`. */
+    settle(ms?: number): Promise<void>;
+    /**
+     * The session key for a paused card save: the key of the captured session whose token is the
+     * save's bearer token, whose saveInstrument href is the save's URL, and whose holderReference and
+     * providerConfigId are the body's, first seen at most PAYRAILS_SESSION_MAX_AGE_MS before `now`.
+     * Null when none matches, or when matching sessions disagree on the key.
+     */
+    keyFor(request: {
+        url: string;
+        headers?: Record<string, string>;
+        body: string | null;
+    }, now?: number): string | null;
+    /** How many sessions are held; for tests. */
+    get size(): number;
+    private prune;
+}
+type VaultLike = {
+    isCardRequest?: (url: string, method?: string) => boolean;
+    checkoutModeOf?: (url: string, method?: string) => string | null;
+} | null | undefined;
+/**
+ * Whether the vault's current registry pauses Payrails' card save in mode device_encrypt: true only
+ * after syncRegistry() for an org the API serves the dark entry to. Everything Payrails-specific in
+ * the adapters (reading answers, intercepting Payrails hosts) runs only when this is true.
+ */
+export declare function recognizesPayrails(vault: VaultLike): boolean;
+/** A Payrails host: https on the standard port, no userinfo, a hostname under payrails.io. */
+export declare function isPayrailsHost(rawUrl: string): boolean;
+/** Payrails' static host: it serves the web SDK and the secure frame's files, and takes no payment. */
+export declare const PAYRAILS_STATIC_HOST = "assets.payrails.io";
+/** A Payrails host (isPayrailsHost) that is exactly the static host. */
+export declare function isPayrailsStaticHost(rawUrl: string): boolean;
+/**
+ * payment-core's judgement of a card save's own shape, before any session is looked up: null when
+ * the save is the SDK's exact card save and keeps no card on file the cardholder has not consented
+ * to, else the refusal code. A guard that throws refuses.
+ */
+export declare function payrailsSaveRefusal(body: string): PayrailsUnsupportedReason | null;
+/**
+ * The key check for a bound session: null when the captured key is an RSA-2048, 3072 or 4096 key as
+ * long as the key the page's frame wrapped for this save, else the refusal code.
+ */
+export declare function payrailsKeyRefusal(key: string, body: string): PayrailsUnsupportedReason | null;
+/**
+ * The only answer the page may receive for an approved Payrails save: Payrails' 201 for a card
+ * instrument, rebuilt from payment-core's allow-list (the BIN cut to six digits), under a JSON
+ * content type. Null for anything else.
+ */
+export declare function payrailsSaveAnswer(status: number, body: string): {
+    status: 201;
+    headers: Record<string, string>;
+    body: string;
+} | null;

package/dist/payrails.generated.d.ts

@@ -0,0 +1,73 @@
+declare var PAYRAILS_PSP: string;
+declare var PAYRAILS_CAPABILITY: string;
+declare var PAYRAILS_OPERATION: string;
+declare var PAYRAILS_SAVE_PATH: string;
+declare var PAYRAILS_SAVE_HOSTS: readonly string[];
+declare var PAYRAILS_JWE_HEADER: string;
+declare var PAYRAILS_JWE_HEADER_B64: string;
+declare var PAYRAILS_KEY_BITS: readonly number[];
+declare var PAYRAILS_FUTURE_USAGES: readonly string[];
+declare var PAYRAILS_CARD_ON_FILE_CONSENTED: readonly never[];
+declare var PAYRAILS_SESSION_MIN_SECONDS: number;
+declare var PAYRAILS_REFUSALS: Readonly<{
+    payrails_request_malformed: string;
+    payrails_not_card_save: string;
+    payrails_jwe_malformed: string;
+    payrails_future_usage_refused: "Refusing to pay: this Payrails save asks to keep the card for a use the Vault cannot approve yet. Nothing was sent.";
+    payrails_card_on_file_consent_required: "Refusing to pay: this Payrails save would keep the card on file without your consent. Nothing was sent.";
+    payrails_key_invalid: string;
+    payrails_key_mismatch: string;
+    payrails_token_invalid: string;
+    payrails_workspace_unpinned: string;
+    payrails_workspace_mismatch: string;
+    payrails_session_expiring: "Refusing to pay: this Payrails session expires before it can be approved. Reload the checkout.";
+}>;
+declare function payrailsRefusalMessage(code: any): any;
+declare function base64UrlEncode(bytes: any): string;
+declare function base64UrlDecode(text: any, max: any): Uint8Array<ArrayBuffer> | null;
+declare function isPayrailsSaveUrl(url: any, { exact: exact2 }?: {
+    exact?: boolean | undefined;
+}): boolean;
+declare function payrailsJweParts(jwe: any): {
+    wrappedKey: Uint8Array<ArrayBuffer>;
+    iv: Uint8Array<ArrayBuffer>;
+    ciphertext: Uint8Array<ArrayBuffer>;
+    tag: Uint8Array<ArrayBuffer>;
+} | null;
+declare function payrailsTemplateRefusal(body: any): any;
+declare function parsePayrailsSave(body: any): any;
+declare function payrailsKeepsCardFor(save: any): any;
+declare function payrailsCardOnFileRefusal(body: any): any;
+declare function classifyPayrailsRequest(url: any, method: any, body: any): "card" | "continue" | null;
+declare function payrailsAuthorizeCarriesCard(url: any, method: any, body: any): boolean;
+declare function payrailsSessionKeyBytes(spki: any): any;
+declare function payrailsSessionKeyRefusal(spki: any, body: any): any;
+declare function payrailsTokenClaims(authorization: any): Readonly<{
+    claims: Readonly<{}>;
+    exp: any;
+}> | null;
+declare function payrailsWorkspacePinRefusal(authorization: any, pin: any, now?: number): "payrails_workspace_unpinned" | "payrails_token_invalid" | "payrails_workspace_mismatch" | "payrails_session_expiring" | null;
+declare var PAYRAILS_USABLE_STATUSES: readonly string[];
+declare var PAYRAILS_UNUSABLE_STATUSES: readonly string[];
+declare var PAYRAILS_SERVED_CARD_FACTS: readonly string[];
+declare function payrailsFacts(text: any): {
+    refusalCode: any;
+};
+declare function sanitizePayrailsResponse(text: any): string;
+declare function payrailsResponseOutcome(status: any, text: any, { card }?: {}): {
+    outcome: string;
+    reason: string;
+    code?: undefined;
+    body?: undefined;
+} | {
+    outcome: string;
+    code: any;
+    reason?: undefined;
+    body?: undefined;
+} | {
+    outcome: string;
+    body: string;
+    reason?: undefined;
+    code?: undefined;
+};
+export { PAYRAILS_CAPABILITY, PAYRAILS_CARD_ON_FILE_CONSENTED, PAYRAILS_FUTURE_USAGES, PAYRAILS_JWE_HEADER, PAYRAILS_JWE_HEADER_B64, PAYRAILS_KEY_BITS, PAYRAILS_OPERATION, PAYRAILS_PSP, PAYRAILS_REFUSALS, PAYRAILS_SAVE_HOSTS, PAYRAILS_SAVE_PATH, PAYRAILS_SERVED_CARD_FACTS, PAYRAILS_SESSION_MIN_SECONDS, PAYRAILS_UNUSABLE_STATUSES, PAYRAILS_USABLE_STATUSES, base64UrlDecode, base64UrlEncode, classifyPayrailsRequest, isPayrailsSaveUrl, parsePayrailsSave, payrailsAuthorizeCarriesCard, payrailsCardOnFileRefusal, payrailsFacts, payrailsJweParts, payrailsKeepsCardFor, payrailsRefusalMessage, payrailsResponseOutcome, payrailsSessionKeyBytes, payrailsSessionKeyRefusal, payrailsTemplateRefusal, payrailsTokenClaims, payrailsWorkspacePinRefusal, sanitizePayrailsResponse };