@porulle/core 0.1.0 → 0.5.0

package/src/kernel/database/migrate.ts

@@ -10,17 +10,20 @@
  *
  * Usage in consumer's drizzle.config.ts:
  *
- *   import { getSchema } from "@porulle/core";
+ *   import { getSchemaFiles } from "@porulle/core";
  *   import { defineConfig } from "drizzle-kit";
  *
  *   export default defineConfig({
  *     dialect: "postgresql",
- *     schema: getSchema(),
+ *     schema: getSchemaFiles(),
  *     dbCredentials: { url: process.env.DATABASE_URL! },
  *   });
  */
 
+import { createRequire } from "node:module";
+import { fileURLToPath } from "node:url";
 import type { CommerceConfig } from "../../config/types.js";
+import { unwrapDb } from "./adapter.js";
 import * as schema from "./schema.js";
 
 /**
@@ -74,3 +77,48 @@ export function getTableNames(): string[] {
     )
     .map(([key]) => key);
 }
+
+/**
+ * Returns the absolute filesystem path(s) of the combined schema module for
+ * use as drizzle-kit's `schema` option in a consumer's `drizzle.config.ts`.
+ *
+ * npm consumers don't have the raw `.ts` sources, so a relative path into
+ * `node_modules` is brittle. This resolves the installed schema module
+ * (compiled `schema.js` for published consumers, `schema.ts` under Bun) so
+ * `drizzle-kit push` / `generate` discover every core table.
+ */
+export function getSchemaFiles(): string[] {
+  // Resolve the sibling schema module that actually exists: `.ts` when running
+  // from source (Bun export condition), `.js` for published/compiled consumers.
+  const ext = fileURLToPath(import.meta.url).endsWith(".ts") ? ".ts" : ".js";
+  return [fileURLToPath(new URL(`./schema${ext}`, import.meta.url))];
+}
+
+/**
+ * Programmatically creates the core tables in the target database
+ * (creates tables if they don't exist), without migration files.
+ *
+ * Uses `drizzle-kit/api` — drizzle-kit introspects the live database and
+ * generates the minimal DDL to converge it on the core schema. Pass a
+ * Drizzle instance bound to your database. `drizzle-kit` must be available
+ * (it is the standard schema tool); a clear error is thrown if it is not.
+ */
+export async function pushSchema(drizzleInstance: unknown): Promise<void> {
+  const require = createRequire(import.meta.url);
+  let drizzleKit: {
+    pushSchema(
+      imports: Record<string, unknown>,
+      db: unknown,
+    ): Promise<{ apply: () => Promise<void> }>;
+  };
+  try {
+    drizzleKit = require("drizzle-kit/api");
+  } catch {
+    throw new Error(
+      "pushSchema() requires `drizzle-kit` to be installed. Add it to your project: bun add -d drizzle-kit",
+    );
+  }
+  // drizzle-kit needs the native driver result shape; unwrap a normalized db.
+  const { apply } = await drizzleKit.pushSchema(getSchema(), unwrapDb(drizzleInstance));
+  await apply();
+}

package/src/modules/analytics/hooks.ts

@@ -1,11 +1,11 @@
 /**
- * Analytics hooks — RFC-006
+ * Analytics hooks — legacy compatibility surface.
  *
  * The in-memory event recording hooks (recordOrderAnalyticsEvent,
  * recordInventoryAnalyticsEvent) have been removed. The source tables
- * (orders, inventory_levels, customers) ARE the source of truth.
- * The DrizzleAnalyticsAdapter queries them directly via SQL.
+ * (orders, inventory_levels, customers) ARE the source of truth; the
+ * DrizzleAnalyticsAdapter queries them directly via SQL.
  *
- * These empty exports preserve backwards compatibility for any code
- * that imports from this module.
+ * The empty exports below preserve backwards compatibility for code
+ * still importing from this module.
  */

package/src/modules/analytics/repository/index.ts

@@ -1,6 +1,5 @@
 import type { TxContext } from "../../../kernel/database/tx-context.js";
 
 export interface AnalyticsRepository {
-  // RFC-002 scaffold: module repositories become the only persistence boundary.
   ping(ctx: TxContext): Promise<void>;
 }

package/src/modules/catalog/category-service.ts

@@ -29,10 +29,31 @@ export class CategoryService {
     }
   }
 
