@vivoa/partner-sdk 0.1.0

package/dist/esm/adapters/fetch-transport.js

@@ -0,0 +1,30 @@
+import { VivoaNetworkError } from "../domain/errors.js";
+/** Default transport: the runtime's global `fetch` (Node ≥ 18, Deno, Bun, edge). */
+export class FetchTransport {
+    fetchImpl;
+    constructor(fetchImpl = globalThis.fetch) {
+        if (!fetchImpl)
+            throw new Error('FetchTransport: no global fetch available — pass one explicitly');
+        this.fetchImpl = fetchImpl;
+    }
+    async send(request) {
+        let res;
+        try {
+            res = await this.fetchImpl(request.url, {
+                method: request.method,
+                headers: request.headers,
+                body: request.body,
+                signal: AbortSignal.timeout(request.timeoutMs),
+            });
+        }
+        catch (err) {
+            const reason = err.name === 'TimeoutError' ? `timed out after ${request.timeoutMs} ms` : err.message;
+            throw new VivoaNetworkError(`${request.method} ${request.url}: ${reason}`, { cause: err });
+        }
+        const headers = {};
+        res.headers.forEach((value, key) => {
+            headers[key.toLowerCase()] = value;
+        });
+        return { status: res.status, headers, body: await res.text() };
+    }
+}

package/dist/esm/adapters/in-memory/fake-vivoa.d.ts

@@ -0,0 +1,93 @@
+import type { HttpRequest, HttpResponse, HttpTransport } from '../../ports/http-transport.port.ts';
+import type { CryptoProvider } from '../../ports/crypto.port.ts';
+import type { Clock } from '../../ports/clock.port.ts';
+import { type MerchantRuntimeStatus } from '../../domain/merchant.ts';
+import type { OperatorProfile, OperatorStatus } from '../../domain/operator.ts';
+/**
+ * How `POST /activate` behaves:
+ * - `live`: provisions synchronously and returns live (the platform's happy path).
+ * - `slow`: returns `creating`; stays creating for `pollsUntilLive` status reads.
+ * - `fail`: responds 500 and leaves the merchant `failed` (retry allowed).
+ * - `drop`: the connection drops (network error) but provisioning continues → live.
+ */
+export type FakeActivationMode = 'live' | 'slow' | 'fail' | 'drop';
+export interface FakeOperatorSeed {
+    apiKey: string;
+    apiSecret: string;
+    name?: string;
+    status?: OperatorStatus;
+    plan?: string;
+    maxStores?: number;
+    allowedRegions?: string[];
+    rateLimitPerMin?: number;
+}
+export interface FakeWebhookDispatch {
+    url: string;
+    headers: Record<string, string>;
+    body: string;
+}
+export interface FakeVivoaOptions {
+    operators?: FakeOperatorSeed[];
+    /**
+     * Handles already in use platform-wide — seed this to force the auto-assigned
+     * handle to fall back to its `-xxxx` suffixed form, the same way a real
+     * collision would. A partner never sends a handle (the platform always
+     * assigns one), so this can no longer produce a 409 on create.
+     */
+    takenHandles?: string[];
+    activation?: FakeActivationMode;
+    pollsUntilLive?: number;
+    failureReason?: string;
+    clock?: Clock;
+    crypto?: CryptoProvider;
+    /** Receives every signed webhook the fake "delivers". */
+    onWebhook?: (dispatch: FakeWebhookDispatch) => void;
+}
+/**
+ * In-memory Vivoa Partner API behind the `HttpTransport` port. It verifies the
+ * real HMAC signature and enforces the same rules as the platform
+ * (`engine/partner-api`): quota, allowed countries, unique handle, active-only
+ * writes, fleet scoping, activation state machine and per-minute rate limit.
+ * The shared contract suite (`test/contract`) runs against this fake AND the
+ * live API, so the two cannot silently drift.
+ */
+export declare class FakeVivoa implements HttpTransport {
+    readonly clock: Clock;
+    activation: FakeActivationMode;
+    pollsUntilLive: number;
+    failureReason: string;
+    private readonly crypto;
+    private readonly onWebhook?;
+    private readonly operators;
+    private readonly merchants;
+    private readonly handles;
+    constructor(options?: FakeVivoaOptions);
+    addOperator(seed: FakeOperatorSeed): OperatorProfile;
+    setOperatorStatus(apiKey: string, status: OperatorStatus): void;
+    /** Test helper: flip a merchant's runtime (e.g. simulate ops tearing it down). */
+    setRuntime(merchantId: string, runtime: MerchantRuntimeStatus): void;
+    send(req: HttpRequest): Promise<HttpResponse>;
+    private authenticate;
+    private rateLimit;
+    private requireActive;
+    private route;
+    private create;
+    /**
+     * Mirrors `StoreService.allocateHandle`: the readable slug of `name` first,
+     * a random `-xxxx` suffix if it (or a seeded `takenHandles` entry) is
+     * already used. The platform assigns this — a partner never sends one.
+     */
+    private allocateHandle;
+    private activate;
+    private goLive;
+    private statusView;
+    private list;
+    private analytics;
+    private webhookRoute;
+    private emit;
+    private deliver;
+    private fleet;
+    private owned;
+    private profile;
+    private requireOperatorByKey;
+}

