@unifiedcommerce/core 0.4.4 → 0.5.0

package/dist/modules/webhooks/service.js

@@ -0,0 +1,92 @@
+import { resolveOrgId } from "../../auth/org.js";
+import { CommerceNotFoundError, CommerceValidationError } from "../../kernel/errors.js";
+import { Err, Ok } from "../../kernel/result.js";
+/**
+ * Checks whether a URL points to a private/internal IP address.
+ * Blocks: loopback (127.x), link-local (169.254.x), private (10.x, 172.16-31.x, 192.168.x),
+ * cloud metadata (169.254.169.254, metadata.google.internal), and localhost.
+ */
+function isPrivateUrl(urlStr) {
+    try {
+        const parsed = new URL(urlStr);
+        // Strip IPv6 brackets: URL.hostname returns "[::1]" not "::1"
+        const hostname = parsed.hostname.toLowerCase().replace(/^\[|\]$/g, "");
+        // Loopback (IPv4 + IPv6)
+        if (hostname === "localhost" || hostname === "127.0.0.1" || hostname === "::1")
+            return true;
+        if (hostname.endsWith(".localhost"))
+            return true;
+        // IPv6 loopback and link-local patterns
+        if (hostname.startsWith("::ffff:"))
+            return true; // IPv6-mapped IPv4 (e.g., ::ffff:127.0.0.1)
+        if (hostname.startsWith("fe80:"))
+            return true; // IPv6 link-local
+        if (hostname === "::")
+            return true; // Unspecified address
+        // Cloud metadata endpoints
+        if (hostname === "169.254.169.254")
+            return true;
+        if (hostname === "metadata.google.internal")
+            return true;
+        // Private IP ranges (RFC 1918 + link-local)
+        const parts = hostname.split(".").map(Number);
+        if (parts.length === 4 && parts.every((n) => !isNaN(n))) {
+            const [a, b] = parts;
+            if (a === 10)
+                return true;
+            if (a === 172 && b !== undefined && b >= 16 && b <= 31)
+                return true;
+            if (a === 192 && b === 168)
+                return true;
+            if (a === 169 && b === 254)
+                return true;
+            if (a === 127)
+                return true; // Full 127.0.0.0/8 range
+            if (a === 0)
+                return true;
+        }
+        return false;
+    }
+    catch {
+        return true; // Invalid URLs are blocked
+    }
+}
+export class WebhookService {
+    deps;
+    repo;
+    constructor(deps) {
+        this.deps = deps;
+        this.repo = deps.repository;
+    }
+    async createEndpoint(input, actor, ctx) {
+        if (isPrivateUrl(input.url)) {
+            return Err(new CommerceValidationError("Webhook URL must not point to a private or internal address."));
+        }
+        const orgId = resolveOrgId(actor ?? ctx?.actor ?? null);
+        const endpoint = await this.repo.createEndpoint({
+            organizationId: orgId,
+            url: input.url,
+            secret: input.secret,
+            events: input.events,
+            isActive: true,
+            metadata: input.metadata ?? {},
+        }, ctx);
+        return Ok(endpoint);
+    }
+    async listEndpoints(ctx) {
+        const endpoints = await this.repo.findAllEndpoints(ctx);
+        return Ok(endpoints);
+    }
+    async deleteEndpoint(id, ctx) {
+        const existing = await this.repo.findEndpointById(id, ctx);
+        if (!existing) {
+            return Err(new CommerceNotFoundError("Webhook endpoint not found."));
+        }
+        await this.repo.deleteEndpoint(id, ctx);
+        return Ok(undefined);
+    }
+    async getEndpointsForEvent(eventName, ctx) {
+        const endpoints = await this.repo.findEndpointsForEvent(eventName, ctx);
+        return Ok(endpoints);
+    }
+}

package/dist/modules/webhooks/signing.d.ts

@@ -0,0 +1,2 @@
+export declare function signWebhookPayload(secret: string, payload: unknown): string;
+//# sourceMappingURL=signing.d.ts.map

