@mohasinac/appkit 4.44.0 → 4.45.0

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

@@ -27,7 +27,9 @@
  * @tag layer:util
  * @tag access:isomorphic
  */
-import { buildSearchTxt } from "./search-txt";
+import { buildSearchTxt } from "./search-txt.js";
+import { aliasVariantsForName } from "../_internal/shared/search/alias-variants.js";
+import { physicalLocationTokens } from "./physical-location.js";
 const stripHtml = (s) => (s ?? "").replace(/<[^>]+>/g, " ");
 /** products — title, description, brand, taxonomy, condition, card/grading, specs. */
 export function buildProductSearchTxt(p) {
@@ -44,6 +46,39 @@ export function buildProductSearchTxt(p) {
         p.card?.cardNumber,
         p.grading?.service,
         p.specifications?.map((s) => `${s.name} ${s.value}`),
+        /*
+         * The warehouse location — C4, and this one line is what makes the hard
+         * direction work.
+         *
+         * "Where is item X" was already answerable from the Location column.
+         * "What is in bin A-3" had **no mechanism at all**: `physicalLocation` was
+         * absent from the products Sieve config, from `PRODUCT_INDEXED_FIELDS`,
+         * from the seller search field list and from this builder — so a seller
+         * could set a location and then never query it.
+         *
+         * 🛑 Indexed as TOKENS rather than queried as a field. A
+         * `physicalLocation.bin == "3"` clause needs its own composite index per
+         * sort field, and the `FAILED_PRECONDITION` would be swallowed into an
+         * empty page (Root Cause #59). `searchTxt` is already
+         * `array-contains`-indexed, so this is more tokens in an existing index
+         * and **no new index** — and it gives both directions through the one
+         * search box the seller already uses.
+         *
+         * See `physicalLocationTokens` for how the match really happens: the
+         * query tokeniser applies the same normaliser as the index, so the PARTS
+         * AND-refine and the separators are irrelevant on both sides.
+         */
+        physicalLocationTokens(p.physicalLocation),
+        /*
+         * Misspelling variants of the TITLE only — last, so they are what the
+         * 600-token cap drops first.
+         *
+         * 🛑 Title only, not `description`. A 300-word body would generate
+         * hundreds of variants and push the real tokens off the end, making exact
+         * search worse to make misspelled search better. The title is what buyers
+         * mistype; prose is what they read.
+         */
+        aliasVariantsForName(p.title ?? ""),
     ]);
 }
 /**
@@ -80,6 +115,22 @@ export function buildCategorySearchTxt(c) {
          * ahead of "also known as" spellings.
          */
         ...(c.aliases ?? []),
+        /*
+         * Mechanical misspelling variants, after the authored aliases for the same
+         * truncation reason: a human-written alias is evidence, a generated one is
+         * a guess, and the guess is what should fall off the end first.
+         *
+         * 🛑 This is what makes "dragon g" find "Dragoon G". Measured against the
+         * built helper: `buildSearchTxt(["Dragoon G"])` yields
+         * `dragoon d dr dra drag drago dragoo g`, and "dragon" is in that set
+         * NOWHERE — it is not a prefix of "dragoon", the two diverge at the sixth
+         * character. Prefix n-grams cannot reach it; an alias can.
+         *
+         * Generated from the NAME and the authored aliases only — deliberately not
+         * from `description` or `path`, which would spend the token budget varying
+         * prose nobody searches by spelling.
+         */
+        ...aliasVariantsForName([c.name, ...(c.aliases ?? [])].filter(Boolean).join(" ")),
     ]);
 }
 /** stores — name, description, category. No payout details, no contact. */
@@ -135,6 +186,15 @@ export function buildOrderSearchTxt(o) {
         o.storeName,
         o.trackingNumber,
         (o.items ?? []).map((i) => i.productTitle),
+        /*
+         * The pick/pack location — C4, same mechanism as the product side.
+         *
+         * `OrderDocument` carries `physicalLocation` too (it is where the parcel
+         * is staged), and the seller bulk-sets it from the orders list. Without
+         * this a seller could file an order to a bin and then not search for it,
+         * which is the same half-built state the product side was in.
+         */
+        physicalLocationTokens(o.physicalLocation),
     ]);
 }
 /** coupons — code, name, description. Nothing here is PII. */

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