package/dist/esm/adapters/in-memory/fake-vivoa.js

@@ -0,0 +1,464 @@
+import { randomUUID } from 'node:crypto';
+import { nodeCrypto } from "../node-crypto.js";
+import { systemClock } from "../system-clock.js";
+import { VivoaNetworkError } from "../../domain/errors.js";
+import { canonicalRequestPayload, MAX_CLOCK_SKEW_SECONDS, PARTNER_HEADERS, } from "../../domain/signature.js";
+import { MAX_EXTERNAL_ID_LENGTH } from "../../domain/merchant.js";
+import { MERCHANT_EVENT_TYPES } from "../../domain/webhook.js";
+class HttpError extends Error {
+    status;
+    constructor(status, message) {
+        super(message);
+        this.status = status;
+    }
+}
+/** `POST /merchants` body — matches CreateMerchantDto's whitelist exactly (a stale `handle` 400s, like on the real platform). */
+const CREATE_MERCHANT_KEYS = new Set(['email', 'name', 'countries', 'industry', 'externalId']);
+/** Mirrors `shared/utils/slugify.ts` on the platform closely enough for a fake. */
+function slugify(value) {
+    return value
+        .toLowerCase()
+        .normalize('NFD')
+        .replace(/[̀-ͯ]/g, '')
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/(^-|-$)/g, '')
+        .slice(0, 40);
+}
+const REASON = {
+    400: 'Bad Request',
+    401: 'Unauthorized',
+    403: 'Forbidden',
+    404: 'Not Found',
+    409: 'Conflict',
+    429: 'Too Many Requests',
+    500: 'Internal Server Error',
+};
+/**
+ * In-memory Vivoa Partner API behind the `HttpTransport` port. It verifies the
+ * real HMAC signature and enforces the same rules as the platform
+ * (`engine/partner-api`): quota, allowed countries, unique handle, active-only
+ * writes, fleet scoping, activation state machine and per-minute rate limit.
+ * The shared contract suite (`test/contract`) runs against this fake AND the
+ * live API, so the two cannot silently drift.
+ */
+export class FakeVivoa {
+    clock;
+    activation;
+    pollsUntilLive;
+    failureReason;
+    crypto;
+    onWebhook;
+    operators = new Map();
+    merchants = new Map();
+    handles = new Set();
+    constructor(options = {}) {
+        this.clock = options.clock ?? systemClock;
+        this.crypto = options.crypto ?? nodeCrypto;
+        this.activation = options.activation ?? 'live';
+        this.pollsUntilLive = options.pollsUntilLive ?? 2;
+        this.failureReason = options.failureReason ?? 'droplet pool exhausted';
+        this.onWebhook = options.onWebhook;
+        for (const handle of options.takenHandles ?? [])
+            this.handles.add(handle);
+        for (const seed of options.operators ?? [])
+            this.addOperator(seed);
+    }
+    addOperator(seed) {
+        const state = {
+            name: 'Fake Partner',
+            status: 'active',
+            plan: 'starter',
+            maxStores: 3,
+            allowedRegions: ['SV'],
+            rateLimitPerMin: 60,
+            ...seed,
+            id: `op_${randomUUID().slice(0, 8)}`,
+            window: { startMs: 0, count: 0 },
+            webhook: null,
+            deliveries: [],
+        };
+        this.operators.set(seed.apiKey, state);
+        return this.profile(state);
+    }
+    setOperatorStatus(apiKey, status) {
+        this.requireOperatorByKey(apiKey).status = status;
+    }
+    /** Test helper: flip a merchant's runtime (e.g. simulate ops tearing it down). */
+    setRuntime(merchantId, runtime) {
+        const m = this.merchants.get(merchantId);
+        if (m)
+            m.runtime = runtime;
+    }
+    async send(req) {
+        try {
+            const url = new URL(req.url);
+            const operator = await this.authenticate(req, url.pathname);
+            this.rateLimit(operator);
+            const result = await this.route(operator, req.method, url, req.body);
+            return json(200, result);
+        }
+        catch (err) {
+            if (err instanceof VivoaNetworkError)
+                throw err;
+            if (err instanceof HttpError) {
+                return json(err.status, { statusCode: err.status, message: err.message, error: REASON[err.status] });
+            }
+            return json(500, { statusCode: 500, message: err.message, error: REASON[500] });
+        }
+    }
+    // ── auth (mirrors core/partner/guards) ──────────────────────────────────
+    async authenticate(req, path) {
+        const h = lower(req.headers);
+        const key = h[PARTNER_HEADERS.key];
+        const timestamp = h[PARTNER_HEADERS.timestamp];
+        const signature = h[PARTNER_HEADERS.signature];
+        if (!key || !timestamp || !signature)
+            throw new HttpError(401, 'Missing partner auth headers');
+        const ts = Number(timestamp);
+        if (!Number.isFinite(ts))
+            throw new HttpError(401, 'Invalid timestamp');
+        if (Math.abs(Math.floor(this.clock.nowMs() / 1000) - ts) > MAX_CLOCK_SKEW_SECONDS) {
+            throw new HttpError(401, 'Timestamp skew too large');
+        }
+        const operator = this.operators.get(key);
+        if (!operator)
+            throw new HttpError(401, 'Unknown partner key');
+        const expected = await this.crypto.hmacSha256Hex(operator.apiSecret, canonicalRequestPayload({
+            timestamp,
+            method: req.method,
+            path,
+            bodySha256Hex: await this.crypto.sha256Hex(req.body ?? ''),
+        }));
+        if (!(await this.crypto.timingSafeEqualHex(expected, signature))) {
+            throw new HttpError(401, 'Invalid signature');
+        }
+        return operator;
+    }
+    rateLimit(operator) {
+        const now = this.clock.nowMs();
+        if (now - operator.window.startMs >= 60_000)
+            operator.window = { startMs: now, count: 0 };
+        operator.window.count += 1;
+        if (operator.window.count > operator.rateLimitPerMin) {
+            throw new HttpError(429, `Rate limit of ${operator.rateLimitPerMin} req/min exceeded`);
+        }
+    }
+    requireActive(operator) {
+        if (operator.status !== 'active') {
+            throw new HttpError(403, `Operator is ${operator.status} — write operations require an active account`);
+        }
+    }
+    // ── routing (mirrors partner-api.controller.ts) ─────────────────────────
+    async route(op, method, url, rawBody) {
+        const path = url.pathname.replace(/^\/partner\/v1/, '');
+        const body = rawBody ? JSON.parse(rawBody) : {};
+        const merchantRoute = path.match(/^\/merchants\/([^/]+)\/(status|activate|suspend|reactivate)$/);
+        if (method === 'GET' && path === '/me')
+            return this.profile(op);
+        if (method === 'POST' && path === '/me/rotate-secret') {
+            this.requireActive(op);
+            op.apiSecret = randomUUID().replace(/-/g, '') + randomUUID().replace(/-/g, '');
+            return { apiSecret: op.apiSecret };
+        }
+        if (method === 'GET' && path === '/merchants')
+            return this.list(op, url.searchParams);
+        if (method === 'POST' && path === '/merchants') {
+            this.requireActive(op);
+            return this.create(op, body);
+        }
+        if (merchantRoute) {
+            const [, id, action] = merchantRoute;
+            const merchant = this.owned(op, decodeURIComponent(id));
+            if (method === 'GET' && action === 'status')
+                return this.statusView(merchant, true);
+            if (method === 'POST') {
+                this.requireActive(op);
+                if (action === 'activate')
+                    return this.activate(op, merchant);
+                if (action === 'suspend') {
+                    merchant.status = 'suspended';
+                    if (merchant.runtime !== 'not_activated')
+                        merchant.runtime = 'suspended';
+                    this.emit(op, 'merchant.suspended', merchant);
+                    return { storeId: merchant.id, status: 'suspended' };
+                }
+                if (action === 'reactivate') {
+                    merchant.status = 'active';
+                    if (merchant.runtime === 'suspended')
+                        merchant.runtime = 'live';
+                    this.emit(op, 'merchant.reactivated', merchant);
+                    return { storeId: merchant.id, status: 'active' };
+                }
+            }
+        }
+        if (method === 'GET' && path === '/fleet/analytics')
+            return this.analytics(op);
+        if (path === '/webhooks' || path.startsWith('/webhooks/'))
+            return this.webhookRoute(op, method, path, body, url);
+        throw new HttpError(404, `Cannot ${method} ${url.pathname}`);
+    }
+    create(op, body) {
+        const unknownKey = Object.keys(body).find((k) => !CREATE_MERCHANT_KEYS.has(k));
+        if (unknownKey)
+            throw new HttpError(400, `property ${unknownKey} should not exist`);
+        const email = String(body.email ?? '');
+        const name = String(body.name ?? '');
+        const countries = Array.isArray(body.countries) ? body.countries.map(String) : [];
+        const externalId = body.externalId === undefined ? undefined : String(body.externalId);
+        const problems = [];
+        if (!/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email))
+            problems.push('email must be an email');
+        if (!name)
+            problems.push('name must be longer than or equal to 1 characters');
+        if (countries.length === 0)
+            problems.push('countries should not be empty');
+        if (externalId !== undefined && externalId.length > MAX_EXTERNAL_ID_LENGTH) {
+            problems.push(`externalId must be shorter than or equal to ${MAX_EXTERNAL_ID_LENGTH} characters`);
+        }
+        if (problems.length)
+            throw new HttpError(400, problems.join('; '));
+        // Idempotent replay BEFORE quota/region checks — mirrors the platform.
+        if (externalId) {
+            const existing = this.fleet(op).find((m) => m.externalId === externalId);
+            if (existing)
+                return publicMerchant(existing);
+        }
+        if (this.fleet(op).length >= op.maxStores) {
+            throw new HttpError(403, `Operator '${op.name}' has reached the store limit of ${op.maxStores} for plan '${op.plan}'`);
+        }
+        const forbidden = countries.filter((c) => !op.allowedRegions.includes(c));
+        if (forbidden.length) {
+            throw new HttpError(400, `Countries not allowed for this operator: ${forbidden.join(', ')}. Allowed: ${op.allowedRegions.join(', ')}`);
+        }
+        const merchant = {
+            id: randomUUID().replace(/-/g, '').slice(0, 24),
+            name,
+            handle: this.allocateHandle(name),
+            status: 'active',
+            runtime: 'not_activated',
+            countries,
+            plan: 'basic',
+            domain: null,
+            ownerEmail: email,
+            externalId: externalId ?? null,
+            createdAt: new Date(this.clock.nowMs()).toISOString(),
+            operatorId: op.id,
+            pollsLeft: 0,
+        };
+        this.handles.add(merchant.handle);
+        this.merchants.set(merchant.id, merchant);
+        this.emit(op, 'merchant.created', merchant, { externalId: merchant.externalId });
+        return publicMerchant(merchant);
+    }
+    /**
+     * Mirrors `StoreService.allocateHandle`: the readable slug of `name` first,
+     * a random `-xxxx` suffix if it (or a seeded `takenHandles` entry) is
+     * already used. The platform assigns this — a partner never sends one.
+     */
+    allocateHandle(name) {
+        const base = slugify(name) || 'tienda';
+        if (!this.handles.has(base))
+            return base;
+        for (let attempt = 0; attempt < 8; attempt++) {
+            const suffix = randomUUID().replace(/-/g, '').slice(0, 4);
+            const candidate = `${base.slice(0, 34)}-${suffix}`;
+            if (!this.handles.has(candidate))
+                return candidate;
+        }
+        throw new HttpError(500, `Could not allocate a free handle for "${name}"`);
+    }
+    activate(op, m) {
+        if (m.runtime === 'creating' || m.runtime === 'live' || m.runtime === 'suspended') {
+            throw new HttpError(409, m.runtime === 'suspended'
+                ? `Merchant '${m.handle}' is suspended — use reactivate instead`
+                : `Merchant '${m.handle}' is already ${m.runtime}`);
+        }
+        switch (this.activation) {
+            case 'fail':
+                m.runtime = 'failed';
+                this.emit(op, 'merchant.failed', m, { reason: this.failureReason });
+                throw new HttpError(500, this.failureReason);
+            case 'slow':
+                m.runtime = 'creating';
+                m.pollsLeft = this.pollsUntilLive;
+                return this.statusView(m, false);
+            case 'drop':
+                m.runtime = 'creating';
+                m.pollsLeft = this.pollsUntilLive;
+                throw new VivoaNetworkError('POST activate: socket hang up');
+            default:
+                this.goLive(m);
+                return this.statusView(m, false);
+        }
+    }
+    goLive(m) {
+        m.runtime = 'live';
+        m.domain = `${m.handle}.vivoa.store`;
+        const op = [...this.operators.values()].find((o) => o.id === m.operatorId);
+        if (op)
+            this.emit(op, 'merchant.live', m);
+    }
+    statusView(m, isPoll) {
+        if (isPoll && m.runtime === 'creating') {
+            if (m.pollsLeft <= 0)
+                this.goLive(m);
+            else
+                m.pollsLeft -= 1;
+        }
+        return {
+            storeId: m.id,
+            handle: m.handle,
+            status: m.status,
+            deployStatus: m.runtime,
+            domain: m.domain,
+            apiBaseUrl: m.runtime === 'live' ? 'https://shared-api.vivoa.app' : null,
+        };
+    }
+    list(op, qs) {
+        const page = Math.max(1, Number(qs.get('page')) || 1);
+        const limit = Math.min(Math.max(1, Number(qs.get('limit')) || 20), 100);
+        const search = qs.get('search')?.toLowerCase();
+        const externalId = qs.get('externalId') ?? undefined;
+        const rows = this.fleet(op)
+            .filter((m) => !search || m.name.toLowerCase().includes(search) || m.handle.includes(search))
+            .filter((m) => !externalId || m.externalId === externalId)
+            .sort((a, b) => b.createdAt.localeCompare(a.createdAt));
+        return {
+            data: rows.slice((page - 1) * limit, page * limit).map(publicMerchant),
+            meta: { total: rows.length, page, limit },
+        };
+    }
+    analytics(op) {
+        const fleet = this.fleet(op);
+        const byStatus = {};
+        for (const m of fleet)
+            byStatus[m.status] = (byStatus[m.status] ?? 0) + 1;
+        return {
+            operatorId: op.id,
+            stores: { total: fleet.length, active: byStatus.active ?? 0, suspended: byStatus.suspended ?? 0, byStatus },
+            revenue: { grossVolume: 0, currency: 'USD', pendingAmount: 0, completedPayments: 0, avgTicket: 0 },
+        };
+    }
+    async webhookRoute(op, method, path, body, url) {
+        if (method === 'GET' && path === '/webhooks')
+            return webhookView(op);
+        if (method === 'GET' && path === '/webhooks/deliveries') {
+            const limit = Math.min(Number(url.searchParams.get('limit')) || 25, 100);
+            return op.deliveries.slice(0, limit);
+        }
+        this.requireActive(op);
+        if (method === 'PUT' && path === '/webhooks') {
+            const target = String(body.url ?? '');
+            if (!/^https?:\/\//.test(target))
+                throw new HttpError(400, 'url must be a URL address');
+            const events = Array.isArray(body.events) ? body.events.map(String) : [];
+            const unknown = events.filter((e) => !MERCHANT_EVENT_TYPES.includes(e));
+            if (unknown.length)
+                throw new HttpError(400, `each value in events must be one of the following values: ${MERCHANT_EVENT_TYPES.join(', ')}`);
+            const isNew = !op.webhook;
+            const secret = op.webhook?.secret ?? `whsec_${randomUUID().replace(/-/g, '')}`;
+            op.webhook = { url: target, events, secret, updatedAt: new Date(this.clock.nowMs()).toISOString() };
+            return { webhook: webhookView(op), signingSecret: isNew ? secret : null };
+        }
+        if (method === 'DELETE' && path === '/webhooks') {
+            op.webhook = null;
+            return webhookView(op);
+        }
+        if (!op.webhook)
+            throw new HttpError(404, 'No webhook configured for this operator');
+        if (method === 'POST' && path === '/webhooks/rotate-secret') {
+            op.webhook.secret = `whsec_${randomUUID().replace(/-/g, '')}`;
+            return { signingSecret: op.webhook.secret };
+        }
+        if (method === 'POST' && path === '/webhooks/test') {
+            return this.deliver(op, 'platform.test', { message: 'Test event from Vivoa', operatorId: op.id });
+        }
+        throw new HttpError(404, `Cannot ${method} /partner/v1${path}`);
+    }
+    // ── events → signed webhook ─────────────────────────────────────────────
+    emit(op, event, m, extra = {}) {
+        if (!op.webhook)
+            return;
+        if (op.webhook.events.length > 0 && !op.webhook.events.includes(event))
+            return;
+        void this.deliver(op, event, {
+            merchantId: m.id,
+            handle: m.handle,
+            operatorId: op.id,
+            occurredAt: new Date(this.clock.nowMs()).toISOString(),
+            ...extra,
+        });
+    }
+    async deliver(op, event, data) {
+        const hook = op.webhook;
+        const body = JSON.stringify({ event, data, sentAt: new Date(this.clock.nowMs()).toISOString() });
+        const signature = await this.crypto.hmacSha256Hex(hook.secret, body);
+        this.onWebhook?.({
+            url: hook.url,
+            headers: { 'content-type': 'application/json', 'x-vivoa-event': event, 'x-vivoa-signature': `sha256=${signature}` },
+            body,
+        });
+        const delivery = {
+            id: randomUUID(),
+            event,
+            statusCode: 200,
+            success: true,
+            error: null,
+            durationMs: 1,
+            attempt: 1,
+            createdAt: new Date(this.clock.nowMs()).toISOString(),
+        };
+        op.deliveries.unshift(delivery);
+        return delivery;
+    }
+    // ── helpers ─────────────────────────────────────────────────────────────
+    fleet(op) {
+        return [...this.merchants.values()].filter((m) => m.operatorId === op.id);
+    }
+    owned(op, id) {
+        const m = this.merchants.get(id);
+        if (!m || m.operatorId !== op.id)
+            throw new HttpError(404, `Merchant store '${id}' not found for this operator`);
+        return m;
+    }
+    profile(op) {
+        return {
+            id: op.id,
+            name: op.name,
+            status: op.status,
+            plan: op.plan,
+            storesUsed: this.fleet(op).length,
+            maxStores: op.maxStores,
+            allowedRegions: [...op.allowedRegions],
+            rateLimitPerMin: op.rateLimitPerMin,
+        };
+    }
+    requireOperatorByKey(apiKey) {
+        const op = this.operators.get(apiKey);
+        if (!op)
+            throw new Error(`FakeVivoa: unknown operator key ${apiKey}`);
+        return op;
+    }
+}
+function publicMerchant(m) {
+    const { operatorId: _op, pollsLeft: _polls, ...view } = m;
+    return { ...view, countries: [...view.countries] };
+}
+function webhookView(op) {
+    return {
+        configured: !!op.webhook,
+        url: op.webhook?.url ?? null,
+        events: op.webhook ? [...op.webhook.events] : [],
+        active: !!op.webhook,
+        updatedAt: op.webhook?.updatedAt ?? null,
+    };
+}
+function json(status, body) {
+    return { status, headers: { 'content-type': 'application/json' }, body: JSON.stringify(body) };
+}
+function lower(headers) {
+    const out = {};
+    for (const [k, v] of Object.entries(headers))
+        out[k.toLowerCase()] = v;
+    return out;
+}

