@mohasinac/appkit 3.0.4 → 3.1.0

package/dist/features/products/repository/products.repository.js

@@ -3,7 +3,7 @@ import { increment, serverTimestamp } from "../../../contracts/field-ops";
 import { DatabaseError } from "../../../errors";
 import { BaseRepository, prepareForFirestore, } from "../../../providers/db-firebase";
 import { cacheManager } from "../../../core";
-import { generateUniqueId, slugify, buildSearchTokens, tokenizeQuery } from "../../../utils";
+import { generateUniqueId, slugify, buildSearchTokens, tokenizeQuery, generateBarcodeId } from "../../../utils";
 import { PRODUCT_COLLECTION, ProductStatusValues, } from "../schemas";
 import { PRODUCT_FIELDS } from "../../../constants/field-names";
 /**
@@ -20,11 +20,17 @@ const SIEVE_CLAUSE_LT_AUCTION = `${PRODUCT_FIELDS.LISTING_TYPE}==${LISTING_TYPE_
 const SIEVE_CLAUSE_LT_PREORDER = `${PRODUCT_FIELDS.LISTING_TYPE}==${LISTING_TYPE_VALUES.PRE_ORDER}`;
 const SIEVE_CLAUSE_LT_STANDARD = `${PRODUCT_FIELDS.LISTING_TYPE}==${LISTING_TYPE_VALUES.STANDARD}`;
 const SIEVE_CLAUSE_LT_PRIZE_DRAW = `${PRODUCT_FIELDS.LISTING_TYPE}==${LISTING_TYPE_VALUES.PRIZE_DRAW}`;
+const SIEVE_CLAUSE_LT_CLASSIFIED = `${PRODUCT_FIELDS.LISTING_TYPE}==${LISTING_TYPE_VALUES.CLASSIFIED}`;
+const SIEVE_CLAUSE_LT_DIGITAL_CODE = `${PRODUCT_FIELDS.LISTING_TYPE}==${LISTING_TYPE_VALUES.DIGITAL_CODE}`;
+const SIEVE_CLAUSE_LT_LIVE = `${PRODUCT_FIELDS.LISTING_TYPE}==${LISTING_TYPE_VALUES.LIVE}`;
 const LISTING_KIND_ALIAS_MAP = {
     standard: LISTING_TYPE_VALUES.STANDARD,
     auction: LISTING_TYPE_VALUES.AUCTION,
     "pre-order": LISTING_TYPE_VALUES.PRE_ORDER,
     "prize-draw": LISTING_TYPE_VALUES.PRIZE_DRAW,
+    classified: LISTING_TYPE_VALUES.CLASSIFIED,
+    "digital-code": LISTING_TYPE_VALUES.DIGITAL_CODE,
+    live: LISTING_TYPE_VALUES.LIVE,
     // Legacy → canonical.
     product: LISTING_TYPE_VALUES.STANDARD,
     preorder: LISTING_TYPE_VALUES.PRE_ORDER,
@@ -105,8 +111,10 @@ export class ProductRepository extends BaseRepository {
                 return false;
             }
         });
+        const barcodeId = input.barcodeId ?? await generateBarcodeId(id);
         const productData = {
             ...input,
+            barcodeId,
             slug: id,
             availableQuantity: input.stockQuantity,
             searchTokens: buildProductSearchTokens(input),
@@ -136,6 +144,10 @@ export class ProductRepository extends BaseRepository {
             .get();
         return snap.docs.map((d) => this.mapDoc(d));
     }
+    async findByBarcodeId(barcodeId) {
+        const docs = await this.findBy("barcodeId", barcodeId);
+        return docs[0] ?? null;
+    }
     async findBySlug(slug) {
         const key = this.cacheKeyBySlug(slug);
         const cached = cacheManager.get(key);
@@ -486,6 +498,15 @@ ProductRepository.SIEVE_FIELDS = {
     currency: { canFilter: true, canSort: false },
     freeShipping: { canFilter: true, canSort: false },
     searchTokens: { canFilter: true, canSort: false },
+    "classified.meetupArea": { canFilter: true, canSort: false },
+    "classified.acceptsShipping": { canFilter: true, canSort: false },
+    "classified.negotiable": { canFilter: true, canSort: false },
+    "digitalCode.codeDeliveryMethod": { canFilter: true, canSort: false },
+    "digitalCode.codesAvailable": { canFilter: true, canSort: true },
+    "liveItem.species": { canFilter: true, canSort: false },
+    "liveItem.sex": { canFilter: true, canSort: false },
+    "liveItem.jurisdictionAllowed": { canFilter: true, canSort: false },
+    "liveItem.cites": { canFilter: true, canSort: false },
 };
 /**
  * Virtual filter aliases — callers can pass `f=listingType==auction` for
@@ -540,6 +561,12 @@ ProductRepository.FILTER_ALIASES = {
                 return [SIEVE_CLAUSE_PUBLISHED, SIEVE_CLAUSE_LT_PREORDER].join(",");
             case "publicPrizeDraws":
                 return [SIEVE_CLAUSE_PUBLISHED, SIEVE_CLAUSE_LT_PRIZE_DRAW].join(",");
+            case "publicClassifieds":
+                return [SIEVE_CLAUSE_PUBLISHED, SIEVE_CLAUSE_LT_CLASSIFIED].join(",");
+            case "publicDigitalCodes":
+                return [SIEVE_CLAUSE_PUBLISHED, SIEVE_CLAUSE_LT_DIGITAL_CODE].join(",");
+            case "publicLive":
+                return [SIEVE_CLAUSE_PUBLISHED, SIEVE_CLAUSE_LT_LIVE].join(",");
             case "published":
                 return SIEVE_CLAUSE_PUBLISHED;
             default:

package/dist/features/products/schemas/firestore.d.ts

@@ -3,6 +3,8 @@
  */
 import { type GenerateProductIdInput, type GenerateAuctionIdInput, type GeneratePreOrderIdInput } from "../../../utils/id-generators";
 import type { ProductStatus, ListingType } from "../types";
