@porulle/plugin-giftcards 0.1.0

package/src/hooks/refund-credit.ts

@@ -0,0 +1,56 @@
+import { resolveOrgId } from "@porulle/core";
+import type { PluginHookRegistration } from "@porulle/core";
+import type { GiftCardService } from "../services/gift-card-service.js";
+import type { GiftCardDeduction } from "../types.js";
+
+interface HookContextLike {
+  actor: { organizationId?: string | null; [key: string]: unknown } | null;
+  [key: string]: unknown;
+}
+
+interface OrderUpdateHookArgs {
+  data: unknown;
+  result: {
+    id: string;
+    status?: string;
+    metadata?: Record<string, unknown> | null;
+  } | null;
+  context: HookContextLike;
+}
+
+/**
+ * order.afterUpdate hook — restores gift card balances when an order is refunded.
+ */
+export function buildRefundCreditHook(
+  service: GiftCardService,
+): PluginHookRegistration {
+  const handler = async (args: OrderUpdateHookArgs) => {
+    const { result, context } = args;
+    if (!result) return;
+
+    const status = result.status;
+    if (status !== "refunded" && status !== "cancelled") return;
+
+    const deductions = result.metadata?.giftCardDeductions as
+      | GiftCardDeduction[]
+      | undefined;
+
+    if (!deductions?.length) return;
+
+    const orgId = resolveOrgId(context.actor);
+    for (const d of deductions) {
+      await service.creditWithLock(
+        orgId,
+        d.code,
+        d.amount,
+        result.id,
+        `Order ${status} — balance restored`,
+      );
+    }
+  };
+
+  return {
+    key: "order.afterUpdate",
+    handler: handler as (...args: unknown[]) => unknown,
+  };
+}

package/src/index.ts

