@m2c/checkout 0.1.0

package/dist/types.d.ts

@@ -0,0 +1,178 @@
+import type { M2CCheckoutError } from './errors.js';
+/**
+ * Client-facing conversion status, mapped server-side from the internal
+ * `auction_logs.conversion_status` (see foundations 4c). `processing` is the
+ * only non-terminal value; the others end a poll.
+ */
+export type ClientStatus = 'processing' | 'completed' | 'failed' | 'canceled';
+/** Lifecycle states the SDK passes through. Drives the merchant's progress UI. */
+export type CheckoutState = 'idle' | 'creating' | 'ready' | 'launching' | 'awaiting_return' | 'returned' | 'polling' | 'completed' | 'failed' | 'canceled' | 'pending_timeout' | 'window_closed' | 'error';
+/** Terminal outcome of a checkout. `pending_timeout` resolves; it does not reject. */
+export type CheckoutResult = {
+    status: 'completed';
+    requestId: string;
+} | {
+    status: 'failed';
+    requestId: string;
+} | {
+    status: 'canceled';
+    requestId: string;
+} | {
+    status: 'pending_timeout';
+    requestId: string;
+} | {
+    status: 'window_closed';
+    requestId: string;
+};
+export interface StateChangeContext {
+    /** The auction request id once known. */
+    requestId?: string;
+    /** Set only on the `error` state. */
+    error?: M2CCheckoutError;
+}
+export type StateChangeListener = (state: CheckoutState, ctx: StateChangeContext) => void;
+/** Bounded-exponential-backoff poll schedule. A single shared definition; see foundations 6. */
+export interface PollConfig {
+    /** Delay before the second poll (the first poll is immediate). */
+    firstDelayMs: number;
+    /** Ceiling each delay doubles toward. */
+    maxDelayMs: number;
+    /** Multiplier applied to the delay each attempt. */
+    factor: number;
+    /** Total wall-clock budget; on elapse the poll resolves to a `pending_timeout`. */
+    windowMs: number;
+}
+/** Adapter for a push status channel (SSE/websocket). Reserved; see README. */
+export type SubscribeAdapter = (requestId: string, onStatus: (status: ClientStatus) => void) => () => void;
+/**
+ * Where the SDK reads status from after the customer returns.
+ * - `m2c`: the M2C advisory read endpoint (client-initiated; needs the publishable key).
+ * - `url`: a merchant endpoint template; `{request_id}` is substituted.
+ * - `callback`: an arbitrary function the merchant supplies.
+ * - `subscribe`: a push adapter (reserved for a future release).
+ */
+export type StatusSource = {
+    kind: 'm2c';
+} | {
+    kind: 'url';
+    template: string;
+} | {
+    kind: 'callback';
+    checkStatus: (requestId: string) => Promise<ClientStatus>;
+} | {
+    kind: 'subscribe';
+    subscribe: SubscribeAdapter;
+};
+/** The subset of the Web Storage API the SDK uses. `sessionStorage` satisfies it. */
+export interface CheckoutStorage {
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+    removeItem(key: string): void;
+}
+/** Performs the page navigation to the vendor checkout. Defaults to `location.assign`. */
+export type Navigate = (url: string) => void;
+/**
+ * How checkout is launched. `redirect` is the default and is the most reliable.
+ * `new_tab` and `popup` pre-open a same-origin blank window before async work,
+ * then navigate it after the checkout URL is known.
+ */
+export type LaunchMode = 'redirect' | 'new_tab' | 'popup';
+/** Opens a browser window/tab for popup launch mode. Defaults to `window.open`. */
+export type OpenCheckoutWindow = (url: string, target: string, features?: string) => Window | null;
+export interface ClientConfig {
+    /** Bid API base, e.g. `https://api.m2cmarkets.com`. */
+    baseUrl: string;
+    /** Required only for client-initiated `start()` and the `m2c` status source. */
+    publishableKey?: string;
+    /** Default status source. Defaults to `{ kind: 'm2c' }`. */
+    statusSource?: StatusSource;
+    /** Override the default poll backoff/window. */
+    poll?: Partial<PollConfig>;
+    /** Storage namespace for the resume record. Defaults to `m2c.checkout`. */
+    storageKey?: string;
+    /** Injectable `fetch` (testing / non-standard runtimes). Defaults to global `fetch`. */
+    fetch?: typeof fetch;
+    /** Injectable storage. Defaults to browser storage when available. */
+    storage?: CheckoutStorage;
+    /** Injectable navigation. Defaults to `location.assign`. */
+    navigate?: Navigate;
+    /** Where to open the vendor checkout. Defaults to `redirect`. */
+    launchMode?: LaunchMode;
+    /** Injectable `window.open` equivalent for `new_tab` / `popup` launch modes. */
+    openWindow?: OpenCheckoutWindow;
+    /**
+     * Popup/new-tab fallback: resolve `window_closed` if no return handoff arrives
+     * within this many milliseconds. Off by default.
+     */
+    returnTimeoutMs?: number;
+    /**
+     * Permit `http://` base and return URLs to loopback hosts (local dev only).
+     * Off by default: production return URLs must be `https`.
+     */
+    allowInsecureUrls?: boolean;
+}
+/** Fields for a client-initiated auction. Money is in major currency units (e.g. 49.99). */
+export interface StartParams {
+    transactionValue: number;
+    currency?: string;
+    description?: string;
+    successUrl: string;
+    cancelUrl: string;
+    segments?: string[];
+    language?: string;
+    deviceType?: string;
+    referrer?: string;
+    reference?: string;
+}
+/** A backend-created session forwarded to the client (the blessed default mode). */
+export interface StartFromSessionParams {
+    checkoutUrl: string;
+    requestId: string;
+    /** Remaining validity in seconds, if the backend forwarded it. */
+    ttl?: number;
+}
+export interface ResumeParams {
+    /**
+     * Which return URL this page is. The SDK cannot tell success_url from
+     * cancel_url on its own, so the merchant declares it. Defaults to `success`.
+     */
+    outcome?: 'success' | 'cancel';
+    /**
+     * Re-supply a non-serializable status source (`callback`) on the return page;
+     * a function cannot survive the full-page redirect.
+     */
+    statusSource?: StatusSource;
+}
+export interface CheckoutClient {
+    /** Client-initiated: run the auction, then launch the vendor checkout. */
+    start(params: StartParams): Promise<CheckoutResult>;
+    /** Backend-initiated: launch a checkout the backend already created. */
+    startFromSession(params: StartFromSessionParams): Promise<CheckoutResult>;
+    /** Call on the return page. Resolves the terminal result, or null if no checkout was in progress. */
+    resume(params?: ResumeParams): Promise<CheckoutResult | null>;
+    /**
+     * One-shot status read for a requestId via the configured status source.
+     * Reconciles an ambiguous outcome (`window_closed` / `pending_timeout`) after
+     * the fact; does not change lifecycle state and may resolve `processing`.
+     */
+    checkStatus(requestId: string): Promise<ClientStatus>;
+    /** Subscribe to lifecycle transitions. Returns an unsubscribe function. */
+    onStateChange(listener: StateChangeListener): () => void;
+    /** The current lifecycle state. */
+    getState(): CheckoutState;
+}
+/** Fully-resolved configuration the internal modules operate on. */
+export interface NormalizedConfig {
+    baseUrl: string;
+    publishableKey?: string;
+    statusSource: StatusSource;
+    poll: PollConfig;
+    storageKey: string;
+    fetch?: typeof fetch;
+    storage?: CheckoutStorage;
+    navigate?: Navigate;
+    launchMode: LaunchMode;
+    openWindow?: OpenCheckoutWindow;
+    returnTimeoutMs?: number;
+    allowInsecureUrls: boolean;
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/dist/validate.d.ts

@@ -0,0 +1,34 @@
+export declare const MAX_TRANSACTION_VALUE = 5000000000;
+export declare const UUID_RE: RegExp;
+/**
+ * UTF-8 byte length. The server measures string limits in bytes (Go `len`), so
+ * we must too; `String.length` counts UTF-16 units and would diverge on
+ * multi-byte input. TextEncoder is available in browsers and Node.
+ */
+export declare function utf8Bytes(value: string): number;
+/**
+ * A strict subset of the server's loopback check: localhost, ::1, 127.0.0.0/8.
+ * Gates the dev-only `allowInsecureUrls` escape hatch, never a security
+ * boundary - the server re-validates every URL. Keeping it a subset guarantees
+ * any host this accepts the server also treats as loopback.
+ */
+export declare function isLoopbackHost(host: string): boolean;
+export declare function assertTransactionValue(value: unknown): asserts value is number;
+/**
+ * Validate a base URL or return URL: a parseable absolute URL with a host, and
+ * `https` unless `allowInsecure` permits loopback `http`. Returns the original
+ * string so callers can use the validated value inline.
+ */
+export declare function validateUrl(value: unknown, label: string, allowInsecure: boolean): string;
+/**
+ * Validate a server-issued checkout_url. The byte cap mirrors the auction
+ * engine's maxCheckoutURLLength so the SDK does not reject a URL the server
+ * intentionally allowed.
+ */
+export declare function validateCheckoutUrl(value: unknown, label: string, allowInsecure: boolean): string;
+/** Validate the optional auction fields against the wire contract. */
+export declare function validateDescription(value: unknown): string | undefined;
+export declare function validateReferrer(value: unknown): string | undefined;
+export declare function validateReference(value: unknown): string | undefined;
+export declare function validateDeviceType(value: unknown): string | undefined;
+export declare function validateSegments(value: unknown): string[] | undefined;

package/dist/validate.js

@@ -0,0 +1,138 @@
+import { M2CCheckoutError } from './errors.js';
+// Mirror the bid server's wire limits (model/bid.go, foundations 4a) so a
+// contract violation fails client-side with a clear message instead of a
+// round-trip and a generic 400.
+export const MAX_TRANSACTION_VALUE = 5000000000;
+const MAX_RETURN_URL_BYTES = 2048;
+const MAX_CHECKOUT_URL_BYTES = 4096;
+const MAX_DESCRIPTION_BYTES = 256;
+const MAX_SEGMENTS = 20;
+const MAX_SEGMENT_BYTES = 128;
+const MAX_REFERRER_BYTES = 2048;
+const MAX_REFERENCE_BYTES = 512;
+const MAX_DEVICE_TYPE_BYTES = 64;
+// Canonical UUID. request_ids are always minted by the server, so this only
+// catches a backend forwarding the wrong field in startFromSession.
+export const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+function invalid(message) {
+    return new M2CCheckoutError('InvalidRequest', message);
+}
+/**
+ * UTF-8 byte length. The server measures string limits in bytes (Go `len`), so
+ * we must too; `String.length` counts UTF-16 units and would diverge on
+ * multi-byte input. TextEncoder is available in browsers and Node.
+ */
+export function utf8Bytes(value) {
+    return new TextEncoder().encode(value).length;
+}
+/**
+ * A strict subset of the server's loopback check: localhost, ::1, 127.0.0.0/8.
+ * Gates the dev-only `allowInsecureUrls` escape hatch, never a security
+ * boundary - the server re-validates every URL. Keeping it a subset guarantees
+ * any host this accepts the server also treats as loopback.
+ */
+export function isLoopbackHost(host) {
+    const h = host.toLowerCase();
+    if (h === 'localhost' || h === '::1' || h === '[::1]') {
+        return true;
+    }
+    const octets = h.split('.');
+    return (octets.length === 4 &&
+        octets[0] === '127' &&
+        octets.every((part) => /^\d+$/.test(part) && Number(part) <= 255));
+}
+export function assertTransactionValue(value) {
+    if (typeof value !== 'number' || !Number.isFinite(value)) {
+        throw invalid('transactionValue must be a finite number');
+    }
+    if (value <= 0) {
+        throw invalid('transactionValue must be greater than 0');
+    }
+    if (value > MAX_TRANSACTION_VALUE) {
+        throw invalid(`transactionValue must be at most ${MAX_TRANSACTION_VALUE} major units`);
+    }
+}
+/**
+ * Validate a base URL or return URL: a parseable absolute URL with a host, and
+ * `https` unless `allowInsecure` permits loopback `http`. Returns the original
+ * string so callers can use the validated value inline.
+ */
+export function validateUrl(value, label, allowInsecure) {
+    return validateHttpUrl(value, label, allowInsecure, MAX_RETURN_URL_BYTES);
+}
+/**
+ * Validate a server-issued checkout_url. The byte cap mirrors the auction
+ * engine's maxCheckoutURLLength so the SDK does not reject a URL the server
+ * intentionally allowed.
+ */
+export function validateCheckoutUrl(value, label, allowInsecure) {
+    return validateHttpUrl(value, label, allowInsecure, MAX_CHECKOUT_URL_BYTES);
+}
+function validateHttpUrl(value, label, allowInsecure, maxBytes) {
+    if (typeof value !== 'string' || value === '') {
+        throw invalid(`${label} is required`);
+    }
+    if (utf8Bytes(value) > maxBytes) {
+        throw invalid(`${label} must be at most ${maxBytes} bytes`);
+    }
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch {
+        throw invalid(`${label} must be a valid absolute URL`);
+    }
+    if (!url.host) {
+        throw invalid(`${label} must include a host`);
+    }
+    if (url.protocol === 'https:') {
+        return value;
+    }
+    if (allowInsecure && url.protocol === 'http:' && isLoopbackHost(url.hostname)) {
+        return value;
+    }
+    throw invalid(`${label} must be an https URL (set allowInsecureUrls to permit loopback http for dev)`);
+}
+function assertOptionalString(value, label, maxBytes) {
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== 'string') {
+        throw invalid(`${label} must be a string`);
+    }
+    if (utf8Bytes(value) > maxBytes) {
+        throw invalid(`${label} must be at most ${maxBytes} bytes`);
+    }
+    return value;
+}
+/** Validate the optional auction fields against the wire contract. */
+export function validateDescription(value) {
+    return assertOptionalString(value, 'description', MAX_DESCRIPTION_BYTES);
+}
+export function validateReferrer(value) {
+    return assertOptionalString(value, 'referrer', MAX_REFERRER_BYTES);
+}
+export function validateReference(value) {
+    return assertOptionalString(value, 'reference', MAX_REFERENCE_BYTES);
+}
+export function validateDeviceType(value) {
+    return assertOptionalString(value, 'deviceType', MAX_DEVICE_TYPE_BYTES);
+}
+export function validateSegments(value) {
+    if (value === undefined)
+        return undefined;
+    if (!Array.isArray(value)) {
+        throw invalid('segments must be an array of strings');
+    }
+    if (value.length > MAX_SEGMENTS) {
+        throw invalid(`segments must have at most ${MAX_SEGMENTS} entries`);
+    }
+    for (const entry of value) {
+        if (typeof entry !== 'string') {
+            throw invalid('segments must be an array of strings');
+        }
+        if (utf8Bytes(entry) > MAX_SEGMENT_BYTES) {
+            throw invalid(`each segment must be at most ${MAX_SEGMENT_BYTES} bytes`);
+        }
+    }
+    return value;
+}

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@m2c/checkout",
+  "version": "0.1.0",
+  "description": "Headless browser checkout SDK for M2C: run an auction, redirect to the winning vendor's hosted checkout, and reflect conversion status.",
+  "type": "module",
+  "engines": {
+    "node": ">=18"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "check:package-files": "node scripts/assert-local-example-unpublished.mjs",
+    "typecheck": "tsc -p tsconfig.test.json",
+    "test": "node --import tsx --test test/**/*.test.ts",
+    "serve:example": "npm run build && node example/server.mjs",
+    "prepack": "npm run build && npm run check:package-files",
+    "prepublishOnly": "npm run check:package-files"
+  },
+  "keywords": [
+    "m2c",
+    "payments",
+    "checkout",
+    "browser",
+    "sdk"
+  ],
+  "author": {
+    "name": "M2C Markets",
+    "url": "https://m2cmarkets.com"
+  },
+  "license": "MIT",
+  "bugs": {
+    "url": "https://m2cmarkets.com/contact"
+  },
+  "homepage": "https://m2cmarkets.com/docs",
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@types/node": "^20.11.0",
+    "tsx": "^4.7.0",
+    "typescript": "^5.4.0"
+  }
+}