@mohasinac/appkit 4.52.4 → 4.53.0

package/dist/_internal/server/features/sticker-trace/storage.js

@@ -0,0 +1,282 @@
+/*
+ * WHY: Scans and artifacts are private bytes that must never be watermarked,
+ *      never be publicly addressable, and never traverse Vercel.
+ * WHAT: Paths, the signed upload/read pair, magic-byte finalize, and tree
+ *       deletion.
+ *
+ * 🛑 THREE RULES, each closing a failure this project has already paid for.
+ *
+ * 1. NOT through /api/media/[...slug]. That route applies NO authentication —
+ *    deliberately, because its job is public product photography — and it
+ *    ALWAYS watermarks (`resolveWatermarkConfig` has no skip path), which would
+ *    ruin a cut-out and make the printed mosaic unusable. See § "Digital
+ *    Content Delivery" for the same decision made for purchased assets.
+ *
+ * 2. NO `mediaAssets` row. That row IS the public `/media/{shortId}` slug — the
+ *    resolver looks up `mediaAssets/{slug}` to find `storagePath` — so no row
+ *    means no public URL exists at all. Object names are RANDOM, against the
+ *    SEO-slug convention used everywhere else, because media filenames here are
+ *    content-derived and therefore guessable, and guessable is the one property
+ *    a private asset must not have.
+ *
+ * 3. VERCEL RETURNS JSON, NEVER BYTES. Every binary is fetched by the browser
+ *    straight from GCS with a 5-minute signed URL; the route returns
+ *    `{ url, expiresAt }`. Vercel's Fast Origin Transfer allowance is 10 GB and
+ *    exceeding it PAUSED this project once already — 52.52 GB against that 10 GB
+ *    (Root Cause #104). Cloud Storage's own egress allowance is ten times
+ *    larger and is not a cliff.
+ *
+ *    Accepted residue, stated rather than hidden: a signed URL is a 5-minute
+ *    bearer token. Acceptable here because an admin's own scan is not a paid
+ *    good — which was the precise reason `digital-content` refused this and
+ *    streams through its route instead.
+ *
+ * EXPORTS: SCAN_ROOT, runPrefix, signScanUpload, finalizeScanUpload,
+ *   signedReadUrl, writeRunArtifact, deleteRunTree, deleteSheetTree,
+ *   measureSheetBytes
+ *
+ * @tag domain:sticker-trace
+ * @tag layer:server
+ * @tag pattern:none
+ * @tag access:server
+ * @tag consumers:api/admin/sticker-sheets,functions/sticker-trace
+ * @tag sideEffects:storage
+ */
+import { normalizeError } from "../../../../errors/normalize.js";
+import { serverLogger } from "../../../../monitoring/index.js";
+import { getAdminStorage } from "../../../../providers/db-firebase/index.js";
+/** Nothing under here is reachable without a signed URL minted by this module. */
+export const SCAN_ROOT = "private/sticker-sheets";
+/** How long a read URL lives. Long enough to fetch, short enough to be useless if leaked. */
+const READ_TTL_MS = 5 * 60 * 1000;
+/** An upload may take a while on a 79 MB PNG over a domestic uplink. */
+const UPLOAD_TTL_MS = 15 * 60 * 1000;
+/** Magic-byte families a scan may legitimately be. */
+const ALLOWED_SCAN_MIMES = new Set([
+    "image/jpeg",
+    "image/png",
+    "image/webp",
+    "image/tiff",
+    "image/bmp",
+]);
+export function runPrefix(sheetId, runId) {
+    return `${SCAN_ROOT}/${sheetId}/${runId}`;
+}
+/**
+ * A random object name, with the caller's extension preserved for tooling only.
+ *
+ * `crypto.randomUUID` rather than a slug: see rule 2 in the header. The
+ * original name is NOT used — a human-supplied filename is both guessable and
+ * a path-traversal surface.
+ */
+function randomObjectName(extension) {
+    const ext = /^[a-z0-9]{1,5}$/i.test(extension) ? extension.toLowerCase() : "bin";
+    return `${globalThis.crypto.randomUUID()}.${ext}`;
+}
+/**
+ * Mint a one-object write URL for a scan.
+ *
+ * 🛑 `contentType` is BOUND INTO THE SIGNATURE. A client that PUTs different
+ * bytes than it declared gets a 403 from GCS rather than a stored lie — which
+ * is the cheap half of the guarantee. The expensive half is `finalizeScanUpload`
+ * below, because a matching header still proves nothing about the content.
+ */
+export async function signScanUpload(input) {
+    const assetPath = `${runPrefix(input.sheetId, input.runId)}/${randomObjectName(input.extension)}`;
+    const expiresAt = new Date(Date.now() + UPLOAD_TTL_MS);
+    const [uploadUrl] = await getAdminStorage()
+        .bucket()
+        .file(assetPath)
+        .getSignedUrl({
+        version: "v4",
+        action: "write",
+        expires: expiresAt,
+        contentType: input.contentType,
+    });
+    return { uploadUrl, assetPath, expiresAt };
+}
+/**
+ * Prove the uploaded object is the image it claims to be.
+ *
+ * 🛑 The DECLARED type is not evidence, and a mismatch DELETES the object.
+ * Leaving it would mean an arbitrary file sitting in our bucket at a path our
+ * own code will later hand a signed URL for. The same magic-byte discipline as
+ * `/api/media/finalize`, which emits a structured 422 for exactly this.
+ *
+ * Reads only the first 4 KB — magic bytes live in the first few, and
+ * downloading a 79 MB scan into a Vercel function to inspect its header would
+ * be the egress mistake this module exists to prevent.
+ */
+export async function finalizeScanUpload(assetPath, maxBytes) {
+    const file = getAdminStorage().bucket().file(assetPath);
+    let bytes = 0;
+    try {
+        const [meta] = await file.getMetadata();
+        bytes = Number(meta.size ?? 0);
+    }
+    catch (err) {
+        const n = normalizeError(err);
+        serverLogger.warn("Sticker scan finalize: object missing", { assetPath, message: n.message });
+        return { ok: false, code: "MISSING", message: "The upload did not complete." };
+    }
+    if (bytes > maxBytes) {
+        await deleteObject(assetPath);
+        return {
+            ok: false,
+            code: "TOO_LARGE",
+            message: `That scan is ${(bytes / 1048576).toFixed(1)} MB; the limit is ${(maxBytes / 1048576).toFixed(0)} MB.`,
+        };
+    }
+    try {
+        const [head] = await file.download({ start: 0, end: 4095 });
+        const { fileTypeFromBuffer } = await import("file-type");
+        const detected = await fileTypeFromBuffer(head);
+        if (!detected || !ALLOWED_SCAN_MIMES.has(detected.mime)) {
+            await deleteObject(assetPath);
+            return {
+                ok: false,
+                code: "MIME_MISMATCH",
+                message: "That file is not a readable image. Upload a JPEG, PNG, WebP, TIFF or BMP scan.",
+            };
+        }
+        return { ok: true, contentType: detected.mime, bytes };
+    }
+    catch (err) {
+        const n = normalizeError(err);
+        serverLogger.error("Sticker scan finalize: magic-byte read failed", {
+            assetPath,
+            message: n.message,
+        });
+        // 🛑 Fails CLOSED and deletes. An object we could not verify must not stay
+        // at a path this module will later sign a URL for.
+        await deleteObject(assetPath);
+        return { ok: false, code: "MIME_MISMATCH", message: "The upload could not be verified." };
+    }
+}
+/**
+ * A short-lived read URL for one private object.
+ *
+ * 🛑 The CALLER is responsible for having authorised the request. This function
+ * mints capability and checks nothing — it cannot, because it does not see the
+ * session. Every call site must sit behind `createRouteHandler`'s admin gate.
+ *
+ * SVG is forced to `attachment`: it is deliberately excluded from
+ * `ALLOWED_IMAGE_MIMES` as an XSS surface, and a signed GCS URL is still our
+ * origin's data. The canvas draws cut lines from `geometry.json`, never by
+ * rendering the SVG.
+ */
+export async function signedReadUrl(assetPath, opts) {
+    const expiresAt = new Date(Date.now() + READ_TTL_MS);
+    const forceDownload = opts?.downloadAs || /\.svg$/i.test(assetPath);
+    const [url] = await getAdminStorage()
+        .bucket()
+        .file(assetPath)
+        .getSignedUrl({
+        version: "v4",
+        action: "read",
+        expires: expiresAt,
+        ...(forceDownload
+            ? {
+                responseDisposition: `attachment; filename="${(opts?.downloadAs ?? "cut.svg").replace(/"/g, "")}"`,
+            }
+            : {}),
+    });
+    return { url, expiresAt };
+}
+/** Save an artifact the tracer produced. Server-side only — never a client upload. */
+export async function writeRunArtifact(input) {
+    const assetPath = `${runPrefix(input.sheetId, input.runId)}/${input.name}`;
+    const buffer = Buffer.isBuffer(input.body) ? input.body : Buffer.from(input.body);
+    await getAdminStorage()
+        .bucket()
+        .file(assetPath)
+        .save(buffer, { contentType: input.contentType, resumable: false });
+    return { assetPath, bytes: buffer.byteLength };
+}
+async function deleteObject(assetPath) {
+    try {
+        await getAdminStorage().bucket().file(assetPath).delete({ ignoreNotFound: true });
+    }
+    catch (err) {
+        const n = normalizeError(err);
+        serverLogger.warn("Sticker trace object delete failed", { assetPath, message: n.message });
+    }
+}
+/**
+ * Delete everything one run wrote.
+ *
+ * `deleteFiles` pages internally, so this is safe on a `max`-tier run that
+ * produced sixty parts plus exports — unlike a hand-batched delete, which is
+ * the shape that died with `Transaction too big` on `categories`.
+ */
+export async function deleteRunTree(sheetId, runId) {
+    await deletePrefix(`${runPrefix(sheetId, runId)}/`);
+}
+/** Delete a whole sheet: the scan, and every run under it. */
+export async function deleteSheetTree(sheetId) {
+    await deletePrefix(`${SCAN_ROOT}/${sheetId}/`);
+}
+async function deletePrefix(prefix) {
+    /*
+     * 🛑 The trailing slash is load-bearing. `prefix: "…/sheet-1"` also matches
+     * `…/sheet-10`, so deleting one sheet would delete its numeric neighbours —
+     * silently, and reported as success.
+     */
+    if (!prefix.startsWith(`${SCAN_ROOT}/`) || !prefix.endsWith("/")) {
+        throw new Error(`Refusing to delete outside ${SCAN_ROOT}: ${prefix}`);
+    }
+    await getAdminStorage().bucket().deleteFiles({ prefix, force: true });
+}
+/**
+ * Total stored bytes and object count under one sheet, for the usage meter.
+ *
+ * 🛑 A quota only discoverable in the GCP console is a quota nobody watches —
+ * the same failure as Root Cause #104, where the first signal was a billing
+ * page. This is what makes "keep every run" a safe default rather than a
+ * deferred surprise.
+ */
+export async function measureSheetBytes(sheetId) {
+    const [files] = await getAdminStorage()
+        .bucket()
+        .getFiles({ prefix: `${SCAN_ROOT}/${sheetId}/` });
+    let bytes = 0;
+    for (const f of files)
+        bytes += Number(f.metadata?.size ?? 0);
+    return { bytes, objects: files.length };
+}
+/**
+ * Download a stored object's bytes.
+ *
+ * 🛑 Takes a RAW assetPath, which is only ever a value this module produced —
+ * `sourceScan.assetPath` or a `runPrefix`-derived artifact path. It must never
+ * be fed a client-supplied string: the bucket's storage rule is
+ * `allow read: if true`, so path containment is enforced here or nowhere.
+ */
+export async function readScanBytes(assetPath) {
+    if (!assetPath.startsWith(`${SCAN_ROOT}/`)) {
+        // Loud, not a silent empty read: an out-of-tree path means a caller
+        // assembled it rather than reading it off a document, and returning
+        // nothing would look like an empty scan.
+        throw new Error(`Refusing to read outside ${SCAN_ROOT}: ${assetPath}`);
+    }
+    const [buf] = await getAdminStorage().bucket().file(assetPath).download();
+    return new Uint8Array(buf);
+}
+/**
+ * Read and parse a run's `geometry.json`.
+ *
+ * 🛑 Parsed HERE rather than in the shard, so the one place that knows the
+ * artifact's name also owns its shape. A shard assembling the path itself
+ * would be a second definition of the layout — and the `parts` array is what
+ * every shard slices, so a disagreement renders the wrong crops rather than
+ * failing.
+ */
+export async function readRunGeometry(runId, sheetId) {
+    const assetPath = `${runPrefix(sheetId, runId)}/geometry.json`;
+    const [buf] = await getAdminStorage().bucket().file(assetPath).download();
+    const parsed = JSON.parse(buf.toString("utf8"));
+    if (!parsed || !Array.isArray(parsed.parts) || !parsed.workingSize) {
+        throw new Error(`geometry.json is malformed for run ${runId}`);
+    }
+    return parsed;
+}

