@unifiedcommerce/core 0.4.4 → 0.5.0

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

@@ -0,0 +1,15 @@
+import type { Actor } from "../auth/types.js";
+/** 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,kBAAkB,CAAC;AAE9C,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.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 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,8BAA8B,CAAC;AAC3E,OAAO,KAAK,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAE3E;;;;;;;;;;;;;;;;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 };
+}

package/dist/testing.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Test utilities for UnifiedCommerce plugins and apps.
+ *
+ * Import from "@unifiedcommerce/core/testing" — NOT from "@unifiedcommerce/core".
+ * This sub-path is isolated from the main barrel to avoid pulling drizzle-kit,
+ * tsx, esbuild, and other heavy dev-only deps into bundlers like Turbopack.
+ */
+export { createTestKernel } from "./test-utils/create-test-kernel.js";
+export { createTestPluginContext } from "./test-utils/create-test-plugin-context.js";
+export { createRepositoryTestHarness } from "./test-utils/create-repository-test-harness.js";
+export { createPluginTestApp, type PluginTestApp, type TestAppEnv } from "./test-utils/create-plugin-test-app.js";
+export { testAdminActor, testStaffActor, testCustomerActor, testNoPermActor, jsonHeaders, } from "./test-utils/test-actors.js";
+export { beforeHook, afterHook } from "./test-utils/typed-hooks.js";
+//# sourceMappingURL=testing.d.ts.map

package/dist/testing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"testing.d.ts","sourceRoot":"","sources":["../src/testing.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,gBAAgB,EAAE,MAAM,oCAAoC,CAAC;AACtE,OAAO,EAAE,uBAAuB,EAAE,MAAM,4CAA4C,CAAC;AACrF,OAAO,EAAE,2BAA2B,EAAE,MAAM,gDAAgD,CAAC;AAC7F,OAAO,EAAE,mBAAmB,EAAE,KAAK,aAAa,EAAE,KAAK,UAAU,EAAE,MAAM,wCAAwC,CAAC;AAClH,OAAO,EACL,cAAc,EAAE,cAAc,EAAE,iBAAiB,EAAE,eAAe,EAClE,WAAW,GACZ,MAAM,6BAA6B,CAAC;AACrC,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,6BAA6B,CAAC"}

package/dist/testing.js

@@ -0,0 +1,13 @@
+/**
+ * Test utilities for UnifiedCommerce plugins and apps.
+ *
+ * Import from "@unifiedcommerce/core/testing" — NOT from "@unifiedcommerce/core".
+ * This sub-path is isolated from the main barrel to avoid pulling drizzle-kit,
+ * tsx, esbuild, and other heavy dev-only deps into bundlers like Turbopack.
+ */
+export { createTestKernel } from "./test-utils/create-test-kernel.js";
+export { createTestPluginContext } from "./test-utils/create-test-plugin-context.js";
+export { createRepositoryTestHarness } from "./test-utils/create-repository-test-harness.js";
+export { createPluginTestApp } from "./test-utils/create-plugin-test-app.js";
+export { testAdminActor, testStaffActor, testCustomerActor, testNoPermActor, jsonHeaders, } from "./test-utils/test-actors.js";
+export { beforeHook, afterHook } from "./test-utils/typed-hooks.js";

package/dist/types/commerce-types.d.ts

@@ -0,0 +1,34 @@
+import type { sellableEntities } from "../modules/catalog/schema.js";
+import type { orders } from "../modules/orders/schema.js";
+import type { carts } from "../modules/cart/schema.js";
+import type { customers } from "../modules/customers/schema.js";
+import type { inventoryLevels } from "../modules/inventory/schema.js";
+/**
+ * Central type map for all commerce entities.
+ *
+ * Plugins can augment this interface via TypeScript module augmentation:
+ *
+ * ```typescript
+ * declare module "@unifiedcommerce/core" {
+ *   interface CommerceModuleTypes {
+ *     LoyaltyPoints: {
+ *       id: string;
+ *       customerId: string;
+ *       points: number;
+ *       tier: "bronze" | "silver" | "gold";
+ *     };
+ *   }
+ * }
+ * ```
+ *
+ * This enables plugin types to be referenced without importing
+ * internal schema modules.
+ */
+export interface CommerceModuleTypes {
+    Product: typeof sellableEntities.$inferSelect;
+    Order: typeof orders.$inferSelect;
+    Cart: typeof carts.$inferSelect;
+    Customer: typeof customers.$inferSelect;
+    InventoryLevel: typeof inventoryLevels.$inferSelect;
+}
+//# sourceMappingURL=commerce-types.d.ts.map

