@mohasinac/appkit 4.30.2 → 4.30.4

package/dist/features/blog/actions/blog-actions.d.ts

@@ -102,9 +102,9 @@ export declare const createBlogPostSchema: z.ZodObject<{
     } | null | undefined;
     authorId?: string | undefined;
     authorName?: string | undefined;
+    authorAvatar?: string | undefined;
     metaTitle?: string | undefined;
     metaDescription?: string | undefined;
-    authorAvatar?: string | undefined;
 }, {
     title: string;
     content: string;
@@ -130,8 +130,6 @@ export declare const createBlogPostSchema: z.ZodObject<{
         alt?: string | undefined;
         thumbnailUrl?: string | undefined;
     }[] | undefined;
-    metaTitle?: string | undefined;
-    metaDescription?: string | undefined;
     contentImages?: {
         type: "video" | "image" | "file";
         url: string;
@@ -139,6 +137,8 @@ export declare const createBlogPostSchema: z.ZodObject<{
         thumbnailUrl?: string | undefined;
     }[] | undefined;
     authorAvatar?: string | undefined;
+    metaTitle?: string | undefined;
+    metaDescription?: string | undefined;
 }>;
 export declare const updateBlogPostSchema: z.ZodObject<{
     title: z.ZodOptional<z.ZodString>;
@@ -235,8 +235,6 @@ export declare const updateBlogPostSchema: z.ZodObject<{
         alt?: string | undefined;
         thumbnailUrl?: string | undefined;
     }[] | undefined;
-    metaTitle?: string | undefined;
-    metaDescription?: string | undefined;
     contentImages?: {
         type: "video" | "image" | "file";
         url: string;
@@ -244,6 +242,8 @@ export declare const updateBlogPostSchema: z.ZodObject<{
         thumbnailUrl?: string | undefined;
     }[] | undefined;
     authorAvatar?: string | undefined;
+    metaTitle?: string | undefined;
+    metaDescription?: string | undefined;
 }, {
     status?: "draft" | "published" | "archived" | undefined;
     title?: string | undefined;
@@ -269,8 +269,6 @@ export declare const updateBlogPostSchema: z.ZodObject<{
         alt?: string | undefined;
         thumbnailUrl?: string | undefined;
     }[] | undefined;
-    metaTitle?: string | undefined;
-    metaDescription?: string | undefined;
     contentImages?: {
         type: "video" | "image" | "file";
         url: string;
@@ -278,6 +276,8 @@ export declare const updateBlogPostSchema: z.ZodObject<{
         thumbnailUrl?: string | undefined;
     }[] | undefined;
     authorAvatar?: string | undefined;
+    metaTitle?: string | undefined;
+    metaDescription?: string | undefined;
 }>;
 export type CreateBlogPostInput = z.infer<typeof createBlogPostSchema>;
 export type UpdateBlogPostInput = z.infer<typeof updateBlogPostSchema>;

package/dist/features/blog/api/route.js

@@ -8,6 +8,7 @@
  * export { GET } from "@mohasinac/feat-blog";
  * ```
  */
+import { blogRepository } from "../repository/blog.repository";
 import { NextResponse } from "next/server.js";
 import { getProviders } from "../../../contracts";
 import { normalizeError } from "../../../errors/normalize";
@@ -33,9 +34,11 @@ export async function GET(request) {
         const tags = param(url, "tags");
         if (tags)
             parts.push(`tags@=${tags}`);
+        // Token search rides OUTSIDE `filters` — array-contains is not expressible
+        // in Sieve, and as `title@=*` this was a case-SENSITIVE prefix match on the
+        // generic repository path (`base.ts`), so "Beyblade" matched and "beyblade"
+        // did not. searchTxt is normalised, so case and accents stop mattering.
         const q = param(url, "q");
-        if (q)
-            parts.push(`title@=*${q}`);
         const featured = param(url, "featured");
         if (featured === "true")
             parts.push("isFeatured==true");
@@ -46,17 +49,19 @@ export async function GET(request) {
         if (!db) {
             return NextResponse.json({ success: false, error: "Database provider not registered" }, { status: 503 });
         }
-        const repo = db.getRepository("blogPosts");
-        const result = await repo.findAll({ filters, sort, page, perPage });
+        // `blogRepository.listAll` rather than the generic `db.getRepository(...)`:
+        // only the feature repository knows how to push a searchTxt clause down and
+        // AND-refine the remaining terms.
+        const result = await blogRepository.listAll({ filters, sorts: sort, page, pageSize: perPage }, q ? { search: q } : undefined);
         const meta = {
             total: result.total,
             page: result.page,
-            pageSize: result.perPage,
+            pageSize: result.pageSize,
             totalPages: result.totalPages,
-            hasMore: result.page < result.totalPages,
+            hasMore: result.hasMore,
         };
         const body = {
-            posts: result.data,
+            posts: result.items,
             meta,
         };
         return NextResponse.json({ success: true, data: body });

package/dist/features/blog/repository/blog.repository.d.ts

@@ -1,3 +1,4 @@
+import type { JsonValue } from "../../../schemas/types";
 import type { FirebaseSieveResult, SieveModel } from "../../../providers/db-firebase";
 import { BaseRepository, parseSieveDateValue } from "../../../providers/db-firebase";
 import { type BlogPostCreateInput, type BlogPostDocument, type BlogPostUpdateInput } from "../schemas";
@@ -86,7 +87,11 @@ declare class BlogRepository extends BaseRepository<BlogPostDocument> {
         category?: BlogPostCategory;
         featuredOnly?: boolean;
     }, model: SieveModel): Promise<FirebaseSieveResult<BlogPostDocument>>;
-    listAll(model: SieveModel): Promise<FirebaseSieveResult<BlogPostDocument>>;
+    /** Derived on every write path via `applyWriteHooks`. */
+    protected buildSearchTxtFor(data: Record<string, JsonValue>): string[] | null;
+    listAll(model: SieveModel, opts?: {
+        search?: string;
+    }): Promise<FirebaseSieveResult<BlogPostDocument>>;
 }
 declare const blogRepository: BlogRepository;
 export { BlogRepository, blogRepository };

package/dist/features/blog/repository/blog.repository.js

@@ -4,6 +4,8 @@ import { BaseRepository, prepareForFirestore, parseSieveDateValue, } from "../..
 import { BLOG_POST_FIELDS, BLOG_POSTS_COLLECTION, } from "../schemas";
 import { createBlogPostId } from "../schemas";
 import { increment } from "../../../contracts/field-ops";
+import { buildBlogSearchTxt } from "../../../utils/search-txt-builders";
+import { planSearchTxt, refineSearchTxt, emptySearchResult, } from "../../../utils/search-txt-query";
 class BlogRepository extends BaseRepository {
     constructor() {
         super(BLOG_POSTS_COLLECTION);
@@ -153,11 +155,24 @@ class BlogRepository extends BaseRepository {
             maxPageSize: 50,
         });
     }
-    async listAll(model) {
-        return this.sieveQuery(model, BlogRepository.SIEVE_FIELDS, {
+    /** Derived on every write path via `applyWriteHooks`. */
+    buildSearchTxtFor(data) {
+        return buildBlogSearchTxt(data);
+    }
+    async listAll(model, opts) {
+        const plan = planSearchTxt(opts?.search);
+        if (plan.empty)
+            return emptySearchResult();
+        let baseQuery = this.getCollection();
+        if (plan.head) {
+            baseQuery = baseQuery.where(BLOG_POST_FIELDS.SEARCH_TXT, "array-contains", plan.head);
+        }
+        const result = await this.sieveQuery(model, BlogRepository.SIEVE_FIELDS, {
+            baseQuery,
             defaultPageSize: 50,
             maxPageSize: 200,
         });
+        return refineSearchTxt(result, plan.rest);
     }
 }
 BlogRepository.SIEVE_FIELDS = {

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

@@ -42,6 +42,8 @@ export interface BlogPostDocument extends BaseDocument {
 export declare const BLOG_POSTS_COLLECTION: "blogPosts";
 export declare const BLOG_POSTS_INDEXED_FIELDS: readonly ["searchTxt", "status", "publishedAt", "isFeatured", "category", "slug"];
 export declare const BLOG_POST_FIELDS: {
+    /** Word-prefix search tokens. Derived on write by `buildSearchTxtFor`. */
+    readonly SEARCH_TXT: "searchTxt";
     readonly ID: "id";
     readonly TITLE: "title";
     readonly SLUG: "slug";

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

@@ -18,6 +18,8 @@ export const BLOG_POSTS_INDEXED_FIELDS = [
     "slug",
 ];
 export const BLOG_POST_FIELDS = {
+    /** Word-prefix search tokens. Derived on write by `buildSearchTxtFor`. */
+    SEARCH_TXT: "searchTxt",
     ID: "id",
     TITLE: "title",
     SLUG: "slug",

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

@@ -155,8 +155,6 @@ export declare const blogPostFirestoreSchema: z.ZodObject<{
         youtubeId?: string | undefined;
         duration?: number | undefined;
     }[] | undefined;
-    metaTitle?: string | undefined;
-    metaDescription?: string | undefined;
     contentImages?: {
         type: "video" | "image" | "file";
         url: string;
@@ -167,6 +165,8 @@ export declare const blogPostFirestoreSchema: z.ZodObject<{
         duration?: number | undefined;
     }[] | undefined;
     authorAvatar?: string | undefined;
+    metaTitle?: string | undefined;
+    metaDescription?: string | undefined;
 }, {
     status: "draft" | "published" | "archived";
     id: string;
@@ -208,8 +208,6 @@ export declare const blogPostFirestoreSchema: z.ZodObject<{
         youtubeId?: string | undefined;
         duration?: number | undefined;
     }[] | undefined;
-    metaTitle?: string | undefined;
-    metaDescription?: string | undefined;
     contentImages?: {
         type: "video" | "image" | "file";
         url: string;
@@ -220,6 +218,8 @@ export declare const blogPostFirestoreSchema: z.ZodObject<{
         duration?: number | undefined;
     }[] | undefined;
     authorAvatar?: string | undefined;
+    metaTitle?: string | undefined;
+    metaDescription?: string | undefined;
 }>;
 export type BlogPostFromSchema = z.infer<typeof blogPostFirestoreSchema>;
 export declare const blogPostCategorySchema: z.ZodEnum<["news", "tips", "guides", "updates", "community"]>;
@@ -401,9 +401,9 @@ export declare const blogPostSchema: z.ZodObject<{
     authorId?: string | undefined;
     authorName?: string | undefined;
     readTimeMinutes?: number | undefined;
+    authorAvatar?: string | undefined;
     metaTitle?: string | undefined;
     metaDescription?: string | undefined;
-    authorAvatar?: string | undefined;
 }, {
     status: "draft" | "published" | "archived";
     id: string;
@@ -439,8 +439,6 @@ export declare const blogPostSchema: z.ZodObject<{
         youtubeId?: string | undefined;
         duration?: number | undefined;
     }[] | undefined;
-    metaTitle?: string | undefined;
-    metaDescription?: string | undefined;
     contentImages?: {
         type: "video" | "image" | "file";
         url: string;
@@ -451,6 +449,8 @@ export declare const blogPostSchema: z.ZodObject<{
         duration?: number | undefined;
     }[] | undefined;
     authorAvatar?: string | undefined;
+    metaTitle?: string | undefined;
+    metaDescription?: string | undefined;
 }>;
 /** Base Zod schema for list-query parameters. */
 export declare const blogListParamsSchema: z.ZodObject<{

package/dist/features/events/repository/events.repository.d.ts

@@ -1,10 +1,19 @@
+import type { JsonValue } from "../../../schemas/types";
 import type { FirebaseSieveFields, FirebaseSieveResult, SieveModel } from "../../../providers/db-firebase";
 import { BaseRepository } from "../../../providers/db-firebase";
 import { type EventCreateInput, type EventDocument, type EventUpdateInput } from "../schemas";
 declare class EventRepository extends BaseRepository<EventDocument> {
     static readonly SIEVE_FIELDS: FirebaseSieveFields;
     constructor();
-    list(model: SieveModel): Promise<FirebaseSieveResult<EventDocument>>;
+    /**
+     * Derived on every write path via `applyWriteHooks`. The field, its index and
+     * its seed tokens all existed before this — but nothing wrote it for a
+     * document created through the app, so only seeded events were searchable.
+     */
+    protected buildSearchTxtFor(data: Record<string, JsonValue>): string[] | null;
+    list(model: SieveModel, opts?: {
+        search?: string;
+    }): Promise<FirebaseSieveResult<EventDocument>>;
     /**
      * How many events exist per `type` and per `status` — the numbers behind the
      * facet checkboxes, and what lets a type with no events disappear from the

package/dist/features/events/repository/events.repository.js

@@ -6,12 +6,31 @@ import { normalizeError } from "../../../errors/normalize";
 import { BaseRepository, prepareForFirestore, parseSieveDateValue, } from "../../../providers/db-firebase";
 import { EVENT_FIELDS, EVENTS_COLLECTION, } from "../schemas";
 import { increment } from "../../../contracts/field-ops";
+import { buildEventSearchTxt } from "../../../utils/search-txt-builders";
+import { planSearchTxt, refineSearchTxt, emptySearchResult, } from "../../../utils/search-txt-query";
 class EventRepository extends BaseRepository {
     constructor() {
         super(EVENTS_COLLECTION);
     }
-    async list(model) {
-        return this.sieveQuery(model, EventRepository.SIEVE_FIELDS);
+    /**
+     * Derived on every write path via `applyWriteHooks`. The field, its index and
+     * its seed tokens all existed before this — but nothing wrote it for a
+     * document created through the app, so only seeded events were searchable.
+     */
+    buildSearchTxtFor(data) {
+        return buildEventSearchTxt(data);
+    }
+    async list(model, opts) {
+        const plan = planSearchTxt(opts?.search);
+        // A search that yielded no usable term must return NOTHING, not everything.
+        if (plan.empty)
+            return emptySearchResult();
+        let baseQuery = this.getCollection();
+        if (plan.head) {
+            baseQuery = baseQuery.where(EVENT_FIELDS.SEARCH_TXT, "array-contains", plan.head);
+        }
+        const result = await this.sieveQuery(model, EventRepository.SIEVE_FIELDS, { baseQuery });
+        return refineSearchTxt(result, plan.rest);
     }
     /**
      * How many events exist per `type` and per `status` — the numbers behind the

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

@@ -105,6 +105,8 @@ export type EventEntryDocument = {
 export declare const EVENT_INDEXED_FIELDS: readonly ["searchTxt", "type", "status", "startsAt", "endsAt", "createdAt"];
 export declare const EVENT_ENTRY_INDEXED_FIELDS: readonly ["eventId", "userId", "guestIpHash", "reviewStatus", "status", "submittedAt", "points", "spinWonAt"];
 export declare const EVENT_FIELDS: {
+    /** Word-prefix search tokens. Derived on write by `buildSearchTxtFor`. */
+    readonly SEARCH_TXT: "searchTxt";
     readonly ID: "id";
     readonly SLUG: "slug";
     readonly TYPE: "type";

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

@@ -22,6 +22,8 @@ export const EVENT_ENTRY_INDEXED_FIELDS = [
     "spinWonAt",
 ];
 export const EVENT_FIELDS = {
+    /** Word-prefix search tokens. Derived on write by `buildSearchTxtFor`. */
+    SEARCH_TXT: "searchTxt",
     ID: "id",
     SLUG: "slug",
     TYPE: "type",

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

@@ -5,7 +5,10 @@ import { BaseRepository, prepareForFirestore, parseSieveDateValue, } from "../..
 import { cacheManager } from "../../../core";
 import { serverLogger } from "../../../monitoring";
 import { generateUniqueId, slugify, generateBarcodeId } from "../../../utils";
-import { buildSearchTxt, matchesAllSearchTerms, parseSearchTxtQuery, } from "../../../utils/search-txt";
+import { matchesAllSearchTerms, parseSearchTxtQuery, } from "../../../utils/search-txt";
+// One definition of "which fields feed searchTxt", shared with the seed
+// wrapper. Three copies existed and two were missing the same three fields.
+import { buildProductSearchTxt } from "../../../utils/search-txt-builders";
 import { PRODUCT_COLLECTION, ProductStatusValues } from "../schemas";
 import { PRODUCT_FIELDS } from "../../../constants/field-names";
 /**
@@ -46,22 +49,6 @@ function buildListingKindClause(kind, inverted) {
     const op = inverted ? "!=" : "==";
     return `${PRODUCT_FIELDS.LISTING_TYPE}${op}${canonical}`;
 }
-function buildProductSearchTxt(p) {
-    return buildSearchTxt([
-        p.title,
-        p.description,
-        p.brand,
-        p.brandSlug,
-        p.categoryNames,
-        p.tags,
-        p.features,
-        p.condition,
-        p.card?.setName,
-        p.card?.cardNumber,
-        p.grading?.service,
-        p.specifications?.map((s) => `${s.name} ${s.value}`),
-    ]);
-}
 export class ProductRepository extends BaseRepository {
     constructor() {
         super(PRODUCT_COLLECTION);

package/dist/features/reviews/repository/reviews.repository.d.ts

@@ -1,3 +1,4 @@
+import type { JsonValue } from "../../../schemas/types";
 import type { FirebaseSieveResult, SieveModel } from "../../../providers/db-firebase";
 import { BaseRepository, parseSieveDateValue } from "../../../providers/db-firebase";
 import { type ReviewCreateInput, type ReviewDocument } from "../schemas";
@@ -173,7 +174,16 @@ declare class ReviewRepository extends BaseRepository<ReviewDocument> {
     };
     listForProduct(productId: string, model: SieveModel): Promise<FirebaseSieveResult<ReviewDocument>>;
     listForStore(storeId: string, model: SieveModel): Promise<FirebaseSieveResult<ReviewDocument>>;
-    listAll(model: SieveModel): Promise<FirebaseSieveResult<ReviewDocument>>;
+    /**
+     * Derived on every write path via `applyWriteHooks`.
+     *
+     * `userName` is PII and is deliberately absent from the token source — a
+     * searchTxt for a person's name IS that name, re-encoded (D1).
+     */
+    protected buildSearchTxtFor(data: Record<string, JsonValue>): string[] | null;
+    listAll(model: SieveModel, opts?: {
+        search?: string;
+    }): Promise<FirebaseSieveResult<ReviewDocument>>;
 }
 declare const reviewRepository: ReviewRepository;
 export { ReviewRepository, reviewRepository };

package/dist/features/reviews/repository/reviews.repository.js

@@ -3,7 +3,11 @@ import { NotFoundError } from "../../../errors";
 import { REVIEW_MAX_RATING, REVIEW_MIN_RATING } from "../../../_internal/shared/features/reviews/config";
 import { decryptPiiFields, encryptPiiFields, piiIndicesFor, REVIEW_PII_FIELDS, REVIEW_PII_INDEX_MAP, } from "../../../security";
 import { createReviewId, REVIEW_COLLECTION, } from "../schemas";
+import { buildReviewSearchTxt } from "../../../utils/search-txt-builders";
+import { planSearchTxt, refineSearchTxt, emptySearchResult, } from "../../../utils/search-txt-query";
 const REVIEW_FIELDS = {
+    /** Word-prefix search tokens. Derived on write by `buildSearchTxtFor`. */
+    SEARCH_TXT: "searchTxt",
     PRODUCT_ID: "productId",
     USER_ID: "userId",
     STORE_ID: "storeId",
@@ -309,12 +313,31 @@ class ReviewRepository extends BaseRepository {
         });
         return this.decryptSieveResult(result);
     }
-    async listAll(model) {
+    /**
+     * Derived on every write path via `applyWriteHooks`.
+     *
+     * `userName` is PII and is deliberately absent from the token source — a
+     * searchTxt for a person's name IS that name, re-encoded (D1).
+     */
+    buildSearchTxtFor(data) {
+        return buildReviewSearchTxt(data);
+    }
+    async listAll(model, opts) {
+        const plan = planSearchTxt(opts?.search);
+        if (plan.empty)
+            return emptySearchResult();
+        let baseQuery = this.getCollection();
+        if (plan.head) {
+            baseQuery = baseQuery.where(REVIEW_FIELDS.SEARCH_TXT, "array-contains", plan.head);
+        }
         const result = await this.sieveQuery(model, ReviewRepository.SIEVE_FIELDS, {
+            baseQuery,
             defaultPageSize: 50,
             maxPageSize: 200,
         });
-        return this.decryptSieveResult(result);
+        // Refine BEFORE decrypting: the refine reads `searchTxt`, which is never
+        // encrypted, and decrypting rows that are about to be dropped is waste.
+        return this.decryptSieveResult(refineSearchTxt(result, plan.rest));
     }
 }
 ReviewRepository.SIEVE_FIELDS = {

package/dist/features/stores/repository/store.repository.d.ts

@@ -7,6 +7,7 @@
 import { BaseRepository, type SieveModel, type FirebaseSieveResult, type DocumentSnapshot } from "../../../providers/db-firebase";
 import { StoreDocument } from "../schemas";
 import { type HistoryActor } from "../../../_internal/shared/history/index";
+import type { JsonValue } from "../../../schemas/types";
 /** Who/why for a store write that lands in `statusHistory`. */
 export interface StoreWriteContext {
     actor?: HistoryActor;
@@ -89,7 +90,11 @@ export declare class StoreRepository extends BaseRepository<StoreDocument> {
      * Paginated list of stores with Sieve filtering/sorting.
      * Filters to active + public stores for the public listing.
      */
-    listStores(model: SieveModel, activeOnly?: boolean): Promise<FirebaseSieveResult<StoreDocument>>;
+    /** Derived on every write path via `applyWriteHooks`. */
+    protected buildSearchTxtFor(data: Record<string, JsonValue>): string[] | null;
+    listStores(model: SieveModel, activeOnly?: boolean, opts?: {
+        search?: string;
+    }): Promise<FirebaseSieveResult<StoreDocument>>;
     /**
      * Admin: list all stores regardless of status.
      */

package/dist/features/stores/repository/store.repository.js

@@ -11,6 +11,8 @@ import { DatabaseError } from "../../../errors";
 import { normalizeError } from "../../../errors/normalize";
 import { encryptSecret, decryptSecret, } from "../../../security/settings-encryption";
 import { withHistory } from "../../../_internal/shared/history/index";
+import { buildStoreSearchTxt } from "../../../utils/search-txt-builders";
+import { planSearchTxt, refineSearchTxt, emptySearchResult, } from "../../../utils/search-txt-query";
 export class StoreRepository extends BaseRepository {
     constructor() {
         super(STORE_COLLECTION);
@@ -178,7 +180,11 @@ export class StoreRepository extends BaseRepository {
      * Paginated list of stores with Sieve filtering/sorting.
      * Filters to active + public stores for the public listing.
      */
-    async listStores(model, activeOnly = true) {
+    /** Derived on every write path via `applyWriteHooks`. */
+    buildSearchTxtFor(data) {
+        return buildStoreSearchTxt(data);
+    }
+    async listStores(model, activeOnly = true, opts) {
         const sieveFields = {
             [STORE_FIELDS.STORE_NAME]: { canFilter: true, canSort: true },
             searchTxt: { canFilter: true, canSort: false },
@@ -196,13 +202,20 @@ export class StoreRepository extends BaseRepository {
             "stats.averageRating": { canFilter: false, canSort: true },
             "stats.totalProducts": { canFilter: true, canSort: false },
         };
+        const plan = planSearchTxt(opts?.search);
+        // A search that yielded no usable term must return NOTHING, not everything.
+        if (plan.empty)
+            return emptySearchResult();
         let baseQuery = this.getCollection();
         if (activeOnly) {
             baseQuery = baseQuery
                 .where(STORE_FIELDS.STATUS, "==", "active")
                 .where(STORE_FIELDS.IS_PUBLIC, "==", true);
         }
-        return applySieveToFirestore({
+        if (plan.head) {
+            baseQuery = baseQuery.where(STORE_FIELDS.SEARCH_TXT, "array-contains", plan.head);
+        }
+        const result = await applySieveToFirestore({
             baseQuery,
             model,
             fields: sieveFields,
@@ -212,6 +225,7 @@ export class StoreRepository extends BaseRepository {
             // WhatsApp bearer token and a list has no use for it.
             mapDoc: (snap) => this.mapDocForList(snap),
         });
+        return refineSearchTxt(result, plan.rest);
     }
     /**
      * Admin: list all stores regardless of status.

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

@@ -174,6 +174,8 @@ export declare const STORE_HISTORY_PII_FIELDS: readonly ["accessToken", "payoutD
 export type { StoreCapability } from "../../auth/permissions/constants";
 export declare const STORE_COLLECTION: "stores";
 export declare const STORE_FIELDS: {
+    /** Word-prefix search tokens. Derived on write by `buildSearchTxtFor`. */
+    readonly SEARCH_TXT: "searchTxt";
     readonly ID: "id";
     readonly STORE_SLUG: "storeSlug";
     readonly OWNER_ID: "ownerId";

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

@@ -45,6 +45,8 @@ export const STORE_HISTORY_PII_FIELDS = [
 ];
 export const STORE_COLLECTION = "stores";
 export const STORE_FIELDS = {
+    /** Word-prefix search tokens. Derived on write by `buildSearchTxtFor`. */
+    SEARCH_TXT: "searchTxt",
     ID: "id",
     STORE_SLUG: "storeSlug",
     OWNER_ID: "ownerId",

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

@@ -617,9 +617,9 @@ export declare const storeListItemSchema: z.ZodObject<{
     storeLogoURL?: string | undefined;
     storeBannerURL?: string | undefined;
     itemsSold?: number | undefined;
-    averageRating?: number | undefined;
     totalProducts?: number | undefined;
     totalReviews?: number | undefined;
+    averageRating?: number | undefined;
 }, {
     status: string;
     id: string;
@@ -633,9 +633,9 @@ export declare const storeListItemSchema: z.ZodObject<{
     storeLogoURL?: string | undefined;
     storeBannerURL?: string | undefined;
     itemsSold?: number | undefined;
-    averageRating?: number | undefined;
     totalProducts?: number | undefined;
     totalReviews?: number | undefined;
+    averageRating?: number | undefined;
 }>;
 export declare const storeListParamsSchema: z.ZodObject<{
     category: z.ZodOptional<z.ZodString>;

package/dist/providers/db-firebase/base.repository.d.ts

@@ -1,6 +1,7 @@
 import type { FirestoreDocument } from "@mohasinac/appkit";
 import type { CollectionReference, DocumentData, DocumentReference, DocumentSnapshot, Firestore, Query, Transaction, WriteBatch } from "firebase-admin/firestore";
 import { type FirebaseSieveFields, type FirebaseSieveOptions, type FirebaseSieveResult, type SieveModel } from "./sieve";
+import type { JsonValue } from "../../schemas/types";
 export declare abstract class BaseRepository<T extends DocumentData> {
     protected collection: string;
     constructor(collectionName: string);
@@ -46,7 +47,7 @@ export declare abstract class BaseRepository<T extends DocumentData> {
      * MUST NOT include PII: `searchTxt` stores readable fragments of the source
      * text, so indexing an encrypted field would undo the encryption.
      */
-    protected buildSearchTxtFor(_data: Record<string, unknown>): string[] | null;
+    protected buildSearchTxtFor(_data: Record<string, JsonValue>): string[] | null;
     /**
      * The one place writes are transformed. Every write path routes through here
      * so a new method cannot silently skip encryption.

package/dist/schemas/registry.d.ts

@@ -226,8 +226,6 @@ export declare const SCHEMAS: {
                 youtubeId?: string | undefined;
                 duration?: number | undefined;
             }[] | undefined;
-            metaTitle?: string | undefined;
-            metaDescription?: string | undefined;
             contentImages?: {
                 type: "video" | "image" | "file";
                 url: string;
@@ -238,6 +236,8 @@ export declare const SCHEMAS: {
                 duration?: number | undefined;
             }[] | undefined;
             authorAvatar?: string | undefined;
+            metaTitle?: string | undefined;
+            metaDescription?: string | undefined;
         }, {
             status: "draft" | "published" | "archived";
             id: string;
@@ -279,8 +279,6 @@ export declare const SCHEMAS: {
                 youtubeId?: string | undefined;
                 duration?: number | undefined;
             }[] | undefined;
-            metaTitle?: string | undefined;
-            metaDescription?: string | undefined;
             contentImages?: {
                 type: "video" | "image" | "file";
                 url: string;
@@ -291,6 +289,8 @@ export declare const SCHEMAS: {
                 duration?: number | undefined;
             }[] | undefined;
             authorAvatar?: string | undefined;
+            metaTitle?: string | undefined;
+            metaDescription?: string | undefined;
         }>;
         readonly carousels: import("zod").ZodObject<{
             createdAt: import("zod").ZodUnion<[import("zod").ZodDate, import("zod").ZodString, import("zod").ZodObject<{

package/dist/seed/_helpers/product-search-txt.js

@@ -1,4 +1,4 @@
-import { buildSearchTxt } from "../../utils/search-txt";
+import { buildProductSearchTxt } from "../../utils/search-txt-builders";
 /**
  * Derive `searchTxt` for a seeded product from its own content.
  *
@@ -16,18 +16,8 @@ import { buildSearchTxt } from "../../utils/search-txt";
  * reintroduce the `appkit-seed` idempotency problem of Root Cause #25.
  */
 export function withProductSearchTxt(p) {
-    return {
-        ...p,
-        searchTxt: buildSearchTxt([
-            p.title,
-            p.description,
-            p.brand,
-            p.brandSlug,
-            p.categoryNames,
-            p.tags,
-            p.features,
-            p.condition,
-            p.specifications?.map((s) => `${s.name} ${s.value}`),
-        ]),
-    };
+    // Delegates rather than re-deriving. This wrapper listed 9 sources while the
+    // write path indexed 12, so a seeded product was findable by fewer terms than
+    // the identical product created through the app — with no error on either side.
+    return { ...p, searchTxt: buildProductSearchTxt(p) };
 }

package/dist/seed/_helpers/search-txt-wrappers.d.ts

@@ -1,20 +1,8 @@
-import type { StoreDocument } from "../../features/stores/schemas";
-import type { EventDocument } from "../../features/events/schemas";
-import type { BlogPostDocument } from "../../features/blog/schemas";
-import type { ReviewDocument } from "../../features/reviews/schemas";
-/** stores — name, description, category. No payout details, no contact. */
+import type { StoreDocument } from "../../features/stores/schemas/firestore";
+import type { EventDocument } from "../../features/events/schemas/firestore";
+import type { BlogPostDocument } from "../../features/blog/schemas/firestore";
+import type { ReviewDocument } from "../../features/reviews/schemas/firestore";
 export declare function withStoreSearchTxt<T extends Partial<StoreDocument>>(p: T): T;
-/** events — title, description, type, tags. */
 export declare function withEventSearchTxt<T extends Partial<EventDocument>>(p: T): T;
-/**
- * blogPosts — title, excerpt, category, tags.
- *
- * The full `content` body is deliberately EXCLUDED. FAQ answers are short
- * (measured: max 449 tokens, avg 200, nothing near the 600 cap), but blog bodies
- * are an order of magnitude larger and would blow the cap — at which point
- * `buildSearchTxt` truncates silently and the tail of every post becomes
- * unsearchable with no error anywhere. The excerpt is the searchable summary.
- */
 export declare function withBlogSearchTxt<T extends Partial<BlogPostDocument>>(p: T): T;
-/** reviews — title, comment, productTitle. `userName` is PII and excluded. */
 export declare function withReviewSearchTxt<T extends Partial<ReviewDocument>>(p: T): T;

package/dist/seed/_helpers/search-txt-wrappers.js

@@ -1,73 +1,13 @@
-import { buildSearchTxt } from "../../utils/search-txt";
-/**
- * Per-collection `searchTxt` derivation for seed data.
- *
- * Applied to the WHOLE array at each file's export, never per record. Writing
- * the field inside object literals is how five product seed files shipped their
- * last fixture — the sold/depleted row — with no tokens at all: the field was
- * added to every record except the one appended at the bottom. The `...p` spread
- * comes FIRST here so a record cannot override or omit it.
- *
- * All of these are pure functions of the record's own content, so they do not
- * reintroduce the `appkit-seed` idempotency problem of Root Cause #25.
- *
- * 🛑 **No PII in any of these.** `searchTxt` stores readable fragments of the
- * source text, so feeding it an encrypted field would undo the encryption.
- * Decision D1: names stay searchable, emails/phones/addresses do not.
- *
- * Each wrapper is typed against its own document rather than a shared
- * `Record<string, unknown>`: that shape trips `audit-unknown-leakage`, and more
- * importantly it would silently accept a field that no longer exists after a
- * rename, which is exactly the class of drift this migration is fixing.
- */
-const stripHtml = (s) => (s ?? "").replace(/<[^>]+>/g, " ");
-/** stores — name, description, category. No payout details, no contact. */
+import { buildStoreSearchTxt, buildEventSearchTxt, buildBlogSearchTxt, buildReviewSearchTxt, } from "../../utils/search-txt-builders";
 export function withStoreSearchTxt(p) {
-    return {
-        ...p,
-        searchTxt: buildSearchTxt([
-            p.storeName,
-            stripHtml(p.storeDescription),
-            p.storeCategory,
-        ]),
-    };
+    return { ...p, searchTxt: buildStoreSearchTxt(p) };
 }
-/** events — title, description, type, tags. */
 export function withEventSearchTxt(p) {
-    return {
-        ...p,
-        searchTxt: buildSearchTxt([
-            p.title,
-            stripHtml(p.description),
-            p.type,
-            p.tags ?? [],
-        ]),
-    };
+    return { ...p, searchTxt: buildEventSearchTxt(p) };
 }
-/**
- * blogPosts — title, excerpt, category, tags.
- *
- * The full `content` body is deliberately EXCLUDED. FAQ answers are short
- * (measured: max 449 tokens, avg 200, nothing near the 600 cap), but blog bodies
- * are an order of magnitude larger and would blow the cap — at which point
- * `buildSearchTxt` truncates silently and the tail of every post becomes
- * unsearchable with no error anywhere. The excerpt is the searchable summary.
- */
 export function withBlogSearchTxt(p) {
-    return {
-        ...p,
-        searchTxt: buildSearchTxt([
-            p.title,
-            stripHtml(p.excerpt),
-            p.category,
-            p.tags ?? [],
-        ]),
-    };
+    return { ...p, searchTxt: buildBlogSearchTxt(p) };
 }
-/** reviews — title, comment, productTitle. `userName` is PII and excluded. */
 export function withReviewSearchTxt(p) {
-    return {
-        ...p,
-        searchTxt: buildSearchTxt([p.title, stripHtml(p.comment), p.productTitle]),
-    };
+    return { ...p, searchTxt: buildReviewSearchTxt(p) };
 }

package/dist/utils/search-txt-builders.d.ts

@@ -0,0 +1,23 @@
+import type { ProductDocument } from "../features/products/schemas/firestore";
+import type { StoreDocument } from "../features/stores/schemas/firestore";
+import type { EventDocument } from "../features/events/schemas/firestore";
+import type { BlogPostDocument } from "../features/blog/schemas/firestore";
+import type { ReviewDocument } from "../features/reviews/schemas/firestore";
+/** products — title, description, brand, taxonomy, condition, card/grading, specs. */
+export declare function buildProductSearchTxt(p: Partial<ProductDocument>): string[];
+/** stores — name, description, category. No payout details, no contact. */
+export declare function buildStoreSearchTxt(s: Partial<StoreDocument>): string[];
+/** events — title, description, type, tags. */
+export declare function buildEventSearchTxt(e: Partial<EventDocument>): string[];
+/**
+ * blogPosts — title, excerpt, category, tags.
+ *
+ * The full `content` body is deliberately EXCLUDED. FAQ answers are short
+ * (measured: max 449 tokens against a 600 cap), but blog bodies are an order of
+ * magnitude larger and would blow it — at which point `buildSearchTxt`
+ * truncates SILENTLY and the tail of every post becomes unsearchable with no
+ * error anywhere. The excerpt is the searchable summary.
+ */
+export declare function buildBlogSearchTxt(b: Partial<BlogPostDocument>): string[];
+/** reviews — title, comment, productTitle. `userName` is PII and excluded. */
+export declare function buildReviewSearchTxt(r: Partial<ReviewDocument>): string[];

package/dist/utils/search-txt-builders.js

@@ -0,0 +1,86 @@
+/*
+ * WHY: One definition per collection of "which fields feed searchTxt".
+ *
+ *      There were THREE copies of the products derivation — the repository's
+ *      `buildProductSearchTxt` (12 sources), the seed wrapper
+ *      `withProductSearchTxt` (9), and `backfill-search-txt.mjs` (9) — and two
+ *      of them were missing the same three fields. Nothing could catch it:
+ *      each copy is valid TypeScript producing a valid token array, and a
+ *      document indexed under fewer tokens is not an error, just unfindable by
+ *      the terms nobody derived.
+ *
+ *      This module is the write-path definition. The repository calls it, the
+ *      seed wrapper calls it, and `backfill-search-txt.mjs` MIRRORS it — the
+ *      script must keep its own copy because it has to run against a checkout
+ *      whose appkit/dist is stale, so `audit-search-parity` cross-checks the
+ *      two rather than trusting them to agree.
+ *
+ * WHAT: Pure functions, document-shape in, token-array out. No Firestore, no
+ *       repository, no seed import — so every layer can share them without
+ *       dragging firebase-admin into a bundle that must not have it.
+ *
+ * 🛑 NEVER feed PII in here. `searchTxt` stores readable fragments of the source
+ *    text, so indexing an encrypted field would undo the encryption (D1).
+ *    `reviews.userName` is encrypted and is deliberately absent below.
+ *
+ * @tag domain:search
+ * @tag layer:util
+ * @tag access:isomorphic
+ */
+import { buildSearchTxt } from "./search-txt";
+const stripHtml = (s) => (s ?? "").replace(/<[^>]+>/g, " ");
+/** products — title, description, brand, taxonomy, condition, card/grading, specs. */
+export function buildProductSearchTxt(p) {
+    return buildSearchTxt([
+        p.title,
+        p.description,
+        p.brand,
+        p.brandSlug,
+        p.categoryNames,
+        p.tags,
+        p.features,
+        p.condition,
+        p.card?.setName,
+        p.card?.cardNumber,
+        p.grading?.service,
+        p.specifications?.map((s) => `${s.name} ${s.value}`),
+    ]);
+}
+/** stores — name, description, category. No payout details, no contact. */
+export function buildStoreSearchTxt(s) {
+    return buildSearchTxt([
+        s.storeName,
+        stripHtml(s.storeDescription),
+        s.storeCategory,
+    ]);
+}
+/** events — title, description, type, tags. */
+export function buildEventSearchTxt(e) {
+    return buildSearchTxt([
+        e.title,
+        stripHtml(e.description),
+        e.type,
+        e.tags ?? [],
+    ]);
+}
+/**
+ * blogPosts — title, excerpt, category, tags.
+ *
+ * The full `content` body is deliberately EXCLUDED. FAQ answers are short
+ * (measured: max 449 tokens against a 600 cap), but blog bodies are an order of
+ * magnitude larger and would blow it — at which point `buildSearchTxt`
+ * truncates SILENTLY and the tail of every post becomes unsearchable with no
+ * error anywhere. The excerpt is the searchable summary.
+ */
+export function buildBlogSearchTxt(b) {
+    return buildSearchTxt([
+        b.title,
+        stripHtml(b.excerpt),
+        b.category,
+        b.tags ?? [],
+    ]);
+}
+/** reviews — title, comment, productTitle. `userName` is PII and excluded. */
+export function buildReviewSearchTxt(r) {
+    return buildSearchTxt([r.title, stripHtml(r.comment), r.productTitle]);
+}

package/dist/utils/search-txt-query.d.ts

@@ -0,0 +1,42 @@
+export interface SearchTxtPlan {
+    /** The single term to push down as `array-contains`, or null for no search. */
+    head: string | null;
+    /** Terms to AND-refine in memory after the query returns. */
+    rest: string[];
+    /**
+     * True when the caller supplied a search string that yielded no usable term.
+     * The caller MUST return an empty page rather than an unfiltered one.
+     */
+    empty: boolean;
+}
+/**
+ * Split a raw search string into the pushdown term and the refine terms.
+ * `parseSearchTxtQuery` already orders longest-first — the cheapest proxy for
+ * "narrows the most" without cardinality stats.
+ */
+export declare function planSearchTxt(search: string | undefined | null): SearchTxtPlan;
+/** An empty page, shaped like a Sieve result. */
+export declare function emptySearchResult<T>(): {
+    items: T[];
+    total: number;
+    page: number;
+    pageSize: number;
+    totalPages: number;
+    hasMore: boolean;
+};
+/**
+ * AND-refine the remaining terms over an already-fetched page.
+ *
+ * `total` becomes a FLOOR once rows are dropped after the page was cut — it
+ * counts this page only. That is the known post-pagination-filter debt, not a
+ * new invention: reporting the pre-filter total would promise pages that render
+ * empty.
+ */
+export declare function refineSearchTxt<T extends {
+    searchTxt?: string[];
+}, R extends {
+    items: T[];
+    total: number;
+    totalPages: number;
+    hasMore: boolean;
+}>(result: R, rest: string[]): R;

package/dist/utils/search-txt-query.js

@@ -0,0 +1,61 @@
+/*
+ * WHY: The READ half of searchTxt, in one place.
+ *
+ *      Firestore permits ONE array operator per query, so token search is
+ *      always the same two-step shape: the most selective term becomes an
+ *      `array-contains` clause, and the remaining terms are AND-refined over
+ *      the returned page. faqs and products each hand-rolled it, and the
+ *      products copy carried a comment promising the refine for a long time
+ *      while nothing refined anything — so "red dranzer" returned everything
+ *      matching "dranzer".
+ *
+ *      Two rules are easy to get wrong independently, and both fail silently:
+ *
+ *        - `array-contains-any` instead of `array-contains` makes a multi-word
+ *          search an OR, which reads as "search does nothing".
+ *        - a query that produced NO usable term must return NOTHING. Falling
+ *          through to an unfiltered list means a 1-character search returns the
+ *          whole collection, which also reads as "search does nothing".
+ *
+ * @tag domain:search
+ * @tag layer:util
+ * @tag access:isomorphic
+ */
+import { matchesAllSearchTerms, parseSearchTxtQuery } from "./search-txt";
+/**
+ * Split a raw search string into the pushdown term and the refine terms.
+ * `parseSearchTxtQuery` already orders longest-first — the cheapest proxy for
+ * "narrows the most" without cardinality stats.
+ */
+export function planSearchTxt(search) {
+    const raw = (search ?? "").trim();
+    const terms = parseSearchTxtQuery(raw);
+    if (terms.length === 0) {
+        return { head: null, rest: [], empty: raw.length > 0 };
+    }
+    return { head: terms[0], rest: terms.slice(1), empty: false };
+}
+/** An empty page, shaped like a Sieve result. */
+export function emptySearchResult() {
+    return { items: [], total: 0, page: 1, pageSize: 0, totalPages: 0, hasMore: false };
+}
+/**
+ * AND-refine the remaining terms over an already-fetched page.
+ *
+ * `total` becomes a FLOOR once rows are dropped after the page was cut — it
+ * counts this page only. That is the known post-pagination-filter debt, not a
+ * new invention: reporting the pre-filter total would promise pages that render
+ * empty.
+ */
+export function refineSearchTxt(result, rest) {
+    if (rest.length === 0)
+        return result;
+    const items = result.items.filter((row) => matchesAllSearchTerms(row.searchTxt, rest));
+    return {
+        ...result,
+        items,
+        total: items.length,
+        totalPages: items.length === 0 ? 0 : 1,
+        hasMore: false,
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mohasinac/appkit",
-  "version": "4.30.2",
+  "version": "4.30.4",
   "license": "MIT",
   "publishConfig": {
     "access": "public"