@mohasinac/appkit 4.69.1 → 4.71.0

package/PROVIDERS.md

@@ -0,0 +1,190 @@
+# Provider registry — what you can replace, and what you cannot
+
+Written against the tree on **2026-10-29**. Every count here was measured, not
+estimated; re-measure before quoting any of it elsewhere.
+
+appkit reaches the outside world through one registry. A consumer calls
+`registerProviders()` once at boot and appkit code asks for what it needs:
+
+```ts
+import { registerProviders } from "@mohasinac/appkit/contracts/registry";
+
+registerProviders({
+  db: myDbProvider,
+  auth: myAuthProvider,
+  session: mySessionProvider,
+  email: myEmailProvider,
+  storage: myStorageProvider,
+  style: tailwindAdapter,
+});
+```
+
+The five without `?` in `ProviderRegistry` are required by the type. The rest
+are optional, and an absent optional provider means "appkit keeps its existing
+behaviour" — never a throw.
+
+---
+
+## 🛑 Read this before planning a replacement: Firebase is a hard dependency today
+
+**appkit is "Firebase ecommerce from scratch", not "ecommerce from scratch".**
+
+| Measured 2026-10-29 | |
+|---|---|
+| appkit files importing `firebase-admin` / `firebase/*` **outside `providers/`** | **59** |
+| appkit files calling `getAdminDb` / `getAdminAuth` / `getAdminStorage` directly | **64** |
+
+`IDbProvider` exists and is registered, but 64 files bypass it and talk to the
+Admin SDK. So swapping `db` for Postgres does **not** work today, whatever the
+registry's shape suggests. The seams that are real are listed below; the rest
+is a direction of travel.
+
+This is stated plainly because the alternative is discovering it in a sales
+conversation. Closing it is a tracked tier (AK3-dip-direct-repo: *"every appkit
+component/hook importing a concrete repository instead of a provider"*), not a
+afternoon's work.
+
+---
+
+## The slots
+
+🛑 **"Read?" is the column that matters.** A slot nothing reads is
+indistinguishable from one that works — the consumer passes a provider, appkit
+accepts it, and the value is never fetched. Six slots are in that state right
+now. `scripts/audit-provider-registry-readers.mjs` blocks a seventh.
+
+| Slot | Contract | letitrip registers | Read? | Replaceable today? |
+|---|---|---|---|---|
+| `db` | `IDbProvider` | `firebaseDbProvider` | ✅ 46 files | ❌ — 64 files bypass it for the Admin SDK |
+| `auth` | `IAuthProvider` | `firebaseAuthProvider` | ✅ 4 | partly |
+| `session` | `ISessionProvider` | `firebaseSessionProvider` | ✅ 3 | partly |
+| `email` | `IEmailProvider` | `createResendProvider(...)` | ✅ 1 | **yes** — the cleanest seam in the package |
+| `payment` | `IPaymentProvider` | manual \| Razorpay \| PhonePe | ✅ 11 | **yes** — three implementations prove it |
+| `shipping` | `IShippingProvider` | manual \| Shiprocket | ✅ 6 | **yes** — two implementations |
+| `rbac` | `IRbacProvider` | inline `{getPermissions, isAdmin}` | ✅ 1 | yes |
+| `eventBus` | `IEventBus` | — | ✅ 1 | yes |
+| `storage` | `IStorageProvider` | `firebaseStorageProvider` | 🛑 **0** | no — media code imports the provider module directly |
+| `style` | `IStyleAdapter` | `tailwindAdapter` | 🛑 **0** | no — reached by direct import |
+| `tax` | `ITaxProvider` | `indiaGstTaxProvider` | 🛑 **0** | **blocked — see below** |
+| `search` | `ISearchProvider` | — | 🛑 **0** | no — listing queries call repositories |
+| `cache` | `ICacheProvider` | — | 🛑 **0** | declared only |
+| `queue` | `IQueueProvider` | — | 🛑 **0** | declared only; the job primitive is `enqueueJob` + `JOB_RUNNERS` |
+
+`payment` and `shipping` are the two to copy when writing a new provider: each
+has more than one real implementation, selected at boot from site settings, and
+a fall-through to a complete manual flow. A half-configured gateway fails
+loudly at boot rather than when a buyer tries to pay.
+
+### 🛑 `tax` — a declared seam that cannot be read yet
+
+Two obstacles, and the second is a design problem rather than effort:
+
+1. **Runtime.** Its call sites are in `_internal/shared/checkout/order-math.ts`,
+   which is isomorphic — `features/cart/utils/line-total.ts` reaches it from the
+   *client* graph for per-store subtotals. `getProviders()` throws where nothing
+   registered, and a consumer registers on the server only. (Same trap
+   `features/contact/email.tsx` documents for Firebase Functions, where it made
+   the daily digest silently never deliver.)
+2. **Shape.** `TaxBreakdown` carries `components[]` keyed by provider-specific
+   codes. `order-math.ts` needs named `cgst`/`sgst`/`igst` scalars — 27
+   references — because India's Rule 46 requires tax *per rate* on the invoice.
+   Converting means generic code doing `components.find(c => c.code === "cgst")`,
+   re-importing the exact vocabulary the interface exists to abstract.
+
+The honest reading: **`order-math.ts` is not generic code that uses GST, it is
+India invoice code.** Fixing it is a decision about where GST invoice assembly
+lives, on a money path.
+
+---
+
+## Two injection mechanisms, and which to use
+
+The registry is not the only seam. Some values are needed on **every runtime**,
+including the browser bundle and Firebase Functions, neither of which calls
+`registerProviders()`.
+
+| Need | Mechanism | Call it in |
+|---|---|---|
+| A service appkit calls (db, email, payment) | `registerProviders({...})` | `providers.config.ts` (server) |
+| A value isomorphic code reads (brand, currency, storage namespace) | a `configure*` function | **both** `providers.config.ts` *and* `client-providers-init.ts` |
+
+The `configure*` family — all merge rather than replace, all have neutral
+defaults:
+
+| Function | Module | Sets |
+|---|---|---|
+| `configureBrand` | `core/brand-resolver` | name, shortName, domain, support/noreply email |
+| `configureMarketDefaults` | `core/baseline-resolver` | currency, locale, country, phone prefix, timezone, symbol |
+| `setStorageNamespace` | `constants/storage-keys` | the prefix on every browser storage key |
+| `configurePlatformSupplier` | `_internal/.../supplier-of-record` | statutory identity for invoices (server only) |
+
+🛑 **Module state does not cross a module graph.** A `configure*` call in
+`providers.config.ts` runs from the instrumentation hook and is invisible to the
+browser bundle. An isomorphic value needs the call in both places, reading the
+same owner (`appkit.config.js`) so the two cannot disagree about the value —
+only about whether they ran.
+
+🛑 **Brand defaults are NEUTRAL (`"Site"`), market defaults are not.**
+`baseline-resolver`'s baseline is India's (INR / en-IN / +91). That asymmetry is
+deliberate: a wrong currency is visible in the first rendered price, while a
+wrong brand name renders plausibly and is someone else's trademark.
+
+---
+
+## The override hierarchy — least invasive first
+
+Replacing a provider is the *fifth* of six options. Try them in order:
+
+1. **Config / tokens** — `siteSettings.theme`, a partial `LabelsProvider` map,
+   `appkit.config.js`.
+2. **Options object** — every public function takes an optional final `opts?`.
+   `renderXOgImage(doc, { theme, headline, layout: "compact" })`.
+3. **Render-prop slots** — `<XDetailView renderActions={(ctx) => <MyActions/>}>`.
+4. **Adapter wrap** — `const myToClient = (doc) => decorate(toClientX(doc))`.
+5. **Replace the call** — register your own provider, or call the repository
+   directly and skip the helper.
+6. **Fork via patch** — only when the seam does not exist. File an issue; the
+   seam should ship in appkit rather than live in your fork.
+
+---
+
+## Writing a provider
+
+Contracts are **abstract classes**, not interfaces, so every implementation
+shares one base:
+
+```ts
+import { IPaymentProvider } from "@mohasinac/appkit/contracts/payment";
+
+export class MyGateway extends IPaymentProvider {
+  readonly id = "my-gateway";
+  // implement the abstract members; `tsc` enumerates them for you
+}
+```
+
+Three rules learned the hard way:
+
+- **Fail at boot, not at point of use.** A provider constructed with empty
+  credentials should throw while the app is starting. The alternative is a buyer
+  discovering it at checkout.
+- **Treat a placeholder as absent.** Seeded credentials like
+  `re_PLACEHOLDER` are truthy. `resolveKeys()` maps them to absent so a flag
+  switched on with no real key does not look configured.
+- **Never name your gateway in generic code.** `audit-provider-name-leak`
+  blocks it: a provider name belongs inside its own `providers/<name>/`
+  directory and nowhere else.
+
+---
+
+## Verifying a standalone install
+
+🛑 **There is no proof app yet, so "standalone" remains a claim.**
+
+The acceptance test is a scratch Next.js app that installs appkit from the
+registry, registers a **non-Firebase** provider for at least one contract, and
+renders a catalogue. Given the 64 files above, the honest expectation is that it
+fails on `db` and succeeds on `email` — which is exactly why the test is worth
+running rather than reasoned about.
+
+It cannot be written against this tree: it must install a *published* version,
+and the work described in this document is not published yet.

package/dist/.build-stamp.json

@@ -1,8 +1,8 @@
 {
   "stampVersion": 1,
-  "version": "4.69.1",
-  "head": "1a1259a8058e4a957e71fef93fe49c34708f77bb",
+  "version": "4.71.0",
+  "head": "260f012ee352221df711fee74a7d61d8825ae3c5",
   "branch": "main",
   "dirty": false,
-  "builtAt": "2026-10-27T13:28:31.858Z"
+  "builtAt": "2026-10-29T02:57:55.180Z"
 }

package/dist/_internal/client/features/lottery/LotteryAdminSlotView.js

@@ -5,6 +5,7 @@ import { Text, Heading } from "../../../../ui/components/Typography.js";
 import { Badge } from "../../../../ui/components/Badge.js";
 import { Section } from "../../../../ui/components/Semantic.js";
 import { DataTable } from "../../../../ui/DataTable.js";
+import { formatMoney } from "../../../../utils/number.formatter.js";
 /**
  * Admin-only view showing slots with price + weight + % chance.
  * Separate from LotterySlotGrid (public) which never shows price/weight.
@@ -25,7 +26,7 @@ export function LotteryAdminSlotView({ slots }) {
         {
             key: "price",
             header: "Price (₹)",
-            render: (s) => (_jsxs(Text, { size: "sm", family: "mono", children: ["\u20B9", s.price.toLocaleString("en-IN")] })),
+            render: (s) => (_jsx(Text, { size: "sm", family: "mono", children: formatMoney(s.price) })),
         },
         {
             key: "weight",

package/dist/_internal/server/features/checkout/actions.js

@@ -45,6 +45,7 @@ import { computeProtectionFees } from "../../../shared/features/shipping/protect
 /* S5a — one payer, N destinations. Pure: the rates come in snapshotted, and
  * an UNPRICED arrangement is refused rather than quoted at ₹0 (D44's lesson). */
 import { countDestinations, quoteSharedPurchase, } from "../../../shared/features/shipping/shared-purchase.js";
+import { formatMoney } from "../../../../utils/number.formatter.js";
 import { resolveCouponCategorySlugs } from "../../../../features/promotions/actions/coupon-actions.js";
 import { assertCheckoutLane, assertLockedLinesStillValid, finalizeLockedLines, } from "./locked-lines.js";
 import { activeLane, defaultCheckoutItems, resolveCheckoutItems, laneOf, } from "../../../shared/checkout/lanes.js";
@@ -65,7 +66,6 @@ import { getProviders } from "../../../../contracts/index.js";
  * index would pull a static `import Razorpay from "razorpay"` into this
  * action's import graph for one HMAC comparison — see that file's header.
  */
-import { verifyPaymentSignature as verifyRazorpayPaymentSignature } from "../../../../providers/payment-razorpay/signature.js";
 import { resolveKeys } from "../../../../core/integration-keys.js";
 import { paiseToRupees } from "../../../../core/money.js";
 import { CHECKOUT_DEFAULT_COMMISSIONS, CHECKOUT_DEFAULT_EMI_SETTINGS } from "../../../shared/features/checkout/config.js";
@@ -868,7 +868,7 @@ async function createOrderForGroup(group, orderType, ctx) {
      */
     const emiGate = groupEmiGate(emiGroupInput, emiSettings);
     if (emiOptIn && emiTenureMonths && !emiGate.applies) {
-        throw new ValidationError(`EMI is not available for this order (${emiGate.reason}). Minimum order value per seller is ₹${emiSettings.minOrderValue}.`);
+        throw new ValidationError(`EMI is not available for this order (${emiGate.reason}). Minimum order value per seller is ${formatMoney(emiSettings.minOrderValue)}.`);
     }
     const emiSchedule = groupEmiSchedule(emiGroupInput, emiSettings) ?? undefined;
     // Handling fee charged to the buyer for choosing COD, on top of the order
@@ -2897,8 +2897,43 @@ export async function verifyAndPlaceGatewayOrderAction(input) {
      */
     if (input.razorpaySignature) {
         const { razorpayKeySecret } = await resolveKeys();
+        /*
+         * 🛑 A4b — through the CONTRACT, not a direct Razorpay import.
+         *
+         * This file used to `import { verifyPaymentSignature } from
+         * "providers/payment-razorpay/signature"`, which named one gateway in the
+         * one place that has to work for every gateway. `verifyCheckoutSignature`
+         * is on `IPaymentProvider` now; Razorpay's implementation calls the SAME
+         * function with the SAME HMAC, so no arithmetic moved.
+         *
+         * Everything that made this fail closed is unchanged: the branch still only
+         * runs when a signature is present, the secret is still resolved here, and
+         * `!!razorpayKeySecret` still short-circuits. A provider with no such
+         * handshake (manual, PhonePe) returns `false` — never `true`.
+         *
+         * Proven rather than argued: `.build-memory/checkout-sig-parity.mjs` ran
+         * both paths over 12 cases — valid, tampered order id, tampered payment id,
+         * wrong secret, empty secret, non-hex, short, and every missing-field
+         * permutation. The provider never accepts what the direct call rejected.
+         *
+         * One case differs, in the safe direction, and it fixes a latent crash:
+         * on a callback MISSING `razorpay_signature` the old call THREW
+         * (`hexEqual` reads `.length` of `undefined`), so a malformed callback
+         * escaped as an unhandled TypeError instead of taking the rejection path
+         * below. The provider checks its three fields first and returns false, so
+         * that request now gets logged as `signature_mismatch` like any other
+         * forgery.
+         */
+        /*
+         * 🛑 No `payment!`. `payment` is OPTIONAL on the registry, and a missing
+         * provider must reject rather than throw — the same fail-closed direction
+         * as the absent secret beside it. An assertion here would turn an
+         * unconfigured install into a 500 on the payment path.
+         */
+        const paymentProvider = getProviders().payment;
         const signatureValid = !!razorpayKeySecret &&
-            verifyRazorpayPaymentSignature(input.razorpaySignature, razorpayKeySecret);
+            !!paymentProvider &&
+            paymentProvider.verifyCheckoutSignature(input.razorpaySignature, razorpayKeySecret);
         if (!signatureValid) {
             serverLogger.warn(`Razorpay signature rejected: order=${input.razorpaySignature.razorpay_order_id} payment=${input.razorpaySignature.razorpay_payment_id}`);
             failedCheckoutRepository
@@ -3022,7 +3057,7 @@ export async function verifyAndPlaceGatewayOrderAction(input) {
     // (no session) reconstructs them from the gateway's own passthrough channel
     // — PhonePe's `metaInfo`, Razorpay's `notes` — both packed at create-order
     // time and both surfaced as `PaymentOrder.metadata`. See
-    // `PhonePeCheckoutIntent`, which is the shape either one carries.
+    // `CheckoutIntentMetadata`, which is the shape either one carries.
     const intent = gatewayOrder.metadata;
     const uid = input.userId ?? intent?.uid;
     if (!uid) {
@@ -3428,9 +3463,9 @@ export async function verifyAndPlaceGatewayOrderAction(input) {
         const amountDelta = paidAmountRs - expectedPaymentAmountRs;
         const AMOUNT_TOLERANCE_RS = 1;
         if (amountDelta < -AMOUNT_TOLERANCE_RS) {
-            serverLogger.warn(`Payment amount mismatch for user ${uid}: paid ₹${paidAmountRs}, expected ≥ ₹${expectedPaymentAmountRs}`);
+            serverLogger.warn(`Payment amount mismatch for user ${uid}: paid ${formatMoney(paidAmountRs)}, expected ≥ ${formatMoney(expectedPaymentAmountRs)}`);
             failedCheckoutRepository
-                .logPayment(uid, "amount_mismatch", `Paid ₹${paidAmountRs}, expected ≥ ₹${expectedPaymentAmountRs}`, {
+                .logPayment(uid, "amount_mismatch", `Paid ${formatMoney(paidAmountRs)}, expected ≥ ${formatMoney(expectedPaymentAmountRs)}`, {
                 gatewayOrderId: gatewayOrder.gatewayOrderId,
                 gatewayPaymentId: merchantOrderId,
                 amountRs: paidAmountRs,
@@ -3440,9 +3475,9 @@ export async function verifyAndPlaceGatewayOrderAction(input) {
             throw new ValidationError(ERROR_MESSAGES.CHECKOUT.PAYMENT_FAILED);
         }
         if (amountDelta > AMOUNT_TOLERANCE_RS) {
-            serverLogger.error(`OVER-CAPTURE for user ${uid}: paid ₹${paidAmountRs}, expected ₹${expectedPaymentAmountRs} (surplus ₹${amountDelta.toFixed(2)}) — order will still be placed`, { merchantOrderId, expectedCouponDiscount });
+            serverLogger.error(`OVER-CAPTURE for user ${uid}: paid ${formatMoney(paidAmountRs)}, expected ${formatMoney(expectedPaymentAmountRs)} (surplus ${formatMoney(amountDelta)}) — order will still be placed`, { merchantOrderId, expectedCouponDiscount });
             failedCheckoutRepository
-                .logPayment(uid, "amount_mismatch", `OVER-CAPTURE: paid ₹${paidAmountRs}, expected ₹${expectedPaymentAmountRs}, surplus ₹${amountDelta.toFixed(2)} — refund owed`, {
+                .logPayment(uid, "amount_mismatch", `OVER-CAPTURE: paid ${formatMoney(paidAmountRs)}, expected ${formatMoney(expectedPaymentAmountRs)}, surplus ${formatMoney(amountDelta)} — refund owed`, {
                 gatewayOrderId: gatewayOrder.gatewayOrderId,
                 gatewayPaymentId: merchantOrderId,
                 amountRs: paidAmountRs,

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

@@ -37,6 +37,7 @@ import { PAYMENT_WINDOW_MS, PAYMENT_FRAUD_REJECTED_REASON, isManualPaymentMethod
 import { deadlinesFor } from "../../../shared/obligations/deadlines.js";
 import { normalizeError } from "../../../../errors/normalize.js";
 import { serverLogger } from "../../../../monitoring/index.js";
+import { formatMoney } from "../../../../utils/number.formatter.js";
 export async function createOrderAction(input) {
     return wrapAction(async () => {
         const user = await requireRoleUser(["user", "buyer", "seller", "admin"]);
@@ -181,7 +182,7 @@ function notifyAdminsOfPaymentProof(order) {
             await adminNotificationsRepository.create({
                 category: "payouts",
                 title: "Payment proof awaiting review",
-                body: `${order.userName} uploaded proof for "${order.productTitle}" (₹${order.totalPrice.toLocaleString("en-IN")}). Review before the 2-hour auto-approve window closes.`,
+                body: `${order.userName} uploaded proof for "${order.productTitle}" (${formatMoney(order.totalPrice)}). Review before the 2-hour auto-approve window closes.`,
                 severity: "warning",
                 isRead: false,
                 entityType: "order",

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

@@ -269,6 +269,24 @@ export function orderDocumentToOrder(doc) {
         supplierGstin: doc.supplierGstin,
         supplierLegalName: doc.supplierLegalName,
         supplierAddress: doc.supplierAddress,
+        /*
+         * 🛑 Root Cause #57, in the one place it is most visible: this adapter
+         * mapped the CGST/SGST/IGST split above and dropped the field that
+         * EXPLAINS it.
+         *
+         * Place of supply is what decides whether a supply is intra-State
+         * (CGST+SGST) or inter-State (IGST). Without it the HTML invoice showed a
+         * split it could not justify — and the PDF, which reads the raw
+         * `OrderDocument` rather than going through here, printed the line
+         * correctly. So the two invoices for ONE order disagreed on a Rule 46(n)
+         * field, and the buyer-facing one was the deficient half.
+         *
+         * Nothing was wrong with the data: `createOrderForGroup` has always
+         * written it. It simply never crossed the client boundary, which is why
+         * the gap reads as "this order has no place of supply" rather than as a
+         * dropped field.
+         */
+        placeOfSupply: doc.placeOfSupply,
         codHandlingFee: doc.codHandlingFee,
         trackingNumber: doc.trackingNumber,
         shippingCarrier: doc.shippingCarrier,

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

@@ -35,6 +35,7 @@ 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";
+import { formatMoney } from "../../../../utils/number.formatter.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
@@ -128,7 +129,7 @@ export async function openBalanceCollection(orderId, actor, now = new Date()) {
         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.`,
+        message: `The balance of ${formatMoney(due)} on order ${orderId} is now payable. Your item is ready to ship once it clears.`,
         relatedId: orderId,
         relatedType: "order",
     });

package/dist/_internal/server/features/orders/cancellation-refund.d.ts

@@ -1,92 +1,3 @@
-/**
- * Cancel an order AND give the money back — one owner, three callers.
- *
- * ## D14, and why passing the amount was only half of it
- *
- * `cancelOrder(orderId, reason, refundAmount?)` has carried an optional
- * `refundAmount` since it was written, and **all four callers omitted it**. So
- * cancelling a *paid* order restored stock and left the money with us, while
- * `previewCancellationRefund` showed the buyer a figure nothing honoured.
- *
- * 🛑 **But passing the amount alone would have made it WORSE.** `cancelOrder`'s
- * body writes `{ refundAmount, refundStatus: "pending" }` and nothing else —
- * there is no provider call anywhere in it. So the obvious fix creates a *new*
- * dead state: a recorded refund intent that nothing ever settles, which is
- * strictly worse than today's honest silence because it reads, in the database,
- * as though a refund is on its way. The amount and the movement have to land
- * together, which is why this module exists rather than a one-line edit at each
- * call site.
- *
- * ## The decision table
- *
- * Every row cancels the order and **restores its stock** — see `releaseStock`,
- * which closes a second half of D14 the plan had recorded backwards. The table
- * is only about the money.
- *
- * | condition | what happens to the money |
- * |---|---|
- * | `paymentStatus !== "paid"` | **nothing** — nothing was ever captured |
- * | nothing left refundable | nothing — already refunded in full |
- * | goods have left the seller | intent recorded, **case opened** — a human decides |
- * | paid by cash / UPI-manual / EMI | intent recorded, **case opened** — there is no automatic rail |
- * | paid through the gateway | **refunded automatically**, in full, once |
- *
- * The last row is the only automatic money movement, and it satisfies the
- * plan's guardrail for one: the ceiling is an amount we captured, the recipient
- * is the payer, and no counterparty is debited.
- *
- * ## Three things that are load-bearing
- *
- * **It goes through `processRefundAction`, never `payment.refund()` directly.**
- * That action owns the idempotency claim, the cumulative cap against
- * `refundableBase`, and the two-phase reserve/settle write around the provider
- * call. A direct provider call here would reintroduce every defect step 8
- * closed — D1, D2, D6 and D7 at once.
- *
- * **The key is `cancel_{orderId}`** — a NATURAL key, so a double-clicked Cancel
- * button, a retried server action and a sweep all collapse to one refund. A
- * `randomUUID()` here would be D2 wearing a new name.
- *
- * ## Points ARE reversed here now (Phase P)
- *
- * `pointsLedger`'s own header states the rule as a legal boundary: *"points
- * spent on a cancelled order are returned as points"* — never as money, because
- * paying them out in rupees is what would make this stored value, which in
- * India is PPI territory with RBI authorisation attached.
- *
- * `reverseRedemptionForOrder` is that rule's first writer; the kind had been
- * declared with none since it was written (D48). It is idempotent on the order
- * — one reversal per order, checked by query before the write, because an
- * append-only ledger cannot net off a double reversal.
- *
- * 🛑 **It stopped being a no-op on 2026-10-22.** This paragraph read "It is a
- * NO-OP today and still correct to call … when redemption becomes a real
- * tender, cancellation already gives the points back" — and the tender is now
- * built (`resolvePointsTender` + `settlePointsTender` in `checkout/actions.ts`),
- * so orders carry `pointsApplied` and this query finds real redemptions. The
- * bet paid off: no cancellation path had to be remembered, because the reversal
- * was already wired and keyed.
- *
- * 🛑 **The MONEY half had to change in the same commit, and it is the sharper
- * of the two.** `refundableBase` now subtracts `pointsApplied`, because a
- * refund can only return what was collected: on a ₹1,000 order settled with
- * 250 points the card paid ₹750, so refunding the full base would return
- * ₹1,000 in cash AND 250 points — ₹250 of real money conjured from a discount.
- * Two halves of one refund, in two units, and only their sum is what the buyer
- * gave up.
- *
- * **Cancel, then stock, then money.** The cancellation is the urgent half and
- * must not be held hostage to a gateway round trip; the restock is a local
- * write another buyer is actively waiting on; the refund is the one step that
- * can hang for a full network timeout. The cost of that ordering is a window
- * where the order is `cancelled` with the money still held — which is exactly
- * why `refundAmount` is written *at cancellation time*, before the provider is
- * called: a crash in the window leaves a detectable artefact rather than
- * nothing, and R5 in `paymentReconcile` is the thing that finds it. The reverse
- * ordering has no such consolation, because a refund posted against a live
- * order that then fails to cancel is money gone from an order the buyer still
- * expects to receive.
- */
 import type { OrderDocument } from "../../../../features/orders/schemas/firestore";
 import type { CancellationRefundOutcome } from "../../../../features/orders/types/index";
 import type { HistoryActor } from "../../../shared/history/types";

package/dist/_internal/server/features/orders/cancellation-refund.js

@@ -1,3 +1,4 @@
+import { formatMoney } from "../../../../utils/number.formatter.js";
 /**
  * Cancel an order AND give the money back — one owner, three callers.
  *
@@ -212,7 +213,7 @@ async function openOwedCase(order, amount, why, detailLines) {
              */
             subjectId: order.id,
             severity: "error",
-            title: `Refund of ₹${amount.toFixed(2)} owed on cancelled order ${order.id}`,
+            title: `Refund of ${formatMoney(amount)} owed on cancelled order ${order.id}`,
             detail: [
                 ...detailLines,
                 "",
@@ -221,7 +222,7 @@ async function openOwedCase(order, amount, why, detailLines) {
                 `Store: ${order.storeId ?? "—"}`,
                 `Payment method: ${order.paymentMethod ?? "unknown"}`,
                 `Gateway reference: ${order.paymentId ?? "—"}`,
-                `Amount owed: ₹${amount.toFixed(2)}`,
+                `Amount owed: ${formatMoney(amount)}`,
                 "",
                 "The order is cancelled and its stock is restored. `refundAmount` is recorded on the order with `refundStatus: \"pending\"`, so this case and the order agree about what is owed.",
             ].join("\n"),

package/dist/_internal/server/features/payouts/actions.js

@@ -64,6 +64,7 @@ import { payoutRepository } from "../../../../features/payments/repository/payou
 import { serverErrorsRepository } from "../../../../features/server-errors/repository/server-errors.repository.js";
 import { ValidationError } from "../../../../errors/index.js";
 import { roundRupees } from "../../../../utils/number.formatter.js";
+import { formatMoney } from "../../../../utils/number.formatter.js";
 export async function applyRefundDeductionAction(input) {
     return wrapAction(async () => {
         if (input.refundedAmount <= 0) {
@@ -95,7 +96,7 @@ export async function applyRefundDeductionAction(input) {
                 source: "vercel",
                 route: "applyRefundDeductionAction",
                 code,
-                message: `Clawback of ₹${deductedAmount} for order ${input.orderId} (store ${input.storeId}) could not be applied: ${unrecoverable}. ` +
+                message: `Clawback of ${formatMoney(deductedAmount)} for order ${input.orderId} (store ${input.storeId}) could not be applied: ${unrecoverable}. ` +
                     `The seller retains this amount for returned goods; there is no automatic recovery until a seller ledger exists.`,
                 requestId: input.refundId,
             });

package/dist/_internal/server/features/points/award.js

@@ -56,6 +56,7 @@ import { POINTS_EARN_PERCENT, pointsExpiryFrom, } from "../../../../features/poi
 import { orderTaxableValue } from "../../../shared/checkout/order-math.js";
 import { normalizeError } from "../../../../errors/normalize.js";
 import { serverLogger } from "../../../../monitoring/index.js";
+import { formatMoney } from "../../../../utils/number.formatter.js";
 function roundPoints(value) {
     return Math.round(value * 100) / 100;
 }
@@ -160,13 +161,13 @@ export async function awardPurchasePoints(order) {
          * later — and written once rather than re-derived, so it stays true of this
          * moment even if the order is edited afterwards.
          */
-        description: `${POINTS_EARN_PERCENT}% back on ${order.id}: ₹${moneyPaidForGoods.toFixed(2)} of items` +
+        description: `${POINTS_EARN_PERCENT}% back on ${order.id}: ${formatMoney(moneyPaidForGoods)} of items` +
             // Named explicitly, because an unexplained gap between the order's item
             // value and the earn base is exactly the kind of figure a buyer writes
             // in to ask about — and the answer ("you paid part of it with points")
             // is a fact about their own order that they can check.
             ((order.pointsApplied ?? 0) > 0
-                ? ` (₹${goods.toFixed(2)} of items less ${order.pointsApplied} points).`
+                ? ` (${formatMoney(goods)} of items less ${order.pointsApplied} points).`
                 : "."),
         expiresAt: pointsExpiryFrom(now),
     });

package/dist/_internal/server/features/protection-claims/actions.js

@@ -35,6 +35,7 @@ import { adjudicateClaim, SALE_PROTECTION_MAX_VALUE, } from "../../../shared/fea
 import { deadlinesFor } from "../../../shared/obligations/deadlines.js";
 import { paymentCasesRepository } from "../../../../features/payment-cases/repository/payment-cases.repository.js";
 import { orderGoodsValue } from "../../../shared/checkout/order-math.js";
+import { formatMoney } from "../../../../utils/number.formatter.js";
 /**
  * File a claim as the buyer.
  *
@@ -100,7 +101,7 @@ export async function fileProtectionClaimAction(input) {
          */
         const claimedAmount = orderGoodsValue(order);
         if (kind === "sale" && claimedAmount > SALE_PROTECTION_MAX_VALUE) {
-            throw new ValidationError(`Sale protection covers orders up to ₹${SALE_PROTECTION_MAX_VALUE.toLocaleString("en-IN")}. This order is above that, so the claim needs a human — please contact support.`);
+            throw new ValidationError(`Sale protection covers orders up to ${formatMoney(SALE_PROTECTION_MAX_VALUE)}. This order is above that, so the claim needs a human — please contact support.`);
         }
         const claim = await protectionClaimsRepository().file({
             kind,

package/dist/_internal/server/features/refunds/actions.js

@@ -49,6 +49,7 @@ import { applyRefundDeductionAction } from "../payouts/actions.js";
 import { issueCreditNoteForRefund } from "../invoicing/credit-note.js";
 import { getAdminDb } from "../../../../providers/db-firebase/index.js";
 import { PRODUCT_COLLECTION, PRODUCT_CODES_SUBCOLLECTION, } from "../../../../features/products/schemas/firestore.js";
+import { formatMoney } from "../../../../utils/number.formatter.js";
 /**
  * SB-UNI-N — block the refund if any of the order's digital codes has already
  * been claimed (revealed). Throws ValidationError on the first claimed code.
@@ -146,9 +147,9 @@ export async function processRefundAction(input) {
          */
         const capacity = refundCapacity(order, siteSettings?.commissions?.gstPercent);
         if (input.amount > capacity.remaining + MONEY_EPSILON) {
-            throw new ValidationError(`Refund of ₹${input.amount.toFixed(2)} exceeds the ₹${capacity.remaining.toFixed(2)} still refundable on this order` +
+            throw new ValidationError(`Refund of ${formatMoney(input.amount)} exceeds the ${formatMoney(capacity.remaining)} still refundable on this order` +
                 (capacity.withheld > 0
-                    ? ` (₹${capacity.withheld.toFixed(2)} platform fee is non-refundable).`
+                    ? ` (${formatMoney(capacity.withheld)} platform fee is non-refundable).`
                     : "."));
         }
         // Guard: non-refundable orders (prize draws, bundles). A property of the

package/dist/_internal/server/features/shipping/courier-block.js

@@ -23,7 +23,10 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
  *    operator blind to everything else.
  */
 import { Fragment } from "react";
-import { renderToStaticMarkup } from "react-dom/server";
+// 🛑 Lazy require, not a top-level `react-dom/server` import — this module is
+// reachable from a Server Component via appkit/server, and Next's static tracer
+// fails the build on it. See render-static-markup.ts.
+import { renderStaticMarkup } from "../../../../features/email/render-static-markup.js";
 import { EmailContainer, EmailDoc, EmailRow, } from "../../../../features/email/primitives.js";
 import { paymentCasesRepository } from "../../../../features/payment-cases/repository/payment-cases.repository.js";
 // `adminNotificationsRepository` lives behind the repositories barrel — the
@@ -260,5 +263,5 @@ async function emailStaff(input) {
  * our own constants and the provider/reason enums.
  */
 function renderStaffAlertEmail(title, body) {
-    return `<!DOCTYPE html>${renderToStaticMarkup(_jsx(EmailDoc, { title: title, children: _jsx(EmailContainer, { children: _jsx(EmailRow, { children: body.split("\n\n").map((para, i) => (_jsxs(Fragment, { children: [i > 0 ? _jsx("br", {}) : null, i > 0 ? _jsx("br", {}) : null, para.split("\n").map((line, j) => (_jsxs(Fragment, { children: [j > 0 ? _jsx("br", {}) : null, line] }, j)))] }, i))) }) }) }))}`;
+    return `<!DOCTYPE html>${renderStaticMarkup(_jsx(EmailDoc, { title: title, children: _jsx(EmailContainer, { children: _jsx(EmailRow, { children: body.split("\n\n").map((para, i) => (_jsxs(Fragment, { children: [i > 0 ? _jsx("br", {}) : null, i > 0 ? _jsx("br", {}) : null, para.split("\n").map((line, j) => (_jsxs(Fragment, { children: [j > 0 ? _jsx("br", {}) : null, line] }, j)))] }, i))) }) }) }))}`;
 }

package/dist/_internal/server/features/shipping/reconcile.js

@@ -8,6 +8,7 @@ import { orderRepository } from "../../../../features/orders/repository/orders.r
 import { pointsRepository } from "../../../../features/points/repository/points.repository.js";
 import { reconcileShipping, } from "../../../shared/shipping/quote.js";
 import { serverLogger } from "../../../../monitoring/index.js";
+import { formatMoney } from "../../../../utils/number.formatter.js";
 /**
  * 🛑 IDEMPOTENT, and the guard is `order.shippingReconciliation` being unset.
  *
@@ -106,8 +107,8 @@ export async function reconcileOrderShipping(orderId, actual) {
              * never re-derived, so it stays true of the moment it describes even if
              * the order is edited afterwards.
              */
-            description: `Shipping saving on ${orderId}: charged ₹${order.selectedShippingQuote.chargedRate} ` +
-                `for ${order.selectedShippingQuote.courierName}, shipped ₹${actual.actualRate} ` +
+            description: `Shipping saving on ${orderId}: charged ${formatMoney(order.selectedShippingQuote.chargedRate)} ` +
+                `for ${order.selectedShippingQuote.courierName}, shipped ${formatMoney(actual.actualRate)} ` +
                 `via ${actual.courierName}.`,
         });
     }