@mohasinac/appkit 4.62.1 → 4.63.0

package/dist/_internal/server/features/orders/amend-delivery.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Correcting a delivery address after the order was placed.
+ *
+ * ## 🛑 This APPENDS. It never touches the snapshot.
+ *
+ * `delivery*` on the order is what the buyer chose when they paid — it is
+ * what the invoice states and what a dispute argues over. A correction is a
+ * new fact about where the parcel should go, not a revision of what was
+ * agreed, and collapsing the two is how an invoice silently restates itself.
+ *
+ * `deliveryPartyFor` reads the latest amendment; `placeOfSupplyFrom` reads
+ * the snapshot. Tax is fixed at the time of supply.
+ *
+ * ## 🛑 There is a window, and it closes at dispatch
+ *
+ * Once a tracking id exists the parcel is with the courier and a new address
+ * changes nothing we control — accepting one would tell the buyer their
+ * correction took effect when it did not. That is a worse outcome than
+ * refusing, which at least routes them to support.
+ */
+import { type DeliveryAmendment, type OrderDocument } from "../../../../features/orders/schemas/firestore";
+import { type HistoryActor } from "../../../shared/history";
+/**
+ * How many corrections one order may carry.
+ *
+ * 🛑 Bounded for the same reason `statusHistory` is: this array rides on the
+ * order document, which has a 1 MiB ceiling and is read by every list query.
+ * Unlike `statusHistory` it does NOT evict — reaching the cap is refused,
+ * because dropping the oldest amendment would silently discard an address a
+ * parcel may already have gone to.
+ *
+ * Ten is far past any honest use. A buyer correcting an address eleven times
+ * is a support conversation, not a form submission.
+ */
+export declare const DELIVERY_AMENDMENT_MAX = 10;
+export interface AmendDeliveryInput {
+    orderId: string;
+    /** An `addresses` row belonging to the actor. Never a loose address. */
+    addressId: string;
+    reason?: string;
+}
+/**
+ * 🛑 The new address is a REFERENCE the caller must own, resolved here — not
+ * a free-form address object.
+ *
+ * Accepting fields directly would let a correction route a parcel anywhere
+ * with no record that the destination was ever the buyer's, which is the
+ * same hole `assertOwnedAddresses` closes for coordinated purchases. The
+ * resolved values are then COPIED into the amendment, because the row can be
+ * edited or deleted afterwards and a label must not depend on that.
+ */
+export declare function amendDeliveryAddress(input: AmendDeliveryInput, actor: HistoryActor & {
+    uid: string;
+}): Promise<DeliveryAmendment>;
+/** Plaintext amendments, for a surface that renders them. */
+export declare function revealAmendments(order: OrderDocument): DeliveryAmendment[];

package/dist/_internal/server/features/orders/amend-delivery.js

