@mohasinac/appkit 4.53.0 → 4.53.2

package/dist/features/auctions/components/AuctionDetailPageView.js

@@ -8,7 +8,7 @@ const __P = {
     p4: "p-[var(--appkit-space-4)]",
     p5: "p-[var(--appkit-space-5)]",
 };
-const CLS_BREADCRUMB_LINK = "hover:text-primary-600 transition-colors";
+const CLS_BREADCRUMB_LINK = "hover:text-primary-600 dark:hover:text-primary-400 transition-colors";
 const CLS_LIVE_BADGE = "inline-block rounded-full bg-warning-surface dark:bg-warning-surface px-[var(--appkit-space-2-5)] py-[var(--appkit-space-0-5)] text-warning dark:text-warning";
 import { ROUTES } from "../../../next/routing/route-map.js";
 import { getDefaultCurrency } from "../../../core/baseline-resolver.js";
@@ -17,16 +17,17 @@ import { normalizeRichTextHtml } from "../../../utils/string.formatter.js";
 import { safeDisplayName } from "../../../security/index.js";
 import { getSiteSettingsGlobal } from "../../admin/utils/getSiteSettingsGlobal.js";
 import { isBuyNowAvailable, resolveMinBid, resolveMinBidIncrement, } from "../../../_internal/shared/features/auctions/config.js";
-import { Button, Container, CountdownDisplay, Div, GatedPrice, PricesOnly, Heading, Input, Main, Nav, RichText, Row, Section, Span, Stack, Text, Ul, Li, Dl, Dt, Dd, } from "../../../ui/index.js";
+import { Button, Container, CountdownDisplay, Div, GatedPrice, PricesOnly, Heading, Input, Main, Nav, RichText, Row, Section, Span, Stack, Text, Ul, Li, SpecTable, } from "../../../ui/index.js";
 import { AuctionDetailView } from "../../products/components/AuctionDetailView.js";
 import { ProductTabsShell } from "../../products/components/ProductTabsShell.js";
-import { CustomSectionTabContent } from "../../products/components/CustomSectionTabContent.js";
+import { toCustomSectionTabs } from "../../products/components/CustomSectionTabContent.js";
 import { AuctionBottomActions } from "./AuctionBottomActions.js";
 import { AuctionLiveStatusBadge } from "./AuctionLiveStatusBadge.js";
 import { RelatedProducts } from "../../products/components/RelatedProducts.js";
 import { ProductGalleryClient } from "../../products/components/ProductGalleryClient.js";
 import { ProductFeatureBadges } from "../../products/components/ProductFeatureBadges.js";
 import { FeatureBadgeList } from "../../products/components/FeatureBadge.js";
+import { productImageUrls } from "../../products/schemas/firestore.js";
 import { HistoryTracker } from "../../history/components/HistoryTracker.js";
 import { ShareButton } from "../../products/components/ShareButton.js";
 import { MarketplaceAuctionGrid } from "./MarketplaceAuctionGrid.js";
