@porulle/plugin-channel-connector 0.9.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 unified-commerce-engine contributors
+
+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/dist/hooks.d.ts

@@ -0,0 +1,3 @@
+import type { PluginHookRegistration } from "@porulle/core";
+import { type ChannelConnectorPluginOptions } from "./service.js";
+export declare function buildHooks(options: ChannelConnectorPluginOptions): PluginHookRegistration[];

package/dist/hooks.js

@@ -0,0 +1,24 @@
+import { resolveOrgId } from "@porulle/core";
+import { and, eq, inArray } from "@porulle/core/drizzle";
+import { sellableEntities } from "@porulle/core/schema";
+import { ChannelConnectorService, } from "./service.js";
+export function buildHooks(options) {
+    return [{
+            key: "checkout.beforePayment",
+            async handler(args) {
+                const { data, context } = args;
+                const service = new ChannelConnectorService(context.db, context.services, options);
+                await service.validateLineStock(resolveOrgId(context.actor), data.lineItems, options.inventoryTimeoutMs);
+                return data;
+            },
+        }, {
+            key: "orders.afterCreate",
+            async handler(args) {
+                const { result, context } = args;
+                const orgId = resolveOrgId(context.actor);
+                const entities = await context.db.select({ id: sellableEntities.id, sourceStoreId: sellableEntities.sourceStoreId }).from(sellableEntities).where(and(eq(sellableEntities.organizationId, orgId), inArray(sellableEntities.id, (result.lineItems ?? []).map((line) => line.entityId))));
+                const stores = new Set(entities.map((entity) => entity.sourceStoreId).filter((storeId) => storeId !== null));
+                await Promise.all([...stores].map((storeId) => context.jobs.enqueue("channel/push-order", { orgId, storeId, orderId: result.id }, { organizationId: orgId, concurrencyKey: `push:${result.id}:${storeId}`, supersedes: true })));
+            },
+        }];
+}

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+import { type ChannelConnectorPluginOptions } from "./service.js";
+export { mockChannelConnector } from "./mock-connector.js";
+export type { MockChannelConnectorOptions } from "./mock-connector.js";
+export { ChannelConnectorService, canExportTransition, } from "./service.js";
+export { signState, verifyState } from "./oauth-state.js";
+export type { ChannelComplianceData, ChannelConnectorPluginOptions, ChannelStockLine, ExportState, PublicConnectedStore, ReconcileReport, } from "./service.js";
+export type { OAuthStatePayload, OAuthStateResult } from "./oauth-state.js";
+export type { ChannelEntityMapEntry, ChannelExportEvent, ChannelOrderExport, ChannelRefundEvent, ChannelRefundRequest, ConnectedStore, } from "./schema.js";
+export declare function channelConnectorPlugin(options?: ChannelConnectorPluginOptions): import("@porulle/core").CommercePlugin;

package/dist/index.js