@@ -0,0 +1,124 @@
+/**
+ * Correcting a delivery address after the order was placed.
+ *
+ * ## 🛑 This APPENDS. It never touches the snapshot.
+ *
+ * `delivery*` on the order is what the buyer chose when they paid — it is
+ * what the invoice states and what a dispute argues over. A correction is a
+ * new fact about where the parcel should go, not a revision of what was
+ * agreed, and collapsing the two is how an invoice silently restates itself.
+ *
+ * `deliveryPartyFor` reads the latest amendment; `placeOfSupplyFrom` reads
+ * the snapshot. Tax is fixed at the time of supply.
+ *
+ * ## 🛑 There is a window, and it closes at dispatch
+ *
+ * Once a tracking id exists the parcel is with the courier and a new address
+ * changes nothing we control — accepting one would tell the buyer their
+ * correction took effect when it did not. That is a worse outcome than
+ * refusing, which at least routes them to support.
+ */
+import { addressesRepository } from "../../../../features/addresses/repository/addresses.repository.js";
+import { orderRepository } from "../../../../features/orders/repository/orders.repository.js";
+import { AMENDMENT_PII_FIELDS, } from "../../../../features/orders/schemas/firestore.js";
+import { revealPii } from "../../../../security/pii-accessors.js";
+import { ValidationError } from "../../../../errors/validation-error.js";
+import { NotFoundError } from "../../../../errors/not-found-error.js";
+import { HISTORY_ACTOR_ROLE } from "../../../shared/history/index.js";
+/**
+ * How many corrections one order may carry.
+ *
+ * 🛑 Bounded for the same reason `statusHistory` is: this array rides on the
+ * order document, which has a 1 MiB ceiling and is read by every list query.
+ * Unlike `statusHistory` it does NOT evict — reaching the cap is refused,
+ * because dropping the oldest amendment would silently discard an address a
+ * parcel may already have gone to.
+ *
+ * Ten is far past any honest use. A buyer correcting an address eleven times
+ * is a support conversation, not a form submission.
+ */
+export const DELIVERY_AMENDMENT_MAX = 10;
+/**
+ * 🛑 The new address is a REFERENCE the caller must own, resolved here — not
+ * a free-form address object.
+ *
+ * Accepting fields directly would let a correction route a parcel anywhere
+ * with no record that the destination was ever the buyer's, which is the
+ * same hole `assertOwnedAddresses` closes for coordinated purchases. The
+ * resolved values are then COPIED into the amendment, because the row can be
+ * edited or deleted afterwards and a label must not depend on that.
+ */
+export async function amendDeliveryAddress(input, actor) {
+    const order = (await orderRepository.findById(input.orderId));
+    if (!order)
+        throw new NotFoundError("Order not found.");
+    /*
+     * Ownership. A seller or admin may correct on a buyer's behalf — that is
+     * the support flow — but a BUYER may only touch their own order.
+     */
+    if (actor.role === HISTORY_ACTOR_ROLE.BUYER && order.userId !== actor.uid) {
+        throw new NotFoundError("Order not found.");
+    }
+    if (order.trackingNumber) {
+        throw new ValidationError("This order has already been dispatched, so its address can no longer be changed.", { addressId: "Already dispatched — contact support." });
+    }
+    const existing = order.deliveryAmendments ?? [];
+    if (existing.length >= DELIVERY_AMENDMENT_MAX) {
+        throw new ValidationError("This order has been corrected too many times. Please contact support.", { addressId: `Limit of ${DELIVERY_AMENDMENT_MAX} corrections reached.` });
+    }
+    const addressDoc = await addressesRepository.findById(input.addressId);
+    /*
+     * Owned by the ORDER'S BUYER, not by the actor. A support agent correcting
+     * on someone's behalf must still pick from that buyer's own addresses —
+     * checking the actor would let staff route a parcel to their own address.
+     */
+    if (!addressDoc || addressDoc.ownerType !== "user" || addressDoc.ownerId !== order.userId) {
+        throw new ValidationError("That delivery address is not available.", {
+            addressId: "That address cannot be used.",
+        });
+    }
+    const address = addressesRepository.revealAddress(addressDoc);
+    const amendment = {
+        at: new Date(),
+        actorUid: actor.uid,
+        actorRole: actor.role,
+        ...(input.reason?.trim() ? { reason: input.reason.trim() } : {}),
+        fullName: String(address.fullName ?? ""),
+        phone: String(address.phone ?? ""),
+        addressLine1: String(address.addressLine1 ?? ""),
+        ...(address.addressLine2 ? { addressLine2: String(address.addressLine2) } : {}),
+        ...(address.landmark ? { landmark: String(address.landmark) } : {}),
+        city: address.city ?? "",
+        state: address.state ?? "",
+        pincode: address.postalCode ?? "",
+        country: address.country ?? "",
+    };
+    /*
+     * 🛑 NOT encrypted here. `ORDER_PII_FIELDS` declares
+     * `deliveryAmendments[].fullName` and friends, and the repository's write
+     * hook runs that list through `encryptInArray` — which the encryptor has
+     * always supported.
+     *
+     * The first draft of this file encrypted by hand, on the belief that
+     * `encryptPiiFields` "is a flat top-level loop that never descends". That
+     * is CLAUDE.md's wording and it is false: the function handles `a.b` and
+     * `a[].b` in both directions, and `CONVERSATION_PII_FIELDS` has been using
+     * the dotted form in production. Encrypting here as well would double-
+     * encrypt — the guard is a `enc:v1:` prefix test, so the second pass is a
+     * no-op today and a silent corruption the day the prefix changes.
+     */
+    /*
+     * 🛑 Whole array, not `arrayUnion`. `arrayUnion` cannot enforce the cap —
+     * the same reason `withHistory`'s batch paths fold in memory — and it
+     * de-duplicates by value, so two identical corrections would collapse into
+     * one and the record would under-state what happened.
+     */
+    await orderRepository.update(input.orderId, {
+        deliveryAmendments: [...existing, amendment],
+    });
+    return amendment;
+}
+/** Plaintext amendments, for a surface that renders them. */
+export function revealAmendments(order) {
+    return (order.deliveryAmendments ?? []).map((a) => revealPii(a, AMENDMENT_PII_FIELDS));
+}

