@unifiedcommerce/core 0.0.1

package/dist/test-utils/rest-api-test-utils.js

@@ -0,0 +1,207 @@
+/**
+ * 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";
+import { createAuth } from "../auth/setup";
+import { authMiddleware } from "../auth/middleware";
+import { createRestRoutes } from "../interfaces/rest";
+import { createPGliteTestConfig } from "./create-test-config";
+import { CommerceValidationError } from "../kernel/errors";
+import { Ok, Err } from "../kernel/result";
+const mockPaymentAdapter = {
+    providerId: "test-payments",
+    async createPaymentIntent(params) {
+        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) {
+        // Extract signature from headers
+        const signature = request.headers.get("stripe-signature") || request.headers.get("webhook-signature");
+        // Extract payload from request body
+        let payload;
+        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 ?? {}) });
+    },
+};
+/**
+ * Creates a test server with PGlite-backed kernel for REST API testing.
+ */
+export async function createTestServer(overrides = {}) {
+    const { config, cleanup } = await createPGliteTestConfig({
+        payments: [mockPaymentAdapter],
+        ...overrides,
+    });
+    const kernel = createKernel(config);
+    const auth = createAuth(kernel.database, config);
+    const app = new Hono();
+    // 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);
+                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");
+            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(response) {
+    return response.json();
+}
+/**
+ * Common test actor with staff permissions
+ */
+export const testActor = {
+    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 = {
+    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 = {
+    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, options) {
+    const url = new URL(options.url, "http://localhost");
+    const headers = {
+        "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 = {
+        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, options) {
+    // 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/dist/test-utils/test-actors.d.ts

@@ -0,0 +1,15 @@
+import type { Actor } from "../auth/types";
+/** Admin with wildcard permissions. Use for setup operations in beforeAll. */
+export declare const testAdminActor: Actor;
+/** Staff with common operational permissions. */
+export declare const testStaffActor: Actor;
+/** Customer with minimal read/write-own permissions. */
+export declare const testCustomerActor: Actor;
+/** Actor with zero permissions. Use for negative auth/perm tests. */
+export declare const testNoPermActor: Actor;
+/**
+ * Builds request headers with optional test actor injection.
+ * The x-test-actor header is parsed by createPluginTestApp's middleware.
+ */
+export declare function jsonHeaders(actor?: Actor): Record<string, string>;
+//# sourceMappingURL=test-actors.d.ts.map

package/dist/test-utils/test-actors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"test-actors.d.ts","sourceRoot":"","sources":["../../src/test-utils/test-actors.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,eAAe,CAAC;AAE3C,8EAA8E;AAC9E,eAAO,MAAM,cAAc,EAAE,KAS5B,CAAC;AAEF,iDAAiD;AACjD,eAAO,MAAM,cAAc,EAAE,KAY5B,CAAC;AAEF,wDAAwD;AACxD,eAAO,MAAM,iBAAiB,EAAE,KAS/B,CAAC;AAEF,qEAAqE;AACrE,eAAO,MAAM,eAAe,EAAE,KAS7B,CAAC;AAEF;;;GAGG;AACH,wBAAgB,WAAW,CAAC,KAAK,CAAC,EAAE,KAAK,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAIjE"}

package/dist/test-utils/test-actors.js

@@ -0,0 +1,57 @@
+/** Admin with wildcard permissions. Use for setup operations in beforeAll. */
+export const testAdminActor = {
+    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 = {
+    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 = {
+    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 = {
+    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) {
+    const headers = { "Content-Type": "application/json" };
+    if (actor)
+        headers["x-test-actor"] = JSON.stringify(actor);
+    return headers;
+}

package/dist/test-utils/typed-hooks.d.ts

@@ -0,0 +1,43 @@
+import type { PluginHookRegistration } from "../kernel/plugin/manifest";
+import type { HookContext, HookOperation } from "../kernel/hooks/types";
+/**
+ * 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 declare function beforeHook<TData>(key: string, handler: (args: {
+    data: TData;
+    operation: HookOperation;
+    context: HookContext;
+}) => Promise<TData> | TData): PluginHookRegistration;
+/**
+ * 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 declare function afterHook<TData>(key: string, handler: (args: {
+    data: TData | null;
+    result: TData;
+    operation: HookOperation;
+    context: HookContext;
+}) => Promise<void> | void): PluginHookRegistration;
+//# sourceMappingURL=typed-hooks.d.ts.map

package/dist/test-utils/typed-hooks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"typed-hooks.d.ts","sourceRoot":"","sources":["../../src/test-utils/typed-hooks.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,2BAA2B,CAAC;AACxE,OAAO,KAAK,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAExE;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAC9B,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,CAAC,IAAI,EAAE;IACd,IAAI,EAAE,KAAK,CAAC;IACZ,SAAS,EAAE,aAAa,CAAC;IACzB,OAAO,EAAE,WAAW,CAAC;CACtB,KAAK,OAAO,CAAC,KAAK,CAAC,GAAG,KAAK,GAC3B,sBAAsB,CAExB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAC7B,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,CAAC,IAAI,EAAE;IACd,IAAI,EAAE,KAAK,GAAG,IAAI,CAAC;IACnB,MAAM,EAAE,KAAK,CAAC;IACd,SAAS,EAAE,aAAa,CAAC;IACzB,OAAO,EAAE,WAAW,CAAC;CACtB,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,GACzB,sBAAsB,CAExB"}

package/dist/test-utils/typed-hooks.js

@@ -0,0 +1,35 @@
+/**
+ * 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(key, handler) {
+    return { key, handler: 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(key, handler) {
+    return { key, handler: handler };
+}