@@ -25,12 +25,47 @@ export declare function emptySearchResult<T>(): {
     hasMore: boolean;
 };
 /**
- * AND-refine the remaining terms over an already-fetched page.
+ * How many rows a multi-term search fetches before refining — D2, Fix 2.
  *
- * `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.
+ * 🛑 This is the number that makes multi-word search paginate at all, and it is
+ * capped rather than unbounded for Rule #6: one bounded read, never a scan that
+ * grows with the collection. 250 is the same ceiling the availability fan-out
+ * uses (`PUBLIC_PRODUCT_MAX_PAGE_SIZE` × 5 clauses), for the same reason — it is
+ * what a single Firestore page can return without becoming a cost.
+ */
+export declare const SEARCH_REFINE_WINDOW = 250;
+/**
+ * AND-refine the remaining terms, then slice the requested page out.
+ *
+ * ## 🛑 The bug this closes: multi-word search lied about its own totals
+ *
+ * This used to filter the ALREADY-PAGINATED page and then set
+ * `total = items.length`, `totalPages = 0|1`, `hasMore = false`. Two
+ * consequences, both silent:
+ *
+ *   1. A two-word query could only ever return matches that happened to fall
+ *      inside one 50-row window. Rows 51+ that matched both terms were
+ *      unreachable — not on page 2, not anywhere, because `hasMore` said there
+ *      was no page 2.
+ *   2. The pager actively asserted completeness. A search returning 7 of 40
+ *      real matches reported "7 results" and disabled Next.
+ *
+ * Both render as plausible results with a 200, which is why neither was
+ * reported: a search that returns seven relevant rows looks like it worked.
+ *
+ * ## The fix, and its honest cost
+ *
+ * The caller over-fetches a bounded WINDOW (`SEARCH_REFINE_WINDOW`), this
+ * function refines over it and then slices the requested page. So page 2 of a
+ * two-word search exists, and `total` is the refined count over the window
+ * rather than over one page.
+ *
+ * 🛑 `truncated` is NOT optional, and it is the part that keeps this honest.
+ * When the window saturated, the refined `total` is a FLOOR, not a total — the
+ * same situation the availability queries document — so the renderer must show
+ * it as "50+" and `totalPages` must offer one more page rather than claiming a
+ * false last one. Reporting a saturated window as an exact total is the defect
+ * above with a bigger number.
  */
 export declare function refineSearchTxt<T extends {
     searchTxt?: string[];
@@ -39,4 +74,17 @@ export declare function refineSearchTxt<T extends {
     total: number;
     totalPages: number;
     hasMore: boolean;
-}>(result: R, rest: string[]): R;
+}>(result: R, rest: string[], 
+/**
+ * Supply these to get real pagination. Omitted, the behaviour is the old
+ * page-only refine — kept so the eleven existing callers are byte-identical
+ * until each is converted, rather than all of them changing at once.
+ */
+opts?: {
+    page: number;
+    pageSize: number;
+    /** True when the fetch returned a full window, so more may exist. */
+    windowSaturated: boolean;
+}): R & {
+    truncated?: boolean;
+};

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

@@ -21,7 +21,7 @@
  * @tag layer:util
  * @tag access:isomorphic
  */
-import { matchesAllSearchTerms, parseSearchTxtQuery } from "./search-txt";
+import { matchesAllSearchTerms, parseSearchTxtQuery } from "./search-txt.js";
 /**
  * Split a raw search string into the pushdown term and the refine terms.
  * `parseSearchTxtQuery` already orders longest-first — the cheapest proxy for
@@ -40,22 +40,90 @@ 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.
+ * How many rows a multi-term search fetches before refining — D2, Fix 2.
  *
- * `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.
+ * 🛑 This is the number that makes multi-word search paginate at all, and it is
+ * capped rather than unbounded for Rule #6: one bounded read, never a scan that
+ * grows with the collection. 250 is the same ceiling the availability fan-out
+ * uses (`PUBLIC_PRODUCT_MAX_PAGE_SIZE` × 5 clauses), for the same reason — it is
+ * what a single Firestore page can return without becoming a cost.
  */
