@unifiedcommerce/core 0.0.1

package/dist/runtime/kernel.js

@@ -0,0 +1,298 @@
+import { HookRegistry } from "../kernel/hooks/registry";
+import { createDatabaseConnection, } from "../kernel/database/adapter";
+import { CatalogServiceImpl } from "../modules/catalog/service";
+import { CatalogRepository } from "../modules/catalog/repository";
+import { InventoryRepository } from "../modules/inventory/repository";
+import { CartRepository } from "../modules/cart/repository";
+import { OrdersRepository } from "../modules/orders/repository";
+import { CustomersRepository } from "../modules/customers/repository";
+import { PricingRepository } from "../modules/pricing/repository";
+import { PromotionsRepository } from "../modules/promotions/repository";
+import { FulfillmentRepository } from "../modules/fulfillment/repository";
+import { WebhooksRepository } from "../modules/webhooks/repository";
+import { MediaRepository } from "../modules/media/repository";
+import { InventoryService } from "../modules/inventory/service";
+import { MediaService } from "../modules/media/service";
+import { CartService } from "../modules/cart/service";
+import { OrderService } from "../modules/orders/service";
+import { PaymentsService } from "../modules/payments/service";
+import { FulfillmentService } from "../modules/fulfillment/service";
+import { CustomerService } from "../modules/customers/service";
+import { WebhookService } from "../modules/webhooks/service";
+import { AnalyticsService } from "../modules/analytics/service";
+import { DrizzleAnalyticsAdapter } from "../modules/analytics/drizzle-adapter";
+import { BUILTIN_ANALYTICS_MODELS } from "../modules/analytics/models";
+import { PricingService } from "../modules/pricing/service";
+import { PromotionService } from "../modules/promotions/service";
+import { TaxService } from "../modules/tax/service";
+import { ShippingService } from "../modules/shipping/service";
+import { SearchService } from "../modules/search/service";
+import { WebhookDeliveryWorker } from "../modules/webhooks/worker";
+import { createAuditService, } from "../modules/audit/service";
+import { OrganizationService } from "../modules/organization/service";
+import { createLogger } from "../utils/logger";
+import { withTiming } from "../kernel/service-timing";
+import { extendOrderStateMachine } from "../kernel/state-machine/machine";
+import { DEFAULT_ORG_ID } from "../auth/org";
+import { deliverWebhooks } from "../modules/webhooks/hook";
+// Analytics event recording hooks removed (RFC-006): source tables ARE the events.
+// The DrizzleAnalyticsAdapter queries orders/inventory directly via SQL.
+import { syncToSearchIndex } from "../modules/search/hooks";
+import { auditHooks } from "../modules/audit/hooks";
+import { sendOrderStatusEmail } from "../hooks/order-emails";
+import { DrizzleJobsAdapter } from "../kernel/jobs/drizzle-adapter";
+const requiredServiceKeys = [
+    "catalog",
+    "inventory",
+    "media",
+    "cart",
+    "orders",
+    "payments",
+    "fulfillment",
+    "customers",
+    "webhooks",
+    "analytics",
+    "pricing",
+    "promotions",
+    "tax",
+    "shipping",
+    "search",
+    "audit",
+];
+function assertServicesReady(services) {
+    for (const key of requiredServiceKeys) {
+        if (services[key] === undefined) {
+            throw new Error(`Kernel service "${String(key)}" was not initialized.`);
+        }
+    }
+}
+function registerConfiguredHooks(config, hooks) {
+    for (const [entityType, entityConfig] of Object.entries(config.entities ?? {})) {
+        const entityHooks = entityConfig.hooks ?? {};
+        for (const [hookName, handlers] of Object.entries(entityHooks)) {
+            hooks.registerConfigHooks(`catalog.${entityType}.${hookName}`, handlers ?? []);
+        }
+    }
+    for (const [moduleName, moduleConfig] of [
+        ["cart", config.cart],
+        ["checkout", config.checkout],
+        ["orders", config.orders],
+        ["inventory", config.inventory],
+    ]) {
+        const hooksObject = moduleConfig?.hooks;
+        if (!hooksObject)
+            continue;
+        for (const [hookName, handlers] of Object.entries(hooksObject)) {
+            const normalizedHandlers = Array.isArray(handlers)
+                ? handlers
+                : [];
+            hooks.registerConfigHooks(`${moduleName}.${hookName}`, normalizedHandlers);
+        }
+    }
+    // Webhook delivery (async via job queue) — 14 event types
+    hooks.append("orders.afterCreate", deliverWebhooks);
+    hooks.append("orders.afterStatusChange", deliverWebhooks);
+    hooks.append("orders.afterStatusChange", sendOrderStatusEmail);
+    hooks.append("catalog.afterCreate", deliverWebhooks);
+    hooks.append("catalog.afterUpdate", deliverWebhooks);
+    hooks.append("catalog.afterDelete", deliverWebhooks);
+    hooks.append("inventory.afterAdjust", deliverWebhooks);
+    hooks.append("customers.afterCreate", deliverWebhooks);
+    hooks.append("customers.afterUpdate", deliverWebhooks);
+    hooks.append("pricing.afterCreate", deliverWebhooks);
+    hooks.append("pricing.afterUpdate", deliverWebhooks);
+    hooks.append("promotions.afterCreate", deliverWebhooks);
+    hooks.append("promotions.afterUpdate", deliverWebhooks);
+    hooks.append("fulfillment.afterCreate", deliverWebhooks);
+    hooks.append("cart.afterAddItem", deliverWebhooks);
+    // Analytics: no event recording hooks needed (RFC-006).
+    // The DrizzleAnalyticsAdapter queries source tables directly via SQL.
+    // Search index sync
+    hooks.append("catalog.afterCreate", syncToSearchIndex);
+    hooks.append("catalog.afterUpdate", syncToSearchIndex);
+    // Auto-audit — records every create/update/delete across all modules
+    for (const [key, handler] of Object.entries(auditHooks)) {
+        hooks.append(key, handler);
+    }
+}
+export function createKernel(config) {
+    const hooks = new HookRegistry();
+    const logger = createLogger("kernel");
+    hooks.setLogger(logger);
+    if (!config.storage) {
+        throw new Error("Storage adapter is required. Configure `storage` in defineConfig (for example: localStorageAdapter for development, or s3StorageAdapter/r2StorageAdapter for object storage).");
+    }
+    const database = createDatabaseConnection({
+        adapter: config.databaseAdapter ?? {
+            provider: config.database.provider,
+            db: {},
+            async transaction(fn) {
+                return fn({});
+            },
+        },
+    });
+    const mcpTools = [];
+    const mcpResources = [];
+    const services = {
+        email: config.email,
+        organization: new OrganizationService(database.db),
+    };
+    const serviceContainer = services;
+    // Expose database on service container so plugin hooks can access it
+    serviceContainer.database = database;
+    const db = database.db;
+    // Expose jobs adapter on service container so plugins can enqueue background work
+    const jobsAdapter = new DrizzleJobsAdapter(db, new Map());
+    serviceContainer.jobs = jobsAdapter;
+    const pricingRepository = new PricingRepository(db);
+    const promotionsRepository = new PromotionsRepository(db);
+    services.tax = new TaxService({ adapter: config.tax?.adapter });
+    services.payments = new PaymentsService(config.payments);
+    const customersRepository = new CustomersRepository(db);
+    services.customers = new CustomerService({
+        repository: customersRepository,
+    });
+    const webhooksRepository = new WebhooksRepository(db);
+    const webhookWorker = new WebhookDeliveryWorker({
+        repository: webhooksRepository,
+    });
+    services.webhooks = Object.assign(new WebhookService({
+        repository: webhooksRepository,
+    }), {
+        async enqueueDelivery(payload) {
+            await webhookWorker.deliver(payload);
+        },
+    });
+    const inventoryRepository = new InventoryRepository(db);
+    services.inventory = new InventoryService({
+        repository: inventoryRepository,
+        hooks,
+        config,
+        services: serviceContainer,
+        database,
+    });
+    const catalogRepository = new CatalogRepository(db);
+    services.catalog = new CatalogServiceImpl({
+        repository: catalogRepository,
+        hooks,
+        config,
+        services: serviceContainer,
+    });
+    services.search = new SearchService({
+        catalogRepository: catalogRepository,
+        ...(config.search?.adapter ? { adapter: config.search.adapter } : {}),
+        ...(config.search?.defaultFacets
+            ? { defaultFacets: config.search.defaultFacets }
+            : {}),
+    });
+    const cartRepository = new CartRepository(db);
+    services.cart = new CartService({
+        repository: cartRepository,
+        catalogRepository: catalogRepository,
+        hooks,
+        config,
+        services: serviceContainer,
+    });
+    const ordersRepository = new OrdersRepository(db);
+    services.orders = new OrderService({
+        repository: ordersRepository,
+        hooks,
+        services: serviceContainer,
+        kernel: { database: database },
+        ...(config.orders?.customTransitions
+            ? { stateMachine: extendOrderStateMachine(config.orders.customTransitions) }
+            : {}),
+    });
+    const fulfillmentRepository = new FulfillmentRepository(db);
+    services.fulfillment = new FulfillmentService({
+        repository: fulfillmentRepository,
+        ordersRepository: ordersRepository,
+        inventoryService: services.inventory,
+    });
+    services.pricing = new PricingService({
+        repository: pricingRepository,
+        catalogRepository: catalogRepository,
+    });
+    services.promotions = new PromotionService({
+        repository: promotionsRepository,
+        catalogRepository: catalogRepository,
+        ordersRepository: ordersRepository,
+    });
+    // AnalyticsService — always uses DrizzleAnalyticsAdapter (direct SQL).
+    // Plugins add their own models via the analyticsModels manifest slot.
+    const analyticsAdapter = new DrizzleAnalyticsAdapter(db);
+    for (const model of BUILTIN_ANALYTICS_MODELS) {
+        analyticsAdapter.registerModel(model);
+    }
+    services.analytics = new AnalyticsService({
+        adapter: analyticsAdapter,
+        config,
+    });
+    services.shipping = new ShippingService({
+        config,
+        catalogRepository: catalogRepository,
+    });
+    const mediaRepository = new MediaRepository(db);
+    services.media = new MediaService({
+        repository: mediaRepository,
+        catalogRepository: catalogRepository,
+        storage: config.storage,
+    });
+    services.audit = createAuditService(db);
+    assertServicesReady(services);
+    // Service method observability: wrap each service in a timing proxy
+    // that logs slow calls (>100ms) and failed calls with duration.
+    // Disabled in test environment to avoid noisy logs.
+    if (process.env.NODE_ENV !== "test") {
+        const timedLogger = logger;
+        const serviceKeys = Object.keys(services);
+        for (const key of serviceKeys) {
+            const svc = services[key];
+            if (svc && typeof svc === "object" && key !== "email") {
+                services[key] = withTiming(svc, key, timedLogger);
+            }
+        }
+    }
+    registerConfiguredHooks(config, hooks);
+    const kernel = {
+        config,
+        hooks,
+        database,
+        services,
+        mcpTools,
+        mcpResources,
+        logger,
+        getMCPActor() {
+            return {
+                type: "api_key",
+                userId: "mcp-agent",
+                email: null,
+                name: "MCP Agent",
+                vendorId: null,
+                organizationId: DEFAULT_ORG_ID,
+                role: "ai_agent",
+                permissions: config.auth?.roles?.ai_agent?.permissions ?? [
+                    "catalog:read",
+                    "catalog:create",
+                    "inventory:read",
+                    "inventory:adjust",
+                    "orders:read",
+                    "cart:create",
+                    "cart:update",
+                    "mcp:access",
+                ],
+            };
+        },
+    };
+    // Register plugin hooks from config.hooks flat map
+    for (const [key, handlers] of Object.entries(config.hooks ?? {})) {
+        for (const handler of handlers) {
+            hooks.append(key, handler);
+        }
+    }
+    // Register plugin analytics models from config.analytics.models
+    for (const model of config.analytics?.models ?? []) {
+        services.analytics.registerModel(model);
+    }
+    return kernel;
+}