@@ -0,0 +1,375 @@
+import { createHash } from "node:crypto";
+import { CommerceConflictError, CommerceInvalidTransitionError, CommerceNotFoundError, CommerceValidationError, defineCommercePlugin, router, createSystemActor, } from "@porulle/core";
+import { z } from "@hono/zod-openapi";
+import { and, eq } from "@porulle/core/drizzle";
+import { processedWebhookEvents } from "@porulle/core/schema";
+import { channelEntityMap, channelExportEvents, channelOrderExports, channelRefundEvents, channelRefundRequests, connectedStores, } from "./schema.js";
+import { ChannelConnectorService, } from "./service.js";
+import { buildHooks } from "./hooks.js";
+import { oauthStateEventId, signState, verifyState } from "./oauth-state.js";
+export { mockChannelConnector } from "./mock-connector.js";
+export { ChannelConnectorService, canExportTransition, } from "./service.js";
+export { signState, verifyState } from "./oauth-state.js";
+function unwrap(result) {
+    if (result.ok)
+        return result.value;
+    switch (result.code) {
+        case "NOT_FOUND":
+            throw new CommerceNotFoundError(result.error);
+        case "INVALID_TRANSITION":
+            throw new CommerceInvalidTransitionError(result.error);
+        case "CONFLICT":
+            throw new CommerceConflictError(result.error);
+        default:
+            throw new CommerceValidationError(result.error);
+    }
+}
+function oauthError(status, code, message) {
+    return new Response(JSON.stringify({ error: { code, message } }), {
+        status,
+        headers: { "content-type": "application/json" },
+    });
+}
+function oauthRedirect(location) {
+    return new Response(null, { status: 302, headers: { location } });
+}
+function callbackUri(raw, redirect, provider) {
+    const request = raw.req.raw;
+    const requestUrl = new URL(request.url);
+    let origin = requestUrl.origin;
+    try {
+        const configured = new URL(redirect);
+        if (configured.protocol === "http:" || configured.protocol === "https:")
+            origin = configured.origin;
+    }
+    catch {
+        origin = requestUrl.origin;
+    }
+    return new URL(`/api/channels/oauth/${provider}/callback`, origin).toString();
+}
+export function channelConnectorPlugin(options = {}) {
+    const jobs = [
+        {
+            slug: "channel/reconcile",
+            concurrency: { key: (input) => String(input.storeId), supersedes: true },
+            handler: async ({ input, ctx }) => {
+                const service = new ChannelConnectorService(ctx.db, ctx.services, options);
+                const orgId = String(input.orgId);
+                const result = await service.reconcile(orgId, String(input.storeId), createSystemActor(orgId));
+                if (!result.ok)
+                    throw new Error(result.error);
+                if (result.value.driftAlert)
+                    ctx.logger.warn("Channel reconciliation detected significant drift.", result.value);
+                return { output: result.value };
+            },
+        },
+        {
+            slug: "channel/reconcile-sweep",
+            handler: async ({ input, ctx }) => {
+                const orgId = String(input.orgId);
+                const jobs = ctx.services.jobs;
+                const stores = await ctx.db.select().from(connectedStores).where(and(eq(connectedStores.organizationId, orgId), eq(connectedStores.status, "connected")));
+                const window = options.reconcileJitterWindowMs ?? 60 * 60 * 1000;
+                for (const store of stores) {
+                    const offset = createHash("sha256").update(store.id).digest().readUInt32BE(0) % window;
+                    await jobs.enqueue("channel/reconcile", { orgId, storeId: store.id }, {
+                        organizationId: orgId,
+                        concurrencyKey: store.id,
+                        supersedes: true,
+                        delayMs: offset,
+                    });
+                }
+                return { output: { enqueued: stores.length } };
+            },
+        },
+        {
+            slug: "channel/import-catalog",
+            concurrency: { key: (input) => String(input.storeId), supersedes: true },
+            handler: async ({ input, ctx }) => {
+                const service = new ChannelConnectorService(ctx.db, ctx.services, options);
+                const result = await service.importCatalog(String(input.orgId), String(input.storeId), createSystemActor(String(input.orgId)));
+                if (!result.ok)
+                    throw new Error(result.error);
+                return { output: { imported: result.value.imported, cursor: result.value.cursor } };
+            },
+        },
+        {
+            slug: "channel/sync-inventory",
+            concurrency: { key: (input) => String(input.storeId) },
+            handler: async ({ input, ctx }) => {
+                const service = new ChannelConnectorService(ctx.db, ctx.services, options);
+                const result = await service.syncInventory(String(input.orgId), String(input.storeId), createSystemActor(String(input.orgId)));
+                if (!result.ok)
+                    throw new Error(result.error);
+                return { output: { synced: result.value.synced } };
+            },
+        },
+        {
+            slug: "channel/push-order",
+            concurrency: { key: (input) => `push:${String(input.orderId)}:${String(input.storeId)}`, supersedes: true },
+            handler: async ({ input, ctx }) => {
+                const service = new ChannelConnectorService(ctx.db, ctx.services, options);
+                const orgId = String(input.orgId);
+                const storeId = String(input.storeId);
+                const orderId = String(input.orderId);
+                const existing = await service.createExport(orgId, storeId, orderId);
+                if (!existing.ok)
+                    throw new Error(existing.error);
+                const slice = await service.buildOrderSlice(orgId, storeId, orderId);
+                if (!slice.ok) {
+                    if (existing.value.state === "pending")
+                        await service.transitionExport(orgId, existing.value.id, "exported", "system", "Export attempt started.");
+                    await service.transitionExport(orgId, existing.value.id, "failed", "system", slice.error);
+                    return { output: { state: "failed" } };
+                }
+                const result = await service.exportOrder(orgId, storeId, slice.value, createSystemActor(orgId));
+                if (!result.ok)
+                    throw new Error(result.error);
+                return { output: { exportId: result.value.id, state: result.value.state } };
+            },
+        },
+        {
+            slug: "channel/reap-exports",
+            handler: async ({ input, ctx }) => {
+                const service = new ChannelConnectorService(ctx.db, ctx.services, options);
+                const result = await service.reapExports({
+                    definitiveMs: typeof input.definitiveMs === "number" ? input.definitiveMs : options.exportSla?.definitiveMs ?? 4 * 60 * 60 * 1000,
+                    transientMs: typeof input.transientMs === "number" ? input.transientMs : options.exportSla?.transientMs ?? 24 * 60 * 60 * 1000,
+                });
+                return { output: result };
+            },
+        },
+    ];
+    return defineCommercePlugin({
+        id: "channel-connector",
+        version: "1.0.0",
+        permissions: [
+            { scope: "channels:read", description: "Read connected stores and channel export status." },
+            { scope: "channels:manage", description: "Connect stores and retry channel order exports." },
+        ],
+        schema: () => ({
+            connectedStores,
+            channelEntityMap,
+            channelOrderExports,
+            channelExportEvents,
+            channelRefundRequests,
+            channelRefundEvents,
+        }),
+        hooks: () => buildHooks(options),
+        jobs: () => jobs,
+        routes: (ctx) => {
+            const db = ctx.database.db;
+            if (!db)
+                return [];
+            const service = new ChannelConnectorService(db, ctx.services, options, ctx.database.transaction);
+            const channels = router("Channels", "/channels", ctx);
+            channels.get("/oauth/{provider}/start")
+                .summary("Start channel OAuth onboarding")
+                .permission("channels:manage")
+                .params(z.object({ provider: z.string().min(1) }))
+                .query(z.object({ shop: z.string().min(1).optional(), store: z.string().min(1).optional() }))
+                .handler(async ({ params, query, orgId, raw }) => {
+                const oauth = options.oauth;
+                if (!oauth?.stateSecret || !oauth.postConnectRedirect)
+                    return oauthError(501, "OAUTH_NOT_CONFIGURED", "Channel OAuth is not configured.");
+                const provider = params.provider;
+                const connector = service.getConnector(provider);
+                if (!connector)
+                    return oauthError(404, "CONNECTOR_NOT_FOUND", `No connector registered for provider "${provider}".`);
+                if (!connector.buildAuthUrl)
+                    return oauthError(501, "OAUTH_UNSUPPORTED", `Connector "${provider}" does not support OAuth onboarding.`);
+                const storeDomain = String(query.shop ?? query.store ?? "");
+                if (!storeDomain)
+                    return oauthError(400, "STORE_DOMAIN_REQUIRED", "The shop or store query parameter is required.");
+                const state = signState({
+                    provider,
+                    orgId,
+                    shopDomain: storeDomain,
+                    exp: Math.floor(Date.now() / 1000) + 300,
+                    jti: crypto.randomUUID(),
+                }, oauth.stateSecret);
+                const redirect = callbackUri(raw, oauth.postConnectRedirect, provider);
+                const authUrl = connector.buildAuthUrl({
+                    storeDomain,
+                    state,
+                    redirectUri: redirect,
+                    callbackUri: redirect,
+                    scopes: [],
+                });
+                if (!authUrl.ok)
+                    return oauthError(422, authUrl.error.code, authUrl.error.message);
+                return oauthRedirect(authUrl.value);
+            });
+            const handleOAuthCallback = async ({ params, raw }) => {
+                const oauth = options.oauth;
+                if (!oauth?.stateSecret || !oauth.postConnectRedirect)
+                    return oauthError(501, "OAUTH_NOT_CONFIGURED", "Channel OAuth is not configured.");
+                const provider = params.provider;
+                const connector = service.getConnector(provider);
+                if (!connector)
+                    return oauthError(404, "CONNECTOR_NOT_FOUND", `No connector registered for provider "${provider}".`);
+                if (!connector.completeAuth)
+                    return oauthError(501, "OAUTH_UNSUPPORTED", `Connector "${provider}" does not support OAuth onboarding.`);
+                const request = raw.req.raw;
+                const requestUrl = new URL(request.url);
+                const state = requestUrl.searchParams.get("state");
+                if (!state)
+                    return oauthError(403, "INVALID_OAUTH_STATE", "OAuth state is missing.");
+                const landing = provider === "woocommerce" && request.method === "GET" && requestUrl.searchParams.get("return") === "1";
+                const verified = verifyState(state, oauth.stateSecret, Math.floor(Date.now() / 1000), !landing);
+                if (!verified.ok || verified.value.provider !== provider)
+                    return oauthError(403, "INVALID_OAUTH_STATE", "OAuth state is invalid or expired.");
+                if (landing)
+                    return oauthRedirect(oauth.postConnectRedirect);
+                const [consumed] = await db.insert(processedWebhookEvents).values({
+                    eventId: oauthStateEventId(verified.value.jti),
+                    provider: `oauth:${provider}`,
+                    eventType: "oauth_state",
+                }).onConflictDoNothing().returning({ id: processedWebhookEvents.id });
+                if (!consumed)
+                    return oauthError(403, "OAUTH_STATE_REPLAYED", "OAuth state has already been used.");
+                const completed = await connector.completeAuth(request, { storeDomain: verified.value.shopDomain });
+                if (!completed.ok)
+                    return oauthError(400, completed.error.code, completed.error.message);
+                if (completed.value.storeDomain !== verified.value.shopDomain)
+                    return oauthError(400, "OAUTH_STORE_MISMATCH", "OAuth callback store does not match the signed state.");
+                const connected = await service.connectStore(verified.value.orgId, {
+                    provider,
+                    storeDomain: verified.value.shopDomain,
+                    credentials: completed.value.credentials,
+                });
+                if (!connected.ok)
+                    return oauthError(422, connected.code ?? "STORE_CONNECTION_FAILED", connected.error);
+                return oauthRedirect(oauth.postConnectRedirect);
+            };
+            channels.get("/oauth/{provider}/callback")
+                .summary("Complete channel OAuth onboarding")
+                .params(z.object({ provider: z.string().min(1) }))
+                .handler(handleOAuthCallback);
+            channels.post("/oauth/{provider}/callback")
+                .summary("Receive channel OAuth credentials")
+                .params(z.object({ provider: z.string().min(1) }))
+                .handler(handleOAuthCallback);
+            channels.post("/webhooks/{storeId}")
+                .summary("Receive a channel webhook")
+                .handler(async ({ params, raw }) => {
+                const context = raw;
+                const storeId = params.storeId;
+                const [store] = await db.select().from(connectedStores).where(eq(connectedStores.id, storeId));
+                if (!store || !store.webhookSecret)
+                    return context.json({ error: { code: "UNAUTHORIZED", message: "Webhook store is not available." } }, 401);
+                const connector = service.getConnector(store.provider);
+                if (!connector)
+                    return context.json({ error: { code: "UNAUTHORIZED", message: "Webhook provider is not configured." } }, 401);
+                const verified = await connector.verifyWebhook(store, context.req.raw);
+                if (!verified.ok)
+                    return context.json({ error: { code: "UNAUTHORIZED", message: "Invalid webhook signature." } }, 401);
+                const [inserted] = await db.insert(processedWebhookEvents).values({ eventId: verified.value.id, provider: store.provider, eventType: verified.value.type }).onConflictDoNothing().returning({ id: processedWebhookEvents.id });
+                if (!inserted)
+                    return context.json({ data: { received: true, duplicate: true } });
+                const handled = await service.handleWebhook(store.organizationId, store.id, verified.value);
+                if (!handled.ok)
+                    return context.json({ error: { code: "WEBHOOK_PROCESSING_FAILED", message: handled.error } }, 422);
+                return context.json({ data: {
+                        received: true,
+                        ...(handled.value.data ? { data: handled.value.data } : {}),
+                        ...(handled.value.redacted !== undefined ? { redacted: handled.value.redacted } : {}),
+                    } });
+            });
+            channels.post("/compliance/{provider}")
+                .summary("Receive a compliance webhook")
+                .params(z.object({ provider: z.string().min(1) }))
+                .handler(async ({ params, raw }) => {
+                const context = raw;
+                const provider = params.provider;
+                const connector = service.getConnector(provider);
+                if (!connector)
+                    return context.json({ error: { code: "NOT_FOUND", message: `No connector registered for provider "${provider}".` } }, 404);
+                if (!connector.verifyAppWebhook)
+                    return context.json({ error: { code: "NOT_IMPLEMENTED", message: `Compliance webhook is not supported for provider "${provider}".` } }, 501);
+                const verified = await connector.verifyAppWebhook(context.req.raw);
+                if (!verified.ok)
+                    return context.json({ error: { code: "UNAUTHORIZED", message: verified.error.message } }, 401);
+                const request = context.req.raw;
+                const eventId = request.headers.get("x-shopify-event-id") ?? createHash("sha256").update(`${verified.value.topic}:${verified.value.shopDomain}:${JSON.stringify(verified.value.data)}`).digest("hex");
+                const [inserted] = await db.insert(processedWebhookEvents).values({ eventId, provider, eventType: verified.value.topic }).onConflictDoNothing().returning({ id: processedWebhookEvents.id });
+                if (!inserted)
+                    return context.json({ data: { received: true, duplicate: true } });
+                const stores = await service.getStoresByDomain(verified.value.shopDomain);
+                if (stores.length === 0)
+                    return context.json({ data: { received: true } });
+                let redacted = 0;
+                let redactedSeen = false;
+                let complianceData;
+                for (const store of stores) {
+                    const handled = await service.handleWebhook(store.organizationId, store.id, { id: eventId, type: verified.value.topic, data: verified.value.data });
+                    if (!handled.ok)
+                        return context.json({ error: { code: "WEBHOOK_PROCESSING_FAILED", message: handled.error } }, 422);
+                    if (handled.value.redacted !== undefined) {
+                        redacted += handled.value.redacted;
+                        redactedSeen = true;
+                    }
+                    if (handled.value.data) {
+                        complianceData = complianceData
+                            ? { customer: complianceData.customer, exports: [...complianceData.exports, ...handled.value.data.exports] }
+                            : handled.value.data;
+                    }
+                }
+                return context.json({ data: {
+                        received: true,
+                        ...(complianceData ? { data: complianceData } : {}),
+                        ...(redactedSeen ? { redacted } : {}),
+                    } });
+            });
+            channels.post("/stores")
+                .summary("Connect a channel store")
+                .permission("channels:manage")
+                .input(z.object({
+                provider: z.string().min(1),
+                credentials: z.record(z.string(), z.unknown()),
+                storeDomain: z.string().min(1),
+                webhookSecret: z.string().min(1).optional(),
+            }))
+                .handler(async ({ input, orgId }) => {
+                return unwrap(await service.connectStore(orgId, input));
+            });
+            channels.get("/stores")
+                .summary("List connected channel stores")
+                .permission("channels:read")
+                .handler(async ({ orgId }) => unwrap(await service.listStores(orgId)));
+            channels.get("/stores/{id}")
+                .summary("Get a connected channel store")
+                .permission("channels:read")
+                .handler(async ({ params, orgId }) => unwrap(await service.getStore(orgId, params.id)));
+            channels.get("/stores/{storeId}/reconcile-status")
+                .summary("Get channel reconciliation status")
+                .permission("channels:read")
+                .handler(async ({ params, orgId }) => unwrap(await service.getReconcileStatus(orgId, params.storeId)));
+            channels.post("/stores/{id}/disconnect")
+                .summary("Disconnect a channel store")
+                .permission("channels:manage")
+                .handler(async ({ params, orgId }) => unwrap(await service.disconnectStore(orgId, params.id)));
+            channels.get("/exports/failed")
+                .summary("List failed channel order exports")
+                .permission("channels:read")
+                .handler(async ({ orgId }) => unwrap(await service.listFailedExports(orgId)));
+            channels.get("/refund-requests")
+                .summary("List pending channel refund requests")
+                .permission("channels:manage")
+                .handler(async ({ orgId }) => unwrap(await service.listRefundRequests(orgId)));
+            channels.post("/refund-requests/{id}/approve")
+                .summary("Approve a channel refund request")
+                .permission("channels:manage")
+                .handler(async ({ params, orgId, actor }) => unwrap(await service.approveRefund(orgId, params.id, actor)));
+            channels.post("/refund-requests/{id}/reject")
+                .summary("Reject a channel refund request")
+                .permission("channels:manage")
+                .handler(async ({ params, orgId, actor }) => unwrap(await service.rejectRefund(orgId, params.id, actor)));
+            channels.post("/exports/{id}/retry")
+                .summary("Retry a failed channel order export")
+                .permission("channels:manage")
+                .handler(async ({ params, orgId, actor }) => unwrap(await service.retryExport(orgId, params.id, actor.userId)));
+            return channels.routes();
+        },
+    });
+}