package/dist/types/commerce-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"commerce-types.d.ts","sourceRoot":"","sources":["../../src/types/commerce-types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,8BAA8B,CAAC;AACrE,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,6BAA6B,CAAC;AAC1D,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,2BAA2B,CAAC;AACvD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gCAAgC,CAAC;AAChE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,gCAAgC,CAAC;AAEtE;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,OAAO,gBAAgB,CAAC,YAAY,CAAC;IAC9C,KAAK,EAAE,OAAO,MAAM,CAAC,YAAY,CAAC;IAClC,IAAI,EAAE,OAAO,KAAK,CAAC,YAAY,CAAC;IAChC,QAAQ,EAAE,OAAO,SAAS,CAAC,YAAY,CAAC;IACxC,cAAc,EAAE,OAAO,eAAe,CAAC,YAAY,CAAC;CACrD"}

package/dist/types/commerce-types.js

@@ -0,0 +1 @@
+export {};

package/dist/utils/id.d.ts

@@ -0,0 +1,2 @@
+export declare function makeId(): string;
+//# sourceMappingURL=id.d.ts.map

package/dist/utils/id.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"id.d.ts","sourceRoot":"","sources":["../../src/utils/id.ts"],"names":[],"mappings":"AAAA,wBAAgB,MAAM,IAAI,MAAM,CAE/B"}

package/dist/utils/id.js

@@ -0,0 +1,3 @@
+export function makeId() {
+    return crypto.randomUUID();
+}

package/dist/utils/logger.d.ts

@@ -0,0 +1,3 @@
+import type { Logger } from "../kernel/hooks/types.js";
+export declare function createLogger(scope: string): Logger;
+//# sourceMappingURL=logger.d.ts.map

package/dist/utils/logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../../src/utils/logger.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,0BAA0B,CAAC;AAEvD,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAelD"}

package/dist/utils/logger.js

@@ -0,0 +1,16 @@
+export function createLogger(scope) {
+    return {
+        info(message, data) {
+            // eslint-disable-next-line no-console
+            console.info(`[${scope}] ${message}`, data ?? "");
+        },
+        warn(message, data) {
+            // eslint-disable-next-line no-console
+            console.warn(`[${scope}] ${message}`, data ?? "");
+        },
+        error(message, data) {
+            // eslint-disable-next-line no-console
+            console.error(`[${scope}] ${message}`, data ?? "");
+        },
+    };
+}

package/dist/utils/pagination.d.ts

@@ -0,0 +1,11 @@
+export interface Pagination {
+    page: number;
+    limit: number;
+    total: number;
+    totalPages: number;
+}
+export declare function paginate<T>(items: T[], page: number, limit: number): {
+    items: T[];
+    pagination: Pagination;
+};
+//# sourceMappingURL=pagination.d.ts.map

package/dist/utils/pagination.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pagination.d.ts","sourceRoot":"","sources":["../../src/utils/pagination.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,wBAAgB,QAAQ,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG;IAAE,KAAK,EAAE,CAAC,EAAE,CAAC;IAAC,UAAU,EAAE,UAAU,CAAA;CAAE,CAc3G"}

package/dist/utils/pagination.js

