@mohasinac/appkit 4.52.5 → 4.53.1

package/dist/features/auth/repository/user.repository.d.ts

@@ -1,11 +1,39 @@
-import type { DocumentSnapshot } from "../../../providers/db-firebase";
+import type { JsonValue } from "../../../schemas/types";
 import { BaseRepository, type FirebaseSieveFields, type FirebaseSieveResult, type SieveModel } from "../../../providers/db-firebase";
 import type { UserRole } from "../types";
-import { type UserDocument } from "../schemas";
+import { type UserDocument, type UserPlain } from "../schemas";
 export declare class UserRepository extends BaseRepository<UserDocument> {
     static readonly SIEVE_FIELDS: FirebaseSieveFields;
     constructor();
-    private decryptUser;
+    /**
+     * Plaintext PII. **Opt-in and named** — for the account's own settings page,
+     * the payout run, and any mail that has to reach the person.
+     */
+    revealUser(doc: UserDocument): UserPlain;
+    /** As `revealUser`, for a list read. */
+    revealUsers(docs: readonly UserDocument[]): UserPlain[];
+    /**
+     * Masked PII — **the default for every admin list and every public
+     * surface.** Decrypts first, then masks, because the mask helpers refuse
+     * ciphertext by design.
+     *
+     * `payoutDetails` and `shippingConfig` are decrypted and then masked
+     * member-by-member: a UPI handle or account number reaching an admin table
+     * unmasked is the most damaging value this document carries.
+     */
+    maskedUser(doc: UserDocument): UserPlain;
+    /** As `maskedUser`, for a list read. */
+    maskedUsers(docs: readonly UserDocument[]): UserPlain[];
+    /**
+     * Mask every string member of an already-decrypted nested object.
+     *
+     * The field list is derived from the object rather than hard-coded, because
+     * `USER_PII_FIELDS` does not name these members and a second list here would
+     * have to be kept in step with `decryptPayoutDetails`'s own (Root Cause #42).
+     * Every string in a payout or shipping block is sensitive, so "all of them"
+     * is the correct list, not an approximation.
+     */
+    private maskNested;
     /**
      * Declared, not hand-rolled.
      *
@@ -19,6 +47,18 @@ export declare class UserRepository extends BaseRepository<UserDocument> {
      */
     protected piiFields: readonly ["email", "phoneNumber", "googleLinkedEmail"];
     protected piiIndexMap: Record<string, string>;
+    /**
+     * Admin search by first/last name or email local-part, without decryption.
+     * `displayName` and `email` only — `phoneNumber` is excluded on purpose: a
+     * phone number has no word boundaries, so tokenising it yields one token
+     * that is the whole number, an exact lookup `phoneIndex` already covers.
+     *
+     * Running through `applyWriteHooks` is what makes a `users` row that
+     * SURVIVES a tester cascade (it is PRESERVE-tier and never wiped) keep a
+     * correct index going forward, and what makes a NEWLY signed-up real user
+     * searchable without anyone having to remember to re-run the backfill.
+     */
+    protected buildTokensIndexFor(data: Record<string, JsonValue>): Record<string, string[]> | null;
     /**
      * The base hook, plus the nested objects it cannot see.
      *
@@ -28,9 +68,8 @@ export declare class UserRepository extends BaseRepository<UserDocument> {
      * that have to agree — which is what the hand-rolled override was.
      */
     protected applyWriteHooks<D extends object>(data: D): D;
-    protected mapDoc<D = UserDocument>(snap: DocumentSnapshot): D;
-    createWithId(id: string, data: Partial<UserDocument>): Promise<UserDocument>;
-    create(input: Omit<UserDocument, "id" | "createdAt" | "updatedAt">): Promise<UserDocument>;
+    createWithId(id: string, data: Partial<UserPlain>): Promise<UserDocument>;
+    create(input: Omit<UserPlain, "id" | "createdAt" | "updatedAt">): Promise<UserDocument>;
     findByUid(uid: string): Promise<UserDocument | null>;
     /**
      * Resolve a public profile slug.
@@ -51,7 +90,7 @@ export declare class UserRepository extends BaseRepository<UserDocument> {
      * Permanent bans (`hardBanExpiresAt` null/absent) never match this query.
      */
     getExpiredHardBans(): Promise<UserDocument[]>;
-    update(uid: string, data: Partial<UserDocument>): Promise<UserDocument>;
+    update(uid: string, data: Partial<UserPlain>): Promise<UserDocument>;
     markEmailAsVerified(uid: string): Promise<UserDocument>;
     disable(uid: string): Promise<UserDocument>;
     enable(uid: string): Promise<UserDocument>;

package/dist/features/auth/repository/user.repository.js

@@ -1,7 +1,8 @@
 import { normalizeError } from "../../../errors/normalize.js";
+import { buildTokensIndex } from "../../../security/blind-index-tokens.js";
 import { DatabaseError } from "../../../errors/index.js";
 import { BaseRepository, getFirestoreCount, prepareForFirestore, parseSieveDateValue, } from "../../../providers/db-firebase/index.js";
-import { USER_PII_FIELDS, USER_PII_INDEX_MAP, decryptPayoutDetails, decryptPiiFields, decryptShippingConfig, encryptPayoutDetails, encryptShippingConfig, piiBlindIndex, } from "../../../security/index.js";
+import { USER_PII_FIELDS, USER_PII_INDEX_MAP, decryptPayoutDetails, maskPii, revealPii, decryptShippingConfig, encryptPayoutDetails, encryptShippingConfig, piiBlindIndex, } from "../../../security/index.js";
 import { USER_COLLECTION, USER_FIELDS, } from "../schemas/index.js";
 export class UserRepository extends BaseRepository {
     constructor() {
@@ -20,15 +21,92 @@ export class UserRepository extends BaseRepository {
         this.piiFields = USER_PII_FIELDS;
         this.piiIndexMap = USER_PII_INDEX_MAP;
     }
-    decryptUser(doc) {
-        const decrypted = decryptPiiFields(doc, [...USER_PII_FIELDS]);
-        if (decrypted.payoutDetails) {
-            decrypted.payoutDetails = decryptPayoutDetails(decrypted.payoutDetails);
+    /*
+     * 🛑 `mapDoc` no longer decrypts. This is the widest-reaching of the
+     * fourteen — 73 files touch this repository — and it is why ciphertext never
+     * leaving the database matters most here: `email` and `phoneNumber` belong
+     * to every account on the platform.
+     *
+     * `payoutDetails` and `shippingConfig` are handled inside the accessors
+     * rather than by `revealPii`, because each is encrypted by its OWN scheme
+     * and not by a `USER_PII_FIELDS` path. An accessor that silently skipped
+     * them would hand a caller a UPI id it could not read — worse than refusing,
+     * because the value looks present.
+     */
+    /**
+     * Plaintext PII. **Opt-in and named** — for the account's own settings page,
+     * the payout run, and any mail that has to reach the person.
+     */
+    revealUser(doc) {
+        const revealed = revealPii(doc, USER_PII_FIELDS);
+        if (revealed.payoutDetails) {
+            revealed.payoutDetails = decryptPayoutDetails(revealed.payoutDetails);
         }
-        if (decrypted.shippingConfig) {
-            decrypted.shippingConfig = decryptShippingConfig(decrypted.shippingConfig);
+        if (revealed.shippingConfig) {
+            revealed.shippingConfig = decryptShippingConfig(revealed.shippingConfig);
         }
-        return decrypted;
+        return revealed;
+    }
+    /** As `revealUser`, for a list read. */
+    revealUsers(docs) {
+        return docs.map((d) => this.revealUser(d));
+    }
+    /**
+     * Masked PII — **the default for every admin list and every public
+     * surface.** Decrypts first, then masks, because the mask helpers refuse
+     * ciphertext by design.
+     *
+     * `payoutDetails` and `shippingConfig` are decrypted and then masked
+     * member-by-member: a UPI handle or account number reaching an admin table
+     * unmasked is the most damaging value this document carries.
+     */
+    maskedUser(doc) {
+        const masked = maskPii(doc, USER_PII_FIELDS);
+        if (masked.payoutDetails) {
+            masked.payoutDetails = this.maskNested(decryptPayoutDetails(masked.payoutDetails));
+        }
+        if (masked.shippingConfig) {
+            masked.shippingConfig = this.maskNested(decryptShippingConfig(masked.shippingConfig));
+        }
+        return masked;
+    }
+    /** As `maskedUser`, for a list read. */
+    maskedUsers(docs) {
+        return docs.map((d) => this.maskedUser(d));
+    }
+    /**
+     * Mask every string member of an already-decrypted nested object.
+     *
+     * The field list is derived from the object rather than hard-coded, because
+     * `USER_PII_FIELDS` does not name these members and a second list here would
+     * have to be kept in step with `decryptPayoutDetails`'s own (Root Cause #42).
+     * Every string in a payout or shipping block is sensitive, so "all of them"
+     * is the correct list, not an approximation.
+     */
+    maskNested(value) {
+        if (!value)
+            return undefined;
+        return maskPii(value, Object.entries(value)
+            .filter(([, v]) => typeof v === "string")
+            .map(([k]) => k));
+    }
+    /**
+     * Admin search by first/last name or email local-part, without decryption.
+     * `displayName` and `email` only — `phoneNumber` is excluded on purpose: a
+     * phone number has no word boundaries, so tokenising it yields one token
+     * that is the whole number, an exact lookup `phoneIndex` already covers.
+     *
+     * Running through `applyWriteHooks` is what makes a `users` row that
+     * SURVIVES a tester cascade (it is PRESERVE-tier and never wiped) keep a
+     * correct index going forward, and what makes a NEWLY signed-up real user
+     * searchable without anyone having to remember to re-run the backfill.
+     */
+    buildTokensIndexFor(data) {
+        const displayName = typeof data.displayName === "string" ? data.displayName : undefined;
+        const email = typeof data.email === "string" ? data.email : undefined;
+        if (!displayName && !email)
+            return null;
+        return { nameTokensIndex: buildTokensIndex(displayName, email) };
     }
     /**
      * The base hook, plus the nested objects it cannot see.
@@ -47,10 +125,11 @@ export class UserRepository extends BaseRepository {
             access.shippingConfig = encryptShippingConfig(access.shippingConfig);
         return out;
     }
-    mapDoc(snap) {
-        const raw = super.mapDoc(snap);
-        return this.decryptUser(raw);
-    }
+    /*
+     * Takes PLAINTEXT, like the base it overrides — the three real signup paths
+     * hand over the email Firebase just gave them, and `applyWriteHooks` below
+     * is what encrypts it.
+     */
     async createWithId(id, data) {
         // `uid` is a required UserDocument field read directly off the mapped
         // object (SessionUser.uid, getServerPermissions(uid), etc.) — mapDoc()
@@ -76,6 +155,7 @@ export class UserRepository extends BaseRepository {
         // request an O(1) lookup). The readable public identifier is `slug`, minted
         // by `reserveUserSlug` from displayName only.
         const id = this.db.collection(this.collection).doc().id;
+        // Plain in, ciphertext out — `applyWriteHooks` encrypts below.
         const userData = {
             ...input,
             createdAt: new Date(),
@@ -86,7 +166,15 @@ export class UserRepository extends BaseRepository {
             .collection(this.collection)
             .doc(id)
             .set(prepareForFirestore(encrypted));
-        return { id, ...userData };
+        /*
+         * Returns what was PERSISTED, not the plaintext input.
+         *
+         * `encrypted` is the exact object just written, so this is both honest and
+         * assignable to the base's `Promise<UserDocument>` — the declaration
+         * previously said `UserDocument` while returning `userData`, the plaintext.
+         * No re-read, so no extra Firestore read (Rule #6).
+         */
+        return { id, ...encrypted };
     }
     async findByUid(uid) {
         return this.findOneBy(USER_FIELDS.UID, uid);
@@ -157,6 +245,11 @@ export class UserRepository extends BaseRepository {
             throw new DatabaseError("Failed to fetch expired hard bans", error);
         }
     }
+    /*
+     * Takes PLAINTEXT, like the base it overrides — this method is the thing
+     * that encrypts (`applyWriteHooks`), so demanding ciphertext from callers
+     * inverted its own contract.
+     */
     async update(uid, data) {
         const encrypted = this.applyWriteHooks(data);
         return super.update(uid, encrypted);
@@ -181,11 +274,22 @@ export class UserRepository extends BaseRepository {
         if (!currentUser) {
             throw new DatabaseError(`User not found: ${uid}`);
         }
+        /*
+          * Plain in, ciphertext out — `this.update` encrypts via the write hook.
+          *
+          * 🛑 The comparison below (`data.email !== currentUser.email`) now
+          * compares PLAINTEXT to CIPHERTEXT, so it is always true and
+          * `emailVerified` is cleared on every profile save that includes an
+          * email — even an unchanged one. `currentUser` comes from `findById`,
+          * which no longer decrypts. Fixed by comparing against the revealed
+          * value, which is the one place in this method that needs plaintext.
+          */
         const updateData = { ...data };
-        if (data.email && data.email !== currentUser.email) {
+        const current = this.revealUser(currentUser);
+        if (data.email && data.email !== current.email) {
             updateData.emailVerified = false;
         }
-        if (data.phoneNumber && data.phoneNumber !== currentUser.phoneNumber) {
+        if (data.phoneNumber && data.phoneNumber !== current.phoneNumber) {
             updateData.phoneVerified = false;
         }
         return this.update(uid, updateData);
@@ -296,6 +400,15 @@ UserRepository.SIEVE_FIELDS = {
     // filter matched every employee. The composite indexes it needs are already
     // declared and deployed — (permissionGroup, role, createdAt|displayName).
     permissionGroup: { canFilter: true, canSort: false },
+    /*
+     * Whole-word admin name search. `canSort: false` — an array field has no
+     * sort order Firestore can express. Without this entry, `@=` (Firestore
+     * `array-contains`) on `nameTokensIndex` is dropped SILENTLY by Sieve
+     * (`throwExceptions: false`), and the clause after it goes with it —
+     * which here would be nothing, but is the exact mechanism Root Cause #62
+     * documents for every other field this has happened to.
+     */
+    nameTokensIndex: { canFilter: true, canSort: false },
     createdAt: { canFilter: true, canSort: true, parseValue: parseSieveDateValue },
     updatedAt: { canFilter: true, canSort: true, parseValue: parseSieveDateValue },
 };

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

@@ -7,6 +7,7 @@
 import type { UserRole } from "../types";
 import type { BannedAction, EmployeeGroup, Permission } from "../permissions/constants";
 import type { BaseDocument } from "../../../_internal/shared/types/base-document";
+import type { Encrypted, Plaintext } from "../../../security/encrypted";
 /**
  * Generic schema defaults for user-related data.
  * Consumer-specific values (admin email, currency) belong in SiteConfig, not here.
@@ -31,6 +32,16 @@ export interface AvatarMetadata {
     };
     zoom: number;
 }
+/**
+ * `UserDocument` with its PII as plain `string` — what the named repository
+ * accessors return, and what a WRITE path accepts (the repository encrypts).
+ *
+ * `Plaintext<T>` is the one definition of this shape; see `security/encrypted.ts`.
+ * It is deliberately NOT distinguishable from a MASKED value — `maskPii`
+ * returns plain strings too, and no type can express "these characters are
+ * asterisks". The distinction is which named method you called.
+ */
+export type UserPlain = Plaintext<UserDocument>;
 export interface UserDocument extends BaseDocument {
     uid: string;
     /**
@@ -52,8 +63,14 @@ export interface UserDocument extends BaseDocument {
      * profile resolution falls back to id and then uid.
      */
     slug?: string;
-    email: string | null;
-    phoneNumber: string | null;
+    /**
+     * PII — CIPHERTEXT at rest, kept true by `UserRepository` no longer
+     * decrypting in `mapDoc`. Readers call `userRepository.maskedUser(doc)` (the
+     * default) or `revealUser(doc)` (opt-in, named, greppable).
+     */
+    email: Encrypted<string> | null;
+    /** PII — ciphertext at rest; see `email`. */
+    phoneNumber: Encrypted<string> | null;
     phoneVerified?: boolean;
     displayName: string | null;
     photoURL: string | null;
@@ -133,7 +150,8 @@ export interface UserDocument extends BaseDocument {
      * exchange rather than the client SDK's linkWithCredential(). */
     googleLinked?: boolean;
     /** The Google account email this profile is linked to, once linked. */
-    googleLinkedEmail?: string | null;
+    /** PII — ciphertext at rest; see `email`. */
+    googleLinkedEmail?: Encrypted<string> | null;
     uiPreferences?: {
         /** IDs of collapsible dashboard sections currently collapsed, flat across
          * every page (IDs are page-prefixed, e.g. "admin-dashboard:alerts", to
@@ -216,13 +234,13 @@ export interface SellerPayoutDetails {
     isConfigured: boolean;
 }
 export declare const USER_COLLECTION: "users";
-export declare const DEFAULT_USER_DATA: Partial<UserDocument>;
+export declare const DEFAULT_USER_DATA: Partial<UserPlain>;
 export declare const USER_INDEXED_FIELDS: readonly ["email", "emailIndex", "phoneNumber", "phoneIndex", "role", "disabled", "emailVerified", "phoneVerified", "storeSlug", "storeStatus", "isTester", "slug"];
 export declare const USER_PUBLIC_FIELDS: readonly ["uid", "displayName", "photoURL", "avatarMetadata", "role", "createdAt", "storeSlug", "publicProfile", "stats"];
 export declare const USER_UPDATABLE_FIELDS: readonly ["displayName", "photoURL"];
 export type UserCreateInput = Omit<UserDocument, "uid" | "id" | "createdAt" | "updatedAt">;
 export type UserUpdateInput = Partial<Pick<UserDocument, "displayName" | "photoURL">>;
-export type UserAdminUpdateInput = Partial<Omit<UserDocument, "uid" | "id" | "createdAt">>;
+export type UserAdminUpdateInput = Partial<Omit<UserPlain, "uid" | "id" | "createdAt">>;
 export interface UserQueryFilter {
     email?: string;
     phoneNumber?: string;
@@ -253,6 +271,8 @@ export declare const USER_FIELDS: {
     readonly DISPLAY_NAME: "displayName";
     readonly EMAIL_INDEX: "emailIndex";
     readonly PHONE_INDEX: "phoneIndex";
+    /** Whole-word HMAC digests of `displayName` + `email`. See `blind-index-tokens.ts`. */
+    readonly NAME_TOKENS_INDEX: "nameTokensIndex";
     readonly PHOTO_URL: "photoURL";
     readonly AVATAR_METADATA: "avatarMetadata";
     readonly ROLE: "role";
@@ -308,18 +328,38 @@ export declare const USER_FIELDS: {
         readonly LOGIN_COUNT: "metadata.loginCount";
     };
 };
+/**
+ * `EmailVerificationTokenDocument` with its PII as plain `string` — what the named repository
+ * accessors return, and what a WRITE path accepts (the repository encrypts).
+ *
+ * `Plaintext<T>` is the one definition of this shape; see `security/encrypted.ts`.
+ * It is deliberately NOT distinguishable from a MASKED value — `maskPii`
+ * returns plain strings too, and no type can express "these characters are
+ * asterisks". The distinction is which named method you called.
+ */
+export type EmailVerificationTokenPlain = Plaintext<EmailVerificationTokenDocument>;
 export type EmailVerificationTokenDocument = {
     id?: string;
     userId: string;
-    email: string;
+    email: Encrypted<string>;
     token: string;
     expiresAt: Date;
     createdAt: Date;
 };
+/**
+ * `PasswordResetTokenDocument` with its PII as plain `string` — what the named repository
+ * accessors return, and what a WRITE path accepts (the repository encrypts).
+ *
+ * `Plaintext<T>` is the one definition of this shape; see `security/encrypted.ts`.
+ * It is deliberately NOT distinguishable from a MASKED value — `maskPii`
+ * returns plain strings too, and no type can express "these characters are
+ * asterisks". The distinction is which named method you called.
+ */
+export type PasswordResetTokenPlain = Plaintext<PasswordResetTokenDocument>;
 export type PasswordResetTokenDocument = {
     id?: string;
     userId: string;
-    email: string;
+    email: Encrypted<string>;
     token: string;
     expiresAt: Date;
     createdAt: Date;
@@ -353,19 +393,32 @@ export declare const TOKEN_FIELDS: {
     readonly USED: "used";
     readonly USED_AT: "usedAt";
 };
+/**
+ * The session shape with its PII as plain `string`.
+ *
+ * Was a hand-written twin, because `Plaintext<T>` un-branded top-level members
+ * only and all three of this document's PII fields are NESTED. Making the
+ * generic recurse removed the twin — which is the better outcome: a
+ * hand-written copy of a derived shape is the drift this whole file's
+ * `*Plain` convention exists to avoid.
+ */
+export type SessionPlain = Plaintext<SessionDocument>;
 export type SessionDocument = {
     id: string;
     userId: string;
     deviceInfo?: {
-        userAgent?: string;
+        /** PII — ciphertext at rest. See `SessionRepository.revealSession`. */
+        userAgent?: Encrypted<string>;
         browser?: string;
         os?: string;
         device?: string;
-        ip?: string;
+        /** PII — ciphertext at rest. */
+        ip?: Encrypted<string>;
     };
     location?: {
         country?: string;
-        city?: string;
+        /** PII — ciphertext at rest. */
+        city?: Encrypted<string>;
     };
     createdAt: Date;
     lastActivity: Date;
@@ -382,7 +435,7 @@ export declare const SESSION_PUBLIC_FIELDS: readonly ["id", "deviceInfo", "locat
 export declare const SESSION_EXPIRATION_MS: number;
 /** 30 days — auto-cleanup threshold */
 export declare const SESSION_CLEANUP_AFTER_MS: number;
-export type SessionCreateInput = Omit<SessionDocument, "id" | "createdAt" | "lastActivity">;
+export type SessionCreateInput = Omit<SessionPlain, "id" | "createdAt" | "lastActivity">;
 export type SessionUpdateInput = {
     lastActivity: Date;
     location?: SessionDocument["location"];
@@ -400,7 +453,7 @@ export declare const sessionQueryHelpers: {
     readonly notExpired: () => readonly ["expiresAt", ">=", Date];
     readonly recentActivity: (since: Date) => readonly ["lastActivity", ">=", Date];
 };
-export declare function parseUserAgent(userAgent: string): SessionDocument["deviceInfo"];
+export declare function parseUserAgent(userAgent: string): SessionPlain["deviceInfo"];
 export declare const SESSION_FIELDS: {
     readonly ID: "id";
     readonly USER_ID: "userId";

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

@@ -24,6 +24,12 @@ export const UserSchemaDefaults = {
     UNKNOWN_USER_AGENT: "Unknown",
 };
 export const USER_COLLECTION = "users";
+/*
+ * The PLAIN shape: this is spread into a brand-new account's payload at
+ * signup, where every value is plaintext and `createWithId` encrypts. Typed
+ * as the document it would have demanded `Encrypted<string>` from all three
+ * signup routes.
+ */
 export const DEFAULT_USER_DATA = {
     role: "user",
     emailVerified: false,
@@ -96,6 +102,8 @@ export const USER_FIELDS = {
     DISPLAY_NAME: "displayName",
     EMAIL_INDEX: "emailIndex",
     PHONE_INDEX: "phoneIndex",
+    /** Whole-word HMAC digests of `displayName` + `email`. See `blind-index-tokens.ts`. */
+    NAME_TOKENS_INDEX: "nameTokensIndex",
     PHOTO_URL: "photoURL",
     AVATAR_METADATA: "avatarMetadata",
     ROLE: "role",
@@ -215,6 +223,11 @@ export const sessionQueryHelpers = {
     notExpired: () => ["expiresAt", ">=", new Date()],
     recentActivity: (since) => ["lastActivity", ">=", since],
 };
+/*
+ * Returns the PLAIN device shape: it parses a raw UA header, so everything it
+ * produces is plaintext and the repository's write hook encrypts it. Declaring
+ * `SessionDocument["deviceInfo"]` claimed the parser emitted ciphertext.
+ */
 export function parseUserAgent(userAgent) {
     const ua = userAgent.toLowerCase();
     const BROWSER_TOKENS = [

package/dist/features/before-after/api/route.js

@@ -33,7 +33,7 @@ export async function GET(request) {
             filters,
             sort,
             page,
-            perPage: pageSize,
+            pageSize: pageSize,
         });
         const totalPages = Math.max(1, Math.ceil(result.total / pageSize));
         return NextResponse.json({

package/dist/features/blog/components/BlogListView.js

@@ -1,7 +1,7 @@
 import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
 import React from "react";
 import Link from "next/link.js";
-import { Article, Button, Div, Grid, Heading, Pagination, Row, Span, Stack, Text } from "../../../ui/index.js";
+import { Article, Div, Grid, Heading, OverflowRow, Pagination, Row, Span, Stack, Text } from "../../../ui/index.js";
 import { MediaImage } from "../../media/MediaImage.js";
 import { getDefaultLocale } from "../../../core/baseline-resolver.js";
 import { getMediaUrl } from "../../media/types/index.js";
@@ -11,7 +11,6 @@ const __P = {
 };
 const __O = {
     hidden: "overflow-hidden",
-    xAuto: "overflow-x-auto",
 };
 const CLS_FEATURED_BADGE = "rounded-full bg-warning-surface px-[var(--appkit-space-2)] py-[var(--appkit-space-0-5)] text-warning dark:bg-warning-surface dark:text-warning";
 export function BlogCard({ post, href, onClick, className = "" }) {
@@ -33,7 +32,21 @@ export function BlogCard({ post, href, onClick, className = "" }) {
     return card;
 }
 export function BlogCategoryTabs({ categories, active, onSelect, labels = {}, }) {
-    return (_jsxs(Div, { layout: "flex", gap: "2", className: `scrollbar-none ${__O.xAuto}`, padding: "b-2xs", children: [_jsx(Button, { onClick: () => onSelect(null), variant: !active ? "primary" : "ghost", size: "sm", className: `whitespace-nowrap rounded-full px-[var(--appkit-space-4)] py-[var(--appkit-space-1-5)] text-[length:var(--appkit-text-sm)] font-medium transition ${!active ? "bg-neutral-900 text-white" : "bg-[var(--appkit-color-surface)] bg-[var(--appkit-color-surface-elevated)] text-[var(--appkit-color-text-muted)] text-[var(--appkit-color-text-muted)] hover:bg-surface-hover"}`, children: labels.all ?? "All" }), categories.map((cat) => (_jsx(Button, { onClick: () => onSelect(cat), variant: active === cat ? "primary" : "ghost", size: "sm", className: `whitespace-nowrap rounded-full px-[var(--appkit-space-4)] py-[var(--appkit-space-1-5)] text-[length:var(--appkit-text-sm)] font-medium capitalize transition ${active === cat ? "bg-neutral-900 text-white" : "bg-[var(--appkit-color-surface)] bg-[var(--appkit-color-surface-elevated)] text-[var(--appkit-color-text-muted)] text-[var(--appkit-color-text-muted)] hover:bg-surface-hover"}`, children: labels[cat] ?? cat }, cat)))] }));
+    /*
+     * `ALL_ID` is a sentinel, not a category. It cannot be `""` because that is
+     * also `OverflowRow`'s "nothing selected" state, which would leave the
+     * collapsed trigger showing the placeholder instead of "All".
+     */
+    const ALL_ID = "__all__";
+    const items = [
+        { id: ALL_ID, label: labels.all ?? "All", onSelect: () => onSelect(null) },
+        ...categories.map((cat) => ({
+            id: cat,
+            label: labels[cat] ?? cat,
+            onSelect: () => onSelect(cat),
+        })),
+    ];
+    return (_jsx(OverflowRow, { items: items, ariaLabel: "Blog categories", activeId: active ?? ALL_ID, searchPlaceholder: "Search categories\u2026", noResultsText: "No matching category" }));
 }
 export function BlogListView({ posts, isLoading, totalPages = 1, currentPage = 1, total = 0, onPageChange, onPostClick, emptyLabel = "No posts found", slots, }) {
     if (isLoading) {

package/dist/features/blog/components/BlogPostView.js

@@ -55,5 +55,5 @@ export function BlogPostView({ slug, initialData, labels = {}, renderImage, rend
         })
         : "";
     const coverImageUrl = getMediaUrl(post.coverImage);
-    return (_jsxs(Div, { className: `min-h-screen ${className}`, children: [coverImageUrl && (_jsxs(Div, { className: `relative h-72 md:h-96 ${__O.hidden}`, children: [renderImage ? (renderImage(post)) : (_jsx(MediaImage, { src: coverImageUrl, alt: post.title, size: "hero" })), _jsx(Scrim, { direction: "bottom-up", intensity: "subtle", className: "absolute inset-0" })] })), _jsxs(Div, { className: "max-w-3xl mx-auto", paddingY: "y-3xl", paddingX: "x-md", children: [renderBlogPostHeader(post, date, labels), post.youtubeId && /^[A-Za-z0-9_-]{6,20}$/.test(post.youtubeId) && (_jsx(Div, { className: "mb-8", children: _jsx(Iframe, { src: `https://www.youtube-nocookie.com/embed/${post.youtubeId}`, title: `${post.title} — video`, aspect: "video", rounded: "lg" }) })), post.tags && post.tags.length > 0 && (_jsx(Row, { wrap: true, gap: "sm", className: "mb-8", children: post.tags.map((tag) => (_jsxs(Link, { href: `${String(ROUTES.PUBLIC.BLOG)}?tags=${encodeURIComponent(tag)}`, className: "inline-block px-[var(--appkit-space-3)] py-[var(--appkit-space-1)] rounded-full bg-[var(--appkit-color-surface)] bg-[var(--appkit-color-surface-elevated)] hover:bg-primary/10 text-[var(--appkit-color-text-muted)] hover:text-primary text-[length:var(--appkit-text-xs)] font-medium transition-colors", children: ["#", tag] }, tag))) })), renderAuthorBio && _jsx(Div, { className: "mb-6", children: renderAuthorBio(post) }), _jsx(Div, { surface: "card", padding: "xl", className: "mb-12", children: renderContent ? renderContent(post) : (_jsx(RichText, { html: normalizeRichTextHtml(post.content ?? ""), proseClass: "prose max-w-none dark:prose-invert" })) }), _jsxs(Stack, { gap: "xl", children: [renderBlogPostRelated(related, labels?.relatedTitle ?? "Related Posts", renderRelatedCard), renderBlogPostRelated(relatedByTags, labels?.relatedByTagsTitle ?? "You might also like", renderRelatedCard), renderBlogPostRelated(relatedByAuthor, labels?.relatedByAuthorTitle ?? `More from ${post.authorName}`, renderRelatedCard)] }), renderBackButton && _jsx(Div, { border: "default", className: "mt-10 border-t", padding: "t-xl", children: renderBackButton() })] })] }));
+    return (_jsxs(Div, { className: `min-h-screen ${className}`, children: [coverImageUrl && (_jsxs(Div, { className: `relative h-72 md:h-96 ${__O.hidden}`, children: [renderImage ? (renderImage(post)) : (_jsx(MediaImage, { src: coverImageUrl, alt: post.title, size: "hero" })), _jsx(Scrim, { direction: "bottom-up", intensity: "subtle", className: "absolute inset-0" })] })), _jsxs(Div, { className: "max-w-3xl mx-auto", paddingY: "y-3xl", paddingX: "x-md", children: [renderBlogPostHeader(post, date, labels), post.youtubeId && /^[A-Za-z0-9_-]{6,20}$/.test(post.youtubeId) && (_jsx(Div, { className: "mb-8", children: _jsx(Iframe, { src: `https://www.youtube-nocookie.com/embed/${post.youtubeId}`, title: `${post.title} — video`, aspect: "video", rounded: "lg" }) })), post.tags && post.tags.length > 0 && (_jsx(Row, { wrap: true, gap: "sm", className: "mb-8", children: post.tags.map((tag) => (_jsxs(Link, { href: `${String(ROUTES.BLOG.LIST)}?tags=${encodeURIComponent(tag)}`, className: "inline-block px-[var(--appkit-space-3)] py-[var(--appkit-space-1)] rounded-full bg-[var(--appkit-color-surface)] bg-[var(--appkit-color-surface-elevated)] hover:bg-primary/10 text-[var(--appkit-color-text-muted)] hover:text-primary text-[length:var(--appkit-text-xs)] font-medium transition-colors", children: ["#", tag] }, tag))) })), renderAuthorBio && _jsx(Div, { className: "mb-6", children: renderAuthorBio(post) }), _jsx(Div, { surface: "card", padding: "xl", className: "mb-12", children: renderContent ? renderContent(post) : (_jsx(RichText, { html: normalizeRichTextHtml(post.content ?? ""), proseClass: "prose max-w-none dark:prose-invert" })) }), _jsxs(Stack, { gap: "xl", children: [renderBlogPostRelated(related, labels?.relatedTitle ?? "Related Posts", renderRelatedCard), renderBlogPostRelated(relatedByTags, labels?.relatedByTagsTitle ?? "You might also like", renderRelatedCard), renderBlogPostRelated(relatedByAuthor, labels?.relatedByAuthorTitle ?? `More from ${post.authorName}`, renderRelatedCard)] }), renderBackButton && _jsx(Div, { border: "default", className: "mt-10 border-t", padding: "t-xl", children: renderBackButton() })] })] }));
 }

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

@@ -467,18 +467,18 @@ export declare const blogListParamsSchema: z.ZodObject<{
     sort?: string | undefined;
     page?: number | undefined;
     q?: string | undefined;
-    perPage?: number | undefined;
     pageSize?: number | undefined;
     category?: "news" | "tips" | "guides" | "updates" | "community" | undefined;
     featured?: boolean | undefined;
     tags?: string | undefined;
+    perPage?: number | undefined;
 }, {
     sort?: string | undefined;
     page?: number | undefined;
     q?: string | undefined;
-    perPage?: number | undefined;
     pageSize?: number | undefined;
     category?: "news" | "tips" | "guides" | "updates" | "community" | undefined;
     featured?: boolean | undefined;
     tags?: string | undefined;
+    perPage?: number | undefined;
 }>;

package/dist/features/business-documents/repository/business-documents.repository.d.ts

@@ -0,0 +1,58 @@
+/**
+ * BusinessDocumentsRepository — thin wrapper over the `businessDocuments`
+ * collection. See `../schemas/firestore.ts` for the doc shape and for why the
+ * bytes are not in Firestore.
+ */
+import { BaseRepository, parseSieveDateValue, type SieveModel, type FirebaseSieveResult } from "../../../providers/db-firebase";
+import { type BusinessDocumentDocument, type BusinessDocumentKind } from "../schemas/firestore";
+export declare class BusinessDocumentsRepository extends BaseRepository<BusinessDocumentDocument> {
+    constructor();
+    static readonly SIEVE_FIELDS: {
+        id: {
+            canFilter: boolean;
+            canSort: boolean;
+        };
+        kind: {
+            canFilter: boolean;
+            canSort: boolean;
+        };
+        fileName: {
+            canFilter: boolean;
+            canSort: boolean;
+        };
+        uploadedBy: {
+            canFilter: boolean;
+            canSort: boolean;
+        };
+        uploadedAt: {
+            canFilter: boolean;
+            canSort: boolean;
+            parseValue: typeof parseSieveDateValue;
+        };
+        createdAt: {
+            canFilter: boolean;
+            canSort: boolean;
+            parseValue: typeof parseSieveDateValue;
+        };
+    };
+    list(model: SieveModel): Promise<FirebaseSieveResult<BusinessDocumentDocument>>;
+    /**
+     * The current document of a given kind — newest `uploadedAt` wins.
+     *
+     * Re-uploading a re-issued certificate is normal and both copies are kept:
+     * the superseded one is the evidence of what was true at the time, which is
+     * the entire point of keeping a registration document. So this resolves the
+     * current one rather than assuming a single row per kind.
+     *
+     * 🛑 Ordered by `createdAt`, NOT `uploadedAt`, even though the latter reads
+     * more naturally here. `BaseRepository.create()` stamps `createdAt` on every
+     * document it writes, so it is guaranteed present; `uploadedAt` is set by the
+     * caller and a single write path that forgot it would make that row vanish
+     * from this query — a Firestore `orderBy` on a field a document lacks is a
+     * silent `WHERE field IS NOT NULL` (Root Cause #100). The two are written in
+     * the same operation and agree, so there is nothing to gain by taking the
+     * field that can be missed.
+     */
+    findCurrentByKind(kind: BusinessDocumentKind): Promise<BusinessDocumentDocument | null>;
+}
+export declare const businessDocumentsRepository: BusinessDocumentsRepository;