@mohasinac/appkit 4.62.0 → 4.63.0

package/dist/features/admin/constants/site-settings-tabs.d.ts

@@ -102,7 +102,7 @@ export declare const SITE_SETTINGS_TABS: readonly [{
     readonly description: "Which listing types sellers may create, and their defaults.";
     readonly keywords: ["listing types", "auctions on", "enable", "categories"];
 }];
-export declare const SITE_SETTINGS_TAB_IDS: ("about" | "shipping" | "notifications" | "contact" | "auction" | "seo" | "listings" | "appearance" | "emi" | "gst" | "watermark" | "integrations" | "limits" | "announcement" | "branding" | "themes" | "fees" | "legal" | "procurement")[];
+export declare const SITE_SETTINGS_TAB_IDS: ("about" | "shipping" | "notifications" | "contact" | "auction" | "seo" | "listings" | "emi" | "legal" | "appearance" | "gst" | "watermark" | "integrations" | "limits" | "announcement" | "branding" | "themes" | "fees" | "procurement")[];
 /**
  * The union `?tab=` is validated against.
  *

package/dist/features/admin/hooks/useAdminListingData.js

@@ -2,6 +2,9 @@
 import { useQuery } from "@tanstack/react-query";
 import { apiClient, ApiClientError } from "../../../http/index.js";
 import { formatCurrency } from "../../../utils/number.formatter.js";
+// The defining module, not a barrel (Root Cause #18). `hasEncPrefix` is a pure
+// string test with no crypto in its import chain, so it is client-safe.
+import { hasEncPrefix } from "../../../security/pii-mask.js";
 function withQueryParams(endpoint, params) {
     const hasQuery = endpoint.includes("?");
     const query = new URLSearchParams(params).toString();
@@ -50,6 +53,19 @@ export function toRecordArray(value) {
 }
 export function toStringValue(value, fallback = "-") {
     if (typeof value === "string") {
+        /*
+         * 🛑 Ciphertext is not a display value. See the twin in
+         * `features/seller/hooks/useSellerListingData.ts` for the full account —
+         * the short version is that `mapDoc` does not decrypt, so a route that
+         * forgets `revealOrders`/`maskedOrders` hands this a stored `enc:v1:…`
+         * blob which is a perfectly ordinary `string` and renders verbatim.
+         *
+         * `/api/admin/orders` already hit this ("measured live at 3 visible
+         * `enc:v1:` strings") and fixed it at the route. This is the backstop for
+         * the next one.
+         */
+        if (hasEncPrefix(value))
+            return fallback;
         return value.trim() || fallback;
     }
     if (typeof value === "number" || typeof value === "boolean") {

package/dist/features/admin/schemas/admin-user-form.d.ts

@@ -82,13 +82,13 @@ export declare const lotteryPullSchema: z.ZodObject<{
     userPhone: z.ZodUnion<[z.ZodOptional<z.ZodString>, z.ZodLiteral<"">]>;
 }, "strip", z.ZodTypeAny, {
     transactionId: string;
-    sourceType: "event" | "product";
+    sourceType: "product" | "event";
     paymentTime: string;
     purchasedItemNumber: number;
     userPhone?: string | undefined;
 }, {
     transactionId: string;
-    sourceType: "event" | "product";
+    sourceType: "product" | "event";
     paymentTime: string;
     purchasedItemNumber: number;
     userPhone?: string | undefined;

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

@@ -3,6 +3,7 @@
  * Covers: notifications, chat rooms, site settings
  */
 import type { AboutContentDocument } from "../../about/schemas/firestore";
+import type { RateChange } from "../../../_internal/shared/features/pricing/rate-registry";
 export declare const ADMIN_CHECKOUT_BYPASS_FLAG_KEY: "adminCheckoutBypass";
 export declare const NOTIFICATION_TYPE_VALUES: readonly ["order_placed", "order_confirmed", "order_shipped", "order_delivered", "order_cancelled", "bid_placed", "bid_outbid", "bid_won", "bid_lost", "auction_ended", "review_approved", "review_replied", "product_available", "promotion", "system", "welcome", "account_action", "support_ticket_update", "scam_report_update", "offer_received", "offer_responded", "offer_expired", "offer_counter_accepted", "refund_initiated", "prize_won", "prize_reveal_expired", "emi_installment_due_soon", "emi_installment_overdue", "payment_review", "catalogue_images_stale", "message_received"];
 export type NotificationType = (typeof NOTIFICATION_TYPE_VALUES)[number];
@@ -233,6 +234,18 @@ export type SiteSettingsAdPlacement = {
     label: string;
     enabled: boolean;
     reservedHeight: number;
+    /**
+     * D56 — the flat monthly rate for a self-serve booking of this slot, in
+     * rupees. Absent means NOT SOLD: `bookAdSlot` refuses rather than
+     * defaulting to zero, because a free booking that looks successful takes
+     * the slot, bills nothing, and says nothing about the missing price.
+     *
+     * 🛑 Editing this does NOT reprice a sold slot. `AdBookingDocument.priceRs`
+     * is snapshotted at booking, for the same reason `sourceContext` is
+     * written once: the rate is a price somebody agreed to, and re-deriving it
+     * later silently rewrites a completed sale.
+     */
+    priceRsPerPeriod?: number;
 };
 /** Embedded in siteSettings.adSettings — a type alias, not a collection root. */
 export type SiteSettingsAdInventoryItem = {
@@ -690,6 +703,36 @@ export interface SiteSettingsDocument extends BaseDocument {
     returns: {
         windowDays: number;
     };
+    /**
+     * The support integration's on/off switch.
+     *
+     * 🛑 The ONLY new integration flag. The other three the admin page switches
+     * already have an authoritative field — `payment.razorpayEnabled`,
+     * `messaging.emailEnabled` (which `guardSend` reads), and
+     * `shipping.provider`. Adding a parallel `integrationSwitches.*` beside
+     * those would be a denormalised mirror that drifts the first time one path
+     * writes only one of a pair (Root Cause #42), and the page would then
+     * disagree with the code that enforces it. The page is a VIEW over the real
+     * fields; this is the one field that did not exist.
+     *
+     * 🛑 Also not under `siteSettings.integrations` — that key is live and holds
+     * analytics/tag IDs (GA, FB Pixel, GTM).
+     *
+     * OFF hides the WHOLE support surface from BUYERS: no nav entry, no ticket
+     * list, no contact form. Staff keep full access, so an open ticket is still
+     * workable and the employee pay-per-ticket basis survives.
+     *
+     * 🛑 A buyer mid-conversation loses sight of their thread. That is the
+     * owner's decision, accepted knowingly — and the admin row must SAY it
+     * rather than implying the switch only stops new tickets.
+     *
+     * Defaults to `true`: support being reachable is the safe state, and a
+     * settings document written before this field existed must not read as
+     * "support is off".
+     */
+    support: {
+        enabled: boolean;
+    };
     faq: {
         variables: {
             shippingDays: number;
@@ -808,6 +851,25 @@ export interface SiteSettingsDocument extends BaseDocument {
      * opt-in and require the corresponding credentials to be set.
      */
     notificationChannels?: NotificationChannelConfig;
+    /**
+     * The rate-change log behind `/admin/pricing`. Append-only, newest FIRST,
+     * capped at `RATE_CHANGE_LOG_MAX`.
+     *
+     * 🛑 **An array on the singleton rather than a collection, deliberately.**
+     * The page's only query is "the recent history of these 16 rates", which is
+     * one document read — and the rates themselves already live here, so a
+     * separate collection would mean two reads to render one table and two
+     * writes to record one change. It is capped for the same reason
+     * `statusHistory` is: an uncapped array on a hot singleton eventually makes
+     * every settings read expensive.
+     *
+     * 🛑 **Not an audit trail, and not a substitute for one.** A `pricing_update`
+     * row also goes to `adminAuditLog`, which is queryable and answers "what
+     * have admins done lately". This answers the narrower question the pricing
+     * page asks — "when did THIS rate last move, and to what" — and it is the
+     * one a truncation can safely lose.
+     */
+    rateChanges?: RateChange[];
 }
 export declare const SITE_SETTINGS_COLLECTION: "siteSettings";
 export declare const SITE_SETTINGS_INDEXED_FIELDS: readonly [];

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

@@ -377,6 +377,11 @@ export const DEFAULT_SITE_SETTINGS_DATA = {
     returns: {
         windowDays: 7,
     },
+    // Reachable is the safe default, and an older settings document with no
+    // `support` group must not read as "support is off".
+    support: {
+        enabled: true,
+    },
     announcementBar: {
         enabled: true,
         message: "🎉 Up to 15% Off on Pokémon TCG this week — Use code SAVE15",

package/dist/features/ads/schemas/booking-write.d.ts

@@ -0,0 +1,120 @@
+/**
+ * The write contract for a self-serve ad booking.
+ *
+ * ## 🛑 The shape cannot express moderation, payment or price
+ *
+ * This is Root Cause #76's rule applied to a surface where the submitter is
+ * a member of the public rather than an admin, which makes it sharper: an
+ * advertiser who can send `moderation: { state: "approved" }` has not
+ * bypassed a check, they have *become* the check. A schema that merely
+ * VALIDATED the field would still let `"approved"` through — the field has
+ * to be unrepresentable, so `.strict()` turns it into a 400 instead of
+ * something the server has to remember to overwrite.
+ *
+ * Same for `priceRs` (the server reads the rate card; a client-supplied
+ * price is a ₹1 banner) and `paymentState` (a booking that declares itself
+ * paid is a free slot).
+ *
+ * `placementId` and `period` ARE accepted: they are what is being bought,
+ * and they are also the booking's identity, so the conflict they can cause
+ * is a document collision rather than a validation question.
+ */
+import { z } from "zod";
+/**
+ * 🛑 Creative fields are bounded, and `ctaHref` is http(s)-only.
+ *
+ * An unbounded `body` is a storage cost per booking and a layout break on
+ * every page carrying the slot. A `javascript:` or `data:` CTA is script
+ * execution on every page the creative renders on, submitted by a member of
+ * the public — this is the one field on this schema where a miss is a
+ * security defect rather than a tidiness one.
+ */
+export declare const httpUrl: z.ZodEffects<z.ZodString, string, string>;
+export declare const adBookingCreativeSchema: z.ZodObject<{
+    title: z.ZodString;
+    body: z.ZodOptional<z.ZodString>;
+    imageUrl: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
+    ctaLabel: z.ZodOptional<z.ZodString>;
+    ctaHref: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
+}, "strict", z.ZodTypeAny, {
+    title: string;
+    body?: string | undefined;
+    imageUrl?: string | undefined;
+    ctaLabel?: string | undefined;
+    ctaHref?: string | undefined;
+}, {
+    title: string;
+    body?: string | undefined;
+    imageUrl?: string | undefined;
+    ctaLabel?: string | undefined;
+    ctaHref?: string | undefined;
+}>;
+export declare const adBookingWriteSchema: z.ZodObject<{
+    placementId: z.ZodString;
+    period: z.ZodEffects<z.ZodString, string, string>;
+    creative: z.ZodObject<{
+        title: z.ZodString;
+        body: z.ZodOptional<z.ZodString>;
+        imageUrl: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
+        ctaLabel: z.ZodOptional<z.ZodString>;
+        ctaHref: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
+    }, "strict", z.ZodTypeAny, {
+        title: string;
+        body?: string | undefined;
+        imageUrl?: string | undefined;
+        ctaLabel?: string | undefined;
+        ctaHref?: string | undefined;
+    }, {
+        title: string;
+        body?: string | undefined;
+        imageUrl?: string | undefined;
+        ctaLabel?: string | undefined;
+        ctaHref?: string | undefined;
+    }>;
+}, "strict", z.ZodTypeAny, {
+    placementId: string;
+    period: string;
+    creative: {
+        title: string;
+        body?: string | undefined;
+        imageUrl?: string | undefined;
+        ctaLabel?: string | undefined;
+        ctaHref?: string | undefined;
+    };
+}, {
+    placementId: string;
+    period: string;
+    creative: {
+        title: string;
+        body?: string | undefined;
+        imageUrl?: string | undefined;
+        ctaLabel?: string | undefined;
+        ctaHref?: string | undefined;
+    };
+}>;
+export type AdBookingWriteInput = z.infer<typeof adBookingWriteSchema>;
+/**
+ * A moderator's verdict.
+ *
+ * 🛑 A rejection REQUIRES a note, for the same reason an admin offer-cancel
+ * does: without one the advertiser's next submission is the same creative
+ * again, and the moderator reviews it twice. An approval takes no note
+ * because there is nothing to say.
+ */
+export declare const adModerationSchema: z.ZodEffects<z.ZodObject<{
+    approve: z.ZodBoolean;
+    note: z.ZodOptional<z.ZodString>;
+}, "strict", z.ZodTypeAny, {
+    approve: boolean;
+    note?: string | undefined;
+}, {
+    approve: boolean;
+    note?: string | undefined;
+}>, {
+    approve: boolean;
+    note?: string | undefined;
+}, {
+    approve: boolean;
+    note?: string | undefined;
+}>;
+export type AdModerationInput = z.infer<typeof adModerationSchema>;

package/dist/features/ads/schemas/booking-write.js

@@ -0,0 +1,75 @@
+/**
+ * The write contract for a self-serve ad booking.
+ *
+ * ## 🛑 The shape cannot express moderation, payment or price
+ *
+ * This is Root Cause #76's rule applied to a surface where the submitter is
+ * a member of the public rather than an admin, which makes it sharper: an
+ * advertiser who can send `moderation: { state: "approved" }` has not
+ * bypassed a check, they have *become* the check. A schema that merely
+ * VALIDATED the field would still let `"approved"` through — the field has
+ * to be unrepresentable, so `.strict()` turns it into a 400 instead of
+ * something the server has to remember to overwrite.
+ *
+ * Same for `priceRs` (the server reads the rate card; a client-supplied
+ * price is a ₹1 banner) and `paymentState` (a booking that declares itself
+ * paid is a free slot).
+ *
+ * `placementId` and `period` ARE accepted: they are what is being bought,
+ * and they are also the booking's identity, so the conflict they can cause
+ * is a document collision rather than a validation question.
+ */
+import { z } from "zod";
+import { isAdPeriod } from "./firestore.js";
+/**
+ * 🛑 Creative fields are bounded, and `ctaHref` is http(s)-only.
+ *
+ * An unbounded `body` is a storage cost per booking and a layout break on
+ * every page carrying the slot. A `javascript:` or `data:` CTA is script
+ * execution on every page the creative renders on, submitted by a member of
+ * the public — this is the one field on this schema where a miss is a
+ * security defect rather than a tidiness one.
+ */
+/*
+ * Exported so `creative-form.ts` reuses the REFINEMENT rather than restating
+ * it — the form and the wire must agree on what a link is, and a second copy
+ * of a security check is a second thing to forget.
+ */
+export const httpUrl = z
+    .string()
+    .url()
+    .refine((u) => /^https?:\/\//i.test(u), "Links must start with http:// or https://");
+export const adBookingCreativeSchema = z
+    .object({
+    title: z.string().min(2).max(80),
+    body: z.string().max(200).optional(),
+    imageUrl: httpUrl.optional(),
+    ctaLabel: z.string().max(40).optional(),
+    ctaHref: httpUrl.optional(),
+})
+    .strict();
+export const adBookingWriteSchema = z
+    .object({
+    placementId: z.string().min(1).max(80),
+    period: z.string().refine(isAdPeriod, "Pick a month, as YYYY-MM."),
+    creative: adBookingCreativeSchema,
+})
+    .strict();
+/**
+ * A moderator's verdict.
+ *
+ * 🛑 A rejection REQUIRES a note, for the same reason an admin offer-cancel
+ * does: without one the advertiser's next submission is the same creative
+ * again, and the moderator reviews it twice. An approval takes no note
+ * because there is nothing to say.
+ */
+export const adModerationSchema = z
+    .object({
+    approve: z.boolean(),
+    note: z.string().max(300).optional(),
+})
+    .strict()
+    .refine((v) => v.approve || (v.note?.trim().length ?? 0) >= 10, {
+    message: "Say why it was rejected — the advertiser sees this and will resubmit without it.",
+    path: ["note"],
+});

package/dist/features/ads/schemas/creative-form.d.ts

@@ -0,0 +1,18 @@
+import { z } from "zod";
+export declare const adCreativeFormSchema: z.ZodObject<{
+    title: z.ZodString;
+    body: z.ZodOptional<z.ZodString>;
+    ctaLabel: z.ZodOptional<z.ZodString>;
+    ctaHref: z.ZodOptional<z.ZodUnion<[z.ZodLiteral<"">, z.ZodEffects<z.ZodString, string, string>]>>;
+}, "strip", z.ZodTypeAny, {
+    title: string;
+    body?: string | undefined;
+    ctaLabel?: string | undefined;
+    ctaHref?: string | undefined;
+}, {
+    title: string;
+    body?: string | undefined;
+    ctaLabel?: string | undefined;
+    ctaHref?: string | undefined;
+}>;
+export type AdCreativeFormValues = z.infer<typeof adCreativeFormSchema>;

package/dist/features/ads/schemas/creative-form.js

@@ -0,0 +1,51 @@
+/*
+ * WHY: `/advertise` rendered four hand-wired `<FieldInput>`s inside a bare
+ *      `<Form>`, so the advertiser's creative had no client-side bounds at
+ *      all — the only limits were the ones `adBookingCreateSchema` enforces
+ *      server-side, which the visitor meets as a 400 after submitting. A
+ *      headline is the single most visible string this platform renders to
+ *      strangers; it should not be the one field with no feedback until POST.
+ *
+ * WHAT: The FLAT form shape for the booking creative, annotated so
+ *       `buildSectionsFromSchema` produces the fields. The wire shape nests
+ *       these under `creative` (see `booking-write.ts`); the page lifts them
+ *       at submit.
+ *
+ * 🛑 It deliberately does NOT carry `placementId` or `period`. Those are
+ * chosen by clicking a month in the rate card, not typed — and more to the
+ * point, a slot whose availability the server has already decided must not
+ * become a text input the advertiser can edit. The booking id IS the lock
+ * (`adBookingId`), so a typed period is a way to aim at somebody else's slot.
+ *
+ * 🛑 Bounds mirror `adCreativeSchema` exactly. Two numbers that merely happen
+ * to agree today would drift into a form that accepts what the route refuses,
+ * which is the worse of the two failures: it looks like a server fault.
+ *
+ * EXPORTS: adCreativeFormSchema, type AdCreativeFormValues
+ *
+ * @tag domain:ads
+ * @tag layer:schema
+ * @tag pattern:none
+ * @tag access:isomorphic
+ * @tag consumers:/advertise
+ * @tag sideEffects:none
+ */
+import { z } from "zod";
+import { annotate } from "../../shell/field-ui-meta.js";
+import { httpUrl } from "./booking-write.js";
+export const adCreativeFormSchema = z.object({
+    title: annotate(z.string().trim().min(2, "A headline is required.").max(80, "Keep the headline under 80 characters."), { section: "creative", sectionLabel: "Your creative", sectionRequired: true, quick: true, order: 1, row: "full" }),
+    body: annotate(z.string().trim().max(200, "Keep the body under 200 characters.").optional(), { section: "creative", order: 2, row: "full", kind: "textarea" }),
+    ctaLabel: annotate(z.string().trim().max(40, "Keep the button text under 40 characters.").optional(), { section: "creative", order: 3, row: "pair" }),
+    /*
+     * 🛑 `httpUrl`, the same refinement the wire schema uses — a `javascript:`
+     * or `data:` CTA on a page we render to strangers is stored XSS with our
+     * own domain's credibility behind it. An empty string is allowed through so
+     * clearing the field is not an error; the page drops it before POST.
+     */
+    ctaHref: annotate(z.union([z.literal(""), httpUrl]).optional(), {
+        section: "creative",
+        order: 4,
+        row: "pair",
+    }),
+});

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

@@ -0,0 +1,140 @@
+/**
+ * D56 — a SELF-SERVE ad booking: one advertiser, one placement, one period.
+ *
+ * ## 🛑 Flat fee per slot per period, and explicitly NOT CPM
+ *
+ * Impression counting is a write per page view, which is the exact cost
+ * pattern that suspended this project (Root Cause #104: 3.1M ISR writes
+ * against a 200K allowance, 52.52 GB of Fast Origin Transfer against 10 GB,
+ * for eleven monthly active users). A flat fee is one write per BOOKING.
+ * Nothing here counts anything per render, and nothing should be added that
+ * does.
+ *
+ * ## Why a PERIOD rather than an arbitrary date range
+ *
+ * The plan's requirement is slot-availability locking — two advertisers must
+ * not book the same slot for overlapping dates. Firestore has no range
+ * constraint, so an arbitrary `startAt`/`endAt` pair can only be checked by
+ * QUERYING for overlaps and then writing, and two concurrent bookings both
+ * read "no overlap" and both write. That race is invisible in testing and
+ * sells the same slot twice.
+ *
+ * Discretising to a period makes the conflict a DOCUMENT COLLISION instead:
+ * the booking id is derived from `(placementId, period)`, so the second
+ * writer fails on an existing document inside its own transaction and
+ * Firestore does the locking. There is no query to race against.
+ *
+ * It also matches what is being sold. "The homepage banner for November" is
+ * the product; "the homepage banner from the 9th to the 23rd" is a pricing
+ * model nobody asked for and an availability calendar nobody can render.
+ */
+import type { BaseDocument } from "../../../_internal/shared/types/base-document";
+export declare const AD_BOOKING_COLLECTION = "adBookings";
+/**
+ * A calendar month, `YYYY-MM`.
+ *
+ * 🛑 A STRING, not a Date. It is an identity — half of the booking's primary
+ * key — and a Date would make "the same month" a comparison rather than an
+ * equality, which is precisely what the document-collision lock depends on
+ * not being.
+ */
+export type AdPeriod = string;
+export declare function isAdPeriod(value: string): value is AdPeriod;
+/** The period a date falls in, in UTC. */
+export declare function adPeriodOf(date: Date): AdPeriod;
+/** First instant of a period, UTC. */
+export declare function adPeriodStart(period: AdPeriod): Date;
+/** First instant of the NEXT period — the exclusive end. */
+export declare function adPeriodEnd(period: AdPeriod): Date;
+/**
+ * 🛑 The booking id IS the lock. Derived, never generated.
+ *
+ * Two advertisers booking `banner-home` for `2026-11` compute the same id and
+ * the second `tx.create` throws `ALREADY_EXISTS` — which is the whole
+ * availability guarantee, enforced by Firestore rather than by a check
+ * somebody could forget to run.
+ */
+export declare function adBookingId(placementId: string, period: AdPeriod): string;
+/**
+ * Payment state. Deliberately coarse: this records whether the slot is PAID
+ * FOR, not how. The invoice and the ledger posting are Part 4's job and carry
+ * the detail; duplicating any of it here would be two records of one fact.
+ */
+export declare const AD_BOOKING_PAYMENT_STATES: readonly ["unpaid", "paid", "refunded"];
+export type AdBookingPaymentState = (typeof AD_BOOKING_PAYMENT_STATES)[number];
+/**
+ * Creative moderation. **Nothing renders on the site until `approved`.**
+ *
+ * 🛑 `pending` is the initial value and there is no way to write `approved`
+ * through the advertiser's own schema — see `adBookingWriteSchema`. A
+ * self-serve flow where the submitter can set their own moderation state is
+ * not moderated; it is a form with an extra field (Root Cause #76 — a field
+ * the form can send is a field the form can destroy, here inverted into a
+ * field the form can grant itself).
+ */
+export declare const AD_MODERATION_STATES: readonly ["pending", "approved", "rejected"];
+export type AdModerationState = (typeof AD_MODERATION_STATES)[number];
+export interface AdBookingCreative {
+    title: string;
+    body?: string;
+    imageUrl?: string;
+    ctaLabel?: string;
+    ctaHref?: string;
+}
+export interface AdBookingDocument extends BaseDocument {
+    /** Matches a `SiteSettingsAdPlacement.id`. */
+    placementId: string;
+    period: AdPeriod;
+    /** Auth uid of the advertiser. */
+    advertiserUid: string;
+    /** Denormalised for the admin queue — a moderator should not fan out to `users`. */
+    advertiserName?: string;
+    /**
+     * Rupees, SNAPSHOTTED at booking.
+     *
+     * 🛑 Never recomputed from the live rate card. The rate is a price the
+     * advertiser agreed to; re-deriving it at render or invoice time would
+     * silently reprice a sold slot the first time an admin edits the card —
+     * the same rule `sourceContext` follows for order provenance.
+     */
+    priceRs: number;
+    paymentState: AdBookingPaymentState;
+    /** Set by the Part 4 invoicing path once the booking is billed. */
+    invoiceId?: string;
+    creative: AdBookingCreative;
+    moderation: {
+        state: AdModerationState;
+        /** Required on a rejection — see `moderateAdCreative`. */
+        note?: string;
+        reviewedAt?: Date;
+        /**
+         * Staff uid. 🛑 Never returned to the advertiser: who rejected you is
+         * not information a self-serve submitter needs, and naming an individual
+         * moderator invites them being contacted directly.
+         */
+        reviewedBy?: string;
+    };
+    /** Set when an admin or the advertiser cancels. A cancelled booking frees nothing — see below. */
+    cancelledAt?: Date;
+    cancelledReason?: string;
+}
+/**
+ * Does this booking put a creative on the page right now?
+ *
+ * 🛑 All four conditions, and the order is not an accident — moderation is
+ * checked before the calendar so an approved-but-future booking and an
+ * unreviewed current one are distinguishable in a debugger.
+ */
+export declare function isAdBookingLive(booking: Pick<AdBookingDocument, "moderation" | "paymentState" | "period" | "cancelledAt">, now?: Date): boolean;
+/**
+ * 🛑 A cancelled booking KEEPS its document, and therefore keeps the slot
+ * locked for its own period.
+ *
+ * Deleting it would free the slot — which sounds like the point and is the
+ * wrong behaviour twice over: the advertiser has paid for a period that has
+ * possibly already started, and re-selling a month mid-flight means two
+ * creatives were live in one slot at different times with one invoice
+ * between them. Freeing a period is an ADMIN act (`releaseAdSlot`), done
+ * knowingly, not a side effect of a cancel button.
+ */
+export declare const AD_BOOKING_CANCELLED_KEEPS_SLOT = true;