@mohasinac/appkit 4.70.0 → 4.71.2

package/dist/_internal/server/jobs/core/settlementVendorRegister.js

@@ -0,0 +1,414 @@
+/**
+ * settlementVendorRegister — register one store as a split-settlement vendor.
+ *
+ * ## Why this is a job and not an inline call
+ *
+ * The trigger is a store being approved (`onStoreActivated`, off the `ACTIVE`
+ * branch of `storeRepository.setStatus`, dispatched by the admin PATCH route).
+ * Registration is an outbound HTTPS call on a path an admin is waiting on,
+ * against Rule #6's 10s sync-function ceiling, in a request that has already
+ * made two Firestore reads and up to three writes. CLAUDE.md § Async Job
+ * Primitive: a route enqueues, this runs in a Firebase Function.
+ *
+ * ## Why registration has to happen at all
+ *
+ * A marketplace cannot be a payment aggregator and cannot commingle buyer funds
+ * with its own, so a seller's share must be settled buyer → aggregator escrow →
+ * seller, with the platform never holding it. For the aggregator to pay a seller
+ * it must know them as a VENDOR. A store with no vendor registration therefore
+ * cannot be part of a multi-vendor online cart at all — the capture is refused
+ * rather than collected into the platform's account.
+ *
+ * ## 🛑 IT RECORDS WHY IT COULD NOT REGISTER. IT NEVER FAILS SILENTLY.
+ *
+ * Blocker #4: payout details live on the OWNER'S USER DOCUMENT while approval
+ * reads the STORE, so this job can and routinely will fire for a store with
+ * nothing to register. That is the normal case for a brand-new seller, not an
+ * error — and it is the case that must be legible, because the seller's own
+ * next action (fill in the payout form) is what clears it.
+ *
+ * So every exit writes a `settlementVendors.<gateway>` record with a stated
+ * reason, and the job reports `skipped` rather than `failed` for anything the
+ * SELLER can fix. `blocked` is distinguished from `rejected` for exactly that
+ * reason — see `SettlementVendorStatusValues`.
+ *
+ * ## 🛑 Idempotent, because it WILL run again
+ *
+ * Jobs retry, and an admin can re-approve a store. `vendorId` is always the
+ * store slug, so a repeat call names the same vendor; the adapter's own
+ * `registerSettlementVendor` is documented idempotent by contract.
+ */
+import { storeRepository } from "../../../../features/stores/repository/store.repository.js";
+import { userRepository } from "../../../../features/auth/repository/user.repository.js";
+import { sellerProfileRepository } from "../../../../features/seller/repository/seller-profile.repository.js";
+import { SettlementVendorStatusValues, StoreStatusValues, } from "../../../../features/stores/schemas/firestore.js";
+import { PAYOUT_VERIFICATION, payoutDestinationIssues, isValidPan, } from "../../../shared/features/payouts/destination.js";
+import { paymentGatewayCandidates } from "../../features/checkout/gateway-selection.js";
+import { normalizeError } from "../../../../errors/normalize.js";
+/** `outcome` → the stored status. A straight mapping, named so it cannot drift. */
+const STATUS_BY_OUTCOME = {
+    active: SettlementVendorStatusValues.ACTIVE,
+    pending: SettlementVendorStatusValues.PENDING,
+    rejected: SettlementVendorStatusValues.REJECTED,
+};
+/**
+ * `outcome` → what the SELLER's payout destination verification becomes.
+ *
+ * 🛑 This is the only place `verified` is ever written, and it is written from
+ * a gateway's answer and nothing else. `verify_account: true` on the Cashfree
+ * vendor payload asks the aggregator to run its own account verification, which
+ * is the one check in this system that is not a self-assertion — we hold no
+ * banking licence and have no penny-drop.
+ *
+ * 🛑 `pending` maps to `pending`, NOT to `verified`. An aggregator that has
+ * taken the vendor and is still checking has not said the account is good.
+ */
+const VERIFICATION_BY_OUTCOME = {
+    active: PAYOUT_VERIFICATION.VERIFIED,
+    pending: PAYOUT_VERIFICATION.PENDING,
+    rejected: PAYOUT_VERIFICATION.FAILED,
+};
+/** One `skipped`/`failed` exit, recorded on the store and reported to the caller. */
+async function recordAndSkip(input) {
+    const { storeSlug, gateway, status, reason, priorAttempts, ctx } = input;
+    const record = {
+        // 🛑 Still OUR id even on a blocked record: it is what a later successful
+        // run will register, and an empty string here would make the split builder
+        // read "registered with no id" rather than "not registered".
+        vendorId: storeSlug,
+        status,
+        message: reason,
+        lastAttemptAt: ctx.now,
+        attempts: priorAttempts + 1,
+    };
+    try {
+        await storeRepository.setSettlementVendor(storeSlug, gateway, record);
+    }
+    catch (err) {
+        const normalized = normalizeError(err);
+        ctx.logger.error("settlementVendorRegister: could not record the registration outcome", err, { storeSlug, gateway, error: normalized.message });
+    }
+    ctx.logger.info("settlementVendorRegister: not registered", {
+        storeSlug,
+        gateway,
+        status,
+        reason,
+    });
+    return {
+        summary: { total: 1, succeeded: 0, skipped: 1, failed: 0 },
+        succeeded: [],
+        skipped: [storeSlug],
+        failed: [],
+        data: { storeSlug, gateway, status, reason },
+    };
+}
+export async function runSettlementVendorRegister(payload, ctx) {
+    const storeSlug = payload.storeSlug?.trim();
+    if (!storeSlug) {
+        return {
+            summary: { total: 0, succeeded: 0, skipped: 0, failed: 1 },
+            succeeded: [],
+            skipped: [],
+            failed: [{ id: "(none)", reason: "settlementVendorRegister requires a storeSlug" }],
+        };
+    }
+    /*
+     * 🛑 Which gateway? THE SPLIT-CAPABLE ONE, selected on the CAPABILITY and
+     * never on the name "cashfree" (Root Cause #61 — and see
+     * `SettlementGatewayCandidate`'s own 🛑). `paymentGatewayCandidates` carries
+     * the registry's `supportsSplit`, which is a fact about the product the
+     * business onboarded rather than about the adapter.
+     *
+     * 🛑 NO splitting gateway enabled is NOT a failure. It is a configuration
+     * state — most installs have none — and a job that marked every approval
+     * failed for it would fill the queue with noise. Nothing is recorded on the
+     * store either: there is no gateway to key the record under.
+     */
+    const splitCapable = paymentGatewayCandidates().filter((entry) => entry.candidate.supportsSplit === true);
+    if (splitCapable.length === 0) {
+        ctx.logger.info("settlementVendorRegister: no split-capable gateway is enabled — nothing to register", { storeSlug });
+        return {
+            summary: { total: 1, succeeded: 0, skipped: 1, failed: 0 },
+            succeeded: [],
+            skipped: [storeSlug],
+            failed: [],
+            data: { storeSlug, reason: "no split-capable gateway enabled" },
+        };
+    }
+    /*
+     * Lowest `order` wins, matching the per-cart resolver's own tie-break. With
+     * one splitting gateway live today this is always that one; registering a
+     * store with EVERY splitting gateway is a deliberate later decision (it
+     * multiplies the outbound calls and the refusal surface), which is why the
+     * stored record is keyed per gateway and this loop is not.
+     */
+    const [{ provider, candidate }] = [...splitCapable].sort((a, b) => (a.candidate.order ?? Number.MAX_SAFE_INTEGER) -
+        (b.candidate.order ?? Number.MAX_SAFE_INTEGER));
+    const gateway = candidate.name;
+    const store = await storeRepository.findById(storeSlug);
+    if (!store) {
+        return {
+            summary: { total: 1, succeeded: 0, skipped: 0, failed: 1 },
+            succeeded: [],
+            skipped: [],
+            failed: [{ id: storeSlug, reason: "store not found" }],
+        };
+    }
+    const prior = store.settlementVendors?.[gateway];
+    const priorAttempts = prior?.attempts ?? 0;
+    /*
+     * 🛑 Already `active` → do nothing, and this is the idempotency that matters
+     * most. Re-approving a store, or a job retry, must not send a second
+     * registration: whether the aggregator treats that as an update or a conflict
+     * is unconfirmed (see `registerSettlementVendor`'s 🛑), and the one thing we
+     * can control is not asking twice when we already have the answer.
+     */
+    if (prior?.status === SettlementVendorStatusValues.ACTIVE && prior.vendorId) {
+        ctx.logger.info("settlementVendorRegister: already registered", { storeSlug, gateway });
+        return {
+            summary: { total: 1, succeeded: 1, skipped: 0, failed: 0 },
+            succeeded: [storeSlug],
+            skipped: [],
+            failed: [],
+            data: { storeSlug, gateway, vendorId: prior.vendorId, status: prior.status },
+        };
+    }
+    // A store that is not active cannot sell, so it has nothing to be settled.
+    if (store.status !== StoreStatusValues.ACTIVE) {
+        return recordAndSkip({
+            storeSlug,
+            gateway,
+            status: SettlementVendorStatusValues.BLOCKED,
+            reason: `the store is "${store.status}", not active`,
+            priorAttempts,
+            ctx,
+        });
+    }
+    /*
+     * ── Blocker #4: the payout destination lives on the OWNER'S USER DOCUMENT ──
+     *
+     * 🛑 `revealUser`, never the raw document. `UserRepository` is
+     * ciphertext-by-default and `payoutDetails` is decrypted by
+     * `decryptPayoutDetails` — a DIFFERENT scheme from `PAYOUT_PII_FIELDS`, which
+     * covers a payout document's own `upiId`/`sellerEmail`. Reading the raw
+     * fields would hand the aggregator `enc:v1:…` as an account number, which it
+     * would accept as a string and then fail to settle to, months later.
+     */
+    const owner = store.ownerId ? await userRepository.findById(store.ownerId) : null;
+    if (!owner) {
+        return recordAndSkip({
+            storeSlug,
+            gateway,
+            status: SettlementVendorStatusValues.BLOCKED,
+            reason: "the store has no owner account to register",
+            priorAttempts,
+            ctx,
+        });
+    }
+    const ownerPlain = userRepository.revealUser(owner);
+    // payoutDetails is seller-only data — sellerProfiles, not users. Same
+    // ciphertext-by-default / revealProfile reasoning as the comment above.
+    const ownerProfile = store.ownerId ? await sellerProfileRepository.findById(store.ownerId) : null;
+    const details = ownerProfile ? sellerProfileRepository.revealProfile(ownerProfile).payoutDetails : undefined;
+    const destinationIssues = payoutDestinationIssues(details);
+    if (destinationIssues.length > 0) {
+        return recordAndSkip({
+            storeSlug,
+            gateway,
+            status: SettlementVendorStatusValues.BLOCKED,
+            reason: `the seller's payout details are incomplete — ` +
+                destinationIssues.map((i) => i.message).join(" "),
+            priorAttempts,
+            ctx,
+        });
+    }
+    /*
+     * ── Blocker #1: the PAN ──────────────────────────────────────────────────
+     *
+     * 🛑 Required HERE and nowhere else, and it is a soft requirement by design.
+     * Most aggregator entity types need a PAN, but which ones is the aggregator's
+     * rule and not ours — so this job refuses only on a MALFORMED one (which the
+     * gateway would reject anyway, for a reason nobody could read) and sends an
+     * absent one through as absent, letting the gateway make its own decision.
+     * Guessing on its behalf is how blocker #5 (an unregistered seller may be
+     * un-onboardable) turns into "we decided they cannot sell".
+     */
+    const pan = storeRepository.revealPan(store);
+    if (pan && !isValidPan(pan)) {
+        return recordAndSkip({
+            storeSlug,
+            gateway,
+            status: SettlementVendorStatusValues.BLOCKED,
+            reason: "the PAN on file is not a valid PAN (five letters, four digits, one letter)",
+            priorAttempts,
+            ctx,
+        });
+    }
+    const email = ownerPlain.email?.trim();
+    const phone = ownerPlain.phoneNumber?.trim();
+    if (!email || !phone) {
+        return recordAndSkip({
+            storeSlug,
+            gateway,
+            status: SettlementVendorStatusValues.BLOCKED,
+            reason: `the seller's account needs ${!email ? "an email address" : ""}` +
+                `${!email && !phone ? " and " : ""}${!phone ? "a phone number" : ""} ` +
+                `before a payment provider can register them`,
+            priorAttempts,
+            ctx,
+        });
+    }
+    /*
+     * 🛑 EXACTLY ONE destination, chosen by the seller's own `method`. Sending
+     * both would let the aggregator pick where real money lands.
+     *
+     * 🛑 Read into locals and NARROWED rather than cast. `payoutDestinationIssues`
+     * above has already proved the chosen destination is complete, so a cast
+     * would "work" — and `details.upiId as string` is specifically the
+     * brand-defeating shape `audit-pii-read-sites` R3 exists to refuse, because a
+     * cast on a PII field is the one way to reopen the hole the nominal brand
+     * closed. A guard costs one branch and asserts nothing.
+     */
+    const accountHolderName = store.legalName?.trim() || store.storeName;
+    const upiVpa = details?.method === "upi" ? details.upiId?.trim() : undefined;
+    const bank = details?.method === "bank_transfer" ? details.bankAccount : undefined;
+    const destination = upiVpa
+        ? { upi: { vpa: upiVpa, accountHolderName } }
+        : bank?.accountNumber && bank.ifscCode && bank.accountHolderName
+            ? {
+                bank: {
+                    accountNumber: bank.accountNumber,
+                    ifsc: bank.ifscCode.toUpperCase(),
+                    accountHolderName: bank.accountHolderName,
+                },
+            }
+            : null;
+    if (!destination) {
+        /*
+         * Unreachable given the issue check above, and it is here anyway because
+         * the alternative is a cast. An unreachable branch that records a reason is
+         * cheaper than a cast that would silently hand the aggregator `undefined`
+         * if the two checks ever disagree.
+         */
+        return recordAndSkip({
+            storeSlug,
+            gateway,
+            status: SettlementVendorStatusValues.BLOCKED,
+            reason: "the seller's payout destination could not be resolved",
+            priorAttempts,
+            ctx,
+        });
+    }
+    const vendorInput = {
+        vendorId: storeSlug,
+        name: accountHolderName,
+        email,
+        phone,
+        ...(pan ? { pan } : {}),
+        ...(store.gstin?.trim() ? { gstin: store.gstin.trim() } : {}),
+        ...destination,
+    };
+    let result = null;
+    let callFailure = null;
+    try {
+        result = await provider.registerSettlementVendor(vendorInput);
+    }
+    catch (err) {
+        /*
+         * The adapter converts a gateway refusal into `outcome: "rejected"`, so a
+         * THROW here is our own problem — a missing implementation, a credential
+         * fault, an outage. Reported as `failed` (not `skipped`) so the job retries
+         * and an operator sees it, and nothing is written to the store: a transient
+         * outage must not leave a `rejected` record that reads as a seller problem.
+         */
+        callFailure = normalizeError(err).message;
+        ctx.logger.error("settlementVendorRegister: registration call failed", err, {
+            storeSlug,
+            gateway,
+        });
+    }
+    if (!result) {
+        return {
+            summary: { total: 1, succeeded: 0, skipped: 0, failed: 1 },
+            succeeded: [],
+            skipped: [],
+            failed: [
+                {
+                    id: storeSlug,
+                    reason: callFailure ?? "the registration call returned nothing",
+                },
+            ],
+        };
+    }
+    const status = STATUS_BY_OUTCOME[result.outcome];
+    const record = {
+        vendorId: result.vendorId || storeSlug,
+        status,
+        ...(result.message ? { message: result.message } : {}),
+        ...(status === SettlementVendorStatusValues.ACTIVE ? { registeredAt: ctx.now } : {}),
+        lastAttemptAt: ctx.now,
+        attempts: priorAttempts + 1,
+    };
+    await storeRepository.setSettlementVendor(storeSlug, gateway, record);
+    /*
+     * ── Blocker #3: the destination stops being self-asserted ────────────────
+     *
+     * 🛑 The WHOLE `payoutDetails` map is written back, because Firestore
+     * replaces a map field entirely — a partial write would destroy the account
+     * number and the IFSC it does not mention. `ownerPlain.payoutDetails` is the
+     * revealed plaintext and the repository's write hook re-encrypts it
+     * (`encryptPayoutDetails`), so this round-trips rather than storing
+     * ciphertext-of-ciphertext.
+     *
+     * 🛑 Best-effort. The vendor record above is the authoritative outcome; a
+     * failed mirror write must not make the whole job retry and re-register. It
+     * is reported rather than swallowed so a drift has a trace (Root Cause #59).
+     */
+    if (details) {
+        try {
+            // payoutDetails is seller-only data — sellerProfiles, not users.
+            await sellerProfileRepository.upsertForOwner(store.ownerId, {
+                payoutDetails: {
+                    ...details,
+                    verificationStatus: VERIFICATION_BY_OUTCOME[result.outcome],
+                    ...(result.message ? { verificationMessage: result.message } : {}),
+                    ...(result.outcome === "active" ? { verifiedAt: ctx.now } : {}),
+                },
+            });
+        }
+        catch (err) {
+            const normalized = normalizeError(err);
+            ctx.logger.warn("settlementVendorRegister: vendor recorded, but the seller's payout verification status could not be updated", { storeSlug, ownerId: store.ownerId, error: normalized.message });
+        }
+    }
+    const registered = status === SettlementVendorStatusValues.ACTIVE;
+    ctx.logger.info("settlementVendorRegister: complete", {
+        storeSlug,
+        gateway,
+        status,
+        /*
+         * 🛑 The gateway's message is logged; the PAN, the account number and the
+         * VPA are not, and must never be. `audit-pii-crypto`'s CIPHERTEXT_IN_MESSAGE
+         * is about the inverse case and this is the plaintext one — worse.
+         */
+        ...(result.message ? { message: result.message } : {}),
+    });
+    return {
+        summary: {
+            total: 1,
+            succeeded: registered ? 1 : 0,
+            skipped: registered ? 0 : 1,
+            failed: 0,
+        },
+        succeeded: registered ? [storeSlug] : [],
+        skipped: registered ? [] : [storeSlug],
+        failed: [],
+        data: {
+            storeSlug,
+            gateway,
+            vendorId: record.vendorId,
+            status,
+            ...(result.message ? { message: result.message } : {}),
+        },
+    };
+}