package/dist/_internal/server/functions/scheduled.d.ts

@@ -7,6 +7,7 @@ export declare const couponExpiry: import("./types").ScheduledFunctionDefinition
 export declare const offerExpiry: import("./types").ScheduledFunctionDefinition;
 export declare const productStatsSync: import("./types").ScheduledFunctionDefinition;
 export declare const revenueRollup: import("./types").ScheduledFunctionDefinition;
+export declare const searchIndexBuild: import("./types").ScheduledFunctionDefinition;
 export declare const priceIndexRollup: import("./types").ScheduledFunctionDefinition;
 export declare const analyticsAlertEvaluate: import("./types").ScheduledFunctionDefinition;
 export declare const pageViewRollup: import("./types").ScheduledFunctionDefinition;
@@ -27,4 +28,4 @@ export declare const prizeDrawExpiryReveal: import("./types").ScheduledFunctionD
 export declare const bundleStockSync: import("./types").ScheduledFunctionDefinition;
 export declare const emiInstallmentReminder: import("./types").ScheduledFunctionDefinition;
 export declare const catalogueImageStalenessReminder: import("./types").ScheduledFunctionDefinition;
-export declare const SCHEDULED_FUNCTIONS: readonly [import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition];
+export declare const SCHEDULED_FUNCTIONS: readonly [import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition, import("./types").ScheduledFunctionDefinition];