package/dist/runtime/logger.d.ts

@@ -0,0 +1,11 @@
+import pino from "pino";
+import type { CommerceConfig } from "../config/types";
+export type Logger = pino.Logger;
+/**
+ * Create a structured JSON logger for the commerce engine.
+ *
+ * Automatically redacts sensitive fields (authorization, password, token, etc.)
+ * from all log output. Uses Pino for high-performance, newline-delimited JSON.
+ */
+export declare function createLogger(config: CommerceConfig): Logger;
+//# sourceMappingURL=logger.d.ts.map

package/dist/runtime/logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../../src/runtime/logger.ts"],"names":[],"mappings":"AAAA,OAAO,IAAI,MAAM,MAAM,CAAC;AACxB,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAEtD,MAAM,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC;AAEjC;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,cAAc,GAAG,MAAM,CAwB3D"}

package/dist/runtime/logger.js

@@ -0,0 +1,32 @@
+import pino from "pino";
+/**
+ * Create a structured JSON logger for the commerce engine.
+ *
+ * Automatically redacts sensitive fields (authorization, password, token, etc.)
+ * from all log output. Uses Pino for high-performance, newline-delimited JSON.
+ */
+export function createLogger(config) {
+    return pino({
+        level: config.logLevel ?? "info",
+        redact: {
+            paths: [
+                "req.headers.authorization",
+                "req.headers.cookie",
+                "*.password",
+                "*.secret",
+                "*.apiKey",
+                "*.creditCard",
+                "*.token",
+                "*.apiToken",
+            ],
+            censor: "[REDACTED]",
+        },
+        serializers: {
+            req: pino.stdSerializers.req,
+            err: pino.stdSerializers.err,
+        },
+        formatters: {
+            level: (label) => ({ level: label }),
+        },
+    });
+}