package/dist/mock-connector.d.ts

@@ -0,0 +1,58 @@
+import { CommerceValidationError } from "@porulle/core";
+import type { ChannelCatalogItem, ChannelInventoryLevel, ChannelOrderSlice } from "@porulle/core";
+export interface MockChannelConnectorOptions {
+    catalog?: ChannelCatalogItem[];
+    inventory?: ChannelInventoryLevel[];
+    inventoryError?: Error;
+    throwOnInventory?: boolean;
+    inventoryDelayMs?: number;
+    onFetchInventory?: (ids: string[]) => void;
+}
+export declare function mockChannelConnector(options?: MockChannelConnectorOptions): {
+    providerId: string;
+    capabilities: {
+        importCatalog: true;
+        importInventory: true;
+        pushOrder: true;
+        receiveWebhooks: true;
+    };
+    importCatalog(): Promise<import("@porulle/core").Result<{
+        items: ChannelCatalogItem[];
+        nextCursor: null;
+    }, never>>;
+    fetchInventory(_store: import("@porulle/core").ChannelStore, ids: string[] | undefined): Promise<{
+        ok: true;
+        value: ChannelInventoryLevel[];
+        meta?: Record<string, unknown>;
+    } | {
+        ok: false;
+        error: CommerceValidationError;
+    }>;
+    pushOrder(_store: import("@porulle/core").ChannelStore, slice: ChannelOrderSlice): Promise<import("@porulle/core").Result<{
+        remoteOrderId: string;
+        remoteUrl: string;
+    }, never>>;
+    fetchOrderStatus(_store: import("@porulle/core").ChannelStore, remoteId: string): Promise<{
+        ok: false;
+        error: CommerceValidationError;
+    } | {
+        ok: true;
+        value: {
+            status: "confirmed";
+        };
+        meta?: Record<string, unknown>;
+    }>;
+    verifyWebhook(store: import("@porulle/core").ChannelStore, request: Request): Promise<{
+        ok: false;
+        error: CommerceValidationError;
+    } | {
+        ok: true;
+        value: {
+            id: string;
+            type: string;
+            data: unknown;
+        };
+        meta?: Record<string, unknown>;
+    }>;
+    refundExecute(): Promise<import("@porulle/core").Result<never, CommerceValidationError>>;
+};

