@m2c/checkout 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 M2C
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,298 @@
+# @m2c/checkout
+
+Headless browser checkout SDK for [M2C](https://m2cmarkets.com). It runs an M2C
+auction, redirects the customer to the winning vendor's hosted checkout, and
+reflects the conversion status back to your UI when they return.
+
+It is **headless**: no components, no styles. You render every pixel (including
+the trigger button); the SDK gives you state, events, and a typed terminal
+result.
+
+It holds **no secrets and does no cryptography**. The signed, retried merchant
+webhook to your backend remains the source of truth for fulfillment - a return
+to `success_url` proves the customer came back, not that they paid. Treat this
+SDK's status as advisory UX.
+
+```
+npm install @m2c/checkout
+```
+
+ESM, zero runtime dependencies, ships `.d.ts` types. Targets evergreen browsers
+(ES2020). Importing the module is SSR-safe; the lifecycle methods need a DOM.
+
+## Two modes
+
+### Backend-initiated (recommended)
+
+Your backend creates the checkout with its secret key (the existing
+`POST /api/v1/auction` call **is** the create step) and forwards
+`checkout_url`, `request_id`, and `ttl` to the browser. No key ships in the
+client.
+
+```ts
+import { createClient } from '@m2c/checkout';
+
+const client = createClient({
+  baseUrl: 'https://api.m2cmarkets.com',
+  // Your backend already receives the M2C webhook, so it is the authoritative
+  // status source. Point the SDK at your own endpoint.
+  statusSource: { kind: 'url', template: 'https://shop.example/checkout-status?ref={request_id}' },
+});
+
+// session = { checkoutUrl, requestId, ttl } from your backend
+await client.startFromSession(session);
+```
+
+### Client-initiated (no-backend shortcut)
+
+The browser calls the auction directly with a **publishable** key. For merchants
+without a backend. Reliable only for low-stakes, instant, in-session digital
+delivery: a customer who never returns is never confirmed client-side.
+
+Live publishable keys require HTTPS origins. Test publishable keys
+(`pub_test_...`) may also allow loopback HTTP origins such as
+`http://127.0.0.1:5173` for local sandbox testing.
+
+```ts
+const client = createClient({
+  baseUrl: 'https://api.m2cmarkets.com',
+  publishableKey: 'pub_live_...',
+  // default statusSource is { kind: 'm2c' } - poll the M2C advisory read endpoint
+});
+
+await client.start({
+  transactionValue: 49.99, // major units, e.g. dollars
+  currency: 'USD',
+  description: 'Pro plan',
+  successUrl: 'https://shop.example/checkout/return',
+  cancelUrl: 'https://shop.example/checkout/canceled',
+});
+```
+
+## The redirect / resume model
+
+The default launch is a **same-tab full-page redirect** (`location.assign`), for
+maximum compatibility with vendor 3-D Secure / bank redirect flows that break
+inside popups and iframes.
+
+Because the redirect tears down the page, `start` / `startFromSession` **navigate
+away and do not resolve in place**. You get the outcome on your return page by
+calling `resume()`:
+
+```ts
+// On your success_url and cancel_url pages:
+const client = createClient({ baseUrl: 'https://api.m2cmarkets.com', publishableKey: 'pub_live_...' });
+
+const result = await client.resume({ outcome: 'success' }); // or 'cancel'
+// result is null if no checkout was in progress, otherwise one of:
+//   { status: 'completed',       requestId }
+//   { status: 'failed',          requestId }
+//   { status: 'canceled',        requestId }
+//   { status: 'pending_timeout', requestId }  <- poll window elapsed; ask your webhook
+```
+
+The SDK cannot tell `success_url` from `cancel_url` on its own, so pass
+`outcome`. A `cancel` return resolves `canceled` immediately; a `success` return
+polls the status source to a terminal result.
+
+`start*` writes a small resume record to `sessionStorage` (namespaced by
+`storageKey`, default `m2c.checkout`) before navigating. It is read and cleared
+on the return page, so a refresh does not re-poll a stale checkout.
+
+### Popup / new-tab launch
+
+For apps that must keep the original page alive, such as web games, opt into a
+separate checkout window:
+
+```ts
+const client = createClient({
+  baseUrl: 'https://api.m2cmarkets.com',
+  publishableKey: 'pub_live_...',
+  launchMode: 'popup', // or 'new_tab'
+  returnTimeoutMs: 60000, // optional fallback for abandoned popup/new-tab flows
+});
+```
+
+Call `start()` directly from a user click/tap. The SDK pre-opens a blank window
+before the auction request, clears `opener`, then navigates that window after
+the checkout URL is known. If the browser blocks the window, `start()` rejects
+with `InvalidRequest` before creating the auction.
+
+The default storage for popup/new-tab launch writes the resume record to
+`localStorage` as well as `sessionStorage`, so the return page in the checkout
+window can call `resume()`. If you inject custom `storage`, make sure it is
+visible to both the opener page and the return page. Use the same client
+factory on the opener and return page, or at least pass the same `launchMode`
+and storage configuration:
+
+```ts
+const client = createClient({
+  baseUrl: 'https://api.m2cmarkets.com',
+  publishableKey: 'pub_live_...',
+  launchMode: 'popup', // same value used before start()
+});
+
+// On your success_url / cancel_url page in the checkout window:
+await client.resume({ outcome: 'success' });
+```
+
+When the return page calls `resume()`, the SDK also broadcasts the terminal
+result back to the original same-origin page. In popup/new-tab mode, the
+`start()` / `startFromSession()` promise in the original page resolves with the
+same result.
+
+This handoff does not make `successUrl` authoritative. `completed` and `failed`
+still come from the configured status source, and fulfillment should still be
+driven server-side from webhook state.
+
+If the checkout window observably closes before a return page publishes a
+result, the original page resolves `start()` / `startFromSession()` with
+`{ status: 'window_closed', requestId }`. This is not a payment status and does
+not mean the purchase failed or was canceled. Some hosted checkout pages sever
+opener observability while the window is still alive; in that case the SDK keeps
+waiting for the return handoff, then treats opener focus as an abandonment
+signal if no return result appears.
+
+Set `returnTimeoutMs` if you want popup/new-tab mode to stop waiting after a
+fixed window when no return handoff arrives. This is an advisory UX fallback;
+choose a value long enough for a normal customer checkout, and keep server-side
+webhook state as the fulfillment source of truth.
+
+To reconcile an ambiguous outcome after the fact - a `window_closed` or
+`pending_timeout` that may have completed server-side - re-read the status for
+the `requestId` with `checkStatus`, a one-shot read against the configured
+status source:
+
+```ts
+const status = await client.checkStatus(requestId);
+// 'processing' | 'completed' | 'failed' | 'canceled'
+```
+
+`checkStatus` does not change the client's lifecycle state, and (like the poll)
+it is advisory - your webhook remains the source of truth.
+
+For example:
+
+```ts
+const result = await client.start({
+  transactionValue: 49.99,
+  successUrl: 'https://shop.example/checkout/return',
+  cancelUrl: 'https://shop.example/checkout/canceled',
+});
+```
+
+The checkout window still lands on your return page because that is where the
+vendor redirects the customer. The original page receives the result through a
+same-origin `BroadcastChannel` / `localStorage` handoff; the SDK does not rely
+on `window.opener`.
+
+## Progress events
+
+```ts
+const unsubscribe = client.onStateChange((state, ctx) => {
+  // state: idle | creating | ready | launching | awaiting_return | returned
+  //        | polling | completed | failed | canceled | pending_timeout
+  //        | window_closed | error
+  // ctx:   { requestId?, error? }   (error is set only on the 'error' state)
+  render(state);
+});
+```
+
+## Status sources
+
+Configure where status is read from after the return:
+
+- `{ kind: 'm2c' }` - poll the M2C advisory read endpoint with the publishable
+  key (client-initiated only). The default.
+- `{ kind: 'url', template }` - poll your endpoint; `{request_id}` is
+  substituted. Answer from your webhook-recorded state. Recommended for
+  backend-initiated mode.
+- `{ kind: 'callback', checkStatus }` - call your async function on the backoff
+  schedule. A function cannot survive a full-page redirect, so **re-supply it on
+  the return page** via `createClient({ statusSource })` or
+  `resume({ statusSource })`.
+
+Status readers may return the client statuses (`processing`, `completed`,
+`failed`, `canceled`) or webhook-native statuses from your own store (`pending`,
+`abandoned`, `refunded`, `chargedback`). The SDK maps them to the client result
+enum before resolving.
+
+The poll uses bounded exponential backoff (immediate, then 1s, 2s, 4s, 8s,
+capped at 8s, ~90s total window; override with `poll`). Correlation is always
+`request_id`, which you get from the auction response and your webhook records -
+no pre-coordination needed.
+
+> A push (`subscribe`) adapter is reserved in the type surface but not
+> implemented yet; use `m2c`, `url`, or `callback`.
+
+## Error handling
+
+Rejections are `M2CCheckoutError` with a typed `code`:
+
+| code | meaning |
+|---|---|
+| `InvalidRequest` | bad input / unsupported currency / bad URL (400, or client-side) |
+| `OriginNotAllowed` | the page origin is not on the key's allowlist (403) |
+| `AccountSuspended` | the merchant account is suspended (403) |
+| `NoVendorsAvailable` | no linked/eligible vendor produced a bid (404) |
+| `RateLimited` | slow down; see `retryAfterSeconds` (429) |
+| `ServiceUnavailable` | transient backend failure (5xx) |
+| `CheckoutExpired` | the TTL lapsed before launch (backend mode cannot re-mint) |
+| `Network` | no HTTP response (fetch failure) |
+
+`pending_timeout` is **not** an error - it resolves as a terminal result. During
+polling, transient read failures (rate limit, 5xx, network, a not-yet-visible
+status row) are swallowed and retried; a developer-actionable failure (bad
+origin, invalid request) rejects so you see it.
+
+## Framework recipes
+
+Vanilla:
+
+```ts
+button.onclick = () => client.start({ /* ... */ }).catch(showError);
+client.onStateChange((s) => (statusEl.textContent = s));
+```
+
+React (drive a state variable from the event; resume on the return route):
+
+```tsx
+useEffect(() => client.onStateChange(setState), []);
+const onBuy = () => client.start({ /* ... */ }).catch(setError);
+
+// On the return route:
+useEffect(() => {
+  client.resume({ outcome: 'success' }).then(setResult).catch(setError);
+}, []);
+```
+
+## Test mode
+
+Use test keys (`pub_test_...`) and forward a backend session created with a
+`sec_test_...` key. The auction runs against the in-server sandbox vendors and
+returns a synthetic M2C-hosted `checkout_url`; the status read is scoped to the
+test flag derived from the key. No special code path - the same flow drives the
+sandbox.
+
+## Server-side / non-browser usage
+
+All DOM access is guarded, so importing the module on a server never throws.
+`start` / `startFromSession` / `resume` throw `InvalidRequest` if no
+`sessionStorage` / navigation is available; inject `storage`, `navigate`, and
+`fetch` to drive the SDK in a non-browser environment (this is how the test
+suite runs).
+
+## What this SDK does not do
+
+- Capture card data or render the vendor's checkout page (M2C is a router; the
+  vendor owns PCI scope).
+- Decide fulfillment. Grant goods server-side off the M2C webhook. See the
+  fulfillment webhook receiver examples that ship alongside the SDKs.
+- Ship UI. Headless by design.
+
+## Packaging note
+
+This package currently publishes ESM only, matching the rest of the M2C SDK
+workspace and its plain-`tsc`, zero-dependency build. Every modern bundler and
+Node 18+ consume it directly; a CJS build can be added without an API change if
+a consumer needs it.