package/dist/_internal/server/jobs/core/stickerTraceSweep.d.ts

@@ -0,0 +1,9 @@
+import type { JobContext } from "../runtime/types";
+/**
+ * Fail any sticker-trace run stuck in `queued`/`running` past 20 minutes.
+ *
+ * 🛑 The only mechanism that notices a run a crashed function left with no
+ * terminal write — see `features/sticker-trace/sweep.ts`'s header for why
+ * that gap exists even with every Cloud Function healthy and deployed.
+ */
+export declare function runStickerTraceSweep(ctx: JobContext): Promise<void>;

package/dist/_internal/server/jobs/core/stickerTraceSweep.js

@@ -0,0 +1,25 @@
+import { sweepStuckStickerTraceRuns } from "../../features/sticker-trace/sweep.js";
+import { normalizeError } from "../../../../errors/normalize.js";
+/**
+ * Fail any sticker-trace run stuck in `queued`/`running` past 20 minutes.
+ *
+ * 🛑 The only mechanism that notices a run a crashed function left with no
+ * terminal write — see `features/sticker-trace/sweep.ts`'s header for why
+ * that gap exists even with every Cloud Function healthy and deployed.
+ */
+export async function runStickerTraceSweep(ctx) {
+    ctx.logger.info("Starting sticker-trace stuck-run sweep");
+    let result;
+    try {
+        result = await sweepStuckStickerTraceRuns(ctx.now);
+    }
+    catch (err) {
+        const normalized = normalizeError(err);
+        ctx.logger.error("Sticker-trace stuck-run sweep failed", { message: normalized.message });
+        throw err;
+    }
+    ctx.logger.info("Sticker-trace stuck-run sweep complete", {
+        scanned: result.scanned,
+        timedOut: result.timedOut,
+    });
+}