package/dist/modules/webhooks/signing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"signing.d.ts","sourceRoot":"","sources":["../../../src/modules/webhooks/signing.ts"],"names":[],"mappings":"AAEA,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,MAAM,CAG3E"}

package/dist/modules/webhooks/signing.js

@@ -0,0 +1,5 @@
+import { createHmac } from "node:crypto";
+export function signWebhookPayload(secret, payload) {
+    const body = typeof payload === "string" ? payload : JSON.stringify(payload);
+    return createHmac("sha256", secret).update(body).digest("hex");
+}

package/dist/modules/webhooks/ssrf-guard.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Shared SSRF prevention utilities.
+ *
+ * Used by both webhook delivery (DNS rebinding check) and connector URL
+ * validation (store URL check) to reject private/internal IP addresses.
+ */
+/**
+ * Returns true if the given IP address falls within a private, loopback,
+ * link-local, or otherwise non-routable range.
+ */
+export declare function isPrivateIp(ip: string): boolean;
+/**
+ * Checks whether a URL string points to a private/internal IP address or
+ * hostname. This performs a string-level check only (no DNS resolution).
+ *
+ * For DNS rebinding protection, use `isPrivateIp` after resolving the hostname.
+ */
+export declare function isPrivateUrl(urlStr: string): boolean;
+//# sourceMappingURL=ssrf-guard.d.ts.map

package/dist/modules/webhooks/ssrf-guard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ssrf-guard.d.ts","sourceRoot":"","sources":["../../../src/modules/webhooks/ssrf-guard.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;;GAGG;AACH,wBAAgB,WAAW,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAY/C;AAmBD;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAsBpD"}

package/dist/modules/webhooks/ssrf-guard.js

@@ -0,0 +1,79 @@
+/**
+ * Shared SSRF prevention utilities.
+ *
+ * Used by both webhook delivery (DNS rebinding check) and connector URL
+ * validation (store URL check) to reject private/internal IP addresses.
+ */
+/**
+ * Returns true if the given IP address falls within a private, loopback,
+ * link-local, or otherwise non-routable range.
+ */
+export function isPrivateIp(ip) {
+    // IPv6 loopback / link-local / mapped
+    if (ip === "::1" || ip === "::")
+        return true;
+    if (ip.startsWith("fe80:"))
+        return true;
+    // IPv6-mapped IPv4 (e.g. ::ffff:127.0.0.1) — extract the IPv4 portion
+    const mappedMatch = ip.match(/^::ffff:(\d+\.\d+\.\d+\.\d+)$/i);
+    if (mappedMatch) {
+        return isPrivateIpv4(mappedMatch[1]);
+    }
+    return isPrivateIpv4(ip);
+}
+function isPrivateIpv4(ip) {
+    const parts = ip.split(".").map(Number);
+    if (parts.length !== 4 || parts.some((n) => isNaN(n)))
+        return false;
+    const [a, b] = parts;
+    if (a === undefined || b === undefined)
+        return false;
+    if (a === 127)
+        return true; // loopback 127.0.0.0/8
+    if (a === 10)
+        return true; // RFC 1918 class A
+    if (a === 172 && b >= 16 && b <= 31)
+        return true; // RFC 1918 class B
+    if (a === 192 && b === 168)
+        return true; // RFC 1918 class C
+    if (a === 169 && b === 254)
+        return true; // link-local / AWS IMDS
+    if (a === 0)
+        return true; // unspecified
+    return false;
+}
+/**
+ * Checks whether a URL string points to a private/internal IP address or
+ * hostname. This performs a string-level check only (no DNS resolution).
+ *
+ * For DNS rebinding protection, use `isPrivateIp` after resolving the hostname.
+ */
+export function isPrivateUrl(urlStr) {
+    try {
+        const parsed = new URL(urlStr);
+        const hostname = parsed.hostname.toLowerCase().replace(/^\[|\]$/g, "");
+        // Direct hostname matches
+        if (hostname === "localhost" || hostname.endsWith(".localhost"))
+            return true;
+        if (hostname === "::1" || hostname === "::")
+            return true;
+        if (hostname.startsWith("::ffff:"))
+            return true;
+        if (hostname.startsWith("fe80:"))
+            return true;
+        if (hostname.endsWith(".local"))
+            return true;
+        if (hostname.endsWith(".internal"))
+            return true;
+        // Cloud metadata endpoints
+        if (hostname === "169.254.169.254")
+            return true;
+        if (hostname === "metadata.google.internal")
+            return true;
+        // Check if hostname is a raw IP in private ranges
+        return isPrivateIpv4(hostname);
+    }
+    catch {
+        return true; // Invalid URLs are blocked
+    }
+}

