@unifiedcommerce/core 0.1.0 → 0.2.0

package/src/modules/webhooks/worker.ts

@@ -1,134 +0,0 @@
-import { signWebhookPayload } from "./signing.js";
-import { isPrivateIp } from "./ssrf-guard.js";
-import type { WebhooksRepository } from "./repository/index.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: string): void {
-  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: string): Promise<void> {
-  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}`);
-  }
-}
-
-interface WorkerDeps {
-  repository: WebhooksRepository;
-  fetchImpl?: typeof fetch;
-}
-
-export class WebhookDeliveryWorker {
-  private fetchImpl: typeof fetch;
-
-  constructor(private deps: WorkerDeps) {
-    this.fetchImpl = deps.fetchImpl ?? fetch;
-  }
-
-  async deliver(args: {
-    endpoint: { id: string; url: string; secret: string };
-    eventName: string;
-    payload: unknown;
-  }): Promise<void> {
-    // 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/src/runtime/commerce.ts

@@ -1,145 +0,0 @@
-import type { Actor } from "../auth/types.js";
-import type { CommerceConfig } from "../config/types.js";
-import type { Kernel } from "./kernel.js";
-import { createKernel } from "./kernel.js";
-import { ensureDefaultOrg } from "../auth/org.js";
-import { createAuth, type AuthInstance } from "../auth/setup.js";
-import { createLogger, type Logger } from "./logger.js";
-import { createLocalAPI, type CommerceLocalAPI, type LocalAPIOptions } 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 async function createCommerce(
-  config: CommerceConfig,
-): Promise<CommerceInstance> {
-  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: Actor): CommerceLocalAPI {
-      return createLocalAPI(kernel, { actor });
-    },
-
-    withTransaction(tx: unknown, actor?: Actor | null): CommerceLocalAPI {
-      return createLocalAPI(kernel, { actor: actor ?? null, tx });
-    },
-  };
-}

package/src/runtime/kernel.ts

@@ -1,419 +0,0 @@
-import type {
-  CommerceConfig,
-  MCPResource,
-  MCPTool,
-} from "../config/types.js";
-import { HookRegistry, type HookHandler } from "../kernel/hooks/registry.js";
-import {
-  createDatabaseConnection,
-  type DatabaseAdapter,
-} from "../kernel/database/adapter.js";
-import type { PluginDb } from "../kernel/database/plugin-types.js";
-
-import { CatalogServiceImpl } from "../modules/catalog/service.js";
-import { CatalogRepository } from "../modules/catalog/repository/index.js";
-import { InventoryRepository } from "../modules/inventory/repository/index.js";
-import { CartRepository } from "../modules/cart/repository/index.js";
-import { OrdersRepository } from "../modules/orders/repository/index.js";
-import { CustomersRepository } from "../modules/customers/repository/index.js";
-import { PricingRepository } from "../modules/pricing/repository/index.js";
-import { PromotionsRepository } from "../modules/promotions/repository/index.js";
-import { FulfillmentRepository } from "../modules/fulfillment/repository/index.js";
-import { WebhooksRepository } from "../modules/webhooks/repository/index.js";
-import { MediaRepository } from "../modules/media/repository/index.js";
-import type { DrizzleDatabase } from "../kernel/database/drizzle-db.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 { DrizzleAnalyticsAdapter } from "../modules/analytics/drizzle-adapter.js";
-import { BUILTIN_ANALYTICS_MODELS } from "../modules/analytics/models.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 { WebhookDeliveryWorker } from "../modules/webhooks/worker.js";
-import {
-  createAuditService,
-  type AuditService,
-} from "../modules/audit/service.js";
-import { OrganizationService } from "../modules/organization/service.js";
-import { createLogger } from "../utils/logger.js";
-import { withTiming } from "../kernel/service-timing.js";
-import { extendOrderStateMachine } from "../kernel/state-machine/machine.js";
-import { DEFAULT_ORG_ID } from "../auth/org.js";
-import { deliverWebhooks } from "../modules/webhooks/hook.js";
-// 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.js";
-import { auditHooks } from "../modules/audit/hooks.js";
-import { sendOrderStatusEmail } from "../hooks/order-emails.js";
-import { DrizzleJobsAdapter } from "../kernel/jobs/drizzle-adapter.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[];
-  mcpResources: MCPResource[];
-  logger: ReturnType<typeof createLogger>;
-  getMCPActor(): {
-    type: "api_key";
-    userId: string;
-    email: null;
-    name: string;
-    vendorId: null;
-    organizationId: string;
-    role: string;
-    permissions: string[];
-  };
-}
-
-const requiredServiceKeys = [
-  "catalog",
-  "inventory",
-  "media",
-  "cart",
-  "orders",
-  "payments",
-  "fulfillment",
-  "customers",
-  "webhooks",
-  "analytics",
-  "pricing",
-  "promotions",
-  "tax",
-  "shipping",
-  "search",
-  "audit",
-] as const satisfies Array<keyof Kernel["services"]>;
-
-function assertServicesReady(
-  services: Partial<Kernel["services"]>,
-): asserts services is Kernel["services"] {
-  for (const key of requiredServiceKeys) {
-    if (services[key] === undefined) {
-      throw new Error(`Kernel service "${String(key)}" was not initialized.`);
-    }
-  }
-}
-
-function registerConfiguredHooks(
-  config: CommerceConfig,
-  hooks: HookRegistry,
-): void {
-  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],
-  ] as const) {
-    const hooksObject = moduleConfig?.hooks;
-    if (!hooksObject) continue;
-    for (const [hookName, handlers] of Object.entries(hooksObject)) {
-      const normalizedHandlers: HookHandler[] = Array.isArray(handlers)
-        ? (handlers as unknown as HookHandler[])
-        : [];
-      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 as (...args: unknown[]) => unknown);
-  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: CommerceConfig): Kernel {
-  const hooks = new HookRegistry();
-  const logger = createLogger("kernel");
-  hooks.setLogger(logger as unknown as { error: (obj: Record<string, unknown>, msg: string) => void });
-
-  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<T>(fn: (tx: unknown) => Promise<T>): Promise<T> {
-        return fn({});
-      },
-    },
-  });
-  const mcpTools: MCPTool[] = [];
-  const mcpResources: MCPResource[] = [];
-
-  const services: Partial<Kernel["services"]> = {
-    email: config.email,
-    organization: new OrganizationService(database.db),
-  };
-
-  const serviceContainer = services as Record<string, unknown>;
-
-  // Expose database on service container so plugin hooks can access it
-  serviceContainer.database = database;
-
-  const db = database.db as DrizzleDatabase;
-
-  // 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: WebhookDeliveryPayload) {
-        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 as { db: PluginDb } },
-    ...(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 as unknown as { info: (o: Record<string, unknown>, m: string) => void; error: (o: Record<string, unknown>, m: string) => void };
-    const serviceKeys = Object.keys(services) as Array<keyof typeof services>;
-    for (const key of serviceKeys) {
-      const svc = services[key];
-      if (svc && typeof svc === "object" && key !== "email") {
-        (services as Record<string, unknown>)[key] = withTiming(
-          svc as object,
-          key,
-          timedLogger,
-        );
-      }
-    }
-  }
-
-  registerConfiguredHooks(config, hooks);
-
-  const kernel: 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 as HookHandler);
-    }
-  }
-
-  // Register plugin analytics models from config.analytics.models
-  for (const model of config.analytics?.models ?? []) {
-    services.analytics.registerModel(model);
-  }
-
-  return kernel;
-}