@unifiedcommerce/core 0.2.0 → 0.2.2

package/src/kernel/hooks/registry.ts

@@ -0,0 +1,74 @@
+export type HookHandler = (...args: never[]) => unknown;
+
+type HookEntry = {
+  prepended: HookHandler[];
+  configured: HookHandler[];
+  appended: HookHandler[];
+};
+
+export class HookRegistry {
+  private registry = new Map<string, HookEntry>();
+  private logger?: { error: (obj: Record<string, unknown>, msg: string) => void };
+
+  registerConfigHooks(hookName: string, handlers: HookHandler[]): void {
+    this.ensureEntry(hookName);
+    this.registry.get(hookName)!.configured = [...handlers];
+  }
+
+  append(hookName: string, handler: HookHandler): void {
+    this.ensureEntry(hookName);
+    this.registry.get(hookName)!.appended.push(handler);
+  }
+
+  prepend(hookName: string, handler: HookHandler): void {
+    this.ensureEntry(hookName);
+    this.registry.get(hookName)!.prepended.push(handler);
+  }
+
+  resolve(hookName: string): HookHandler[] {
+    const entry = this.registry.get(hookName);
+    if (!entry) return [];
+    return [...entry.prepended, ...entry.configured, ...entry.appended];
+  }
+
+  /**
+   * Emit a plugin event to all registered listeners.
+   *
+   * Unlike the before/after hook pattern (which transforms data through
+   * a pipeline), emit is fire-and-forget notification. Errors in handlers
+   * are caught and logged but do not propagate to the emitter.
+   *
+   * Usage:
+   *   kernel.hooks.emit("production.afterComplete", { orderId, quantity });
+   *
+   * Any plugin can listen:
+   *   hooks: () => [{ key: "production.afterComplete", handler: async (payload) => { ... } }]
+   */
+  setLogger(logger: { error: (obj: Record<string, unknown>, msg: string) => void }): void {
+    this.logger = logger;
+  }
+
+  async emit(key: string, payload: unknown): Promise<void> {
+    const handlers = this.resolve(key);
+    for (const handler of handlers) {
+      try {
+        await (handler as (payload: unknown) => unknown)(payload);
+      } catch (err) {
+        this.logger?.error(
+          { err, hookKey: key },
+          `Event handler failed for "${key}"`,
+        );
+      }
+    }
+  }
+
+  private ensureEntry(hookName: string): void {
+    if (!this.registry.has(hookName)) {
+      this.registry.set(hookName, {
+        prepended: [],
+        configured: [],
+        appended: [],
+      });
+    }
+  }
+}

package/src/kernel/hooks/types.ts

@@ -0,0 +1,52 @@
+import type { Actor } from "../../auth/types.js";
+import type { JobsAdapter } from "../jobs/adapter.js";
+import type { PluginDb } from "../database/plugin-types.js";
+
+export type HookOperation =
+  | "create"
+  | "update"
+  | "delete"
+  | "read"
+  | "list"
+  | "statusChange"
+  | "addItem"
+  | "removeItem"
+  | "custom";
+
+export interface Logger {
+  info(message: string, data?: unknown): void;
+  warn(message: string, data?: unknown): void;
+  error(message: string, data?: unknown): void;
+}
+
+export interface ServiceContainer {
+  [key: string]: unknown;
+}
+
+export type HookOrigin = "rest" | "local" | "mcp";
+
+export interface HookContext {
+  actor: Actor | null;
+  tx: unknown;
+  logger: Logger;
+  services: ServiceContainer;
+  context: Record<string, unknown>;
+  requestId: string;
+  origin: HookOrigin;
+  jobs: JobsAdapter;
+  /** Drizzle database instance. Fully typed — use directly for queries in hook handlers. */
+  db: PluginDb;
+}
+
+export type BeforeHook<TData> = (args: {
+  data: TData;
+  operation: HookOperation;
+  context: HookContext;
+}) => Promise<TData> | TData;
+
+export type AfterHook<TData> = (args: {
+  data: TData | null;
+  result: TData;
+  operation: HookOperation;
+  context: HookContext;
+}) => Promise<void> | void;