package/dist/mock-connector.js

@@ -0,0 +1,62 @@
+import { CommerceValidationError, Err, Ok, defineChannelConnector, } from "@porulle/core";
+export function mockChannelConnector(options = {}) {
+    const orders = new Map();
+    return defineChannelConnector({
+        providerId: "mock",
+        capabilities: {
+            importCatalog: true,
+            importInventory: true,
+            pushOrder: true,
+            receiveWebhooks: true,
+        },
+        async importCatalog() {
+            return Ok({ items: options.catalog ?? [], nextCursor: null });
+        },
+        async fetchInventory(_store, ids) {
+            const requestedIds = ids ?? [];
+            options.onFetchInventory?.(requestedIds);
+            if (options.inventoryDelayMs !== undefined) {
+                await new Promise((resolve) => setTimeout(resolve, options.inventoryDelayMs));
+            }
+            if (options.throwOnInventory)
+                throw new Error("Mock inventory failure.");
+            if (options.inventoryError)
+                return Err(new CommerceValidationError(options.inventoryError.message));
+            const inventory = options.inventory ?? [];
+            return Ok(ids ? inventory.filter((item) => ids.includes(item.externalId)) : inventory);
+        },
+        async pushOrder(_store, slice) {
+            const remoteOrderId = `mock-order-${orders.size + 1}`;
+            orders.set(remoteOrderId, structuredClone(slice));
+            return Ok({
+                remoteOrderId,
+                remoteUrl: `https://mock.channel.test/orders/${remoteOrderId}`,
+            });
+        },
+        async fetchOrderStatus(_store, remoteId) {
+            if (!orders.has(remoteId)) {
+                return Err(new CommerceValidationError(`Mock order "${remoteId}" was not found.`));
+            }
+            return Ok({ status: "confirmed" });
+        },
+        async verifyWebhook(store, request) {
+            if (request.headers.get("x-mock-signature") !== store.webhookSecret) {
+                return Err(new CommerceValidationError("Invalid mock webhook signature."));
+            }
+            let data;
+            try {
+                data = await request.json();
+            }
+            catch {
+                return Err(new CommerceValidationError("Mock webhook body must be valid JSON."));
+            }
+            if (!data.id || !data.type) {
+                return Err(new CommerceValidationError("Mock webhook requires id and type."));
+            }
+            return Ok({ id: data.id, type: data.type, data: data.data });
+        },
+        async refundExecute() {
+            return Err(new CommerceValidationError("Channel refund execution is not implemented in the foundations slice."));
+        },
+    });
+}