package/dist/_internal/server/features/orders/balance.d.ts

@@ -0,0 +1,89 @@
+/**
+ * D55 — collecting a pre-order balance.
+ *
+ * ## 🛑 `balanceDue` has been computed and rendered since Part 2, and
+ * nothing has ever collected it
+ *
+ * `OrderSourcePreOrder.balanceDue` is written at order creation and
+ * `OrderProvenanceCard` prints it — so `/user/pre-orders` has been
+ * advertising a figure the product has no way to accept. That is worse than
+ * omitting it: a buyer who sees "Balance due ₹4,000" and finds no control
+ * reasonably concludes the site is broken, and a seller waiting on it has no
+ * mechanism to chase.
+ *
+ * ## Manual only, and that is a decision rather than a stopping point
+ *
+ * The manual path needs no mandate, no scheduled debit and no account
+ * change, so it is what makes the balance payable AT ALL today. The auto
+ * path is blocked on RBI requirements and on Razorpay recurring being
+ * enabled against live keys — see the schema's own note, which declares the
+ * union so adding `auto` is a compile-checked change.
+ *
+ * ## 🛑 It reuses the manual-payment REVIEW flow and none of its STORAGE
+ *
+ * The vocabulary is the same (submit a proof, an admin approves or rejects
+ * with a note) and the fields are separate, because a pre-order has two
+ * payments months apart. Writing the balance's proof over the deposit's
+ * would destroy the evidence for the payment that created the order — and
+ * `paymentWindowTimeout`, which sweeps `pending`/`pending` orders with no
+ * `paymentProofUrl`, would then cancel and restock a paid one.
+ */
+import type { OrderDocument } from "../../../../features/orders/schemas/firestore";
+/**
+ * How long a buyer gets, once the balance is opened for collection.
+ *
+ * 🛑 Days, not the 15 MINUTES the deposit window uses. That window exists to
+ * stop an unpaid order holding stock; this one is a bill falling due on goods
+ * that have arrived, and the buyer may legitimately need to move money. A
+ * 15-minute balance window would cancel real orders for no benefit.
+ */
+export declare const BALANCE_WINDOW_DAYS = 7;
+/** The balance a pre-order still owes, or `null` when it is not one. */
+export declare function balanceDueOn(order: OrderDocument): number | null;
+/**
+ * Open the balance for collection — the seller's "the goods have landed"
+ * signal.
+ *
+ * 🛑 **Opening is an EVENT, not a derived state.** The balance could be
+ * computed as payable the moment the order exists, and that would be wrong:
+ * a pre-order's whole premise is that the goods do not exist yet, so asking
+ * for the balance before they do is asking a buyer to fund inventory. The
+ * seller opens it when stock arrives, and `dueBy` runs from that moment.
+ *
+ * 🛑 Idempotent. A seller clicking twice must not restart the buyer's
+ * window — which, since `dueBy` is what a reminder and any future
+ * auto-cancel would read, would silently extend the deadline every time
+ * anyone touched the button.
+ *
+ * 🛑 **Ownership is checked HERE, and it has to be**: the route that calls
+ * this is role-gated to sellers, and every seller passes that gate. Without
+ * this block any seller could open — and therefore start the payment clock
+ * on, and notify the buyer about — another seller's pre-order.
+ *
+ * It was missing, and the reason it was invisible is worth recording: the
+ * route also carried `permission: "orders:write"` alongside a `roles` array
+ * holding `seller`, which `getServerPermissions()` resolves for `employee`
+ * only — so every seller got a 403 before reaching this function at all. A
+ * broken gate masked an absent one, exactly as in Root Cause #98.
+ */
+export declare function openBalanceCollection(orderId: string, actor: {
+    uid: string;
+    role: string;
+}, now?: Date): Promise<OrderDocument>;
+/**
+ * The buyer submits a proof.
+ *
+ * 🛑 Allowed from `awaiting` AND from `rejected`. A rejected proof is the
+ * commonest reason to need a second attempt — a blurred screenshot, the
+ * wrong reference — and locking the buyer out after one rejection turns a
+ * recoverable mistake into a support ticket.
+ */
+export declare function submitBalanceProof(orderId: string, buyerUid: string, proofUrl: string, transactionId: string, now?: Date): Promise<void>;
+/**
+ * An admin approves or rejects the balance proof.
+ *
+ * 🛑 A rejection REQUIRES a note, for the same reason a reversal does: the
+ * buyer has to know what to send instead, and "rejected" alone guarantees
+ * the next attempt is the same proof again.
+ */
+export declare function reviewBalanceProof(orderId: string, reviewerUid: string, approve: boolean, note?: string, now?: Date): Promise<void>;

