@unifiedcommerce/plugin-giftcards 0.0.1

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

@@ -0,0 +1,45 @@
+import type { PluginResult } from "@unifiedcommerce/core";
+import type { Db, GiftCard, GiftCardDeduction, GiftCardPluginOptions, GiftCardTransaction, GiftCardStatus } from "../types";
+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,uBAAuB,CAAC;AAG1D,OAAO,KAAK,EACV,EAAE,EACF,QAAQ,EACR,iBAAiB,EACjB,qBAAqB,EACrB,mBAAmB,EACnB,cAAc,EAEf,MAAM,UAAU,CAAC;AAElB,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 "@unifiedcommerce/core";
+import { generateGiftCardCode, normalizeCode } from "../code-generator";
+import { GiftCardRepository } from "./gift-card-repository";
+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;
+    }
+}