package/dist/auction.d.ts

@@ -0,0 +1,21 @@
+import type { NormalizedConfig, StartParams } from './types.js';
+export interface AuctionSession {
+    checkoutUrl: string;
+    requestId: string;
+    ttl?: number;
+}
+/**
+ * Build the auction request body from client-initiated params. The server
+ * decoder rejects unknown fields, so only the contract keys are emitted, and
+ * each is validated against the wire limits first. `country` / `customer_ip`
+ * are intentionally never sent: the server derives them from the observed
+ * connection for publishable callers.
+ */
+export declare function buildAuctionBody(params: StartParams, allowInsecureUrls: boolean): string;
+/**
+ * Run a client-initiated auction with the publishable key. The browser sets the
+ * `Origin` header (it is forbidden to set from script), which the server gates
+ * against the key's allowlist. Resolves the minimal publishable session
+ * ({ checkout_url, ttl, request_id }); rejects with a typed error otherwise.
+ */
+export declare function runAuction(config: NormalizedConfig, params: StartParams): Promise<AuctionSession>;

package/dist/auction.js

@@ -0,0 +1,136 @@
+import { M2CCheckoutError, auctionErrorForResponse, parseRetryAfter } from './errors.js';
+import { assertTransactionValue, validateCheckoutUrl, validateDescription, validateDeviceType, validateReference, validateReferrer, validateSegments, validateUrl, } from './validate.js';
+const AUCTION_PATH = '/api/v1/auction';
+/**
+ * Build the auction request body from client-initiated params. The server
+ * decoder rejects unknown fields, so only the contract keys are emitted, and
+ * each is validated against the wire limits first. `country` / `customer_ip`
+ * are intentionally never sent: the server derives them from the observed
+ * connection for publishable callers.
+ */
+export function buildAuctionBody(params, allowInsecureUrls) {
+    assertTransactionValue(params.transactionValue);
+    const wire = {
+        transaction_value: params.transactionValue,
+        success_url: validateUrl(params.successUrl, 'successUrl', allowInsecureUrls),
+        cancel_url: validateUrl(params.cancelUrl, 'cancelUrl', allowInsecureUrls),
+    };
+    if (params.currency !== undefined) {
+        if (typeof params.currency !== 'string' || params.currency === '') {
+            throw new M2CCheckoutError('InvalidRequest', 'currency must be a non-empty string');
+        }
+        // The server's allowlist (model.IsSupportedCurrency) is the authority; we
+        // only guard the shape and let an unsupported code return a clean 400.
+        wire.currency = params.currency;
+    }
+    const description = validateDescription(params.description);
+    if (description !== undefined)
+        wire.description = description;
+    const segments = validateSegments(params.segments);
+    if (segments !== undefined)
+        wire.segments = segments;
+    if (params.language !== undefined) {
+        if (typeof params.language !== 'string') {
+            throw new M2CCheckoutError('InvalidRequest', 'language must be a string');
+        }
+        wire.language = params.language;
+    }
+    const deviceType = validateDeviceType(params.deviceType);
+    if (deviceType !== undefined)
+        wire.device_type = deviceType;
+    const referrer = validateReferrer(params.referrer);
+    if (referrer !== undefined)
+        wire.referrer = referrer;
+    const reference = validateReference(params.reference);
+    if (reference !== undefined)
+        wire.reference = reference;
+    return JSON.stringify(wire);
+}
+/**
+ * Run a client-initiated auction with the publishable key. The browser sets the
+ * `Origin` header (it is forbidden to set from script), which the server gates
+ * against the key's allowlist. Resolves the minimal publishable session
+ * ({ checkout_url, ttl, request_id }); rejects with a typed error otherwise.
+ */
+export async function runAuction(config, params) {
+    if (!config.publishableKey) {
+        throw new M2CCheckoutError('InvalidRequest', 'publishableKey is required for client-initiated start()');
+    }
+    if (!config.fetch) {
+        throw new M2CCheckoutError('InvalidRequest', 'no fetch implementation available; pass config.fetch or run where global fetch exists');
+    }
+    const body = buildAuctionBody(params, config.allowInsecureUrls);
+    let res;
+    try {
+        res = await config.fetch(`${config.baseUrl}${AUCTION_PATH}`, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                'X-API-Key': config.publishableKey,
+            },
+            body,
+            // No ambient credentials: the publishable key in the header is the auth.
+            credentials: 'omit',
+            // M2C never redirects this route; a redirect would re-send the key to
+            // another host, so treat any redirect as a failure rather than follow it.
+            redirect: 'error',
+        });
+    }
+    catch (err) {
+        throw new M2CCheckoutError('Network', `auction request failed: ${err.message}`, {
+            cause: err,
+        });
+    }
+    const text = await res.text().catch(() => '');
+    if (res.status !== 200) {
+        throw auctionErrorForResponse(res.status, extractErrorMessage(text), parseRetryAfter(res.headers.get('retry-after')));
+    }
+    return parseAuctionResponse(text, config.allowInsecureUrls);
+}
+function parseAuctionResponse(text, allowInsecureUrls) {
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        throw new M2CCheckoutError('Unknown', 'auction response was not valid JSON');
+    }
+    if (typeof parsed !== 'object' || parsed === null) {
+        throw new M2CCheckoutError('Unknown', 'auction response had an unexpected shape');
+    }
+    const obj = parsed;
+    const winner = obj.winner;
+    const requestId = obj.request_id;
+    if (typeof requestId !== 'string' || requestId === '') {
+        throw new M2CCheckoutError('Unknown', 'auction response was missing request_id');
+    }
+    if (typeof winner !== 'object' || winner === null) {
+        throw new M2CCheckoutError('Unknown', 'auction response was missing winner');
+    }
+    const checkoutUrl = winner.checkout_url;
+    const ttl = winner.ttl;
+    if (typeof checkoutUrl !== 'string' || checkoutUrl === '') {
+        throw new M2CCheckoutError('Unknown', 'auction response was missing winner.checkout_url');
+    }
+    return {
+        checkoutUrl: validateCheckoutUrl(checkoutUrl, 'winner.checkout_url', allowInsecureUrls),
+        requestId,
+        ttl: typeof ttl === 'number' ? ttl : undefined,
+    };
+}
+function extractErrorMessage(text) {
+    if (!text)
+        return undefined;
+    try {
+        const parsed = JSON.parse(text);
+        if (typeof parsed === 'object' && parsed !== null) {
+            const err = parsed.error;
+            if (typeof err === 'string')
+                return err;
+        }
+    }
+    catch {
+        // Non-JSON error body; fall through to the raw text.
+    }
+    return text;
+}