package/dist/oauth-state.d.ts

@@ -0,0 +1,17 @@
+export interface OAuthStatePayload {
+    provider: string;
+    orgId: string;
+    shopDomain: string;
+    exp: number;
+    jti: string;
+}
+export type OAuthStateResult = {
+    ok: true;
+    value: OAuthStatePayload;
+} | {
+    ok: false;
+    error: string;
+};
+export declare function signState(payload: OAuthStatePayload, secret: string): string;
+export declare function verifyState(state: string, secret: string, now?: number, consume?: boolean): OAuthStateResult;
+export declare function oauthStateEventId(jti: string): string;

package/dist/oauth-state.js

@@ -0,0 +1,78 @@
+import { createHmac, timingSafeEqual } from "node:crypto";
+const consumedJtis = new Map();
+function encodeText(value) {
+    return Buffer.from(value, "utf8").toString("base64url");
+}
+function encodeBytes(value) {
+    return Buffer.from(value).toString("base64url");
+}
+function decode(value) {
+    try {
+        return Buffer.from(value, "base64url").toString("utf8");
+    }
+    catch {
+        return undefined;
+    }
+}
+function signature(payload, secret) {
+    return createHmac("sha256", secret).update(payload).digest();
+}
+export function signState(payload, secret) {
+    if (!secret)
+        throw new Error("OAuth state secret is required.");
+    const encodedPayload = encodeText(JSON.stringify(payload));
+    return `${encodedPayload}.${encodeBytes(signature(encodedPayload, secret))}`;
+}
+export function verifyState(state, secret, now = Math.floor(Date.now() / 1000), consume = true) {
+    if (!secret)
+        return { ok: false, error: "OAuth state secret is required." };
+    const parts = state.split(".");
+    if (parts.length !== 2 || !parts[0] || !parts[1])
+        return { ok: false, error: "Malformed OAuth state." };
+    const expected = signature(parts[0], secret);
+    let actual;
+    try {
+        actual = Buffer.from(parts[1], "base64url");
+    }
+    catch {
+        return { ok: false, error: "Malformed OAuth state signature." };
+    }
+    if (actual.length !== expected.length || !timingSafeEqual(actual, expected)) {
+        return { ok: false, error: "Invalid OAuth state signature." };
+    }
+    const decoded = decode(parts[0]);
+    if (!decoded)
+        return { ok: false, error: "Malformed OAuth state payload." };
+    let payload;
+    try {
+        payload = JSON.parse(decoded);
+    }
+    catch {
+        return { ok: false, error: "Malformed OAuth state payload." };
+    }
+    if (!payload || typeof payload !== "object")
+        return { ok: false, error: "Malformed OAuth state payload." };
+    const candidate = payload;
+    const exp = candidate.exp;
+    if (typeof candidate.provider !== "string" ||
+        typeof candidate.orgId !== "string" ||
+        typeof candidate.shopDomain !== "string" ||
+        typeof candidate.jti !== "string" ||
+        typeof exp !== "number" ||
+        !Number.isInteger(exp))
+        return { ok: false, error: "Malformed OAuth state payload." };
+    if (exp <= now)
+        return { ok: false, error: "OAuth state has expired." };
+    for (const [jti, expiresAt] of consumedJtis) {
+        if (expiresAt <= now)
+            consumedJtis.delete(jti);
+    }
+    if (consume && consumedJtis.has(candidate.jti))
+        return { ok: false, error: "OAuth state has already been used." };
+    if (consume)
+        consumedJtis.set(candidate.jti, exp);
+    return { ok: true, value: candidate };
+}
+export function oauthStateEventId(jti) {
+    return `oauth-state:${jti}`;
+}