package/dist/esm/adapters/manual-clock.d.ts

@@ -0,0 +1,9 @@
+import type { Clock } from '../ports/clock.port.ts';
+/** Deterministic clock: `sleep` advances time instantly. For tests and the fake. */
+export declare class ManualClock implements Clock {
+    private current;
+    constructor(startMs?: number);
+    nowMs(): number;
+    sleep(ms: number): Promise<void>;
+    advance(ms: number): void;
+}

package/dist/esm/adapters/manual-clock.js

@@ -0,0 +1,16 @@
+/** Deterministic clock: `sleep` advances time instantly. For tests and the fake. */
+export class ManualClock {
+    current;
+    constructor(startMs = Date.UTC(2026, 0, 1)) {
+        this.current = startMs;
+    }
+    nowMs() {
+        return this.current;
+    }
+    async sleep(ms) {
+        this.current += ms;
+    }
+    advance(ms) {
+        this.current += ms;
+    }
+}

package/dist/esm/adapters/node-crypto.d.ts

@@ -0,0 +1,2 @@
+import type { CryptoProvider } from '../ports/crypto.port.ts';
+export declare const nodeCrypto: CryptoProvider;

package/dist/esm/adapters/node-crypto.js

@@ -0,0 +1,10 @@
+import { createHash, createHmac, timingSafeEqual } from 'node:crypto';
+export const nodeCrypto = {
+    sha256Hex: (data) => createHash('sha256').update(data).digest('hex'),
+    hmacSha256Hex: (secret, data) => createHmac('sha256', secret).update(data).digest('hex'),
+    timingSafeEqualHex: (a, b) => {
+        const x = Buffer.from(a, 'hex');
+        const y = Buffer.from(b, 'hex');
+        return x.length > 0 && x.length === y.length && timingSafeEqual(x, y);
+    },
+};

package/dist/esm/adapters/system-clock.d.ts

@@ -0,0 +1,2 @@
+import type { Clock } from '../ports/clock.port.ts';
+export declare const systemClock: Clock;

package/dist/esm/adapters/system-clock.js

@@ -0,0 +1,4 @@
+export const systemClock = {
+    nowMs: () => Date.now(),
+    sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+};