package/src/kernel/http-error.ts

@@ -0,0 +1,44 @@
+/**
+ * Converts a PluginResultErr into a structured HTTP error response.
+ *
+ * Replaces the `throw new Error(result.error)` pattern in plugin routes
+ * which always produces HTTP 500 with no structured error code.
+ *
+ * Usage in routes:
+ *   const result = await service.doSomething(orgId, input);
+ *   if (!result.ok) return toHttpError(result);
+ *   return result.value;
+ *
+ * The function infers HTTP status from the error code or message content:
+ *   - "NOT_FOUND" or "not found"        --> 404
+ *   - "FORBIDDEN" or "permission"        --> 403
+ *   - "CONFLICT" or "already exists"     --> 409
+ *   - "VALIDATION" or "cannot/must"      --> 422
+ *   - Everything else                    --> 400
+ */
+
+import type { PluginResultErr } from "./result.js";
+
+export interface HttpErrorResponse {
+  status: 400 | 403 | 404 | 409 | 422;
+  body: { error: { code: string; message: string } };
+}
+
+export function toHttpError(result: PluginResultErr): HttpErrorResponse {
+  const message = result.error;
+  const code = result.code;
+
+  if (code === "NOT_FOUND" || /not found/i.test(message)) {
+    return { status: 404, body: { error: { code: "NOT_FOUND", message } } };
+  }
+  if (code === "FORBIDDEN" || /permission|forbidden|unauthorized/i.test(message)) {
+    return { status: 403, body: { error: { code: "FORBIDDEN", message } } };
+  }
+  if (code === "CONFLICT" || /already|duplicate|exists|unique/i.test(message)) {
+    return { status: 409, body: { error: { code: "CONFLICT", message } } };
+  }
+  if (code === "VALIDATION" || /invalid|cannot|must|required|exceeded|negative/i.test(message)) {
+    return { status: 422, body: { error: { code: "VALIDATION_FAILED", message } } };
+  }
+  return { status: 400, body: { error: { code: code ?? "BAD_REQUEST", message } } };
+}

package/src/kernel/jobs/adapter.ts

@@ -0,0 +1,36 @@
+/**
+ * Minimal interface for enqueueing background jobs.
+ * The full DrizzleJobsAdapter implements this; hooks receive
+ * it on HookContext.jobs so they can defer work without caring
+ * about the underlying storage.
+ */
+export interface JobsAdapter {
+  enqueue(
+    taskSlug: string,
+    input: Record<string, unknown>,
+    options?: EnqueueOptions,
+  ): Promise<string>;
+}
+
+export interface EnqueueOptions {
+  queue?: string;
+  maxAttempts?: number;
+  delayMs?: number;
+  concurrencyKey?: string;
+  supersedes?: boolean;
+  organizationId?: string;
+}
+
+/**
+ * No-op adapter used when no jobs backend is configured.
+ * All enqueue calls silently succeed and return a placeholder ID.
+ */
+export class NullJobsAdapter implements JobsAdapter {
+  async enqueue(
+    _taskSlug: string,
+    _input: Record<string, unknown>,
+    _options?: EnqueueOptions,
+  ): Promise<string> {
+    return "null-job-id";
+  }
+}

package/src/kernel/jobs/drizzle-adapter.ts

