@unifiedcommerce/core 0.2.0 → 0.2.1

package/src/test-utils/create-repository-test-harness.ts

@@ -0,0 +1,16 @@
+import type { CommerceConfig } from "../config/types.js";
+import { createTestConfig } from "./create-test-config.js";
+import { createKernel } from "../runtime/kernel.js";
+
+export interface RepositoryTestHarness {
+  config: CommerceConfig;
+  kernel: ReturnType<typeof createKernel>;
+}
+
+export async function createRepositoryTestHarness(
+  overrides: Partial<CommerceConfig> = {},
+): Promise<RepositoryTestHarness> {
+  const config = await createTestConfig(overrides);
+  const kernel = createKernel(config);
+  return { config, kernel };
+}

package/src/test-utils/create-test-config.ts

@@ -0,0 +1,190 @@
+import { defineConfig } from "../config/define-config.js";
+import type { CommerceConfig } from "../config/types.js";
+import { Ok } from "../kernel/result.js";
+import type { StorageAdapter } from "../modules/media/adapter.js";
+
+function createInMemoryStorageAdapter(): StorageAdapter {
+  const files = new Map<string, { data: ArrayBuffer; contentType: string }>();
+  const baseUrl = "http://localhost:3000/test-assets";
+
+  return {
+    providerId: "test-memory-storage",
+    async upload(key, data, contentType) {
+      const body =
+        data instanceof ArrayBuffer
+          ? data
+          : await new Response(data).arrayBuffer();
+      files.set(key, { data: body, contentType });
+      return Ok({
+        key,
+        url: `${baseUrl}/${key}`,
+        contentType,
+        size: body.byteLength,
+      });
+    },
+    async getUrl(key) {
+      return Ok(`${baseUrl}/${key}`);
+    },
+    async getSignedUrl(key, expiresIn) {
+      return Ok(`${baseUrl}/${key}?expiresIn=${expiresIn}`);
+    },
+    async delete(key) {
+      files.delete(key);
+      return Ok(undefined);
+    },
+    async list(prefix) {
+      return Ok(
+        Array.from(files.entries())
+          .filter(([key]) => key.startsWith(prefix))
+          .map(([key, file]) => ({
+            key,
+            url: `${baseUrl}/${key}`,
+            contentType: file.contentType,
+            size: file.data.byteLength,
+          })),
+      );
+    },
+  };
+}
+
+export async function createTestConfig(
+  overrides: Partial<CommerceConfig> = {},
+): Promise<CommerceConfig> {
+  // Auto-provision PGlite when no databaseAdapter is provided
+  if (!overrides.databaseAdapter) {
+    const { createPGliteTestAdapter } = await import("./create-pglite-adapter.js");
+    const { adapter } = await createPGliteTestAdapter();
+    overrides = { ...overrides, databaseAdapter: adapter };
+  }
+
+  return defineConfig({
+    version: "0.0.1-test",
+    storeName: "Test Store",
+    database: {
+      provider: "postgresql",
+    },
+    auth: {
+      requireEmailVerification: false,
+      apiKeys: { enabled: true, defaultPermissions: ["catalog:read"] },
+      enableDevKey: true,
+      devKey: "dev-staff-key",
+      posPin: { enabled: true },
+      roles: {
+        owner: { permissions: ["*:*"] },
+        admin: { permissions: ["*:*"] },
+        staff: {
+          permissions: [
+            "catalog:create",
+            "catalog:update",
+            "catalog:delete",
+            "catalog:read",
+            "inventory:adjust",
+            "orders:create",
+            "orders:read",
+            "orders:update",
+            "cart:create",
+            "cart:update",
+            "customers:update:self",
+          ],
+        },
+        ai_agent: {
+          permissions: [
+            "catalog:read",
+            "catalog:create",
+            "inventory:read",
+            "inventory:adjust",
+            "orders:read",
+            "cart:create",
+            "cart:update",
+            "mcp:access",
+          ],
+        },
+      },
+      customerPermissions: [
+        "catalog:read",
+        "cart:create",
+        "cart:read",
+        "cart:update",
+        "orders:create",
+        "orders:read:own",
+        "customers:read:self",
+        "customers:update:self",
+      ],
+    },
+    entities: {
+      product: {
+        fields: [
+          { name: "weight", type: "number" },
+          { name: "brand", type: "text" },
+        ],
+        variants: { enabled: true, optionTypes: ["size", "color"] },
+        fulfillment: "physical",
+      },
+      digitalDownload: {
+        fields: [{ name: "fileAssetId", type: "text" }],
+        variants: { enabled: false },
+        fulfillment: "digital-download",
+      },
+      course: {
+        fields: [{ name: "modules", type: "json" }],
+        variants: { enabled: false },
+        fulfillment: "digital-access",
+      },
+    },
+    cart: {
+      ttlMinutes: 5,
+      hooks: {},
+    },
+    checkout: {
+      hooks: {
+        beforeCreate: [],
+        afterCreate: [],
+      },
+    },
+    orders: {
+      hooks: {
+        beforeCreate: [],
+        afterCreate: [],
+        beforeStatusChange: [],
+        afterStatusChange: [],
+      },
+    },
+    inventory: {
+      hooks: {
+        afterAdjust: [],
+      },
+    },
+    email: {
+      async send() {
+        // no-op for tests
+      },
+    },
+    storage: createInMemoryStorageAdapter(),
+    ...overrides,
+  });
+}
+
+/**
+ * Creates a test config backed by PGlite (in-memory PostgreSQL).
+ *
+ * This provides production parity for tests by using real SQL execution
+ * and PostgreSQL behavior while remaining fast and self-contained.
+ *
+ * @param overrides - Optional config overrides
+ * @returns A promise resolving to an object containing:
+ *   - config: The CommerceConfig to pass to createKernel
+ *   - cleanup: Async function to reset data between tests
+ */
+export async function createPGliteTestConfig(
+  overrides: Partial<CommerceConfig> = {},
+): Promise<{ config: CommerceConfig; cleanup: () => Promise<void> }> {
+  const { createPGliteTestAdapter } = await import("./create-pglite-adapter.js");
+  const { adapter, cleanup } = await createPGliteTestAdapter();
+
+  const config = await createTestConfig({
+    databaseAdapter: adapter,
+    ...overrides,
+  });
+
+  return { config, cleanup };
+}

