@porulle/core 0.1.0

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

@@ -0,0 +1,70 @@
+import type { Actor } from "../auth/types.js";
+import { DEFAULT_ORG_ID } from "../auth/org.js";
+
+/**
+ * Organization ID used in test fixtures. Tests use the deprecated DEFAULT_ORG_ID
+ * because ensureDefaultOrg() creates this org in test setup. When RFC-060 Phase 6
+ * removes DEFAULT_ORG_ID, test setup will create a real org via Better Auth API.
+ */
+export const TEST_ORG_ID = DEFAULT_ORG_ID;
+
+/** 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: TEST_ORG_ID,
+  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: TEST_ORG_ID,
+  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: TEST_ORG_ID,
+  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: TEST_ORG_ID,
+  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,55 @@
+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
+ * import { resolveOrgId } from "@porulle/core";
+ * hooks: () => [
+ *   afterHook<{ id: string; grandTotal: number }>("orders.afterCreate", async ({ result, context }) => {
+ *     await context.jobs.enqueue("loyalty:award-points", { orderId: result.id }, { organizationId: resolveOrgId(context.actor) });
+ *   }),
+ * ],
+ * ```
+ */
+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"] };
+}

package/src/testing.ts

@@ -0,0 +1,21 @@
+/**
+ * Test utilities for UnifiedCommerce plugins and apps.
+ *
+ * Import from "@porulle/core/testing" — NOT from "@porulle/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 {
+  TEST_ORG_ID,
+  testAdminActor, testStaffActor, testCustomerActor, testNoPermActor,
+  jsonHeaders,
+} from "./test-utils/test-actors.js";
+export { beforeHook, afterHook } from "./test-utils/typed-hooks.js";
+
+// Actor type re-export for plugin tests that build custom test actors.
+export type { Actor } from "./auth/types.js";

package/src/types/commerce-types.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 "@porulle/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;
+}

package/src/utils/agent-prompt.ts

@@ -0,0 +1,12 @@
+export const COMMERCE_AGENT_SYSTEM_PROMPT = `You are an AI commerce assistant with access to a live e-commerce store via the UnifiedCommerce Engine REST API.
+
+Your role:
+- Help users browse products, place orders, and answer commerce questions
+- Use structured tool outputs and summarize clearly
+- Be accurate, concise, and transparent about limitations
+
+Guidelines:
+- Prefer factual responses grounded in API data
+- Ask for clarification when requests are ambiguous
+- Never invent order, inventory, or payment state
+- Protect sensitive information and follow least-privilege access`;

package/src/utils/id.ts

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

package/src/utils/logger.ts

@@ -0,0 +1,18 @@
+import type { Logger } from "../kernel/hooks/types.js";
+
+export function createLogger(scope: string): Logger {
+  return {
+    info(message: string, data?: unknown) {
+      // eslint-disable-next-line no-console
+      console.info(`[${scope}] ${message}`, data ?? "");
+    },
+    warn(message: string, data?: unknown) {
+      // eslint-disable-next-line no-console
+      console.warn(`[${scope}] ${message}`, data ?? "");
+    },
+    error(message: string, data?: unknown) {
+      // eslint-disable-next-line no-console
+      console.error(`[${scope}] ${message}`, data ?? "");
+    },
+  };
+}

package/src/utils/pagination.ts

@@ -0,0 +1,22 @@
+export interface Pagination {
+  page: number;
+  limit: number;
+  total: number;
+  totalPages: number;
+}
+
+export function paginate<T>(items: T[], page: number, limit: number): { items: T[]; pagination: Pagination } {
+  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)),
+    },
+  };
+}