@@ -149,8 +150,12 @@ export async function AuctionDetailPageView({ id, initialAuction, onPlaceBid, on
             ? p.price
             : 0;
     const minBidIncrementOverride = typeof p.minBidIncrement === "number" ? p.minBidIncrement : undefined;
-    const images = Array.isArray(p.images)
-        ? p.images
+    // `images` is `ProductImage[]` since A6 — `productImageUrls` is the one
+    // normaliser (it also accepts the legacy `string[]`). Casting it to
+    // `string[]` handed the gallery objects and rendered a placeholder.
+    const galleryUrls = productImageUrls(p.images);
+    const images = galleryUrls.length > 0
+        ? galleryUrls
         : typeof p.mainImage === "string"
             ? [p.mainImage]
             : [];
@@ -184,9 +189,6 @@ export async function AuctionDetailPageView({ id, initialAuction, onPlaceBid, on
     const specs = Array.isArray(p.specifications)
         ? p.specifications
         : [];
-    const customSections = Array.isArray(p.customSections)
-        ? p.customSections
-        : [];
     const descriptionHtml = toDescriptionHtml(p.description);
     const sublistingCategoryId = typeof p.sublistingCategoryId === "string" ? p.sublistingCategoryId : null;
     const relatedDocs = (await safeRead(() => productRepository.findByCategory(String(p.category ?? "")), {
@@ -209,11 +211,7 @@ export async function AuctionDetailPageView({ id, initialAuction, onPlaceBid, on
     });
     return (_jsxs(Main, { children: [_jsx(HistoryTracker, { productId: String(p.id ?? p.slug ?? ""), productType: "auction", snapshot: {
                     title: typeof p.title === "string" ? p.title : undefined,
-                    thumb: typeof p.mainImage === "string"
-                        ? p.mainImage
-                        : Array.isArray(p.images) && typeof p.images[0] === "string"
-                            ? p.images[0]
-                            : undefined,
+                    thumb: typeof p.mainImage === "string" ? p.mainImage : images[0],
                     price: typeof p.price === "number" ? p.price : undefined,
                     storeId: typeof p.storeId === "string" ? p.storeId : undefined,
                     storeName: typeof p.storeName === "string" ? p.storeName : undefined,
@@ -230,11 +228,7 @@ export async function AuctionDetailPageView({ id, initialAuction, onPlaceBid, on
                                         // prompt here would be the same affordance twice.
                                         _jsx(PricesOnly, { children: _jsxs(Text, { align: "center", size: "xs", color: "muted", children: ["Buy Now available at ", formatCurrency(buyNowPrice, currency)] }) }))] }), tags.length > 0 && (_jsx(Div, { border: "default", className: "border-t", padding: "t-md", children: _jsx(Row, { wrap: true, gap: "xs", children: tags.map((tag) => (_jsx(Span, { size: "xs", rounded: "full", padding: "pill-sm-tall", surface: "subtle", color: "muted", children: tag }, tag))) }) }))] })), renderMobileBidForm: () => !isEnded && onPlaceBid ? (_jsxs(Stack, { className: `lg:hidden ${__P.p4}`, border: "subtle", gap: "3", rounded: "xl", surface: "muted", children: [_jsx(LiveBidPrice, { productId: String(product.id), currentBid: currentBid, bidCount: bidCount, currency: currency, isEnded: isEnded, priceSize: "base", badgeSize: "xs" }), endDate && (_jsxs(Text, { align: "center", size: "xs", color: "muted", children: ["Ends in ", _jsx(CountdownDisplay, { targetDate: endDate, format: "auto", expiredLabel: "Ended" })] })), _jsx(PlaceBidModalButton, { productId: String(product.id), currentBid: currentBid, startingBid: startingBid, tiers: bidIncrementTiers, minBidIncrementOverride: minBidIncrementOverride, currency: currency, isEnded: isEnded, auctionEndDate: endDate, buyNowPrice: buyNowPrice, bidCount: bidCount, tags: tags, onPlaceBid: onPlaceBid, onBuyNow: onBuyNow, triggerClassName: "w-full" })] })) : !isEnded ? (_jsxs(Div, { className: `${__P.p4} lg:hidden`, border: "subtle", rounded: "xl", surface: "muted", children: [_jsxs(Row, { align: "center", gap: "sm", className: "mb-3", children: [_jsx(Span, { size: "base", weight: "bold", className: "text-primary-600 dark:text-primary-400", children: _jsx(GatedPrice, { label: "Sign in to see the current bid", children: formatCurrency(currentBid, currency) }) }), _jsxs(Span, { size: "xs", color: "muted", children: [bidCount, " bids"] })] }), endDate && (_jsxs(Text, { align: "center", className: "mb-3", size: "xs", color: "muted", children: ["Ends in ", _jsx(CountdownDisplay, { targetDate: endDate, format: "auto", expiredLabel: "Ended" })] })), _jsx(Button, { variant: "primary", size: "md", className: "w-full", children: "Place Bid" })] })) : null, renderSublistingSection: sublistingCategoryId
                             ? () => (_jsx(SublistingCarouselSection, { sublistingCategoryId: sublistingCategoryId, currentListingId: String(product.id) }))
-                            : undefined, renderTabs: () => (_jsx(ProductTabsShell, { descriptionContent: descriptionHtml ? (_jsx(RichText, { html: descriptionHtml, proseClass: "prose prose-sm sm:prose max-w-none dark:prose-invert", className: "text-[var(--appkit-color-text-muted)]" })) : undefined, specsContent: specs.length > 0 ? (_jsx(Dl, { divide: "subtle", rounded: "xl", border: "subtle", className: "overflow-hidden", children: specs.map((s, i) => (_jsxs(Row, { gap: "md", oddEven: "zebra", surface: "default", padding: "inline", children: [_jsx(Dt, { className: "w-36 flex-shrink-0", color: "primary", weight: "medium", children: s.name }), _jsxs(Dd, { className: "flex-1", color: "muted", children: [s.value, s.unit ? ` ${s.unit}` : ""] })] }, i))) })) : undefined, customTabs: customSections.map((s) => ({
-                                id: s.id,
-                                label: s.title,
-                                content: _jsx(CustomSectionTabContent, { section: s }),
-                            })) })), renderBidHistory: () => {
+                            : undefined, renderTabs: () => (_jsx(ProductTabsShell, { descriptionContent: descriptionHtml ? (_jsx(RichText, { html: descriptionHtml, proseClass: "prose prose-sm sm:prose max-w-none dark:prose-invert", className: "text-[var(--appkit-color-text-muted)]" })) : undefined, specsContent: specs.length > 0 ? (_jsx(SpecTable, { rows: specs })) : undefined, customTabs: toCustomSectionTabs(p.customSections) })), renderBidHistory: () => {
                             if (!bidsResult)
                                 return null;
                             return (_jsx(CollapsibleBidHistory, { productId: String(product.id), initialData: bidsResult, currency: currency }));

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

@@ -1,3 +1,4 @@
+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, type UserPlain } from "../schemas";
@@ -46,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.
      *

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

@@ -1,4 +1,5 @@
 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, maskPii, revealPii, decryptShippingConfig, encryptPayoutDetails, encryptShippingConfig, piiBlindIndex, } from "../../../security/index.js";
@@ -89,6 +90,24 @@ export class UserRepository extends BaseRepository {
             .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.
      *
@@ -381,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

@@ -271,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";

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

@@ -102,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",

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;

package/dist/features/business-documents/repository/business-documents.repository.js

@@ -0,0 +1,54 @@
+/**
+ * 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, } from "../../../providers/db-firebase/index.js";
+import { BUSINESS_DOCUMENTS_COLLECTION, } from "../schemas/firestore.js";
+export class BusinessDocumentsRepository extends BaseRepository {
+    constructor() {
+        super(BUSINESS_DOCUMENTS_COLLECTION);
+    }
+    async list(model) {
+        return this.sieveQuery(model, BusinessDocumentsRepository.SIEVE_FIELDS, { defaultPageSize: 25, maxPageSize: 100 });
+    }
+    /**
+     * 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.
+     */
+    async findCurrentByKind(kind) {
+        const result = await this.list({
+            filters: `kind==${kind}`,
+            sorts: "-createdAt",
+            page: 1,
+            pageSize: 1,
+        });
+        return result.items[0] ?? null;
+    }
+}
+BusinessDocumentsRepository.SIEVE_FIELDS = {
+    id: { canFilter: true, canSort: false },
+    kind: { canFilter: true, canSort: true },
+    fileName: { canFilter: true, canSort: true },
+    uploadedBy: { canFilter: true, canSort: false },
+    // Timestamp fields that are filterable MUST carry parseValue, or an ISO
+    // string reaches Firestore as a string, the type does not match the stored
+    // Timestamp, and the query matches ZERO documents with no error anywhere
+    // (Root Cause #47).
+    uploadedAt: { canFilter: true, canSort: true, parseValue: parseSieveDateValue },
+    createdAt: { canFilter: true, canSort: true, parseValue: parseSieveDateValue },
+};
+export const businessDocumentsRepository = new BusinessDocumentsRepository();

package/dist/features/business-documents/schemas/firestore.d.ts

@@ -0,0 +1,105 @@
+/**
+ * Business Documents Firestore Document Types & Constants
+ *
+ * Collection: businessDocuments
+ * Document ID: Firestore auto-ID (no slug prefix — same convention as
+ * `adminAuditLog` / `notifications` / `sessions` / `jobs`; see CLAUDE.md's
+ * "True Firestore auto-IDs" list).
+ *
+ * The statutory registration documents of the business itself — GST
+ * certificate, Udyam registration, bank passbook. These are NOT product media
+ * and NOT user uploads; there is exactly one current document per `kind`.
+ *
+ * ## 🛑 Metadata only. The bytes are never in Firestore.
+ *
+ * A Firestore document is capped at 1 MiB and the Udyam certificate alone is
+ * 680 KB, which base64-encodes to ~907 KB — so an "encrypt the PDF into a
+ * string field" design is one slightly larger certificate away from an
+ * unrecoverable write failure, at upload time, after the user has handed over
+ * the document. The ciphertext lives in Storage; this collection records where.
+ *
+ * ## 🛑 Why `storagePath` must never be served through /api/media
+ *
+ * `GET /api/media/[...slug]` applies NO authentication — deliberately, because
+ * its job is serving public product photography through a watermarker — and
+ * `storage.rules` is `allow read: if true` for every object in the bucket. So
+ * the only thing standing between these documents and the public internet is
+ * that nothing routes them there, and that they carry no `mediaAssets` row (the
+ * row IS the public `/media/<shortId>` slug, so no row means no public URL).
+ *
+ * Read them through `GET /api/admin/business-documents/[id]` and nothing else.
+ */
+import type { BaseDocument } from "../../../_internal/shared/types/base-document";
+export declare const BUSINESS_DOCUMENTS_COLLECTION = "businessDocuments";
+export declare const BusinessDocumentKindValues: {
+    readonly GST_CERTIFICATE: "gst_certificate";
+    readonly UDYAM_CERTIFICATE: "udyam_certificate";
+    readonly BANK_PASSBOOK: "bank_passbook";
+};
+export type BusinessDocumentKind = (typeof BusinessDocumentKindValues)[keyof typeof BusinessDocumentKindValues];
+export declare const ALL_BUSINESS_DOCUMENT_KINDS: readonly BusinessDocumentKind[];
+/**
+ * A `Record<BusinessDocumentKind, string>` rather than a lookup with a
+ * fallback, so adding a fourth kind is a COMPILE error here instead of
+ * rendering as a raw snake_case id in the admin list.
+ */
+export declare const BUSINESS_DOCUMENT_KIND_LABELS: Record<BusinessDocumentKind, string>;
+export interface BusinessDocumentDocument extends BaseDocument {
+    kind: BusinessDocumentKind;
+    /**
+     * Path inside the Storage bucket, e.g.
+     * `private/business-documents/3f2a…-gst-certificate.pdf`.
+     *
+     * 🛑 Never returned by any API, to anyone. The download route resolves it
+     * server-side and streams the decrypted bytes; handing the path to a client
+     * would let it be fetched straight from Storage, where the rules permit any
+     * read.
+     */
+    storagePath: string;
+    /** Original filename as uploaded — shown in the admin list and used for Content-Disposition. */
+    fileName: string;
+    /** Verified against the file's magic bytes at upload; never trusted from the client. */
+    contentType: string;
+    /** Size of the PLAINTEXT, before the envelope. What an admin expects to see downloaded. */
+    sizeBytes: number;
+    /**
+     * Whether the stored object carries the `enc:v1:` binary envelope.
+     *
+     * Always `true` for anything this codebase writes — `encryptBuffer` throws
+     * rather than degrading when `SETTINGS_ENCRYPTION_KEY` is unset, so there is
+     * no path that produces a plaintext object. It is recorded anyway because
+     * the download route must not GUESS: a future hand-uploaded object would
+     * otherwise be fed to `decryptBuffer` and throw an envelope error that
+     * describes the crypto rather than the upload.
+     */
+    encrypted: boolean;
+    /** Auth UID of the admin who uploaded it. */
+    uploadedBy: string;
+    uploadedAt: Date;
+}
+export declare const BUSINESS_DOCUMENT_FIELDS: {
+    readonly KIND: "kind";
+    readonly STORAGE_PATH: "storagePath";
+    readonly FILE_NAME: "fileName";
+    readonly CONTENT_TYPE: "contentType";
+    readonly SIZE_BYTES: "sizeBytes";
+    readonly ENCRYPTED: "encrypted";
+    readonly UPLOADED_BY: "uploadedBy";
+    readonly UPLOADED_AT: "uploadedAt";
+    readonly CREATED_AT: "createdAt";
+    readonly KIND_VALUES: {
+        readonly GST_CERTIFICATE: "gst_certificate";
+        readonly UDYAM_CERTIFICATE: "udyam_certificate";
+        readonly BANK_PASSBOOK: "bank_passbook";
+    };
+};
+/** Storage prefix. Mirrors `private/digital-content/` — outside any public read path. */
+export declare const BUSINESS_DOCUMENTS_STORAGE_PREFIX = "private/business-documents";
+/**
+ * Accepted upload types. PDFs and scans only.
+ *
+ * Checked against the file's MAGIC BYTES, not the declared Content-Type: a
+ * declared type is a claim by the uploader, and an HTML document served from
+ * this origin would be stored XSS against a signed-in admin.
+ */
+export declare const BUSINESS_DOCUMENT_ALLOWED_TYPES: readonly ["application/pdf", "image/jpeg", "image/png", "image/webp"];

package/dist/features/business-documents/schemas/firestore.js

@@ -0,0 +1,75 @@
+/**
+ * Business Documents Firestore Document Types & Constants
+ *
+ * Collection: businessDocuments
+ * Document ID: Firestore auto-ID (no slug prefix — same convention as
+ * `adminAuditLog` / `notifications` / `sessions` / `jobs`; see CLAUDE.md's
+ * "True Firestore auto-IDs" list).
+ *
+ * The statutory registration documents of the business itself — GST
+ * certificate, Udyam registration, bank passbook. These are NOT product media
+ * and NOT user uploads; there is exactly one current document per `kind`.
+ *
+ * ## 🛑 Metadata only. The bytes are never in Firestore.
+ *
+ * A Firestore document is capped at 1 MiB and the Udyam certificate alone is
+ * 680 KB, which base64-encodes to ~907 KB — so an "encrypt the PDF into a
+ * string field" design is one slightly larger certificate away from an
+ * unrecoverable write failure, at upload time, after the user has handed over
+ * the document. The ciphertext lives in Storage; this collection records where.
+ *
+ * ## 🛑 Why `storagePath` must never be served through /api/media
+ *
+ * `GET /api/media/[...slug]` applies NO authentication — deliberately, because
+ * its job is serving public product photography through a watermarker — and
+ * `storage.rules` is `allow read: if true` for every object in the bucket. So
+ * the only thing standing between these documents and the public internet is
+ * that nothing routes them there, and that they carry no `mediaAssets` row (the
+ * row IS the public `/media/<shortId>` slug, so no row means no public URL).
+ *
+ * Read them through `GET /api/admin/business-documents/[id]` and nothing else.
+ */
+export const BUSINESS_DOCUMENTS_COLLECTION = "businessDocuments";
+export const BusinessDocumentKindValues = {
+    GST_CERTIFICATE: "gst_certificate",
+    UDYAM_CERTIFICATE: "udyam_certificate",
+    BANK_PASSBOOK: "bank_passbook",
+};
+export const ALL_BUSINESS_DOCUMENT_KINDS = Object.values(BusinessDocumentKindValues);
+/**
+ * A `Record<BusinessDocumentKind, string>` rather than a lookup with a
+ * fallback, so adding a fourth kind is a COMPILE error here instead of
+ * rendering as a raw snake_case id in the admin list.
+ */
+export const BUSINESS_DOCUMENT_KIND_LABELS = {
+    [BusinessDocumentKindValues.GST_CERTIFICATE]: "GST Certificate",
+    [BusinessDocumentKindValues.UDYAM_CERTIFICATE]: "Udyam Registration Certificate",
+    [BusinessDocumentKindValues.BANK_PASSBOOK]: "Bank Passbook",
+};
+export const BUSINESS_DOCUMENT_FIELDS = {
+    KIND: "kind",
+    STORAGE_PATH: "storagePath",
+    FILE_NAME: "fileName",
+    CONTENT_TYPE: "contentType",
+    SIZE_BYTES: "sizeBytes",
+    ENCRYPTED: "encrypted",
+    UPLOADED_BY: "uploadedBy",
+    UPLOADED_AT: "uploadedAt",
+    CREATED_AT: "createdAt",
+    KIND_VALUES: BusinessDocumentKindValues,
+};
+/** Storage prefix. Mirrors `private/digital-content/` — outside any public read path. */
+export const BUSINESS_DOCUMENTS_STORAGE_PREFIX = "private/business-documents";
+/**
+ * Accepted upload types. PDFs and scans only.
+ *
+ * Checked against the file's MAGIC BYTES, not the declared Content-Type: a
+ * declared type is a claim by the uploader, and an HTML document served from
+ * this origin would be stored XSS against a signed-in admin.
+ */
+export const BUSINESS_DOCUMENT_ALLOWED_TYPES = [
+    "application/pdf",
+    "image/jpeg",
+    "image/png",
+    "image/webp",
+];

package/dist/features/cart/actions/cart-actions.js

@@ -15,6 +15,7 @@ import { CART_LANE, activeLane, canAddNewItems, } from "../../../_internal/share
 import { CART_MAX_ITEMS } from "../../../constants/limits.js";
 import { getExpandedDecrements, validateCartItemStock, } from "../../../_internal/server/features/checkout/bundle-expansion.js";
 import { safeRead } from "../../../errors/safe-read.js";
+import { checkGroupRules, readGroupRules, } from "../../../_internal/shared/features/products/group-rules.js";
 /**
  * Product documents don't always carry a denormalized `storeName` — the
  * create routes only set it when the caller explicitly passes one, so
@@ -133,7 +134,13 @@ export async function addGroupLineToCart(userId, input) {
         if (!rule.cartEligible) {
             throw new ValidationError(`"${product.title}" can't be added to the cart. ${rule.cartIneligibleHint ?? ""}`.trim());
         }
-        if ((product.availableQuantity ?? 0) < m.quantity) {
+        /*
+         * 🛑 Made to order: no stock CHECK for this member. Nothing is held in
+         * reserve — it is printed or built when the order arrives — so the only
+         * honest answer to "how many are left" is "as many as you want". The
+         * decrement still happens at checkout; see `validateCartItemStock`.
+         */
+        if (product.madeToOrder !== true && (product.availableQuantity ?? 0) < m.quantity) {
             throw new ValidationError(`Only ${product.availableQuantity ?? 0} left of "${product.title}".`);
         }
         resolved.push({
@@ -141,7 +148,7 @@ export async function addGroupLineToCart(userId, input) {
             quantity: m.quantity,
             unitPrice: product.price,
             title: product.title,
-            image: product.images?.[0] ?? product.mainImage,
+            image: product.images?.[0]?.url ?? product.mainImage,
             gstRate: product.gstRate,
             hsnCode: product.hsnCode,
             listingType,
@@ -164,7 +171,7 @@ export async function addGroupLineToCart(userId, input) {
         return addItemToCart(userId, {
             productId: first.id,
             productTitle: first.title,
-            productImage: first.images?.[0] ?? first.mainImage,
+            productImage: first.images?.[0]?.url ?? first.mainImage,
             price: first.price,
             currency: first.currency,
             quantity: resolved[0].quantity,
@@ -192,6 +199,25 @@ export async function addGroupLineToCart(userId, input) {
         throw new ValidationError(`Only ${shortfall.availableQty} left of "${short?.title ?? shortfall.productId}" once your cart is counted.`);
     }
     const groupTitle = await resolveGroupTitle(groupId, groupSource, first ?? null);
+    /*
+     * 🛑 SERVER-SIDE ENFORCEMENT OF THE GROUP'S OWN RULES.
+     *
+     * `GroupMemberPicker` mirrors this so a buyer is not told "no" only after
+     * submitting — but the picker is a convenience and this is the boundary. The
+     * two share `checkGroupRules`, so they cannot disagree about what a valid
+     * selection is; only about WHEN the buyer finds out.
+     *
+     * It throws on the FIRST violation while the picker shows all of them
+     * together, which is each surface doing the right thing for its own job: a
+     * form lists everything to fix, an API answers one reason.
+     */
+    const rules = await resolveGroupRules(groupId, groupSource, first ?? null);
+    const violations = checkGroupRules(rules, resolved.map((r) => ({ productId: r.productId, quantity: r.quantity, title: r.title })));
+    if (violations.length > 0) {
+        throw Object.assign(new ValidationError(violations[0].message), {
+            code: violations[0].code,
+        });
+    }
     return cartRepository.addGroupLine(userId, {
         productId: groupId,
         productTitle: groupTitle,
@@ -208,9 +234,51 @@ export async function addGroupLineToCart(userId, input) {
         groupId,
         groupSlug: groupSource === "product-group" ? groupId : undefined,
         groupTitle,
+        /*
+         * Snapshotted at add time — see `CartItemDocument.groupDiscountPercent`.
+         * Omitted entirely when there is no discount, so a line with no group
+         * pricing carries no field rather than a zero that reads as "0% off".
+         */
+        ...(rules.groupDiscountPercent !== undefined && rules.groupDiscountPercent > 0
+            ? { groupDiscountPercent: rules.groupDiscountPercent }
+            : {}),
         groupMembers: resolved,
     });
 }
+/**
+ * The group's selection rules, from whichever of the two homes owns them.
+ *
+ * 🛑 ONE resolver, because there are TWO homes: a product group keeps them on
+ * its PARENT PRODUCT (identified by the parent's slug, which IS the groupId),
+ * while a `groupedListing` keeps them on its own document. Reading them at each
+ * call site is how the picker and the server come to disagree.
+ *
+ * Fails OPEN — an unreadable group yields no rules rather than refusing the
+ * add. A transient Firestore error must not look like "your selection is
+ * invalid", which is a statement about the buyer's choice and would send them
+ * to change something that was already correct.
+ */
+async function resolveGroupRules(groupId, groupSource, sample) {
+    if (groupSource === "grouped-listing") {
+        const { groupedListingsRepository } = await import("../../grouped/repository/grouped-listings.repository.js");
+        const group = await safeRead(() => groupedListingsRepository.findById(groupId), {
+            route: "/cart", key: "groupedListings.rules", fallback: null,
+        });
+        return readGroupRules(group);
+    }
+    /*
+     * A product group's rules live on the PARENT, and `sample` is an arbitrary
+     * member — so the parent has to be fetched unless the sample happens to BE
+     * it. `groupId` is the parent's slug and products are pure slugs
+     * (`id === slug`), so `findById` resolves it directly.
+     */
+    if (sample?.isGroupParent && sample.id === groupId)
+        return readGroupRules(sample);
+    const parent = await safeRead(() => productRepository.findById(groupId), {
+        route: "/cart", key: "products.groupParentRules", fallback: null,
+    });
+    return readGroupRules(parent);
+}
 /** Is this product listed on that `groupedListings` document? */
 async function isGroupedListingMember(groupId, productId) {
     const { groupedListingsRepository } = await import("../../grouped/repository/grouped-listings.repository.js");
@@ -263,14 +331,23 @@ export async function mergeGuestCart(userId, items) {
         const product = await productRepository.findById(item.productId);
         if (!product || product.status !== "published")
             continue;
-        if (product.availableQuantity < 1)
+        /*
+         * A made-to-order row survives the guest-cart merge at its full requested
+         * quantity. Dropping it (or clamping it to 0) would silently delete the
+         * line a signed-out visitor had chosen, which reads as the cart losing
+         * items on login — and there is no stock level for the clamp to clamp to.
+         */
+        const unlimited = product.madeToOrder === true;
+        if (!unlimited && product.availableQuantity < 1)
             continue;
-        const safeQty = Math.min(item.quantity, product.availableQuantity);
+        const safeQty = unlimited
+            ? item.quantity
+            : Math.min(item.quantity, product.availableQuantity);
         const storeName = await resolveStoreName(product.storeId, product.storeName);
         await cartRepository.addItem(userId, {
             productId: product.id,
             productTitle: product.title,
-            productImage: product.images?.[0] ?? "",
+            productImage: product.images?.[0]?.url ?? "",
             price: product.price,
             currency: product.currency ?? getDefaultCurrency(),
             quantity: safeQty,