@unifiedcommerce/core 0.0.1

package/src/modules/audit/service.ts

@@ -0,0 +1,151 @@
+import { eq, and, desc, gte, lte } from "drizzle-orm";
+import type { InferSelectModel } from "drizzle-orm";
+import type { DrizzleDatabase } from "../../kernel/database/drizzle-db";
+import type { TxContext } from "../../kernel/database/tx-context";
+import type { HookContext } from "../../kernel/hooks/types";
+import { resolveOrgId } from "../../auth/org";
+import { auditLog } from "./schema";
+
+export type AuditEntry = InferSelectModel<typeof auditLog>;
+
+export interface RecordArgs {
+  entityType: string;
+  entityId: string;
+  event: string;
+  payload?: Record<string, unknown>;
+  ctx: HookContext;
+}
+
+export interface ListForEntityArgs {
+  organizationId?: string;
+  entityType: string;
+  entityId: string;
+  limit?: number;
+  ctx?: TxContext;
+}
+
+export interface ListArgs {
+  organizationId?: string | undefined;
+  entityType?: string | undefined;
+  entityId?: string | undefined;
+  event?: string | undefined;
+  actorId?: string | undefined;
+  from?: Date | undefined;
+  to?: Date | undefined;
+  limit?: number | undefined;
+}
+
+export interface AuditService {
+  record(args: RecordArgs): Promise<void>;
+  listForEntity(args: ListForEntityArgs): Promise<AuditEntry[]>;
+  list(args: ListArgs): Promise<AuditEntry[]>;
+}
+
+export function createNullAuditService(): AuditService {
+  const entries: AuditEntry[] = [];
+  return {
+    async record(args) {
+      entries.push({
+        id: crypto.randomUUID(),
+        organizationId: resolveOrgId(args.ctx.actor),
+        entityType: args.entityType,
+        entityId: args.entityId,
+        event: args.event,
+        payload: args.payload ?? {},
+        actorId: args.ctx.actor?.userId ?? null,
+        actorType: args.ctx.actor != null ? "user" : null,
+        requestId: args.ctx.requestId,
+        createdAt: new Date(),
+      });
+    },
+    async listForEntity(args) {
+      return entries
+        .filter(
+          (e) =>
+            e.entityType === args.entityType && e.entityId === args.entityId,
+        )
+        .sort(
+          (a, b) => b.createdAt.getTime() - a.createdAt.getTime(),
+        )
+        .slice(0, args.limit ?? 50);
+    },
+    async list(args) {
+      let result = entries;
+      if (args.entityType) result = result.filter((e) => e.entityType === args.entityType);
+      if (args.entityId) result = result.filter((e) => e.entityId === args.entityId);
+      if (args.event) result = result.filter((e) => e.event === args.event);
+      if (args.actorId) result = result.filter((e) => e.actorId === args.actorId);
+      if (args.from) result = result.filter((e) => e.createdAt >= args.from!);
+      if (args.to) result = result.filter((e) => e.createdAt <= args.to!);
+      return result
+        .sort((a, b) => b.createdAt.getTime() - a.createdAt.getTime())
+        .slice(0, args.limit ?? 50);
+    },
+  };
+}
+
+export function createAuditService(db: DrizzleDatabase): AuditService {
+  return {
+    async record(args) {
+      const { entityType, entityId, event, payload, ctx } = args;
+      const dbOrTx =
+        ctx.tx != null
+          ? (ctx.tx as typeof db)
+          : db;
+
+      await dbOrTx.insert(auditLog).values({
+        organizationId: resolveOrgId(ctx.actor),
+        entityType,
+        entityId,
+        event,
+        payload: payload ?? {},
+        actorId: ctx.actor?.userId ?? null,
+        actorType: ctx.actor != null ? "user" : null,
+        requestId: ctx.requestId,
+      });
+    },
+
+    async listForEntity(args) {
+      const { organizationId, entityType, entityId, limit = 50, ctx } = args;
+      const dbOrTx =
+        ctx?.tx != null
+          ? (ctx.tx as typeof db)
+          : db;
+
+      const conditions = [
+        eq(auditLog.entityType, entityType),
+        eq(auditLog.entityId, entityId),
+      ];
+      if (organizationId) {
+        conditions.push(eq(auditLog.organizationId, organizationId));
+      }
+
+      return dbOrTx
+        .select()
+        .from(auditLog)
+        .where(and(...conditions))
+        .orderBy(desc(auditLog.createdAt))
+        .limit(limit);
+    },
+
+    async list(args) {
+      const conditions = [];
+      if (args.organizationId) conditions.push(eq(auditLog.organizationId, args.organizationId));
+      if (args.entityType) conditions.push(eq(auditLog.entityType, args.entityType));
+      if (args.entityId) conditions.push(eq(auditLog.entityId, args.entityId));
+      if (args.event) conditions.push(eq(auditLog.event, args.event));
+      if (args.actorId) conditions.push(eq(auditLog.actorId, args.actorId));
+      if (args.from) conditions.push(gte(auditLog.createdAt, args.from));
+      if (args.to) conditions.push(lte(auditLog.createdAt, args.to));
+
+      let query = db.select().from(auditLog).$dynamic();
+      if (conditions.length > 0) {
+        query = query.where(conditions.length === 1 ? conditions[0]! : and(...conditions));
+      }
+
+      return query
+        .orderBy(desc(auditLog.createdAt))
+        .limit(args.limit ?? 50);
+    },
+  };
+}

