@mohasinac/appkit 4.52.5 → 4.53.1

package/dist/_internal/server/features/raffle/actions.js

@@ -10,6 +10,7 @@ import { wrapAction } from "@mohasinac/appkit/server";
 import { getAdminDb } from "../../../../providers/db-firebase/admin.js";
 import { runTriggerEventRaffle, } from "../../jobs/core/triggerEventRaffle.js";
 import { runAssignSpinPrize, } from "../../jobs/core/assignSpinPrize.js";
+import { resolveEventRef } from "../../jobs/core/_event-ref.js";
 function buildContext(job) {
     const logger = {
         info: (msg, meta) => console.info(`[${job}] ${msg}`, meta ?? {}),
@@ -30,3 +31,27 @@ export async function triggerEventRaffleAction(input) {
 export async function assignSpinPrizeAction(input) {
     return wrapAction(async () => runAssignSpinPrize(input, buildContext("user.assignSpinPrize")));
 }
+/**
+ * Resolve a slug-or-id to the canonical event DOCUMENT ID.
+ *
+ * Exists for one caller — `POST /api/events/[id]/spin`, which must hash a
+ * guest's identity against a stable key BEFORE calling the spin action.
+ *
+ * 🛑 Why this is not just a nicety. Public URLs link by slug, so the route
+ * received a slug and did `hashGuestIdentity(slug, request)`, while
+ * `enterEvent` hashes on the resolved doc id. Two identities for one guest on
+ * one event. While the spin core's lookup was broken that was invisible (every
+ * spin 404'd); the moment the lookup was fixed it would have become a silent
+ * `spinMaxPerUser` bypass — exhaust your spins on `/events/<slug>/participate`
+ * and get a fresh allowance on `/events/<docId>/participate`.
+ *
+ * Returns `null` for an unknown event; the route then lets the spin action
+ * produce the single authoritative `event_not_found` rather than guessing at
+ * one here.
+ */
+export async function resolveEventIdAction(idOrSlug) {
+    return wrapAction(async () => {
+        const resolved = await resolveEventRef(buildContext("user.resolveEventId").db, idOrSlug);
+        return resolved?.id ?? null;
+    });
+}

package/dist/_internal/server/features/reviews/actions.js

@@ -17,7 +17,7 @@ export async function createReviewAction(input) {
         await assertNotDuplicateReview(productId, user.uid);
         const product = await productRepository.findById(productId);
         const profile = await userRepository.findById(user.uid);
-        return reviewRepository.create({
+        return reviewRepository.createReview({
             productId,
             productTitle: product?.title ?? productId,
             storeId: storeId || product?.storeId,

package/dist/_internal/server/features/reviews/data.d.ts

@@ -1,5 +1,5 @@
 export declare const getReviewsForProduct: (productId: string, limit?: number) => Promise<import("../../../..").ReviewDocument[]>;
-export declare const getReviewsForStore: (storeId: string, page?: number, pageSize?: number) => Promise<import("../../../..").FirebaseSieveResult<import("../../../..").ReviewDocument> | {
+export declare const getReviewsForStore: (storeId: string, page?: number, pageSize?: number) => Promise<import("../../../..").FirebaseSieveResult<import("../../../../security/encrypted").Plaintext<import("../../../..").ReviewDocument>> | {
     items: never[];
     total: number;
     page: number;

package/dist/_internal/server/features/search/index-build/artifact-store.d.ts

@@ -0,0 +1,89 @@
+import type { SearchIndexArtifact } from "../../../../shared/search/index-record";
+import type { Firestore } from "firebase-admin/firestore";
+import type { Bucket } from "@google-cloud/storage";
+export declare const SEARCH_INDEX_COLLECTION = "searchIndex";
+export declare const SEARCH_INDEX_MANIFEST_ID = "manifest";
+/**
+ * 🛑 A declared ceiling, and the build FAILS rather than truncating.
+ *
+ * Deliberately the opposite of `buildSearchTxt`'s `MAX_TOKENS`, which this
+ * codebase complains about in four separate places for silently slicing. A
+ * short artifact is a search index missing rows, and nothing downstream can
+ * tell that from a small catalogue. 1.5 MB against a measured 384 KB leaves
+ * roughly 4x headroom; if it is ever hit, that is a real signal.
+ */
+export declare const SEARCH_INDEX_MAX_BYTES = 1500000;
+export interface SearchIndexManifest {
+    schema: number;
+    version: number;
+    builtAt: string;
+    lastFullAt: string | null;
+    storagePath: string;
+    recordCount: number;
+    bytes: number;
+    perType: Record<string, number>;
+    /** Set by the content triggers; cleared when a build consumes it. */
+    dirty: boolean;
+}
+type ManifestDb = Firestore;
+type StorageBucket = Bucket;
+export declare function manifestRef(db: ManifestDb): FirebaseFirestore.DocumentReference<FirebaseFirestore.DocumentData, FirebaseFirestore.DocumentData>;
+export declare function readManifest(db: ManifestDb): Promise<SearchIndexManifest | null>;
+/**
+ * Mark the index stale. Called from the content triggers.
+ *
+ * 🛑 READ-THEN-WRITE, guarding on a BOOLEAN — never a deep compare.
+ * Root Cause #92's trigger cost 12 million invocations a day because its
+ * no-op guard used `JSON.stringify`, which is key-order sensitive and so
+ * never matched. A boolean cannot have that failure mode, and the read means
+ * a burst of 50 product writes costs 50 reads and exactly ONE write.
+ *
+ * Never throws: a failed dirty-mark delays the index by one cadence, and
+ * failing the product write that triggered it would be far worse.
+ */
+export declare function markSearchIndexDirty(db: ManifestDb, job: string): Promise<void>;
+export declare function storagePathFor(version: number): string;
+export interface PublishResult {
+    storagePath: string;
+    bytes: number;
+    pruned: number;
+}
+/**
+ * Write the artifact and prune older versions.
+ *
+ * The object carries `public, max-age=31536000, immutable` because the URL
+ * contains the version — a new build is a new URL, so nothing ever needs
+ * revalidating.
+ */
+export declare function publishArtifact(bucket: StorageBucket, artifact: SearchIndexArtifact): Promise<PublishResult>;
+/**
+ * Mirror the manifest to Storage so the client needs no Firebase SDK.
+ *
+ * Writes only the four fields a browser has any business reading — `dirty`,
+ * `lastFullAt` and `perType` are build bookkeeping, and publishing "the index
+ * is currently stale" to every visitor tells them nothing they can act on.
+ * The shape is `SearchIndexManifestPublic`, declared beside the URL builders.
+ *
+ * ## 🛑 60 seconds, and the number is load-bearing in both directions
+ *
+ * This is the ONLY uncacheable-for-long hop in the whole design, so it sets
+ * the floor on how fast a new build reaches a visitor — and the ceiling on
+ * how often a returning visitor pays for a request. The artifact behind it is
+ * `immutable`, so a client that re-reads the manifest and finds the same
+ * version does one small conditional fetch and no download at all.
+ *
+ * Too long and the 15-minute build cadence is a lie; too short and every
+ * visitor re-requests it per page view for a document that changes a few
+ * times an hour.
+ *
+ * ## Written LAST, and failing it does not fail the build
+ *
+ * A published artifact with a stale manifest serves the previous index for up
+ * to a minute — correct, just behind. A manifest pointing at an artifact that
+ * was never written is a 404 on the client's critical path. So the order is
+ * artifact, then Firestore, then this; and a throw here is logged, not
+ * propagated, because the Firestore manifest (which is what the NEXT build
+ * reads) is already correct by this point.
+ */
+export declare function publishManifestMirror(bucket: StorageBucket, manifest: SearchIndexManifest): Promise<void>;
+export {};

package/dist/_internal/server/features/search/index-build/artifact-store.js

@@ -0,0 +1,208 @@
+/*
+ * WHY: Where the search artifact lives, and how it is served without a
+ *      Next.js route in front of it.
+ * WHAT: The Firestore manifest singleton, the Storage upload, and the prune.
+ *
+ * ## Why Storage directly rather than an /api route
+ *
+ * A version-addressed object written with `immutable` cache headers is served
+ * by the browser and any CDN in front of the bucket with no function in the
+ * path at all. `storage.rules` is already `allow read: if true` for every
+ * object, so no rules change is needed.
+ *
+ * It is also the only shape that can be deployed AND verified under this
+ * round's constraint of no Vercel deploy: the Function writes the artifact and
+ * it is immediately fetchable. A same-origin `/api/search-index/*` proxy stays
+ * a documented fallback if CORS or egress accounting later argues for it — it
+ * would change the two URLs and nothing else.
+ *
+ * ## 🛑 Old versions MUST be pruned
+ *
+ * Immutable version-addressed objects never overwrite, so without a prune this
+ * accumulates ~384 KB per content change, for ever, against a ~5 GB allowance
+ * the media library already shares. Two versions are kept — the current one
+ * and the one it replaced — so a client that fetched mid-publish is never
+ * orphaned, matching the service worker's `maxEntries: 2`.
+ *
+ * @tag domain:search
+ * @tag layer:server
+ * @tag pattern:none
+ * @tag access:server
+ * @tag consumers:searchIndexBuild
+ * @tag sideEffects:firestore,storage
+ */
+import { normalizeError } from "../../../../../errors/normalize.js";
+import { serverLogger } from "../../../../../monitoring/server-logger.js";
+import { SEARCH_INDEX_PREFIX, SEARCH_MANIFEST_OBJECT, searchIndexObjectPath, } from "../../../../shared/search/artifact-url.js";
+export const SEARCH_INDEX_COLLECTION = "searchIndex";
+export const SEARCH_INDEX_MANIFEST_ID = "manifest";
+/*
+ * 🛑 `SEARCH_INDEX_PREFIX` and the object paths are IMPORTED, not declared
+ * here. They were declared here first, and the client then needed the same
+ * two strings — which is a mirror, and a mirror of a URL fails in the worst
+ * available way: the builder writes `search-index/v4.json`, the client asks
+ * for `searchIndex/v4.json`, and a 404 is indistinguishable from "the index
+ * has not been built yet" (Root Cause #42). One declaration, in the shared
+ * module both sides already import.
+ */
+/** Current + previous. See the prune note in the header. */
+const KEEP_VERSIONS = 2;
+/**
+ * 🛑 A declared ceiling, and the build FAILS rather than truncating.
+ *
+ * Deliberately the opposite of `buildSearchTxt`'s `MAX_TOKENS`, which this
+ * codebase complains about in four separate places for silently slicing. A
+ * short artifact is a search index missing rows, and nothing downstream can
+ * tell that from a small catalogue. 1.5 MB against a measured 384 KB leaves
+ * roughly 4x headroom; if it is ever hit, that is a real signal.
+ */
+export const SEARCH_INDEX_MAX_BYTES = 1500000;
+export function manifestRef(db) {
+    return db.collection(SEARCH_INDEX_COLLECTION).doc(SEARCH_INDEX_MANIFEST_ID);
+}
+export async function readManifest(db) {
+    const snap = await manifestRef(db).get();
+    if (!snap.exists)
+        return null;
+    /*
+     * Firestore hands back `DocumentData`, which is `Record<string, any>` — the
+     * one place a cast is unavoidable, because the SDK cannot know the shape.
+     * Narrowed to the declared interface at the single read site rather than
+     * left as `DocumentData` for callers to re-cast: the latter is how a
+     * boundary type spreads (Root Cause #98).
+     */
+    return snap.data() ?? null;
+}
+/**
+ * Mark the index stale. Called from the content triggers.
+ *
+ * 🛑 READ-THEN-WRITE, guarding on a BOOLEAN — never a deep compare.
+ * Root Cause #92's trigger cost 12 million invocations a day because its
+ * no-op guard used `JSON.stringify`, which is key-order sensitive and so
+ * never matched. A boolean cannot have that failure mode, and the read means
+ * a burst of 50 product writes costs 50 reads and exactly ONE write.
+ *
+ * Never throws: a failed dirty-mark delays the index by one cadence, and
+ * failing the product write that triggered it would be far worse.
+ */
+export async function markSearchIndexDirty(db, job) {
+    try {
+        const ref = manifestRef(db);
+        const snap = await ref.get();
+        if (snap.exists && snap.data()?.dirty === true)
+            return;
+        await ref.set({ dirty: true }, { merge: true });
+    }
+    catch (err) {
+        const e = normalizeError(err);
+        serverLogger.warn("markSearchIndexDirty failed (non-fatal)", { job, message: e.message });
+    }
+}
+export function storagePathFor(version) {
+    return searchIndexObjectPath(version);
+}
+/**
+ * Write the artifact and prune older versions.
+ *
+ * The object carries `public, max-age=31536000, immutable` because the URL
+ * contains the version — a new build is a new URL, so nothing ever needs
+ * revalidating.
+ */
+export async function publishArtifact(bucket, artifact) {
+    const body = Buffer.from(JSON.stringify(artifact), "utf8");
+    if (body.byteLength > SEARCH_INDEX_MAX_BYTES) {
+        // Loud, not truncated. See SEARCH_INDEX_MAX_BYTES.
+        throw new Error(`search index artifact is ${body.byteLength} bytes, over the declared ` +
+            `${SEARCH_INDEX_MAX_BYTES}. Refusing to publish a silently short index — ` +
+            `raise the ceiling deliberately or find out why it grew.`);
+    }
+    const path = storagePathFor(artifact.version);
+    await bucket.file(path).save(body, {
+        contentType: "application/json; charset=utf-8",
+        metadata: {
+            cacheControl: "public, max-age=31536000, immutable",
+            contentEncoding: undefined,
+        },
+    });
+    let pruned = 0;
+    try {
+        const [files] = await bucket.getFiles({ prefix: `${SEARCH_INDEX_PREFIX}/v` });
+        const versions = files
+            .map((f) => ({ name: f.name, v: Number(/v(\d+)\.json$/.exec(f.name)?.[1] ?? NaN) }))
+            .filter((f) => Number.isFinite(f.v))
+            .sort((a, b) => b.v - a.v);
+        for (const stale of versions.slice(KEEP_VERSIONS)) {
+            await bucket.file(stale.name).delete();
+            pruned++;
+        }
+    }
+    catch (err) {
+        /*
+         * A failed prune is NOT a failed publish. The new artifact is already
+         * live and correct; the cost of leaving an extra 384 KB object behind is
+         * trivial next to failing a build that produced a good index.
+         */
+        const e = normalizeError(err);
+        serverLogger.warn("search index prune failed (artifact is published)", {
+            message: e.message,
+        });
+    }
+    return { storagePath: path, bytes: body.byteLength, pruned };
+}
+/**
+ * Mirror the manifest to Storage so the client needs no Firebase SDK.
+ *
+ * Writes only the four fields a browser has any business reading — `dirty`,
+ * `lastFullAt` and `perType` are build bookkeeping, and publishing "the index
+ * is currently stale" to every visitor tells them nothing they can act on.
+ * The shape is `SearchIndexManifestPublic`, declared beside the URL builders.
+ *
+ * ## 🛑 60 seconds, and the number is load-bearing in both directions
+ *
+ * This is the ONLY uncacheable-for-long hop in the whole design, so it sets
+ * the floor on how fast a new build reaches a visitor — and the ceiling on
+ * how often a returning visitor pays for a request. The artifact behind it is
+ * `immutable`, so a client that re-reads the manifest and finds the same
+ * version does one small conditional fetch and no download at all.
+ *
+ * Too long and the 15-minute build cadence is a lie; too short and every
+ * visitor re-requests it per page view for a document that changes a few
+ * times an hour.
+ *
+ * ## Written LAST, and failing it does not fail the build
+ *
+ * A published artifact with a stale manifest serves the previous index for up
+ * to a minute — correct, just behind. A manifest pointing at an artifact that
+ * was never written is a 404 on the client's critical path. So the order is
+ * artifact, then Firestore, then this; and a throw here is logged, not
+ * propagated, because the Firestore manifest (which is what the NEXT build
+ * reads) is already correct by this point.
+ */
+export async function publishManifestMirror(bucket, manifest) {
+    try {
+        const body = Buffer.from(JSON.stringify({
+            schema: manifest.schema,
+            version: manifest.version,
+            builtAt: manifest.builtAt,
+            recordCount: manifest.recordCount,
+        }), "utf8");
+        await bucket.file(SEARCH_MANIFEST_OBJECT).save(body, {
+            contentType: "application/json; charset=utf-8",
+            metadata: { cacheControl: "public, max-age=60" },
+        });
+    }
+    catch (err) {
+        const e = normalizeError(err);
+        /*
+         * WARN rather than throw. But it is a real symptom: the artifact is live
+         * and no client will ever learn its version, so the index silently stops
+         * advancing while every other signal says the build succeeded. That is
+         * precisely the "confident wrong answer" shape, which is why it is logged
+         * at WARN and not swallowed.
+         */
+        serverLogger.warn("search index manifest mirror failed (artifact is published)", {
+            version: manifest.version,
+            message: e.message,
+        });
+    }
+}

package/dist/_internal/server/features/search/index-build/build.d.ts

@@ -0,0 +1,57 @@
+import { type IndexDocData } from "./sources";
+import { type SearchIndexArtifact, type SearchIndexRecord } from "../../../../shared/search/index-record";
+/** The minimal Firestore surface this module needs, so it stays testable. */
+interface BuildQuery {
+    where(field: string, op: string, value: unknown): BuildQuery;
+    select(...fields: string[]): BuildQuery;
+    get(): Promise<{
+        docs: Array<{
+            id: string;
+            data(): IndexDocData;
+        }>;
+    }>;
+}
+interface BuildDb {
+    collection(name: string): BuildQuery;
+}
+export interface BuildStats {
+    readonly mode: "full" | "incremental";
+    /** Documents READ. This is the number that has to stay inside the budget. */
+    readonly reads: number;
+    readonly perType: Readonly<Record<string, number>>;
+    /** Documents read but rejected by `toRecord` — unpublished, unjoinable, … */
+    readonly dropped: number;
+    /**
+     * Sources that threw. Non-zero means the artifact is INCOMPLETE for those
+     * types, so the caller must not treat the build as clean — see the
+     * `dirty` handling in `searchIndexBuild`.
+     */
+    readonly failed: number;
+    readonly durationMs: number;
+}
+export interface BuildResult {
+    readonly artifact: SearchIndexArtifact;
+    readonly stats: BuildStats;
+}
+/**
+ * Build from scratch. Reconciles hard deletes by construction, because the
+ * result contains exactly what the sources currently return.
+ */
+export declare function buildFull(db: BuildDb, version: number, now?: Date): Promise<BuildResult>;
+/**
+ * Patch the previous artifact with everything that changed since it was built.
+ *
+ * 🛑 A source that fails here is logged and SKIPPED, not fatal — unlike the
+ * full build. The difference is what the failure costs: a skipped incremental
+ * source leaves that type's records at their previous (correct, slightly
+ * stale) values and the next pass picks them up, whereas a skipped full source
+ * would delete the type from the artifact entirely.
+ */
+export declare function buildIncremental(db: BuildDb, previous: SearchIndexArtifact, since: Date, version: number, now?: Date): Promise<BuildResult>;
+/**
+ * Re-key a record from a previous artifact. Mirrors `keyOf` — both sides key
+ * on `${typeKey}:${slug}`, which is the invariant that makes an incremental
+ * patch REPLACE a changed row rather than add a second copy of it.
+ */
+export declare function keyFromRecord(rec: SearchIndexRecord): string | null;
+export {};