-  async listCategories(ctx?: TxContext): Promise<Result<CategorySummary[]>> {
+  async listCategories(ctx?: TxContext, opts?: { includeArchived?: boolean }): Promise<Result<CategorySummary[]>> {
     const allCategories = await this.repo.findAllCategories(resolveOrgId(ctx?.actor ?? null), ctx);
-    const sorted = allCategories.sort((a, b) => a.sortOrder - b.sortOrder || a.slug.localeCompare(b.slug));
-    return Ok(sorted.map((c) => ({ id: c.id, parentId: c.parentId, slug: c.slug, sortOrder: c.sortOrder, metadata: c.metadata ?? {} })));
+    const visible = opts?.includeArchived
+      ? allCategories
+      : allCategories.filter((c) => (c.status ?? "active") === "active");
+    const sorted = visible.sort((a, b) => a.sortOrder - b.sortOrder || a.slug.localeCompare(b.slug));
+    return Ok(sorted.map((c) => ({ id: c.id, parentId: c.parentId, slug: c.slug, sortOrder: c.sortOrder, status: c.status ?? "active", metadata: c.metadata ?? {} })));
+  }
+
+  private async setStatus(id: string, status: "active" | "archived", actor: Actor | null, ctx?: TxContext): Promise<Result<CategorySummary>> {
+    try { assertPermission(actor, "catalog:update"); } catch (error) { return Err(toCommerceError(error)); }
+    const existing = await this.repo.findCategoryById(id, ctx);
+    if (!existing) return Err(new CommerceNotFoundError("Category not found."));
+    try { this.assertSameOrg(existing, actor); } catch (error) { return Err(toCommerceError(error)); }
+    const updated = await this.repo.updateCategory(id, { status }, ctx);
+    if (!updated) return Err(new CommerceNotFoundError("Category not found."));
+    return Ok({ id: updated.id, parentId: updated.parentId, slug: updated.slug, sortOrder: updated.sortOrder, status: updated.status ?? status, metadata: updated.metadata ?? {} });
+  }
+
+  async archiveCategory(id: string, actor: Actor | null, ctx?: TxContext): Promise<Result<CategorySummary>> {
+    return this.setStatus(id, "archived", actor, ctx);
+  }
+
+  async restoreCategory(id: string, actor: Actor | null, ctx?: TxContext): Promise<Result<CategorySummary>> {
+    return this.setStatus(id, "active", actor, ctx);
   }
 
   async createCategory(input: CreateCategoryInput, actor: Actor | null, ctx?: TxContext): Promise<Result<CategorySummary>> {
@@ -45,7 +66,7 @@ export class CategoryService {
     const existingBySlug = await this.repo.findCategoryBySlug(orgId, input.slug, ctx);
     if (existingBySlug) return Err(new CommerceConflictError(`Category with slug ${input.slug} already exists.`));
     const category = await this.repo.createCategory({ organizationId: orgId, ...(input.id ? { id: input.id } : {}), slug: input.slug, sortOrder: input.sortOrder ?? 0, metadata: input.metadata ?? {}, ...(input.parentId !== undefined ? { parentId: input.parentId } : {}) }, ctx);
-    return Ok({ id: category.id, parentId: category.parentId, slug: category.slug, sortOrder: category.sortOrder, metadata: category.metadata ?? {} });
+    return Ok({ id: category.id, parentId: category.parentId, slug: category.slug, sortOrder: category.sortOrder, status: category.status ?? "active", metadata: category.metadata ?? {} });
   }
 
   async updateCategory(id: string, input: UpdateCategoryInput, actor: Actor | null, ctx?: TxContext): Promise<Result<CategorySummary>> {
@@ -59,7 +80,7 @@ export class CategoryService {
     }
     const updated = await this.repo.updateCategory(id, { ...(input.slug !== undefined ? { slug: input.slug } : {}), ...(input.sortOrder !== undefined ? { sortOrder: input.sortOrder } : {}), ...(input.metadata !== undefined ? { metadata: input.metadata } : {}), ...(input.parentId !== undefined ? { parentId: input.parentId } : {}) }, ctx);
     if (!updated) return Err(new CommerceNotFoundError("Category not found."));
-    return Ok({ id: updated.id, parentId: updated.parentId, slug: updated.slug, sortOrder: updated.sortOrder, metadata: updated.metadata ?? {} });
+    return Ok({ id: updated.id, parentId: updated.parentId, slug: updated.slug, sortOrder: updated.sortOrder, status: updated.status ?? "active", metadata: updated.metadata ?? {} });
   }
 
   async deleteCategory(id: string, actor: Actor | null, ctx?: TxContext): Promise<Result<void>> {

package/src/modules/catalog/schema.ts

@@ -106,6 +106,8 @@ export const categories = pgTable(
     }),
     slug: text("slug").notNull(),
     sortOrder: integer("sort_order").notNull().default(0),
+    // active | archived. Soft-delete without cascading entity_categories.
+    status: text("status").notNull().default("active"),
     metadata: jsonb("metadata").$type<Record<string, unknown>>().default({}),
   },
   (table) => ({

package/src/modules/catalog/service.ts

@@ -167,12 +167,25 @@ export interface CatalogService {
     locale: string,
     ctx?: TxContext,
   ): Promise<Result<SellableAttribute>>;
-  listCategories(ctx?: TxContext): Promise<Result<CategorySummary[]>>;
+  listCategories(
+    ctx?: TxContext,
+    opts?: { includeArchived?: boolean },
+  ): Promise<Result<CategorySummary[]>>;
   createCategory(
     input: CreateCategoryInput,
     actor: Actor | null,
     ctx?: TxContext,
   ): Promise<Result<CategorySummary>>;
+  archiveCategory(
+    id: string,
+    actor: Actor | null,
+    ctx?: TxContext,
+  ): Promise<Result<CategorySummary>>;
+  restoreCategory(
+    id: string,
+    actor: Actor | null,
+    ctx?: TxContext,
+  ): Promise<Result<CategorySummary>>;
   updateCategory(
     id: string,
     input: UpdateCategoryInput,
@@ -266,6 +279,7 @@ export type CategorySummary = {
   parentId?: string | null;
   slug: string;
   sortOrder: number;
+  status: string;
   metadata: Record<string, unknown>;
 };
 
@@ -326,14 +340,22 @@ export class CatalogServiceImpl implements CatalogService {
     return this.entities.getAttributes(entityId, locale, ctx);
   }
 
-  listCategories(ctx?: TxContext): Promise<Result<CategorySummary[]>> {
-    return this.categories.listCategories(ctx);
+  listCategories(ctx?: TxContext, opts?: { includeArchived?: boolean }): Promise<Result<CategorySummary[]>> {
+    return this.categories.listCategories(ctx, opts);
   }
 
   createCategory(input: CreateCategoryInput, actor: Actor | null, ctx?: TxContext): Promise<Result<CategorySummary>> {
     return this.categories.createCategory(input, actor, ctx);
   }
 
+  archiveCategory(id: string, actor: Actor | null, ctx?: TxContext): Promise<Result<CategorySummary>> {
+    return this.categories.archiveCategory(id, actor, ctx);
+  }
+
+  restoreCategory(id: string, actor: Actor | null, ctx?: TxContext): Promise<Result<CategorySummary>> {
+    return this.categories.restoreCategory(id, actor, ctx);
+  }
+
   updateCategory(id: string, input: UpdateCategoryInput, actor: Actor | null, ctx?: TxContext): Promise<Result<CategorySummary>> {
     return this.categories.updateCategory(id, input, actor, ctx);
   }

package/src/modules/customers/repository/index.ts

@@ -1,4 +1,4 @@
-import { eq, and } from "drizzle-orm";
+import { eq, and, desc } from "drizzle-orm";
 import type { TxContext } from "../../../kernel/database/tx-context.js";
 import type {
   DrizzleDatabase,
@@ -9,11 +9,14 @@ import {
   customerAddresses,
   customerGroups,
   customerGroupMembers,
+  customerInteractions,
 } from "../schema.js";
 
 // Infer types from Drizzle schema
 export type Customer = typeof customers.$inferSelect;
 export type CustomerInsert = typeof customers.$inferInsert;
+export type CustomerInteraction = typeof customerInteractions.$inferSelect;
+export type CustomerInteractionInsert = typeof customerInteractions.$inferInsert;
 export type CustomerAddress = typeof customerAddresses.$inferSelect;
 export type CustomerAddressInsert = typeof customerAddresses.$inferInsert;
 export type CustomerGroup = typeof customerGroups.$inferSelect;
@@ -101,6 +104,57 @@ export class CustomersRepository {
     return rows[0]!;
   }
 
+  // ─── Customer interactions ───────────────────────────────────────────────
+
+  async listInteractions(orgId: string, customerId: string, ctx?: TxContext): Promise<CustomerInteraction[]> {
+    const db = this.getDb(ctx);
+    return db
+      .select()
+      .from(customerInteractions)
+      .where(and(eq(customerInteractions.organizationId, orgId), eq(customerInteractions.customerId, customerId)))
+      .orderBy(desc(customerInteractions.at));
+  }
+
+  async findInteractionById(orgId: string, id: string, ctx?: TxContext): Promise<CustomerInteraction | undefined> {
+    const db = this.getDb(ctx);
+    const rows = await db
+      .select()
+      .from(customerInteractions)
+      .where(and(eq(customerInteractions.organizationId, orgId), eq(customerInteractions.id, id)))
+      .limit(1);
+    return rows[0];
+  }
+
+  async createInteraction(data: CustomerInteractionInsert, ctx?: TxContext): Promise<CustomerInteraction> {
+    const db = this.getDb(ctx);
+    const rows = await db.insert(customerInteractions).values(data).returning();
+    return rows[0]!;
+  }
+
+  async updateInteraction(
+    orgId: string,
+    id: string,
+    data: Partial<Omit<CustomerInteractionInsert, "id" | "organizationId" | "customerId">>,
+    ctx?: TxContext,
+  ): Promise<CustomerInteraction | undefined> {
+    const db = this.getDb(ctx);
+    const rows = await db
+      .update(customerInteractions)
+      .set(data)
+      .where(and(eq(customerInteractions.organizationId, orgId), eq(customerInteractions.id, id)))
+      .returning();
+    return rows[0];
+  }
+
+  async deleteInteraction(orgId: string, id: string, ctx?: TxContext): Promise<boolean> {
+    const db = this.getDb(ctx);
+    const rows = await db
+      .delete(customerInteractions)
+      .where(and(eq(customerInteractions.organizationId, orgId), eq(customerInteractions.id, id)))
+      .returning();
+    return rows.length > 0;
+  }
+
   async update(
     id: string,
     data: Partial<Omit<CustomerInsert, "id">>,

package/src/modules/customers/schema.ts

@@ -62,3 +62,22 @@ export const customerGroupMembers = pgTable("customer_group_members", {
   index("idx_group_members_group_id").on(table.groupId),
   uniqueIndex("customer_group_members_customer_group_unique").on(table.customerId, table.groupId),
 ]);
+
+// Non-transactional clienteling interactions: visits, calls, inquiries,
+// fittings, follow-ups, messages. Distinct from the audit log (accountability).
+export const customerInteractions = pgTable("customer_interactions", {
+  id: uuid("id").defaultRandom().primaryKey(),
+  organizationId: text("organization_id").notNull().references(() => organization.id, { onDelete: "cascade" }),
+  customerId: uuid("customer_id")
+    .references(() => customers.id, { onDelete: "cascade" })
+    .notNull(),
+  actorUserId: text("actor_user_id"),
+  kind: text("kind").notNull(),
+  notes: text("notes").notNull(),
+  relatedEntityId: uuid("related_entity_id"),
+  metadata: jsonb("metadata").$type<Record<string, unknown>>().default({}),
+  at: timestamp("at", { withTimezone: true }).defaultNow().notNull(),
+}, (table) => [
+  index("idx_customer_interactions_customer_id").on(table.customerId),
+  index("idx_customer_interactions_org").on(table.organizationId),
+]);

package/src/modules/customers/service.ts

@@ -1,6 +1,7 @@
 import { resolveOrgId } from "../../auth/org.js";
+import { assertPermission } from "../../auth/permissions.js";
 import type { Actor } from "../../auth/types.js";
-import { CommerceNotFoundError } from "../../kernel/errors.js";
+import { CommerceNotFoundError, toCommerceError } from "../../kernel/errors.js";
 import { runAfterHooks } from "../../kernel/hooks/executor.js";
 import { createHookContext } from "../../kernel/hooks/create-context.js";
 import type { HookRegistry } from "../../kernel/hooks/registry.js";
@@ -15,6 +16,7 @@ import type {
   Customer,
   CustomerAddress,
   CustomerAddressInsert,
+  CustomerInteraction,
 } from "./repository/index.js";
 
 interface CustomerServiceDeps {
@@ -47,6 +49,124 @@ export class CustomerService {
     this.repo = deps.repository;
   }
 
+  /**
+   * Create a customer. `userId` is optional: for walk-in / point-of-sale
+   * customers who never log in, omit it and a synthetic `anonymous_<uuid>` id
+   * is generated and the customer is flagged `metadata.walkIn = true`. This
+   * keeps non-account contacts out of the auth users table.
+   */
+  async createWalkIn(
+    input: {
+      userId?: string | undefined;
+      firstName?: string | undefined;
+      lastName?: string | undefined;
+      phone?: string | undefined;
+      email?: string | undefined;
+      metadata?: Record<string, unknown> | undefined;
+    },
+    actor?: Actor | null,
+    ctx?: TxContext,
+  ): Promise<Result<Customer>> {
+    try {
+      assertPermission(actor ?? null, "customers:create");
+    } catch (error) {
+      return Err(toCommerceError(error));
+    }
+
+    const orgId = resolveOrgId(actor ?? ctx?.actor ?? null);
+    const isWalkIn = input.userId === undefined;
+    const userId = input.userId ?? `anonymous_${crypto.randomUUID()}`;
+    const metadata = {
+      ...(input.metadata ?? {}),
+      ...(isWalkIn ? { walkIn: true } : {}),
+    };
+
+    const customer = await this.repo.create(
+      {
+        organizationId: orgId,
+        userId,
+        metadata,
+        ...(input.firstName !== undefined ? { firstName: input.firstName } : {}),
+        ...(input.lastName !== undefined ? { lastName: input.lastName } : {}),
+        ...(input.phone !== undefined ? { phone: input.phone } : {}),
+        ...(input.email !== undefined ? { email: input.email } : {}),
+      },
+      ctx,
+    );
+
+    const afterHooks = this.deps.hooks.resolve(
+      "customers.afterCreate",
+    ) as AfterHook<Customer>[];
+    const hctx = hookContext(actor ?? null, this.deps.services, this.deps.database, ctx?.tx ?? null);
+    await runAfterHooks(afterHooks, null, customer, "create", hctx);
+
+    return Ok(customer);
+  }
+
+  // ─── Customer interactions (clienteling notes / visits / calls) ──────────
+
+  async listInteractions(customerId: string, actor?: Actor | null, ctx?: TxContext): Promise<Result<CustomerInteraction[]>> {
+    try { assertPermission(actor ?? null, "customers:read"); } catch (error) { return Err(toCommerceError(error)); }
+    const orgId = resolveOrgId(actor ?? ctx?.actor ?? null);
+    return Ok(await this.repo.listInteractions(orgId, customerId, ctx));
+  }
+
+  async createInteraction(
+    customerId: string,
+    input: { kind: string; notes: string; relatedEntityId?: string | null | undefined; metadata?: Record<string, unknown> | undefined },
+    actor?: Actor | null,
+    ctx?: TxContext,
+  ): Promise<Result<CustomerInteraction>> {
+    try { assertPermission(actor ?? null, "customers:update"); } catch (error) { return Err(toCommerceError(error)); }
+    const orgId = resolveOrgId(actor ?? ctx?.actor ?? null);
+    const customer = await this.repo.findById(orgId, customerId, ctx);
+    if (!customer) return Err(new CommerceNotFoundError("Customer not found."));
+    const interaction = await this.repo.createInteraction(
+      {
+        organizationId: orgId,
+        customerId,
+        kind: input.kind,
+        notes: input.notes,
+        actorUserId: actor?.userId ?? null,
+        relatedEntityId: input.relatedEntityId ?? null,
+        metadata: input.metadata ?? {},
+      },
+      ctx,
+    );
+    return Ok(interaction);
+  }
+
+  async updateInteraction(
+    customerId: string,
+    interactionId: string,
+    input: { kind?: string | undefined; notes?: string | undefined; relatedEntityId?: string | null | undefined; metadata?: Record<string, unknown> | undefined },
+    actor?: Actor | null,
+    ctx?: TxContext,
+  ): Promise<Result<CustomerInteraction>> {
+    try { assertPermission(actor ?? null, "customers:update"); } catch (error) { return Err(toCommerceError(error)); }
+    const orgId = resolveOrgId(actor ?? ctx?.actor ?? null);
+    const existing = await this.repo.findInteractionById(orgId, interactionId, ctx);
+    if (!existing || existing.customerId !== customerId) return Err(new CommerceNotFoundError("Interaction not found."));
+    const patch = {
+      ...(input.kind !== undefined ? { kind: input.kind } : {}),
+      ...(input.notes !== undefined ? { notes: input.notes } : {}),
+      ...(input.relatedEntityId !== undefined ? { relatedEntityId: input.relatedEntityId } : {}),
+      ...(input.metadata !== undefined ? { metadata: input.metadata } : {}),
+    };
+    const updated = await this.repo.updateInteraction(orgId, interactionId, patch, ctx);
+    if (!updated) return Err(new CommerceNotFoundError("Interaction not found."));
+    return Ok(updated);
+  }
+
+  async deleteInteraction(customerId: string, interactionId: string, actor?: Actor | null, ctx?: TxContext): Promise<Result<void>> {
+    try { assertPermission(actor ?? null, "customers:update"); } catch (error) { return Err(toCommerceError(error)); }
+    const orgId = resolveOrgId(actor ?? ctx?.actor ?? null);
+    const existing = await this.repo.findInteractionById(orgId, interactionId, ctx);
+    if (!existing || existing.customerId !== customerId) return Err(new CommerceNotFoundError("Interaction not found."));
+    await this.repo.deleteInteraction(orgId, interactionId, ctx);
+    return Ok(undefined);
+  }
+
   private async getOrCreateByUserId(
     orgId: string,
     userId: string,
@@ -119,11 +239,26 @@ export class CustomerService {
     >,
     actor?: Actor | null,
     ctx?: TxContext,
+    options?: { replaceMetadata?: boolean },
   ): Promise<Result<Customer>> {
     const orgId = resolveOrgId(actor ?? ctx?.actor ?? null);
     const existing = await this.repo.findById(orgId, id, ctx);
     if (!existing) return Err(new CommerceNotFoundError("Customer not found."));
-    const updated = await this.repo.update(id, updates, ctx);
+
+    // Shallow-merge metadata by default (top-level keys) so a single-key edit
+    // doesn't clobber the rest of the blob. Pass replaceMetadata to overwrite.
+    let finalUpdates = updates;
+    if (updates.metadata !== undefined && !options?.replaceMetadata) {
+      finalUpdates = {
+        ...updates,
+        metadata: {
+          ...((existing.metadata as Record<string, unknown> | null) ?? {}),
+          ...(updates.metadata as Record<string, unknown>),
+        },
+      };
+    }
+
+    const updated = await this.repo.update(id, finalUpdates, ctx);
     if (!updated) return Err(new CommerceNotFoundError("Customer not found."));
 
     const afterHooks = this.deps.hooks.resolve(

package/src/modules/inventory/schemas.ts

@@ -6,7 +6,12 @@ export const InventoryAdjustBodySchema = z.object({
   entityId: z.string().openapi({ example: "550e8400-e29b-41d4-a716-446655440000" }),
   variantId: z.string().optional().openapi({ example: "variant-uuid" }),
   warehouseId: z.string().optional().openapi({ example: "warehouse-uuid" }),
-  adjustment: z.number().int().refine((v) => v !== 0, { message: "Adjustment cannot be zero" }).openapi({ example: 10 }),
+  // Signed-delta form (legacy/default). Required when `mode` is omitted.
+  adjustment: z.number().int().refine((v) => v !== 0, { message: "Adjustment cannot be zero" }).optional().openapi({ example: 10 }),
+  // Mode form. `add`/`remove`/`set` operate on the unsigned `amount`.
+  // `remove` clamps at 0; `set` writes the absolute quantity.
+  mode: z.enum(["add", "remove", "set"]).optional().openapi({ example: "add" }),
+  amount: z.number().int().min(0).optional().openapi({ example: 5 }),
   reason: z.string().openapi({ example: "Restock from supplier" }),
   performedBy: z.string().optional(),
   referenceType: z.string().optional(),