package/dist/modules/webhooks/tasks.d.ts

@@ -0,0 +1,16 @@
+import type { TaskDefinition } from "../../kernel/jobs/types.js";
+/**
+ * Background task for async webhook delivery.
+ *
+ * Instead of blocking the HTTP response with inline webhook HTTP calls,
+ * the deliverWebhooks hook enqueues this task. The job runner picks it up
+ * and delivers asynchronously with retries.
+ */
+export declare const webhookDeliveryTask: TaskDefinition<{
+    endpointId: string;
+    endpointUrl: string;
+    endpointSecret: string;
+    eventName: string;
+    payload: unknown;
+}>;
+//# sourceMappingURL=tasks.d.ts.map

package/dist/modules/webhooks/tasks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tasks.d.ts","sourceRoot":"","sources":["../../../src/modules/webhooks/tasks.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAC;AAIjE;;;;;;GAMG;AACH,eAAO,MAAM,mBAAmB,EAAE,cAAc,CAAC;IAC/C,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,cAAc,EAAE,MAAM,CAAC;IACvB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,OAAO,CAAC;CAClB,CAkCA,CAAC"}

package/dist/modules/webhooks/tasks.js

@@ -0,0 +1,35 @@
+import { WebhookDeliveryWorker } from "./worker.js";
+/**
+ * Background task for async webhook delivery.
+ *
+ * Instead of blocking the HTTP response with inline webhook HTTP calls,
+ * the deliverWebhooks hook enqueues this task. The job runner picks it up
+ * and delivers asynchronously with retries.
+ */
+export const webhookDeliveryTask = {
+    slug: "webhooks/deliver",
+    async handler({ input, ctx }) {
+        const webhooksService = ctx.services.webhooks;
+        // Build a minimal worker — the repository is needed for delivery tracking
+        const repository = webhooksService?.repository;
+        if (!repository) {
+            ctx.logger.warn("Webhook delivery skipped: no webhooks repository available");
+            return { output: {} };
+        }
+        const worker = new WebhookDeliveryWorker({ repository });
+        await worker.deliver({
+            endpoint: {
+                id: input.endpointId,
+                url: input.endpointUrl,
+                secret: input.endpointSecret,
+            },
+            eventName: input.eventName,
+            payload: input.payload,
+        });
+        return { output: {} };
+    },
+    retries: {
+        attempts: 5,
+        backoff: { type: "exponential", delay: 2000 },
+    },
+};

package/dist/modules/webhooks/worker.d.ts

@@ -0,0 +1,21 @@
+import type { WebhooksRepository } from "./repository/index.js";
+interface WorkerDeps {
+    repository: WebhooksRepository;
+    fetchImpl?: typeof fetch;
+}
+export declare class WebhookDeliveryWorker {
+    private deps;
+    private fetchImpl;
+    constructor(deps: WorkerDeps);
+    deliver(args: {
+        endpoint: {
+            id: string;
+            url: string;
+            secret: string;
+        };
+        eventName: string;
+        payload: unknown;
+    }): Promise<void>;
+}
+export {};
+//# sourceMappingURL=worker.d.ts.map

