@m2c/checkout 0.1.0

package/dist/errors.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Typed error surface for the checkout SDK. The taxonomy mirrors the bid
+ * server's response codes for the auction and status-read endpoints so a
+ * merchant can branch on `code` without sniffing HTTP statuses or message text.
+ */
+export type CheckoutErrorCode = 'InvalidRequest' | 'OriginNotAllowed' | 'AccountSuspended' | 'NoVendorsAvailable' | 'RateLimited' | 'ServiceUnavailable' | 'CheckoutExpired' | 'Network' | 'Unknown';
+export interface M2CCheckoutErrorOptions {
+    status?: number;
+    retryAfterSeconds?: number;
+    cause?: unknown;
+}
+/** Every error the checkout SDK rejects with is an instance of this class. */
+export declare class M2CCheckoutError extends Error {
+    readonly code: CheckoutErrorCode;
+    /** The HTTP status when the error came from a response; absent for client-side / network errors. */
+    readonly status?: number;
+    /** Present when the server sent a Retry-After header (seconds). */
+    readonly retryAfterSeconds?: number;
+    constructor(code: CheckoutErrorCode, message: string, options?: M2CCheckoutErrorOptions);
+    /**
+     * Whether re-attempting could plausibly succeed. Transient conditions
+     * (rate limit, 5xx / unavailable, network) are retryable; auth and contract
+     * failures (bad origin, suspended, invalid request) never are. The poll loop
+     * uses this to decide whether to swallow a status-read failure and keep
+     * polling or surface it to the integrator.
+     */
+    get retryable(): boolean;
+}
+/**
+ * Map a non-2xx auction response to a typed error. The bid server returns the
+ * same HTTP status for more than one 403 condition (origin vs suspended), so we
+ * disambiguate on the body's error string - the only signal available - and
+ * fall back to OriginNotAllowed, the far more common case, when it is absent.
+ */
+export declare function auctionErrorForResponse(status: number, bodyError: string | undefined, retryAfterSeconds: number | undefined): M2CCheckoutError;
+/**
+ * Parse a Retry-After header into seconds. Accepts RFC 7231 delta-seconds or an
+ * HTTP-date; rejects junk (e.g. "-1", "1.5") so it never yields a negative or
+ * fractional backoff. Returns undefined when there is nothing usable, leaving
+ * the caller on its normal backoff schedule.
+ */
+export declare function parseRetryAfter(header: string | null): number | undefined;

package/dist/errors.js