@@ -0,0 +1,148 @@
+import { defineCommercePlugin } from "@porulle/core";
+import { giftCards, giftCardTransactions } from "./schema.js";
+import { GiftCardService } from "./services/gift-card-service.js";
+import {
+  buildCheckoutDeductionHook,
+  buildCheckoutCompensationHook,
+} from "./hooks/checkout-deduction.js";
+import { buildGiftCardIssuanceHook } from "./hooks/checkout-issuance.js";
+import { buildRefundCreditHook } from "./hooks/refund-credit.js";
+import { buildAdminRoutes } from "./routes/admin.js";
+import { buildPublicRoutes } from "./routes/public.js";
+import { buildCustomerRoutes } from "./routes/customer.js";
+import type { GiftCardPluginOptions } from "./types.js";
+import { DEFAULT_OPTIONS } from "./types.js";
+
+export type { GiftCardPluginOptions } from "./types.js";
+export { GiftCardService } from "./services/gift-card-service.js";
+
+export function giftCardPlugin(userOptions: GiftCardPluginOptions = {}) {
+  const options: Required<GiftCardPluginOptions> = {
+    ...DEFAULT_OPTIONS,
+    ...userOptions,
+    // Preserve null for defaultExpiryDays when user doesn't set it
+    defaultExpiryDays: userOptions.defaultExpiryDays ?? DEFAULT_OPTIONS.defaultExpiryDays,
+  };
+
+  return defineCommercePlugin({
+    id: "gift-cards",
+    version: "1.0.0",
+
+    permissions: [
+      {
+        scope: "gift-cards:admin",
+        description:
+          "Create, list, disable, and adjust gift cards. Required for all admin routes.",
+      },
+    ],
+
+    schema: () => ({
+      giftCards,
+      giftCardTransactions,
+    }),
+
+    hooks: () => {
+      // Hooks are registered before the service is available (no DB context).
+      // They will be populated with the real service in routes() where ctx is available.
+      // For now, return empty — we'll wire them up via a shared reference.
+      return [];
+    },
+
+    routes: (ctx) => {
+      const db = ctx.database.db;
+      if (!db) return [];
+
+      const service = new GiftCardService(
+        db,
+        ctx.database.transaction,
+        options,
+      );
+
+      return [
+        ...buildAdminRoutes(service, ctx),
+        ...buildPublicRoutes(service, ctx),
+        ...buildCustomerRoutes(service, ctx),
+      ];
+    },
+  });
+}
+
+/**
+ * Standalone factory for the plugin with hooks wired.
+ *
+ * Since hooks() runs before routes() (no DB context), we use a deferred
+ * service pattern: hooks capture a shared reference that gets populated
+ * when routes() runs with the real DB.
+ */
+export function giftCardPluginWithHooks(
+  userOptions: GiftCardPluginOptions = {},
+) {
+  const options: Required<GiftCardPluginOptions> = {
+    ...DEFAULT_OPTIONS,
+    ...userOptions,
+    defaultExpiryDays: userOptions.defaultExpiryDays ?? DEFAULT_OPTIONS.defaultExpiryDays,
+  };
+
+  // Shared mutable reference — populated when routes() runs
+  const serviceRef: { current: GiftCardService | null } = { current: null };
+
+  return defineCommercePlugin({
+    id: "gift-cards",
+    version: "1.0.0",
+
+    permissions: [
+      {
+        scope: "gift-cards:admin",
+        description:
+          "Create, list, disable, and adjust gift cards. Required for all admin routes.",
+      },
+    ],
+
+    schema: () => ({
+      giftCards,
+      giftCardTransactions,
+    }),
+
+    hooks: () => {
+      // Lazy proxy: defers to serviceRef.current once routes() initializes it.
+      // Uses Reflect.get for type-safe dynamic property access (no index signature needed).
+      const lazyService = new Proxy({} as GiftCardService, {
+        get(_target, prop, receiver) {
+          if (!serviceRef.current) {
+            throw new Error(
+              "Gift card service not initialized — hooks ran before routes()",
+            );
+          }
+          return Reflect.get(serviceRef.current, prop, receiver);
+        },
+      });
+
+      return [
+        buildCheckoutDeductionHook(lazyService),
+        buildCheckoutCompensationHook(lazyService),
+        buildGiftCardIssuanceHook(lazyService, options),
+        buildRefundCreditHook(lazyService),
+      ];
+    },
+
+    routes: (ctx) => {
+      const db = ctx.database.db;
+      if (!db) return [];
+
+      const service = new GiftCardService(
+        db,
+        ctx.database.transaction,
+        options,
+      );
+
+      // Wire up the shared reference so hooks can access the service
+      serviceRef.current = service;
+
+      return [
+        ...buildAdminRoutes(service, ctx),
+        ...buildPublicRoutes(service, ctx),
+        ...buildCustomerRoutes(service, ctx),
+      ];
+    },
+  });
+}

package/src/routes/admin.ts

