@unifiedcommerce/plugin-giftcards 0.0.1

package/dist/types.d.ts

@@ -0,0 +1,30 @@
+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 declare const DEFAULT_OPTIONS: Required<GiftCardPluginOptions>;
+export interface GiftCardDeduction {
+    code: string;
+    giftCardId: string;
+    amount: number;
+    balanceAfter: number;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,QAAQ,IAAI,EAAE,EAAE,MAAM,uBAAuB,CAAC;AAC5D,OAAO,KAAK,EAAE,SAAS,EAAE,oBAAoB,EAAE,MAAM,UAAU,CAAC;AAEhE,MAAM,MAAM,QAAQ,GAAG,OAAO,SAAS,CAAC,YAAY,CAAC;AACrD,MAAM,MAAM,cAAc,GAAG,OAAO,SAAS,CAAC,YAAY,CAAC;AAC3D,MAAM,MAAM,mBAAmB,GAAG,OAAO,oBAAoB,CAAC,YAAY,CAAC;AAC3E,MAAM,MAAM,yBAAyB,GAAG,OAAO,oBAAoB,CAAC,YAAY,CAAC;AAEjF,MAAM,MAAM,cAAc,GAAG,QAAQ,GAAG,UAAU,GAAG,WAAW,CAAC;AACjE,MAAM,MAAM,eAAe,GAAG,OAAO,GAAG,QAAQ,GAAG,QAAQ,CAAC;AAE5D,MAAM,WAAW,qBAAqB;IACpC,0DAA0D;IAC1D,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,uEAAuE;IACvE,iBAAiB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC,+EAA+E;IAC/E,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,gFAAgF;IAChF,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,8CAA8C;IAC9C,sBAAsB,CAAC,EAAE,OAAO,CAAC;IACjC,qFAAqF;IACrF,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,eAAO,MAAM,eAAe,EAAE,QAAQ,CAAC,qBAAqB,CAO3D,CAAC;AAEF,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,YAAY,EAAE,MAAM,CAAC;CACtB"}

package/dist/types.js

@@ -0,0 +1,8 @@
+export const DEFAULT_OPTIONS = {
+    codeFormat: "XXXX-XXXX-XXXX-XXXX",
+    defaultExpiryDays: null,
+    maxBalancePerCard: 10_000_00,
+    emailTemplate: "gift-card-delivery",
+    allowPartialRedemption: true,
+    productType: "gift_card",
+};

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@unifiedcommerce/plugin-giftcards",
+  "version": "0.0.1",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "check-types": "tsc --noEmit",
+    "lint": "eslint . --max-warnings 1000",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@hono/zod-openapi": "^1.2.2",
+    "@unifiedcommerce/core": "*",
+    "drizzle-orm": "^0.45.1",
+    "hono": "^4.12.5"
+  },
+  "devDependencies": {
+    "@repo/eslint-config": "*",
+    "@repo/typescript-config": "*",
+    "@types/node": "^24.5.2",
+    "eslint": "^9.39.1",
+    "typescript": "5.9.2",
+    "vitest": "^3.2.4"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "src",
+    "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";
+import type { GiftCardDeduction } from "../types";
+
+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";
+import type { GiftCardPluginOptions } from "../types";
+
+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";
+import type { GiftCardDeduction } from "../types";
+
+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,147 @@
+import { defineCommercePlugin } from "@unifiedcommerce/core";
+import { giftCards, giftCardTransactions } from "./schema";
+import { GiftCardService } from "./services/gift-card-service";
+import {
+  buildCheckoutDeductionHook,
+  buildCheckoutCompensationHook,
+} from "./hooks/checkout-deduction";
+import { buildGiftCardIssuanceHook } from "./hooks/checkout-issuance";
+import { buildRefundCreditHook } from "./hooks/refund-credit";
+import { buildAdminRoutes } from "./routes/admin";
+import { buildPublicRoutes } from "./routes/public";
+import { buildCustomerRoutes } from "./routes/customer";
+import type { GiftCardPluginOptions, Db } from "./types";
+import { DEFAULT_OPTIONS } from "./types";
+
+export type { GiftCardPluginOptions } from "./types";
+export { GiftCardService } from "./services/gift-card-service";
+
+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 as unknown as Db;
+      if (!db) return [];
+
+      const service = new GiftCardService(
+        db,
+        ctx.database.transaction as unknown as (fn: (tx: Db) => Promise<unknown>) => Promise<unknown>,
+        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: () => {
+      // Create a lazy proxy service that defers to serviceRef.current
+      const lazyService = new Proxy({} as GiftCardService, {
+        get(_target, prop) {
+          if (!serviceRef.current) {
+            throw new Error(
+              "Gift card service not initialized — hooks ran before routes()",
+            );
+          }
+          return (serviceRef.current as unknown as Record<string, unknown>)[prop as string];
+        },
+      });
+
+      return [
+        buildCheckoutDeductionHook(lazyService),
+        buildCheckoutCompensationHook(lazyService),
+        buildGiftCardIssuanceHook(lazyService, options),
+        buildRefundCreditHook(lazyService),
+      ];
+    },
+
+    routes: (ctx) => {
+      const db = ctx.database.db as unknown as Db;
+      if (!db) return [];
+
+      const service = new GiftCardService(
+        db,
+        ctx.database.transaction as unknown as (fn: (tx: Db) => Promise<unknown>) => Promise<unknown>,
+        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";
+import type { PluginRouteRegistration } from "@unifiedcommerce/core";
+import { formatCode } from "../code-generator";
+
+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();
+}