@mohasinac/appkit 4.62.1 → 4.63.0

package/dist/features/admin/components/AdminOrderEditorView.js

@@ -46,7 +46,7 @@ const CARRIER_OPTIONS = [
     { label: "Other", value: "Other" },
 ];
 // --- Component ---------------------------------------------------------------
-export function AdminOrderEditorView({ open, onClose, orderId, orderLabel, currentStatus, items, sourceContext, currency, paymentProofUrl, paymentTransactionId, paymentMethod, paymentStatus, displayedUpiId, buyerReportedUpiId, paymentUpiMismatch, buyerMarkedPaid, buyerFraudAgreementAccepted, paymentReviewOutcome, addons, }) {
+export function AdminOrderEditorView({ open, onClose, orderId, orderLabel, currentStatus, items, sourceContext, currency, paymentProofUrl, paymentTransactionId, paymentMethod, paymentStatus, displayedUpiId, buyerReportedUpiId, paymentUpiMismatch, buyerMarkedPaid, buyerFraudAgreementAccepted, paymentReviewOutcome, addons, balance, }) {
     const queryClient = useQueryClient();
     const { showToast } = useToast();
     const [draft, setDraft] = React.useState({
@@ -83,6 +83,19 @@ export function AdminOrderEditorView({ open, onClose, orderId, orderLabel, curre
     const [reviewNoteError, setReviewNoteError] = React.useState(null);
     const [isRequestingReupload, setIsRequestingReupload] = useState(false);
     const [isRejectingFraud, setIsRejectingFraud] = useState(false);
+    /*
+     * D55 — the balance review's OWN note and its own pending flags.
+     *
+     * 🛑 Not shared with `reviewNote` above, which belongs to the deposit's
+     * three actions. One note box feeding two reviews is the bug where an admin
+     * types "blurry screenshot" meaning the balance and sends it as a
+     * fraud-rejection reason on the deposit — and the deposit's rejection bans
+     * the account for 7 days.
+     */
+    const [balanceNote, setBalanceNote] = React.useState("");
+    const [balanceNoteError, setBalanceNoteError] = React.useState(null);
+    const [isAcceptingBalance, setIsAcceptingBalance] = useState(false);
+    const [isRejectingBalance, setIsRejectingBalance] = useState(false);
     // This used to inline `paymentMethod === "cash" || === "upi_manual"`, which
     // omitted `emi` — so the whole proof panel never rendered for an EMI order and
     // an admin had no way to verify one, even though the list row said "Awaiting
@@ -105,6 +118,10 @@ export function AdminOrderEditorView({ open, onClose, orderId, orderLabel, curre
                 notes: "",
             });
             setReviewNote("");
+            // Reset with its sibling — a note typed for one order must not reappear
+            // under the next one the drawer opens.
+            setBalanceNote("");
+            setBalanceNoteError(null);
         }
     }, [open, currentStatus]);
     const saveMutation = useApiMutation({
@@ -216,7 +233,49 @@ export function AdminOrderEditorView({ open, onClose, orderId, orderLabel, curre
             setIsRejectingFraud(false);
         }
     };
-    return (_jsx(SideDrawer, { isOpen: open, onClose: onClose, title: orderLabel ? `Order: ${orderLabel}` : "Update Order", children: _jsx(FormShellContext.Provider, { value: form.shellCtx, children: _jsxs(Stack, { gap: "md", padding: "md", children: [_jsx(FormErrorSummary, {}), addons && _jsx(OrderAddonBadges, { order: addons, variant: "detail" }), _jsx(OrderProvenanceCard, { sourceContext: sourceContext, currency: currency }), items && items.length > 0 && (_jsxs(Stack, { gap: "xs", children: [_jsxs(Label, { size: "sm", weight: "medium", color: "primary", children: ["Items (", items.length, ")"] }), _jsx(Div, { className: "divide-y divide-[var(--appkit-color-border)] border border-[var(--appkit-color-border)]", rounded: "lg", children: groupOrderItemsByLine(items).map((group, gi) => group.kind === "single" ? (adminOrderItemRow(group.item, `s-${group.index}`)) : (_jsxs(Div, { children: [_jsxs(Div, { layout: "flex", align: "center", gap: "2", padding: "x-sm", surface: "muted", children: [_jsx(Text, { size: "xs", weight: "semibold", children: group.groupTitle ?? "Grouped purchase" }), _jsx(Text, { size: "xs", color: "muted", children: `${group.memberCount} ${group.memberCount === 1 ? "item" : "items"} · one line` })] }), _jsx(Div, { className: "pl-4", children: group.items.map(({ item, index }) => adminOrderItemRow(item, `m-${index}`)) })] }, `g-${gi}`))) })] })), _jsx(SectionForm, { sections: sections, values: draft, onChange: (partial) => setDraft((d) => ({ ...d, ...partial })), onSubmit: () => {
+    /**
+     * D55 — accept or reject the pre-order BALANCE proof.
+     *
+     * 🛑 One handler, because the two verdicts differ by a boolean and a note
+     * and nothing else. The deposit has three handlers because its three
+     * outcomes are genuinely different operations (verify / re-ask / cancel +
+     * ban); mirroring that shape here would be three copies of one request.
+     *
+     * The note requirement is checked in BOTH places on purpose: here so the
+     * admin is told before the round trip, and in `reviewBalanceProof` because
+     * the route is reachable without this component.
+     */
+    const handleBalanceReview = async (approve) => {
+        if (!orderId)
+            return;
+        if (!approve && !balanceNote.trim()) {
+            setBalanceNoteError("Say what was wrong — without it the buyer will send the same proof again.");
+            return;
+        }
+        setBalanceNoteError(null);
+        const setPending = approve ? setIsAcceptingBalance : setIsRejectingBalance;
+        setPending(true);
+        try {
+            await apiClient.post(ADMIN_ENDPOINTS.ORDER_BALANCE_REVIEW(orderId), {
+                approve,
+                ...(balanceNote.trim() ? { note: balanceNote.trim() } : {}),
+            });
+            showToast(approve
+                ? "Balance accepted. The order is clear to ship."
+                : "Proof returned to the buyer with your note.", "success");
+            queryClient.invalidateQueries({ queryKey: ["admin", "orders"] });
+            onClose();
+        }
+        catch (err) {
+            void normalizeError(err);
+            // Authored copy — `err.message` is server text (Root Cause #86).
+            showToast("Could not record that decision.", "error");
+        }
+        finally {
+            setPending(false);
+        }
+    };
+    return (_jsx(SideDrawer, { isOpen: open, onClose: onClose, title: orderLabel ? `Order: ${orderLabel}` : "Update Order", children: _jsx(FormShellContext.Provider, { value: form.shellCtx, children: _jsxs(Stack, { gap: "md", padding: "md", children: [_jsx(FormErrorSummary, {}), addons && _jsx(OrderAddonBadges, { order: addons, variant: "detail" }), _jsx(OrderProvenanceCard, { sourceContext: sourceContext, currency: currency }), items && items.length > 0 && (_jsxs(Stack, { gap: "xs", children: [_jsxs(Label, { size: "sm", weight: "medium", color: "primary", children: ["Items (", items.length, ")"] }), _jsx(Div, { className: "divide-y divide-[var(--appkit-color-border)] border border-[var(--appkit-color-border)]", rounded: "lg", children: groupOrderItemsByLine(items).map((group, gi) => group.kind === "single" ? (adminOrderItemRow(group.item, `s-${group.index}`)) : (_jsxs(Div, { children: [_jsxs(Div, { layout: "flex", align: "center", gap: "2", padding: "x-sm", surface: "muted", children: [_jsx(Text, { size: "xs", weight: "semibold", children: group.groupTitle ?? "Grouped purchase" }), _jsx(Text, { size: "xs", color: "muted", children: `${group.memberCount} ${group.memberCount === 1 ? "item" : "items"} · one line` })] }), _jsx(Div, { paddingX: "l-md", children: group.items.map(({ item, index }) => adminOrderItemRow(item, `m-${index}`)) })] }, `g-${gi}`))) })] })), _jsx(SectionForm, { sections: sections, values: draft, onChange: (partial) => setDraft((d) => ({ ...d, ...partial })), onSubmit: () => {
                             // SectionForm surfaces errors and then submits regardless, so the
                             // guard is here.
                             form.clearErrors();
@@ -226,5 +285,15 @@ export function AdminOrderEditorView({ open, onClose, orderId, orderLabel, curre
                                 return;
                             }
                             saveMutation.mutate();
-                        }, onValidationChange: () => form.validate(draft), schema: adminOrderUpdateSchema, openIds: nav.openIds, onOpenChange: nav.setOpenIds, submitLabel: "Save changes", cancelLabel: "Cancel", onCancel: onClose, isLoading: saveMutation.isPending }), isManualPayment && (_jsxs(Stack, { gap: "xs", children: [_jsx(Label, { size: "sm", weight: "medium", color: "primary", children: "Payment Proof" }), isRejected && (_jsx(Text, { size: "xs", className: "text-error", weight: "medium", children: "Payment rejected as fraud \u2014 no further action available here." })), isReuploadRequested && !isVerified && (_jsx(Text, { size: "xs", className: "text-warning", weight: "medium", children: "Re-upload requested \u2014 waiting for the buyer to submit a new proof." })), paymentProofUrl ? (_jsxs(Stack, { gap: "xs", children: [_jsx(Div, { border: "default", rounded: "lg", overflow: "hidden", children: _jsx(MediaImage, { src: paymentProofUrl, alt: "Payment screenshot", size: "card" }) }), paymentTransactionId && (_jsxs(Text, { size: "xs", color: "muted", children: ["UTR: ", _jsx(Text, { as: "span", size: "xs", weight: "medium", children: paymentTransactionId })] })), needsVerification && (_jsxs(Stack, { gap: "xs", children: [(displayedUpiId || buyerReportedUpiId) && (_jsxs(Stack, { gap: "xs", children: [_jsxs(Text, { size: "xs", color: "muted", children: ["Expected UPI: ", _jsx(Text, { as: "span", size: "xs", weight: "medium", children: displayedUpiId || "—" }), " · ", "Buyer reported: ", _jsx(Text, { as: "span", size: "xs", weight: "medium", children: buyerReportedUpiId || "—" })] }), paymentUpiMismatch && (_jsx(Div, { rounded: "lg", padding: "inlineSm", className: "border border-error/20", surface: "danger-surface", children: _jsx(Text, { size: "xs", className: "text-error", weight: "semibold", children: "UPI mismatch \u2014 buyer-reported ID doesn't match the one shown for this order." }) }))] })), _jsxs(Text, { size: "xs", color: "muted", children: ["Buyer marked as paid: ", _jsx(Text, { as: "span", size: "xs", weight: "medium", children: buyerMarkedPaid ? "Yes" : "No" }), " · ", "Fraud agreement accepted: ", _jsx(Text, { as: "span", size: "xs", weight: "medium", children: buyerFraudAgreementAccepted ? "Yes" : "No" })] }), _jsxs(Stack, { gap: "xs", children: [_jsx(Label, { size: "sm", weight: "medium", color: "primary", children: "Review note" }), _jsxs(Text, { size: "xs", color: "muted", children: ["Sent with ", _jsx(Text, { as: "span", size: "xs", weight: "medium", children: "Request re-upload" }), " or", " ", _jsx(Text, { as: "span", size: "xs", weight: "medium", children: "Reject as fraud" }), " below. Not saved by \u201CSave changes\u201D."] }), _jsx(Textarea, { value: reviewNote, onChange: (e) => handleReviewNoteChange(e.target.value), rows: 2, "aria-invalid": reviewNoteError ? true : undefined, placeholder: "e.g. Screenshot is blurry \u2014 amount not readable / UPI ID doesn't match order" }), reviewNoteError && (_jsx(Text, { size: "xs", color: "error", role: "alert", children: reviewNoteError }))] }), _jsx(Button, { type: "button", action: ACTIONS.ADMIN["verify-payment"], onClick: handleVerifyPayment, isLoading: isVerifyingPayment, disabled: isVerifyingPayment, variant: "primary", className: "w-full" }), _jsx(Button, { type: "button", action: ACTIONS.ADMIN["request-payment-reupload"], onClick: handleRequestReupload, isLoading: isRequestingReupload, disabled: isRequestingReupload, variant: "secondary", className: "w-full" }), _jsx(Button, { type: "button", action: ACTIONS.ADMIN["reject-payment-fraud"], onClick: handleRejectFraud, isLoading: isRejectingFraud, disabled: isRejectingFraud, variant: "danger", className: "w-full" })] })), isVerified && (_jsx(Div, { rounded: "lg", padding: "inlineSm", className: "border border-success/20", surface: "success-surface", children: _jsx(Text, { size: "xs", className: "text-success", weight: "medium", children: "Payment verified" }) }))] })) : (_jsx(Text, { size: "xs", color: "faint", children: "No proof uploaded yet." }))] }))] }) }) }));
+                        }, onValidationChange: () => form.validate(draft), schema: adminOrderUpdateSchema, openIds: nav.openIds, onOpenChange: nav.setOpenIds, submitLabel: "Save changes", cancelLabel: "Cancel", onCancel: onClose, isLoading: saveMutation.isPending }), isManualPayment && (_jsxs(Stack, { gap: "xs", children: [_jsx(Label, { size: "sm", weight: "medium", color: "primary", children: "Payment Proof" }), isRejected && (_jsx(Text, { size: "xs", className: "text-error", weight: "medium", children: "Payment rejected as fraud \u2014 no further action available here." })), isReuploadRequested && !isVerified && (_jsx(Text, { size: "xs", className: "text-warning", weight: "medium", children: "Re-upload requested \u2014 waiting for the buyer to submit a new proof." })), paymentProofUrl ? (_jsxs(Stack, { gap: "xs", children: [_jsx(Div, { border: "default", rounded: "lg", overflow: "hidden", children: _jsx(MediaImage, { src: paymentProofUrl, alt: "Payment screenshot", size: "card" }) }), paymentTransactionId && (_jsxs(Text, { size: "xs", color: "muted", children: ["UTR: ", _jsx(Text, { as: "span", size: "xs", weight: "medium", children: paymentTransactionId })] })), needsVerification && (_jsxs(Stack, { gap: "xs", children: [(displayedUpiId || buyerReportedUpiId) && (_jsxs(Stack, { gap: "xs", children: [_jsxs(Text, { size: "xs", color: "muted", children: ["Expected UPI: ", _jsx(Text, { as: "span", size: "xs", weight: "medium", children: displayedUpiId || "—" }), " · ", "Buyer reported: ", _jsx(Text, { as: "span", size: "xs", weight: "medium", children: buyerReportedUpiId || "—" })] }), paymentUpiMismatch && (_jsx(Div, { rounded: "lg", padding: "inlineSm", className: "border border-error/20", surface: "danger-surface", children: _jsx(Text, { size: "xs", className: "text-error", weight: "semibold", children: "UPI mismatch \u2014 buyer-reported ID doesn't match the one shown for this order." }) }))] })), _jsxs(Text, { size: "xs", color: "muted", children: ["Buyer marked as paid: ", _jsx(Text, { as: "span", size: "xs", weight: "medium", children: buyerMarkedPaid ? "Yes" : "No" }), " · ", "Fraud agreement accepted: ", _jsx(Text, { as: "span", size: "xs", weight: "medium", children: buyerFraudAgreementAccepted ? "Yes" : "No" })] }), _jsxs(Stack, { gap: "xs", children: [_jsx(Label, { size: "sm", weight: "medium", color: "primary", children: "Review note" }), _jsxs(Text, { size: "xs", color: "muted", children: ["Sent with ", _jsx(Text, { as: "span", size: "xs", weight: "medium", children: "Request re-upload" }), " or", " ", _jsx(Text, { as: "span", size: "xs", weight: "medium", children: "Reject as fraud" }), " below. Not saved by \u201CSave changes\u201D."] }), _jsx(Textarea, { value: reviewNote, onChange: (e) => handleReviewNoteChange(e.target.value), rows: 2, "aria-invalid": reviewNoteError ? true : undefined, placeholder: "e.g. Screenshot is blurry \u2014 amount not readable / UPI ID doesn't match order" }), reviewNoteError && (_jsx(Text, { size: "xs", color: "error", role: "alert", children: reviewNoteError }))] }), _jsx(Button, { type: "button", action: ACTIONS.ADMIN["verify-payment"], onClick: handleVerifyPayment, isLoading: isVerifyingPayment, disabled: isVerifyingPayment, variant: "primary", className: "w-full" }), _jsx(Button, { type: "button", action: ACTIONS.ADMIN["request-payment-reupload"], onClick: handleRequestReupload, isLoading: isRequestingReupload, disabled: isRequestingReupload, variant: "secondary", className: "w-full" }), _jsx(Button, { type: "button", action: ACTIONS.ADMIN["reject-payment-fraud"], onClick: handleRejectFraud, isLoading: isRejectingFraud, disabled: isRejectingFraud, variant: "danger", className: "w-full" })] })), isVerified && (_jsx(Div, { rounded: "lg", padding: "inlineSm", className: "border border-success/20", surface: "success-surface", children: _jsx(Text, { size: "xs", className: "text-success", weight: "medium", children: "Payment verified" }) }))] })) : (_jsx(Text, { size: "xs", color: "faint", children: "No proof uploaded yet." }))] })), balance && (_jsxs(Stack, { gap: "xs", children: [_jsx(Label, { size: "sm", weight: "medium", color: "primary", children: "Pre-order balance" }), _jsxs(Text, { size: "xs", color: "muted", children: [toCurrency(balance.amount), " \u00B7", " ", balance.status === "paid"
+                                        ? "accepted"
+                                        : balance.status === "submitted"
+                                            ? "proof submitted, awaiting your decision"
+                                            : balance.status === "rejected"
+                                                ? "returned to the buyer"
+                                                : "open — the buyer has not paid yet", balance.transactionId ? ` · Ref ${balance.transactionId}` : ""] }), balance.status === "rejected" && balance.reviewNote && (_jsxs(Text, { size: "xs", color: "muted", children: ["Last note: ", balance.reviewNote] })), balance.status === "submitted" && (_jsxs(Stack, { gap: "xs", children: [balance.proofUrl && (_jsx(Div, { border: "default", rounded: "lg", overflow: "hidden", children: _jsx(MediaImage, { src: balance.proofUrl, alt: "Balance payment screenshot", size: "card" }) })), _jsx(Text, { size: "xs", color: "muted", children: "Check the reference against the bank before accepting. Accepting does NOT post a ledger entry \u2014 the sale was recognised in full when the order was created, so a second entry would double it." }), _jsx(Textarea, { value: balanceNote, onChange: (e) => {
+                                            setBalanceNote(e.target.value);
+                                            if (balanceNoteError)
+                                                setBalanceNoteError(null);
+                                        }, rows: 2, "aria-invalid": balanceNoteError ? true : undefined, placeholder: "Required when rejecting \u2014 e.g. reference does not match any credit we received" }), balanceNoteError && (_jsx(Text, { size: "xs", color: "error", role: "alert", children: balanceNoteError })), _jsx(Button, { type: "button", action: ACTIONS.ADMIN["verify-balance"], onClick: () => void handleBalanceReview(true), isLoading: isAcceptingBalance, disabled: isAcceptingBalance || isRejectingBalance, variant: "primary", className: "w-full" }), _jsx(Button, { type: "button", action: ACTIONS.ADMIN["reject-balance"], onClick: () => void handleBalanceReview(false), isLoading: isRejectingBalance, disabled: isAcceptingBalance || isRejectingBalance, variant: "secondary", className: "w-full" })] }))] }))] }) }) }));
 }

package/dist/features/admin/components/AdminOrdersView.js

@@ -267,6 +267,25 @@ export function AdminOrdersView({ children, ...props }) {
                 // which coerces every field by hand, this one needs a tag check
                 // before it can be trusted. See `toSourceContext`.
                 sourceContext: toSourceContext(item.sourceContext),
+                /*
+                 * D55. Coerced field by field like `addons` above, deliberately
+                 * NOT `as AdminOrderEditorViewProps["balance"]` — a cast at a
+                 * raw-document boundary is where Root Cause #98 lives, and main
+                 * had just removed the same cast from `sourceContext` one line up.
+                 *
+                 * `proofUrl` is omitted ON PURPOSE: this is the LIST payload, and
+                 * the screenshot is admin-detail only. A list row never needs it.
+                 */
+                balance: item.balance
+                    ? {
+                        amount: Number(item.balance.amount ?? 0),
+                        status: toStringValue(item.balance.status, "awaiting"),
+                        transactionId: toStringValue(item.balance.transactionId) ||
+                            undefined,
+                        reviewNote: toStringValue(item.balance.reviewNote) ||
+                            undefined,
+                    }
+                    : undefined,
                 currency: toStringValue(item.currency, "") || undefined,
             };
         }),
@@ -351,5 +370,5 @@ export function AdminOrdersView({ children, ...props }) {
             ] })),
         renderFilterPanel: ({ pendingFilters, setPendingFilters }) => (_jsxs(_Fragment, { children: [_jsx(FilterChipGroup, { label: "Status", tabs: ADMIN_ORDER_STATUS_TABS, value: pendingFilters.status ?? "", onChange: (id) => setPendingFilters((p) => ({ ...p, status: id, paymentReview: "" })) }), _jsx(FilterChipGroup, { label: "Manual payment", tabs: ADMIN_ORDER_PAYMENT_REVIEW_TABS, value: pendingFilters.paymentReview ?? "", onChange: (id) => setPendingFilters((p) => ({ ...p, paymentReview: id, status: "" })) })] })),
     };
