@unifiedcommerce/plugin-giftcards 0.0.1

package/src/routes/customer.ts

@@ -0,0 +1,30 @@
+import { router } from "@unifiedcommerce/core";
+import type { GiftCardService } from "../services/gift-card-service";
+import type { PluginRouteRegistration } from "@unifiedcommerce/core";
+import { formatCode } from "../code-generator";
+
+export function buildCustomerRoutes(
+  service: GiftCardService,
+  ctx: { services?: Record<string, unknown>; database?: { db: unknown } },
+): PluginRouteRegistration[] {
+  const r = router("Gift Cards (Customer)", "/me/gift-cards", ctx);
+
+  // ─── List Customer's Gift Cards ───────────────────────────────────
+
+  r.get("/")
+    .summary("List my gift cards")
+    .auth()
+    .handler(async ({ actor, orgId }) => {
+      if (!actor) throw new Error("Unauthorized");
+      const result = await service.list(orgId, { purchaserId: actor.userId });
+      if (!result.ok) throw new Error("Failed to list gift cards");
+      return result.value.map((card) => ({
+        ...card,
+        displayCode: formatCode(card.code),
+        // Mask the full code for security — show only last 4 chars
+        maskedCode: `****-****-****-${card.code.slice(-4)}`,
+      }));
+    });
+
+  return r.routes();
+}

package/src/routes/public.ts

@@ -0,0 +1,31 @@
+import { router } from "@unifiedcommerce/core";
+import { z } from "@hono/zod-openapi";
+import type { GiftCardService } from "../services/gift-card-service";
+import type { PluginRouteRegistration } from "@unifiedcommerce/core";
+
+export function buildPublicRoutes(
+  service: GiftCardService,
+  ctx: { services?: Record<string, unknown>; database?: { db: unknown } },
+): PluginRouteRegistration[] {
+  const r = router("Gift Cards", "/gift-cards", ctx);
+
+  // ─── Check Balance (Public) ───────────────────────────────────────
+
+  r.post("/check-balance")
+    .summary("Check gift card balance")
+    .description("Public endpoint — no authentication required. Rate-limited.")
+    .input(
+      z.object({
+        code: z.string().min(4).max(30).describe("Gift card code (hyphens optional)"),
+      }),
+    )
+    .handler(async ({ input }) => {
+      const body = input as { code: string };
+      // Public endpoint: codes are globally unique, no org scoping needed
+      const result = await service.checkBalance("_any", body.code);
+      if (!result.ok) throw new Error(result.error);
+      return result.value;
+    });
+
+  return r.routes();
+}

package/src/schema.ts

@@ -0,0 +1,89 @@
+import {
+  pgTable,
+  uuid,
+  text,
+  integer,
+  boolean,
+  timestamp,
+  jsonb,
+  index,
+  check,
+  uniqueIndex,
+} from "drizzle-orm/pg-core";
+import { sql } from "drizzle-orm";
+
+// ─── Gift Cards ──────────────────────────────────────────────────────────────
+
+export const giftCards = pgTable(
+  "gift_cards",
+  {
+    id: uuid("id").defaultRandom().primaryKey(),
+    organizationId: text("organization_id").notNull(),
+    code: text("code").notNull(),
+    initialAmount: integer("initial_amount").notNull(),
+    balance: integer("balance").notNull(),
+    currency: text("currency").notNull(),
+    status: text("status", {
+      enum: ["active", "disabled", "exhausted"],
+    })
+      .notNull()
+      .default("active"),
+    purchaserId: text("purchaser_id"),
+    recipientEmail: text("recipient_email"),
+    senderName: text("sender_name"),
+    personalMessage: text("personal_message"),
+    sourceOrderId: text("source_order_id"),
+    expiresAt: timestamp("expires_at", { withTimezone: true }),
+    version: integer("version").notNull().default(0),
+    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) => ({
+    orgCodeUnique: uniqueIndex("gift_cards_org_code_unique").on(table.organizationId, table.code),
+    orgIdx: index("idx_gift_cards_org").on(table.organizationId),
+    codeIdx: index("idx_gift_cards_code").on(table.code),
+    purchaserIdx: index("idx_gift_cards_purchaser").on(table.purchaserId),
+    statusIdx: index("idx_gift_cards_status").on(table.status),
+    balanceCheck: check(
+      "gift_cards_balance_non_negative",
+      sql`${table.balance} >= 0`,
+    ),
+    initialAmountCheck: check(
+      "gift_cards_initial_amount_positive",
+      sql`${table.initialAmount} > 0`,
+    ),
+  }),
+);
+
+// ─── Gift Card Transactions ─────────────────────────────────────────────────
+
+export const giftCardTransactions = pgTable(
+  "gift_card_transactions",
+  {
+    id: uuid("id").defaultRandom().primaryKey(),
+    giftCardId: uuid("gift_card_id")
+      .notNull()
+      .references(() => giftCards.id, { onDelete: "cascade" }),
+    type: text("type", {
+      enum: ["debit", "credit", "refund"],
+    }).notNull(),
+    amount: integer("amount").notNull(),
+    balanceAfter: integer("balance_after").notNull(),
+    orderId: text("order_id"),
+    note: text("note"),
+    createdAt: timestamp("created_at", { withTimezone: true })
+      .defaultNow()
+      .notNull(),
+  },
+  (table) => ({
+    cardIdx: index("idx_gc_txn_card").on(table.giftCardId),
+    orderIdx: index("idx_gc_txn_order").on(table.orderId),
+  }),
+);