package/src/modules/cart/access.ts

@@ -0,0 +1,27 @@
+import type { Actor } from "../../auth/types";
+import type { Cart } from "./repository";
+
+/**
+ * Determines whether an actor can access a cart.
+ *
+ * Access is granted if:
+ * 1. The actor is authenticated and owns the cart (customerId match)
+ * 2. The provided secret matches the cart's secret (guest access)
+ */
+export function canAccessCart(
+  actor: Actor | null,
+  cart: Cart,
+  providedSecret?: string,
+): boolean {
+  // Authenticated owner
+  if (actor && cart.customerId && actor.userId === cart.customerId) {
+    return true;
+  }
+
+  // Valid secret (guest access)
+  if (providedSecret && cart.secret && providedSecret === cart.secret) {
+    return true;
+  }
+
+  return false;
+}

package/src/modules/cart/matcher.ts

@@ -0,0 +1,26 @@
+import type { CartLineItem } from "./repository";
+
+/**
+ * Determines whether a new item matches an existing cart line item.
+ * Used by addItem to decide whether to increment quantity (match)
+ * or insert a new line (no match).
+ *
+ * The default matcher compares entityId + variantId.
+ * Developers selling customizable products (engraving, gift notes)
+ * can provide a custom matcher that includes metadata fields.
+ */
+export type CartItemMatcher = (args: {
+  existingItem: CartLineItem;
+  newItem: {
+    entityId: string;
+    variantId: string | null;
+    [key: string]: unknown;
+  };
+}) => boolean;
+
+export const defaultCartItemMatcher: CartItemMatcher = ({
+  existingItem,
+  newItem,
+}) =>
+  existingItem.entityId === newItem.entityId &&
+  existingItem.variantId === (newItem.variantId ?? null);

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