package/dist/client.d.ts

@@ -0,0 +1,33 @@
+import type { PollDeps } from './poll.js';
+import type { CheckoutClient, CheckoutResult, CheckoutState, ClientConfig, ClientStatus, NormalizedConfig, ResumeParams, StartFromSessionParams, StartParams, StateChangeListener } from './types.js';
+/** Create a headless checkout client. Safe to import in SSR; lifecycle methods need a DOM. */
+export declare function createClient(config: ClientConfig): CheckoutClient;
+declare class CheckoutClientImpl implements CheckoutClient {
+    private readonly config;
+    private state;
+    private requestId;
+    private readonly listeners;
+    private readonly pollDeps;
+    constructor(config: NormalizedConfig, pollDeps?: PollDeps);
+    getState(): CheckoutState;
+    onStateChange(listener: StateChangeListener): () => void;
+    start(params: StartParams): Promise<CheckoutResult>;
+    startFromSession(params: StartFromSessionParams): Promise<CheckoutResult>;
+    resume(params?: ResumeParams): Promise<CheckoutResult | null>;
+    checkStatus(requestId: string): Promise<ClientStatus>;
+    private persistAndLaunch;
+    private prepareAsyncLaunchWindow;
+    private waitForReturnResult;
+    private publishReturnResult;
+    private launchCheckout;
+    private openBlankCheckoutWindow;
+    private closeLaunchWindow;
+    private setState;
+    private fail;
+    private requireIdle;
+    private requireStorage;
+    private requireLaunchEnvironment;
+    private requireLaunchableStatusSource;
+}
+declare function normalizeConfig(config: ClientConfig): NormalizedConfig;
+export { CheckoutClientImpl, normalizeConfig };