@mohasinac/appkit 4.58.0 → 4.60.0

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

@@ -749,7 +749,28 @@ export interface ProductDocument extends BaseDocument {
         w: number;
         h: number;
     };
-    /** Physical storage location for inventory management (Print & Label Center). */
+    /**
+     * @deprecated Free-text storage location. Superseded by `inventoryPlacements`.
+     *
+     * 🛑 READ-ONLY FROM 2026-10-21. Three uncontrolled text inputs with no
+     * registry behind them, so "shelf 3", "Shelf-3" and "AC60 3" all meant one
+     * place: no list could group them, no query could find everything on a
+     * shelf, and the label printed whichever spelling that one product carried.
+     * Three boxes a human types into cannot be made consistent by validation.
+     *
+     * Where something lives is now a PLACEMENT (`storageBoxes` +
+     * `inventoryPlacements`), which carries a quantity and permits one product
+     * in two boxes — neither expressible here.
+     *
+     * 🛑 NOT DELETED, AND THE REASON IS NOT TIMIDITY. The stored strings cannot
+     * be mechanically mapped to box codes — that impossibility is exactly why
+     * the registry exists — so an automatic migration would either invent boxes
+     * from free text or lose the data. Listings that carry a value still show it
+     * (the product form and the label both do) until a human has re-placed them
+     * in a real box. The inputs are gone, so nothing new accumulates;
+     * `audit-no-physical-location-input` keeps it that way, and the field goes
+     * when the last value does.
+     */
     physicalLocation?: {
         zone: string;
         shelf: string;
@@ -757,8 +778,30 @@ export interface ProductDocument extends BaseDocument {
     };
     /** 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. */
+     *  Override by scanning a pre-printed sticker during the create/edit flow.
+     *
+     *  🛑 THE MACHINE KEY, and it must stay uniform-width. This field used to
+     *  hold the semantic codes too — 23 seeded products carried
+     *  `LIR-BEY-X-005` while everything app-created carried the SHA-1 form, so
+     *  the audit found both printed in one list. Those moved to `sku`; see the
+     *  note above `generateBarcodeId` for why the widths cannot share a field.
+     */
     barcodeId?: string;
+    /**
+     * The HUMAN key — a stock-keeping unit a person reads, says aloud and files
+     * by. `LIR-BURS-K3F9P` from `generateSku`, or whatever the seller authored.
+     *
+     * 🛑 Distinct from `barcodeId` ON PURPOSE, and the pair is the whole
+     * reconciliation of the audit's two-barcode finding. A barcode is scanned
+     * and must be fixed-width for a label to fit; a SKU is spoken and must be
+     * meaningful. One field could not be both, and was not.
+     *
+     * Optional, and absent on most live rows until the backfill runs
+     * (`appkit/scripts/backfill-sku.mjs`). 🛑 Nothing may assume its presence:
+     * the admin toolbar advertised SKU search for a field that did not exist at
+     * all, and every row read "No SKU" as a result.
+     */
+    sku?: string;
     /** Normalized edge-n-gram search field. Replaced `searchTokens`. */
     searchTxt?: string[];
 }
@@ -795,7 +838,7 @@ export declare const PRODUCT_COLLECTION: "products";
 export declare const PRODUCT_INDEXED_FIELDS: readonly ["storeId", "status", "category", "categoryIds", "featured", "listingType", "isPromoted", "isOnSale", "isSold", "searchTxt", "createdAt", "barcodeId", "physicalLocation.zone"];
 export declare const DEFAULT_PRODUCT_DATA: Partial<ProductDocument>;
 export declare const PRODUCT_PUBLIC_FIELDS: readonly ["allowOffers", "minOfferPercent", "id", "title", "description", "category", "categoryIds", "categoryIdNames", "subcategory", "brand", "price", "originalPrice", "currency", "stockQuantity", "availableQuantity", "images", "status", "storeName", "featured", "tags", "specifications", "features", "shippingInfo", "returnPolicy", "finalSale", "isLot", "lotSize", "unitLabel", "partGlossaryId", "colourway", "mouldVariant", "assembledFrom", "views7d", "views30d", "unitLabel", "partGlossaryId", "colourway", "mouldVariant", "assembledFrom", "listingType", "auctionEndDate", "startingBid", "currentBid", "bidCount", "reservePrice", "buyNowPrice", "minBidIncrement", "autoExtendable", "auctionExtensionMinutes", "auctionShippingPaidBy", "bidsHaveStarted", "grading", "card", "classified", "digitalCode", "liveItem", "catalogProductId", "preOrderDeliveryDate", "preOrderDepositPercent", "preOrderDepositAmount", "preOrderMaxQuantity", "preOrderCurrentCount", "preOrderProductionStatus", "preOrderCancellable", "condition", "insurance", "insuranceCost", "shippingPaidBy", "isPromoted", "isOnSale", "isSold", "madeToOrder", "sourceStickerSheetId", "sourceStickerPartOrdinal", "slug", "seoTitle", "seoDescription", "seoKeywords", "viewCount", "customFields", "customSections", "sublistingCategoryId", "groupId", "isGroupParent", "groupParentSlug", "groupChildSlugs", "groupTitle", "groupMinMembers", "groupMaxMembers", "groupMaxUnitsPerMember", "groupRequiredMemberIds", "groupDiscountPercent", "createdAt"];