@@ -0,0 +1,234 @@
+import { eq, and, lt } from "drizzle-orm";
+import type { TxContext } from "../../../kernel/database/tx-context";
+import type {
+  DrizzleDatabase,
+  DbOrTx,
+} from "../../../kernel/database/drizzle-db";
+import { carts, cartLineItems } from "../schema";
+
+// Infer types from Drizzle schema
+export type Cart = typeof carts.$inferSelect;
+export type CartInsert = typeof carts.$inferInsert;
+export type CartLineItem = typeof cartLineItems.$inferSelect;
+export type CartLineItemInsert = typeof cartLineItems.$inferInsert;
+
+/**
+ * CartRepository provides type-safe database operations for shopping carts.
+ *
+ * This repository manages carts and cart line items.
+ * All methods support an optional TxContext parameter for transaction participation.
+ */
+export class CartRepository {
+  constructor(private readonly db: DrizzleDatabase) {}
+
+  private getDb(ctx?: TxContext): DbOrTx {
+    return (ctx?.tx as DbOrTx | undefined) ?? this.db;
+  }
+
+  // ─────────────────────────────────────────────────────────────────────────────
+  // Carts
+  // ─────────────────────────────────────────────────────────────────────────────
+
+  async findById(orgId: string, id: string, ctx?: TxContext): Promise<Cart | undefined> {
+    const db = this.getDb(ctx);
+    const rows = await db
+      .select()
+      .from(carts)
+      .where(and(eq(carts.organizationId, orgId), eq(carts.id, id)));
+    return rows[0];
+  }
+
+  async findByCustomerId(
+    orgId: string,
+    customerId: string,
+    ctx?: TxContext,
+  ): Promise<Cart | undefined> {
+    const db = this.getDb(ctx);
+    const rows = await db
+      .select()
+      .from(carts)
+      .where(and(eq(carts.organizationId, orgId), eq(carts.customerId, customerId), eq(carts.status, "active")));
+    return rows[0];
+  }
+
+  async findActiveByCustomerId(
+    orgId: string,
+    customerId: string,
+    ctx?: TxContext,
+  ): Promise<Cart | undefined> {
+    const db = this.getDb(ctx);
+    const rows = await db
+      .select()
+      .from(carts)
+      .where(and(eq(carts.organizationId, orgId), eq(carts.customerId, customerId), eq(carts.status, "active")));
+    return rows[0];
+  }
+
+  async findExpiredCarts(ctx?: TxContext): Promise<Cart[]> {
+    const db = this.getDb(ctx);
+    return db
+      .select()
+      .from(carts)
+      .where(and(eq(carts.status, "active"), lt(carts.expiresAt, new Date())));
+  }
+
+  async create(data: CartInsert, ctx?: TxContext): Promise<Cart> {
+    const db = this.getDb(ctx);
+    const rows = await db.insert(carts).values(data).returning();
+    return rows[0]!;
+  }
+
+  async update(
+    id: string,
+    data: Partial<Omit<CartInsert, "id">>,
+    ctx?: TxContext,
+  ): Promise<Cart | undefined> {
+    const db = this.getDb(ctx);
+    const rows = await db
+      .update(carts)
+      .set({ ...data, updatedAt: new Date() })
+      .where(eq(carts.id, id))
+      .returning();
+    return rows[0];
+  }
+
+  async updateStatus(
+    id: string,
+    status: Cart["status"],
+    ctx?: TxContext,
+  ): Promise<Cart | undefined> {
+    return this.update(id, { status }, ctx);
+  }
+
+  /**
+   * Atomically transitions a cart from "active" to "checking_out".
+   * Returns the updated cart if the transition succeeded, or undefined if
+   * the cart was not in "active" status (e.g., a concurrent checkout already
+   * claimed it). This prevents TOCTOU race conditions on double-checkout.
+   */
+  async transitionToCheckingOut(
+    id: string,
+    ctx?: TxContext,
+  ): Promise<Cart | undefined> {
+    const db = this.getDb(ctx);
+    const rows = await db
+      .update(carts)
+      .set({ status: "checking_out", updatedAt: new Date() })
+      .where(and(eq(carts.id, id), eq(carts.status, "active")))
+      .returning();
+    return rows[0];
+  }
+
+  async delete(id: string, ctx?: TxContext): Promise<boolean> {
+    const db = this.getDb(ctx);
+    const result = await db.delete(carts).where(eq(carts.id, id)).returning();
+    return result.length > 0;
+  }
+
+  // ─────────────────────────────────────────────────────────────────────────────
+  // Cart Line Items
+  // ─────────────────────────────────────────────────────────────────────────────
+
+  async findLineItemById(
+    id: string,
+    ctx?: TxContext,
+  ): Promise<CartLineItem | undefined> {
+    const db = this.getDb(ctx);
+    const rows = await db
+      .select()
+      .from(cartLineItems)
+      .where(eq(cartLineItems.id, id));
+    return rows[0];
+  }
+
+  async findLineItemsByCartId(
+    cartId: string,
+    ctx?: TxContext,
+  ): Promise<CartLineItem[]> {
+    const db = this.getDb(ctx);
+    return db
+      .select()
+      .from(cartLineItems)
+      .where(eq(cartLineItems.cartId, cartId));
+  }
+
+  async findLineItemByEntity(
+    cartId: string,
+    entityId: string,
+    variantId?: string,
+    ctx?: TxContext,
+  ): Promise<CartLineItem | undefined> {
+    const db = this.getDb(ctx);
+    const conditions = [
+      eq(cartLineItems.cartId, cartId),
+      eq(cartLineItems.entityId, entityId),
+    ];
+
+    if (variantId !== undefined) {
+      conditions.push(eq(cartLineItems.variantId, variantId));
+    }
+
+    const rows = await db
+      .select()
+      .from(cartLineItems)
+      .where(and(...conditions));
+
+    // Filter for exact variantId match
+    return rows.find((r) => r.variantId === (variantId ?? null));
+  }
+
+  async createLineItem(
+    data: CartLineItemInsert,
+    ctx?: TxContext,
+  ): Promise<CartLineItem> {
+    const db = this.getDb(ctx);
+    const rows = await db.insert(cartLineItems).values(data).returning();
+    return rows[0]!;
+  }
+
+  async updateLineItem(
+    id: string,
+    data: Partial<Omit<CartLineItemInsert, "id">>,
+    ctx?: TxContext,
+  ): Promise<CartLineItem | undefined> {
+    const db = this.getDb(ctx);
+    const rows = await db
+      .update(cartLineItems)
+      .set(data)
+      .where(eq(cartLineItems.id, id))
+      .returning();
+    return rows[0];
+  }
+
+  async deleteLineItem(id: string, ctx?: TxContext): Promise<boolean> {
+    const db = this.getDb(ctx);
+    const result = await db
+      .delete(cartLineItems)
+      .where(eq(cartLineItems.id, id))
+      .returning();
+    return result.length > 0;
+  }
+
+  async deleteLineItemsByCartId(
+    cartId: string,
+    ctx?: TxContext,
+  ): Promise<void> {
+    const db = this.getDb(ctx);
+    await db.delete(cartLineItems).where(eq(cartLineItems.cartId, cartId));
+  }
+
+  // ─────────────────────────────────────────────────────────────────────────────
+  // Cart with Line Items (Aggregate)
+  // ─────────────────────────────────────────────────────────────────────────────
+
+  async findWithLineItems(
+    orgId: string,
+    id: string,
+    ctx?: TxContext,
+  ): Promise<{ cart: Cart; lineItems: CartLineItem[] } | undefined> {
+    const cart = await this.findById(orgId, id, ctx);
+    if (!cart) return undefined;
+    const lineItems = await this.findLineItemsByCartId(id, ctx);
+    return { cart, lineItems };
+  }
+}

