@unifiedcommerce/plugin-giftcards 0.2.0 → 0.2.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unifiedcommerce/plugin-giftcards",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "type": "module",
   "exports": {
     ".": {
@@ -39,6 +39,7 @@
     "access": "public"
   },
   "files": [
+    "src",
     "dist",
     "README.md"
   ],

package/src/code-generator.ts

@@ -0,0 +1,79 @@
+import { randomBytes } from "node:crypto";
+
+/**
+ * Allowed characters for gift card codes.
+ * Excludes visually ambiguous characters: 0, O, 1, I, L
+ * Charset size: 30 → 30^16 ≈ 7.2 × 10^23 possible codes
+ */
+const CHARSET = "ABCDEFGHJKMNPQRSTUVWXYZ23456789";
+
+/**
+ * Generate a cryptographically secure gift card code.
+ *
+ * Format: XXXX-XXXX-XXXX-XXXX (16 alphanumeric chars)
+ * Uses crypto.randomBytes for uniform distribution.
+ *
+ * @param format - Pattern where X is replaced with a random char. Default: "XXXX-XXXX-XXXX-XXXX"
+ */
+export function generateGiftCardCode(format = "XXXX-XXXX-XXXX-XXXX"): string {
+  const charCount = (format.match(/X/g) ?? []).length;
+  // Request extra bytes to handle modulo bias rejection
+  const bytes = randomBytes(charCount * 2);
+
+  let byteIdx = 0;
+  let result = "";
+
+  for (const ch of format) {
+    if (ch === "X") {
+      // Rejection sampling to avoid modulo bias
+      // CHARSET.length = 30, so we reject values >= 240 (240 = 30 * 8)
+      let value: number;
+      do {
+        if (byteIdx >= bytes.length) {
+          // Extremely unlikely — generate more bytes
+          const extra = randomBytes(charCount);
+          for (let i = 0; i < extra.length; i++) {
+            bytes[byteIdx + i] = extra[i]!;
+          }
+        }
+        value = bytes[byteIdx++]!;
+      } while (value >= 240); // 240 = 30 * 8, ensures uniform distribution
+
+      result += CHARSET[value % CHARSET.length]!;
+    } else {
+      result += ch;
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Normalize a gift card code for database lookup.
+ * Strips hyphens/spaces and uppercases.
+ */
+export function normalizeCode(code: string): string {
+  return code.replace(/[-\s]/g, "").toUpperCase();
+}
+
+/**
+ * Format a raw code string into the display format.
+ */
+export function formatCode(raw: string, format = "XXXX-XXXX-XXXX-XXXX"): string {
+  const chars = raw.replace(/[-\s]/g, "").toUpperCase();
+  let charIdx = 0;
+  let result = "";
+
+  for (const ch of format) {
+    if (ch === "X" && charIdx < chars.length) {
+      result += chars[charIdx++];
+    } else if (ch !== "X") {
+      result += ch;
+    }
+  }
+
+  return result;
+}
+
+/** The character set used for code generation (for validation/testing) */
+export const CODE_CHARSET = CHARSET;

package/src/hooks/checkout-deduction.ts

@@ -0,0 +1,115 @@
+import { resolveOrgId } from "@unifiedcommerce/core";
+import type { PluginHookRegistration } from "@unifiedcommerce/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 CheckoutHookArgs {
+  data: {
+    total: number;
+    currency: string;
+    checkoutId: string;
+    metadata?: Record<string, unknown>;
+  };
+  context: HookContextLike;
+}
+
+interface AfterCreateHookArgs {
+  data: { metadata?: Record<string, unknown>; checkoutId: string };
+  result: unknown;
+  context: HookContextLike;
+}
+
+/**
+ * checkout.beforePayment hook — deducts gift card balances before the
+ * payment adapter authorizes the remaining amount.
+ */
+export function buildCheckoutDeductionHook(
+  service: GiftCardService,
+): PluginHookRegistration {
+  const handler = async (args: CheckoutHookArgs) => {
+    const { data, context } = args;
+    const orgId = resolveOrgId(context.actor);
+    const codes = data.metadata?.giftCardCodes as string[] | undefined;
+    if (!codes?.length) return data;
+
+    let remaining = data.total;
+    const deductions: GiftCardDeduction[] = [];
+
+    for (const code of codes) {
+      if (remaining <= 0) break;
+
+      const balanceResult = await service.checkBalance(orgId, code);
+      if (!balanceResult.ok) continue;
+
+      const deductAmount = Math.min(remaining, balanceResult.value.balance);
+      if (deductAmount <= 0) continue;
+
+      const result = await service.debitWithLock(
+        orgId,
+        code,
+        deductAmount,
+        data.checkoutId,
+        data.currency,
+      );
+
+      if (result.ok) {
+        deductions.push(result.value);
+        remaining -= deductAmount;
+      }
+    }
+
+    const giftCardTotal = deductions.reduce((sum, d) => sum + d.amount, 0);
+
+    return {
+      ...data,
+      total: Math.max(0, remaining),
+      metadata: {
+        ...data.metadata,
+        giftCardDeductions: deductions,
+        giftCardTotal,
+      },
+    };
+  };
+
+  return {
+    key: "checkout.beforePayment",
+    handler: handler as (...args: unknown[]) => unknown,
+  };
+}
+
+/**
+ * checkout.afterCreate hook — compensates gift card deductions if checkout fails.
+ */
+export function buildCheckoutCompensationHook(
+  service: GiftCardService,
+): PluginHookRegistration {
+  const handler = async (args: AfterCreateHookArgs) => {
+    const { data, result, context } = args;
+    const orgId = resolveOrgId(context.actor);
+    if (!result) {
+      const deductions = data.metadata?.giftCardDeductions as
+        | GiftCardDeduction[]
+        | undefined;
+
+      for (const d of deductions ?? []) {
+        await service.creditWithLock(
+          orgId,
+          d.code,
+          d.amount,
+          data.checkoutId,
+          "Checkout failed — balance restored",
+        );
+      }
+    }
+  };
+
+  return {
+    key: "checkout.afterCreate",
+    handler: handler as (...args: unknown[]) => unknown,
+  };
+}

package/src/hooks/checkout-issuance.ts

@@ -0,0 +1,93 @@
+import { resolveOrgId } from "@unifiedcommerce/core";
+import type { PluginHookRegistration } from "@unifiedcommerce/core";
+import type { GiftCardService } from "../services/gift-card-service.js";
+import type { GiftCardPluginOptions } from "../types.js";
+
+interface OrderLineItem {
+  entityId: string;
+  entityType?: string;
+  quantity: number;
+  unitPrice?: number;
+  totalPrice?: number;
+}
+
+interface OrderResult {
+  id: string;
+  customerId?: string | null;
+  currency: string;
+  lineItems?: OrderLineItem[];
+  metadata?: Record<string, unknown> | null;
+}
+
+interface HookContextLike {
+  actor: { organizationId?: string | null; [key: string]: unknown } | null;
+  [key: string]: unknown;
+}
+
+interface AfterCreateHookArgs {
+  data: unknown;
+  result: OrderResult | null;
+  context: HookContextLike;
+}
+
+/**
+ * checkout.afterCreate hook — issues gift cards when a gift card product is purchased.
+ */
+export function buildGiftCardIssuanceHook(
+  service: GiftCardService,
+  options: Required<GiftCardPluginOptions>,
+  enqueueJob?: (slug: string, input: Record<string, unknown>) => Promise<string>,
+): PluginHookRegistration {
+  const handler = async (args: AfterCreateHookArgs) => {
+    const { result, context } = args;
+    if (!result?.lineItems) return;
+
+    const orgId = resolveOrgId(context.actor);
+
+    for (const item of result.lineItems) {
+      if (item.entityType !== options.productType) continue;
+
+      const amount = item.totalPrice ?? (item.unitPrice ?? 0) * item.quantity;
+      if (amount <= 0) continue;
+
+      const orderMeta = result.metadata as Record<string, unknown> | null;
+      const recipientEmail = (orderMeta?.giftCardRecipientEmail as string) ?? undefined;
+      const senderName = (orderMeta?.giftCardSenderName as string) ?? undefined;
+      const personalMessage = (orderMeta?.giftCardPersonalMessage as string) ?? undefined;
+
+      const createInput: Parameters<typeof service.create>[1] = {
+        amount,
+        currency: result.currency,
+        sourceOrderId: result.id,
+      };
+      if (result.customerId) createInput.purchaserId = result.customerId;
+      if (recipientEmail) createInput.recipientEmail = recipientEmail;
+      if (senderName) createInput.senderName = senderName;
+      if (personalMessage) createInput.personalMessage = personalMessage;
+
+      const cardResult = await service.create(orgId, createInput);
+
+      if (cardResult.ok && enqueueJob && recipientEmail) {
+        try {
+          await enqueueJob("gift-card.deliver", {
+            giftCardId: cardResult.value.id,
+            code: cardResult.value.code,
+            amount,
+            currency: result.currency,
+            recipientEmail,
+            senderName: senderName ?? "",
+            personalMessage: personalMessage ?? "",
+            template: options.emailTemplate,
+          });
+        } catch {
+          // Email delivery failure should not break checkout
+        }
+      }
+    }
+  };
+
+  return {
+    key: "checkout.afterCreate",
+    handler: handler as (...args: unknown[]) => unknown,
+  };
+}

package/src/hooks/refund-credit.ts

@@ -0,0 +1,56 @@
+import { resolveOrgId } from "@unifiedcommerce/core";
+import type { PluginHookRegistration } from "@unifiedcommerce/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,219 @@
+import { defineCommercePlugin, toolBuilder } from "@unifiedcommerce/core";
+import { z } from "zod";
+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 [];
+    },
+
+    mcpTools: (ctx) => {
+      const db = ctx.database.db;
+      if (!db) return [];
+      const service = new GiftCardService(
+        db,
+        ctx.database.transaction,
+        options,
+      );
+
+      const t = toolBuilder("giftcards", "Manage gift cards. Use when checking balances, issuing new cards, looking up card details, or viewing transaction history.");
+
+      t.action("check_balance", "look up balance by code")
+        .input(z.object({
+          orgId: z.string().describe("Organization ID"),
+          code: z.string().describe("Gift card code"),
+        }))
+        .handler(async (args) => service.checkBalance(args.orgId, args.code));
+
+      t.action("issue", "create new card with amount/currency")
+        .input(z.object({
+          orgId: z.string().describe("Organization ID"),
+          amount: z.number().describe("Initial balance in minor units/cents"),
+          currency: z.string().describe("Currency code e.g. USD"),
+          purchaserId: z.string().describe("Customer who purchased the card").optional(),
+          recipientEmail: z.string().describe("Email to deliver the card to").optional(),
+          senderName: z.string().describe("Name of the sender").optional(),
+          personalMessage: z.string().describe("Personal message for recipient").optional(),
+        }))
+        .handler(async (args) => {
+          const input: { amount: number; currency: string; purchaserId?: string; recipientEmail?: string; senderName?: string; personalMessage?: string } = {
+            amount: args.amount,
+            currency: args.currency,
+          };
+          if (args.purchaserId != null) input.purchaserId = args.purchaserId;
+          if (args.recipientEmail != null) input.recipientEmail = args.recipientEmail;
+          if (args.senderName != null) input.senderName = args.senderName;
+          if (args.personalMessage != null) input.personalMessage = args.personalMessage;
+          return service.create(args.orgId, input);
+        });
+
+      t.action("get", "card details by ID")
+        .input(z.object({
+          orgId: z.string().describe("Organization ID"),
+          id: z.string().describe("Gift card ID"),
+        }))
+        .handler(async (args) => service.getById(args.orgId, args.id));
+
+      t.action("list", "all cards with optional filters")
+        .input(z.object({
+          orgId: z.string().describe("Organization ID"),
+          status: z.string().describe("Filter by status: active, exhausted, or disabled").optional(),
+          purchaserId: z.string().describe("Filter by purchaser ID").optional(),
+        }))
+        .handler(async (args) => {
+          const filters: { status?: "active" | "exhausted" | "disabled"; purchaserId?: string } = {};
+          if (args.status != null) filters.status = args.status as "active" | "exhausted" | "disabled";
+          if (args.purchaserId != null) filters.purchaserId = args.purchaserId;
+          return service.list(args.orgId, filters);
+        });
+
+      t.action("transactions", "credit/debit history for a card")
+        .input(z.object({
+          orgId: z.string().describe("Organization ID"),
+          giftCardId: z.string().describe("Gift card ID"),
+        }))
+        .handler(async (args) => service.getTransactions(args.orgId, args.giftCardId));
+
+      return t.build(ctx);
+    },
+
+    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 "@unifiedcommerce/core";
+import { z } from "@hono/zod-openapi";
+import type { GiftCardService } from "../services/gift-card-service.js";
+import type { PluginRouteRegistration } from "@unifiedcommerce/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 "@unifiedcommerce/core";
+import type { GiftCardService } from "../services/gift-card-service.js";
+import type { PluginRouteRegistration } from "@unifiedcommerce/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 "@unifiedcommerce/core";
+import { z } from "@hono/zod-openapi";
+import type { GiftCardService } from "../services/gift-card-service.js";
+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.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));
+  }
+}

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.js";
+import { GiftCardRepository } from "./gift-card-repository.js";
+import type {
+  Db,
+  GiftCard,
+  GiftCardDeduction,
+  GiftCardPluginOptions,
+  GiftCardTransaction,
+  GiftCardStatus,
+  TransactionType,
+} from "../types.js";
+
+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.js";
+
+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: 0 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;
+}