package/dist/runtime/server.d.ts

@@ -0,0 +1,28 @@
+import { OpenAPIHono } from "@hono/zod-openapi";
+import type { Actor } from "../auth/types";
+import type { AuthInstance } from "../auth/setup";
+import type { CommerceConfig } from "../config/types";
+import { type Logger } from "./logger";
+import { type CommerceInstance } from "./commerce";
+type ServerEnv = {
+    Variables: {
+        auth: AuthInstance;
+        actor: Actor | null;
+        requestId: string;
+        logger: Logger;
+    };
+};
+/**
+ * Create a full HTTP server (Hono) with all REST routes, auth, and middleware.
+ *
+ * For server-side frameworks (Next.js, TanStack Start, SvelteKit), use
+ * `createCommerce()` instead — it gives you a local API without HTTP overhead.
+ */
+export declare function createServer(config: CommerceConfig): Promise<{
+    app: OpenAPIHono<ServerEnv, {}, "/">;
+    kernel: import("./kernel").Kernel;
+    logger: Logger;
+    commerce: CommerceInstance;
+}>;
+export {};
+//# sourceMappingURL=server.d.ts.map

package/dist/runtime/server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../src/runtime/server.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAKhD,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,eAAe,CAAC;AAC3C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAClD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAQtD,OAAO,EAAgB,KAAK,MAAM,EAAE,MAAM,UAAU,CAAC;AACrD,OAAO,EAAkB,KAAK,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAEnE,KAAK,SAAS,GAAG;IACf,SAAS,EAAE;QACT,IAAI,EAAE,YAAY,CAAC;QACnB,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;QACpB,SAAS,EAAE,MAAM,CAAC;QAClB,MAAM,EAAE,MAAM,CAAC;KAChB,CAAC;CACH,CAAC;AAEF;;;;;GAKG;AACH,wBAAsB,YAAY,CAAC,MAAM,EAAE,cAAc;;;;;GAsTxD"}

