@unifiedcommerce/core 0.2.0 → 0.2.1

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

@@ -0,0 +1,325 @@
+import { eq, and, lte, gte, or, isNull, desc, sql } from "drizzle-orm";
+import type { TxContext } from "../../../kernel/database/tx-context.js";
+import type {
+  DrizzleDatabase,
+  DbOrTx,
+} from "../../../kernel/database/drizzle-db.js";
+import { promotions, promotionUsages } from "../schema.js";
+
+// Infer types from Drizzle schema
+export type Promotion = typeof promotions.$inferSelect;
+export type PromotionInsert = typeof promotions.$inferInsert;
+export type PromotionUsage = typeof promotionUsages.$inferSelect;
+export type PromotionUsageInsert = typeof promotionUsages.$inferInsert;
+
+/**
+ * PromotionsRepository provides type-safe database operations for promotions.
+ *
+ * This repository manages promotions and their usage tracking.
+ * All methods support an optional TxContext parameter for transaction participation.
+ */
+export class PromotionsRepository {
+  constructor(private readonly db: DrizzleDatabase) {}
+
+  private getDb(ctx?: TxContext): DbOrTx {
+    return (ctx?.tx as DbOrTx | undefined) ?? this.db;
+  }
+
+  // ─────────────────────────────────────────────────────────────────────────────
+  // Promotions
+  // ─────────────────────────────────────────────────────────────────────────────
+
+  async findById(orgId: string, id: string, ctx?: TxContext): Promise<Promotion | undefined> {
+    const db = this.getDb(ctx);
+    const rows = await db
+      .select()
+      .from(promotions)
+      .where(and(eq(promotions.organizationId, orgId), eq(promotions.id, id)));
+    return rows[0];
+  }
+
+  async findByCode(
+    orgId: string,
+    code: string,
+    ctx?: TxContext,
+  ): Promise<Promotion | undefined> {
+    const db = this.getDb(ctx);
+    const rows = await db
+      .select()
+      .from(promotions)
+      .where(
+        and(
+          eq(promotions.organizationId, orgId),
+          eq(promotions.code, code),
+        ),
+      );
+    return rows[0];
+  }
+
+  async findAll(orgId: string, ctx?: TxContext): Promise<Promotion[]> {
+    const db = this.getDb(ctx);
+    return db
+      .select()
+      .from(promotions)
+      .where(eq(promotions.organizationId, orgId))
+      .orderBy(desc(promotions.priority));
+  }
+
+  async findActive(orgId: string, ctx?: TxContext): Promise<Promotion[]> {
+    const db = this.getDb(ctx);
+    const now = new Date();
+
+    return db
+      .select()
+      .from(promotions)
+      .where(
+        and(
+          eq(promotions.organizationId, orgId),
+          eq(promotions.isActive, true),
+          or(isNull(promotions.validFrom), lte(promotions.validFrom, now)),
+          or(isNull(promotions.validUntil), gte(promotions.validUntil, now)),
+        ),
+      )
+      .orderBy(desc(promotions.priority));
+  }
+
+  async findAutomatic(orgId: string, ctx?: TxContext): Promise<Promotion[]> {
+    const db = this.getDb(ctx);
+    const now = new Date();
+
+    return db
+      .select()
+      .from(promotions)
+      .where(
+        and(
+          eq(promotions.organizationId, orgId),
+          eq(promotions.isActive, true),
+          eq(promotions.isAutomatic, true),
+          or(isNull(promotions.validFrom), lte(promotions.validFrom, now)),
+          or(isNull(promotions.validUntil), gte(promotions.validUntil, now)),
+        ),
+      )
+      .orderBy(desc(promotions.priority));
+  }
+
+  async create(data: PromotionInsert, ctx?: TxContext): Promise<Promotion> {
+    const db = this.getDb(ctx);
+    const rows = await db.insert(promotions).values(data).returning();
+    return rows[0]!;
+  }
+
+  async update(
+    id: string,
+    data: Partial<Omit<PromotionInsert, "id">>,
+    ctx?: TxContext,
+  ): Promise<Promotion | undefined> {
+    const db = this.getDb(ctx);
+    const rows = await db
+      .update(promotions)
+      .set({ ...data, updatedAt: new Date() })
+      .where(eq(promotions.id, id))
+      .returning();
+    return rows[0];
+  }
+
+  async delete(id: string, ctx?: TxContext): Promise<boolean> {
+    const db = this.getDb(ctx);
+    const result = await db
+      .delete(promotions)
+      .where(eq(promotions.id, id))
+      .returning();
+    return result.length > 0;
+  }
+
+  async activate(id: string, ctx?: TxContext): Promise<Promotion | undefined> {
+    return this.update(id, { isActive: true }, ctx);
+  }
+
+  async deactivate(
+    id: string,
+    ctx?: TxContext,
+  ): Promise<Promotion | undefined> {
+    return this.update(id, { isActive: false }, ctx);
+  }
+
+  // ─────────────────────────────────────────────────────────────────────────────
+  // Promotion Usages
+  // ─────────────────────────────────────────────────────────────────────────────
+
+  async findUsageById(
+    id: string,
+    ctx?: TxContext,
+  ): Promise<PromotionUsage | undefined> {
+    const db = this.getDb(ctx);
+    const rows = await db
+      .select()
+      .from(promotionUsages)
+      .where(eq(promotionUsages.id, id));
+    return rows[0];
+  }
+
+  async findUsagesByPromotionId(
+    promotionId: string,
+    ctx?: TxContext,
+  ): Promise<PromotionUsage[]> {
+    const db = this.getDb(ctx);
+    return db
+      .select()
+      .from(promotionUsages)
+      .where(eq(promotionUsages.promotionId, promotionId));
+  }
+
+  async findUsagesByCustomerId(
+    customerId: string,
+    ctx?: TxContext,
+  ): Promise<PromotionUsage[]> {
+    const db = this.getDb(ctx);
+    return db
+      .select()
+      .from(promotionUsages)
+      .where(eq(promotionUsages.customerId, customerId));
+  }
+
+  async createUsage(
+    data: PromotionUsageInsert,
+    ctx?: TxContext,
+  ): Promise<PromotionUsage> {
+    const db = this.getDb(ctx);
+
+    // Atomic guard: use INSERT ... SELECT WHERE count < limit to prevent
+    // race conditions between concurrent checkouts using the same coupon.
+    // A plain count-then-insert has a TOCTOU gap; this single statement
+    // ensures the insert only succeeds if the limit has not been reached.
+    const promo = await db
+      .select({ usageLimitTotal: promotions.usageLimitTotal })
+      .from(promotions)
+      .where(eq(promotions.id, data.promotionId));
+
+    const limit = promo[0]?.usageLimitTotal;
+
+    if (limit != null) {
+      // Atomic guard: lock the promotion row and check usage count in the
+      // same statement sequence. This prevents two concurrent checkouts
+      // from both passing the count check (TOCTOU race).
+      //
+      // SELECT ... FOR UPDATE acquires a row-level lock that serializes
+      // concurrent callers. If the caller is already inside a transaction
+      // (ctx.tx), the lock is held until that transaction commits.
+      await db.execute(
+        sql`SELECT id FROM promotions WHERE id = ${data.promotionId} FOR UPDATE`,
+      );
+
+      const currentCount = await this.countUsages(data.promotionId, ctx);
+      if (currentCount >= limit) {
+        throw new Error(`Promotion usage limit reached (${currentCount}/${limit})`);
+      }
+
+      const rows = await db.insert(promotionUsages).values(data).returning();
+      return rows[0]!;
+    }
+
+    const rows = await db.insert(promotionUsages).values(data).returning();
+    return rows[0]!;
+  }
+
+  async countUsages(promotionId: string, ctx?: TxContext): Promise<number> {
+    const db = this.getDb(ctx);
+    const result = await db
+      .select({ count: sql<number>`count(*)::int` })
+      .from(promotionUsages)
+      .where(eq(promotionUsages.promotionId, promotionId));
+    return result[0]?.count ?? 0;
+  }
+
+  async countUsagesByCustomer(
+    promotionId: string,
+    customerId: string,
+    ctx?: TxContext,
+  ): Promise<number> {
+    const db = this.getDb(ctx);
+    const result = await db
+      .select({ count: sql<number>`count(*)::int` })
+      .from(promotionUsages)
+      .where(
+        and(
+          eq(promotionUsages.promotionId, promotionId),
+          eq(promotionUsages.customerId, customerId),
+        ),
+      );
+    return result[0]?.count ?? 0;
+  }
+
+  // ─────────────────────────────────────────────────────────────────────────────
+  // Validation Helpers
+  // ─────────────────────────────────────────────────────────────────────────────
+
+  async isUsageLimitReached(
+    orgId: string,
+    promotionId: string,
+    ctx?: TxContext,
+  ): Promise<boolean> {
+    const promotion = await this.findById(orgId, promotionId, ctx);
+    if (!promotion || promotion.usageLimitTotal === null) {
+      return false;
+    }
+    const count = await this.countUsages(promotionId, ctx);
+    return count >= promotion.usageLimitTotal;
+  }
+
+  async isCustomerUsageLimitReached(
+    orgId: string,
+    promotionId: string,
+    customerId: string,
+    ctx?: TxContext,
+  ): Promise<boolean> {
+    const promotion = await this.findById(orgId, promotionId, ctx);
+    if (!promotion || promotion.usageLimitPerCustomer === null) {
+      return false;
+    }
+    const count = await this.countUsagesByCustomer(
+      promotionId,
+      customerId,
+      ctx,
+    );
+    return count >= promotion.usageLimitPerCustomer;
+  }
+
+  async isPromotionValid(
+    orgId: string,
+    promotionId: string,
+    customerId?: string,
+    ctx?: TxContext,
+  ): Promise<{ valid: boolean; reason?: string }> {
+    const promotion = await this.findById(orgId, promotionId, ctx);
+
+    if (!promotion) {
+      return { valid: false, reason: "Promotion not found" };
+    }
+
+    if (!promotion.isActive) {
+      return { valid: false, reason: "Promotion is not active" };
+    }
+
+    const now = new Date();
+    if (promotion.validFrom && promotion.validFrom > now) {
+      return { valid: false, reason: "Promotion has not started yet" };
+    }
+
+    if (promotion.validUntil && promotion.validUntil < now) {
+      return { valid: false, reason: "Promotion has expired" };
+    }
+
+    if (await this.isUsageLimitReached(orgId, promotionId, ctx)) {
+      return { valid: false, reason: "Promotion usage limit reached" };
+    }
+
+    if (
+      customerId &&
+      (await this.isCustomerUsageLimitReached(orgId, promotionId, customerId, ctx))
+    ) {
+      return { valid: false, reason: "Customer usage limit reached" };
+    }
+
+    return { valid: true };
+  }
+}