package/src/test-utils/create-test-kernel.ts

@@ -0,0 +1,7 @@
+import type { CommerceConfig } from "../config/types.js";
+import { createKernel } from "../runtime/kernel.js";
+import { createTestConfig } from "./create-test-config.js";
+
+export async function createTestKernel(overrides: Partial<CommerceConfig> = {}) {
+  return createKernel(await createTestConfig(overrides));
+}

package/src/test-utils/create-test-plugin-context.ts

@@ -0,0 +1,75 @@
+import { HookRegistry } from "../kernel/hooks/registry.js";
+import { createLogger } from "../utils/logger.js";
+import { createTestConfig } from "./create-test-config.js";
+import type { CommerceConfig, MCPTool } from "../config/types.js";
+
+interface PluginContextShape {
+  hooks: HookRegistry;
+  config: CommerceConfig;
+  services: Record<string, unknown>;
+  routes: { add(method: string, path: string, handler: (...args: unknown[]) => unknown): void };
+  mcp: { registerTool(tool: MCPTool): void };
+  analytics: { registerModel(model: unknown): void };
+  database: {
+    registerSchema(schema: Record<string, unknown>): void;
+    query: unknown;
+    transaction<T>(fn: (tx: unknown) => Promise<T>): Promise<T>;
+  };
+  logger: { info(message: string, data?: unknown): void; warn(message: string, data?: unknown): void; error(message: string, data?: unknown): void };
+}
+
+export interface TestPluginContext extends PluginContextShape {
+  registeredRoutes: Array<{ method: string; path: string; handler: (...args: unknown[]) => unknown }>;
+  registeredMCPTools: MCPTool[];
+  registeredAnalyticsModels: unknown[];
+  registeredSchemas: Array<Record<string, unknown>>;
+}
+
+export async function createTestPluginContext(options?: {
+  config?: Partial<CommerceConfig>;
+  services?: Record<string, unknown>;
+}): Promise<TestPluginContext> {
+  const hooks = new HookRegistry();
+  const config = await createTestConfig(options?.config ?? {});
+  const services = options?.services ?? {};
+
+  const registeredRoutes: TestPluginContext["registeredRoutes"] = [];
+  const registeredMCPTools: MCPTool[] = [];
+  const registeredAnalyticsModels: unknown[] = [];
+  const registeredSchemas: Array<Record<string, unknown>> = [];
+
+  return {
+    hooks,
+    config,
+    services,
+    routes: {
+      add(method, path, handler) {
+        registeredRoutes.push({ method: method.toUpperCase(), path, handler });
+      },
+    },
+    mcp: {
+      registerTool(tool) {
+        registeredMCPTools.push(tool);
+      },
+    },
+    analytics: {
+      registerModel(model) {
+        registeredAnalyticsModels.push(model);
+      },
+    },
+    database: {
+      registerSchema(schema) {
+        registeredSchemas.push(schema);
+      },
+      query: {},
+      async transaction<T>(fn: (tx: unknown) => Promise<T>): Promise<T> {
+        return fn({});
+      },
+    },
+    logger: createLogger("test-plugin-context"),
+    registeredRoutes,
+    registeredMCPTools,
+    registeredAnalyticsModels,
+    registeredSchemas,
+  };
+}