package/src/services/gift-card-repository.ts

@@ -0,0 +1,157 @@
+import { eq, desc, and } from "drizzle-orm";
+import { giftCards, giftCardTransactions } from "../schema";
+import type { Db, GiftCard, GiftCardInsert, GiftCardTransaction, GiftCardStatus, TransactionType } from "../types";
+
+export class GiftCardRepository {
+  constructor(private db: Db) {}
+
+  private getDb(ctx?: { tx?: Db }): Db {
+    return ctx?.tx ?? this.db;
+  }
+
+  // ─── Gift Card CRUD ─────────────────────────────────────────────────
+
+  async create(data: GiftCardInsert, ctx?: { tx?: Db }): Promise<GiftCard> {
+    const rows = await this.getDb(ctx)
+      .insert(giftCards)
+      .values(data)
+      .returning();
+    return rows[0]!;
+  }
+
+  async findById(id: string, ctx?: { tx?: Db }): Promise<GiftCard | undefined> {
+    const rows = await this.getDb(ctx)
+      .select()
+      .from(giftCards)
+      .where(eq(giftCards.id, id));
+    return rows[0];
+  }
+
+  async findByCode(code: string, ctx?: { tx?: Db }): Promise<GiftCard | undefined> {
+    const rows = await this.getDb(ctx)
+      .select()
+      .from(giftCards)
+      .where(eq(giftCards.code, code));
+    return rows[0];
+  }
+
+  async list(
+    filters?: { status?: GiftCardStatus; purchaserId?: string },
+    ctx?: { tx?: Db },
+  ): Promise<GiftCard[]> {
+    const conditions = [];
+    if (filters?.status) conditions.push(eq(giftCards.status, filters.status));
+    if (filters?.purchaserId) conditions.push(eq(giftCards.purchaserId, filters.purchaserId));
+
+    return this.getDb(ctx)
+      .select()
+      .from(giftCards)
+      .where(conditions.length > 0 ? and(...conditions) : undefined)
+      .orderBy(desc(giftCards.createdAt));
+  }
+
+  async disable(id: string, ctx?: { tx?: Db }): Promise<GiftCard | undefined> {
+    const rows = await this.getDb(ctx)
+      .update(giftCards)
+      .set({ status: "disabled" as const, updatedAt: new Date() })
+      .where(eq(giftCards.id, id))
+      .returning();
+    return rows[0];
+  }
+
+  // ─── SELECT FOR UPDATE (Concurrency-Safe Balance Operations) ───────
+
+  async findByCodeForUpdate(code: string, tx: Db): Promise<GiftCard | undefined> {
+    const rows = await tx
+      .select()
+      .from(giftCards)
+      .where(eq(giftCards.code, code))
+      .for("update");
+    return rows[0];
+  }
+
+  async findByIdForUpdate(id: string, tx: Db): Promise<GiftCard | undefined> {
+    const rows = await tx
+      .select()
+      .from(giftCards)
+      .where(eq(giftCards.id, id))
+      .for("update");
+    return rows[0];
+  }
+
+  async updateBalance(
+    id: string,
+    balance: number,
+    status: GiftCardStatus,
+    currentVersion: number,
+    tx: Db,
+  ): Promise<GiftCard> {
+    const rows = await tx
+      .update(giftCards)
+      .set({
+        balance,
+        status,
+        version: currentVersion + 1,
+        updatedAt: new Date(),
+      })
+      .where(eq(giftCards.id, id))
+      .returning();
+    return rows[0]!;
+  }
+
+  async adjustBalance(
+    id: string,
+    delta: number,
+    tx: Db,
+  ): Promise<GiftCard> {
+    const card = await this.findByIdForUpdate(id, tx);
+    if (!card) throw new Error("Gift card not found");
+
+    const newBalance = Math.max(0, Math.min(card.initialAmount, card.balance + delta));
+    const newStatus: GiftCardStatus = newBalance === 0 ? "exhausted" : "active";
+
+    return this.updateBalance(id, newBalance, newStatus, card.version, tx);
+  }
+
+  // ─── Transactions ───────────────────────────────────────────────────
+
+  async recordTransaction(
+    data: {
+      giftCardId: string;
+      type: TransactionType;
+      amount: number;
+      balanceAfter: number;
+      orderId?: string;
+      note?: string;
+    },
+    ctx?: { tx?: Db },
+  ): Promise<GiftCardTransaction> {
+    const rows = await this.getDb(ctx)
+      .insert(giftCardTransactions)
+      .values(data)
+      .returning();
+    return rows[0]!;
+  }
+
+  async listTransactions(
+    giftCardId: string,
+    ctx?: { tx?: Db },
+  ): Promise<GiftCardTransaction[]> {
+    return this.getDb(ctx)
+      .select()
+      .from(giftCardTransactions)
+      .where(eq(giftCardTransactions.giftCardId, giftCardId))
+      .orderBy(desc(giftCardTransactions.createdAt));
+  }
+
+  async findTransactionsByOrderId(
+    orderId: string,
+    ctx?: { tx?: Db },
+  ): Promise<GiftCardTransaction[]> {
+    return this.getDb(ctx)
+      .select()
+      .from(giftCardTransactions)
+      .where(eq(giftCardTransactions.orderId, orderId))
+      .orderBy(desc(giftCardTransactions.createdAt));
+  }
+}