package/src/modules/promotions/schema.ts

@@ -0,0 +1,62 @@
+import { boolean, index, integer, jsonb, pgTable, text, timestamp, uniqueIndex, uuid } from "drizzle-orm/pg-core";
+import { organization } from "../../auth/auth-schema.js";
+
+export const promotions = pgTable(
+  "promotions",
+  {
+    id: uuid("id").defaultRandom().primaryKey(),
+    organizationId: text("organization_id")
+      .notNull()
+      .references(() => organization.id, { onDelete: "cascade" }),
+    code: text("code"),
+    name: text("name").notNull(),
+    type: text("type", {
+      enum: [
+        "percentage_off_order",
+        "fixed_off_order",
+        "percentage_off_item",
+        "fixed_off_item",
+        "free_shipping",
+        "buy_x_get_y",
+      ],
+    }).notNull(),
+    value: integer("value").notNull().default(0),
+    buyQuantity: integer("buy_quantity"),
+    getQuantity: integer("get_quantity"),
+    isAutomatic: boolean("is_automatic").notNull().default(false),
+    isActive: boolean("is_active").notNull().default(true),
+    priority: integer("priority").notNull().default(100),
+    conditions: jsonb("conditions").$type<Record<string, unknown>>().default({}),
+    usageLimitTotal: integer("usage_limit_total"),
+    usageLimitPerCustomer: integer("usage_limit_per_customer"),
+    validFrom: timestamp("valid_from", { withTimezone: true }),
+    validUntil: timestamp("valid_until", { withTimezone: true }),
+    metadata: jsonb("metadata").$type<Record<string, unknown>>().default({}),
+    createdAt: timestamp("created_at", { withTimezone: true }).defaultNow().notNull(),
+    updatedAt: timestamp("updated_at", { withTimezone: true }).defaultNow().notNull(),
+  },
+  (table) => ({
+    codeIdx: index("idx_promotions_code").on(table.code),
+    activePriorityIdx: index("idx_promotions_active_priority").on(table.isActive, table.priority),
+    validityIdx: index("idx_promotions_validity").on(table.validFrom, table.validUntil),
+    orgIdx: index("idx_promotions_org").on(table.organizationId),
+    orgCodeUnique: uniqueIndex("promotions_org_code_unique").on(table.organizationId, table.code),
+  }),
+);
+
+export const promotionUsages = pgTable(
+  "promotion_usages",
+  {
+    id: uuid("id").defaultRandom().primaryKey(),
+    promotionId: uuid("promotion_id")
+      .references(() => promotions.id, { onDelete: "cascade" })
+      .notNull(),
+    customerId: uuid("customer_id"),
+    orderId: uuid("order_id"),
+    usedAt: timestamp("used_at", { withTimezone: true }).defaultNow().notNull(),
+  },
+  (table) => ({
+    promotionIdx: index("idx_promotion_usage_promotion").on(table.promotionId),
+    customerIdx: index("idx_promotion_usage_customer").on(table.customerId),
+  }),
+);