@@ -0,0 +1,79 @@
+/** Every error the checkout SDK rejects with is an instance of this class. */
+export class M2CCheckoutError extends Error {
+    constructor(code, message, options = {}) {
+        super(message);
+        this.name = 'M2CCheckoutError';
+        this.code = code;
+        this.status = options.status;
+        this.retryAfterSeconds = options.retryAfterSeconds;
+        // Preserve the originating error without widening the public type surface.
+        if (options.cause !== undefined) {
+            this.cause = options.cause;
+        }
+    }
+    /**
+     * Whether re-attempting could plausibly succeed. Transient conditions
+     * (rate limit, 5xx / unavailable, network) are retryable; auth and contract
+     * failures (bad origin, suspended, invalid request) never are. The poll loop
+     * uses this to decide whether to swallow a status-read failure and keep
+     * polling or surface it to the integrator.
+     */
+    get retryable() {
+        return (this.code === 'RateLimited' ||
+            this.code === 'ServiceUnavailable' ||
+            this.code === 'Network');
+    }
+}
+/**
+ * Map a non-2xx auction response to a typed error. The bid server returns the
+ * same HTTP status for more than one 403 condition (origin vs suspended), so we
+ * disambiguate on the body's error string - the only signal available - and
+ * fall back to OriginNotAllowed, the far more common case, when it is absent.
+ */
+export function auctionErrorForResponse(status, bodyError, retryAfterSeconds) {
+    const message = bodyError && bodyError.trim() !== '' ? bodyError : `auction failed: ${status}`;
+    switch (status) {
+        case 400:
+            return new M2CCheckoutError('InvalidRequest', message, { status });
+        case 403:
+            if (bodyError && /suspend/i.test(bodyError)) {
+                return new M2CCheckoutError('AccountSuspended', message, { status });
+            }
+            return new M2CCheckoutError('OriginNotAllowed', message, { status });
+        case 404:
+            return new M2CCheckoutError('NoVendorsAvailable', message, { status });
+        case 429:
+            return new M2CCheckoutError('RateLimited', message, { status, retryAfterSeconds });
+        default:
+            if (status >= 500 && status <= 599) {
+                return new M2CCheckoutError('ServiceUnavailable', message, { status, retryAfterSeconds });
+            }
+            return new M2CCheckoutError('Unknown', message, { status });
+    }
+}
+/**
+ * Parse a Retry-After header into seconds. Accepts RFC 7231 delta-seconds or an
+ * HTTP-date; rejects junk (e.g. "-1", "1.5") so it never yields a negative or
+ * fractional backoff. Returns undefined when there is nothing usable, leaving
+ * the caller on its normal backoff schedule.
+ */
+export function parseRetryAfter(header) {
+    if (!header)
+        return undefined;
+    const trimmed = header.trim();
+    if (trimmed === '')
+        return undefined;
+    if (/^\d+$/.test(trimmed)) {
+        const seconds = Number(trimmed);
+        return Number.isFinite(seconds) ? seconds : undefined;
+    }
+    // A bare signed/fractional number is neither valid delta-seconds nor an
+    // HTTP-date; Date.parse would misread some of these as historical dates.
+    if (/^[+-]?(?:\d+(?:\.\d*)?|\.\d+)$/.test(trimmed)) {
+        return undefined;
+    }
+    const dateMs = Date.parse(trimmed);
+    if (Number.isNaN(dateMs))
+        return undefined;
+    return Math.max(0, Math.ceil((dateMs - Date.now()) / 1000));
+}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { createClient } from './client.js';
+export { M2CCheckoutError } from './errors.js';
+export type { CheckoutErrorCode } from './errors.js';
+export { DEFAULT_POLL_CONFIG } from './poll.js';
+export type { CheckoutClient, CheckoutResult, CheckoutState, ClientConfig, ClientStatus, LaunchMode, Navigate, OpenCheckoutWindow, PollConfig, ResumeParams, StartFromSessionParams, StartParams, StateChangeContext, StateChangeListener, StatusSource, SubscribeAdapter, CheckoutStorage, } from './types.js';

package/dist/index.js

@@ -0,0 +1,3 @@
+export { createClient } from './client.js';
+export { M2CCheckoutError } from './errors.js';
+export { DEFAULT_POLL_CONFIG } from './poll.js';

package/dist/poll.d.ts

@@ -0,0 +1,25 @@
+import type { ClientStatus, PollConfig } from './types.js';
+/** Default schedule: immediate, then 1s, 2s, 4s, 8s, capped at 8s, total ~90s window. */
+export declare const DEFAULT_POLL_CONFIG: PollConfig;
+/** Resolves the current advisory status for a request, or throws on a read failure. */
+export type CheckStatusFn = (requestId: string) => Promise<ClientStatus>;
+/** Injectable clock + sleeper so the schedule is deterministically testable. */
+export interface PollDeps {
+    sleep: (ms: number) => Promise<void>;
+    now: () => number;
+}
+export declare const realPollDeps: PollDeps;
+/**
+ * Poll a status source on a bounded exponential backoff until it returns a
+ * terminal status or the window elapses.
+ *
+ * Transient read failures (rate limit, 5xx, network, not-yet-visible row) are
+ * swallowed and retried: the read is advisory and the webhook is the truth, so
+ * a flaky read must not fail the checkout. A developer-actionable failure
+ * (bad origin, invalid request) is NOT swallowed - it is rethrown so the
+ * integrator sees their misconfiguration instead of a silent `pending_timeout`.
+ *
+ * On window timeout returns `processing`; the caller maps that to the terminal
+ * `pending_timeout` result. Never rejects on a terminal status.
+ */
+export declare function pollStatus(checkStatus: CheckStatusFn, requestId: string, config: PollConfig, deps?: PollDeps): Promise<ClientStatus>;

package/dist/poll.js

