@asteby/storefront-react 0.4.0 → 0.5.0

package/dist/payments.d.ts

@@ -0,0 +1,364 @@
+import * as react from 'react';
+import { ReactNode, CSSProperties } from 'react';
+import { Money, PaymentAttemptResult, PaymentClient, PaymentOutcomeKind, PaymentOutcome, PaymentErrorView, PaymentMessages, PaymentErrorKind } from '@asteby/storefront';
+
+/**
+ * Replaceable ports of the embedded payment. The shop (or another provider)
+ * implements these; the hook and component only talk to them.
+ *
+ * Two ports, on purpose:
+ * - `PaymentFormAdapter` = the provider SDK in the browser (Mercado Pago Bricks, Stripe Elements...).
+ *   It mounts a secure form and returns only what the SDK allows to travel (a one-use token).
+ * - `PaymentTransport` = how the browser reaches the shop SERVER. The browser never calls OPS: the shop's
+ *   route forwards to `client.checkouts.pay(...)` with its private token. The HTTP contract between
+ *   the shop route and OPS lives in `@asteby/storefront` (`checkouts.pay`); the shop route is free to
+ *   shape its own JSON as long as it answers with a `PaymentAttemptResult`.
+ */
+
+type PaymentFormError = {
+    /** `true`: the form cannot be used (SDK blocked, iframe failed). The hook falls back to a redirect. */
+    critical: boolean;
+    /** Short, non-sensitive text for logs. Never card data. */
+    message?: string;
+};
+type PaymentFormMountOptions = {
+    /** Element the provider renders into. Its `id` is set by the hook. */
+    container: HTMLElement;
+    client: PaymentClient;
+    /** Total computed by the server. Only passed to the provider widget; never calculated here. */
+    amount: Money;
+    email?: string;
+    locale?: string;
+    /** Visual tokens read from CSS variables (see `readPaymentTheme`). */
+    theme?: Record<string, string>;
+    onReady: () => void;
+    onError: (error: PaymentFormError) => void;
+};
+/** What a mounted form hands back at submit time. */
+type PaymentFormData = {
+    /** Sent to the server as `provider_data`. Must never contain amounts or raw card data. */
+    provider_data: Record<string, unknown>;
+    /** Anti-fraud device fingerprint, if the SDK exposes one. */
+    device_session_id?: string;
+};
+interface MountedPaymentForm {
+    /** Tokenises the card inside the provider iframes. Rejects when the form is invalid (the provider shows the field errors). */
+    collect(): Promise<PaymentFormData>;
+    unmount(): void | Promise<void>;
+}
+interface PaymentFormAdapter {
+    /** `PaymentClient.kind` this adapter serves. */
+    readonly kind: string;
+    /** Loads the provider script (once). Rejects on timeout, blocked script or invalid URL. */
+    load(client: PaymentClient, options: {
+        nonce?: string;
+        timeoutMs: number;
+    }): Promise<void>;
+    mount(options: PaymentFormMountOptions): Promise<MountedPaymentForm>;
+}
+/** Everything the shop server needs for one attempt. No card data: only the provider token and choices. */
+type PaymentSubmitRequest = {
+    option: 'card';
+    /** Stable per attempt: the same attempt always carries the same key, so a retry never charges twice. */
+    attempt: string;
+    idempotencyKey: string;
+    provider_data: Record<string, unknown>;
+    device_session_id?: string;
+    /** The total the buyer saw (the server's own number). The server answers 422 `price_mismatch` if it differs. */
+    expected_total: Money;
+};
+type PaymentTransport = {
+    submit(request: PaymentSubmitRequest, context: {
+        signal: AbortSignal;
+    }): Promise<PaymentAttemptResult>;
+    /** Optional: re-reads the checkout state (3DS challenge, "in review"). Same result shape as `submit`. */
+    refresh?(context: {
+        signal: AbortSignal;
+    }): Promise<PaymentAttemptResult>;
+};
+/** Error thrown by `createFetchTransport` for non-2xx answers; compatible with `paymentErrorView`. */
+declare class PaymentHttpError extends Error {
+    readonly status: number;
+    readonly code: string;
+    /** Raw `error.details` (e.g. the new `cost` of a `price_mismatch`); untrusted shape. */
+    readonly details?: unknown | undefined;
+    readonly name = "PaymentHttpError";
+    constructor(status: number, code: string, message?: string, 
+    /** Raw `error.details` (e.g. the new `cost` of a `price_mismatch`); untrusted shape. */
+    details?: unknown | undefined);
+}
+type FetchTransportOptions = {
+    fetch?: typeof fetch;
+    headers?: Record<string, string>;
+    /** Default `same-origin`. */
+    credentials?: RequestCredentials;
+    /** Shapes the JSON body; the default sends the request as is. */
+    buildBody?: (request: PaymentSubmitRequest) => unknown;
+    /** Same-origin URL that re-reads the state (enables `refresh`). */
+    refreshUrl?: string;
+};
+/**
+ * Transport to a same-origin shop route (`POST url` with JSON). Maps `{ error: { code, message, details } }`
+ * answers to `PaymentHttpError`. Network failures surface as the original `TypeError`, which the
+ * hook treats as retryable with the same attempt.
+ */
+declare function createFetchTransport(url: string, options?: FetchTransportOptions): PaymentTransport;
+
+type EmbeddedPaymentStatus = 'idle' | 'loading' | 'ready' | 'processing' | OutcomeStatus | 'network_error' | 'blocked' | 'fallback';
+type OutcomeStatus = PaymentOutcomeKind;
+type PaymentFallbackReason = 'sdk_timeout' | 'sdk_error' | 'form_error' | 'unsupported_provider' | 'no_client';
+/** Anonymous funnel events: no personal or card data. */
+type PaymentEvent = {
+    type: 'form_ready';
+    ms: number;
+} | {
+    type: 'form_failed';
+    reason: PaymentFallbackReason;
+} | {
+    type: 'tokenize_error';
+} | {
+    type: 'submit';
+} | {
+    type: 'result';
+    status: PaymentOutcomeKind;
+    decline_code: string | null;
+} | {
+    type: 'error';
+    kind: PaymentErrorKind;
+} | {
+    type: 'retry';
+};
+type UseEmbeddedPaymentOptions = {
+    /** Provider data from `paymentMethods[].client`. `null`/absent: nothing to mount (status `idle`). */
+    client: PaymentClient | null | undefined;
+    /** The total computed by the server. The Brick is remounted when it changes. Never calculate it in the shop. */
+    amount: Money;
+    transport: PaymentTransport;
+    /** Mount only while the card option is selected. Default true. */
+    enabled?: boolean;
+    email?: string;
+    locale?: string;
+    /** Replaces the adapter chosen from `client.kind`. */
+    adapter?: PaymentFormAdapter;
+    /** Extra adapters by `kind`. Mercado Pago is built in. */
+    adapters?: Record<string, PaymentFormAdapter>;
+    /** CSP nonce for the inserted script. */
+    nonce?: string;
+    /** Time to wait for the form to be ready before falling back. Default 8000. */
+    sdkTimeoutMs?: number;
+    /** Automatic resubmits (same attempt) after a network failure before showing the retry button. Default 2. */
+    autoRetries?: number;
+    /** Base delay for the backoff between automatic retries. Default 600. */
+    retryDelayMs?: number;
+    /** Poll interval/timeout for a pending 3DS challenge or review when `transport.refresh` exists. */
+    pollIntervalMs?: number;
+    pollTimeoutMs?: number;
+    /** Where the attempt id is kept so a reload/retry reuses it. Default `sessionStorage`; `null` disables. Never holds card data. */
+    storage?: Pick<Storage, 'getItem' | 'setItem' | 'removeItem'> | null;
+    /** Scope of the stored attempt (e.g. the checkout or cart id). Default `default`. */
+    scope?: string;
+    messages?: Partial<PaymentMessages>;
+    /** Called with the classified outcome of every definitive answer. */
+    onResult?: (outcome: PaymentOutcome, result: PaymentAttemptResult) => void;
+    /** Called for `redirect` outcomes. Default: `location.assign(url)` (https only). */
+    onRedirect?: (url: string) => void;
+    onFallback?: (reason: PaymentFallbackReason) => void;
+    onEvent?: (event: PaymentEvent) => void;
+    /** Overrides the theme read from `--sf-pay-*` tokens. */
+    theme?: Record<string, string>;
+    /** Test hooks. */
+    newAttemptId?: () => string;
+};
+type EmbeddedPaymentState = {
+    status: EmbeddedPaymentStatus;
+    /** Text to show for the current state (decline reason, review notice, error...). */
+    message: string | null;
+    outcome: PaymentOutcome | null;
+    error: PaymentErrorView | null;
+    fallbackReason: PaymentFallbackReason | null;
+    attemptsLeft: number | null;
+    /** Id of the current attempt (stable across network retries). */
+    attemptId: string | null;
+    /** `true` while loading, mounting or processing. */
+    busy: boolean;
+    /** Attach to the element the provider renders into. */
+    containerRef: (el: HTMLElement | null) => void;
+    containerId: string;
+    /** Tokenises and sends. No-ops while another submit is in flight (double click safe). */
+    submit: () => Promise<void>;
+    /** Repeats the last submit with the SAME attempt after a network failure. */
+    retry: () => Promise<void>;
+    /** After a rejection: clears the message (the form is remounted by the hook). */
+    dismiss: () => void;
+};
+/**
+ * Embedded payment state machine for one card form.
+ *
+ * Guarantees:
+ * - The amount is the server's: it is passed to the provider widget and echoed as `expected_total`; never computed.
+ * - One idempotency key per attempt (`attempt`), kept in `storage`, reused on network retries and rotated only
+ *   after a definitive answer (a rejected card needs a new token, hence a new attempt).
+ * - Card data never reaches this code or storage: only the provider token, held in memory until the answer.
+ * - A double click returns the in-flight promise instead of sending twice.
+ */
+declare function useEmbeddedPayment(options: UseEmbeddedPaymentOptions): EmbeddedPaymentState;
+
+type VoucherCardProps = {
+    outcome: PaymentOutcome;
+    locale?: string;
+    messages?: Partial<PaymentMessages>;
+    className?: string;
+};
+/**
+ * Cash/SPEI voucher: point, exact amount, reference, barcode/CLABE and deadline, all from the server.
+ * The link only renders for https URLs (already filtered by `paymentOutcome`).
+ */
+declare function VoucherCard({ outcome, locale, messages, className }: VoucherCardProps): react.JSX.Element | null;
+type PaymentChallengeProps = {
+    outcome: PaymentOutcome;
+    locale?: string;
+    messages?: Partial<PaymentMessages>;
+    /** Replace the default iframe (e.g. mount the provider's status screen). */
+    render?: (outcome: PaymentOutcome) => ReactNode;
+    onCancel?: () => void;
+};
+/** 3DS inside the page: a modal dialog with title and focus trap. Default content is the bank's https iframe. */
+declare function PaymentChallenge({ outcome, locale, messages, render, onCancel }: PaymentChallengeProps): react.JSX.Element;
+type PaymentBrickHandle = EmbeddedPaymentState;
+type PaymentBrickProps = Omit<UseEmbeddedPaymentOptions, 'amount'> & {
+    /** The server's total. Shown on the button and passed to the provider widget. */
+    amount: Money;
+    /** When set, renders the shop's pay button with this label. Otherwise drive it through the ref. */
+    submitLabel?: ReactNode;
+    /** Hide the total next to the label. */
+    hideAmountInButton?: boolean;
+    /** Rendered instead of the built-in voucher card. */
+    renderVoucher?: (outcome: PaymentOutcome) => ReactNode;
+    renderChallenge?: (outcome: PaymentOutcome) => ReactNode;
+    /** Height reserved for the provider form so the page does not jump. Default 360. */
+    minHeight?: number | string;
+    className?: string;
+    style?: CSSProperties;
+};
+/**
+ * Card form for an embedded payment. Headless: no styles of its own, only `data-*` hooks and CSS variables
+ * (`--sf-pay-*`, read for the provider widget; `--sf-pay-min-height` for the reserved height).
+ *
+ * Accessibility: the container is labelled and `aria-busy` while loading; every message goes through one
+ * `role="status"` region (or `role="alert"` for errors, which also takes focus); the button explains why it is
+ * busy and never silently disables.
+ *
+ * Use the `ref` to get the same state the hook returns (`submit`, `retry`, `status`...) when the shop owns the button.
+ */
+declare const PaymentBrick: react.ForwardRefExoticComponent<Omit<UseEmbeddedPaymentOptions, "amount"> & {
+    /** The server's total. Shown on the button and passed to the provider widget. */
+    amount: Money;
+    /** When set, renders the shop's pay button with this label. Otherwise drive it through the ref. */
+    submitLabel?: ReactNode;
+    /** Hide the total next to the label. */
+    hideAmountInButton?: boolean;
+    /** Rendered instead of the built-in voucher card. */
+    renderVoucher?: (outcome: PaymentOutcome) => ReactNode;
+    renderChallenge?: (outcome: PaymentOutcome) => ReactNode;
+    /** Height reserved for the provider form so the page does not jump. Default 360. */
+    minHeight?: number | string;
+    className?: string;
+    style?: CSSProperties;
+} & react.RefAttributes<EmbeddedPaymentState>>;
+
+/** The `PaymentClient.kind` the addon `mercadopago` declares. */
+declare const MERCADOPAGO_BRICKS_KIND = "mercadopago_bricks";
+type MpController = {
+    getFormData(): Promise<Record<string, unknown> | undefined | null>;
+    unmount(): void | Promise<void>;
+};
+type MpBricks = {
+    create(brick: string, containerId: string, settings: Record<string, unknown>): Promise<MpController>;
+};
+type MercadoPagoCtor = new (publicKey: string, options?: {
+    locale?: string;
+}) => {
+    bricks(): MpBricks;
+};
+type MercadoPagoAdapterOptions = {
+    /** Exact origins allowed for `sdk_url`. Default: Mercado Pago's SDK origin only. */
+    allowedSdkOrigins?: readonly string[];
+    /** Resolves the SDK constructor. Default: `window.MercadoPago`. Inject a fake in tests. */
+    getSdk?: () => MercadoPagoCtor | undefined;
+    /** Reads the anti-fraud device id. Default: `window.MP_DEVICE_SESSION_ID`. */
+    getDeviceSessionId?: () => string | undefined;
+};
+/**
+ * The only fields that may leave the browser, and the only place that decides it. Anything else the SDK returns
+ * (notably `transaction_amount`, the amount: the server owns it) is dropped. Strings only, bounded length.
+ */
+declare function sanitizeMercadoPagoFormData(data: Record<string, unknown> | null | undefined): Record<string, unknown>;
+/**
+ * Card Payment Brick adapter. The payment button is hidden: the shop's own button calls `collect()` (MP's
+ * `getFormData()`), which tokenises inside MP's iframes. Card data never touches this code.
+ */
+declare function mercadoPagoBricksAdapter(options?: MercadoPagoAdapterOptions): PaymentFormAdapter;
+
+/**
+ * Loads a provider script once, with timeout, CSP nonce and an origin allowlist.
+ * The URL comes from the server (`PaymentClient.sdk_url`) but is still checked:
+ * https only and, when `allowedOrigins` is given, an exact origin match.
+ */
+type LoadScriptOptions = {
+    nonce?: string;
+    timeoutMs: number;
+    /** Exact origins allowed for the script (`https://sdk.mercadopago.com`). Omitted: any https origin. */
+    allowedOrigins?: readonly string[];
+    /** `true` when the SDK global is already there (skips the insert). */
+    isLoaded?: () => boolean;
+    document?: Document;
+};
+declare function loadPaymentSdk(url: string, options: LoadScriptOptions): Promise<void>;
+/** Test helper: forgets the loaded-script cache. */
+declare function resetPaymentSdkCache(): void;
+
+type PaymentCspOptions = {
+    /** Per-request nonce; also set it on the inserted `<script>` and on `<Scripts nonce>`. */
+    nonce?: string;
+    /** Extra origins by directive (e.g. your image CDN). */
+    extra?: {
+        script?: string[];
+        frame?: string[];
+        connect?: string[];
+        img?: string[];
+        form?: string[];
+    };
+    /** `report-uri` / `report-to` target for the report-only rollout. */
+    reportUri?: string;
+};
+/**
+ * Builds the Content-Security-Policy for the payment routes from what each provider declares
+ * (`PaymentClient.csp`), so the shop never hard-codes provider hosts. Meant for `/pagar` only,
+ * never for the whole site. Roll out as `Content-Security-Policy-Report-Only` first.
+ *
+ * No SRI on purpose: provider SDK URLs are unversioned and a hash would break payments on any update.
+ */
+declare function paymentCsp(clients: readonly (PaymentClient | null | undefined)[], options?: PaymentCspOptions): string;
+/** `Content-Security-Policy` or, during the rollout week, `Content-Security-Policy-Report-Only`. */
+declare function paymentCspHeaderName(reportOnly: boolean): string;
+
+/** CSS custom properties (set by the shop in its stylesheet) -> provider widget variables. */
+declare const PAYMENT_THEME_TOKENS: {
+    readonly '--sf-pay-text': "textPrimaryColor";
+    readonly '--sf-pay-text-muted': "textSecondaryColor";
+    readonly '--sf-pay-background': "formBackgroundColor";
+    readonly '--sf-pay-input-background': "inputBackgroundColor";
+    readonly '--sf-pay-primary': "baseColor";
+    readonly '--sf-pay-primary-contrast': "buttonTextColor";
+    readonly '--sf-pay-error': "errorColor";
+    readonly '--sf-pay-success': "successColor";
+    readonly '--sf-pay-outline': "outlinePrimaryColor";
+    readonly '--sf-pay-radius': "borderRadiusMedium";
+};
+/**
+ * Reads the `--sf-pay-*` tokens from an element's computed style, so the provider form follows the shop's
+ * theme without the shop copying colors into JavaScript. Unsafe or empty values are skipped.
+ */
+declare function readPaymentTheme(el: Element | null | undefined, tokens?: Record<string, string>): Record<string, string>;
+
+export { type EmbeddedPaymentState, type EmbeddedPaymentStatus, type FetchTransportOptions, type LoadScriptOptions, MERCADOPAGO_BRICKS_KIND, type MercadoPagoAdapterOptions, type MercadoPagoCtor, type MountedPaymentForm, PAYMENT_THEME_TOKENS, PaymentBrick, type PaymentBrickHandle, type PaymentBrickProps, PaymentChallenge, type PaymentChallengeProps, type PaymentCspOptions, type PaymentEvent, type PaymentFallbackReason, type PaymentFormAdapter, type PaymentFormData, type PaymentFormError, type PaymentFormMountOptions, PaymentHttpError, type PaymentSubmitRequest, type PaymentTransport, type UseEmbeddedPaymentOptions, VoucherCard, type VoucherCardProps, createFetchTransport, loadPaymentSdk, mercadoPagoBricksAdapter, paymentCsp, paymentCspHeaderName, readPaymentTheme, resetPaymentSdkCache, sanitizeMercadoPagoFormData, useEmbeddedPayment };