package/dist/_internal/server/features/orders/balance.js

@@ -0,0 +1,256 @@
+/**
+ * D55 — collecting a pre-order balance.
+ *
+ * ## 🛑 `balanceDue` has been computed and rendered since Part 2, and
+ * nothing has ever collected it
+ *
+ * `OrderSourcePreOrder.balanceDue` is written at order creation and
+ * `OrderProvenanceCard` prints it — so `/user/pre-orders` has been
+ * advertising a figure the product has no way to accept. That is worse than
+ * omitting it: a buyer who sees "Balance due ₹4,000" and finds no control
+ * reasonably concludes the site is broken, and a seller waiting on it has no
+ * mechanism to chase.
+ *
+ * ## Manual only, and that is a decision rather than a stopping point
+ *
+ * The manual path needs no mandate, no scheduled debit and no account
+ * change, so it is what makes the balance payable AT ALL today. The auto
+ * path is blocked on RBI requirements and on Razorpay recurring being
+ * enabled against live keys — see the schema's own note, which declares the
+ * union so adding `auto` is a compile-checked change.
+ *
+ * ## 🛑 It reuses the manual-payment REVIEW flow and none of its STORAGE
+ *
+ * The vocabulary is the same (submit a proof, an admin approves or rejects
+ * with a note) and the fields are separate, because a pre-order has two
+ * payments months apart. Writing the balance's proof over the deposit's
+ * would destroy the evidence for the payment that created the order — and
+ * `paymentWindowTimeout`, which sweeps `pending`/`pending` orders with no
+ * `paymentProofUrl`, would then cancel and restock a paid one.
+ */
+import { orderRepository } from "../../../../features/orders/repository/orders.repository.js";
+import { ValidationError } from "../../../../errors/validation-error.js";
+import { NotFoundError } from "../../../../errors/not-found-error.js";
+import { AuthorizationError } from "../../../../errors/authorization-error.js";
+import { storeRepository } from "../../../../features/stores/repository/store.repository.js";
+import { sendNotification } from "../../../../features/admin/actions/notification-actions.js";
+import { serverLogger } from "../../../../monitoring/server-logger.js";
+/*
+ * 🛑 ONE message, for the same reason the ads collector names its own: an
+ * order that is not the caller's answers 404 rather than 403, so "no such
+ * order" and "not yours" must read identically. Two matching literals are a
+ * coincidence; a constant is the rule.
+ */
+const ORDER_NOT_FOUND = "Order not found.";
+/**
+ * How long a buyer gets, once the balance is opened for collection.
+ *
+ * 🛑 Days, not the 15 MINUTES the deposit window uses. That window exists to
+ * stop an unpaid order holding stock; this one is a bill falling due on goods
+ * that have arrived, and the buyer may legitimately need to move money. A
+ * 15-minute balance window would cancel real orders for no benefit.
+ */
+export const BALANCE_WINDOW_DAYS = 7;
+/** The balance a pre-order still owes, or `null` when it is not one. */
+export function balanceDueOn(order) {
+    const ctx = order.sourceContext;
+    if (!ctx || ctx.path !== "pre-order")
+        return null;
+    return ctx.balanceDue > 0 ? ctx.balanceDue : null;
+}
+/**
+ * Open the balance for collection — the seller's "the goods have landed"
+ * signal.
+ *
+ * 🛑 **Opening is an EVENT, not a derived state.** The balance could be
+ * computed as payable the moment the order exists, and that would be wrong:
+ * a pre-order's whole premise is that the goods do not exist yet, so asking
+ * for the balance before they do is asking a buyer to fund inventory. The
+ * seller opens it when stock arrives, and `dueBy` runs from that moment.
+ *
+ * 🛑 Idempotent. A seller clicking twice must not restart the buyer's
+ * window — which, since `dueBy` is what a reminder and any future
+ * auto-cancel would read, would silently extend the deadline every time
+ * anyone touched the button.
+ *
+ * 🛑 **Ownership is checked HERE, and it has to be**: the route that calls
+ * this is role-gated to sellers, and every seller passes that gate. Without
+ * this block any seller could open — and therefore start the payment clock
+ * on, and notify the buyer about — another seller's pre-order.
+ *
+ * It was missing, and the reason it was invisible is worth recording: the
+ * route also carried `permission: "orders:write"` alongside a `roles` array
+ * holding `seller`, which `getServerPermissions()` resolves for `employee`
+ * only — so every seller got a 403 before reaching this function at all. A
+ * broken gate masked an absent one, exactly as in Root Cause #98.
+ */
+export async function openBalanceCollection(orderId, actor, now = new Date()) {
+    const order = (await orderRepository.findById(orderId));
+    if (!order)
+        throw new NotFoundError(ORDER_NOT_FOUND);
+    /*
+     * 🛑 `order.storeId` is the store SLUG, never the seller's Firebase UID —
+     * two namespaces by design (§ "Store Identity Architecture"). Comparing it
+     * to `actor.uid` returns false for every legitimate seller, which is the
+     * other half of Root Cause #98. Resolve the store first.
+     */
+    if (actor.role !== "admin") {
+        const store = await storeRepository.findByOwnerId(actor.uid);
+        if (!store || order.storeId !== store.id) {
+            throw new AuthorizationError("You do not own this order");
+        }
+    }
+    const due = balanceDueOn(order);
+    if (due == null) {
+        throw new ValidationError("This order has no pre-order balance.", {
+            orderId: "Only a pre-order carries a balance.",
+        });
+    }
+    if (order.balance)
+        return order; // already open — see the idempotency note.
+    const dueBy = new Date(now.getTime() + BALANCE_WINDOW_DAYS * 24 * 60 * 60 * 1000);
+    await orderRepository.update(orderId, {
+        balance: {
+            /*
+             * 🛑 Snapshotted HERE, from `sourceContext`, and never read live
+             * again. The gap between deposit and balance is months — the worst in
+             * the codebase for D61 — so a price or tax change in between must not
+             * move what the buyer was told they owe.
+             */
+            amount: due,
+            method: "manual",
+            status: "awaiting",
+            dueBy,
+        },
+    });
+    await sendNotification({
+        userId: order.userId,
+        type: "order_confirmed",
+        priority: "high",
+        title: "Your pre-order balance is due",
+        message: `The balance of ₹${due.toFixed(2)} on order ${orderId} is now payable. Your item is ready to ship once it clears.`,
+        relatedId: orderId,
+        relatedType: "order",
+    });
+    return { ...order, balance: { amount: due, method: "manual", status: "awaiting", dueBy } };
+}
+/**
+ * The buyer submits a proof.
+ *
+ * 🛑 Allowed from `awaiting` AND from `rejected`. A rejected proof is the
+ * commonest reason to need a second attempt — a blurred screenshot, the
+ * wrong reference — and locking the buyer out after one rejection turns a
+ * recoverable mistake into a support ticket.
+ */
+export async function submitBalanceProof(orderId, buyerUid, proofUrl, transactionId, now = new Date()) {
+    const order = (await orderRepository.findById(orderId));
+    if (!order)
+        throw new NotFoundError(ORDER_NOT_FOUND);
+    /*
+     * 🛑 Ownership checked against `userId`, which is the buyer field on
+     * `OrderDocument` — NOT `buyerId`, which does not exist. A query or guard
+     * written against `buyerId` returns nothing and raises nothing, which is
+     * indistinguishable from "not your order" (CLAUDE.md records this costing
+     * real time once already).
+     */
+    if (order.userId !== buyerUid) {
+        throw new NotFoundError(ORDER_NOT_FOUND);
+    }
+    if (!order.balance) {
+        throw new ValidationError("No balance has been opened on this order yet.", {
+            orderId: "The seller opens the balance when the goods arrive.",
+        });
+    }
+    if (order.balance.status === "paid") {
+        throw new ValidationError("This balance is already paid.", {
+            orderId: "Nothing further is owed.",
+        });
+    }
+    if (order.balance.status === "submitted") {
+        throw new ValidationError("A proof is already awaiting review.", {
+            orderId: "Wait for the current one to be reviewed before sending another.",
+        });
+    }
+    if (!transactionId.trim()) {
+        throw new ValidationError("Enter the transaction reference.", {
+            transactionId: "The UTR or reference from your bank or UPI app.",
+        });
+    }
+    await orderRepository.update(orderId, {
+        balance: {
+            ...order.balance,
+            status: "submitted",
+            proofUrl,
+            transactionId: transactionId.trim(),
+            submittedAt: now,
+            /*
+             * 🛑 The previous rejection's note is CLEARED on resubmission. Leaving
+             * it would show the buyer a stale "your proof was unreadable" beside a
+             * proof they have just replaced.
+             */
+            reviewNote: undefined,
+        },
+    });
+}
+/**
+ * An admin approves or rejects the balance proof.
+ *
+ * 🛑 A rejection REQUIRES a note, for the same reason a reversal does: the
+ * buyer has to know what to send instead, and "rejected" alone guarantees
+ * the next attempt is the same proof again.
+ */
+export async function reviewBalanceProof(orderId, reviewerUid, approve, note, now = new Date()) {
+    const order = (await orderRepository.findById(orderId));
+    if (!order)
+        throw new NotFoundError(ORDER_NOT_FOUND);
+    if (order.balance?.status !== "submitted") {
+        throw new ValidationError("There is no submitted balance proof to review.", {
+            orderId: `The balance is "${order.balance?.status ?? "not opened"}".`,
+        });
+    }
+    if (!approve && !note?.trim()) {
+        throw new ValidationError("A rejection needs a reason.", {
+            note: "Say what was wrong, or the buyer will send the same proof again.",
+        });
+    }
+    await orderRepository.update(orderId, {
+        balance: {
+            ...order.balance,
+            status: approve ? "paid" : "rejected",
+            reviewedBy: reviewerUid,
+            reviewedAt: now,
+            ...(note?.trim() ? { reviewNote: note.trim() } : {}),
+        },
+    });
+    /*
+     * 🛑 The LEDGER is not posted here, and that is deliberate.
+     *
+     * A balance payment is a second capture against an order whose sale was
+     * already posted in full at creation — `orderPlacedPosting` recognises the
+     * whole `totalPrice`, not the deposit. Posting again would double the
+     * sale. What actually changes is which asset holds the money, and that is
+     * the settlement's job: the gateway receivable clears when the settlement
+     * lands, exactly as it does for a single-payment order.
+     *
+     * Recording this is left to whoever wires the deposit/balance split into
+     * `orderPlacedPosting`, which is a change to that rule rather than an
+     * extra entry here. An extra entry would balance and be wrong, which is
+     * the failure mode Part 4's whole design is about.
+     */
+    serverLogger.info("balance proof reviewed", {
+        orderId,
+        approved: approve,
+        reviewerUid,
+    });
+    await sendNotification({
+        userId: order.userId,
+        type: approve ? "order_confirmed" : "payment_review",
+        priority: "high",
+        title: approve ? "Balance received" : "We could not accept your payment proof",
+        message: approve
+            ? `Your balance on order ${orderId} has been confirmed. It is ready to ship.`
+            : `Your balance proof on order ${orderId} was not accepted: ${note?.trim() ?? ""}`,
+        relatedId: orderId,
+        relatedType: "order",
+    });
+}