@@ -0,0 +1,58 @@
+import { eq, and } from "drizzle-orm";
+import type { DrizzleDatabase } from "../database/drizzle-db.js";
+import type { TaskDefinition } from "./types.js";
+import type { JobsAdapter, EnqueueOptions } from "./adapter.js";
+import { DEFAULT_ORG_ID } from "../../auth/org.js";
+import { commerceJobs } from "./schema.js";
+
+/**
+ * PostgreSQL-backed job queue adapter using the application's own database.
+ * Stores jobs in the `commerce_jobs` table. Supports concurrency keys
+ * and supersede semantics for deduplication.
+ */
+export class DrizzleJobsAdapter implements JobsAdapter {
+  constructor(
+    private db: DrizzleDatabase,
+    private tasks: Map<string, TaskDefinition>,
+  ) {}
+
+  async enqueue(
+    taskSlug: string,
+    input: Record<string, unknown>,
+    options?: EnqueueOptions,
+  ): Promise<string> {
+    // If supersedes is set, delete existing pending jobs with the same concurrency key
+    if (options?.concurrencyKey && options.supersedes) {
+      await this.db
+        .delete(commerceJobs)
+        .where(
+          and(
+            eq(commerceJobs.concurrencyKey, options.concurrencyKey),
+            eq(commerceJobs.status, "pending"),
+          ),
+        );
+    }
+
+    // Look up task definition for default retry config
+    const task = this.tasks.get(taskSlug);
+    const maxAttempts =
+      options?.maxAttempts ?? task?.retries?.attempts ?? 1;
+
+    const rows = await this.db
+      .insert(commerceJobs)
+      .values({
+        organizationId: options?.organizationId ?? DEFAULT_ORG_ID,
+        taskSlug,
+        input,
+        queue: options?.queue ?? "default",
+        maxAttempts,
+        waitUntil: options?.delayMs
+          ? new Date(Date.now() + options.delayMs)
+          : null,
+        concurrencyKey: options?.concurrencyKey ?? null,
+      })
+      .returning({ id: commerceJobs.id });
+
+    return rows[0]!.id;
+  }
+}

package/src/kernel/jobs/runner.ts

@@ -0,0 +1,153 @@
+import { eq, and, sql } from "drizzle-orm";
+import type { DrizzleDatabase } from "../database/drizzle-db.js";
+import type { Logger, ServiceContainer } from "../hooks/types.js";
+import type { TaskDefinition } from "./types.js";
+import { commerceJobs } from "./schema.js";
+
+export interface RunPendingJobsArgs {
+  db: DrizzleDatabase;
+  tasks: Map<string, TaskDefinition>;
+  queue?: string;
+  limit?: number;
+  logger: Logger;
+  services: ServiceContainer;
+}
+
+/**
+ * Claims and processes pending jobs from the `commerce_jobs` table.
+ *
+ * Uses `FOR UPDATE SKIP LOCKED` to allow multiple runners to process
+ * jobs in parallel without conflicts. Each runner claims a batch,
+ * marks them as processing, then executes handlers outside the
+ * claim transaction.
+ */
+export async function runPendingJobs(
+  args: RunPendingJobsArgs,
+): Promise<{ processed: number; failed: number }> {
+  const {
+    db,
+    tasks,
+    queue = "default",
+    limit = 10,
+    logger,
+    services,
+  } = args;
+
+  let processed = 0;
+  let failed = 0;
+
+  // Phase 1: Claim jobs atomically
+  const claimed = await db.transaction(async (tx) => {
+    const pending = await tx
+      .select()
+      .from(commerceJobs)
+      .where(
+        and(
+          eq(commerceJobs.status, "pending"),
+          eq(commerceJobs.queue, queue),
+          sql`(${commerceJobs.waitUntil} IS NULL OR ${commerceJobs.waitUntil} <= now())`,
+        ),
+      )
+      .orderBy(commerceJobs.createdAt)
+      .limit(limit)
+      .for("update", { skipLocked: true });
+
+    for (const job of pending) {
+      await tx
+        .update(commerceJobs)
+        .set({
+          status: "processing",
+          processingStartedAt: new Date(),
+          updatedAt: new Date(),
+        })
+        .where(eq(commerceJobs.id, job.id));
+    }
+
+    return pending;
+  });
+
+  // Phase 2: Execute each claimed job outside the claim transaction
+  for (const job of claimed) {
+    const task = tasks.get(job.taskSlug);
+
+    if (!task) {
+      logger.warn("Unknown task slug — job marked as failed. Register the task handler in config.jobs.tasks.", {
+        taskSlug: job.taskSlug,
+        jobId: job.id,
+      });
+      await db
+        .update(commerceJobs)
+        .set({
+          status: "failed",
+          error: `Unknown task slug: ${job.taskSlug}`,
+          updatedAt: new Date(),
+          completedAt: new Date(),
+        })
+        .where(eq(commerceJobs.id, job.id));
+      failed++;
+      continue;
+    }
+
+    try {
+      const result = await task.handler({
+        input: job.input as Record<string, unknown>,
+        ctx: { logger, db, services },
+      });
+
+      await db
+        .update(commerceJobs)
+        .set({
+          status: "succeeded",
+          output: result.output,
+          attempts: job.attempts + 1,
+          updatedAt: new Date(),
+          completedAt: new Date(),
+        })
+        .where(eq(commerceJobs.id, job.id));
+
+      processed++;
+    } catch (err) {
+      logger.error("Job handler failed", {
+        taskSlug: job.taskSlug,
+        jobId: job.id,
+        error: err instanceof Error ? err.message : String(err),
+      });
+      const attempts = job.attempts + 1;
+      const maxAttempts = job.maxAttempts;
+
+      if (attempts >= maxAttempts) {
+        await db
+          .update(commerceJobs)
+          .set({
+            status: "failed",
+            error: err instanceof Error ? err.message : String(err),
+            attempts,
+            updatedAt: new Date(),
+            completedAt: new Date(),
+          })
+          .where(eq(commerceJobs.id, job.id));
+        failed++;
+      } else {
+        // Compute backoff delay
+        const retries = task.retries;
+        const delay =
+          retries?.backoff?.type === "exponential"
+            ? retries.backoff.delay * Math.pow(2, attempts - 1)
+            : (retries?.backoff?.delay ?? 1000);
+
+        await db
+          .update(commerceJobs)
+          .set({
+            status: "pending",
+            error: err instanceof Error ? err.message : String(err),
+            attempts,
+            waitUntil: new Date(Date.now() + delay),
+            updatedAt: new Date(),
+          })
+          .where(eq(commerceJobs.id, job.id));
+      }
+    }
+  }
+
+  return { processed, failed };
+}

