@mohasinac/appkit 4.63.5 → 4.64.0

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

@@ -9,6 +9,78 @@ import type { LotteryConfig } from "../../lottery/types";
 import type { Encrypted, Plaintext } from "../../../security/encrypted";
 export declare const EVENTS_COLLECTION: "events";
 export declare const EVENT_ENTRIES_COLLECTION: "eventEntries";
+/**
+ * Shared by both placements: which slide this event owns, and how prominent.
+ *
+ * `order` is the slide's position in the hero rail. `active` is what decides
+ * whether it renders at all — and it is capped downstream, not here: the rail
+ * shows at most `MAX_ACTIVE_SLIDES` (5), and `buildSlideFromEvent` refuses
+ * loudly rather than emitting a sixth that would never be seen.
+ */
+interface EventCarouselBase {
+    /** Slide order in the hero rail. Lower is earlier. */
+    order?: number;
+    /** Whether the generated slide is live. Absent means false — opt in. */
+    active?: boolean;
+    /**
+     * Background image slug for the slide. Defaults to the event's own
+     * `coverImage` when absent, which is usually what you want: the slide and
+     * the page it links to then read as one promotion.
+     *
+     * 🛑 A cover is cropped at `banner` (1200x600) and a hero background wants
+     * `hero` (1920x860). Naming a dedicated hero slug here is the difference
+     * between a sharp full-bleed backdrop and a 1200px image upscaled across it.
+     */
+    backgroundMediaSlug?: string;
+    /** Dim applied over the background so inverse ink stays readable. 0–1. */
+    dimOpacity?: number;
+}
+/**
+ * One headline, one line of copy, one button, centred over the background.
+ * The right shape for a single offer with a single call to action.
+ */
+export interface EventCarouselOverlayConfig extends EventCarouselBase {
+    placement: "overlay";
+    /** Small uppercase line above the headline — a date, a status, a hook. */
+    eyebrow?: string;
+    /** The headline. Kept short: it renders at up to 6rem on a wide screen. */
+    title: string;
+    description?: string;
+    buttonText?: string;
+}
+/**
+ * Up to six independently-linked tiles in a 2x3 grid.
+ *
+ * This is what makes one slide able to advertise several deals at once —
+ * each card is its own background, its own copy and its own destination, so
+ * three sale events can share a single slide instead of consuming three of
+ * the five available.
+ */
+export interface EventCarouselCardsConfig extends EventCarouselBase {
+    placement: "cards";
+    /**
+     * 🛑 Max SIX. Zones are 1–6 over a 2-row x 3-column grid (row 1 = 1·2·3,
+     * row 2 = 4·5·6) and `HeroCarousel` slices to 6 — a seventh card is
+     * silently dropped, so it is refused at build time instead.
+     */
+    cards: EventCarouselCard[];
+}
+/** One tile. Mirrors `CarouselCard` but without the stored-slide plumbing. */
+export interface EventCarouselCard {
+    /** 1–3 is the top row, 4–6 the bottom. Desktop only — a phone lays these
+     *  out in document order, one per row. */
+    zone: 1 | 2 | 3 | 4 | 5 | 6;
+    /** Background image slug for this tile. */
+    mediaSlug?: string;
+    dimOpacity?: number;
+    eyebrow?: string;
+    title?: string;
+    description?: string;
+    /** Where the tile's button goes. Absent uses the event's own detail page. */
+    href?: string;
+    buttonText?: string;
+}
+export type EventCarouselConfig = EventCarouselOverlayConfig | EventCarouselCardsConfig;
 export interface EventDocument extends BaseDocument {
     /** Normalized edge-n-gram search field — see appkit/src/utils/search-txt.ts. */
     searchTxt?: string[];
@@ -63,6 +135,28 @@ export interface EventDocument extends BaseDocument {
      * renderer, on purpose.
      */
     couponIds?: string[];
+    /**
+     * How this event presents itself as a homepage carousel slide.
+     *
+     * An event is the natural owner of its own promo artwork: authoring the
+     * slide here rather than in a separate `carouselSlides` document means the
+     * two cannot drift, which they did — the live Diwali slide and its event
+     * page carried different headline copy for weeks because each was edited
+     * separately.
+     *
+     * `buildSlideFromEvent()` is the one function that turns this into a
+     * `CarouselSlideDocument`; both the seed and `push-editorial-content.mjs`
+     * call it, so there is no second rendering of the same intent.
+     *
+     * 🛑 A DISCRIMINATED UNION ON `placement`, NOT TWO OPTIONAL ARRAYS. A slide's
+     * overlay and its cards are sibling `POSITION_FILL` elements — they stack on
+     * exactly the same pixels, so a slide carrying both renders its text twice,
+     * overlapping. Making that unrepresentable is why this is a union;
+     * `push-editorial-content.mjs` had to enforce the same rule imperatively by
+     * nulling the opposite field on every merge-write, which only works for as
+     * long as everyone remembers to do it.
+     */
+    carouselConfig?: EventCarouselConfig;
     saleConfig?: SaleConfig;
     offerConfig?: OfferConfig;
     pollConfig?: PollConfig;
@@ -131,6 +225,22 @@ export interface EventDocument extends BaseDocument {
         totalEntries: number;
         approvedEntries: number;
         flaggedEntries: number;
+        /**
+         * Likes. The public social signal, shown on the card and the detail hero
+         * in place of the entry count — nobody "enters" a cashback code, so
+         * `totalEntries` was structurally 0 on every `offer` and `sale` event
+         * while still being rendered as "0 entries".
+         *
+         * 🛑 OPTIONAL, and readers must treat absent as 0. Every event written
+         * before this field existed has no value for it, so a Firestore
+         * `orderBy("stats.likeCount")` would EXCLUDE all of them (Root Cause
+         * #100) — sort likes in memory, never in the query.
+         *
+         * Written only by `eventLikesRepository.toggle`, inside the same
+         * transaction that creates or deletes the like row, so the count and the
+         * membership cannot disagree.
+         */
+        likeCount?: number;
     };
     createdBy: string;
 }
@@ -292,3 +402,4 @@ export declare const eventQueryHelpers: {
     readonly withRaffle: () => readonly ["hasRaffle", "==", true];
     readonly raffleNotYetDrawn: () => readonly ["raffleWinnerUserId", "==", null];
 };
+export {};

package/dist/features/events/schemas/likes.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Event likes — the public "N people like this" signal, and who.
+ *
+ * ## Why this replaced "participants" on public surfaces
+ *
+ * Every event card and the detail hero showed `stats.totalEntries` as
+ * "N entries". For a raffle or a poll an entry is a real thing; for an
+ * `offer` or a `sale` nobody "enters" a cashback code, so the number was
+ * structurally 0 and the label meant nothing. A like works on every event
+ * type, which an entry cannot.
+ *
+ * Entries are NOT replaced anywhere they are real — participate, leaderboard
+ * and every admin surface still read `eventEntries`. This is a second,
+ * lighter signal beside them, not a rename of the first.
+ *
+ * ## 🛑 The document id IS the idempotency key
+ *
+ * `{eventId}__{userId}`, the `courierVoteId` precedent. A like is a `.set()`,
+ * an unlike is a `.delete()`, and "have I liked this" is a single
+ * `.doc(id).get()` — no query, no index, no transaction needed to dedupe.
+ *
+ * The alternative considered and rejected was the review-helpful shape, an
+ * `likedBy[]` array on the event document. It has no un-vote by design (see
+ * `voteHelpful`'s own comment) and it caps out at Firestore's 1 MiB document
+ * limit, which is a real ceiling for a popular event and a silent one.
+ *
+ * ## 🛑 No denormalised name or email on this row
+ *
+ * Only `userId`. `enterEvent` denormalises `userDisplayName`/`userEmail` onto
+ * an entry and both are then PII-encrypted, masked on read, and must be
+ * stripped by every projection that touches them. A likes row is read on a
+ * PUBLIC surface by definition, so the cheapest way to never leak a field is
+ * to not store it: the display name and avatar are joined from the user's own
+ * public projection at read time instead.
+ *
+ * @tag domain:events
+ * @tag layer:schema
+ */
+import type { BaseDocument } from "../../../_internal/shared/types/base-document";
+export declare const EVENT_LIKES_COLLECTION: "eventLikes";
+/**
+ * The deterministic id. A repeat like overwrites itself rather than
+ * double-counting; an unlike deletes exactly this document.
+ *
+ * 🛑 `__` matches `courierVoteId` and the tester-response id
+ * (`${testerId}__${checklistItemId}`). Firestore ids may not contain `/`, and
+ * a single `_` appears inside real uids — a double underscore does not.
+ */
+export declare function eventLikeId(eventId: string, userId: string): string;
+export interface EventLikeDocument extends BaseDocument {
+    eventId: string;
+    /** The Firebase Auth uid. The ONLY identity stored — see the header. */
+    userId: string;
+    createdAt: Date;
+}
+export declare const EVENT_LIKE_FIELDS: {
+    readonly EVENT_ID: "eventId";
+    readonly USER_ID: "userId";
+    readonly CREATED_AT: "createdAt";
+};
+/**
+ * A liker as a public visitor may see them.
+ *
+ * An explicit allow-list, never a spread of the user document: that document
+ * carries email, phone, role, addresses and store ownership, and a spread
+ * publishes every field nobody thought to delete — including fields the
+ * interface does not declare (Root Cause #70).
+ *
+ * `displayName` and `photoURL` are both in `USER_PUBLIC_FIELDS` and neither is
+ * in `USER_PII_FIELDS`; they already render on public profile pages, so this
+ * publishes nothing new.
+ */
+export interface PublicLiker {
+    uid: string;
+    displayName: string;
+    photoURL?: string;
+}
+/** How many faces the rail shows before "View all". */
+export declare const LIKERS_PREVIEW_LIMIT = 10;
+/** One page of the "everyone who liked this" modal. */
+export declare const LIKERS_PAGE_SIZE = 24;

package/dist/features/events/schemas/likes.js

@@ -0,0 +1,59 @@
+/**
+ * Event likes — the public "N people like this" signal, and who.
+ *
+ * ## Why this replaced "participants" on public surfaces
+ *
+ * Every event card and the detail hero showed `stats.totalEntries` as
+ * "N entries". For a raffle or a poll an entry is a real thing; for an
+ * `offer` or a `sale` nobody "enters" a cashback code, so the number was
+ * structurally 0 and the label meant nothing. A like works on every event
+ * type, which an entry cannot.
+ *
+ * Entries are NOT replaced anywhere they are real — participate, leaderboard
+ * and every admin surface still read `eventEntries`. This is a second,
+ * lighter signal beside them, not a rename of the first.
+ *
+ * ## 🛑 The document id IS the idempotency key
+ *
+ * `{eventId}__{userId}`, the `courierVoteId` precedent. A like is a `.set()`,
+ * an unlike is a `.delete()`, and "have I liked this" is a single
+ * `.doc(id).get()` — no query, no index, no transaction needed to dedupe.
+ *
+ * The alternative considered and rejected was the review-helpful shape, an
+ * `likedBy[]` array on the event document. It has no un-vote by design (see
+ * `voteHelpful`'s own comment) and it caps out at Firestore's 1 MiB document
+ * limit, which is a real ceiling for a popular event and a silent one.
+ *
+ * ## 🛑 No denormalised name or email on this row
+ *
+ * Only `userId`. `enterEvent` denormalises `userDisplayName`/`userEmail` onto
+ * an entry and both are then PII-encrypted, masked on read, and must be
+ * stripped by every projection that touches them. A likes row is read on a
+ * PUBLIC surface by definition, so the cheapest way to never leak a field is
+ * to not store it: the display name and avatar are joined from the user's own
+ * public projection at read time instead.
+ *
+ * @tag domain:events
+ * @tag layer:schema
+ */
+export const EVENT_LIKES_COLLECTION = "eventLikes";
+/**
+ * The deterministic id. A repeat like overwrites itself rather than
+ * double-counting; an unlike deletes exactly this document.
+ *
+ * 🛑 `__` matches `courierVoteId` and the tester-response id
+ * (`${testerId}__${checklistItemId}`). Firestore ids may not contain `/`, and
+ * a single `_` appears inside real uids — a double underscore does not.
+ */
+export function eventLikeId(eventId, userId) {
+    return `${eventId}__${userId}`;
+}
+export const EVENT_LIKE_FIELDS = {
+    EVENT_ID: "eventId",
+    USER_ID: "userId",
+    CREATED_AT: "createdAt",
+};
+/** How many faces the rail shows before "View all". */
+export const LIKERS_PREVIEW_LIMIT = 10;
+/** One page of the "everyone who liked this" modal. */
+export const LIKERS_PAGE_SIZE = 24;

package/dist/features/events/types/index.d.ts

@@ -148,6 +148,13 @@ export interface EventItem {
         totalEntries: number;
         approvedEntries: number;
         flaggedEntries: number;
+        /**
+         * Likes — the public social signal the card and hero render in place of
+         * the entry count. OPTIONAL: every event written before the field has
+         * no value, so readers must treat absent as 0 and must never sort on it
+         * in Firestore (an orderBy excludes documents lacking the field).
+         */
+        likeCount?: number;
     };
     createdBy: string;
     createdAt: string;

package/dist/features/events/utils/carousel-slide.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Turn an event's own `carouselConfig` into a hero-carousel slide.
+ *
+ * WHY THIS EXISTS: the homepage slide advertising an event and the event page
+ * it links to were authored in two different places — a `carouselSlides`
+ * document and an `events` document — with nothing tying them together. They
+ * drifted. The live Diwali slide read "Diwali: 10% cashback on every order"
+ * while its event page had been rebranded to "Diwali to New Year: Four Offers,
+ * Three Months", and neither edit knew about the other.
+ *
+ * So the event owns its promo, and this is the only function that renders that
+ * intent into a slide. The seed derives `carouselSlidesSeedData` through it;
+ * `scripts/push-editorial-content.mjs` pushes what the seed produced. Neither
+ * hand-writes a slide, so there is no second copy to drift from.
+ */
+import type { CarouselSlideDocument } from "../../homepage/schemas/firestore";
+import type { EventDocument } from "../schemas/firestore";
+export interface BuildSlideOptions {
+    /** The event's public detail path, e.g. `/events/festive-cashback-10`. */
+    eventHref: string;
+    /** Who the generated document records as its author. */
+    createdBy: string;
+}
+/**
+ * `null` when the event carries no `carouselConfig` — most events do not want
+ * a slide, and that is the normal case rather than an error.
+ *
+ * @throws when the config is internally impossible (more cards than zones).
+ *         Refusing loudly is deliberate: `HeroCarousel` silently `.slice(0, 6)`s,
+ *         so a seventh card would vanish with nothing to indicate it had been
+ *         authored at all.
+ */
+export declare function buildSlideFromEvent(event: EventDocument, opts: BuildSlideOptions): Partial<CarouselSlideDocument> | null;
+/**
+ * Build every event-owned slide, newest-ordered, and refuse an over-full rail.
+ *
+ * 🛑 `MAX_ACTIVE_SLIDES` is a real ceiling, not advice — `HeroCarousel` renders
+ * the first five and a sixth active slide is authored, stored, and never seen
+ * by anyone. Failing here is what makes that visible at seed time rather than
+ * as a silently missing promotion.
+ */
+export declare function buildSlidesFromEvents(events: readonly EventDocument[], resolveHref: (event: EventDocument) => string, createdBy: string): Partial<CarouselSlideDocument>[];

package/dist/features/events/utils/carousel-slide.js

@@ -0,0 +1,174 @@
+/**
+ * Turn an event's own `carouselConfig` into a hero-carousel slide.
+ *
+ * WHY THIS EXISTS: the homepage slide advertising an event and the event page
+ * it links to were authored in two different places — a `carouselSlides`
+ * document and an `events` document — with nothing tying them together. They
+ * drifted. The live Diwali slide read "Diwali: 10% cashback on every order"
+ * while its event page had been rebranded to "Diwali to New Year: Four Offers,
+ * Three Months", and neither edit knew about the other.
+ *
+ * So the event owns its promo, and this is the only function that renders that
+ * intent into a slide. The seed derives `carouselSlidesSeedData` through it;
+ * `scripts/push-editorial-content.mjs` pushes what the seed produced. Neither
+ * hand-writes a slide, so there is no second copy to drift from.
+ */
+import { MAX_ACTIVE_SLIDES } from "../../homepage/schemas/firestore.js";
+/** Matches the seeded slides; a slower rail is unreadable, a faster one is a blur. */
+const DEFAULT_AUTOPLAY_MS = 6000;
+const DEFAULT_DIM = 0.55;
+/** Zones are a 2-row x 3-column grid, so six is the ceiling. */
+const MAX_CARDS_PER_SLIDE = 6;
+/**
+ * `/media/<shortId>`, never `seedExtMedia()` and never a raw upstream URL.
+ *
+ * Root Cause #104: persisting `/api/media/ext?url=<third party>` makes every
+ * render a Node lambda plus an upstream fetch plus a sharp re-encode. ~400 of
+ * those contributed 52.52 GB of Fast Origin Transfer against a 10 GB allowance
+ * and suspended the project.
+ */
+function mediaUrl(slug) {
+    return `/media/${slug}`;
+}
+function background(slug, dim) {
+    if (!slug)
+        return undefined;
+    return {
+        type: "image",
+        url: mediaUrl(slug),
+        dimOverlay: { enabled: true, opacity: dim },
+    };
+}
+/**
+ * The background slug, preferring an explicitly-named hero crop.
+ *
+ * 🛑 Falling back to the event's `coverImage` is correct but lossy: a cover is
+ * fetched at `banner` (1200x600) while a hero background wants `hero`
+ * (1920x860), so the fallback upscales across a full-bleed slide. That is
+ * exactly what the live Diwali slide did. Name a hero slug when the slide
+ * matters; the fallback is there so a slide is never blank.
+ */
+function resolveBackgroundSlug(event) {
+    const cfg = event.carouselConfig;
+    if (cfg?.backgroundMediaSlug)
+        return cfg.backgroundMediaSlug;
+    const coverUrl = event.coverImage?.url ?? event.coverImageUrl;
+    if (!coverUrl)
+        return undefined;
+    // Already a `/media/<slug>` URL — recover the slug so we re-wrap it once.
+    const match = /^\/media\/([^/?#]+)$/.exec(coverUrl);
+    return match ? match[1] : undefined;
+}
+function toCard(card, eventHref, dim) {
+    return {
+        id: `card-zone-${card.zone}`,
+        zone: card.zone,
+        background: background(card.mediaSlug, card.dimOpacity ?? dim) ?? {
+            type: "color",
+            color: "var(--appkit-color-primary)",
+        },
+        content: {
+            eyebrow: card.eyebrow,
+            title: card.title,
+            description: card.description,
+        },
+        buttons: card.buttonText
+            ? [
+                {
+                    id: `card-zone-${card.zone}-cta`,
+                    text: card.buttonText,
+                    href: card.href ?? eventHref,
+                    variant: "primary",
+                },
+            ]
+            : [],
+        hover: { effect: "scale" },
+    };
+}
+/**
+ * `null` when the event carries no `carouselConfig` — most events do not want
+ * a slide, and that is the normal case rather than an error.
+ *
+ * @throws when the config is internally impossible (more cards than zones).
+ *         Refusing loudly is deliberate: `HeroCarousel` silently `.slice(0, 6)`s,
+ *         so a seventh card would vanish with nothing to indicate it had been
+ *         authored at all.
+ */
+export function buildSlideFromEvent(event, opts) {
+    const cfg = event.carouselConfig;
+    if (!cfg)
+        return null;
+    const dim = cfg.dimOpacity ?? DEFAULT_DIM;
+    const bg = background(resolveBackgroundSlug(event), dim);
+    const base = {
+        id: `slide-${event.id}`,
+        title: event.title,
+        order: cfg.order ?? 99,
+        active: cfg.active === true,
+        background: bg,
+        settings: { autoplayDelayMs: DEFAULT_AUTOPLAY_MS, height: "medium" },
+        createdBy: opts.createdBy,
+    };
+    if (cfg.placement === "cards") {
+        if (cfg.cards.length > MAX_CARDS_PER_SLIDE) {
+            throw new Error(`Event ${event.id}: ${cfg.cards.length} carousel cards, max is ${MAX_CARDS_PER_SLIDE} ` +
+                `(zones are a 2x3 grid). HeroCarousel slices to 6, so the extras would vanish silently.`);
+        }
+        const seenZones = new Set();
+        for (const c of cfg.cards) {
+            if (seenZones.has(c.zone)) {
+                throw new Error(`Event ${event.id}: two carousel cards both claim zone ${c.zone}. ` +
+                    `They would render stacked on the same grid cell.`);
+            }
+            seenZones.add(c.zone);
+        }
+        return {
+            ...base,
+            // 🛑 Empty overlay, not omitted. The two are sibling POSITION_FILL
+            // elements; a merge-write that leaves a previous overlay in place would
+            // paint it over the cards.
+            overlay: undefined,
+            cards: cfg.cards.map((c) => toCard(c, opts.eventHref, dim)),
+        };
+    }
+    return {
+        ...base,
+        cards: [],
+        overlay: {
+            enabled: true,
+            subtitle: cfg.eyebrow,
+            title: cfg.title,
+            description: cfg.description,
+            button: cfg.buttonText
+                ? {
+                    id: `slide-${event.id}-cta`,
+                    text: cfg.buttonText,
+                    link: opts.eventHref,
+                    variant: "primary",
+                    openInNewTab: false,
+                }
+                : undefined,
+        },
+    };
+}
+/**
+ * Build every event-owned slide, newest-ordered, and refuse an over-full rail.
+ *
+ * 🛑 `MAX_ACTIVE_SLIDES` is a real ceiling, not advice — `HeroCarousel` renders
+ * the first five and a sixth active slide is authored, stored, and never seen
+ * by anyone. Failing here is what makes that visible at seed time rather than
+ * as a silently missing promotion.
+ */
+export function buildSlidesFromEvents(events, resolveHref, createdBy) {
+    const slides = events
+        .map((e) => buildSlideFromEvent(e, { eventHref: resolveHref(e), createdBy }))
+        .filter((s) => s !== null)
+        .sort((a, b) => (a.order ?? 99) - (b.order ?? 99));
+    const activeCount = slides.filter((s) => s.active).length;
+    if (activeCount > MAX_ACTIVE_SLIDES) {
+        throw new Error(`${activeCount} active event slides but MAX_ACTIVE_SLIDES is ${MAX_ACTIVE_SLIDES}. ` +
+            `The extras would never render. Deactivate one, or fold several deals into ` +
+            `a single cards slide — that is what the 6 zones are for.`);
+    }
+    return slides;
+}

package/dist/features/events/utils/event-charts.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Chart specs for event pages — pure builders, no React, no recharts.
+ *
+ * Kept free of any import that reaches the DOM so a Server Component can call
+ * these and hand the result to `<Chart>`, whose own `"use client"` boundary is
+ * internal (`chart-spec.ts` is deliberately the same shape of module).
+ *
+ * ## 🛑 EVERY NUMBER HERE IS MEASURED, NOT ILLUSTRATIVE
+ *
+ * A chart asserts "we measured this". So each builder returns `null` rather
+ * than a plausible-looking shape when it has nothing real to plot — an absent
+ * chart says "not enough data yet", a flat or invented one says "we measured,
+ * and this is the result", which is a different and false claim.
+ *
+ * @tag domain:events
+ * @tag layer:utils
+ */
+import type { ChartSpec } from "../../../ui/components/chart-spec";
+import type { CouponDocument } from "../../promotions/schemas/firestore";
+import type { AttachedCoupon } from "../../promotions/constants/attached-coupons";
+/**
+ * Poll results as bars.
+ *
+ * The data already existed and was rendered as the plain string
+ * "12 votes (34%)" — `getEventPollResults` computes both server-side and
+ * `EventLeaderboard` printed them in a flex row. This is the same numbers,
+ * shaped so the differences between options are visible at a glance.
+ */
+export declare function buildPollChart(pollConfig: {
+    options?: {
+        id: string;
+        label: string;
+    }[];
+} | undefined, results: {
+    optionId: string;
+    count: number;
+}[] | undefined): ChartSpec | null;
+export declare function buildCouponSavingsChart(coupons: AttachedCoupon[]): ChartSpec | null;
+/**
+ * Likes over time. Data comes from `getLikeTrend`, which returns `null` below
+ * `LIKE_TREND_MIN_POINTS` so a two-like event plots nothing rather than a flat
+ * line with axes.
+ */
+export declare function buildLikeTrendChart(trend: {
+    categories: string[];
+    values: number[];
+} | null): ChartSpec | null;
+export interface SaleProgress {
+    /** 0–100, how far through the sale window we are. */
+    elapsedPercent: number;
+    /** Human remaining time, or null once it has ended. */
+    endsAt: Date | null;
+    /** 0–100 of a coupon's total redemption allowance, when one is capped. */
+    claimedPercent: number | null;
+    claimedLabel: string | null;
+}
+/**
+ * Time elapsed in the sale window, and redemptions against a real cap.
+ *
+ * 🛑 `claimedPercent` IS null UNLESS A REAL CAP EXISTS. `usage.totalLimit` is
+ * optional, and an uncapped coupon has no denominator — rendering a progress
+ * bar against an invented 100 would show a bar filling toward a limit nobody
+ * set. Absent is the honest state and the caller renders only the countdown.
+ */
+export declare function buildSaleProgress(startsAt: Date | undefined, endsAt: Date | undefined, coupon?: Pick<CouponDocument, "usage" | "code">, now?: Date): SaleProgress | null;