@mohasinac/appkit 4.13.1 → 4.14.0

package/dist/_internal/shared/features/products/schema.d.ts

@@ -35,9 +35,6 @@ export declare const productInputSchema: z.ZodObject<{
     tags: string[];
     features?: string[] | undefined;
     description?: string | undefined;
-    seoTitle?: string | undefined;
-    seoDescription?: string | undefined;
-    seoKeywords?: string[] | undefined;
     brandSlug?: string | undefined;
     shippingInfo?: string | undefined;
     returnPolicy?: string | undefined;
@@ -45,6 +42,9 @@ export declare const productInputSchema: z.ZodObject<{
     insurance?: boolean | undefined;
     insuranceCost?: number | undefined;
     shippingPaidBy?: "seller" | "buyer" | undefined;
+    seoTitle?: string | undefined;
+    seoDescription?: string | undefined;
+    seoKeywords?: string[] | undefined;
     allowOffers?: boolean | undefined;
     minOfferPercent?: number | undefined;
 }, {
@@ -55,9 +55,6 @@ export declare const productInputSchema: z.ZodObject<{
     currency?: string | undefined;
     features?: string[] | undefined;
     description?: string | undefined;
-    seoTitle?: string | undefined;
-    seoDescription?: string | undefined;
-    seoKeywords?: string[] | undefined;
     brandSlug?: string | undefined;
     stockQuantity?: number | undefined;
     availableQuantity?: number | undefined;
@@ -69,6 +66,9 @@ export declare const productInputSchema: z.ZodObject<{
     insurance?: boolean | undefined;
     insuranceCost?: number | undefined;
     shippingPaidBy?: "seller" | "buyer" | undefined;
+    seoTitle?: string | undefined;
+    seoDescription?: string | undefined;
+    seoKeywords?: string[] | undefined;
     allowOffers?: boolean | undefined;
     minOfferPercent?: number | undefined;
 }>;
@@ -100,11 +100,8 @@ export declare const productUpdateSchema: z.ZodObject<{
     currency?: string | undefined;
     title?: string | undefined;
     features?: string[] | undefined;
-    category?: string | undefined;
     description?: string | undefined;
-    seoTitle?: string | undefined;
-    seoDescription?: string | undefined;
-    seoKeywords?: string[] | undefined;
+    category?: string | undefined;
     brandSlug?: string | undefined;
     price?: number | undefined;
     stockQuantity?: number | undefined;
@@ -118,17 +115,17 @@ export declare const productUpdateSchema: z.ZodObject<{
     insurance?: boolean | undefined;
     insuranceCost?: number | undefined;
     shippingPaidBy?: "seller" | "buyer" | undefined;
+    seoTitle?: string | undefined;
+    seoDescription?: string | undefined;
+    seoKeywords?: string[] | undefined;
     allowOffers?: boolean | undefined;
     minOfferPercent?: number | undefined;
 }, {
     currency?: string | undefined;
     title?: string | undefined;
     features?: string[] | undefined;
-    category?: string | undefined;
     description?: string | undefined;
-    seoTitle?: string | undefined;
-    seoDescription?: string | undefined;
-    seoKeywords?: string[] | undefined;
+    category?: string | undefined;
     brandSlug?: string | undefined;
     price?: number | undefined;
     stockQuantity?: number | undefined;
@@ -142,6 +139,9 @@ export declare const productUpdateSchema: z.ZodObject<{
     insurance?: boolean | undefined;
     insuranceCost?: number | undefined;
     shippingPaidBy?: "seller" | "buyer" | undefined;
+    seoTitle?: string | undefined;
+    seoDescription?: string | undefined;
+    seoKeywords?: string[] | undefined;
     allowOffers?: boolean | undefined;
     minOfferPercent?: number | undefined;
 }>;
@@ -183,21 +183,18 @@ export declare const auctionInputSchema: z.ZodObject<{
     currency: string;
     title: string;
     category: string;
-    listingType: "auction";
     price: number;
     stockQuantity: number;
     availableQuantity: number;
     mainImage: string;
     images: string[];
     tags: string[];
+    listingType: "auction";
     auctionEndDate: string;
     startingBid: number;
     autoExtendable: boolean;
     features?: string[] | undefined;
     description?: string | undefined;
-    seoTitle?: string | undefined;
-    seoDescription?: string | undefined;
-    seoKeywords?: string[] | undefined;
     brandSlug?: string | undefined;
     shippingInfo?: string | undefined;
     returnPolicy?: string | undefined;
@@ -210,22 +207,22 @@ export declare const auctionInputSchema: z.ZodObject<{
     minBidIncrement?: number | undefined;
     auctionExtensionMinutes?: number | undefined;
     auctionShippingPaidBy?: "seller" | "winner" | undefined;
+    seoTitle?: string | undefined;
+    seoDescription?: string | undefined;
+    seoKeywords?: string[] | undefined;
     allowOffers?: boolean | undefined;
     minOfferPercent?: number | undefined;
 }, {
     title: string;
     category: string;
-    listingType: "auction";
     price: number;
     mainImage: string;
+    listingType: "auction";
     auctionEndDate: string;
     startingBid: number;
     currency?: string | undefined;
     features?: string[] | undefined;
     description?: string | undefined;
-    seoTitle?: string | undefined;
-    seoDescription?: string | undefined;
-    seoKeywords?: string[] | undefined;
     brandSlug?: string | undefined;
     stockQuantity?: number | undefined;
     availableQuantity?: number | undefined;
@@ -243,6 +240,9 @@ export declare const auctionInputSchema: z.ZodObject<{
     autoExtendable?: boolean | undefined;
     auctionExtensionMinutes?: number | undefined;
     auctionShippingPaidBy?: "seller" | "winner" | undefined;
+    seoTitle?: string | undefined;
+    seoDescription?: string | undefined;
+    seoKeywords?: string[] | undefined;
     allowOffers?: boolean | undefined;
     minOfferPercent?: number | undefined;
 }>;
@@ -281,21 +281,18 @@ export declare const preOrderInputSchema: z.ZodObject<{
     currency: string;
     title: string;
     category: string;
-    listingType: "pre-order";
     price: number;
     stockQuantity: number;
     availableQuantity: number;
     mainImage: string;
     images: string[];
     tags: string[];
+    listingType: "pre-order";
     preOrderDeliveryDate: string;
-    preOrderProductionStatus: "upcoming" | "in_production" | "ready_to_ship";
+    preOrderProductionStatus: "in_production" | "upcoming" | "ready_to_ship";
     preOrderCancellable: boolean;
     features?: string[] | undefined;
     description?: string | undefined;
-    seoTitle?: string | undefined;
-    seoDescription?: string | undefined;
-    seoKeywords?: string[] | undefined;
     brandSlug?: string | undefined;
     shippingInfo?: string | undefined;
     returnPolicy?: string | undefined;
@@ -305,21 +302,21 @@ export declare const preOrderInputSchema: z.ZodObject<{
     shippingPaidBy?: "seller" | "buyer" | undefined;
     preOrderDepositPercent?: number | undefined;
     preOrderMaxQuantity?: number | undefined;
+    seoTitle?: string | undefined;
+    seoDescription?: string | undefined;
+    seoKeywords?: string[] | undefined;
     allowOffers?: boolean | undefined;
     minOfferPercent?: number | undefined;
 }, {
     title: string;
     category: string;
-    listingType: "pre-order";
     price: number;
     mainImage: string;
+    listingType: "pre-order";
     preOrderDeliveryDate: string;
     currency?: string | undefined;
     features?: string[] | undefined;
     description?: string | undefined;
-    seoTitle?: string | undefined;
-    seoDescription?: string | undefined;
-    seoKeywords?: string[] | undefined;
     brandSlug?: string | undefined;
     stockQuantity?: number | undefined;
     availableQuantity?: number | undefined;
@@ -333,8 +330,11 @@ export declare const preOrderInputSchema: z.ZodObject<{
     shippingPaidBy?: "seller" | "buyer" | undefined;
     preOrderDepositPercent?: number | undefined;
     preOrderMaxQuantity?: number | undefined;
-    preOrderProductionStatus?: "upcoming" | "in_production" | "ready_to_ship" | undefined;
+    preOrderProductionStatus?: "in_production" | "upcoming" | "ready_to_ship" | undefined;
     preOrderCancellable?: boolean | undefined;
+    seoTitle?: string | undefined;
+    seoDescription?: string | undefined;
+    seoKeywords?: string[] | undefined;
     allowOffers?: boolean | undefined;
     minOfferPercent?: number | undefined;
 }>;

package/dist/_internal/shared/features/products/to-product-item.js

@@ -41,5 +41,11 @@ export function toProductItem(doc) {
         // when listingType is missing) — same bug class as the Phase 1 routing
         // fix, one hop further downstream in the related-items card link path.
         listingType: doc.listingType ?? undefined,
+        // Same reasoning as `listingType` directly above, on the offers axis: the
+        // card grid renders a "Taking Offers" pill from this flag, so dropping it
+        // here made every related-item / grouped-listing card claim the seller
+        // doesn't negotiate — regardless of whether they do.
+        allowOffers: doc.allowOffers === true ? true : undefined,
+        minOfferPercent: typeof doc.minOfferPercent === "number" ? doc.minOfferPercent : undefined,
     };
 }

package/dist/_internal/shared/features/reviews/schema.d.ts

@@ -12,15 +12,15 @@ export declare const createReviewSchema: z.ZodObject<{
     body: string;
     storeId: string;
     images: string[];
-    rating: number;
     productId: string;
+    rating: number;
     orderId?: string | undefined;
 }, {
     title: string;
     body: string;
     storeId: string;
-    rating: number;
     productId: string;
+    rating: number;
     orderId?: string | undefined;
     images?: string[] | undefined;
 }>;

package/dist/_internal/shared/features/site-settings/fees.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Buyer-facing projections of `siteSettings.commissions` / `siteSettings.emi`.
+ *
+ * The commissions block holds 25 fields, most of which describe internal
+ * economics — `gatewayFeePercent`, `sellerShippingFixed`,
+ * `platformShippingPercent`, `payoutHoldDays`, `minPayoutAmount`,
+ * `autoPayoutWindowDays`, and the listing/featured/promoted slot fees. Ten of
+ * them price something the buyer actually chooses, and only those ten belong
+ * in a browser.
+ *
+ * Why a projection rather than a type: the cart and checkout client props were
+ * ALREADY typed narrowly (`StoreAddonsRates`, `CodHandlingFeeRates & …`), but
+ * the SSR pages passed `settings.commissions` whole. TypeScript's structural
+ * typing accepts a wider object without complaint, so every one of the 25
+ * fields was serialised into the page's HTML regardless of what the prop type
+ * said. A type alone cannot strip fields at runtime — this function can.
+ *
+ * Use this for BOTH the cart/checkout SSR props and any future public API that
+ * needs fee data, so there is exactly one definition of "buyer-facing fee".
+ */
+import type { SiteSettingsDocument } from "../../../../features/admin/schemas/firestore";
+import type { EmiSettings } from "../emi/schedule";
+/**
+ * = `StoreAddonsRates` ∪ `CodHandlingFeeRates` ∪ `{ codDepositPercent }` —
+ * the union of what `StoreAddonsPicker` and the checkout COD block read.
+ * Every field is optional because older `siteSettings` documents predate them
+ * and each `compute*Fee` helper carries its own default.
+ */
+export interface BuyerFacingFees {
+    whatsappNotifyFeeEnabled?: boolean;
+    whatsappNotifyFee?: number;
+    giftWrapFeeEnabled?: boolean;
+    giftWrapFee?: number;
+    shipmentProtectionFeeEnabled?: boolean;
+    shipmentProtectionFeePercent?: number;
+    shipmentProtectionFeeMin?: number;
+    codHandlingFeeMin?: number;
+    codHandlingFeePercent?: number;
+    codDepositPercent?: number;
+}
+/**
+ * Withheld on purpose (15 of 25): platformFeePercent, gstPercent,
+ * minimumTransactionFee, platformFeeMax, gatewayFeePercent,
+ * sellerShippingFixed, platformShippingPercent, platformShippingFixedMin,
+ * autoPayoutWindowDays, payoutHoldDays, minPayoutAmount, auctionListingFee,
+ * preOrderListingFee, featuredSlotFee, promotedSlotFee.
+ *
+ * The buyer still SEES the platform fee and GST — as computed amounts in the
+ * server pricing preview (`CartPriceBreakdownData`), never as the rates that
+ * produced them.
+ */
+export declare function toBuyerFacingFees(commissions: SiteSettingsDocument["commissions"] | null | undefined): BuyerFacingFees | null;
+/**
+ * EMI settings minus `surchargeSellerSharePercent` — how the surcharge is
+ * split between platform and seller is a commercial term, not something the
+ * buyer's browser needs. Pair with `computeBuyerEmiQuote`, which is typed to
+ * accept exactly this shape.
+ */
+export type BuyerEmiSettings = Omit<EmiSettings, "surchargeSellerSharePercent">;
+export declare function toBuyerEmiSettings(emi: SiteSettingsDocument["emi"] | null | undefined): BuyerEmiSettings | null;

package/dist/_internal/shared/features/site-settings/fees.js

@@ -0,0 +1,39 @@
+/**
+ * Withheld on purpose (15 of 25): platformFeePercent, gstPercent,
+ * minimumTransactionFee, platformFeeMax, gatewayFeePercent,
+ * sellerShippingFixed, platformShippingPercent, platformShippingFixedMin,
+ * autoPayoutWindowDays, payoutHoldDays, minPayoutAmount, auctionListingFee,
+ * preOrderListingFee, featuredSlotFee, promotedSlotFee.
+ *
+ * The buyer still SEES the platform fee and GST — as computed amounts in the
+ * server pricing preview (`CartPriceBreakdownData`), never as the rates that
+ * produced them.
+ */
+export function toBuyerFacingFees(commissions) {
+    if (!commissions)
+        return null;
+    return {
+        whatsappNotifyFeeEnabled: commissions.whatsappNotifyFeeEnabled,
+        whatsappNotifyFee: commissions.whatsappNotifyFee,
+        giftWrapFeeEnabled: commissions.giftWrapFeeEnabled,
+        giftWrapFee: commissions.giftWrapFee,
+        shipmentProtectionFeeEnabled: commissions.shipmentProtectionFeeEnabled,
+        shipmentProtectionFeePercent: commissions.shipmentProtectionFeePercent,
+        shipmentProtectionFeeMin: commissions.shipmentProtectionFeeMin,
+        codHandlingFeeMin: commissions.codHandlingFeeMin,
+        codHandlingFeePercent: commissions.codHandlingFeePercent,
+        codDepositPercent: commissions.codDepositPercent,
+    };
+}
+export function toBuyerEmiSettings(emi) {
+    if (!emi)
+        return null;
+    return {
+        enabled: emi.enabled,
+        minOrderValue: emi.minOrderValue,
+        tenureOptions: emi.tenureOptions,
+        tokenPercent: emi.tokenPercent,
+        billingDay: emi.billingDay,
+        surchargePercentPerMonth: emi.surchargePercentPerMonth,
+    };
+}

package/dist/_internal/shared/features/site-settings/types.d.ts

@@ -0,0 +1,40 @@
+/**
+ * The public shape of site settings — the ONLY fields
+ * `GET /api/site-settings` may return to an unauthenticated caller.
+ *
+ * This type lives under `_internal/shared/` rather than beside the server
+ * adapter because client code consumes it (`useSiteSettings<PublicSiteSettings>()`),
+ * and client files must not import from `_internal/server`.
+ *
+ * Additive by explicit triage only: see `PUBLIC_SITE_SETTINGS_FIELDS` /
+ * `PRIVATE_SITE_SETTINGS_FIELDS` in
+ * `../../../server/features/site-settings/adapters.ts`, enforced by
+ * `scripts/audit-public-projection-parity.mjs`. Adding a field here without a
+ * proven client reader is how the endpoint drifted in the first place.
+ */
+import type { NotificationChannelConfig, SiteSettingsDocument } from "../../../../features/admin/schemas/firestore";
+import type { MediaVideoWatermark } from "../../../../features/media/MediaVideo";
+export interface PublicSiteSettings {
+    /** Support channels shown to buyers. Deliberately NOT the full `contact` — `address` and `upiVpa` stay server-side. */
+    contact: {
+        email: string;
+        phone: string;
+        whatsappNumber: string;
+    };
+    /** Deliberately NOT the full `payment` block — only the checkout OTP threshold has a client reader. */
+    payment: {
+        otpCheckoutThreshold?: number;
+    };
+    /** Deliberately NOT the full `featureFlags` — `adminCheckoutBypass` must never be advertised publicly. */
+    featureFlags: {
+        listingTypes?: SiteSettingsDocument["featureFlags"]["listingTypes"];
+    };
+    notificationChannels?: NotificationChannelConfig;
+    announcementBar?: SiteSettingsDocument["announcementBar"];
+    navConfig?: SiteSettingsDocument["navConfig"];
+    actionConfig?: SiteSettingsDocument["actionConfig"];
+    background?: SiteSettingsDocument["background"];
+    watermark?: SiteSettingsDocument["watermark"];
+    /** Derived, not a stored field — the resolved marker → wordmark → text chain. */
+    effectiveWatermark?: MediaVideoWatermark;
+}

package/dist/_internal/shared/features/site-settings/types.js

@@ -0,0 +1 @@
+export {};

package/dist/_internal/shared/history/history.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Tracked-field diffing and capped append for entity status history.
+ *
+ * These are deliberately plain functions rather than a `BaseRepository`
+ * override: the repository method that owns a transition already knows the
+ * actor and the trigger, and a generic hook would have to guess both. The
+ * repository calls `buildHistoryEntry` + `appendHistoryEntry` inside its own
+ * write primitive — which is the point, since that is what keeps the 32
+ * call sites above it unchanged.
+ */
+import type { FirestoreDocument } from "../../../schemas/types";
+import { type AppendHistoryResult, type FieldChange, type HistoryActor, type StatusChangeEntry } from "./types";
+/**
+ * Diff only the fields an entity declares as tracked.
+ *
+ * The tracked list is explicit per entity, never "every field": a whole-
+ * document diff would record the `updatedAt` bump on every single write and
+ * exhaust the 50-entry cap within days, burying the transitions anyone
+ * actually wants to read.
+ *
+ * A field absent from `patch` is untouched — this diffs the patch against
+ * the current document, not two full documents.
+ */
+export declare function diffTrackedFields(current: FirestoreDocument | undefined, patch: FirestoreDocument, tracked: readonly string[]): Record<string, FieldChange>;
+export interface BuildHistoryEntryInput {
+    actor: HistoryActor;
+    trigger: string;
+    changes: Record<string, FieldChange>;
+    reason?: string;
+    note?: string;
+    /** Injectable for deterministic tests and seed fixtures. */
+    now?: Date;
+}
+export declare function buildHistoryEntry(input: BuildHistoryEntryInput): StatusChangeEntry;
+/**
+ * Append with a FIFO cap. Returns the new array plus the running count of
+ * entries dropped over the document's lifetime, so the caller can persist it
+ * and the UI can be honest about what it is not showing.
+ */
+export declare function appendHistoryEntry(existing: readonly StatusChangeEntry[] | undefined, entry: StatusChangeEntry, previousTruncatedCount?: number, cap?: number): AppendHistoryResult;
+/**
+ * The whole flow in one call: diff, and return the patch additions needed to
+ * record it. Returns `null` when no tracked field changed — the caller then
+ * writes its patch unchanged, so an untracked update never grows the array.
+ */
+export declare function withHistory<TPatch extends FirestoreDocument>(current: FirestoreDocument | undefined, patch: TPatch, opts: {
+    tracked: readonly string[];
+    actor: HistoryActor;
+    trigger: string;
+    reason?: string;
+    note?: string;
+    /**
+     * Changes the field diff cannot express, merged over the diffed ones.
+     *
+     * Needed for append-to-array events: a refund posted to `refunds[]`
+     * shows up in a raw diff as "an array of 1 became an array of 2", which
+     * is true and useless. The caller instead contributes
+     * `{ refund: { from: null, to: { amount, type, reason } } }` — the thing
+     * a reader actually wants on the timeline.
+     */
+    extraChanges?: Record<string, FieldChange>;
+    historyField?: string;
+    truncatedField?: string;
+    now?: Date;
+    cap?: number;
+}): (TPatch & FirestoreDocument) | null;

package/dist/_internal/shared/history/history.js

@@ -0,0 +1,158 @@
+/**
+ * Tracked-field diffing and capped append for entity status history.
+ *
+ * These are deliberately plain functions rather than a `BaseRepository`
+ * override: the repository method that owns a transition already knows the
+ * actor and the trigger, and a generic hook would have to guess both. The
+ * repository calls `buildHistoryEntry` + `appendHistoryEntry` inside its own
+ * write primitive — which is the point, since that is what keeps the 32
+ * call sites above it unchanged.
+ */
+import { normalizeError } from "../../../errors/normalize";
+import { STATUS_HISTORY_MAX, } from "./types";
+/**
+ * Structural equality for field values.
+ *
+ * Tracked fields are not all scalars, so identity comparison would flag an
+ * unchanged object as changed on every write. Dates compare by instant,
+ * because Firestore hands back a fresh object on every read — without this,
+ * re-saving a document with no edits would append a history entry.
+ */
+function isSameValue(a, b) {
+    if (a === b)
+        return true;
+    if (a == null || b == null)
+        return a == null && b == null;
+    const aDate = toDateOrNull(a);
+    const bDate = toDateOrNull(b);
+    if (aDate && bDate)
+        return aDate.getTime() === bDate.getTime();
+    if (aDate || bDate)
+        return false;
+    if (typeof a !== "object" || typeof b !== "object")
+        return false;
+    try {
+        return JSON.stringify(a) === JSON.stringify(b);
+    }
+    catch (err) {
+        void normalizeError(err);
+        // Circular or non-serialisable — treat as changed rather than throwing
+        // inside a write path.
+        return false;
+    }
+}
+/** Firestore Timestamps expose `toDate()`; plain Dates are used directly. */
+function toDateOrNull(v) {
+    if (v instanceof Date)
+        return v;
+    if (typeof v === "object" && v !== null && typeof v.toDate === "function") {
+        try {
+            return v.toDate();
+        }
+        catch (err) {
+            void normalizeError(err);
+            // A Timestamp-like object whose toDate() threw is not a usable date;
+            // the caller treats null as "not a date" and falls through to structural
+            // comparison, so there is nothing to report.
+            return null;
+        }
+    }
+    return null;
+}
+/** Read a possibly-dotted path (`emiInstallments.0.status`) off an object. */
+function readPath(source, path) {
+    if (!source)
+        return undefined;
+    if (!path.includes("."))
+        return source[path];
+    let cursor = source;
+    for (const segment of path.split(".")) {
+        if (cursor == null || typeof cursor !== "object")
+            return undefined;
+        cursor = cursor[segment];
+    }
+    return cursor;
+}
+/**
+ * Diff only the fields an entity declares as tracked.
+ *
+ * The tracked list is explicit per entity, never "every field": a whole-
+ * document diff would record the `updatedAt` bump on every single write and
+ * exhaust the 50-entry cap within days, burying the transitions anyone
+ * actually wants to read.
+ *
+ * A field absent from `patch` is untouched — this diffs the patch against
+ * the current document, not two full documents.
+ */
+export function diffTrackedFields(current, patch, tracked) {
+    const changes = {};
+    for (const field of tracked) {
+        if (!(field in patch) && !field.includes("."))
+            continue;
+        const to = readPath(patch, field);
+        if (to === undefined)
+            continue;
+        const from = readPath(current, field);
+        if (isSameValue(from, to))
+            continue;
+        changes[field] = { from: from ?? null, to };
+    }
+    return changes;
+}
+export function buildHistoryEntry(input) {
+    const entry = {
+        at: input.now ?? new Date(),
+        actorRole: input.actor.role,
+        changes: input.changes,
+        trigger: input.trigger,
+    };
+    if (input.actor.uid)
+        entry.actorUid = input.actor.uid;
+    if (input.reason)
+        entry.reason = input.reason;
+    if (input.note)
+        entry.note = input.note;
+    return entry;
+}
+/**
+ * Append with a FIFO cap. Returns the new array plus the running count of
+ * entries dropped over the document's lifetime, so the caller can persist it
+ * and the UI can be honest about what it is not showing.
+ */
+export function appendHistoryEntry(existing, entry, previousTruncatedCount = 0, cap = STATUS_HISTORY_MAX) {
+    const next = [...(existing ?? []), entry];
+    if (next.length <= cap) {
+        return { history: next, truncatedCount: previousTruncatedCount };
+    }
+    const overflow = next.length - cap;
+    return {
+        history: next.slice(overflow),
+        truncatedCount: previousTruncatedCount + overflow,
+    };
+}
+/**
+ * The whole flow in one call: diff, and return the patch additions needed to
+ * record it. Returns `null` when no tracked field changed — the caller then
+ * writes its patch unchanged, so an untracked update never grows the array.
+ */
+export function withHistory(current, patch, opts) {
+    const changes = { ...diffTrackedFields(current, patch, opts.tracked), ...opts.extraChanges };
+    if (Object.keys(changes).length === 0)
+        return null;
+    const historyField = opts.historyField ?? "statusHistory";
+    const truncatedField = opts.truncatedField ?? "statusHistoryTruncated";
+    const entry = buildHistoryEntry({
+        actor: opts.actor,
+        trigger: opts.trigger,
+        changes,
+        reason: opts.reason,
+        note: opts.note,
+        now: opts.now,
+    });
+    const { history, truncatedCount } = appendHistoryEntry(readPath(current, historyField) ?? [], entry, readPath(current, truncatedField) ?? 0, opts.cap);
+    return {
+        ...patch,
+        [historyField]: history,
+        ...(truncatedCount > 0 ? { [truncatedField]: truncatedCount } : {}),
+    };
+}

package/dist/_internal/shared/history/index.d.ts

@@ -0,0 +1,4 @@
+export type { HistoryActorRole, HistoryActor, FieldChange, StatusChangeEntry, AppendHistoryResult, } from "./types";
+export { STATUS_HISTORY_MAX } from "./types";
+export type { BuildHistoryEntryInput } from "./history";
+export { diffTrackedFields, buildHistoryEntry, appendHistoryEntry, withHistory, } from "./history";

package/dist/_internal/shared/history/index.js

@@ -0,0 +1,2 @@
+export { STATUS_HISTORY_MAX } from "./types";
+export { diffTrackedFields, buildHistoryEntry, appendHistoryEntry, withHistory, } from "./history";

package/dist/_internal/shared/history/types.d.ts

@@ -0,0 +1,61 @@
+import type { FirestoreValue } from "../../../schemas/types";
+/**
+ * Generic entity status history — the shape shared by every entity that
+ * records how it got to its current state.
+ *
+ * Built for orders first (W2) and adopted by stores, payouts, offers, bids,
+ * support tickets, scammer profiles, catalogue approvals, shipments and
+ * returns in W15. Before this existed, exactly ONE of ~40 status-bearing
+ * entities had any history at all — `ads`, built inline in a route handler
+ * with no type and no reuse.
+ */
+export type HistoryActorRole = "buyer" | "seller" | "admin" | "system";
+export interface HistoryActor {
+    /** Firebase Auth uid. Absent for `system` (cron jobs, Firestore triggers). */
+    uid?: string;
+    role: HistoryActorRole;
+}
+/** A single field's before/after. `from` is `null` on the creation entry. */
+export interface FieldChange {
+    from: FirestoreValue;
+    to: FirestoreValue;
+}
+export interface StatusChangeEntry {
+    at: Date;
+    actorUid?: string;
+    actorRole: HistoryActorRole;
+    /**
+     * DELTA ONLY — the tracked fields that actually changed, never a copy of
+     * the whole document. A full snapshot per transition would duplicate the
+     * record on every status change; the whole point of this shape is that it
+     * does not.
+     */
+    changes: Record<string, FieldChange>;
+    /** Why, when a human supplied a reason (cancellation, rejection). */
+    reason?: string;
+    /** Free-text note from an admin/seller action. */
+    note?: string;
+    /**
+     * The function, route or job that caused the change — `"customShipOrder"`,
+     * `"paymentWindowTimeout"`, `"adminVerifyPayment"`. This is what the
+     * timeline renders by, which is why per-path events (proof uploaded,
+     * installment paid, winner revealed) need NO new status values.
+     */
+    trigger: string;
+}
+/**
+ * Cap for any history array. Matches `HISTORY_MAX`'s reasoning: an unbounded
+ * array on a hot document inflates every read of that document (Rule #6), and
+ * an order that changes status more than this has a different problem.
+ */
+export declare const STATUS_HISTORY_MAX = 50;
+export interface AppendHistoryResult {
+    history: StatusChangeEntry[];
+    /**
+     * How many entries have been dropped off the front across the document's
+     * lifetime. Surfaced so the UI can say "earlier history trimmed" instead
+     * of implying none existed — silent truncation reads as "this is all of
+     * it", which is the same lie as a silently dropped field.
+     */
+    truncatedCount: number;
+}