package/src/services/gift-card-service.ts

@@ -0,0 +1,286 @@
+import { Ok, Err } from "@unifiedcommerce/core";
+import type { PluginResult } from "@unifiedcommerce/core";
+import { generateGiftCardCode, normalizeCode } from "../code-generator";
+import { GiftCardRepository } from "./gift-card-repository";
+import type {
+  Db,
+  GiftCard,
+  GiftCardDeduction,
+  GiftCardPluginOptions,
+  GiftCardTransaction,
+  GiftCardStatus,
+  TransactionType,
+} from "../types";
+
+export class GiftCardService {
+  private repo: GiftCardRepository;
+  private transaction: (fn: (tx: Db) => Promise<unknown>) => Promise<unknown>;
+
+  constructor(
+    db: Db,
+    transactionFn: (fn: (tx: Db) => Promise<unknown>) => Promise<unknown>,
+    private options: Required<GiftCardPluginOptions>,
+  ) {
+    this.repo = new GiftCardRepository(db);
+    this.transaction = transactionFn;
+  }
+
+  // ─── Create ──────────────────────────────────────────────────────────
+
+  async create(orgId: string, input: {
+    amount: number;
+    currency: string;
+    purchaserId?: string;
+    recipientEmail?: string;
+    senderName?: string;
+    personalMessage?: string;
+    sourceOrderId?: string;
+    metadata?: Record<string, unknown>;
+  }): Promise<PluginResult<GiftCard>> {
+    if (input.amount <= 0) {
+      return Err("Amount must be positive");
+    }
+    if (input.amount > this.options.maxBalancePerCard) {
+      return Err(`Amount exceeds maximum of ${this.options.maxBalancePerCard}`);
+    }
+
+    // Generate unique code with collision retry
+    let code: string;
+    let attempts = 0;
+    do {
+      code = normalizeCode(generateGiftCardCode(this.options.codeFormat));
+      const existing = await this.repo.findByCode(code);
+      if (!existing) break;
+      attempts++;
+    } while (attempts < 10);
+
+    if (attempts >= 10) {
+      return Err("Failed to generate unique code after 10 attempts");
+    }
+
+    const expiresAt = this.options.defaultExpiryDays
+      ? new Date(Date.now() + this.options.defaultExpiryDays * 24 * 60 * 60 * 1000)
+      : undefined;
+
+    const card = await this.repo.create({
+      organizationId: orgId,
+      code,
+      initialAmount: input.amount,
+      balance: input.amount,
+      currency: input.currency.toUpperCase(),
+      purchaserId: input.purchaserId,
+      recipientEmail: input.recipientEmail,
+      senderName: input.senderName,
+      personalMessage: input.personalMessage,
+      sourceOrderId: input.sourceOrderId,
+      expiresAt,
+      metadata: input.metadata ?? {},
+    });
+
+    // Record initial credit transaction
+    await this.repo.recordTransaction({
+      giftCardId: card.id,
+      type: "credit" as const,
+      amount: input.amount,
+      balanceAfter: input.amount,
+      note: "Initial load",
+    });
+
+    return Ok(card);
+  }
+
+  // ─── Query ───────────────────────────────────────────────────────────
+
+  async getById(orgId: string, id: string): Promise<PluginResult<GiftCard>> {
+    const card = await this.repo.findById(id);
+    if (!card) return Err("Gift card not found");
+    return Ok(card);
+  }
+
+  async getByCode(orgId: string, code: string): Promise<PluginResult<GiftCard>> {
+    const card = await this.repo.findByCode(normalizeCode(code));
+    if (!card) return Err("Gift card not found");
+    return Ok(card);
+  }
+
+  async list(orgId: string, filters?: {
+    status?: GiftCardStatus;
+    purchaserId?: string;
+  }): Promise<PluginResult<GiftCard[]>> {
+    const cards = await this.repo.list(filters);
+    return Ok(cards);
+  }
+
+  async getTransactions(
+    orgId: string,
+    giftCardId: string,
+  ): Promise<PluginResult<GiftCardTransaction[]>> {
+    const txns = await this.repo.listTransactions(giftCardId);
+    return Ok(txns);
+  }
+
+  // ─── Balance Check (Public) ──────────────────────────────────────────
+
+  async checkBalance(orgId: string, code: string): Promise<PluginResult<{
+    balance: number;
+    currency: string;
+    status: string;
+  }>> {
+    const card = await this.repo.findByCode(normalizeCode(code));
+    if (!card) return Err("Gift card not found");
+
+    return Ok({
+      balance: card.balance,
+      currency: card.currency,
+      status: card.status,
+    });
+  }
+
+  // ─── Debit (Concurrency-Safe) ────────────────────────────────────────
+
+  /**
+   * Debit a gift card balance within a transaction.
+   * Uses SELECT FOR UPDATE to prevent double-spend.
+   */
+  async debitWithLock(
+    orgId: string,
+    code: string,
+    amount: number,
+    orderId: string,
+    currency: string,
+  ): Promise<PluginResult<GiftCardDeduction>> {
+    if (amount <= 0) return Err("Debit amount must be positive");
+
+    const result = await this.transaction(async (tx) => {
+      const card = await this.repo.findByCodeForUpdate(normalizeCode(code), tx);
+      if (!card) return Err("GIFT_CARD_NOT_FOUND");
+      if (card.status === "disabled") return Err("GIFT_CARD_INACTIVE");
+      if (card.status === "exhausted") return Err("GIFT_CARD_EXHAUSTED");
+      if (card.expiresAt && card.expiresAt < new Date()) return Err("GIFT_CARD_EXPIRED");
+      if (card.currency !== currency.toUpperCase()) return Err("CURRENCY_MISMATCH");
+      if (card.balance < amount) return Err("INSUFFICIENT_BALANCE");
+
+      const balanceAfter = card.balance - amount;
+      const newStatus: GiftCardStatus = balanceAfter === 0 ? "exhausted" : "active";
+
+      await this.repo.updateBalance(card.id, balanceAfter, newStatus, card.version, tx);
+      await this.repo.recordTransaction(
+        {
+          giftCardId: card.id,
+          type: "debit" as const,
+          amount,
+          balanceAfter,
+          orderId,
+        },
+        { tx },
+      );
+
+      return Ok({
+        code: card.code,
+        giftCardId: card.id,
+        amount,
+        balanceAfter,
+      });
+    });
+
+    return result as PluginResult<GiftCardDeduction>;
+  }
+
+  // ─── Credit (Concurrency-Safe) ───────────────────────────────────────
+
+  /**
+   * Credit a gift card balance (refund/compensation).
+   * Uses SELECT FOR UPDATE. Cannot exceed initial_amount.
+   */
+  async creditWithLock(
+    orgId: string,
+    code: string,
+    amount: number,
+    orderId: string,
+    note: string,
+  ): Promise<PluginResult<{ balanceAfter: number }>> {
+    if (amount <= 0) return Err("Credit amount must be positive");
+
+    const result = await this.transaction(async (tx) => {
+      const card = await this.repo.findByCodeForUpdate(normalizeCode(code), tx);
+      if (!card) return Err("GIFT_CARD_NOT_FOUND");
+
+      // Cap credit at initial amount (prevent inflation attack)
+      const balanceAfter = Math.min(card.initialAmount, card.balance + amount);
+      const actualCredit = balanceAfter - card.balance;
+
+      if (actualCredit <= 0) {
+        return Ok({ balanceAfter: card.balance });
+      }
+
+      const newStatus: GiftCardStatus = balanceAfter > 0 ? "active" : card.status;
+
+      await this.repo.updateBalance(card.id, balanceAfter, newStatus, card.version, tx);
+      await this.repo.recordTransaction(
+        {
+          giftCardId: card.id,
+          type: "refund" as const,
+          amount: actualCredit,
+          balanceAfter,
+          orderId,
+          note,
+        },
+        { tx },
+      );
+
+      return Ok({ balanceAfter });
+    });
+
+    return result as PluginResult<{ balanceAfter: number }>;
+  }
+
+  // ─── Admin Operations ────────────────────────────────────────────────
+
+  async disable(orgId: string, id: string): Promise<PluginResult<GiftCard>> {
+    const card = await this.repo.disable(id);
+    if (!card) return Err("Gift card not found");
+    return Ok(card);
+  }
+
+  async adjust(
+    orgId: string,
+    id: string,
+    delta: number,
+    note: string,
+  ): Promise<PluginResult<GiftCard>> {
+    const result = await this.transaction(async (tx) => {
+      const card = await this.repo.findByIdForUpdate(id, tx);
+      if (!card) return Err("Gift card not found");
+
+      const newBalance = Math.max(0, Math.min(card.initialAmount, card.balance + delta));
+      const actualDelta = newBalance - card.balance;
+      const newStatus: GiftCardStatus = newBalance === 0 ? "exhausted" : "active";
+
+      const updated = await this.repo.updateBalance(
+        card.id,
+        newBalance,
+        newStatus,
+        card.version,
+        tx,
+      );
+
+      if (actualDelta !== 0) {
+        const txnType: TransactionType = actualDelta > 0 ? "credit" : "debit";
+        await this.repo.recordTransaction(
+          {
+            giftCardId: card.id,
+            type: txnType,
+            amount: Math.abs(actualDelta),
+            balanceAfter: newBalance,
+            note,
+          },
+          { tx },
+        );
+      }
+
+      return Ok(updated);
+    });
+
+    return result as PluginResult<GiftCard>;
+  }
+}