package/dist/modules/webhooks/worker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"worker.d.ts","sourceRoot":"","sources":["../../../src/modules/webhooks/worker.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AA+DhE,UAAU,UAAU;IAClB,UAAU,EAAE,kBAAkB,CAAC;IAC/B,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;CAC1B;AAED,qBAAa,qBAAqB;IAGpB,OAAO,CAAC,IAAI;IAFxB,OAAO,CAAC,SAAS,CAAe;gBAEZ,IAAI,EAAE,UAAU;IAI9B,OAAO,CAAC,IAAI,EAAE;QAClB,QAAQ,EAAE;YAAE,EAAE,EAAE,MAAM,CAAC;YAAC,GAAG,EAAE,MAAM,CAAC;YAAC,MAAM,EAAE,MAAM,CAAA;SAAE,CAAC;QACtD,SAAS,EAAE,MAAM,CAAC;QAClB,OAAO,EAAE,OAAO,CAAC;KAClB,GAAG,OAAO,CAAC,IAAI,CAAC;CAoDlB"}

package/dist/modules/webhooks/worker.js

@@ -0,0 +1,113 @@
+import { signWebhookPayload } from "./signing.js";
+import { isPrivateIp } from "./ssrf-guard.js";
+/**
+ * SSRF prevention: reject webhook URLs targeting private/internal hosts.
+ * Blocks RFC 1918, loopback, link-local, and common internal domains.
+ */
+const PRIVATE_HOST_PATTERNS = [
+    /^127\./, // loopback
+    /^10\./, // RFC 1918 class A
+    /^172\.(1[6-9]|2[0-9]|3[01])\./, // RFC 1918 class B
+    /^192\.168\./, // RFC 1918 class C
+    /^169\.254\./, // link-local / AWS IMDS
+    /^0\.0\.0\.0/, // unspecified
+    /^localhost$/i,
+    /\.local$/i,
+    /\.internal$/i,
+];
+function validateWebhookUrl(url) {
+    const parsed = new URL(url);
+    if (process.env.NODE_ENV === "production" && parsed.protocol !== "https:") {
+        throw new Error("Webhook URLs must use HTTPS in production.");
+    }
+    const hostname = parsed.hostname;
+    for (const pattern of PRIVATE_HOST_PATTERNS) {
+        if (pattern.test(hostname)) {
+            throw new Error(`Webhook URLs cannot target private hosts: ${hostname}`);
+        }
+    }
+}
+/**
+ * Resolve the webhook URL hostname via DNS and verify the resolved IP is not
+ * private. This closes the DNS rebinding gap where a hostname initially
+ * resolves to a public IP but later rebinds to an internal address.
+ */
+async function validateResolvedIp(url) {
+    const { lookup } = await import("node:dns/promises");
+    const parsed = new URL(url);
+    const hostname = parsed.hostname.replace(/^\[|\]$/g, "");
+    // Skip DNS resolution for raw IP addresses — they are already checked
+    // by validateWebhookUrl via PRIVATE_HOST_PATTERNS.
+    const isIpLiteral = /^[\d.]+$/.test(hostname) || hostname.includes(":");
+    if (isIpLiteral)
+        return;
+    try {
+        const { address } = await lookup(hostname);
+        if (isPrivateIp(address)) {
+            throw new Error(`Webhook URL hostname "${hostname}" resolved to private IP ${address}`);
+        }
+    }
+    catch (err) {
+        if (err instanceof Error && err.message.includes("resolved to private")) {
+            throw err;
+        }
+        throw new Error(`Failed to resolve webhook URL hostname "${hostname}": ${err}`);
+    }
+}
+export class WebhookDeliveryWorker {
+    deps;
+    fetchImpl;
+    constructor(deps) {
+        this.deps = deps;
+        this.fetchImpl = deps.fetchImpl ?? fetch;
+    }
+    async deliver(args) {
+        // SSRF prevention: validate URL string patterns + resolved DNS IP
+        validateWebhookUrl(args.endpoint.url);
+        await validateResolvedIp(args.endpoint.url);
+        let attempt = 0;
+        const maxAttempts = 3;
+        while (attempt < maxAttempts) {
+            attempt += 1;
+            const signature = signWebhookPayload(args.endpoint.secret, args.payload);
+            try {
+                const response = await this.fetchImpl(args.endpoint.url, {
+                    method: "POST",
+                    headers: {
+                        "content-type": "application/json",
+                        "x-commerce-signature": signature,
+                        "x-commerce-event": args.eventName,
+                    },
+                    body: JSON.stringify(args.payload),
+                    signal: AbortSignal.timeout(10_000),
+                });
+                await this.deps.repository.createDelivery({
+                    endpointId: args.endpoint.id,
+                    eventName: args.eventName,
+                    payload: args.payload,
+                    statusCode: response.status,
+                    attemptCount: attempt,
+                    ...(response.ok ? { deliveredAt: new Date() } : {}),
+                    ...(!response.ok ? { failedAt: new Date() } : {}),
+                    ...(!response.ok && attempt < maxAttempts
+                        ? { nextRetryAt: new Date(Date.now() + 2 ** attempt * 1000) }
+                        : {}),
+                });
+                if (response.ok)
+                    return;
+            }
+            catch {
+                await this.deps.repository.createDelivery({
+                    endpointId: args.endpoint.id,
+                    eventName: args.eventName,
+                    payload: args.payload,
+                    attemptCount: attempt,
+                    failedAt: new Date(),
+                    ...(attempt < maxAttempts
+                        ? { nextRetryAt: new Date(Date.now() + 2 ** attempt * 1000) }
+                        : {}),
+                });
+            }
+        }
+    }
+}