-export function refineSearchTxt(result, rest) {
+export const SEARCH_REFINE_WINDOW = 250;
+/**
+ * AND-refine the remaining terms, then slice the requested page out.
+ *
+ * ## 🛑 The bug this closes: multi-word search lied about its own totals
+ *
+ * This used to filter the ALREADY-PAGINATED page and then set
+ * `total = items.length`, `totalPages = 0|1`, `hasMore = false`. Two
+ * consequences, both silent:
+ *
+ *   1. A two-word query could only ever return matches that happened to fall
+ *      inside one 50-row window. Rows 51+ that matched both terms were
+ *      unreachable — not on page 2, not anywhere, because `hasMore` said there
+ *      was no page 2.
+ *   2. The pager actively asserted completeness. A search returning 7 of 40
+ *      real matches reported "7 results" and disabled Next.
+ *
+ * Both render as plausible results with a 200, which is why neither was
+ * reported: a search that returns seven relevant rows looks like it worked.
+ *
+ * ## The fix, and its honest cost
+ *
+ * The caller over-fetches a bounded WINDOW (`SEARCH_REFINE_WINDOW`), this
+ * function refines over it and then slices the requested page. So page 2 of a
+ * two-word search exists, and `total` is the refined count over the window
+ * rather than over one page.
+ *
+ * 🛑 `truncated` is NOT optional, and it is the part that keeps this honest.
+ * When the window saturated, the refined `total` is a FLOOR, not a total — the
+ * same situation the availability queries document — so the renderer must show
+ * it as "50+" and `totalPages` must offer one more page rather than claiming a
+ * false last one. Reporting a saturated window as an exact total is the defect
+ * above with a bigger number.
+ */
+export function refineSearchTxt(result, rest, 
+/**
+ * Supply these to get real pagination. Omitted, the behaviour is the old
+ * page-only refine — kept so the eleven existing callers are byte-identical
+ * until each is converted, rather than all of them changing at once.
+ */
+opts) {
     if (rest.length === 0)
         return result;
-    const items = result.items.filter((row) => matchesAllSearchTerms(row.searchTxt, rest));
+    const matched = result.items.filter((row) => matchesAllSearchTerms(row.searchTxt, rest));
+    if (!opts) {
+        /*
+         * The legacy shape. `total` is this page's count — a floor — and
+         * `hasMore: false` is the known post-pagination-filter debt this function
+         * carried from the start. Preserved verbatim for unconverted callers.
+         */
+        return {
+            ...result,
+            items: matched,
+            total: matched.length,
+            totalPages: matched.length === 0 ? 0 : 1,
+            hasMore: false,
+        };
+    }
+    const page = Math.max(1, Math.floor(opts.page) || 1);
+    const pageSize = Math.max(1, Math.floor(opts.pageSize) || 1);
+    const start = (page - 1) * pageSize;
+    const items = matched.slice(start, start + pageSize);
+    /*
+     * 🛑 A saturated window means `matched.length` is a FLOOR. `totalPages` then
+     * offers `page + 1` rather than the floor's own last page, so the reader can
+     * go and look — exactly the convention the availability queries use, where
+     * claiming a false last page is worse than admitting the ceiling.
+     */
+    const truncated = opts.windowSaturated;
+    const exactPages = Math.ceil(matched.length / pageSize);
     return {
         ...result,
         items,
-        total: items.length,
-        totalPages: items.length === 0 ? 0 : 1,
-        hasMore: false,
+        total: matched.length,
+        totalPages: truncated ? Math.max(exactPages, page + 1) : exactPages,
+        hasMore: truncated ? true : start + items.length < matched.length,
+        ...(truncated ? { truncated: true } : {}),
     };
 }

package/dist/utils/sieve-builder.js

@@ -62,4 +62,4 @@ export function expandSieveParam(field, value, op = SIEVE_OP.EQ) {
 export function sieveAnd(...clauses) {
     return clauses.filter(Boolean).join(",");
 }
-export { sortBy } from "../constants/sort";
+export { sortBy } from "../constants/sort.js";

package/dist/utils/string.formatter.js

@@ -1,7 +1,7 @@
 /**
  * String Formatting and Manipulation Utilities
  */
-import { normalizeError } from "../errors/normalize";
+import { normalizeError } from "../errors/normalize.js";
 export function capitalize(str) {
     return str.charAt(0).toUpperCase() + str.slice(1).toLowerCase();
 }

package/dist/validation/ZodSetup.js

@@ -1,6 +1,6 @@
 "use client";
 import { useEffect } from "react";
-import { setupZodErrorMap } from "./zod-error-map";
+import { setupZodErrorMap } from "./zod-error-map.js";
 export function ZodSetup(_props) {
     setupZodErrorMap();
     useEffect(() => {

package/dist/validation/index.js

@@ -1,8 +1,8 @@
-export { paginationQuerySchema, objectIdSchema, urlSchema, mediaUrlSchema, dateStringSchema, passwordSchema, phoneSchema, emailSchema, resetPasswordSchema, sendVerificationSchema, addPhoneSchema, verifyPhoneSchema, deleteAccountSchema, changePasswordSchema, cropDataSchema, trimDataSchema, validateRequestBody, formatZodErrors, } from "./schemas";
-export { zodErrorMap, setupZodErrorMap } from "./zod-error-map";
-export { ZodSetup } from "./ZodSetup";
-export * from "./email.validator";
-export * from "./password.validator";
-export * from "./phone.validator";
-export * from "./url.validator";
-export * from "./input.validator";
+export { paginationQuerySchema, objectIdSchema, urlSchema, mediaUrlSchema, dateStringSchema, passwordSchema, phoneSchema, emailSchema, resetPasswordSchema, sendVerificationSchema, addPhoneSchema, verifyPhoneSchema, deleteAccountSchema, changePasswordSchema, cropDataSchema, trimDataSchema, validateRequestBody, formatZodErrors, } from "./schemas.js";
+export { zodErrorMap, setupZodErrorMap } from "./zod-error-map.js";
+export { ZodSetup } from "./ZodSetup.js";
+export * from "./email.validator.js";
+export * from "./password.validator.js";
+export * from "./phone.validator.js";
+export * from "./url.validator.js";
+export * from "./input.validator.js";

package/dist/validation/phone.validator.js

@@ -1,7 +1,7 @@
 /**
  * Phone Number Validation Utilities
  */
-import { getDefaultCountry, getDefaultPhonePrefix, } from "../core/baseline-resolver";
+import { getDefaultCountry, getDefaultPhonePrefix, } from "../core/baseline-resolver.js";
 export function isValidPhone(phone) {
     const phoneRegex = /^\+?[\d\s-()]+$/;
     const cleaned = phone.replace(/[\s-()]/g, "");

package/dist/validation/schemas.d.ts

@@ -142,9 +142,9 @@ export declare const cropDataSchema: z.ZodEffects<z.ZodEffects<z.ZodEffects<z.Zo
     aspectRatio?: string | undefined;
     minHeight?: number | undefined;
     minWidth?: number | undefined;
-    quality?: number | undefined;
     outputFormat?: "webp" | "png" | "jpeg" | undefined;
     rotation?: number | undefined;
+    quality?: number | undefined;
     outputFolder?: string | undefined;
 }, {
     height: number;
@@ -155,9 +155,9 @@ export declare const cropDataSchema: z.ZodEffects<z.ZodEffects<z.ZodEffects<z.Zo
     aspectRatio?: string | undefined;
     minHeight?: number | undefined;
     minWidth?: number | undefined;
-    quality?: number | undefined;
     outputFormat?: "webp" | "png" | "jpeg" | undefined;
     rotation?: number | undefined;
+    quality?: number | undefined;
     outputFolder?: string | undefined;
 }>, {
     height: number;
@@ -168,9 +168,9 @@ export declare const cropDataSchema: z.ZodEffects<z.ZodEffects<z.ZodEffects<z.Zo
     aspectRatio?: string | undefined;
     minHeight?: number | undefined;
     minWidth?: number | undefined;
-    quality?: number | undefined;
     outputFormat?: "webp" | "png" | "jpeg" | undefined;
     rotation?: number | undefined;
+    quality?: number | undefined;
     outputFolder?: string | undefined;
 }, {
     height: number;
@@ -181,9 +181,9 @@ export declare const cropDataSchema: z.ZodEffects<z.ZodEffects<z.ZodEffects<z.Zo
     aspectRatio?: string | undefined;
     minHeight?: number | undefined;
     minWidth?: number | undefined;
-    quality?: number | undefined;
     outputFormat?: "webp" | "png" | "jpeg" | undefined;
     rotation?: number | undefined;
+    quality?: number | undefined;
     outputFolder?: string | undefined;
 }>, {
     height: number;
@@ -194,9 +194,9 @@ export declare const cropDataSchema: z.ZodEffects<z.ZodEffects<z.ZodEffects<z.Zo
     aspectRatio?: string | undefined;
     minHeight?: number | undefined;
     minWidth?: number | undefined;
-    quality?: number | undefined;
     outputFormat?: "webp" | "png" | "jpeg" | undefined;
     rotation?: number | undefined;
+    quality?: number | undefined;
     outputFolder?: string | undefined;
 }, {
     height: number;
@@ -207,9 +207,9 @@ export declare const cropDataSchema: z.ZodEffects<z.ZodEffects<z.ZodEffects<z.Zo
     aspectRatio?: string | undefined;
     minHeight?: number | undefined;
     minWidth?: number | undefined;
-    quality?: number | undefined;
     outputFormat?: "webp" | "png" | "jpeg" | undefined;
     rotation?: number | undefined;
+    quality?: number | undefined;
     outputFolder?: string | undefined;
 }>, {
     height: number;
@@ -220,9 +220,9 @@ export declare const cropDataSchema: z.ZodEffects<z.ZodEffects<z.ZodEffects<z.Zo
     aspectRatio?: string | undefined;
     minHeight?: number | undefined;
     minWidth?: number | undefined;
-    quality?: number | undefined;
     outputFormat?: "webp" | "png" | "jpeg" | undefined;
     rotation?: number | undefined;
+    quality?: number | undefined;
     outputFolder?: string | undefined;
 }, {
     height: number;
@@ -233,9 +233,9 @@ export declare const cropDataSchema: z.ZodEffects<z.ZodEffects<z.ZodEffects<z.Zo
     aspectRatio?: string | undefined;
     minHeight?: number | undefined;
     minWidth?: number | undefined;
-    quality?: number | undefined;
     outputFormat?: "webp" | "png" | "jpeg" | undefined;
     rotation?: number | undefined;
+    quality?: number | undefined;
     outputFolder?: string | undefined;
 }>;
 export declare const trimDataSchema: z.ZodEffects<z.ZodObject<{
@@ -249,29 +249,29 @@ export declare const trimDataSchema: z.ZodEffects<z.ZodObject<{
     startTime: number;
     endTime: number;
     sourceUrl: string;
-    quality?: "medium" | "high" | "low" | undefined;
     outputFormat?: "mp4" | "webm" | undefined;
+    quality?: "medium" | "high" | "low" | undefined;
     outputFolder?: string | undefined;
 }, {
     startTime: number;
     endTime: number;
     sourceUrl: string;
-    quality?: "medium" | "high" | "low" | undefined;
     outputFormat?: "mp4" | "webm" | undefined;
+    quality?: "medium" | "high" | "low" | undefined;
     outputFolder?: string | undefined;
 }>, {
     startTime: number;
     endTime: number;
     sourceUrl: string;
-    quality?: "medium" | "high" | "low" | undefined;
     outputFormat?: "mp4" | "webm" | undefined;
+    quality?: "medium" | "high" | "low" | undefined;
     outputFolder?: string | undefined;
 }, {
     startTime: number;
     endTime: number;
     sourceUrl: string;
-    quality?: "medium" | "high" | "low" | undefined;
     outputFormat?: "mp4" | "webm" | undefined;
+    quality?: "medium" | "high" | "low" | undefined;
     outputFolder?: string | undefined;
 }>;
 export declare function validateRequestBody<T>(schema: z.ZodSchema<T>, body: unknown): {

package/dist/validation/schemas.js

@@ -11,7 +11,7 @@ export const paginationQuerySchema = z.object({
 });
 export const objectIdSchema = z.string().regex(/^[a-z0-9-]+$/);
 export const urlSchema = z.string().url().max(2048);
-import { isStoredMediaRef, MEDIA_URL_MAX_LENGTH, MEDIA_URL_MESSAGE, } from "../utils/media-url";
+import { isStoredMediaRef, MEDIA_URL_MAX_LENGTH, MEDIA_URL_MESSAGE, } from "../utils/media-url.js";
 /**
  * A media reference we are willing to PERSIST.
  *

package/dist/validation/url.validator.js

@@ -1,7 +1,7 @@
 /**
  * URL Validation Utilities
  */
-import { normalizeError } from "../errors/normalize";
+import { normalizeError } from "../errors/normalize.js";
 export function isValidUrl(url) {
     try {
         new URL(url);

package/dist/values/index.js

@@ -3,4 +3,4 @@
  *
  * Centralized message and constant definitions used across features.
  */
-export { SUCCESS_MESSAGES, INFO_MESSAGES, CONFIRMATION_MESSAGES, } from "./success-messages";
+export { SUCCESS_MESSAGES, INFO_MESSAGES, CONFIRMATION_MESSAGES, } from "./success-messages.js";