package/src/types.ts

@@ -0,0 +1,41 @@
+export type { PluginDb as Db } from "@unifiedcommerce/core";
+import type { giftCards, giftCardTransactions } from "./schema";
+
+export type GiftCard = typeof giftCards.$inferSelect;
+export type GiftCardInsert = typeof giftCards.$inferInsert;
+export type GiftCardTransaction = typeof giftCardTransactions.$inferSelect;
+export type GiftCardTransactionInsert = typeof giftCardTransactions.$inferInsert;
+
+export type GiftCardStatus = "active" | "disabled" | "exhausted";
+export type TransactionType = "debit" | "credit" | "refund";
+
+export interface GiftCardPluginOptions {
+  /** Code format pattern. Default: "XXXX-XXXX-XXXX-XXXX" */
+  codeFormat?: string;
+  /** Default expiry duration in days. null = no expiry. Default: null */
+  defaultExpiryDays?: number | null;
+  /** Maximum balance per card in minor units. Default: 10_000_00 (100,000.00) */
+  maxBalancePerCard?: number;
+  /** Email template name for gift card delivery. Default: "gift-card-delivery" */
+  emailTemplate?: string;
+  /** Allow partial redemption. Default: true */
+  allowPartialRedemption?: boolean;
+  /** Entity type that triggers gift card issuance on purchase. Default: "gift_card" */
+  productType?: string;
+}
+
+export const DEFAULT_OPTIONS: Required<GiftCardPluginOptions> = {
+  codeFormat: "XXXX-XXXX-XXXX-XXXX",
+  defaultExpiryDays: null as unknown as number,
+  maxBalancePerCard: 10_000_00,
+  emailTemplate: "gift-card-delivery",
+  allowPartialRedemption: true,
+  productType: "gift_card",
+};
+
+export interface GiftCardDeduction {
+  code: string;
+  giftCardId: string;
+  amount: number;
+  balanceAfter: number;
+}