@mohasinac/appkit 4.13.1 → 4.15.0

package/dist/_internal/shared/features/homepage/section-gate.js

@@ -0,0 +1,51 @@
+/*
+ * WHY: The only code in the repo that gated homepage sections on
+ *      `siteSettings.featureFlags` lived inside `getHomepageInitial`, a
+ *      function with ZERO call sites — the live homepage
+ *      (`MarketplaceHomepageView`) reads `homepageSectionsRepository`
+ *      directly. So turning off the `auctions` flag hid auctions everywhere
+ *      except the homepage, which kept advertising them.
+ *
+ *      `getHomepageInitial` itself was deleted rather than wired up: its other
+ *      unique calls, `findActiveAuctions()` / `findActivePreOrders()`, are
+ *      unbounded `.get()` collection scans with no `.limit()`, which Rule #6
+ *      forbids. The gate is the only part worth keeping, so it moved here.
+ *
+ * EXPORTS: SECTION_FEATURE_GATE, filterSectionsByFeatureFlags
+ *
+ * @tag domain:homepage
+ * @tag layer:shared
+ * @tag pattern:none
+ * @tag access:isomorphic
+ * @tag consumers:MarketplaceHomepageView
+ * @tag sideEffects:none
+ */
+/** Section types that require a feature flag to be enabled to show on the homepage. */
+export const SECTION_FEATURE_GATE = {
+    auctions: "auctions",
+    "pre-orders": "preOrders",
+    events: "events",
+    "event-raffles": "events",
+    "prize-draws": "events",
+    "blog-articles": "blog",
+};
+/**
+ * Drop sections whose feature flag is off.
+ *
+ * A section type with no gate entry always passes, and a MISSING flag value
+ * counts as enabled (`!== false`) — the flags map is partial, and a section
+ * must not vanish just because an admin has never opened Site Settings.
+ */
+export function filterSectionsByFeatureFlags(sections, 
+// Not `Partial<Record<FeatureFlagKey, boolean>>`: two of the flag keys
+// (`listingTypes`, `categoryTypes`) hold nested per-type objects rather than
+// booleans. Neither is a gate key, so the `=== false` test below simply
+// never fires for them.
+flags) {
+    if (!flags)
+        return [...sections];
+    return sections.filter((section) => {
+        const flagKey = SECTION_FEATURE_GATE[section.type];
+        return !flagKey || flags[flagKey] !== false;
+    });
+}

package/dist/_internal/shared/features/offers/config.d.ts

@@ -0,0 +1,30 @@
+/**
+ * The floor, as a percentage of the listed price, below which an offer is
+ * rejected — used whenever a listing does not set its own `minOfferPercent`.
+ *
+ * 70, not 50. This resolves a real disagreement rather than picking a number:
+ * 70 is what `makeOffer` has always enforced, so a listing created through
+ * either seller editor (which seeded 50) has in practice behaved as 70 the whole
+ * time — the forms were lying to sellers. Lowering the server to 50 would
+ * silently loosen the rule on every listing that already exists; raising the
+ * forms to 70 changes only what new listings are seeded with and makes the UI
+ * honest about the rule already in force.
+ */
+export declare const DEFAULT_MIN_OFFER_PERCENT = 70;
+/**
+ * The lowest amount this listing will accept as an offer.
+ *
+ * Rounded UP to the paisa, so the returned value always satisfies the
+ * percentage rule it was derived from — rounding down could return a number
+ * fractionally below the true floor, which the server would then reject while
+ * the UI displayed it as the minimum.
+ */
+export declare function minOfferAmount(listedPrice: number, percent?: number | null): number;
+/**
+ * Whether `amount` is a legal offer on a listing priced at `listedPrice`.
+ *
+ * Both bounds matter and both are enforced server-side: at or above the listed
+ * price there is nothing to negotiate (the buyer should use Add to Cart), and
+ * below the floor the seller has said they don't want to hear it.
+ */
+export declare function isOfferAmountValid(amount: number, listedPrice: number, percent?: number | null): boolean;

package/dist/_internal/shared/features/offers/config.js