@@ -0,0 +1,51 @@
+import { M2CCheckoutError } from './errors.js';
+/** Default schedule: immediate, then 1s, 2s, 4s, 8s, capped at 8s, total ~90s window. */
+export const DEFAULT_POLL_CONFIG = {
+    firstDelayMs: 1000,
+    maxDelayMs: 8000,
+    factor: 2,
+    windowMs: 90000,
+};
+export const realPollDeps = {
+    sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+    now: () => Date.now(),
+};
+/**
+ * Poll a status source on a bounded exponential backoff until it returns a
+ * terminal status or the window elapses.
+ *
+ * Transient read failures (rate limit, 5xx, network, not-yet-visible row) are
+ * swallowed and retried: the read is advisory and the webhook is the truth, so
+ * a flaky read must not fail the checkout. A developer-actionable failure
+ * (bad origin, invalid request) is NOT swallowed - it is rethrown so the
+ * integrator sees their misconfiguration instead of a silent `pending_timeout`.
+ *
+ * On window timeout returns `processing`; the caller maps that to the terminal
+ * `pending_timeout` result. Never rejects on a terminal status.
+ */
+export async function pollStatus(checkStatus, requestId, config, deps = realPollDeps) {
+    const deadline = deps.now() + config.windowMs;
+    let delayMs = 0; // first poll is immediate
+    for (;;) {
+        if (delayMs > 0) {
+            await deps.sleep(delayMs);
+        }
+        let status = 'processing';
+        try {
+            status = await checkStatus(requestId);
+        }
+        catch (err) {
+            if (err instanceof M2CCheckoutError && !err.retryable) {
+                throw err;
+            }
+            status = 'processing';
+        }
+        if (status === 'completed' || status === 'failed' || status === 'canceled') {
+            return status;
+        }
+        if (deps.now() >= deadline) {
+            return 'processing';
+        }
+        delayMs = delayMs === 0 ? config.firstDelayMs : Math.min(delayMs * config.factor, config.maxDelayMs);
+    }
+}

package/dist/status.d.ts

@@ -0,0 +1,17 @@
+import type { CheckStatusFn } from './poll.js';
+import type { StatusSourceRef } from './storage.js';
+import type { NormalizedConfig, StatusSource } from './types.js';
+/**
+ * Rebuild a live status reader from the persisted ref and the (re-instantiated)
+ * config. `m2c` and `url` rebuild from config alone; `callback` needs the
+ * function re-supplied on the return page (functions do not survive the
+ * redirect). `subscribe` is reserved and rejected for now (see README).
+ */
+export declare function resolveStatusSource(ref: StatusSourceRef, config: NormalizedConfig, resupplied: StatusSource | undefined): CheckStatusFn;
+/**
+ * Build a one-shot status reader from the live, configured status source. Backs
+ * `client.checkStatus(requestId)`, which reconciles an outcome after the fact
+ * (e.g. a window_closed / pending_timeout that later completed) - separate from
+ * the resume-record-driven poll.
+ */
+export declare function checkStatusForSource(source: StatusSource, config: NormalizedConfig): CheckStatusFn;

package/dist/status.js