package/src/test-utils/rest-api-test-utils.ts

@@ -0,0 +1,265 @@
+/**
+ * Integration test utilities for REST API endpoints.
+ *
+ * Provides helper functions to test Hono routes with a real kernel,
+ * PGlite database, and authentication middleware.
+ */
+
+import { Hono } from "hono";
+import { createKernel } from "../runtime/kernel.js";
+import { createAuth } from "../auth/setup.js";
+import { authMiddleware } from "../auth/middleware.js";
+import { createRestRoutes } from "../interfaces/rest/index.js";
+import { createPGliteTestConfig } from "./create-test-config.js";
+import { CommerceValidationError } from "../kernel/errors.js";
+import { Ok, Err } from "../kernel/result.js";
+import type { CommerceConfig } from "../config/types.js";
+import type { Actor } from "../auth/types.js";
+import type { AuthInstance } from "../auth/setup.js";
+
+type ServerEnv = {
+  Variables: {
+    auth: AuthInstance;
+    actor: Actor | null;
+  };
+};
+
+const mockPaymentAdapter = {
+  providerId: "test-payments",
+  async createPaymentIntent(params: { amount: number; currency: string }) {
+    return Ok({
+      id: "pi_test_" + Date.now(),
+      status: "requires_capture",
+      amount: params.amount,
+      currency: params.currency,
+      clientSecret: "secret_test",
+    });
+  },
+  async capturePayment() {
+    return Ok({ id: "pi_test_" + Date.now(), status: "succeeded", amountCaptured: 1000 });
+  },
+  async refundPayment() {
+    return Ok({ id: "re_test_" + Date.now(), status: "succeeded", amountRefunded: 1000 });
+  },
+  async cancelPaymentIntent() {
+    return Ok(undefined);
+  },
+  async verifyWebhook(request: Request) {
+    // Extract signature from headers
+    const signature = request.headers.get("stripe-signature") || request.headers.get("webhook-signature");
+
+    // Extract payload from request body
+    let payload: Record<string, unknown> | undefined;
+    try {
+      payload = await request.clone().json();
+    } catch {
+      return Err(new CommerceValidationError("Webhook payload is invalid or missing"));
+    }
+
+    // Simulate signature verification for production-hardened testing
+    // Reject invalid signatures like "invalid_signature"
+    if (signature === "invalid_signature") {
+      return Err(new CommerceValidationError("Invalid webhook signature"));
+    }
+
+    // Reject requests with no required fields
+    if (!payload || !payload.type) {
+      return Err(new CommerceValidationError("Webhook payload is missing required fields"));
+    }
+
+    return Ok({ id: "evt_test_" + Date.now(), type: String(payload.type), data: (payload.data ?? {}) as unknown });
+  },
+};
+
+/**
+ * Creates a test server with PGlite-backed kernel for REST API testing.
+ */
+export async function createTestServer(
+  overrides: Partial<CommerceConfig> = {},
+): Promise<{
+  server: Hono<ServerEnv>;
+  kernel: ReturnType<typeof createKernel>;
+  auth: AuthInstance;
+  cleanup: () => Promise<void>;
+}> {
+  const { config, cleanup } = await createPGliteTestConfig({
+    payments: [mockPaymentAdapter],
+    ...overrides,
+  });
+
+  const kernel = createKernel(config);
+  const auth = createAuth(kernel.database, config);
+  const app = new Hono<ServerEnv>();
+
+  // Set auth in context (like createServer does)
+  app.use("*", async (c, next) => {
+    c.set("auth", auth);
+    await next();
+  });
+
+  // Test middleware: allow direct actor injection via x-test-actor header for testing
+  app.use("*", async (c, next) => {
+    const testActorHeader = c.req.header("x-test-actor");
+    if (testActorHeader) {
+      try {
+        const actor = JSON.parse(testActorHeader) as Actor;
+        c.set("actor", actor);
+        await next();
+        return;
+      } catch {
+        // Invalid JSON, continue to auth middleware
+      }
+    }
+    await next();
+  });
+
+  // Add auth middleware
+  app.use("*", authMiddleware(auth, config));
+
+  // Error handling middleware - catch thrown errors and convert to JSON
+  app.use("*", async (c, next) => {
+    try {
+      await next();
+    } catch (error) {
+      // Import error handling utilities
+      const { mapErrorToResponse, mapErrorToStatus } = await import("../interfaces/rest/utils.js");
+      return c.json(
+        mapErrorToResponse(error),
+        mapErrorToStatus(error),
+      );
+    }
+  });
+
+  // Add REST routes
+  app.route("/api", createRestRoutes(kernel));
+
+  return { server: app, kernel, auth, cleanup };
+}
+
+/**
+ * Helper to parse JSON response from Hono Response
+ */
+export async function parseJsonResponse<T = unknown>(response: Response): Promise<T> {
+  return response.json() as Promise<T>;
+}
+
+/**
+ * Common test actor with staff permissions
+ */
+export const testActor: Actor = {
+  type: "user",
+  userId: "00000000-0000-0000-0000-000000000001",
+  email: "test@example.com",
+  name: "Test Staff",
+  vendorId: null,
+  organizationId: "org_default",
+  role: "staff",
+  permissions: [
+    "catalog:create",
+    "catalog:update",
+    "catalog:read",
+    "inventory:adjust",
+    "inventory:read",
+    "orders:create",
+    "orders:read",
+    "orders:update",
+    "cart:create",
+    "cart:update",
+    "cart:read",
+    "customers:update:self",
+    "webhooks:manage",
+    "pricing:manage",
+    "promotions:manage",
+    "promotions:read",
+    "audit:read",
+    "media:write",
+  ],
+};
+
+/**
+ * Test actor with read-only permissions
+ */
+export const readonlyActor: Actor = {
+  type: "user",
+  userId: "00000000-0000-0000-0000-000000000002",
+  email: "readonly@example.com",
+  name: "Read Only User",
+  vendorId: null,
+  organizationId: "org_default",
+  role: "customer",
+  permissions: ["catalog:read", "cart:read", "orders:read:own"],
+};
+
+/**
+ * Test actor with no permissions
+ */
+export const noPermActor: Actor = {
+  type: "user",
+  userId: "00000000-0000-0000-0000-000000000003",
+  email: "noperm@example.com",
+  name: "No Perm",
+  vendorId: null,
+  organizationId: "org_default",
+  role: "customer",
+  permissions: [],
+};
+
+/**
+ * Helper to create a mock request with actor context
+ */
+export function createMockRequest(server: Hono<ServerEnv>, options: {
+  method: string;
+  url: string;
+  body?: unknown;
+  headers?: Record<string, string>;
+  actor?: Actor;
+}) {
+  const url = new URL(options.url, "http://localhost");
+
+  const headers: Record<string, string> = {
+    "content-type": "application/json",
+    ...options.headers,
+  };
+
+  // Add actor as header for test middleware
+  if (options.actor) {
+    headers["x-test-actor"] = JSON.stringify(options.actor);
+  }
+
+  // Build the request
+  const requestInit: RequestInit = {
+    method: options.method,
+    headers,
+  };
+  if (options.body) {
+    requestInit.body = JSON.stringify(options.body);
+  }
+  const request = new Request(url, requestInit);
+
+  return request;
+}
+
+/**
+ * Helper to make authenticated requests to the test server
+ */
+export async function makeRequest(
+  server: Hono<ServerEnv>,
+  options: {
+    method: string;
+    url: string;
+    body?: unknown;
+    headers?: Record<string, string>;
+    actor?: Actor;
+  },
+) {
+  // Create request with actor header (defaults to testActor)
+  const request = createMockRequest(server, {
+    ...options,
+    actor: options.actor ?? testActor,
+  });
+
+  // Route the request through Hono
+  const response = await server.fetch(request);
+
+  return response;
+}