-    return (_jsxs(_Fragment, { children: [_jsx(DataListingView, { config: config }), _jsx(AdminOrderEditorView, { open: drawerOpen, onClose: () => setDrawerOpen(false), orderId: selectedRow?.id, orderLabel: selectedRow?.primary, currentStatus: selectedRow?.status, items: selectedRow?.items, paymentProofUrl: selectedRow?.paymentProofUrl, paymentTransactionId: selectedRow?.paymentTransactionId, paymentMethod: selectedRow?.paymentMethod, paymentStatus: selectedRow?.paymentStatus, displayedUpiId: selectedRow?.displayedUpiId, buyerReportedUpiId: selectedRow?.buyerReportedUpiId, paymentUpiMismatch: selectedRow?.paymentUpiMismatch, buyerMarkedPaid: selectedRow?.buyerMarkedPaid, buyerFraudAgreementAccepted: selectedRow?.buyerFraudAgreementAccepted, paymentReviewOutcome: selectedRow?.paymentReviewOutcome, addons: selectedRow?.addons, sourceContext: selectedRow?.sourceContext, currency: selectedRow?.currency })] }));
+    return (_jsxs(_Fragment, { children: [_jsx(DataListingView, { config: config }), _jsx(AdminOrderEditorView, { open: drawerOpen, onClose: () => setDrawerOpen(false), orderId: selectedRow?.id, orderLabel: selectedRow?.primary, currentStatus: selectedRow?.status, items: selectedRow?.items, paymentProofUrl: selectedRow?.paymentProofUrl, paymentTransactionId: selectedRow?.paymentTransactionId, paymentMethod: selectedRow?.paymentMethod, paymentStatus: selectedRow?.paymentStatus, displayedUpiId: selectedRow?.displayedUpiId, buyerReportedUpiId: selectedRow?.buyerReportedUpiId, paymentUpiMismatch: selectedRow?.paymentUpiMismatch, buyerMarkedPaid: selectedRow?.buyerMarkedPaid, buyerFraudAgreementAccepted: selectedRow?.buyerFraudAgreementAccepted, paymentReviewOutcome: selectedRow?.paymentReviewOutcome, addons: selectedRow?.addons, sourceContext: selectedRow?.sourceContext, balance: selectedRow?.balance, currency: selectedRow?.currency })] }));
 }

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 = {
@@ -838,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/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;