package/src/kernel/jobs/schema.ts

@@ -0,0 +1,46 @@
+import {
+  pgTable,
+  uuid,
+  text,
+  jsonb,
+  integer,
+  timestamp,
+  index,
+} from "drizzle-orm/pg-core";
+import { organization } from "../../auth/auth-schema.js";
+
+export const commerceJobs = pgTable("commerce_jobs", {
+  id: uuid("id").primaryKey().defaultRandom(),
+  organizationId: text("organization_id")
+    .notNull()
+    .references(() => organization.id, { onDelete: "cascade" }),
+  queue: text("queue").notNull().default("default"),
+  taskSlug: text("task_slug").notNull(),
+  input: jsonb("input").notNull().default("{}"),
+  output: jsonb("output"),
+  status: text("status", {
+    enum: ["pending", "processing", "succeeded", "failed"],
+  })
+    .notNull()
+    .default("pending"),
+  attempts: integer("attempts").notNull().default(0),
+  maxAttempts: integer("max_attempts").notNull().default(1),
+  error: text("error"),
+  waitUntil: timestamp("wait_until", { withTimezone: true }),
+  concurrencyKey: text("concurrency_key"),
+  createdAt: timestamp("created_at", { withTimezone: true })
+    .notNull()
+    .defaultNow(),
+  updatedAt: timestamp("updated_at", { withTimezone: true })
+    .notNull()
+    .defaultNow(),
+  processingStartedAt: timestamp("processing_started_at", {
+    withTimezone: true,
+  }),
+  completedAt: timestamp("completed_at", { withTimezone: true }),
+}, (table) => ({
+  statusQueueIdx: index("idx_jobs_status_queue").on(table.status, table.queue),
+  taskSlugIdx: index("idx_jobs_task_slug").on(table.taskSlug),
+  waitUntilIdx: index("idx_jobs_wait_until").on(table.waitUntil),
+  orgIdx: index("idx_jobs_org").on(table.organizationId),
+}));

package/src/kernel/jobs/types.ts