package/dist/runtime/commerce.d.ts

@@ -0,0 +1,110 @@
+import type { Actor } from "../auth/types.js";
+import type { CommerceConfig } from "../config/types.js";
+import type { Kernel } from "./kernel.js";
+import { type AuthInstance } from "../auth/setup.js";
+import { type Logger } from "./logger.js";
+import { type CommerceLocalAPI } from "../kernel/local-api.js";
+/**
+ * The commerce instance returned by `createCommerce()`.
+ *
+ * This is the headless, framework-agnostic entry point.
+ * No HTTP server, no Hono — just typed services and a local API.
+ *
+ * ## Usage with Next.js App Router:
+ *
+ * ```typescript
+ * // lib/commerce.ts
+ * import { createCommerce } from "@unifiedcommerce/core";
+ * import config from "../commerce.config.js";
+ *
+ * export const commerce = await createCommerce(config);
+ *
+ * // app/products/page.tsx (Server Component)
+ * import { commerce } from "@/lib/commerce";
+ *
+ * export default async function ProductsPage() {
+ *   const products = await commerce.api.catalog.list({ limit: 20 });
+ *   if (!products.ok) return <div>Error</div>;
+ *   return <ProductGrid items={products.value.items} />;
+ * }
+ * ```
+ *
+ * ## Usage with TanStack Start:
+ *
+ * ```typescript
+ * // app/routes/products.tsx
+ * import { createServerFn } from "@tanstack/start";
+ * import { commerce } from "../lib/commerce.js";
+ *
+ * const getProducts = createServerFn("GET", async () => {
+ *   return commerce.api.catalog.list({ limit: 20 });
+ * });
+ * ```
+ *
+ * ## Usage with SvelteKit:
+ *
+ * ```typescript
+ * // src/lib/server/commerce.ts
+ * import { createCommerce } from "@unifiedcommerce/core";
+ * import config from "./commerce.config.js";
+ * export const commerce = await createCommerce(config);
+ *
+ * // src/routes/products/+page.server.ts
+ * import { commerce } from "$lib/server/commerce";
+ * export async function load() {
+ *   const products = await commerce.api.catalog.list({ limit: 20 });
+ *   return { products: products.ok ? products.value : { items: [] } };
+ * }
+ * ```
+ */
+export interface CommerceInstance {
+    /** Proxy-based local API — auto-injects actor/tx to every service call */
+    api: CommerceLocalAPI;
+    /** Raw kernel for advanced usage (hooks, database, config) */
+    kernel: Kernel;
+    /** Drizzle database instance for direct queries */
+    db: unknown;
+    /** Auth instance (Better Auth) for session management */
+    auth: AuthInstance;
+    /** Logger */
+    logger: Logger;
+    /**
+     * Create a scoped API for a specific user/actor.
+     * Use this in authenticated routes to scope data access.
+     *
+     * ```typescript
+     * // In a Next.js server action:
+     * const userApi = commerce.withActor({
+     *   type: "user", userId: session.userId, ...
+     * });
+     * const orders = await userApi.orders.list({ limit: 10 });
+     * // Only returns orders for this user's org
+     * ```
+     */
+    withActor(actor: Actor): CommerceLocalAPI;
+    /**
+     * Create a scoped API within a database transaction.
+     *
+     * ```typescript
+     * await commerce.kernel.database.transaction(async (tx) => {
+     *   const txApi = commerce.withTransaction(tx, actor);
+     *   await txApi.inventory.adjust({ entityId, adjustment: -1, reason: "sold" });
+     *   await txApi.orders.create({ ... });
+     * });
+     * ```
+     */
+    withTransaction(tx: unknown, actor?: Actor | null): CommerceLocalAPI;
+}
+/**
+ * Create a headless commerce instance.
+ *
+ * This is the primary entry point for using UnifiedCommerce without an HTTP server.
+ * It initializes the kernel, database, auth, and returns a local API that works
+ * exactly like the REST API but without HTTP overhead.
+ *
+ * The Hono server (`createServer`) is optional — use it only when you need
+ * a standalone HTTP API. For Next.js, TanStack Start, SvelteKit, Nuxt, etc.,
+ * use `createCommerce()` directly.
+ */
+export declare function createCommerce(config: CommerceConfig): Promise<CommerceInstance>;
+//# sourceMappingURL=commerce.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"commerce.d.ts","sourceRoot":"","sources":["../../src/runtime/commerce.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACzD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAG1C,OAAO,EAAc,KAAK,YAAY,EAAE,MAAM,kBAAkB,CAAC;AACjE,OAAO,EAAgB,KAAK,MAAM,EAAE,MAAM,aAAa,CAAC;AACxD,OAAO,EAAkB,KAAK,gBAAgB,EAAwB,MAAM,wBAAwB,CAAC;AAErG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoDG;AACH,MAAM,WAAW,gBAAgB;IAC/B,0EAA0E;IAC1E,GAAG,EAAE,gBAAgB,CAAC;IAEtB,8DAA8D;IAC9D,MAAM,EAAE,MAAM,CAAC;IAEf,mDAAmD;IACnD,EAAE,EAAE,OAAO,CAAC;IAEZ,yDAAyD;IACzD,IAAI,EAAE,YAAY,CAAC;IAEnB,aAAa;IACb,MAAM,EAAE,MAAM,CAAC;IAEf;;;;;;;;;;;;OAYG;IACH,SAAS,CAAC,KAAK,EAAE,KAAK,GAAG,gBAAgB,CAAC;IAE1C;;;;;;;;;;OAUG;IACH,eAAe,CAAC,EAAE,EAAE,OAAO,EAAE,KAAK,CAAC,EAAE,KAAK,GAAG,IAAI,GAAG,gBAAgB,CAAC;CACtE;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,cAAc,CAClC,MAAM,EAAE,cAAc,GACrB,OAAO,CAAC,gBAAgB,CAAC,CAyB3B"}