@@ -0,0 +1,175 @@
+import { M2CCheckoutError, parseRetryAfter } from './errors.js';
+const STATUS_PATH = '/api/v1/conversions';
+/**
+ * Rebuild a live status reader from the persisted ref and the (re-instantiated)
+ * config. `m2c` and `url` rebuild from config alone; `callback` needs the
+ * function re-supplied on the return page (functions do not survive the
+ * redirect). `subscribe` is reserved and rejected for now (see README).
+ */
+export function resolveStatusSource(ref, config, resupplied) {
+    switch (ref.kind) {
+        case 'm2c':
+            return m2cCheckStatus(config);
+        case 'url':
+            return urlCheckStatus(ref.template, config);
+        case 'callback': {
+            const source = resupplied ?? config.statusSource;
+            if (!source || source.kind !== 'callback' || typeof source.checkStatus !== 'function') {
+                throw new M2CCheckoutError('InvalidRequest', 'a callback status source must be re-supplied on the return page via resume({ statusSource }) or createClient({ statusSource }); a function cannot survive the redirect');
+            }
+            return callbackCheckStatus(source.checkStatus);
+        }
+        default:
+            throw new M2CCheckoutError('InvalidRequest', 'the subscribe status source is not supported yet; use m2c, url, or callback');
+    }
+}
+/**
+ * Build a one-shot status reader from the live, configured status source. Backs
+ * `client.checkStatus(requestId)`, which reconciles an outcome after the fact
+ * (e.g. a window_closed / pending_timeout that later completed) - separate from
+ * the resume-record-driven poll.
+ */
+export function checkStatusForSource(source, config) {
+    switch (source.kind) {
+        case 'm2c':
+            return m2cCheckStatus(config);
+        case 'url':
+            return urlCheckStatus(source.template, config);
+        case 'callback':
+            return callbackCheckStatus(source.checkStatus);
+        default:
+            throw new M2CCheckoutError('InvalidRequest', 'the subscribe status source is not supported yet; use m2c, url, or callback');
+    }
+}
+function m2cCheckStatus(config) {
+    if (!config.publishableKey) {
+        throw new M2CCheckoutError('InvalidRequest', 'the m2c status source requires a publishableKey (re-supply it on the return page)');
+    }
+    if (!config.fetch) {
+        throw new M2CCheckoutError('InvalidRequest', 'no fetch implementation available');
+    }
+    const fetchImpl = config.fetch;
+    const key = config.publishableKey;
+    return async (requestId) => {
+        const url = `${config.baseUrl}${STATUS_PATH}/${encodeURIComponent(requestId)}`;
+        let res;
+        try {
+            res = await fetchImpl(url, {
+                method: 'GET',
+                headers: { 'X-API-Key': key },
+                credentials: 'omit',
+                redirect: 'error',
+            });
+        }
+        catch (err) {
+            throw new M2CCheckoutError('Network', `status read failed: ${err.message}`, {
+                cause: err,
+            });
+        }
+        if (res.status === 200) {
+            return parseClientStatus(await res.text().catch(() => ''));
+        }
+        throw statusReadError(res.status, parseRetryAfter(res.headers.get('retry-after')));
+    };
+}
+function urlCheckStatus(template, config) {
+    if (typeof template !== 'string' || template === '') {
+        throw new M2CCheckoutError('InvalidRequest', 'url status source requires a non-empty template');
+    }
+    if (!config.fetch) {
+        throw new M2CCheckoutError('InvalidRequest', 'no fetch implementation available');
+    }
+    const fetchImpl = config.fetch;
+    return async (requestId) => {
+        const url = template.replace(/\{request_id\}/g, encodeURIComponent(requestId));
+        let res;
+        try {
+            // Default (same-origin) credentials: a merchant status endpoint on the
+            // page's own origin commonly authenticates the customer by cookie.
+            res = await fetchImpl(url, { method: 'GET' });
+        }
+        catch (err) {
+            throw new M2CCheckoutError('Network', `merchant status read failed: ${err.message}`, {
+                cause: err,
+            });
+        }
+        if (res.ok) {
+            return parseClientStatus(await res.text().catch(() => ''));
+        }
+        // The merchant endpoint's error shape is theirs; treat any non-2xx as
+        // transient so the poll keeps trying within the window rather than failing
+        // the checkout on a blip.
+        throw new M2CCheckoutError('ServiceUnavailable', `merchant status endpoint returned ${res.status}`, { status: res.status });
+    };
+}
+function callbackCheckStatus(fn) {
+    return async (requestId) => {
+        try {
+            return coerceClientStatus(await fn(requestId));
+        }
+        catch (err) {
+            // A merchant callback throwing is treated as transient: the read is
+            // advisory, so a flaky backend should not fail the checkout. Persisting
+            // failures resolve to pending_timeout when the window elapses.
+            throw new M2CCheckoutError('ServiceUnavailable', `status callback threw: ${err.message}`, {
+                cause: err,
+            });
+        }
+    };
+}
+/**
+ * Map the status read JSON to a ClientStatus. Merchant status endpoints often
+ * reflect M2C webhook statuses directly, so accept both the client enum and the
+ * internal/webhook terminal names. An unrecognized or missing value is treated
+ * as `processing` (fail safe) so the poll continues rather than mistaking an
+ * unexpected payload for a terminal outcome.
+ */
+function parseClientStatus(text) {
+    let status;
+    try {
+        const obj = JSON.parse(text);
+        status = typeof obj === 'object' && obj !== null ? obj.status : undefined;
+    }
+    catch {
+        status = undefined;
+    }
+    return coerceClientStatus(status);
+}
+function coerceClientStatus(status) {
+    switch (status) {
+        case 'completed':
+        case 'refunded':
+        case 'chargedback':
+            return 'completed';
+        case 'failed':
+            return 'failed';
+        case 'canceled':
+        case 'abandoned':
+            return 'canceled';
+        case 'processing':
+        case 'pending':
+            return 'processing';
+        default:
+            return 'processing';
+    }
+}
+function statusReadError(status, retryAfterSeconds) {
+    switch (status) {
+        case 400:
+            return new M2CCheckoutError('InvalidRequest', 'status read rejected the request', { status });
+        case 403:
+            return new M2CCheckoutError('OriginNotAllowed', 'origin not allowed for this key', { status });
+        case 429:
+            return new M2CCheckoutError('RateLimited', 'status read rate limited', { status, retryAfterSeconds });
+        case 404:
+            // The row is account-scoped and may briefly not be visible to this key
+            // just after the auction; treat as transient so the poll retries rather
+            // than failing. A persistent 404 resolves to pending_timeout.
+            return new M2CCheckoutError('ServiceUnavailable', 'status not yet available', { status });
+        default:
+            if (status >= 500 && status <= 599) {
+                return new M2CCheckoutError('ServiceUnavailable', `status read returned ${status}`, { status });
+            }
+            return new M2CCheckoutError('Unknown', `status read returned ${status}`, { status });
+    }
+}