@@ -0,0 +1,15 @@
+export function paginate(items, page, limit) {
+    const safeLimit = Math.max(1, limit);
+    const safePage = Math.max(1, page);
+    const start = (safePage - 1) * safeLimit;
+    const sliced = items.slice(start, start + safeLimit);
+    return {
+        items: sliced,
+        pagination: {
+            page: safePage,
+            limit: safeLimit,
+            total: items.length,
+            totalPages: Math.max(1, Math.ceil(items.length / safeLimit)),
+        },
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unifiedcommerce/core",
-  "version": "0.4.4",
+  "version": "0.5.0",
   "type": "module",
   "exports": {
     ".": {
@@ -37,7 +37,7 @@
   "scripts": {
     "generate:plugins": "node ./scripts/generate-plugin-types.mjs",
     "check:store-guard": "node ./scripts/check-store-guard.mjs",
-    "build": "npm run generate:plugins && npm run check:store-guard && tsc -p tsconfig.build.json",
+    "build": "rm -rf dist tsconfig.build.tsbuildinfo && npm run generate:plugins && npm run check:store-guard && tsc -p tsconfig.build.json",
     "check-types": "npm run generate:plugins && npm run check:store-guard && tsc --noEmit",
     "lint": "eslint . --max-warnings 1000",
     "test": "vitest run"

package/src/auth/setup.ts

@@ -105,6 +105,32 @@ export function createAuth(
         provider: resolveAuthDbProvider(db.provider),
         schema: authSchema,
       }),
+      databaseHooks: {
+        user: {
+          create: {
+            after: async (user: { id: string; email?: string | null; name?: string | null }) => {
+              // Auto-create customer record on signup. Uses the Drizzle db
+              // directly because the kernel isn't fully initialized yet during
+              // auth setup. Best-effort — getByUserId() lazy-creates as fallback.
+              try {
+                const { customers } = await import("../kernel/database/schema.js");
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                const drizzle = db.db as any;
+                await drizzle.insert(customers).values({
+                  organizationId: "org_default",
+                  userId: user.id,
+                  email: user.email ?? null,
+                  firstName: user.name?.split(" ")[0] ?? null,
+                  lastName: user.name?.split(" ").slice(1).join(" ") ?? null,
+                  metadata: {},
+                }).onConflictDoNothing();
+              } catch {
+                // Silent — lazy creation in getByUserId() is the fallback
+              }
+            },
+          },
+        },
+      },
       trustedOrigins: config.auth?.trustedOrigins ?? [],
       emailAndPassword: {
         enabled: true,

package/src/interfaces/rest/routes/customers.ts

@@ -7,11 +7,15 @@ import {
   getCustomerOrdersRoute,
   getCustomerAddressesRoute,
 } from "../schemas/customers.js";
-import { type AppEnv, mapErrorToResponse, mapErrorToStatus, parsePagination } from "../utils.js";
+import { type AppEnv, mapErrorToResponse, mapErrorToStatus, parsePagination, requirePerm } from "../utils.js";
 
 export function customerRoutes(kernel: Kernel) {
   const router = new OpenAPIHono<AppEnv>();
 
+  // All customer admin routes require authentication + customers:read
+  router.use("/*", requirePerm("customers:read"));
+  router.use("/", requirePerm("customers:read"));
+
   // @ts-expect-error -- openapi handler union return type
   router.openapi(listCustomersRoute, async (c) => {
     const actor = c.get("actor");
@@ -42,6 +46,8 @@ export function customerRoutes(kernel: Kernel) {
     return c.json({ data: result.value });
   });
 
+  // PATCH requires customers:update (checked in handler since middleware can't distinguish methods)
+
   // @ts-expect-error -- openapi handler union return type
   router.openapi(updateCustomerRoute, async (c) => {
     const { id } = c.req.valid("param");

package/src/interfaces/rest/routes/inventory.ts

@@ -9,11 +9,14 @@ import {
   listWarehousesRoute,
   listInventoryLevelsRoute,
 } from "../schemas/inventory.js";
-import { type AppEnv, mapErrorToResponse, mapErrorToStatus } from "../utils.js";
+import { type AppEnv, mapErrorToResponse, mapErrorToStatus, requirePerm } from "../utils.js";
 
 export function inventoryRoutes(kernel: Kernel) {
   const router = new OpenAPIHono<AppEnv>();
 
+  // Inventory levels listing requires inventory:read
+  router.use("/levels", requirePerm("inventory:read"));
+
   // @ts-expect-error -- openapi handler union return type
   router.openapi(listInventoryLevelsRoute, async (c) => {
     const actor = c.get("actor");

package/src/interfaces/rest/routes/promotions.ts

@@ -1,7 +1,8 @@
 import { OpenAPIHono } from "@hono/zod-openapi";
 import { rateLimiter } from "hono-rate-limiter";
 import type { Kernel } from "../../../runtime/kernel.js";
-import { createPromotionRoute, validatePromotionRoute, deactivatePromotionRoute, listActivePromotionsRoute } from "../schemas/promotions.js";
+import { createPromotionRoute, validatePromotionRoute, deactivatePromotionRoute, listPromotionsRoute } from "../schemas/promotions.js";
+import type { PromotionStatusFilter } from "../../../modules/promotions/service.js";
 import { type AppEnv, mapErrorToResponse, mapErrorToStatus, requirePerm } from "../utils.js";
 import { resolveOrgId } from "../../../auth/org.js";
 
@@ -37,17 +38,19 @@ export function promotionRoutes(kernel: Kernel) {
     return c.json({ data: result.value }, 201);
   });
 
-  // List active promotions — requires auth
-  router.use("/active", requirePerm("promotions:read"));
-
+  // List promotions — supports ?status= filter (active/inactive/expired/scheduled)
   // @ts-expect-error -- openapi handler union return type
-  router.openapi(listActivePromotionsRoute, async (_c) => {
-    const actor = _c.get("actor");
-    const result = await kernel.services.promotions.listActive(actor);
+  router.openapi(listPromotionsRoute, async (c) => {
+    const actor = c.get("actor");
+    const status = c.req.query("status") as PromotionStatusFilter | undefined;
+    const result = await kernel.services.promotions.list(
+      status ? { status } : undefined,
+      actor,
+    );
     if (!result.ok) {
-      return _c.json(mapErrorToResponse(result.error), mapErrorToStatus(result.error));
+      return c.json(mapErrorToResponse(result.error), mapErrorToStatus(result.error));
     }
-    return _c.json({ data: result.value });
+    return c.json({ data: result.value });
   });
 
   // @ts-expect-error -- openapi() enforces strict response typing but our handler

package/src/interfaces/rest/schemas/promotions.ts

@@ -35,15 +35,21 @@ const PromotionIdParam = z.object({
 
 // ─── Route Definitions ──────────────────────────────────────────────────────
 
-export const listActivePromotionsRoute = createRoute({
+export const listPromotionsRoute = createRoute({
   method: "get",
   path: "/",
   tags: ["Promotions"],
-  summary: "List active promotions",
+  summary: "List promotions",
+  description: "Lists promotions. Filter by status: active (currently valid), inactive (deactivated), expired (past validUntil), scheduled (future validFrom). Omit status to return all.",
+  request: {
+    query: z.object({
+      status: z.enum(["active", "inactive", "expired", "scheduled"]).optional().openapi({ example: "active" }),
+    }),
+  },
   responses: {
     200: {
-      content: { "application/json": { schema: PromotionResponseSchema } },
-      description: "Active promotions",
+      content: { "application/json": { schema: z.object({ data: z.array(z.record(z.string(), z.unknown())) }) } },
+      description: "Promotions list",
     },
   },
 });

package/src/modules/catalog/service.ts

@@ -120,6 +120,7 @@ export interface CatalogEntityHydrated extends SellableEntity {
   categories?: EntityCategory[];
   brands?: EntityBrand[];
   media?: Array<{ mediaAssetId: string; role: string; variantId?: string }>;
+  pricing?: Array<{ currency: string; amount: number; compareAtAmount?: number | null }>;
 }
 
 export interface CatalogService {
@@ -482,6 +483,24 @@ export class CatalogServiceImpl implements CatalogService {
       hydrated.media = [];
     }
 
+    if (options?.includePricing) {
+      try {
+        const pricingService = this.deps.services.pricing as {
+          listPrices: (filter: { entityId: string }) => Promise<{ ok: boolean; value?: { prices: Array<{ currency: string; amount: number; compareAtAmount?: number | null }> } }>;
+        };
+        const priceResult = await pricingService.listPrices({ entityId: entity.id });
+        if (priceResult.ok && priceResult.value) {
+          hydrated.pricing = priceResult.value.prices.map((p) => ({
+            currency: p.currency,
+            amount: p.amount,
+            compareAtAmount: p.compareAtAmount ?? null,
+          }));
+        }
+      } catch {
+        // Pricing service may not be initialized — leave pricing undefined
+      }
+    }
+
     return hydrated;
   }
 

package/src/modules/promotions/service.ts

@@ -23,6 +23,9 @@ export type PromotionType =
   | "free_shipping"
   | "buy_x_get_y";
 
+/** Filter status for listing promotions. Used by the REST API and service layer. */
+export type PromotionStatusFilter = "active" | "inactive" | "expired" | "scheduled";
+
 interface PromotionServiceDeps {
   repository: PromotionsRepository;
   catalogRepository: CatalogRepository;
@@ -222,6 +225,35 @@ export class PromotionService {
     return Ok(updated);
   }
 
+  async list(
+    filter?: { status?: PromotionStatusFilter },
+    actor?: Actor | null,
+    ctx?: TxContext,
+  ): Promise<Result<Promotion[]>> {
+    const orgId = resolveOrgId(actor ?? ctx?.actor ?? null);
+    const all = await this.repo.findAll(orgId, ctx);
+    const now = new Date();
+
+    if (!filter?.status) return Ok(sortByPriority(all));
+
+    const filtered = all.filter((p) => {
+      const isActive = p.isActive && matchesWindow(p, now);
+      const isExpired = p.isActive && p.validUntil && new Date(p.validUntil) < now;
+      const isScheduled = p.isActive && p.validFrom && new Date(p.validFrom) > now;
+      const isInactive = !p.isActive;
+
+      switch (filter.status) {
+        case "active": return isActive;
+        case "inactive": return isInactive;
+        case "expired": return isExpired;
+        case "scheduled": return isScheduled;
+        default: return true;
+      }
+    });
+
+    return Ok(sortByPriority(filtered));
+  }
+
   async listActive(
     actor?: Actor | null,
     timestamp = new Date(),

package/src/runtime/commerce.ts

@@ -121,6 +121,7 @@ export async function createCommerce(
 ): Promise<CommerceInstance> {
   const kernel = createKernel(config);
   await ensureDefaultOrg(kernel.database.db);
+
   const auth = createAuth(kernel.database, config);
   const logger = createLogger(config);