-export declare const PRODUCT_UPDATABLE_FIELDS: readonly ["title", "description", "category", "categoryIds", "subcategory", "brand", "price", "originalPrice", "stockQuantity", "images", "status", "tags", "specifications", "features", "shippingInfo", "returnPolicy", "finalSale", "isLot", "lotSize", "pickupAddressId", "condition", "insurance", "shippingPaidBy", "autoExtendable", "auctionExtensionMinutes", "auctionShippingPaidBy", "reservePrice", "buyNowPrice", "minBidIncrement", "bidsHaveStarted", "grading", "card", "classified", "digitalCode", "liveItem", "catalogProductId", "listingType", "preOrderDeliveryDate", "preOrderDepositPercent", "preOrderDepositAmount", "preOrderMaxQuantity", "preOrderProductionStatus", "preOrderCancellable", "isOnSale", "isSold", "madeToOrder", "sourceStickerSheetId", "sourceStickerPartOrdinal", "allowShipBeforeEmiComplete", "gstRate", "hsnCode", "authenticity", "printMeta", "seoTitle", "seoDescription", "seoKeywords", "customFields", "customSections", "sublistingCategoryId", "groupId", "isGroupParent", "groupParentSlug", "groupChildSlugs", "groupTitle", "groupMinMembers", "groupMaxMembers", "groupMaxUnitsPerMember", "groupRequiredMemberIds", "groupDiscountPercent", "barcodeId"];
+export declare const PRODUCT_UPDATABLE_FIELDS: readonly ["title", "description", "category", "categoryIds", "subcategory", "brand", "price", "originalPrice", "stockQuantity", "images", "status", "tags", "specifications", "features", "shippingInfo", "returnPolicy", "finalSale", "isLot", "lotSize", "physicalLocation", "sku", "pickupAddressId", "condition", "insurance", "shippingPaidBy", "autoExtendable", "auctionExtensionMinutes", "auctionShippingPaidBy", "reservePrice", "buyNowPrice", "minBidIncrement", "bidsHaveStarted", "grading", "card", "classified", "digitalCode", "liveItem", "catalogProductId", "listingType", "preOrderDeliveryDate", "preOrderDepositPercent", "preOrderDepositAmount", "preOrderMaxQuantity", "preOrderProductionStatus", "preOrderCancellable", "isOnSale", "isSold", "madeToOrder", "sourceStickerSheetId", "sourceStickerPartOrdinal", "allowShipBeforeEmiComplete", "gstRate", "hsnCode", "authenticity", "printMeta", "seoTitle", "seoDescription", "seoKeywords", "customFields", "customSections", "sublistingCategoryId", "groupId", "isGroupParent", "groupParentSlug", "groupChildSlugs", "groupTitle", "groupMinMembers", "groupMaxMembers", "groupMaxUnitsPerMember", "groupRequiredMemberIds", "groupDiscountPercent", "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

@@ -305,6 +305,27 @@ export const PRODUCT_UPDATABLE_FIELDS = [
      * (which both renderers read) was not in this list either. */
     "isLot",
     "lotSize",
+    /*
+     * 🛑 `physicalLocation` WAS MISSING, and the comment five lines above
+     * describes the identical defect one field over: "the form wrote
+     * `compareAtPrice`, nothing declared it, and `originalPrice` was not in
+     * this list either".
+     *
+     * `ProductForm` renders three inputs for it — zone, shelf, bin. They
+     * accept typing, they parse, and the repository dropped the whole object
+     * on every save, so 0 of the catalogue's products carry one. The field is
+     * declared on `ProductDocument`, and `physicalLocation.zone` is even in
+     * the searchable-field list, so everything existed except the one entry
+     * that lets a write through.
+     *
+     * Added rather than removing the inputs. Phase 5 of the current plan
+     * retires this field in favour of a box registry with a move ledger, and
+     * until that lands a working field is better than three inputs that lie —
+     * a seller who labels a shelf today should find it there tomorrow.
+     */
+    "physicalLocation",
+    // The human stock key. Seller-authored or generated; see ProductDocument.sku.
+    "sku",
     "pickupAddressId",
     "condition",
     "insurance",

package/dist/features/promotions/components/PromotionsView.js

@@ -7,7 +7,7 @@ export function PromotionsViewProductSection({ title, subtitle, renderProducts,
 }
 /** Slim hero banner for the promotions page — tabs + content live in the page. */
 export function PromotionsHero({ labels, heroBannerClass = "", }) {
-    return (_jsx(Section, { color: "inverse", tone: "accent-banner", className: `${heroBannerClass}`, padding: "y-2-5xl", children: _jsxs(Div, { paddingX: "x-page", className: "max-w-5xl mx-auto text-left", children: [_jsxs(Text, { color: "inverse", className: "mb-2 tracking-widest", size: "sm", weight: "medium", transform: "uppercase", children: ["\uD83C\uDF89 ", labels.exclusiveOffersBadge] }), _jsx(Heading, { color: "inverse", level: 1, variant: "none", className: "mb-4", children: labels.title }), _jsx(Text, { color: "inverse", variant: "none", className: "/90 max-w-2xl mx-auto", size: "lg", children: labels.subtitle })] }) }));
+    return (_jsx(Section, { color: "inverse", tone: "accent-banner", className: `${heroBannerClass}`, padding: "y-2-5xl", children: _jsxs(Div, { paddingX: "x-page", className: "max-w-5xl mx-auto text-left", children: [_jsxs(Text, { color: "inverse", className: "mb-2 tracking-widest", size: "sm", weight: "medium", transform: "uppercase", children: ["\uD83C\uDF89 ", labels.exclusiveOffersBadge] }), _jsx(Heading, { color: "inverse", level: 1, variant: "none", className: "mb-4", children: labels.title }), _jsx(Text, { color: "inverse-muted", variant: "none", className: "max-w-2xl mx-auto", size: "lg", children: labels.subtitle })] }) }));
 }
 /** @deprecated Use PromotionsHero + per-tab content in your page instead. */
 export function PromotionsView({ labels, hasContent, heroBannerClass = "", renderCoupons, couponsCount = 0, renderDealsSection, renderFeaturedSection, }) {

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

@@ -21,6 +21,38 @@ export declare class ClaimedCouponsRepository extends BaseRepository<ClaimedCoup
     /** Idempotent claim — returns the existing claim if one already exists. */
     claim(input: ClaimedCouponCreateInput): Promise<ClaimedCouponDocument>;
     listForUser(userId: string): Promise<ClaimedCouponDocument[]>;
+    /**
+     * Re-sync every wallet copy of a coupon's snapshot after the source coupon
+     * is edited (D59).
+     *
+     * 🛑 WHY THIS EXISTS, and what the defect actually was — the plan overstates
+     * it and the correction matters.
+     *
+     * `ClaimedCouponDocument.couponSnapshot` is a denormalised copy of
+     * `discount` + `restrictions` + `type` + `scope`, so `/user/coupons` renders
+     * the wallet in ONE indexed read instead of N joins. Nothing re-synced it
+     * when an admin edited the source coupon, so it drifted — the mirror shape
+     * of Root Cause #42.
+     *
+     * The plan says the consequence is that "a spin/raffle win keeps the old
+     * terms". **It does not.** Verified: redemption goes
+     * `validateCouponForCart` → `_fetchAndValidateCoupon` →
+     * `getCouponByCode(code)`, which reads the LIVE `CouponDocument`. The
+     * snapshot is never consulted when money moves.
+     *
+     * So this is a DISPLAY defect, not a money one — and still worth fixing,
+     * because the wallet advertising "20% off" while checkout applies 10% is a
+     * trust problem and a support ticket. Calling it a money bug would have
+     * sent someone looking for an exploit that is not there.
+     *
+     * Re-syncing beats dropping the snapshot: rendering live would cost a join
+     * per wallet row, which is the exact thing the denormalisation buys.
+     *
+     * Best-effort by design — a failed re-sync must never fail the admin's
+     * coupon edit, which has already succeeded. The worst case is a stale
+     * DISPLAY, i.e. exactly today's behaviour.
+     */
+    resyncSnapshotsForCoupon(couponId: string, snapshot: ClaimedCouponSnapshot): Promise<number>;
     markUsed(userId: string, couponCode: string, orderId: string): Promise<void>;
     softRemove(userId: string, couponCode: string): Promise<void>;
 }

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

@@ -82,6 +82,64 @@ export class ClaimedCouponsRepository extends BaseRepository {
             throw new DatabaseError("Failed to list claimed coupons", error);
         }
     }
+    /**
+     * Re-sync every wallet copy of a coupon's snapshot after the source coupon
+     * is edited (D59).
+     *
+     * 🛑 WHY THIS EXISTS, and what the defect actually was — the plan overstates
+     * it and the correction matters.
+     *
+     * `ClaimedCouponDocument.couponSnapshot` is a denormalised copy of
+     * `discount` + `restrictions` + `type` + `scope`, so `/user/coupons` renders
+     * the wallet in ONE indexed read instead of N joins. Nothing re-synced it
+     * when an admin edited the source coupon, so it drifted — the mirror shape
+     * of Root Cause #42.
+     *
+     * The plan says the consequence is that "a spin/raffle win keeps the old
+     * terms". **It does not.** Verified: redemption goes
+     * `validateCouponForCart` → `_fetchAndValidateCoupon` →
+     * `getCouponByCode(code)`, which reads the LIVE `CouponDocument`. The
+     * snapshot is never consulted when money moves.
+     *
+     * So this is a DISPLAY defect, not a money one — and still worth fixing,
+     * because the wallet advertising "20% off" while checkout applies 10% is a
+     * trust problem and a support ticket. Calling it a money bug would have
+     * sent someone looking for an exploit that is not there.
+     *
+     * Re-syncing beats dropping the snapshot: rendering live would cost a join
+     * per wallet row, which is the exact thing the denormalisation buys.
+     *
+     * Best-effort by design — a failed re-sync must never fail the admin's
+     * coupon edit, which has already succeeded. The worst case is a stale
+     * DISPLAY, i.e. exactly today's behaviour.
+     */
+    async resyncSnapshotsForCoupon(couponId, snapshot) {
+        try {
+            /*
+             * Bounded at 500. A coupon claimed by more wallets than that is a
+             * campaign, and silently updating only the first page would be worse
+             * than saying so — the count is returned and the caller logs it.
+             */
+            const snap = await this.db
+                .collection(this.collection)
+                .where("couponId", "==", couponId)
+                .limit(500)
+                .get();
+            if (snap.empty)
+                return 0;
+            const writer = this.db.bulkWriter();
+            for (const doc of snap.docs) {
+                writer.update(doc.ref, { couponSnapshot: snapshot, updatedAt: new Date() });
+            }
+            await writer.close();
+            return snap.size;
+        }
+        catch (error) {
+            void normalizeError(error);
+            // Deliberately NOT thrown — see the docstring.
+            return 0;
+        }
+    }
     async markUsed(userId, couponCode, orderId) {
         const id = createClaimedCouponId(userId, couponCode);
         try {

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

@@ -204,18 +204,45 @@ export function calculateDiscount(coupon, orderTotal,
 lines) {
     if (coupon.discount.minPurchase && orderTotal < coupon.discount.minPurchase)
         return 0;
+    /*
+     * ── Tiered discounts ──────────────────────────────────────────────────────
+     *
+     * 🛑 `tiers` HAS BEEN ON `CouponDocument` SINCE IT SHIPPED, AND NOTHING EVER
+     * READ IT. `getTieredDiscount` existed, was exported from the barrel, and
+     * had ZERO callers — so a coupon carrying tiers was charged at its flat
+     * `discount.value` and the tiers did nothing at all. This is the reader.
+     *
+     * A tier REPLACES `discount.value` rather than adding to it, which is what
+     * its own field comment describes: "Percentage (0-100) when the coupon type
+     * === percentage; decimal rupees when type === fixed". So the tier is the
+     * value for that band, not a bonus on top.
+     *
+     * 🛑 Only `percentage` and `fixed` consult it. A BOGO's value lives in
+     * `bxgy` and free shipping is a shipping-line waiver, so neither has a
+     * `discount.value` for a tier to replace — applying one there would be
+     * inventing semantics the field does not define.
+     *
+     * 🛑 `> 0` means "a tier matched". `getTieredDiscount` returns 0 for all
+     * three of "no tiers", "no band matched" and "the matched band is worth
+     * zero", and those are indistinguishable in its signature. That is fine
+     * here ONLY because a zero-value tier is a no-op either way — it would
+     * discount nothing whether honoured or ignored. Do not reuse this test for
+     * anything where zero is a meaningful outcome.
+     */
+    const tieredValue = getTieredDiscount(coupon.tiers, orderTotal);
+    const effectiveValue = tieredValue > 0 ? tieredValue : coupon.discount.value;
     let discountAmount = 0;
     switch (coupon.type) {
         case "percentage":
-            // audit-money-units-ok: percentage divisor (coupon.discount.value is 0-100), not paise
-            discountAmount = (orderTotal * coupon.discount.value) / 100;
+            // audit-money-units-ok: percentage divisor (effectiveValue is 0-100), not paise
+            discountAmount = (orderTotal * effectiveValue) / 100;
             if (coupon.discount.maxDiscount &&
                 discountAmount > coupon.discount.maxDiscount) {
                 discountAmount = coupon.discount.maxDiscount;
             }
             break;
         case "fixed":
-            discountAmount = Math.min(coupon.discount.value, orderTotal);
+            discountAmount = Math.min(effectiveValue, orderTotal);
             break;
         case "buy_x_get_y":
             // Needs the basket — see calculateBxgyDiscount. Capped at the total so a

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

@@ -34,11 +34,11 @@ export declare const tieredDiscountSchema: z.ZodObject<{
     minAmount: z.ZodEffects<z.ZodNumber, number, number>;
     discountValue: z.ZodNumber;
 }, "strip", z.ZodTypeAny, {
-    discountValue: number;
     minAmount: number;
-}, {
     discountValue: number;
+}, {
     minAmount: number;
+    discountValue: number;
 }>;
 export declare const usageConfigSchema: z.ZodObject<{
     totalLimit: z.ZodOptional<z.ZodNumber>;
@@ -177,11 +177,11 @@ export declare const couponFirestoreSchema: z.ZodObject<{
         minAmount: z.ZodEffects<z.ZodNumber, number, number>;
         discountValue: z.ZodNumber;
     }, "strip", z.ZodTypeAny, {
-        discountValue: number;
         minAmount: number;
-    }, {
         discountValue: number;
+    }, {
         minAmount: number;
+        discountValue: number;
     }>, "many">>;
     usage: z.ZodObject<{
         totalLimit: z.ZodOptional<z.ZodNumber>;
@@ -320,8 +320,8 @@ export declare const couponFirestoreSchema: z.ZodObject<{
         applicableCategories?: string[] | undefined;
     } | undefined;
     tiers?: {
-        discountValue: number;
         minAmount: number;
+        discountValue: number;
     }[] | undefined;
 }, {
     code: string;
@@ -378,8 +378,8 @@ export declare const couponFirestoreSchema: z.ZodObject<{
         applicableCategories?: string[] | undefined;
     } | undefined;
     tiers?: {
-        discountValue: number;
         minAmount: number;
+        discountValue: number;
     }[] | undefined;
 }>;
 export declare const couponUsageFirestoreSchema: z.ZodObject<{

package/dist/features/protection-claims/repository/protection-claims.repository.d.ts

@@ -0,0 +1,54 @@
+import { BaseRepository } from "../../../providers/db-firebase";
+import { type ProtectionClaimDocument, type ProtectionClaimReason, type ProtectionClaimStatus } from "../schemas/firestore";
+import type { ClaimFinding, ClaimOutcome, ProtectionKind } from "../../../_internal/shared/features/shipping/protections";
+export interface FileClaimInput {
+    kind: ProtectionKind;
+    orderId: string;
+    storeId: string;
+    buyerId: string;
+    reason: ProtectionClaimReason;
+    detail: string;
+    claimedAmount: number;
+    itemIds?: string[];
+    evidenceUrls?: string[];
+    isTestData?: boolean;
+    now?: Date;
+}
+export declare class ProtectionClaimsRepository extends BaseRepository<ProtectionClaimDocument> {
+    constructor();
+    /**
+     * File a claim. **Refuses a second claim on the same (order, kind).**
+     *
+     * 🛑 `.create()` with a deterministic id, and the refusal is a 409 rather
+     * than a silent no-op — the buyer needs to know their existing claim is the
+     * one being worked, not that their second attempt vanished.
+     *
+     * Why it matters more here than elsewhere: a protected sale claim is
+     * refunded **unconditionally** (`adjudicateClaim` refunds on a
+     * change-of-mind finding too, and only shifts who pays). So N claims on one
+     * order would be N refunds against the same goods.
+     */
+    file(input: FileClaimInput): Promise<ProtectionClaimDocument>;
+    /**
+     * Record the human finding and the outcome `adjudicateClaim` produced.
+     *
+     * 🛑 It does NOT move money. The refund is `processRefundAction`'s job, and
+     * keeping them apart is what lets the refund carry its own idempotency key
+     * — a claim that adjudicated and then failed to refund leaves a `upheld`
+     * claim with no `refundId`, which is a findable state rather than a lost one.
+     */
+    adjudicate(id: string, input: {
+        finding: ClaimFinding;
+        outcome: ClaimOutcome;
+        adjudicatedBy: string;
+        now?: Date;
+    }): Promise<void>;
+    /** Link the refund that settled this claim. */
+    attachRefund(id: string, refundId: string, now?: Date): Promise<void>;
+    setStatus(id: string, status: ProtectionClaimStatus, reason: string, now?: Date): Promise<void>;
+    findByOrderAndKind(orderId: string, kind: ProtectionKind): Promise<ProtectionClaimDocument | null>;
+    /** The admin queue: claims still needing work, oldest first. */
+    listActive(limit?: number): Promise<ProtectionClaimDocument[]>;
+    listForBuyer(buyerId: string, limit?: number): Promise<ProtectionClaimDocument[]>;
+}
+export declare function protectionClaimsRepository(): ProtectionClaimsRepository;

package/dist/features/protection-claims/repository/protection-claims.repository.js

@@ -0,0 +1,174 @@
+import { BaseRepository, prepareForFirestore } from "../../../providers/db-firebase/index.js";
+import { normalizeError } from "../../../errors/normalize.js";
+import { buildHistoryEntry } from "../../../_internal/shared/history/history.js";
+import { ConflictError } from "../../../errors/index.js";
+import { PROTECTION_CLAIMS_COLLECTION, PROTECTION_CLAIM_ACTIVE_STATUSES, PROTECTION_CLAIM_FIELDS, createProtectionClaimId, } from "../schemas/firestore.js";
+const GRPC_ALREADY_EXISTS = 6;
+function isAlreadyExists(err) {
+    if (typeof err !== "object" || err === null)
+        return false;
+    const code = err.code;
+    if (code === GRPC_ALREADY_EXISTS)
+        return true;
+    if (code === "already-exists" || code === "ALREADY_EXISTS")
+        return true;
+    const message = err.message;
+    return typeof message === "string" && message.includes("ALREADY_EXISTS");
+}
+export class ProtectionClaimsRepository extends BaseRepository {
+    constructor() {
+        super(PROTECTION_CLAIMS_COLLECTION);
+    }
+    /**
+     * File a claim. **Refuses a second claim on the same (order, kind).**
+     *
+     * 🛑 `.create()` with a deterministic id, and the refusal is a 409 rather
+     * than a silent no-op — the buyer needs to know their existing claim is the
+     * one being worked, not that their second attempt vanished.
+     *
+     * Why it matters more here than elsewhere: a protected sale claim is
+     * refunded **unconditionally** (`adjudicateClaim` refunds on a
+     * change-of-mind finding too, and only shifts who pays). So N claims on one
+     * order would be N refunds against the same goods.
+     */
+    async file(input) {
+        const now = input.now ?? new Date();
+        const id = createProtectionClaimId(input.orderId, input.kind);
+        const doc = {
+            id,
+            kind: input.kind,
+            orderId: input.orderId,
+            storeId: input.storeId,
+            buyerId: input.buyerId,
+            status: "open",
+            reason: input.reason,
+            detail: input.detail,
+            claimedAmount: input.claimedAmount,
+            ...(input.itemIds?.length ? { itemIds: input.itemIds } : {}),
+            ...(input.evidenceUrls?.length ? { evidenceUrls: input.evidenceUrls } : {}),
+            ...(input.isTestData ? { isTestData: true } : {}),
+            statusHistory: [
+                buildHistoryEntry({
+                    actor: { role: "buyer", uid: input.buyerId },
+                    trigger: `protectionClaim:file:${input.kind}`,
+                    changes: { status: { from: null, to: "open" } },
+                    reason: input.reason,
+                    now,
+                }),
+            ],
+            createdAt: now,
+            updatedAt: now,
+        };
+        try {
+            await this.getCollection().doc(id).create(prepareForFirestore(doc));
+            return doc;
+        }
+        catch (err) {
+            if (isAlreadyExists(err)) {
+                void normalizeError(err);
+                throw new ConflictError(`A ${input.kind} protection claim is already open on this order. Add to that claim rather than filing a second one.`);
+            }
+            void normalizeError(err);
+            throw err;
+        }
+    }
+    /**
+     * Record the human finding and the outcome `adjudicateClaim` produced.
+     *
+     * 🛑 It does NOT move money. The refund is `processRefundAction`'s job, and
+     * keeping them apart is what lets the refund carry its own idempotency key
+     * — a claim that adjudicated and then failed to refund leaves a `upheld`
+     * claim with no `refundId`, which is a findable state rather than a lost one.
+     */
+    async adjudicate(id, input) {
+        const now = input.now ?? new Date();
+        const existing = await this.findById(id);
+        const status = input.outcome.refundBuyer ? "upheld" : "rejected";
+        await this.getCollection()
+            .doc(id)
+            .update({
+            status,
+            finding: input.finding,
+            outcome: {
+                refundBuyer: input.outcome.refundBuyer,
+                costBorneBy: input.outcome.costBorneBy,
+                raisesReport: input.outcome.raisesReport,
+            },
+            adjudicatedBy: input.adjudicatedBy,
+            adjudicatedAt: now,
+            updatedAt: now,
+            statusHistory: [
+                ...(existing?.statusHistory ?? []),
+                buildHistoryEntry({
+                    actor: { role: "admin", uid: input.adjudicatedBy },
+                    trigger: "protectionClaim:adjudicate",
+                    changes: {
+                        status: { from: existing?.status ?? null, to: status },
+                        finding: { from: null, to: input.finding },
+                    },
+                    note: `cost borne by ${input.outcome.costBorneBy}`,
+                    now,
+                }),
+            ],
+        });
+    }
+    /** Link the refund that settled this claim. */
+    async attachRefund(id, refundId, now = new Date()) {
+        try {
+            await this.getCollection().doc(id).update({ refundId, updatedAt: now });
+        }
+        catch (err) {
+            void normalizeError(err);
+        }
+    }
+    async setStatus(id, status, reason, now = new Date()) {
+        try {
+            const existing = await this.findById(id);
+            await this.getCollection()
+                .doc(id)
+                .update({
+                status,
+                updatedAt: now,
+                statusHistory: [
+                    ...(existing?.statusHistory ?? []),
+                    buildHistoryEntry({
+                        actor: { role: "system" },
+                        trigger: "protectionClaim:setStatus",
+                        changes: { status: { from: existing?.status ?? null, to: status } },
+                        reason,
+                        now,
+                    }),
+                ],
+            });
+        }
+        catch (err) {
+            void normalizeError(err);
+        }
+    }
+    async findByOrderAndKind(orderId, kind) {
+        return this.findById(createProtectionClaimId(orderId, kind));
+    }
+    /** The admin queue: claims still needing work, oldest first. */
+    async listActive(limit = 100) {
+        const snap = await this.getCollection()
+            .where(PROTECTION_CLAIM_FIELDS.STATUS, "in", [...PROTECTION_CLAIM_ACTIVE_STATUSES])
+            .orderBy(PROTECTION_CLAIM_FIELDS.CREATED_AT, "asc")
+            .limit(limit)
+            .get();
+        return snap.docs.map((d) => this.mapDoc(d));
+    }
+    async listForBuyer(buyerId, limit = 50) {
+        const snap = await this.getCollection()
+            .where(PROTECTION_CLAIM_FIELDS.BUYER_ID, "==", buyerId)
+            .orderBy(PROTECTION_CLAIM_FIELDS.CREATED_AT, "desc")
+            .limit(limit)
+            .get();
+        return snap.docs.map((d) => this.mapDoc(d));
+    }
+}
+let cached = null;
+export function protectionClaimsRepository() {
+    if (!cached)
+        cached = new ProtectionClaimsRepository();
+    return cached;
+}