package/src/test-utils/test-actors.ts

@@ -0,0 +1,62 @@
+import type { Actor } from "../auth/types.js";
+
+/** Admin with wildcard permissions. Use for setup operations in beforeAll. */
+export const testAdminActor: Actor = {
+  type: "user",
+  userId: "test-admin-1",
+  email: "admin@test.local",
+  name: "Test Admin",
+  vendorId: null,
+  organizationId: "org_default",
+  role: "admin",
+  permissions: ["*:*"],
+};
+
+/** Staff with common operational permissions. */
+export const testStaffActor: Actor = {
+  type: "user",
+  userId: "test-staff-1",
+  email: "staff@test.local",
+  name: "Test Staff",
+  vendorId: null,
+  organizationId: "org_default",
+  role: "staff",
+  permissions: [
+    "catalog:read", "catalog:create", "catalog:update",
+    "inventory:adjust", "orders:read", "orders:create", "orders:update",
+  ],
+};
+
+/** Customer with minimal read/write-own permissions. */
+export const testCustomerActor: Actor = {
+  type: "user",
+  userId: "test-customer-1",
+  email: "customer@test.local",
+  name: "Test Customer",
+  vendorId: null,
+  organizationId: "org_default",
+  role: "customer",
+  permissions: ["catalog:read", "cart:create", "cart:read", "orders:read:own"],
+};
+
+/** Actor with zero permissions. Use for negative auth/perm tests. */
+export const testNoPermActor: Actor = {
+  type: "user",
+  userId: "test-noperm-1",
+  email: "noperm@test.local",
+  name: "No Permissions",
+  vendorId: null,
+  organizationId: "org_default",
+  role: "customer",
+  permissions: [],
+};
+
+/**
+ * Builds request headers with optional test actor injection.
+ * The x-test-actor header is parsed by createPluginTestApp's middleware.
+ */
+export function jsonHeaders(actor?: Actor): Record<string, string> {
+  const headers: Record<string, string> = { "Content-Type": "application/json" };
+  if (actor) headers["x-test-actor"] = JSON.stringify(actor);
+  return headers;
+}