package/dist/runtime/commerce.js

@@ -0,0 +1,37 @@
+import { createKernel } from "./kernel.js";
+import { ensureDefaultOrg } from "../auth/org.js";
+import { createAuth } from "../auth/setup.js";
+import { createLogger } from "./logger.js";
+import { createLocalAPI } from "../kernel/local-api.js";
+/**
+ * Create a headless commerce instance.
+ *
+ * This is the primary entry point for using UnifiedCommerce without an HTTP server.
+ * It initializes the kernel, database, auth, and returns a local API that works
+ * exactly like the REST API but without HTTP overhead.
+ *
+ * The Hono server (`createServer`) is optional — use it only when you need
+ * a standalone HTTP API. For Next.js, TanStack Start, SvelteKit, Nuxt, etc.,
+ * use `createCommerce()` directly.
+ */
+export async function createCommerce(config) {
+    const kernel = createKernel(config);
+    await ensureDefaultOrg(kernel.database.db);
+    const auth = createAuth(kernel.database, config);
+    const logger = createLogger(config);
+    // Default API: no actor (public access), no transaction
+    const api = createLocalAPI(kernel);
+    return {
+        api,
+        kernel,
+        db: kernel.database.db,
+        auth,
+        logger,
+        withActor(actor) {
+            return createLocalAPI(kernel, { actor });
+        },
+        withTransaction(tx, actor) {
+            return createLocalAPI(kernel, { actor: actor ?? null, tx });
+        },
+    };
+}