+import type { BaseDocument } from "../../../_internal/shared/types/base-document";
+import type { LotteryConfig } from "../../lottery/types";
 export interface ProductVideoField {
     url: string;
     thumbnailUrl: string;
@@ -103,8 +105,7 @@ export interface ProductLiveItemMeta {
     /** CITES permit number (Appendix I/II species). */
     cites?: string;
 }
-export interface ProductDocument {
-    id: string;
+export interface ProductDocument extends BaseDocument {
     title: string;
     description: string;
     slug?: string;
@@ -142,7 +143,7 @@ export interface ProductDocument {
     features?: string[];
     shippingInfo?: string;
     returnPolicy?: string;
-    condition?: "new" | "used" | "refurbished" | "broken" | "graded";
+    condition?: "new" | "like_new" | "good" | "fair" | "poor" | "used" | "refurbished" | "broken" | "graded";
     insurance?: boolean;
     insuranceCost?: number;
     shippingPaidBy?: "seller" | "buyer";
@@ -236,6 +237,17 @@ export interface ProductDocument {
     prizeRevealDeadlineDays?: number;
     /** Public proof-of-fairness file (commit-reveal scheme). */
     prizeGithubFileUrl?: string;
+    /**
+     * Draw mode for prize-draw listings.
+     * "reveal" = classic buyer-reveal flow (default, backward-compat).
+     * "lottery" = user self-pull with weighted random slot assignment.
+     */
+    prizeDrawMode?: "reveal" | "lottery";
+    /**
+     * Full lottery config. Only set when prizeDrawMode === "lottery".
+     * Includes server-only price/weight fields — stripped by adapter before any client response.
+     */
+    lotteryConfig?: LotteryConfig;
     /**
      * Optional per-item shipping constraints. When absent the store's
      * shippingConfig applies unchanged.
@@ -264,9 +276,11 @@ export interface ProductDocument {
         shelf: string;
         bin: string;
     };
+    /** Scannable barcode identifier linking this listing to a physical stickered item.
+     *  Auto-generated as `LIR-{8-char-hex}` on product creation when not supplied.
+     *  Override by scanning a pre-printed sticker during the create/edit flow. */
+    barcodeId?: string;
     searchTokens?: string[];
-    createdAt: Date;
-    updatedAt: Date;
 }
 /**
  * Single prize within a prize-draw listing. A draw can have between 3 and 16
@@ -284,6 +298,8 @@ export interface PrizeDrawItem {
     };
     condition: string;
     estimatedValue?: number;
+    /** Per-slot price in paise for lottery mode. Lower price = higher weight = higher chance. */
+    prizeSlotPrice?: number;
     isWon: boolean;
 }
 /** Runtime-accessible product status values — use instead of bare string literals. */
@@ -294,10 +310,10 @@ export declare const ProductStatusValues: {
     readonly ARCHIVED: "archived";
 };
 export declare const PRODUCT_COLLECTION: "products";
-export declare const PRODUCT_INDEXED_FIELDS: readonly ["storeId", "status", "category", "featured", "listingType", "isPromoted", "isOnSale", "isSold", "searchTokens", "createdAt"];
+export declare const PRODUCT_INDEXED_FIELDS: readonly ["storeId", "status", "category", "featured", "listingType", "isPromoted", "isOnSale", "isSold", "searchTokens", "createdAt", "barcodeId"];
 export declare const DEFAULT_PRODUCT_DATA: Partial<ProductDocument>;
 export declare const PRODUCT_PUBLIC_FIELDS: readonly ["id", "title", "description", "category", "subcategory", "brand", "price", "currency", "stockQuantity", "availableQuantity", "images", "status", "storeName", "featured", "tags", "specifications", "features", "shippingInfo", "returnPolicy", "listingType", "auctionEndDate", "startingBid", "currentBid", "bidCount", "reservePrice", "buyNowPrice", "minBidIncrement", "autoExtendable", "auctionExtensionMinutes", "auctionShippingPaidBy", "buyItNowPriceInPaise", "bidsHaveStarted", "grading", "card", "classified", "digitalCode", "liveItem", "catalogProductId", "preOrderDeliveryDate", "preOrderDepositPercent", "preOrderDepositAmount", "preOrderMaxQuantity", "preOrderCurrentCount", "preOrderProductionStatus", "preOrderCancellable", "condition", "insurance", "insuranceCost", "shippingPaidBy", "isPromoted", "isOnSale", "isSold", "slug", "seoTitle", "seoDescription", "seoKeywords", "viewCount", "customFields", "customSections", "sublistingCategoryId", "groupId", "isGroupParent", "groupParentSlug", "groupChildSlugs", "groupTitle", "createdAt"];
-export declare const PRODUCT_UPDATABLE_FIELDS: readonly ["title", "description", "category", "subcategory", "brand", "price", "stockQuantity", "images", "status", "tags", "specifications", "features", "shippingInfo", "returnPolicy", "pickupAddressId", "condition", "insurance", "shippingPaidBy", "autoExtendable", "auctionExtensionMinutes", "auctionShippingPaidBy", "reservePrice", "buyNowPrice", "minBidIncrement", "buyItNowPriceInPaise", "bidsHaveStarted", "grading", "card", "classified", "digitalCode", "liveItem", "catalogProductId", "listingType", "preOrderDeliveryDate", "preOrderDepositPercent", "preOrderDepositAmount", "preOrderMaxQuantity", "preOrderProductionStatus", "preOrderCancellable", "isOnSale", "isSold", "seoTitle", "seoDescription", "seoKeywords", "customFields", "customSections", "sublistingCategoryId", "groupId", "isGroupParent", "groupParentSlug", "groupChildSlugs", "groupTitle"];
+export declare const PRODUCT_UPDATABLE_FIELDS: readonly ["title", "description", "category", "subcategory", "brand", "price", "stockQuantity", "images", "status", "tags", "specifications", "features", "shippingInfo", "returnPolicy", "pickupAddressId", "condition", "insurance", "shippingPaidBy", "autoExtendable", "auctionExtensionMinutes", "auctionShippingPaidBy", "reservePrice", "buyNowPrice", "minBidIncrement", "buyItNowPriceInPaise", "bidsHaveStarted", "grading", "card", "classified", "digitalCode", "liveItem", "catalogProductId", "listingType", "preOrderDeliveryDate", "preOrderDepositPercent", "preOrderDepositAmount", "preOrderMaxQuantity", "preOrderProductionStatus", "preOrderCancellable", "isOnSale", "isSold", "seoTitle", "seoDescription", "seoKeywords", "customFields", "customSections", "sublistingCategoryId", "groupId", "isGroupParent", "groupParentSlug", "groupChildSlugs", "groupTitle", "barcodeId"];
 export type ProductCreateInput = Omit<ProductDocument, "id" | "createdAt" | "updatedAt" | "availableQuantity" | "bidCount" | "currentBid" | "auctionOriginalEndDate">;
 export type ProductUpdateInput = Partial<Pick<ProductDocument, (typeof PRODUCT_UPDATABLE_FIELDS)[number]>>;
 export type ProductAdminUpdateInput = Partial<Omit<ProductDocument, "id" | "createdAt">>;

package/dist/features/products/schemas/firestore.js

@@ -23,6 +23,7 @@ export const PRODUCT_INDEXED_FIELDS = [
     "isSold",
     "searchTokens",
     "createdAt",
+    "barcodeId",
 ];
 export const DEFAULT_PRODUCT_DATA = {
     status: "draft",
@@ -173,6 +174,7 @@ export const PRODUCT_UPDATABLE_FIELDS = [
     "groupParentSlug",
     "groupChildSlugs",
     "groupTitle",
+    "barcodeId",
 ];
 // ── SB-UNI-N 2026-05-15 — Digital-code pool subcollection ───────────────────
 // Codes live at `products/{productId}/codes/{codeId}` — seller-only write,

package/dist/features/products/schemas/index.d.ts

@@ -92,8 +92,8 @@ export declare const productItemSchema: z.ZodObject<{
     categorySlug: z.ZodOptional<z.ZodString>;
     sellerAvatar: z.ZodOptional<z.ZodString>;
     status: z.ZodEnum<["draft", "published", "in_review", "archived"]>;
-    condition: z.ZodOptional<z.ZodEnum<["new", "like_new", "good", "fair", "poor", "used", "refurbished", "broken"]>>;
-    listingType: z.ZodOptional<z.ZodEnum<["standard", "auction", "pre-order", "prize-draw", "bundle"]>>;
+    condition: z.ZodOptional<z.ZodEnum<["new", "like_new", "good", "fair", "poor", "used", "refurbished", "broken", "graded"]>>;
+    listingType: z.ZodOptional<z.ZodEnum<["standard", "auction", "pre-order", "prize-draw", "classified", "digital-code", "live"]>>;
     maxPerUser: z.ZodOptional<z.ZodNumber>;
     partOfBundleIds: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
     partOfBundleTitles: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
@@ -263,8 +263,8 @@ export declare const productItemSchema: z.ZodObject<{
             unit?: string | undefined;
         }>, "many">>;
     }, "strip", z.ZodTypeAny, {
-        id: string;
         title: string;
+        id: string;
         text?: string | undefined;
         fields?: {
             value: string;
@@ -273,8 +273,8 @@ export declare const productItemSchema: z.ZodObject<{
             unit?: string | undefined;
         }[] | undefined;
     }, {
-        id: string;
         title: string;
+        id: string;
         text?: string | undefined;
         fields?: {
             value: string;
@@ -285,9 +285,9 @@ export declare const productItemSchema: z.ZodObject<{
     }>, "many">>;
 }, "strip", z.ZodTypeAny, {
     status: "draft" | "published" | "archived" | "in_review";
-    id: string;
     title: string;
     price: number;
+    id: string;
     currency?: string | undefined;
     video?: {
         url: string;
@@ -296,7 +296,7 @@ export declare const productItemSchema: z.ZodObject<{
     storeId?: string | undefined;
     category?: string | undefined;
     featured?: boolean | undefined;
-    listingType?: "standard" | "auction" | "pre-order" | "prize-draw" | "bundle" | undefined;
+    listingType?: "standard" | "auction" | "pre-order" | "prize-draw" | "classified" | "digital-code" | "live" | undefined;
     isPromoted?: boolean | undefined;
     createdAt?: string | undefined;
     description?: string | undefined;
@@ -316,7 +316,7 @@ export declare const productItemSchema: z.ZodObject<{
     features?: string[] | undefined;
     shippingInfo?: string | undefined;
     returnPolicy?: string | undefined;
-    condition?: "new" | "used" | "refurbished" | "broken" | "like_new" | "good" | "fair" | "poor" | undefined;
+    condition?: "new" | "used" | "refurbished" | "like_new" | "good" | "fair" | "poor" | "broken" | "graded" | undefined;
     insurance?: boolean | undefined;
     insuranceCost?: number | undefined;
     shippingPaidBy?: "seller" | "buyer" | undefined;
@@ -356,8 +356,8 @@ export declare const productItemSchema: z.ZodObject<{
         unit?: string | undefined;
     }[] | undefined;
     customSections?: {
-        id: string;
         title: string;
+        id: string;
         text?: string | undefined;
         fields?: {
             value: string;
@@ -414,9 +414,9 @@ export declare const productItemSchema: z.ZodObject<{
     publishedAt?: string | undefined;
 }, {
     status: "draft" | "published" | "archived" | "in_review";
-    id: string;
     title: string;
     price: number;
+    id: string;
     currency?: string | undefined;
     video?: {
         url: string;
@@ -425,7 +425,7 @@ export declare const productItemSchema: z.ZodObject<{
     storeId?: string | undefined;
     category?: string | undefined;
     featured?: boolean | undefined;
-    listingType?: "standard" | "auction" | "pre-order" | "prize-draw" | "bundle" | undefined;
+    listingType?: "standard" | "auction" | "pre-order" | "prize-draw" | "classified" | "digital-code" | "live" | undefined;
     isPromoted?: boolean | undefined;
     createdAt?: string | undefined;
     description?: string | undefined;
@@ -445,7 +445,7 @@ export declare const productItemSchema: z.ZodObject<{
     features?: string[] | undefined;
     shippingInfo?: string | undefined;
     returnPolicy?: string | undefined;
-    condition?: "new" | "used" | "refurbished" | "broken" | "like_new" | "good" | "fair" | "poor" | undefined;
+    condition?: "new" | "used" | "refurbished" | "like_new" | "good" | "fair" | "poor" | "broken" | "graded" | undefined;
     insurance?: boolean | undefined;
     insuranceCost?: number | undefined;
     shippingPaidBy?: "seller" | "buyer" | undefined;
@@ -485,8 +485,8 @@ export declare const productItemSchema: z.ZodObject<{
         unit?: string | undefined;
     }[] | undefined;
     customSections?: {
-        id: string;
         title: string;
+        id: string;
         text?: string | undefined;
         fields?: {
             value: string;
@@ -547,11 +547,11 @@ export declare const productListParamsSchema: z.ZodObject<{
     q: z.ZodOptional<z.ZodString>;
     category: z.ZodOptional<z.ZodString>;
     status: z.ZodOptional<z.ZodEnum<["draft", "published", "in_review", "archived"]>>;
-    condition: z.ZodOptional<z.ZodEnum<["new", "like_new", "good", "fair", "poor", "used", "refurbished", "broken"]>>;
+    condition: z.ZodOptional<z.ZodEnum<["new", "like_new", "good", "fair", "poor", "used", "refurbished", "broken", "graded"]>>;
     minPrice: z.ZodOptional<z.ZodNumber>;
     maxPrice: z.ZodOptional<z.ZodNumber>;
     inStock: z.ZodOptional<z.ZodBoolean>;
-    listingType: z.ZodOptional<z.ZodEnum<["standard", "auction", "pre-order", "prize-draw", "bundle"]>>;
+    listingType: z.ZodOptional<z.ZodEnum<["standard", "auction", "pre-order", "prize-draw", "classified", "digital-code", "live"]>>;
     storeId: z.ZodOptional<z.ZodString>;
     sort: z.ZodOptional<z.ZodString>;
     page: z.ZodOptional<z.ZodNumber>;
@@ -563,8 +563,8 @@ export declare const productListParamsSchema: z.ZodObject<{
     storeId?: string | undefined;
     category?: string | undefined;
     featured?: boolean | undefined;
-    listingType?: "standard" | "auction" | "pre-order" | "prize-draw" | "bundle" | undefined;
-    condition?: "new" | "used" | "refurbished" | "broken" | "like_new" | "good" | "fair" | "poor" | undefined;
+    listingType?: "standard" | "auction" | "pre-order" | "prize-draw" | "classified" | "digital-code" | "live" | undefined;
+    condition?: "new" | "used" | "refurbished" | "like_new" | "good" | "fair" | "poor" | "broken" | "graded" | undefined;
     page?: number | undefined;
     q?: string | undefined;
     perPage?: number | undefined;
@@ -577,8 +577,8 @@ export declare const productListParamsSchema: z.ZodObject<{
     storeId?: string | undefined;
     category?: string | undefined;
     featured?: boolean | undefined;
-    listingType?: "standard" | "auction" | "pre-order" | "prize-draw" | "bundle" | undefined;
-    condition?: "new" | "used" | "refurbished" | "broken" | "like_new" | "good" | "fair" | "poor" | undefined;
+    listingType?: "standard" | "auction" | "pre-order" | "prize-draw" | "classified" | "digital-code" | "live" | undefined;
+    condition?: "new" | "used" | "refurbished" | "like_new" | "good" | "fair" | "poor" | "broken" | "graded" | undefined;
     page?: number | undefined;
     q?: string | undefined;
     perPage?: number | undefined;

package/dist/features/products/schemas/index.js

@@ -64,11 +64,12 @@ export const productItemSchema = z.object({
         "used",
         "refurbished",
         "broken",
+        "graded",
     ])
         .optional(),
     // SB1-G Phase 4 — canonical discriminator (legacy `isAuction`/`isPreOrder` booleans removed).
     listingType: z
-        .enum(["standard", "auction", "pre-order", "prize-draw", "bundle"])
+        .enum(["standard", "auction", "pre-order", "prize-draw", "classified", "digital-code", "live"])
         .optional(),
     // SB1-C — prize-draw + bundle fields. All optional.
     maxPerUser: z.number().int().positive().optional(),
@@ -205,13 +206,14 @@ export const productListParamsSchema = z.object({
         "used",
         "refurbished",
         "broken",
+        "graded",
     ])
         .optional(),
     minPrice: z.coerce.number().optional(),
     maxPrice: z.coerce.number().optional(),
     inStock: z.coerce.boolean().optional(),
     listingType: z
-        .enum(["standard", "auction", "pre-order", "prize-draw", "bundle"])
+        .enum(["standard", "auction", "pre-order", "prize-draw", "classified", "digital-code", "live"])
         .optional(),
     storeId: z.string().optional(),
     sort: z.string().optional(),

package/dist/features/products/types/index.d.ts

@@ -2,7 +2,7 @@ import type { MediaField } from "../../media/types/index";
 import type { CustomField, CustomSection } from "../schemas/firestore";
 export type { CustomField, CustomSection } from "../schemas/firestore";
 export type ProductStatus = "draft" | "published" | "in_review" | "archived";
-export type ProductCondition = "new" | "like_new" | "good" | "fair" | "poor" | "used" | "refurbished" | "broken";
+export type ProductCondition = "new" | "like_new" | "good" | "fair" | "poor" | "used" | "refurbished" | "broken" | "graded";
 /**
  * Canonical listing-kind discriminator (SB1-G Phase 4).
  *
@@ -149,6 +149,8 @@ export interface ProductItem {
         shelf: string;
         bin: string;
     };
+    /** Scannable barcode ID linking this listing to a physical stickered item. */
+    barcodeId?: string;
 }
 export interface ProductListResponse {
     items: ProductItem[];

package/dist/features/promotions/repository/__tests__/claimed-coupons.repository.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/features/promotions/repository/__tests__/claimed-coupons.repository.test.js

@@ -0,0 +1,219 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { makeMockDb, makeSnap, makeQuerySnap } from "../../../../../tests/helpers/mock-firestore";
+const { db, mockDocRef, mockCollection, mockQuery } = makeMockDb();
+vi.mock("../../../../providers/db-firebase/admin", () => ({
+    getAdminDb: () => db,
+}));
+vi.mock("../../../../providers/db-firebase", async (importOriginal) => {
+    const actual = await importOriginal();
+    return {
+        ...actual,
+        prepareForFirestore: (d) => d,
+    };
+});
+vi.mock("../../../../errors/normalize", () => ({
+    normalizeError: vi.fn(),
+}));
+import { ClaimedCouponsRepository } from "../claimed-coupons.repository";
+import { createClaimedCouponId } from "../../schemas";
+const repo = new ClaimedCouponsRepository();
+function makeClaimInput(overrides = {}) {
+    return {
+        userId: "user-yugi",
+        couponId: "coupon-welcome10",
+        couponCode: "welcome10",
+        source: "manual",
+        couponSnapshot: {
+            name: "10% Off Coupon",
+            type: "percentage",
+            scope: "admin",
+            discount: { value: 10, maxDiscount: 0, minPurchase: 0 },
+            restrictions: { firstTimeUserOnly: false, combineWithSellerCoupons: true },
+        },
+        expiresAt: null,
+        ...overrides,
+    };
+}
+function makeClaimDoc(userId = "user-yugi", code = "WELCOME10") {
+    return {
+        id: createClaimedCouponId(userId, code),
+        userId,
+        couponId: "coupon-welcome10",
+        couponCode: code,
+        source: "manual",
+        status: "active",
+        expiresAt: null,
+        claimedAt: new Date(),
+        updatedAt: new Date(),
+        couponSnapshot: {},
+    };
+}
+beforeEach(() => {
+    vi.clearAllMocks();
+    db.collection.mockReturnValue(mockCollection);
+    mockCollection.doc.mockReturnValue(mockDocRef);
+    mockCollection.where.mockReturnValue(mockQuery);
+    mockQuery.where.mockReturnValue(mockQuery);
+    mockQuery.get.mockResolvedValue(makeQuerySnap([]));
+    mockDocRef.get.mockResolvedValue(makeSnap(null));
+    mockDocRef.set.mockResolvedValue(undefined);
+    mockDocRef.update.mockResolvedValue(undefined);
+});
+// ---------------------------------------------------------------------------
+// findByUserAndCode
+// ---------------------------------------------------------------------------
+describe("ClaimedCouponsRepository.findByUserAndCode", () => {
+    it("existing claim → returns document", async () => {
+        const doc = makeClaimDoc();
+        mockDocRef.get.mockResolvedValue(makeSnap(doc, doc.id));
+        const result = await repo.findByUserAndCode("user-yugi", "WELCOME10");
+        expect(result).not.toBeNull();
+        expect(result.couponCode).toBe("WELCOME10");
+    });
+    it("no claim → returns null", async () => {
+        mockDocRef.get.mockResolvedValue(makeSnap(null));
+        const result = await repo.findByUserAndCode("user-yugi", "NOTFOUND");
+        expect(result).toBeNull();
+    });
+    it("uses deterministic ID based on userId + couponCode", async () => {
+        mockDocRef.get.mockResolvedValue(makeSnap(null));
+        await repo.findByUserAndCode("user-yugi", "WELCOME10");
+        const expectedId = createClaimedCouponId("user-yugi", "WELCOME10");
+        expect(mockCollection.doc).toHaveBeenCalledWith(expectedId);
+    });
+});
+// ---------------------------------------------------------------------------
+// claim
+// ---------------------------------------------------------------------------
+describe("ClaimedCouponsRepository.claim", () => {
+    it("first call → creates record with status: active", async () => {
+        mockDocRef.get.mockResolvedValue(makeSnap(null));
+        const result = await repo.claim(makeClaimInput());
+        expect(result.status).toBe("active");
+        expect(mockDocRef.set).toHaveBeenCalledOnce();
+    });
+    it("second call for same user + code → returns existing record (idempotent)", async () => {
+        const existingDoc = makeClaimDoc();
+        mockDocRef.get.mockResolvedValue(makeSnap(existingDoc, existingDoc.id));
+        const result = await repo.claim(makeClaimInput());
+        expect(mockDocRef.set).not.toHaveBeenCalled();
+        expect(result.id).toBe(existingDoc.id);
+    });
+    it("couponCode normalized to uppercase on create", async () => {
+        mockDocRef.get.mockResolvedValue(makeSnap(null));
+        const result = await repo.claim(makeClaimInput({ couponCode: "welcome10" }));
+        expect(result.couponCode).toBe("WELCOME10");
+    });
+    it("expiresAt stored as provided (null case)", async () => {
+        mockDocRef.get.mockResolvedValue(makeSnap(null));
+        const result = await repo.claim(makeClaimInput({ expiresAt: null }));
+        expect(result.expiresAt).toBeNull();
+    });
+    it("expiresAt stored as provided (date case)", async () => {
+        const exp = new Date(Date.now() + 86400000);
+        mockDocRef.get.mockResolvedValue(makeSnap(null));
+        const result = await repo.claim(makeClaimInput({ expiresAt: exp }));
+        expect(result.expiresAt).toEqual(exp);
+    });
+    it("uses createClaimedCouponId for the document ID", async () => {
+        mockDocRef.get.mockResolvedValue(makeSnap(null));
+        await repo.claim(makeClaimInput({ userId: "user-yugi", couponCode: "SAVE20" }));
+        const expectedId = createClaimedCouponId("user-yugi", "SAVE20");
+        expect(mockCollection.doc).toHaveBeenCalledWith(expectedId);
+    });
+});
+// ---------------------------------------------------------------------------
+// listForUser
+// ---------------------------------------------------------------------------
+describe("ClaimedCouponsRepository.listForUser", () => {
+    it("queries by userId field", async () => {
+        mockQuery.get.mockResolvedValue(makeQuerySnap([]));
+        await repo.listForUser("user-yugi");
+        expect(mockCollection.where).toHaveBeenCalledWith("userId", "==", "user-yugi");
+    });
+    it("valid coupon (not expired) → returned without mutation", async () => {
+        const futureDate = new Date(Date.now() + 86400000);
+        const doc = { ...makeClaimDoc(), status: "active", expiresAt: futureDate };
+        mockQuery.get.mockResolvedValue(makeQuerySnap([{ id: doc.id, data: doc }]));
+        const results = await repo.listForUser("user-yugi");
+        expect(results[0].status).toBe("active");
+        expect(mockDocRef.update).not.toHaveBeenCalled();
+    });
+    it("active coupon with no expiresAt → not lazily expired", async () => {
+        const doc = { ...makeClaimDoc(), status: "active", expiresAt: null };
+        mockQuery.get.mockResolvedValue(makeQuerySnap([{ id: doc.id, data: doc }]));
+        const results = await repo.listForUser("user-yugi");
+        expect(results[0].status).toBe("active");
+        expect(mockDocRef.update).not.toHaveBeenCalled();
+    });
+    it("expired coupon found on read → lazy-flips status to expired in returned item", async () => {
+        const pastDate = new Date(Date.now() - 86400000);
+        const doc = { ...makeClaimDoc(), status: "active", expiresAt: pastDate };
+        mockQuery.get.mockResolvedValue(makeQuerySnap([{ id: doc.id, data: doc }]));
+        const results = await repo.listForUser("user-yugi");
+        expect(results[0].status).toBe("expired");
+    });
+    it("expired coupon → best-effort write-back update called (fire-and-forget)", async () => {
+        const pastDate = new Date(Date.now() - 86400000);
+        const doc = { ...makeClaimDoc(), status: "active", expiresAt: pastDate };
+        mockQuery.get.mockResolvedValue(makeQuerySnap([{ id: doc.id, data: doc }]));
+        await repo.listForUser("user-yugi");
+        // Allow the fire-and-forget to complete
+        await new Promise((r) => setTimeout(r, 10));
+        expect(mockDocRef.update).toHaveBeenCalledWith(expect.objectContaining({ status: "expired" }));
+    });
+    it("already-expired coupon → no write-back (only active transitions)", async () => {
+        const pastDate = new Date(Date.now() - 86400000);
+        const doc = { ...makeClaimDoc(), status: "expired", expiresAt: pastDate };
+        mockQuery.get.mockResolvedValue(makeQuerySnap([{ id: doc.id, data: doc }]));
+        await repo.listForUser("user-yugi");
+        await new Promise((r) => setTimeout(r, 10));
+        expect(mockDocRef.update).not.toHaveBeenCalled();
+    });
+    it("empty list → returns []", async () => {
+        mockQuery.get.mockResolvedValue(makeQuerySnap([]));
+        const results = await repo.listForUser("user-nobody");
+        expect(results).toHaveLength(0);
+    });
+});
+// ---------------------------------------------------------------------------
+// markUsed
+// ---------------------------------------------------------------------------
+describe("ClaimedCouponsRepository.markUsed", () => {
+    it("sets status: used on the claim document", async () => {
+        await repo.markUsed("user-yugi", "WELCOME10", "order-1-20260101-abc");
+        expect(mockDocRef.update).toHaveBeenCalledWith(expect.objectContaining({ status: "used" }));
+    });
+    it("stores usedOrderId on the claim", async () => {
+        await repo.markUsed("user-yugi", "WELCOME10", "order-1-20260101-abc");
+        expect(mockDocRef.update).toHaveBeenCalledWith(expect.objectContaining({ usedOrderId: "order-1-20260101-abc" }));
+    });
+    it("sets usedAt timestamp", async () => {
+        await repo.markUsed("user-yugi", "WELCOME10", "order-x");
+        expect(mockDocRef.update).toHaveBeenCalledWith(expect.objectContaining({ usedAt: expect.any(Date) }));
+    });
+    it("uses the correct document ID (userId + code)", async () => {
+        await repo.markUsed("user-yugi", "WELCOME10", "order-x");
+        const expectedId = createClaimedCouponId("user-yugi", "WELCOME10");
+        expect(mockCollection.doc).toHaveBeenCalledWith(expectedId);
+    });
+});
+// ---------------------------------------------------------------------------
+// softRemove
+// ---------------------------------------------------------------------------
+describe("ClaimedCouponsRepository.softRemove", () => {
+    it("sets status: expired (audit trail preserved, no delete)", async () => {
+        await repo.softRemove("user-yugi", "WELCOME10");
+        expect(mockDocRef.update).toHaveBeenCalledWith(expect.objectContaining({ status: "expired" }));
+        expect(mockDocRef.delete).not.toHaveBeenCalled();
+    });
+    it("does NOT call delete on the document", async () => {
+        await repo.softRemove("user-yugi", "SAVE20");
+        expect(mockDocRef.delete).not.toHaveBeenCalled();
+    });
+    it("uses the correct document ID (userId + code)", async () => {
+        await repo.softRemove("user-yugi", "SAVE20");
+        const expectedId = createClaimedCouponId("user-yugi", "SAVE20");
+        expect(mockCollection.doc).toHaveBeenCalledWith(expectedId);
+    });
+});

package/dist/features/promotions/repository/__tests__/coupons.repository.test.d.ts

@@ -0,0 +1 @@
+export {};