@@ -0,0 +1,59 @@
+/*
+ * WHY: The minimum-offer rule had four independent implementations that did not
+ *      agree. `makeOffer` enforced a 70% floor rounded with
+ *      `Math.ceil(price * pct / 100 * 100) / 100`; `MakeOfferButton` computed
+ *      its own floor with `roundRupees()` and seeded the input from it; and both
+ *      seller editors wrote `minOfferPercent ?? 50` when the toggle was flipped
+ *      on. So the forms advertised a 50% floor the server would reject, and even
+ *      at a matching percentage the two rounding rules could differ by a rupee —
+ *      the button seeding an amount its own submit then bounced.
+ * WHAT: One percentage default and one floor function, imported by every gate.
+ *       Same discipline as `resolveMinBid` in the auctions config next door.
+ *
+ * EXPORTS:
+ *   DEFAULT_MIN_OFFER_PERCENT, minOfferAmount, isOfferAmountValid
+ *
+ * @tag domain:offers,seller
+ * @tag layer:shared
+ * @tag pattern:none
+ * @tag access:isomorphic
+ * @tag consumers:offer-actions,MakeOfferButton,ProductDetailPageView,ProductForm,SellerProductShell
+ * @tag sideEffects:none
+ */
+/**
+ * The floor, as a percentage of the listed price, below which an offer is
+ * rejected — used whenever a listing does not set its own `minOfferPercent`.
+ *
+ * 70, not 50. This resolves a real disagreement rather than picking a number:
+ * 70 is what `makeOffer` has always enforced, so a listing created through
+ * either seller editor (which seeded 50) has in practice behaved as 70 the whole
+ * time — the forms were lying to sellers. Lowering the server to 50 would
+ * silently loosen the rule on every listing that already exists; raising the
+ * forms to 70 changes only what new listings are seeded with and makes the UI
+ * honest about the rule already in force.
+ */
+export const DEFAULT_MIN_OFFER_PERCENT = 70;
+/**
+ * The lowest amount this listing will accept as an offer.
+ *
+ * Rounded UP to the paisa, so the returned value always satisfies the
+ * percentage rule it was derived from — rounding down could return a number
+ * fractionally below the true floor, which the server would then reject while
+ * the UI displayed it as the minimum.
+ */
+export function minOfferAmount(listedPrice, percent) {
+    const pct = typeof percent === "number" && Number.isFinite(percent) && percent > 0
+        ? percent
+        : DEFAULT_MIN_OFFER_PERCENT;
+    return Math.ceil(listedPrice * (pct / 100) * 100) / 100;
+}
+/**
+ * Whether `amount` is a legal offer on a listing priced at `listedPrice`.
+ *
+ * Both bounds matter and both are enforced server-side: at or above the listed
+ * price there is nothing to negotiate (the buyer should use Add to Cart), and
+ * below the floor the seller has said they don't want to hear it.
+ */
+export function isOfferAmountValid(amount, listedPrice, percent) {
+    return amount >= minOfferAmount(listedPrice, percent) && amount < listedPrice;
+}

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

@@ -24,18 +24,18 @@ export declare const createOrderSchema: z.ZodObject<{
         country: z.ZodDefault<z.ZodString>;
     }, "strip", z.ZodTypeAny, {
         country: string;
-        phone: string;
-        city: string;
         fullName: string;
+        phone: string;
         addressLine1: string;
+        city: string;
         state: string;
         pincode: string;
         addressLine2?: string | undefined;
     }, {
-        phone: string;
-        city: string;
         fullName: string;
+        phone: string;
         addressLine1: string;
+        city: string;
         state: string;
         pincode: string;
         country?: string | undefined;
@@ -47,10 +47,10 @@ export declare const createOrderSchema: z.ZodObject<{
     paymentMethod: "upi" | "razorpay" | "cod";
     shippingAddress: {
         country: string;
-        phone: string;
-        city: string;
         fullName: string;
+        phone: string;
         addressLine1: string;
+        city: string;
         state: string;
         pincode: string;
         addressLine2?: string | undefined;
@@ -64,10 +64,10 @@ export declare const createOrderSchema: z.ZodObject<{
 }, {
     paymentMethod: "upi" | "razorpay" | "cod";
     shippingAddress: {
-        phone: string;
-        city: string;
         fullName: string;
+        phone: string;
         addressLine1: string;
+        city: string;
         state: string;
         pincode: string;
         country?: string | undefined;

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";
     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;
@@ -335,6 +332,9 @@ export declare const preOrderInputSchema: z.ZodObject<{
     preOrderMaxQuantity?: number | undefined;
     preOrderProductionStatus?: "upcoming" | "in_production" | "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,88 @@
+/**
+ * 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>;
+    /**
+     * This entity's PII field names — pass the same list the repository hands
+     * to `encryptPiiFields` (`ORDER_PII_FIELDS`, `OFFER_PII_FIELDS`, …).
+     *
+     * 🛑 Not optional in spirit. `encryptPiiFields` is a FLAT top-level loop:
+     * it reads `doc[field]`, skips anything that is not a string, and never
+     * descends into arrays or nested objects. `statusHistory` is an array of
+     * objects, so a PII value that reaches `changes` is written to Firestore
+     * **in plaintext** and `mapDoc`'s decrypt never touches it on the way
+     * back out — a leak with no error and no visible symptom.
+     *
+     * Scrubbing here rather than at each call site is deliberate: a
+     * convention that says "don't put PII in history" is one forgetful
+     * adopter away from that leak, and 9 more entities adopt this primitive.
+     *
+     * SCOPE: this scrubs `changes` structurally, at any depth — a key whose
+     * NAME is PII is dropped. It cannot scrub `note`, which is free text the
+     * user themselves authored (a seller's counter-offer note). The rule
+     * there is a call-site one: pass the author's own text, never an identity
+     * field lifted off the document.
+     */
+    piiFields?: readonly string[];
+    historyField?: string;
+    truncatedField?: string;
+    now?: Date;
+    cap?: number;
+}): (TPatch & FirestoreDocument) | null;