package/dist/_internal/server/functions/scheduled.js

@@ -1,6 +1,6 @@
 // Scheduled function definitions (Cloud Scheduler triggers).
 // Cron syntax accepts both Firebase shorthand and standard cron expressions.
-import { auctionSettlementHandler, autoPayoutEligibilityHandler, bundleStockSyncHandler, cartPruneHandler, cleanupRtdbEventsHandler, countersReconcileHandler, couponExpiryHandler, dailyDataCleanupHandler, draftPruneHandler, emiInstallmentReminderHandler, catalogueImageStalenessReminderHandler, mediaTmpCleanupHandler, notificationPruneHandler, offerExpiryHandler, paymentWindowTimeoutHandler, hardBanReinstatementHandler, paymentReviewAutoApproveHandler, pendingOrderTimeoutHandler, positionsReconcileHandler, prizeDrawExpiryRevealHandler, productStatsSyncHandler, revenueRollupHandler, priceIndexRollupHandler, analyticsAlertEvaluateHandler, pageViewRollupHandler, pageViewPruneHandler, dailyStatusDigestHandler, weeklyPayoutEligibilityHandler, testDataCleanupHandler, } from "../jobs/handlers/index.js";
+import { auctionSettlementHandler, autoPayoutEligibilityHandler, bundleStockSyncHandler, cartPruneHandler, cleanupRtdbEventsHandler, countersReconcileHandler, couponExpiryHandler, dailyDataCleanupHandler, draftPruneHandler, emiInstallmentReminderHandler, catalogueImageStalenessReminderHandler, mediaTmpCleanupHandler, notificationPruneHandler, offerExpiryHandler, paymentWindowTimeoutHandler, hardBanReinstatementHandler, paymentReviewAutoApproveHandler, pendingOrderTimeoutHandler, positionsReconcileHandler, prizeDrawExpiryRevealHandler, productStatsSyncHandler, revenueRollupHandler, priceIndexRollupHandler, searchIndexBuildHandler, analyticsAlertEvaluateHandler, pageViewRollupHandler, pageViewPruneHandler, dailyStatusDigestHandler, weeklyPayoutEligibilityHandler, testDataCleanupHandler, } from "../jobs/handlers/index.js";
 import { defineFunction } from "./define.js";
 const REGION = "asia-south1";
 const EVERY_5_MIN = "every 5 minutes";