package/dist/runtime/server.js

@@ -0,0 +1,277 @@
+import { OpenAPIHono } from "@hono/zod-openapi";
+import { cors } from "hono/cors";
+import { csrf } from "hono/csrf";
+import { bodyLimit } from "hono/body-limit";
+import { rateLimiter } from "hono-rate-limiter";
+import { authMiddleware } from "../auth/middleware";
+import { createMCPHandler } from "../interfaces/mcp/transport";
+import { createRestRoutes } from "../interfaces/rest";
+import { createCustomerPortalRoutes } from "../interfaces/rest/customer-portal";
+import { createCommerce } from "./commerce";
+/**
+ * Create a full HTTP server (Hono) with all REST routes, auth, and middleware.
+ *
+ * For server-side frameworks (Next.js, TanStack Start, SvelteKit), use
+ * `createCommerce()` instead — it gives you a local API without HTTP overhead.
+ */
+export async function createServer(config) {
+    const commerce = await createCommerce(config);
+    const { kernel, auth, logger } = commerce;
+    const isProdEnv = process.env.NODE_ENV === "production";
+    const app = new OpenAPIHono({
+        defaultHook: (result, c) => {
+            if (!result.success) {
+                return c.json({
+                    error: {
+                        code: "VALIDATION_FAILED",
+                        message: isProdEnv
+                            ? "Invalid input."
+                            : result.error.issues
+                                .map((i) => `${i.path.join(".")}: ${i.message}`)
+                                .join("; "),
+                    },
+                }, 422);
+            }
+        },
+    });
+    // ─── Security Guards ──────────────────────────────────────────────
+    if (config.auth?.enableDevKey && process.env.NODE_ENV === "production") {
+        throw new Error("FATAL: Dev key MUST NOT be enabled in production. " +
+            "Set auth.enableDevKey: false in production config.");
+    }
+    if (config.auth?.enableDevKey && process.env.NODE_ENV !== "development") {
+        logger.warn("Dev key is enabled outside NODE_ENV=development. " +
+            "Set auth.enableDevKey: false in production config to disable the dev backdoor.");
+    }
+    // ─── Process Crash Handlers (F4) ─────────────────────────────────────
+    process.on("unhandledRejection", (reason) => {
+        logger.fatal({ err: reason }, "unhandled promise rejection -- exiting");
+        process.exit(1);
+    });
+    process.on("uncaughtException", (err) => {
+        logger.fatal({ err }, "uncaught exception -- exiting");
+        process.exit(1);
+    });
+    // ─── Security Response Headers ──────────────────────────────────────
+    app.use("*", async (c, next) => {
+        c.header("X-Content-Type-Options", "nosniff");
+        c.header("X-Frame-Options", "DENY");
+        c.header("Referrer-Policy", "strict-origin-when-cross-origin");
+        c.header("Permissions-Policy", "camera=(), microphone=(), geolocation=()");
+        if (isProdEnv) {
+            c.header("Strict-Transport-Security", "max-age=31536000; includeSubDomains");
+        }
+        await next();
+    });
+    // ─── Request ID + Logging (F2, F12) ──────────────────────────────────
+    app.use("*", async (c, next) => {
+        const requestId = c.req.header("x-request-id") ?? crypto.randomUUID();
+        c.header("x-request-id", requestId);
+        c.set("requestId", requestId);
+        const child = logger.child({ requestId, method: c.req.method, path: c.req.path });
+        c.set("logger", child);
+        const start = performance.now();
+        await next();
+        // Sanitize ZodError responses in production.
+        // @hono/zod-openapi returns { success: false, error: { name: "ZodError" } }
+        // which leaks schema details. The library does not respect defaultHook for
+        // this format, so we intercept at the response level.
+        if (isProdEnv && c.res.status >= 400 && c.res.status < 500) {
+            const ct = c.res.headers.get("content-type");
+            if (ct?.includes("json")) {
+                try {
+                    const body = await c.res.clone().json();
+                    if (body?.error?.name === "ZodError") {
+                        c.res = new Response(JSON.stringify({ error: { code: "VALIDATION_FAILED", message: "Invalid input." } }), { status: 422, headers: { "content-type": "application/json" } });
+                    }
+                }
+                catch { /* non-parseable, skip */ }
+            }
+        }
+        const duration = Math.round(performance.now() - start);
+        child.info({ status: c.res.status, durationMs: duration }, "request completed");
+    });
+    // ─── CORS (hardened by default) ──────────────────────────────────────
+    const trustedOrigins = config.auth?.trustedOrigins ?? [];
+    app.use("*", cors({
+        origin: trustedOrigins.length > 0
+            ? trustedOrigins
+            : (process.env.NODE_ENV === "production" ? [] : ["http://localhost:*"]),
+        credentials: true,
+        allowMethods: ["GET", "POST", "PATCH", "PUT", "DELETE", "OPTIONS"],
+        allowHeaders: ["Content-Type", "Authorization", "x-api-key", "x-request-id"],
+        maxAge: 86400,
+    }));
+    // ─── CSRF Protection (F14) ──────────────────────────────────────────
+    app.use("/api/*", csrf({
+        origin: trustedOrigins.length > 0
+            ? trustedOrigins
+            : (process.env.NODE_ENV === "production" ? [] : ["http://localhost:*"]),
+    }));
+    // ─── Body Size Limit (F6) ──────────────────────────────────────────
+    app.use("*", bodyLimit({
+        maxSize: 1024 * 1024, // 1 MB default
+        onError: (c) => c.json({
+            error: { code: "PAYLOAD_TOO_LARGE", message: "Request body exceeds 1MB limit." },
+        }, 413),
+    }));
+    // ─── Rate Limiting (F1) ──────────────────────────────────────────────
+    // Trust X-Forwarded-For ONLY from a known reverse proxy IP.
+    // Set TRUSTED_PROXY_IP env var to the proxy's IP (e.g., "127.0.0.1").
+    const trustedProxyIp = process.env.TRUSTED_PROXY_IP;
+    const getClientIp = (c) => {
+        const raw = c.req.raw;
+        const remoteAddress = raw.socket?.remoteAddress;
+        // Only trust X-Forwarded-For when the direct connection is from a trusted proxy
+        if (trustedProxyIp && remoteAddress === trustedProxyIp) {
+            const xff = c.req.header("x-forwarded-for")?.split(",")[0]?.trim();
+            if (xff)
+                return xff;
+        }
+        return remoteAddress ?? "unknown";
+    };
+    const keyGenerator = getClientIp;
+    app.use("/api/auth/*", rateLimiter({
+        windowMs: 60 * 1000,
+        limit: config.rateLimits?.auth ?? 10,
+        keyGenerator,
+    }));
+    app.use("/api/checkout", rateLimiter({
+        windowMs: 60 * 1000,
+        limit: config.rateLimits?.checkout ?? 5,
+        keyGenerator,
+    }));
+    app.use("/api/*", rateLimiter({
+        windowMs: 60 * 1000,
+        limit: config.rateLimits?.api ?? 100,
+        keyGenerator,
+    }));
+    // ─── Custom Middleware ──────────────────────────────────────────────
+    if (config.middleware) {
+        for (const middleware of config.middleware) {
+            app.use("*", middleware);
+        }
+    }
+    // ─── Auth ──────────────────────────────────────────────────────────
+    app.use("/api/auth/*", async (c, next) => {
+        if (c.req.path.startsWith("/api/auth/pos/")) {
+            await next();
+            return;
+        }
+        return auth.handler(c.req.raw);
+    });
+    app.use("*", authMiddleware(auth, config));
+    app.use("*", async (c, next) => {
+        c.set("auth", auth);
+        await next();
+    });
+    // ─── Global Error Handler ─────────────────────────────────────────
+    // Sanitize errors in production — no stack traces, no class names, no schema details
+    const isProd = process.env.NODE_ENV === "production";
+    app.onError((err, c) => {
+        // Catch ZodError from @hono/zod-openapi validation (bypasses defaultHook)
+        if (err.constructor?.name === "ZodError" || "issues" in err) {
+            if (isProd) {
+                return c.json({ error: { code: "VALIDATION_FAILED", message: "Invalid input." } }, 422);
+            }
+            const issues = err.issues ?? [];
+            return c.json({
+                error: {
+                    code: "VALIDATION_FAILED",
+                    message: issues.map((i) => `${i.path.join(".")}: ${i.message}`).join("; "),
+                },
+            }, 422);
+        }
+        if (isProd) {
+            logger.error({ err }, "unhandled request error");
+            return c.json({ error: { code: "INTERNAL_ERROR", message: "An unexpected error occurred." } }, 500);
+        }
+        return c.json({ error: { code: "INTERNAL_ERROR", message: err.message } }, 500);
+    });
+    // ─── Routes ──────────────────────────────────────────────────────────
+    app.route("/api", createRestRoutes(kernel));
+    app.route("/mcp", createMCPHandler(kernel, config.mcpTools));
+    app.route("/api/me", createCustomerPortalRoutes(kernel));
+    if (config.routes) {
+        config.routes(app, kernel);
+    }
+    // OpenAPI spec — disabled in production unless explicitly enabled
+    const exposeSpec = config.exposeOpenApiSpec ?? !isProd;
+    if (exposeSpec) {
+        app.doc("/api/doc", {
+            openapi: "3.0.0",
+            info: {
+                title: "UnifiedCommerce API",
+                version: config.version ?? "0.0.1",
+                description: "Headless commerce engine REST API. Includes core and plugin endpoints.",
+            },
+        });
+    }
+    else {
+        app.get("/api/doc", (c) => c.json({ error: { code: "NOT_FOUND", message: "Not found." } }, 404));
+    }
+    // ─── Job Queue ───────────────────────────────────────────────────────
+    // Background job processing: webhook delivery, scheduled orders, email tasks.
+    //
+    // Three runner strategies (inspired by Payload CMS):
+    //   1. autorun: in-process polling (long-running servers)
+    //   2. GET /api/jobs/run: cron endpoint (serverless — Vercel, Cloudflare)
+    //   3. runPendingJobs() export (custom worker process)
+    const { runPendingJobs } = await import("../kernel/jobs/runner");
+    const taskMap = new Map();
+    for (const task of config.jobs?.tasks ?? []) {
+        taskMap.set(task.slug ?? task.name, task);
+    }
+    const runJobs = async (queue, limit) => {
+        return runPendingJobs({
+            db: kernel.database.db,
+            tasks: taskMap,
+            queue: queue ?? "default",
+            limit: limit ?? 10,
+            logger: logger,
+            services: kernel.services,
+        });
+    };
+    // Strategy 1: Built-in cron endpoint for serverless deployments.
+    // Point Vercel Cron or Cloudflare Cron Trigger at GET /api/jobs/run
+    // Optional query params: ?queue=emails&limit=20
+    app.get("/api/jobs/run", async (c) => {
+        // Always require admin — cron triggers must authenticate
+        const actor = c.get("actor");
+        if (!actor?.permissions?.includes("*:*")) {
+            return c.json({ error: { code: "FORBIDDEN", message: "Job runner requires admin access" } }, 403);
+        }
+        const queue = c.req.query("queue") ?? "default";
+        const limit = parseInt(c.req.query("limit") ?? "10", 10);
+        try {
+            const result = await runJobs(queue, limit);
+            return c.json({ data: result });
+        }
+        catch (err) {
+            logger.error({ err }, "Job runner endpoint failed");
+            return c.json({ error: { code: "INTERNAL_ERROR", message: "Job processing failed" } }, 500);
+        }
+    });
+    // Strategy 2: In-process polling for long-running servers (ECS, Cloud Run, Docker).
+    // Enable via config.jobs.autorun.enabled = true
+    if (config.jobs?.autorun?.enabled) {
+        const intervalMs = config.jobs.autorun.intervalMs ?? 10_000;
+        const jobInterval = setInterval(async () => {
+            try {
+                await runJobs();
+            }
+            catch (err) {
+                logger.error({ err }, "Job runner iteration failed");
+            }
+        }, intervalMs);
+        const cleanup = () => clearInterval(jobInterval);
+        process.on("SIGTERM", cleanup);
+        process.on("SIGINT", cleanup);
+        logger.info({ intervalMs }, "Job queue autorun started (in-process polling)");
+    }
+    else {
+        logger.info("Job queue autorun disabled. Use GET /api/jobs/run for serverless cron, " +
+            "or set config.jobs.autorun.enabled = true for in-process polling.");
+    }
+    return { app, kernel, logger, commerce };
+}

package/dist/runtime/shutdown.d.ts

@@ -0,0 +1,15 @@
+import type { Logger } from "./logger";
+/**
+ * Sets up graceful shutdown handlers for SIGTERM and SIGINT.
+ *
+ * On signal:
+ * 1. Stops accepting new connections
+ * 2. Runs cleanup (close DB pool, flush logs)
+ * 3. Force-exits after timeout if cleanup hangs
+ */
+export declare function setupGracefulShutdown(opts: {
+    cleanup: () => Promise<void>;
+    logger: Logger;
+    timeoutMs?: number;
+}): void;
+//# sourceMappingURL=shutdown.d.ts.map

package/dist/runtime/shutdown.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shutdown.d.ts","sourceRoot":"","sources":["../../src/runtime/shutdown.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AAEvC;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE;IAC1C,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,GAAG,IAAI,CA4BP"}