@@ -0,0 +1,30 @@
+import type { Logger, ServiceContainer } from "../hooks/types.js";
+import type { DrizzleDatabase } from "../database/drizzle-db.js";
+
+export interface TaskContext {
+  logger: Logger;
+  db: DrizzleDatabase;
+  services: ServiceContainer;
+}
+
+export interface TaskRetryConfig {
+  attempts: number;
+  backoff?: { type: "fixed" | "exponential"; delay: number };
+}
+
+export interface TaskDefinition<
+  TInput extends Record<string, unknown> = Record<string, unknown>,
+  TOutput extends Record<string, unknown> = Record<string, unknown>,
+> {
+  slug: string;
+  handler: (args: {
+    input: TInput;
+    ctx: TaskContext;
+  }) => Promise<{ output: TOutput }>;
+  retries?: TaskRetryConfig;
+  concurrency?: {
+    key: (input: TInput) => string;
+    exclusive?: boolean;
+    supersedes?: boolean;
+  };
+}

package/src/kernel/local-api.ts

@@ -0,0 +1,187 @@
+import type { Actor } from "../auth/types.js";
+import type { Kernel } from "../runtime/kernel.js";
+import type { TxContext } from "./database/tx-context.js";
+
+/**
+ * Proxy-based Local API — the Payload-style programmatic interface.
+ *
+ * Automatically exposes EVERY service on `kernel.services` (core + plugins)
+ * without hardcoding method signatures. Uses a Proxy to intercept property
+ * access and wrap each service method to auto-inject `actor` and `txCtx`.
+ *
+ * ## Usage in Next.js / TanStack Start / SvelteKit:
+ *
+ * ```typescript
+ * import { createCommerce } from "@unifiedcommerce/core";
+ * import config from "./commerce.config.js";
+ *
+ * const commerce = await createCommerce(config);
+ *
+ * // Server action / loader — no HTTP round-trip
+ * const products = await commerce.api.catalog.list({ limit: 10 });
+ * const order = await commerce.api.orders.getById("order-123");
+ *
+ * // Plugin services are automatically available
+ * const balance = await commerce.api.giftCards.checkBalance("CARD-CODE");
+ * const points = await commerce.api.loyalty.redeemPoints("org", "cust", 100);
+ * ```
+ *
+ * ## Usage from a hook:
+ *
+ * ```typescript
+ * const api = createLocalAPI(kernel, { actor, tx });
+ * const product = await api.catalog.getById("prod-123");
+ * ```
+ *
+ * ## How it works:
+ *
+ * 1. `api.catalog` → Proxy intercepts, finds `kernel.services.catalog`
+ * 2. `api.catalog.getById(id)` → Proxy intercepts method call
+ * 3. Wraps the call: `kernel.services.catalog.getById(id, actor, txCtx)`
+ * 4. Returns the result directly — no HTTP, no serialization
+ *
+ * The Proxy auto-appends `actor` and `txCtx` to every method call.
+ * Service methods that accept `(actor, ctx)` as the last two params
+ * get them injected automatically. Methods that don't accept them
+ * still work — extra args are harmlessly ignored by JavaScript.
+ */
+
+// ─── Types ──────────────────────────────────────────────────────────────────
+
+/** Options for creating a local API instance */
+export interface LocalAPIOptions {
+  actor?: Actor | null;
+  tx?: unknown;
+  requestId?: string;
+}
+
+/**
+ * Maps a service type to strip actor/txCtx params from each method.
+ * Plugin authors get clean autocomplete: `api.catalog.create(input)`
+ * instead of `api.catalog.create(input, actor, txCtx)`.
+ */
+type CleanService<T> = {
+  [K in keyof T]: T[K] extends (...args: infer _A) => infer R
+    ? (...args: unknown[]) => R
+    : T[K];
+};
+
+/** The full local API type — all kernel services with cleaned signatures */
+export type CommerceLocalAPI<
+  TServices extends Record<string, unknown> = Kernel["services"],
+> = {
+  [K in keyof TServices]: TServices[K] extends Record<string, unknown>
+    ? CleanService<TServices[K]>
+    : TServices[K];
+};
+
+// ─── Implementation ─────────────────────────────────────────────────────────
+
+const SERVICE_METHOD_CACHE = new WeakMap<object, Map<string, Function>>();
+
+/**
+ * Create a proxy-based local API over kernel services.
+ * Every service method gets `actor` and `txCtx` auto-injected.
+ */
+export function createLocalAPI(
+  kernel: Kernel,
+  options: LocalAPIOptions = {},
+): CommerceLocalAPI {
+  const actor = options.actor ?? null;
+  const txCtx: TxContext | undefined =
+    options.tx != null
+      ? ({
+          tx: options.tx,
+          actor,
+          requestId: options.requestId ?? crypto.randomUUID(),
+        } as TxContext)
+      : undefined;
+
+  // Top-level proxy: intercept service access (e.g., api.catalog, api.giftCards)
+  // The Proxy transforms method signatures at runtime (auto-injecting actor/txCtx),
+  // so the cast from Kernel["services"] to CommerceLocalAPI is safe.
+  return new Proxy(kernel.services as CommerceLocalAPI, {
+    get(target, serviceName: string) {
+      const service = (target as Record<string, unknown>)[serviceName];
+
+      // Non-object services (e.g., email config) — return as-is
+      if (service == null || typeof service !== "object") {
+        return service;
+      }
+
+      // Method-level proxy: intercept method calls on the service
+      return new Proxy(service, {
+        get(svcTarget, methodName: string) {
+          const method = (svcTarget as Record<string, unknown>)[methodName];
+
+          if (typeof method !== "function") {
+            return method;
+          }
+
+          // Check cache to avoid re-creating wrapper functions
+          let methodCache = SERVICE_METHOD_CACHE.get(svcTarget as object);
+          if (!methodCache) {
+            methodCache = new Map();
+            SERVICE_METHOD_CACHE.set(svcTarget as object, methodCache);
+          }
+
+          const cacheKey = `${methodName}:${actor?.userId ?? "null"}`;
+          let cached = methodCache.get(cacheKey);
+          if (cached) return cached;
+
+          // Create wrapped method that auto-injects actor + txCtx
+          cached = (...args: unknown[]) => {
+            return (method as Function).call(svcTarget, ...args, actor, txCtx);
+          };
+
+          methodCache.set(cacheKey, cached);
+          return cached;
+        },
+      });
+    },
+  });
+}
+
+// ─── Legacy Class API (backward compat) ─────────────────────────────────────
+
+/**
+ * @deprecated Use `createLocalAPI(kernel, { actor, tx })` instead.
+ * Kept for backward compatibility with existing hook code.
+ */
+export class LocalAPI {
+  private _proxy: CommerceLocalAPI;
+
+  constructor(
+    ctx: { actor: Actor | null; tx: unknown; requestId: string },
+    kernel: Kernel,
+  ) {
+    this._proxy = createLocalAPI(kernel, {
+      actor: ctx.actor,
+      tx: ctx.tx,
+      requestId: ctx.requestId,
+    });
+  }
+
+  get orders() { return this._proxy.orders; }
+  get catalog() { return this._proxy.catalog; }
+  get cart() { return this._proxy.cart; }
+  get inventory() { return this._proxy.inventory; }
+  get customers() { return this._proxy.customers; }
+  get pricing() { return this._proxy.pricing; }
+  get promotions() { return this._proxy.promotions; }
+  get media() { return this._proxy.media; }
+  get shipping() { return this._proxy.shipping; }
+  get search() { return this._proxy.search; }
+  get webhooks() { return this._proxy.webhooks; }
+  get fulfillment() { return this._proxy.fulfillment; }
+  get payments() { return this._proxy.payments; }
+  get analytics() { return this._proxy.analytics; }
+  get tax() { return this._proxy.tax; }
+  get audit() { return this._proxy.audit; }
+  get organization() { return this._proxy.organization; }
+
+  /** Access any service (including plugins) by name */
+  service(name: string) {
+    return (this._proxy as Record<string, unknown>)[name];
+  }
+}