@@ -0,0 +1,115 @@
+import { router } from "@porulle/core";
+import { z } from "@hono/zod-openapi";
+import type { GiftCardService } from "../services/gift-card-service.js";
+import type { PluginRouteRegistration } from "@porulle/core";
+import { formatCode } from "../code-generator.js";
+
+export function buildAdminRoutes(
+  service: GiftCardService,
+  ctx: { services?: Record<string, unknown>; database?: { db: unknown } },
+): PluginRouteRegistration[] {
+  const r = router("Gift Cards (Admin)", "/gift-cards", ctx);
+
+  // ─── Create Gift Card ─────────────────────────────────────────────
+
+  r.post("/")
+    .summary("Create gift card")
+    .permission("gift-cards:admin")
+    .input(
+      z.object({
+        amount: z.number().int().positive().describe("Amount in minor units (cents)"),
+        currency: z.string().min(3).max(3).describe("ISO 4217 currency code"),
+        recipientEmail: z.string().email().optional(),
+        senderName: z.string().optional(),
+        personalMessage: z.string().max(500).optional(),
+        metadata: z.record(z.string(), z.unknown()).optional(),
+      }),
+    )
+    .handler(async ({ input, orgId }) => {
+      const body = input as {
+        amount: number;
+        currency: string;
+        recipientEmail?: string;
+        senderName?: string;
+        personalMessage?: string;
+        metadata?: Record<string, unknown>;
+      };
+      const result = await service.create(orgId, body);
+      if (!result.ok) throw new Error(result.error);
+      return {
+        ...result.value,
+        displayCode: formatCode(result.value.code),
+      };
+    });
+
+  // ─── List Gift Cards ──────────────────────────────────────────────
+
+  r.get("/")
+    .summary("List gift cards")
+    .permission("gift-cards:admin")
+    .query(
+      z.object({
+        status: z.enum(["active", "disabled", "exhausted"]).optional(),
+        purchaserId: z.string().optional(),
+      }),
+    )
+    .handler(async ({ query, orgId }) => {
+      const q = query as { status?: string; purchaserId?: string };
+      const filters: { status?: "active" | "disabled" | "exhausted"; purchaserId?: string } = {};
+      if (q.status === "active" || q.status === "disabled" || q.status === "exhausted") {
+        filters.status = q.status;
+      }
+      if (q.purchaserId) filters.purchaserId = q.purchaserId;
+      const result = await service.list(orgId, filters);
+      if (!result.ok) throw new Error("Failed to list gift cards");
+      return result.value;
+    });
+
+  // ─── Get Gift Card by ID ──────────────────────────────────────────
+
+  r.get("/{id}")
+    .summary("Get gift card details")
+    .permission("gift-cards:admin")
+    .handler(async ({ params, orgId }) => {
+      const cardResult = await service.getById(orgId, params.id!);
+      if (!cardResult.ok) throw new Error(cardResult.error);
+
+      const txnResult = await service.getTransactions(orgId, cardResult.value.id);
+      return {
+        ...cardResult.value,
+        displayCode: formatCode(cardResult.value.code),
+        transactions: txnResult.ok ? txnResult.value : [],
+      };
+    });
+
+  // ─── Disable Gift Card ────────────────────────────────────────────
+
+  r.post("/{id}/disable")
+    .summary("Disable gift card")
+    .permission("gift-cards:admin")
+    .handler(async ({ params, orgId }) => {
+      const result = await service.disable(orgId, params.id!);
+      if (!result.ok) throw new Error(result.error);
+      return result.value;
+    });
+
+  // ─── Manual Balance Adjustment ────────────────────────────────────
+
+  r.post("/{id}/adjust")
+    .summary("Adjust gift card balance")
+    .permission("gift-cards:admin")
+    .input(
+      z.object({
+        delta: z.number().int().describe("Adjustment amount in minor units (positive=credit, negative=debit)"),
+        note: z.string().min(1).max(500).describe("Reason for adjustment"),
+      }),
+    )
+    .handler(async ({ params, input, orgId }) => {
+      const body = input as { delta: number; note: string };
+      const result = await service.adjust(orgId, params.id!, body.delta, body.note);
+      if (!result.ok) throw new Error(result.error);
+      return result.value;
+    });
+
+  return r.routes();
+}

package/src/routes/customer.ts

@@ -0,0 +1,30 @@
+import { router } from "@porulle/core";
+import type { GiftCardService } from "../services/gift-card-service.js";
+import type { PluginRouteRegistration } from "@porulle/core";
+import { formatCode } from "../code-generator.js";
+
+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 "@porulle/core";
+import { z } from "@hono/zod-openapi";
+import type { GiftCardService } from "../services/gift-card-service.js";
+import type { PluginRouteRegistration } from "@porulle/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 "@porulle/core/drizzle";
+import { sql } from "@porulle/core/drizzle";
+
+// ─── 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 "@porulle/core/drizzle";
+import { giftCards, giftCardTransactions } from "../schema.js";
+import type { Db, GiftCard, GiftCardInsert, GiftCardTransaction, GiftCardStatus, TransactionType } from "../types.js";
+
+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));
+  }
+}