@porulle/plugin-giftcards 0.1.0

package/dist/services/gift-card-service.d.ts

@@ -0,0 +1,45 @@
+import type { PluginResult } from "@porulle/core";
+import type { Db, GiftCard, GiftCardDeduction, GiftCardPluginOptions, GiftCardTransaction, GiftCardStatus } from "../types.js";
+export declare class GiftCardService {
+    private options;
+    private repo;
+    private transaction;
+    constructor(db: Db, transactionFn: (fn: (tx: Db) => Promise<unknown>) => Promise<unknown>, options: Required<GiftCardPluginOptions>);
+    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>>;
+    getById(orgId: string, id: string): Promise<PluginResult<GiftCard>>;
+    getByCode(orgId: string, code: string): Promise<PluginResult<GiftCard>>;
+    list(orgId: string, filters?: {
+        status?: GiftCardStatus;
+        purchaserId?: string;
+    }): Promise<PluginResult<GiftCard[]>>;
+    getTransactions(orgId: string, giftCardId: string): Promise<PluginResult<GiftCardTransaction[]>>;
+    checkBalance(orgId: string, code: string): Promise<PluginResult<{
+        balance: number;
+        currency: string;
+        status: string;
+    }>>;
+    /**
+     * Debit a gift card balance within a transaction.
+     * Uses SELECT FOR UPDATE to prevent double-spend.
+     */
+    debitWithLock(orgId: string, code: string, amount: number, orderId: string, currency: string): Promise<PluginResult<GiftCardDeduction>>;
+    /**
+     * Credit a gift card balance (refund/compensation).
+     * Uses SELECT FOR UPDATE. Cannot exceed initial_amount.
+     */
+    creditWithLock(orgId: string, code: string, amount: number, orderId: string, note: string): Promise<PluginResult<{
+        balanceAfter: number;
+    }>>;
+    disable(orgId: string, id: string): Promise<PluginResult<GiftCard>>;
+    adjust(orgId: string, id: string, delta: number, note: string): Promise<PluginResult<GiftCard>>;
+}
+//# sourceMappingURL=gift-card-service.d.ts.map

package/dist/services/gift-card-service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gift-card-service.d.ts","sourceRoot":"","sources":["../../src/services/gift-card-service.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAGlD,OAAO,KAAK,EACV,EAAE,EACF,QAAQ,EACR,iBAAiB,EACjB,qBAAqB,EACrB,mBAAmB,EACnB,cAAc,EAEf,MAAM,aAAa,CAAC;AAErB,qBAAa,eAAe;IAOxB,OAAO,CAAC,OAAO;IANjB,OAAO,CAAC,IAAI,CAAqB;IACjC,OAAO,CAAC,WAAW,CAAyD;gBAG1E,EAAE,EAAE,EAAE,EACN,aAAa,EAAE,CAAC,EAAE,EAAE,CAAC,EAAE,EAAE,EAAE,KAAK,OAAO,CAAC,OAAO,CAAC,KAAK,OAAO,CAAC,OAAO,CAAC,EAC7D,OAAO,EAAE,QAAQ,CAAC,qBAAqB,CAAC;IAQ5C,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE;QACjC,MAAM,EAAE,MAAM,CAAC;QACf,QAAQ,EAAE,MAAM,CAAC;QACjB,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,cAAc,CAAC,EAAE,MAAM,CAAC;QACxB,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,eAAe,CAAC,EAAE,MAAM,CAAC;QACzB,aAAa,CAAC,EAAE,MAAM,CAAC;QACvB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;KACpC,GAAG,OAAO,CAAC,YAAY,CAAC,QAAQ,CAAC,CAAC;IAuD7B,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,QAAQ,CAAC,CAAC;IAMnE,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,QAAQ,CAAC,CAAC;IAMvE,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAClC,MAAM,CAAC,EAAE,cAAc,CAAC;QACxB,WAAW,CAAC,EAAE,MAAM,CAAC;KACtB,GAAG,OAAO,CAAC,YAAY,CAAC,QAAQ,EAAE,CAAC,CAAC;IAK/B,eAAe,CACnB,KAAK,EAAE,MAAM,EACb,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC,YAAY,CAAC,mBAAmB,EAAE,CAAC,CAAC;IAOzC,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC;QACpE,OAAO,EAAE,MAAM,CAAC;QAChB,QAAQ,EAAE,MAAM,CAAC;QACjB,MAAM,EAAE,MAAM,CAAC;KAChB,CAAC,CAAC;IAaH;;;OAGG;IACG,aAAa,CACjB,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,YAAY,CAAC,iBAAiB,CAAC,CAAC;IAwC3C;;;OAGG;IACG,cAAc,CAClB,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,YAAY,CAAC;QAAE,YAAY,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAsC5C,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,QAAQ,CAAC,CAAC;IAMnE,MAAM,CACV,KAAK,EAAE,MAAM,EACb,EAAE,EAAE,MAAM,EACV,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,YAAY,CAAC,QAAQ,CAAC,CAAC;CAoCnC"}

package/dist/services/gift-card-service.js