package/dist/_internal/server/jobs/core/surfaceCountsRollup.js

@@ -111,14 +111,54 @@ export async function computeSurfaceCounts(ctx, only) {
 export async function runSurfaceCountsRollup(ctx, only) {
     const result = await computeSurfaceCounts(ctx, only);
     const payload = { updatedAt: new Date() };
-    // Dot-path merge for a narrowed run: `{ listingTypes: {...} }` with
-    // `merge: true` would still replace the whole map on some drivers, and we
-    // must not drop a key this run did not probe.
-    for (const [k, v] of Object.entries(result.listingTypes)) {
-        payload[`listingTypes.${k}`] = v;
+    /*
+     * 🛑 NESTED MAPS, NOT DOT-PATHED KEYS — and the previous spelling here was a
+     * silently-failed safety gate, which is the worst failure shape there is.
+     *
+     * This wrote `payload["listingTypes." + k] = v` and then called
+     * `.set(payload, { merge: true })`. **Firestore resolves `"a.b"` as a nested
+     * field path only in `update()`. In `set()` it is a literal field name that
+     * happens to contain a dot.** So `surfaceCounts/global` held top-level fields
+     * NAMED `listingTypes.standard`, `surfaces.reviews`, … and no `listingTypes`
+     * map at all. `getSurfaceCounts` reads `data.listingTypes` → `undefined` →
+     * `sanitize(undefined)` → `undefined` → both maps absent → the function
+     * returns `undefined` and every reader takes the fail-open path. The module's
+     * own warning names the consequence: "surfaces will all render visible".
+     *
+     * The gate had therefore never fired, on any surface, ever. Corroborated
+     * live: `GET /api/site-settings` returned `hiddenSurfacePaths:
+     * ["/classified","/live"]` — exactly the two listing types flagged `false`,
+     * i.e. hidden by FLAG. Not one path was contributed by a measured count.
+     *
+     * The comment that justified the dot-paths had it exactly backwards: it
+     * feared `{ listingTypes: {...} }` with `merge: true` would "replace the
+     * whole map on some drivers". Verified against the SHIPPED driver
+     * (`@google-cloud/firestore/build/src/document.js`, `DocumentMask.fromObject`):
+     * it recurses into plain objects and pushes only LEAF paths, so
+     * `{ listingTypes: { standard: 5 } }` produces the update mask
+     * `["listingTypes.standard"]`. A narrowed run cannot touch a sibling key.
+     * That is the merge behaviour this job needs, and it is what the hazard
+     * story claimed was unavailable.
+     *
+     * ⚠ ONE REAL HAZARD IN THE SAME FUNCTION, which is why the guards below are
+     * not defensive clutter. `extractFieldPaths` ends with *"Add a field path for
+     * an explicitly updated empty map"* — `if (currentPath && isEmpty)
+     * fieldPaths.push(currentPath)`. So writing `{ listingTypes: {} }` masks
+     * `listingTypes` ITSELF and **wipes the whole map**. An all-probes-failed run
+     * (`listingTypes` empty, every type in `failed`) would therefore erase every
+     * figure the last good run recorded — turning a transient query failure into
+     * "nothing is measured". Omit an empty map and the run writes only
+     * `updatedAt`, which is the correct no-op.
+     *
+     * The contrast case lives in this repo and is correct as written:
+     * `scripts/seed-demo-inventory.mjs:485` dot-paths an `.update()`. Dotted keys
+     * are not the defect — dotted keys in `set()` are.
+     */
+    if (Object.keys(result.listingTypes).length > 0) {
+        payload.listingTypes = result.listingTypes;
     }
-    for (const [k, v] of Object.entries(result.surfaces)) {
-        payload[`surfaces.${k}`] = v;
+    if (Object.keys(result.surfaces).length > 0) {
+        payload.surfaces = result.surfaces;
     }
     await ctx.db
         .collection(SURFACE_COUNTS_COLLECTION)

package/dist/_internal/server/jobs/core/testDataCleanup.js

@@ -80,7 +80,7 @@ export async function runTestDataCleanup(ctx, opts = {}) {
     }
     // Cascade into bids referencing deleted test products — bids hold only a live
     // productId FK with no denormalized snapshot, so leaving them behind after the
-    // product is gone would create meaningless orphaned auction history.
+    // product is gone would create meaningless orphaned collector drop history.
     for (let i = 0; i < deletedProductIds.length; i += BID_CHUNK_SIZE) {
         const chunk = deletedProductIds.slice(i, i + BID_CHUNK_SIZE);
         if (chunk.length === 0)

package/dist/_internal/server/jobs/core/triggerEventRaffle.d.ts

@@ -23,7 +23,7 @@
  *    winner write sat outside any transaction, so two concurrent admin clicks
  *    both saw no winner and both wrote — two winners for one prize. The
  *    check-and-write is now inside `runTransaction`, following the sibling
- *    core `prizeDrawAssignWinner`.
+ *    core `clearanceAssignWinner`.
  *
  * 3. **The winner was never told.** A winner was recorded and the only way to
  *    find out was to revisit the event page.
@@ -32,7 +32,7 @@
  * 2026-10-19 — see the header of `assignSpinPrize.ts`. Its branch here was the
  * second-worst shaped of the nine: it returned early with **no `reason`**, and
  * the route decides success by `if (data.reason && !data.raffleWinnerUserId)`,
- * so a disabled feature answered `200 "Raffle triggered"` with no winner.
+ * so a disabled feature answered `200 "Giveaway triggered"` with no winner.
  */
 import type { JobContext } from "../runtime/types";
 export interface TriggerEventRaffleInput {

package/dist/_internal/server/jobs/core/triggerEventRaffle.js

@@ -23,7 +23,7 @@
  *    winner write sat outside any transaction, so two concurrent admin clicks
  *    both saw no winner and both wrote — two winners for one prize. The
  *    check-and-write is now inside `runTransaction`, following the sibling
- *    core `prizeDrawAssignWinner`.
+ *    core `clearanceAssignWinner`.
  *
  * 3. **The winner was never told.** A winner was recorded and the only way to
  *    find out was to revisit the event page.
@@ -32,12 +32,13 @@
  * 2026-10-19 — see the header of `assignSpinPrize.ts`. Its branch here was the
  * second-worst shaped of the nine: it returned early with **no `reason`**, and
  * the route decides success by `if (data.reason && !data.raffleWinnerUserId)`,
- * so a disabled feature answered `200 "Raffle triggered"` with no winner.
+ * so a disabled feature answered `200 "Giveaway triggered"` with no winner.
  */
 import crypto from "node:crypto";
 import { normalizeError } from "../../../../errors/normalize.js";
 import { sendNotification } from "../../../../features/admin/actions/notification-actions.js";
 import { EVENT_ENTRY_FIELDS, EVENT_FIELDS } from "../../../../constants/field-names.js";
+import { normalizeEventType } from "../../../../features/events/types/index.js";
 import { EVENT_ENTRY_PII_FIELDS, maskPii } from "../../../../security/index.js";
 import { resolveEventRef } from "./_event-ref.js";
 import { EVENT_DRAW_REASON } from "./event-draw-reasons.js";
@@ -69,11 +70,15 @@ export async function runTriggerEventRaffle(input, ctx) {
     /*
      * Nothing checked that this event HAS a raffle, so the runner would happily
      * draw a winner on a poll or a sale and write `raffleWinnerUserId` onto it.
-     * `hasRaffle` is the bolt-on flag; `type === "raffle"` is the dedicated
-     * event type. Either qualifies — a raffle-typed event with the flag unset is
-     * a seeding omission, not a reason to refuse a legitimate draw.
+     * `hasRaffle` is the bolt-on flag; `type === "giveaway"` is the dedicated
+     * event type. Either qualifies — a giveaway-typed event with the flag unset
+     * is a seeding omission, not a reason to refuse a legitimate draw.
+     *
+     * 🛑 `normalizeEventType`, not a bare `!==`: pre-2026-10-31 documents still
+     * hold `raffle`. `hasRaffle` stays — it is a persisted field, not a type.
      */
-    if (event.hasRaffle !== true && event.type !== EVENT_FIELDS.TYPE_VALUES.RAFFLE) {
+    if (event.hasRaffle !== true &&
+        normalizeEventType(event.type) !== EVENT_FIELDS.TYPE_VALUES.GIVEAWAY) {
         return { eventId, raffleEntryCount: 0, reason: EVENT_DRAW_REASON.NOT_A_RAFFLE };
     }
     /*
@@ -105,7 +110,7 @@ export async function runTriggerEventRaffle(input, ctx) {
      * raffle claims 1,892 entries) and a Firestore transaction holds locks for
      * everything it reads — so reading the pool inside would make a draw scale
      * its lock footprint with entrant count. The same split as
-     * `prizeDrawAssignWinner`: read the candidates normally, then do the
+     * `clearanceAssignWinner`: read the candidates normally, then do the
      * check-and-write transactionally.
      *
      * 🛑 `reviewStatus == "approved"`, NOT `status == "CONFIRMED"`. See this
@@ -190,7 +195,7 @@ export async function runTriggerEventRaffle(input, ctx) {
                  * winner the other prizes, and must not cost them the win at all.
                  * Warned rather than thrown for exactly that reason.
                  */
-                ctx.logger.warn("Raffle prize couponId does not resolve to a coupon", {
+                ctx.logger.warn("Giveaway prize couponId does not resolve to a coupon", {
                     eventId,
                     couponId: snap.id,
                 });
@@ -259,7 +264,7 @@ export async function runTriggerEventRaffle(input, ctx) {
             reason: EVENT_DRAW_REASON.ALREADY_TRIGGERED,
         };
     }
-    ctx.logger.info("Event raffle triggered", {
+    ctx.logger.info("Event giveaway triggered", {
         eventId,
         raffleType,
         poolSize: pool.length,
@@ -270,7 +275,7 @@ export async function runTriggerEventRaffle(input, ctx) {
      * fails must not roll back a recorded draw (the draw is irreversible and
      * re-running it would pick a different winner), and a send inside the
      * transaction would be retried on every abort. Same shape as
-     * `prizeDrawAssignWinner`.
+     * `clearanceAssignWinner`.
      */
     if (drawn.userId) {
         try {
@@ -278,7 +283,7 @@ export async function runTriggerEventRaffle(input, ctx) {
                 userId: drawn.userId,
                 type: "prize_won",
                 priority: "high",
-                title: "You won the raffle!",
+                title: "You won the giveaway!",
                 message: rafflePrizeCouponCode
                     ? `You've been drawn as the winner. Your prize coupon code is ${rafflePrizeCouponCode}.`
                     : "You've been drawn as the winner — open the event to see your prize.",
@@ -288,7 +293,7 @@ export async function runTriggerEventRaffle(input, ctx) {
         }
         catch (err) {
             void normalizeError(err);
-            ctx.logger.warn("Raffle winner notification failed", {
+            ctx.logger.warn("Giveaway winner notification failed", {
                 eventId,
                 err: err instanceof Error ? err.message : String(err),
             });