package/dist/storage.d.ts

@@ -0,0 +1,37 @@
+import type { CheckoutStorage, LaunchMode, StatusSource } from './types.js';
+/**
+ * Serializable descriptor of the status source, persisted across the full-page
+ * redirect. A `callback` function cannot be serialized, so only its kind is
+ * stored; the merchant must re-supply the function on the return page. `m2c`
+ * and `url` carry everything needed to rebuild the source from config alone.
+ */
+export type StatusSourceRef = {
+    kind: 'm2c';
+} | {
+    kind: 'url';
+    template: string;
+} | {
+    kind: 'callback';
+} | {
+    kind: 'subscribe';
+};
+/** What `start*` writes before navigating away. */
+export interface ResumeRecord {
+    v: 1;
+    requestId: string;
+    mode: 'client' | 'session';
+    launchMode?: LaunchMode;
+    statusSourceRef: StatusSourceRef;
+    /** Epoch ms when the checkout was started. */
+    startedAt: number;
+    /** Validity in seconds, if known. */
+    ttl?: number;
+}
+export declare function statusSourceRefFor(source: StatusSource): StatusSourceRef;
+export declare function writeResumeRecord(storage: CheckoutStorage, key: string, record: ResumeRecord): void;
+/**
+ * Read and immediately clear the resume record. Clearing first (even on a
+ * malformed value) makes resume single-shot: a refresh of the return page does
+ * not re-poll a stale checkout. Returns null when nothing valid was stored.
+ */
+export declare function readAndClearResumeRecord(storage: CheckoutStorage, key: string): ResumeRecord | null;

package/dist/storage.js

@@ -0,0 +1,62 @@
+export function statusSourceRefFor(source) {
+    switch (source.kind) {
+        case 'url':
+            return { kind: 'url', template: source.template };
+        case 'callback':
+            return { kind: 'callback' };
+        case 'subscribe':
+            return { kind: 'subscribe' };
+        default:
+            return { kind: 'm2c' };
+    }
+}
+export function writeResumeRecord(storage, key, record) {
+    storage.setItem(key, JSON.stringify(record));
+}
+/**
+ * Read and immediately clear the resume record. Clearing first (even on a
+ * malformed value) makes resume single-shot: a refresh of the return page does
+ * not re-poll a stale checkout. Returns null when nothing valid was stored.
+ */
+export function readAndClearResumeRecord(storage, key) {
+    const raw = storage.getItem(key);
+    if (!raw)
+        return null;
+    storage.removeItem(key);
+    try {
+        const parsed = JSON.parse(raw);
+        if (isResumeRecord(parsed)) {
+            return parsed;
+        }
+    }
+    catch {
+        // Corrupt value (manual tampering, partial write): treat as no record.
+    }
+    return null;
+}
+function isResumeRecord(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const r = value;
+    if (r.v !== 1)
+        return false;
+    if (typeof r.requestId !== 'string' || r.requestId === '')
+        return false;
+    if (r.mode !== 'client' && r.mode !== 'session')
+        return false;
+    if (typeof r.startedAt !== 'number')
+        return false;
+    if (typeof r.statusSourceRef !== 'object' || r.statusSourceRef === null)
+        return false;
+    const ref = r.statusSourceRef;
+    switch (ref.kind) {
+        case 'm2c':
+        case 'callback':
+        case 'subscribe':
+            return true;
+        case 'url':
+            return typeof ref.template === 'string' && ref.template !== '';
+        default:
+            return false;
+    }
+}