package/dist/_internal/server/features/pricing/actions.d.ts

@@ -0,0 +1,58 @@
+/**
+ * The ONE write path for a platform rate.
+ *
+ * ## Why there is exactly one
+ *
+ * Rates live on `siteSettings`, which `PUT /api/admin/site` can already write
+ * — so this is not the only way the numbers CAN move. It is the only way they
+ * move with a recorded reason, an effective date and an `adminAuditLog` row,
+ * and that difference is the whole point of `/admin/pricing`.
+ *
+ * The general settings form stays able to write them. Locking it out would
+ * mean an admin fixing a typo in the COD ceiling gets a 400 from the page that
+ * has always owned it, and the fix would be to come here — which is a worse
+ * outcome than an occasional unlogged edit. What this buys is that the
+ * DELIBERATE act of repricing has one door with a record behind it.
+ *
+ * ## 🛑 Forward-only, enforced at the WRITE
+ *
+ * `rejectRateChange` is a pure function and lives in the registry so the form
+ * can run it too — but the form running it is a courtesy, and this is the
+ * enforcement. A backdated change here would restate figures already invoiced
+ * and already paid out; see the registry header.
+ */
+/**
+ * How many changes the log keeps, newest first.
+ *
+ * Sized so a year of ordinary repricing fits: 16 rates changed a few times
+ * each is well under this, and the page shows only the most recent per rate
+ * anyway. The cap exists because the array rides on a document every request
+ * reads, not because 200 entries is a lot of data.
+ */
+export declare const RATE_CHANGE_LOG_MAX = 200;
+export interface ApplyRateChangeInput {
+    path: string;
+    newValue: number;
+    /** Omit for "now". Never earlier than now — see `rejectRateChange`. */
+    effectiveFrom?: Date;
+    reason?: string;
+}
+export interface ApplyRateChangeResult {
+    path: string;
+    previousValue: number | null;
+    newValue: number;
+    effectiveFrom: Date;
+}
+/**
+ * Change one rate.
+ *
+ * 🛑 **One rate per call, on purpose.** A bulk form would need one reason
+ * covering a heterogeneous set, which is the same argument that removed the
+ * bulk offer-cancel: one shared reason across unlike records is worse audit
+ * data than no bulk action. Repricing three things is three decisions.
+ */
+export declare function applyRateChange(input: ApplyRateChangeInput, actor: {
+    uid: string;
+    name?: string;
+    isAdmin: boolean;
+}, now?: Date): Promise<ApplyRateChangeResult>;