@@ -0,0 +1,196 @@
+import { Ok, Err } from "@porulle/core";
+import { generateGiftCardCode, normalizeCode } from "../code-generator.js";
+import { GiftCardRepository } from "./gift-card-repository.js";
+export class GiftCardService {
+    options;
+    repo;
+    transaction;
+    constructor(db, transactionFn, options) {
+        this.options = options;
+        this.repo = new GiftCardRepository(db);
+        this.transaction = transactionFn;
+    }
+    // ─── Create ──────────────────────────────────────────────────────────
+    async create(orgId, input) {
+        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;
+        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",
+            amount: input.amount,
+            balanceAfter: input.amount,
+            note: "Initial load",
+        });
+        return Ok(card);
+    }
+    // ─── Query ───────────────────────────────────────────────────────────
+    async getById(orgId, id) {
+        const card = await this.repo.findById(id);
+        if (!card)
+            return Err("Gift card not found");
+        return Ok(card);
+    }
+    async getByCode(orgId, code) {
+        const card = await this.repo.findByCode(normalizeCode(code));
+        if (!card)
+            return Err("Gift card not found");
+        return Ok(card);
+    }
+    async list(orgId, filters) {
+        const cards = await this.repo.list(filters);
+        return Ok(cards);
+    }
+    async getTransactions(orgId, giftCardId) {
+        const txns = await this.repo.listTransactions(giftCardId);
+        return Ok(txns);
+    }
+    // ─── Balance Check (Public) ──────────────────────────────────────────
+    async checkBalance(orgId, code) {
+        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, code, amount, orderId, currency) {
+        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 = balanceAfter === 0 ? "exhausted" : "active";
+            await this.repo.updateBalance(card.id, balanceAfter, newStatus, card.version, tx);
+            await this.repo.recordTransaction({
+                giftCardId: card.id,
+                type: "debit",
+                amount,
+                balanceAfter,
+                orderId,
+            }, { tx });
+            return Ok({
+                code: card.code,
+                giftCardId: card.id,
+                amount,
+                balanceAfter,
+            });
+        });
+        return result;
+    }
+    // ─── Credit (Concurrency-Safe) ───────────────────────────────────────
+    /**
+     * Credit a gift card balance (refund/compensation).
+     * Uses SELECT FOR UPDATE. Cannot exceed initial_amount.
+     */
+    async creditWithLock(orgId, code, amount, orderId, note) {
+        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 = 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",
+                amount: actualCredit,
+                balanceAfter,
+                orderId,
+                note,
+            }, { tx });
+            return Ok({ balanceAfter });
+        });
+        return result;
+    }
+    // ─── Admin Operations ────────────────────────────────────────────────
+    async disable(orgId, id) {
+        const card = await this.repo.disable(id);
+        if (!card)
+            return Err("Gift card not found");
+        return Ok(card);
+    }
+    async adjust(orgId, id, delta, note) {
+        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 = newBalance === 0 ? "exhausted" : "active";
+            const updated = await this.repo.updateBalance(card.id, newBalance, newStatus, card.version, tx);
+            if (actualDelta !== 0) {
+                const txnType = 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;
+    }
+}

package/dist/types.d.ts

@@ -0,0 +1,30 @@
+export type { PluginDb as Db } from "@porulle/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 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,eAAe,CAAC;AACpD,OAAO,KAAK,EAAE,SAAS,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAEnE,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: 0,
+    maxBalancePerCard: 10_000_00,
+    emailTemplate: "gift-card-delivery",
+    allowPartialRedemption: true,
+    productType: "gift_card",
+};

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@porulle/plugin-giftcards",
+  "version": "0.1.0",
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    ".": {
+      "bun": "./src/index.ts",
+      "import": "./dist/index.js",
+      "types": "./src/index.ts"
+    },
+    "./schema": {
+      "bun": "./src/schema.ts",
+      "import": "./dist/schema.js",
+      "require": "./dist/schema.js",
+      "types": "./src/schema.ts"
+    }
+  },
+  "scripts": {
+    "build": "rm -rf dist tsconfig.build.tsbuildinfo && tsc -p tsconfig.build.json",
+    "check-types": "tsc --noEmit",
+    "lint": "eslint . --max-warnings 1000",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@hono/zod-openapi": "^1.2.2",
+    "@porulle/core": "workspace:*",
+    "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": [
+    "src",
+    "dist",
+    "README.md"
+  ],
+  "peerDependencies": {
+    "zod": ">=4.0.0"
+  },
+  "description": "Stored-value gift cards with balance checks, checkout redemption, issuance from qualifying purchases, and admin lifecycle APIs.",
+  "homepage": "https://porulle-docs.vercel.app",
+  "bugs": {
+    "url": "https://github.com/asyncdotengineering/porulle/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/asyncdotengineering/porulle.git",
+    "directory": "packages/plugins/plugin-gift-cards"
+  },
+  "author": "Porulle contributors"
+}

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 "@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 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 "@porulle/core";
+import type { PluginHookRegistration } from "@porulle/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,
+  };
+}