package/src/test-utils/typed-hooks.ts

@@ -0,0 +1,54 @@
+import type { PluginHookRegistration } from "../kernel/plugin/manifest.js";
+import type { HookContext, HookOperation } from "../kernel/hooks/types.js";
+
+/**
+ * Creates a typed before-hook registration for plugins.
+ *
+ * Narrows the handler signature from the loose `(...args: unknown[]) => unknown`
+ * on PluginHookRegistration to the actual `{ data, operation, context }` shape,
+ * providing autocomplete on context.jobs.enqueue(), context.logger.info(), etc.
+ *
+ * @example
+ * ```typescript
+ * hooks: () => [
+ *   beforeHook<{ customerId: string }>("orders.beforeCreate", async ({ data, context }) => {
+ *     context.logger.info("order_creating", { customerId: data.customerId });
+ *     return data;
+ *   }),
+ * ],
+ * ```
+ */
+export function beforeHook<TData>(
+  key: string,
+  handler: (args: {
+    data: TData;
+    operation: HookOperation;
+    context: HookContext;
+  }) => Promise<TData> | TData,
+): PluginHookRegistration {
+  return { key, handler: handler as PluginHookRegistration["handler"] };
+}
+
+/**
+ * Creates a typed after-hook registration for plugins.
+ *
+ * @example
+ * ```typescript
+ * hooks: () => [
+ *   afterHook<{ id: string; grandTotal: number }>("orders.afterCreate", async ({ result, context }) => {
+ *     await context.jobs.enqueue("loyalty:award-points", { orderId: result.id });
+ *   }),
+ * ],
+ * ```
+ */
+export function afterHook<TData>(
+  key: string,
+  handler: (args: {
+    data: TData | null;
+    result: TData;
+    operation: HookOperation;
+    context: HookContext;
+  }) => Promise<void> | void,
+): PluginHookRegistration {
+  return { key, handler: handler as PluginHookRegistration["handler"] };
+}