package/src/modules/cart/schema.ts

@@ -0,0 +1,42 @@
+import { index, integer, jsonb, pgTable, text, timestamp, uuid } from "drizzle-orm/pg-core";
+import { organization } from "../../auth/auth-schema";
+import { sellableEntities, variants } from "../catalog/schema";
+
+export const carts = pgTable("carts", {
+  id: uuid("id").defaultRandom().primaryKey(),
+  organizationId: text("organization_id").notNull().references(() => organization.id, { onDelete: "cascade" }),
+  customerId: uuid("customer_id"),
+  status: text("status", {
+    enum: ["active", "checking_out", "merged", "checked_out", "abandoned"],
+  })
+    .notNull()
+    .default("active"),
+  currency: text("currency").notNull().default("USD"),
+  secret: text("secret"),
+  metadata: jsonb("metadata").$type<Record<string, unknown>>().default({}),
+  expiresAt: timestamp("expires_at", { withTimezone: true }).notNull(),
+  createdAt: timestamp("created_at", { withTimezone: true }).defaultNow().notNull(),
+  updatedAt: timestamp("updated_at", { withTimezone: true }).defaultNow().notNull(),
+}, (table) => ({
+  orgIdx: index("idx_carts_org").on(table.organizationId),
+  customerIdIdx: index("idx_carts_customer_id").on(table.customerId),
+  statusIdx: index("idx_carts_status").on(table.status),
+  expiresAtIdx: index("idx_carts_expires_at").on(table.expiresAt),
+}));
+
+export const cartLineItems = pgTable("cart_line_items", {
+  id: uuid("id").defaultRandom().primaryKey(),
+  cartId: uuid("cart_id")
+    .references(() => carts.id, { onDelete: "cascade" })
+    .notNull(),
+  entityId: uuid("entity_id").references(() => sellableEntities.id).notNull(),
+  variantId: uuid("variant_id").references(() => variants.id),
+  quantity: integer("quantity").notNull().default(1),
+  unitPriceSnapshot: integer("unit_price_snapshot").notNull(),
+  currency: text("currency").notNull(),
+  notes: text("notes"),
+  metadata: jsonb("metadata").$type<Record<string, unknown>>().default({}),
+  addedAt: timestamp("added_at", { withTimezone: true }).defaultNow().notNull(),
+}, (table) => [
+  index("idx_cart_line_items_cart_id").on(table.cartId),
+]);

package/src/modules/cart/schemas.ts

@@ -0,0 +1,38 @@
+import { z } from "@hono/zod-openapi";
+
+// ─── Cart Body Schemas (single source of truth) ─────────────────────────────
+
+export const CreateCartBodySchema = z.object({
+  customerId: z.string().optional().openapi({ example: "customer-uuid" }),
+  currency: z.string().length(3).optional().openapi({ example: "USD" }),
+}).openapi("CreateCartRequest");
+
+export const AddCartItemBodySchema = z.object({
+  entityId: z.string().openapi({ example: "product-uuid" }),
+  variantId: z.string().nullable().optional().openapi({ example: "variant-uuid" }),
+  quantity: z.number().int().min(1).max(9999).openapi({ example: 1 }),
+}).openapi("AddCartItemRequest");
+
+export const UpdateCartItemQuantityBodySchema = z.object({
+  quantity: z.number().int().min(1).max(9999).openapi({ example: 2 }),
+}).openapi("UpdateCartItemQuantityRequest");
+
+// ─── Derived Input Types ─────────────────────────────────────────────────────
+
+export type CreateCartInput = z.infer<typeof CreateCartBodySchema> & {
+  metadata?: Record<string, unknown>;
+};
+
+export type AddCartItemInput = z.infer<typeof AddCartItemBodySchema> & {
+  cartId: string;
+  unitPriceSnapshot?: number;
+  currency?: string;
+  metadata?: Record<string, unknown>;
+};
+
+/** Hand-written: all fields come from path params + body; schema only has quantity. */
+export interface UpdateCartItemInput {
+  cartId: string;
+  itemId: string;
+  quantity: number;
+}