@@ -83,6 +83,29 @@ export const revenueRollup = defineFunction({
  * additionally drop each category page's ISR entry nightly on a project that
  * was paused for exceeding ISR writes by 15.5×.
  */
+/*
+ * Build the public search index artifact — every 15 minutes, but it EXITS on
+ * one read unless something changed.
+ *
+ * 🛑 The cadence is not the cost. Firestore bills per document read
+ * regardless of `select()`, so a full rebuild at this cadence would be
+ * ~358,000 reads/day against a 50,000/day tier. The job is idle-exit /
+ * incremental / daily-full instead, landing at ~4,000/day. See the core's
+ * header; it logs its mode and read count on every run so a regression to
+ * always-full is visible before it is a quota wall.
+ *
+ * Its own job rather than folded into an existing cadence: `countersReconcile`
+ * and `productStatsSync` already run near their 540s ceiling, and a rebuild
+ * failing inside one would take category metrics down with it — the argument
+ * `priceIndexRollup` makes directly below.
+ */
+export const searchIndexBuild = defineFunction({
+    name: "searchIndexBuild",
+    description: "Build the public search index artifact into Storage (idle-exit / incremental / daily full).",
+    trigger: { kind: "schedule", cron: "*/15 * * * *", timeZone: "UTC" },
+    handler: searchIndexBuildHandler,
+    options: { region: REGION, timeoutSeconds: 540, memory: "512MiB", maxInstances: 1 },
+});
 export const priceIndexRollup = defineFunction({
     name: "priceIndexRollup",
     description: "Roll up realised sale prices per leaf category into priceIndex/{leafId} (daily 04:30 UTC = 10:00 IST).",
@@ -277,6 +300,7 @@ export const SCHEDULED_FUNCTIONS = [
     productStatsSync,
     revenueRollup,
     priceIndexRollup,
+    searchIndexBuild,
     analyticsAlertEvaluate,
     pageViewRollup,
     pageViewPrune,

package/dist/_internal/server/jobs/core/_event-ref.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Resolve an event reference from a value that may be either a document id or
+ * a slug — the ONE implementation for the `ctx.db` (job-core) layer.
+ *
+ * ## Why this exists
+ *
+ * Public URLs link by SLUG: `EventCard` builds its href from
+ * `event.slug ?? event.id`, and `/events/[id]/participate` reuses that same
+ * route param. So every job core reached from a public surface receives a slug
+ * far more often than an id.
+ *
+ * `assignSpinPrize` and `triggerEventRaffle` both did a bare
+ * `.collection("events").doc(eventId).get()` with no slug fallback, so a spin
+ * launched from any card link returned `event_not_found` — 404 on every
+ * attempt, forever. `enterEvent` had always resolved it correctly
+ * (`eventRepository.findByIdOrSlug`, under a comment saying "eventId may have
+ * arrived as a slug (public URLs link by slug)"); the two job cores were the
+ * copies that never learned the rule.
+ *
+ * ## Why not `eventRepository.findByIdOrSlug`
+ *
+ * That is the right call at the repository layer and `enterEvent` keeps using
+ * it. A job core holds a raw `Firestore` from `JobContext` and no repository —
+ * and no repository in this codebase imports another feature's, because of the
+ * Turbopack import-chain trap (Root Cause #6/#18). A raw collection read has
+ * neither problem. This function also returns the `DocumentReference`, which a
+ * repository method cannot, and the cores need it to write.
+ *
+ * ## Slug first, deliberately
+ *
+ * Mirrors `findByIdOrSlug`'s own order. The common caller is a public URL, so
+ * the slug query hits on the first try; an id lookup then costs one extra
+ * query only on the admin path, where it is already behind a role gate.
+ */
+import type { DocumentReference, Firestore } from "firebase-admin/firestore";
+export interface ResolvedEventRef<T = unknown> {
+    /** The canonical DOCUMENT ID — never the slug, whichever was passed in. */
+    id: string;
+    ref: DocumentReference;
+    data: T;
+}
+/**
+ * @returns the resolved event, or `null` when neither a slug nor an id matches.
+ *
+ * 🛑 Callers must use the returned `id` for every subsequent query and write.
+ * Carrying the caller's original `idOrSlug` forward is how a guest identity
+ * ends up hashed on the slug on one path and on the doc id on another — two
+ * identities for one person on one event, which silently resets any per-user
+ * cap (see `hashGuestIdentity` at the spin route).
+ */
+export declare function resolveEventRef<T = unknown>(db: Firestore, idOrSlug: string): Promise<ResolvedEventRef<T> | null>;

package/dist/_internal/server/jobs/core/_event-ref.js

@@ -0,0 +1,63 @@
+/**
+ * Resolve an event reference from a value that may be either a document id or
+ * a slug — the ONE implementation for the `ctx.db` (job-core) layer.
+ *
+ * ## Why this exists
+ *
+ * Public URLs link by SLUG: `EventCard` builds its href from
+ * `event.slug ?? event.id`, and `/events/[id]/participate` reuses that same
+ * route param. So every job core reached from a public surface receives a slug
+ * far more often than an id.
+ *
+ * `assignSpinPrize` and `triggerEventRaffle` both did a bare
+ * `.collection("events").doc(eventId).get()` with no slug fallback, so a spin
+ * launched from any card link returned `event_not_found` — 404 on every
+ * attempt, forever. `enterEvent` had always resolved it correctly
+ * (`eventRepository.findByIdOrSlug`, under a comment saying "eventId may have
+ * arrived as a slug (public URLs link by slug)"); the two job cores were the
+ * copies that never learned the rule.
+ *
+ * ## Why not `eventRepository.findByIdOrSlug`
+ *
+ * That is the right call at the repository layer and `enterEvent` keeps using
+ * it. A job core holds a raw `Firestore` from `JobContext` and no repository —
+ * and no repository in this codebase imports another feature's, because of the
+ * Turbopack import-chain trap (Root Cause #6/#18). A raw collection read has
+ * neither problem. This function also returns the `DocumentReference`, which a
+ * repository method cannot, and the cores need it to write.
+ *
+ * ## Slug first, deliberately
+ *
+ * Mirrors `findByIdOrSlug`'s own order. The common caller is a public URL, so
+ * the slug query hits on the first try; an id lookup then costs one extra
+ * query only on the admin path, where it is already behind a role gate.
+ */
+import { EVENT_FIELDS } from "../../../../constants/field-names.js";
+const EVENTS_COLLECTION = "events";
+/**
+ * @returns the resolved event, or `null` when neither a slug nor an id matches.
+ *
+ * 🛑 Callers must use the returned `id` for every subsequent query and write.
+ * Carrying the caller's original `idOrSlug` forward is how a guest identity
+ * ends up hashed on the slug on one path and on the doc id on another — two
+ * identities for one person on one event, which silently resets any per-user
+ * cap (see `hashGuestIdentity` at the spin route).
+ */
+export async function resolveEventRef(db, idOrSlug) {
+    if (!idOrSlug)
+        return null;
+    const bySlug = await db
+        .collection(EVENTS_COLLECTION)
+        .where(EVENT_FIELDS.SLUG, "==", idOrSlug)
+        .limit(1)
+        .get();
+    if (!bySlug.empty) {
+        const doc = bySlug.docs[0];
+        return { id: doc.id, ref: doc.ref, data: doc.data() };
+    }
+    const byId = await db.collection(EVENTS_COLLECTION).doc(idOrSlug).get();
+    if (byId.exists) {
+        return { id: byId.id, ref: byId.ref, data: byId.data() };
+    }
+    return null;
+}

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

@@ -9,6 +9,23 @@
  * find/create/assign/mark-used sequence runs inside a single Firestore
  * transaction so two rapid spins from the same identity can't both win a
  * prize (the old read-then-`ref.update()` version had this race).
+ *
+ * ## Every non-success branch returns a `reason`, and that is load-bearing
+ *
+ * Both entry points — `POST /api/events/[id]/spin` and the Firebase callable —
+ * decide success by `if (data.reason && !data.spinPrizeId)`. A branch that
+ * returns early WITHOUT a reason is therefore reported to the caller as a
+ * successful spin that awarded nothing. Reasons come from
+ * `EVENT_DRAW_REASON`; `reasonToHttp` turns each into one status and one
+ * stable code for both entry points (Root Cause #85).
+ *
+ * The `FEATURE_PRIZE_DRAWS` gate that used to open this function was DELETED
+ * on 2026-10-19. The whole `FEATURE_*` mechanism had already been retired —
+ * `audit-feature-flags` bans it strict-zero and `.env.example` declares no
+ * such key — but that audit only matched `process.env.FEATURE_*`, and this
+ * read it as `ctx.env("FEATURE_PRIZE_DRAWS")`, which the regex could not see.
+ * So an env var nothing documented was never set in production and every spin
+ * returned 503 `feature_disabled` while the Spin button rendered enabled.
  */
 import type { JobContext } from "../runtime/types";
 export interface AssignSpinPrizeInput {
@@ -19,6 +36,7 @@ export interface AssignSpinPrizeInput {
     guestIpHash?: string;
 }
 export interface AssignSpinPrizeResult {
+    /** The canonical DOCUMENT ID, even when the caller passed a slug. */
     eventId: string;
     userId?: string;
     spinPrizeId?: string;

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

@@ -9,39 +9,88 @@
  * find/create/assign/mark-used sequence runs inside a single Firestore
  * transaction so two rapid spins from the same identity can't both win a
  * prize (the old read-then-`ref.update()` version had this race).
+ *
+ * ## Every non-success branch returns a `reason`, and that is load-bearing
+ *
+ * Both entry points — `POST /api/events/[id]/spin` and the Firebase callable —
+ * decide success by `if (data.reason && !data.spinPrizeId)`. A branch that
+ * returns early WITHOUT a reason is therefore reported to the caller as a
+ * successful spin that awarded nothing. Reasons come from
+ * `EVENT_DRAW_REASON`; `reasonToHttp` turns each into one status and one
+ * stable code for both entry points (Root Cause #85).
+ *
+ * The `FEATURE_PRIZE_DRAWS` gate that used to open this function was DELETED
+ * on 2026-10-19. The whole `FEATURE_*` mechanism had already been retired —
+ * `audit-feature-flags` bans it strict-zero and `.env.example` declares no
+ * such key — but that audit only matched `process.env.FEATURE_*`, and this
+ * read it as `ctx.env("FEATURE_PRIZE_DRAWS")`, which the regex could not see.
+ * So an env var nothing documented was never set in production and every spin
+ * returned 503 `feature_disabled` while the Spin button rendered enabled.
  */
 import crypto from "node:crypto";
-import { EVENT_ENTRY_FIELDS, COMMON_FIELDS } from "../../../../constants/field-names.js";
+import { EVENT_ENTRY_FIELDS, EVENT_FIELDS, COMMON_FIELDS, } from "../../../../constants/field-names.js";
 import { resolveDate } from "../../../../utils/index.js";
-const EVENTS_COLLECTION = "events";
+import { resolveEventRef } from "./_event-ref.js";
+import { EVENT_DRAW_REASON } from "./event-draw-reasons.js";
 const EVENT_ENTRIES_COLLECTION = "eventEntries";
 const COUPONS_COLLECTION = "coupons";
 export async function runAssignSpinPrize(input, ctx) {
-    if (ctx.env("FEATURE_PRIZE_DRAWS") !== "true") {
-        ctx.logger.info("FEATURE_PRIZE_DRAWS disabled — skipping spin prize assignment");
-        return { eventId: input.eventId, userId: input.userId, reason: "feature_disabled" };
-    }
-    const { eventId, userId, guestIpHash } = input;
+    const { userId, guestIpHash } = input;
     if (!userId && !guestIpHash) {
-        return { eventId, userId, reason: "identity_required" };
+        return {
+            eventId: input.eventId,
+            userId,
+            reason: EVENT_DRAW_REASON.IDENTITY_REQUIRED,
+        };
+    }
+    /*
+     * 🛑 Slug-or-id, not `.doc(eventId)`. Public URLs link by SLUG (`EventCard`
+     * builds its href from `event.slug ?? event.id`, and the participate tab
+     * reuses that param), so a spin launched from any card link used to resolve
+     * to nothing and return `event_not_found` — a 404 on every attempt, forever.
+     *
+     * Every query and write below uses the RESOLVED `eventId`, never the
+     * caller's input: carrying the slug forward is what let one guest count as
+     * two identities and silently reset `spinMaxPerUser`.
+     */
+    const resolved = await resolveEventRef(ctx.db, input.eventId);
+    if (!resolved) {
+        return {
+            eventId: input.eventId,
+            userId,
+            reason: EVENT_DRAW_REASON.EVENT_NOT_FOUND,
+        };
+    }
+    const eventId = resolved.id;
+    const event = resolved.data;
+    /*
+     * The page redirects a non-running event to the overview, so these were
+     * never reachable through the UI — but `POST /api/events/<ended>/spin`
+     * answered 200 and awarded a prize. A redirect is navigation, not a
+     * precondition.
+     */
+    if (event.type && event.type !== EVENT_FIELDS.TYPE_VALUES.SPIN_WHEEL) {
+        return { eventId, userId, reason: EVENT_DRAW_REASON.NOT_A_SPIN_WHEEL };
     }
-    const eventSnap = await ctx.db.collection(EVENTS_COLLECTION).doc(eventId).get();
-    if (!eventSnap.exists) {
-        return { eventId, userId, reason: "event_not_found" };
+    const endsAt = resolveDate(event.endsAt);
+    if (event.status !== EVENT_FIELDS.STATUS_VALUES.ACTIVE ||
+        (endsAt && ctx.now > endsAt)) {
+        return { eventId, userId, reason: EVENT_DRAW_REASON.NOT_ACTIVE };
     }
-    const event = eventSnap.data();
     if (!userId && !event.allowGuestParticipation) {
-        return { eventId, userId, reason: "login_required" };
+        return { eventId, userId, reason: EVENT_DRAW_REASON.LOGIN_REQUIRED };
     }
-    const prizes = Array.isArray(event.spinPrizes) ? event.spinPrizes : [];
+    // Active prizes only — see the `isActive` note on SpinPrize. The weighted
+    // pick below iterates this same array, so the gate and the draw agree.
+    const prizes = (Array.isArray(event.spinPrizes) ? event.spinPrizes : []).filter((p) => p.isActive !== false);
     const totalWeight = prizes.reduce((s, p) => s + (p.weight ?? 0), 0);
     if (totalWeight <= 0) {
-        return { eventId, userId, reason: "no_prizes_configured" };
+        return { eventId, userId, reason: EVENT_DRAW_REASON.NO_PRIZES_CONFIGURED };
     }
     const windowStart = resolveDate(event.spinWindowStart);
     const windowEnd = resolveDate(event.spinWindowEnd);
     if ((windowStart && ctx.now < windowStart) || (windowEnd && ctx.now > windowEnd)) {
-        return { eventId, userId, reason: "outside_spin_window" };
+        return { eventId, userId, reason: EVENT_DRAW_REASON.OUTSIDE_SPIN_WINDOW };
     }
     const maxPerUser = typeof event.spinMaxPerUser === "number" && event.spinMaxPerUser > 0
         ? event.spinMaxPerUser
@@ -59,11 +108,23 @@ export async function runAssignSpinPrize(input, ctx) {
         const existingData = existingDoc?.data();
         const priorSpinCount = existingData?.spinCount ?? (existingData?.spinUsed ? 1 : 0);
         if (priorSpinCount >= maxPerUser) {
+            /*
+             * 🛑 `reason` is REQUIRED here, and its absence was a bug.
+             *
+             * Both entry points gate on `if (data.reason && !data.spinPrizeId)`, so
+             * this branch used to fall through to `successResponse(…, "Spin
+             * recorded")` — HTTP 200 for a refusal. When the stored entry happened
+             * to carry no `spinPrizeId`, the client then saw a 200 with no prize and
+             * printed "Spin failed. Please try again." for what is really "you have
+             * already spun".
+             */
             return {
                 eventId,
                 userId,
                 spinPrizeId: existingData?.spinPrizeId,
+                spinPrizeCouponCode: existingData?.spinPrizeCouponCode ?? undefined,
                 alreadyUsed: true,
+                reason: EVENT_DRAW_REASON.ALREADY_USED,
             };
         }
         const roll = crypto.randomInt(0, totalWeight);

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

@@ -211,10 +211,19 @@ async function settleAuction(ctx, product) {
     });
 }
 export async function runAuctionSettlement(ctx) {
-    if (ctx.env("FEATURE_AUCTIONS") !== "true") {
-        ctx.logger.info("FEATURE_AUCTIONS disabled — skipping auction settlement");
-        return;
-    }
+    /*
+     * 🛑 `FEATURE_AUCTIONS` gate DELETED 2026-10-19, and this one was live.
+     *
+     * The flag mechanism was retired on 2026-08-29, but `audit-feature-flags`
+     * only matched `process.env.FEATURE_*` and this read it through
+     * `ctx.env(...)` — so it survived unseen. This is a SCHEDULED Firebase
+     * Function, which reads `functions/.env.<projectId>`, and measured on
+     * 2026-10-19 that file contains exactly one flag: `FEATURE_PAYOUTS=true`.
+     * `FEATURE_AUCTIONS` was never set there, so this sweep returned on its
+     * first line on every run — no expired auction was ever settled in
+     * production, no winner ever got a cart line, and the only trace was an
+     * `info` log saying it had been skipped.
+     */
     ctx.logger.info("Starting auction settlement sweep");
     const expired = await productRepository.getExpiredAuctions(ctx.now);
     if (expired.length === 0) {