package/dist/runtime/kernel.d.ts

@@ -0,0 +1,71 @@
+import type { CommerceConfig, MCPTool } from "../config/types.js";
+import { HookRegistry } from "../kernel/hooks/registry.js";
+import { type DatabaseAdapter } from "../kernel/database/adapter.js";
+import { CatalogServiceImpl } from "../modules/catalog/service.js";
+import { InventoryService } from "../modules/inventory/service.js";
+import { MediaService } from "../modules/media/service.js";
+import { CartService } from "../modules/cart/service.js";
+import { OrderService } from "../modules/orders/service.js";
+import { PaymentsService } from "../modules/payments/service.js";
+import { FulfillmentService } from "../modules/fulfillment/service.js";
+import { CustomerService } from "../modules/customers/service.js";
+import { WebhookService } from "../modules/webhooks/service.js";
+import { AnalyticsService } from "../modules/analytics/service.js";
+import { PricingService } from "../modules/pricing/service.js";
+import { PromotionService } from "../modules/promotions/service.js";
+import { TaxService } from "../modules/tax/service.js";
+import { ShippingService } from "../modules/shipping/service.js";
+import { SearchService } from "../modules/search/service.js";
+import { type AuditService } from "../modules/audit/service.js";
+import { OrganizationService } from "../modules/organization/service.js";
+import { createLogger } from "../utils/logger.js";
+export interface WebhookDeliveryPayload {
+    endpoint: {
+        id: string;
+        url: string;
+        secret: string;
+    };
+    eventName: string;
+    payload: unknown;
+}
+export interface Kernel {
+    config: CommerceConfig;
+    hooks: HookRegistry;
+    database: DatabaseAdapter;
+    services: {
+        catalog: CatalogServiceImpl;
+        inventory: InventoryService;
+        media: MediaService;
+        cart: CartService;
+        orders: OrderService;
+        payments: PaymentsService;
+        fulfillment: FulfillmentService;
+        customers: CustomerService;
+        webhooks: WebhookService & {
+            enqueueDelivery(payload: WebhookDeliveryPayload): Promise<void>;
+        };
+        analytics: AnalyticsService;
+        pricing: PricingService;
+        promotions: PromotionService;
+        tax: TaxService;
+        shipping: ShippingService;
+        search: SearchService;
+        audit: AuditService;
+        email: CommerceConfig["email"];
+        organization: OrganizationService;
+    };
+    mcpTools: MCPTool[];
+    logger: ReturnType<typeof createLogger>;
+    getMCPActor(): {
+        type: "api_key";
+        userId: string;
+        email: null;
+        name: string;
+        vendorId: null;
+        organizationId: string;
+        role: string;
+        permissions: string[];
+    };
+}
+export declare function createKernel(config: CommerceConfig): Kernel;
+//# sourceMappingURL=kernel.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"kernel.d.ts","sourceRoot":"","sources":["../../src/runtime/kernel.ts"],"names":[],"mappings":"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"}