package/src/modules/promotions/schemas.ts

@@ -0,0 +1,38 @@
+import { z } from "@hono/zod-openapi";
+
+// ─── Zod Body Schemas (single source of truth) ─────────────────────────────
+
+export const CreatePromotionBodySchema = z.object({
+  name: z.string().openapi({ example: "Summer Sale" }),
+  type: z.enum([
+    "percentage_off_order",
+    "fixed_off_order",
+    "percentage_off_item",
+    "fixed_off_item",
+    "free_shipping",
+    "buy_x_get_y",
+  ]).openapi({ example: "percentage_off_order" }),
+  value: z.number().openapi({ example: 10 }),
+  code: z.string().optional().openapi({ example: "SUMMER10" }),
+  buyQuantity: z.number().int().optional(),
+  getQuantity: z.number().int().optional(),
+  isAutomatic: z.boolean().optional(),
+  isActive: z.boolean().optional(),
+  priority: z.number().int().optional(),
+  conditions: z.object({
+    minimumOrderValue: z.number().optional(),
+    minimumQuantity: z.number().int().optional(),
+    entityTypes: z.array(z.string()).optional(),
+    categories: z.array(z.string()).optional(),
+    customerGroups: z.array(z.string()).optional(),
+  }).optional(),
+  usageLimitTotal: z.number().int().optional(),
+  usageLimitPerCustomer: z.number().int().optional(),
+  validFrom: z.coerce.date().optional(),
+  validUntil: z.coerce.date().optional(),
+  metadata: z.record(z.string(), z.unknown()).optional(),
+}).openapi("CreatePromotionRequest");
+
+// ─── Derived Input Types ────────────────────────────────────────────────────
+
+export type CreatePromotionInput = z.infer<typeof CreatePromotionBodySchema>;