@mohasinac/appkit 4.30.18 → 4.30.19

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

@@ -1,7 +1,12 @@
 import { cache } from "react";
 import { orderRepository } from "../../../../repositories";
+import { safeRead } from "../../../../errors/safe-read";
 export const getOrderForDetail = cache(async (orderId) => {
-    return (await orderRepository.findById(orderId).catch(() => undefined)) ?? null;
+    // No catch: this order IS the page. Swallowing a Firestore failure to null
+    // renders "order not found" for a datastore outage — the caller cannot tell
+    // the two apart, which is Root Cause #59 on the money path. A throw reaches
+    // the route/error boundary and is now recorded.
+    return (await orderRepository.findById(orderId)) ?? null;
 });
 export const getOrdersForBuyer = cache(async (userId, page = 1, pageSize = 20) => {
     return orderRepository.listForUser(userId, { page, pageSize }).catch(() => ({
@@ -14,5 +19,12 @@ export const getOrdersForBuyer = cache(async (userId, page = 1, pageSize = 20) =
     }));
 });
 export const getRecentOrdersForBuyer = cache(async (userId) => {
-    return orderRepository.findRecentByUser(userId).catch(() => []);
+    // Optional: a recent-orders rail. Degrading to empty is right, but it must
+    // be VISIBLE — safeRead records a DEGRADED_READ row instead of returning a
+    // value indistinguishable from "no recent orders".
+    return safeRead(() => orderRepository.findRecentByUser(userId), {
+        route: "/user/orders",
+        key: "orders.findRecentByUser",
+        fallback: [],
+    });
 });

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

@@ -2,7 +2,7 @@ import { orderRepository } from "../../../../repositories";
 import { OrderNotFoundError, OrderCancelError, OrderOwnershipError, OrderReturnWindowError, } from "../../../shared/features/orders/errors";
 import { ORDER_CANCELLABLE_STATUSES, ORDER_RETURN_WINDOW_MS, } from "../../../shared/features/orders/config";
 export async function assertOrderOwnership(orderId, userId) {
-    const order = await orderRepository.findById(orderId).catch(() => null);
+    const order = await orderRepository.findById(orderId);
     if (!order)
         throw new OrderNotFoundError(orderId);
     if (order.userId !== userId)

package/dist/_internal/server/features/pre-orders/service.js

@@ -4,7 +4,7 @@ import { roundRupees } from "../../../../utils/number.formatter";
 import { PreOrderNotFoundError, PreOrderSoldOutError, PreOrderNotOpenError, } from "../../../shared/features/pre-orders/errors";
 /** Assert a pre-order exists, is published, and has remaining capacity. */
 export async function assertPreOrderAvailable(preOrderId, requestedQty = 1) {
-    const product = await productRepository.findByIdOrSlug(preOrderId).catch(() => null);
+    const product = await productRepository.findByIdOrSlug(preOrderId);
     if (!product || !isPreOrderListing(product))
         throw new PreOrderNotFoundError(preOrderId);
     if (product.status !== "published")

package/dist/_internal/server/features/prize-draws/actions.js

@@ -9,7 +9,7 @@ export async function enterPrizeDrawAction(input) {
         const { prizeDrawId } = input;
         if (!prizeDrawId)
             throw new Error("prizeDrawId is required.");
-        const product = await productRepository.findByIdOrSlug(prizeDrawId).catch(() => null);
+        const product = await productRepository.findByIdOrSlug(prizeDrawId);
         if (!product)
             throw new Error("Prize draw not found.");
         assertPrizeDrawOpen(product);

package/dist/_internal/server/features/products/data.js

@@ -8,6 +8,7 @@ import { productRepository } from "../../../../repositories";
 import { reviewRepository } from "../../../../repositories";
 import { getAdminDb } from "../../../../providers/db-firebase";
 import { normalizeError } from "../../../../errors/normalize";
+import { safeRead } from "../../../../errors/safe-read";
 import { serverLogger } from "../../../../monitoring/server-logger";
 import { PRODUCT_COLLECTION } from "../../../../features/products/schemas/firestore";
 import { PRODUCTS_SITEMAP_LIMIT } from "../../../shared/features/products/config";
@@ -23,7 +24,7 @@ import { REVIEWS_DETAIL_PAGE_SIZE } from "../../../shared/features/reviews/confi
 // ---------------------------------------------------------------------------
 /** Fetch a single product by slug or id, deduped per request. */
 export const getProductForDetail = cache(async (slugOrId) => {
-    const product = (await productRepository.findByIdOrSlug(slugOrId).catch(() => undefined)) ?? null;
+    const product = (await productRepository.findByIdOrSlug(slugOrId)) ?? null;
     // Fire-and-forget viewCount increment — must not affect response time
     if (product)
         void productRepository.incrementViewCount(product.id);
@@ -31,7 +32,11 @@ export const getProductForDetail = cache(async (slugOrId) => {
 });
 /** Fetch the first page of approved reviews for a product, deduped per request. */
 export const getReviewsForProduct = cache(async (productId, limit = REVIEWS_DETAIL_PAGE_SIZE) => {
-    return reviewRepository.findApprovedByProduct(productId, limit).catch(() => []);
+    return safeRead(() => reviewRepository.findApprovedByProduct(productId, limit), {
+        route: "/products",
+        key: "products.getReviewsForProduct",
+        fallback: [],
+    });
 });
 /** Firestore review doc → client Review shape. Shared by every listing-type detail page's reviews tab. */
 export function toReview(doc) {

package/dist/_internal/server/features/products/service.js

@@ -12,7 +12,7 @@ const ALLOWED_STATUS_TRANSITIONS = {
 };
 /** Assert a product exists and belongs to the given seller. Throws on failure. */
 export async function assertProductOwnership(productId, sellerId) {
-    const product = await productRepository.findById(productId).catch(() => null);
+    const product = await productRepository.findById(productId);
     if (!product)
         throw new ProductNotFoundError(productId);
     if (product.storeId !== sellerId)

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

@@ -33,7 +33,7 @@ export async function createCouponAction(input) {
 export async function updateCouponAction(couponId, input) {
     return wrapAction(async () => {
         await requireRoleUser(["admin", "seller"]);
-        const coupon = await couponsRepository.findById(couponId).catch(() => null);
+        const coupon = await couponsRepository.findById(couponId);
         if (!coupon)
             throw new CouponNotFoundError(couponId);
         const parsed = updateCouponSchema.safeParse(input);

package/dist/_internal/server/features/promotions/data.js

@@ -1,5 +1,5 @@
 import { cache } from "react";
 import { couponsRepository } from "../../../../repositories";
 export const getCouponByCode = cache(async (code) => {
-    return (await couponsRepository.getCouponByCode(code).catch(() => undefined)) ?? null;
+    return (await couponsRepository.getCouponByCode(code)) ?? null;
 });

package/dist/_internal/server/features/promotions/service.js

@@ -2,7 +2,7 @@ import { couponsRepository } from "../../../../repositories";
 import { roundRupees } from "../../../../utils/number.formatter";
 import { CouponNotFoundError, CouponExpiredError, CouponUsageLimitError, CouponPerUserLimitError, CouponMinPurchaseError, CouponScopeError, } from "../../../shared/features/promotions/errors";
 export async function validateCoupon(input, userId) {
-    const coupon = await couponsRepository.getCouponByCode(input.code).catch(() => null);
+    const coupon = await couponsRepository.getCouponByCode(input.code);
     if (!coupon)
         throw new CouponNotFoundError(input.code);
     if (!coupon.validity?.isActive)

package/dist/_internal/server/features/reviews/data.d.ts

@@ -1,4 +1,4 @@
-export declare const getReviewsForProduct: (productId: string, limit?: number) => Promise<never[] | import("../../../..").ReviewDocument[]>;
+export declare const getReviewsForProduct: (productId: string, limit?: number) => Promise<import("../../../..").ReviewDocument[]>;
 export declare const getReviewsForStore: (storeId: string, page?: number, pageSize?: number) => Promise<import("../../../..").FirebaseSieveResult<import("../../../..").ReviewDocument> | {
     items: never[];
     total: number;

package/dist/_internal/server/features/reviews/data.js

@@ -1,8 +1,13 @@
 import { cache } from "react";
 import { reviewRepository, orderRepository } from "../../../../repositories";
+import { safeRead } from "../../../../errors/safe-read";
 import { REVIEWS_DETAIL_PAGE_SIZE } from "../../../shared/features/reviews/config";
 export const getReviewsForProduct = cache(async (productId, limit = REVIEWS_DETAIL_PAGE_SIZE) => {
-    return reviewRepository.findApprovedByProduct(productId, limit).catch(() => []);
+    return safeRead(() => reviewRepository.findApprovedByProduct(productId, limit), {
+        route: "/products",
+        key: "reviews.getReviewsForProduct",
+        fallback: [],
+    });
 });
 export const getReviewsForStore = cache(async (storeId, page = 1, pageSize = 20) => {
     return reviewRepository.listForStore(storeId, { page, pageSize }).catch(() => ({

package/dist/_internal/server/features/reviews/og-data.js

@@ -3,5 +3,5 @@ import { reviewRepository } from "../../../../repositories";
 export const getReviewById = cache(async (id) => {
     if (!id)
         return null;
-    return reviewRepository.findById(id).catch(() => null);
+    return reviewRepository.findById(id);
 });

package/dist/_internal/server/features/shared/listing-data-factory.js

@@ -1,5 +1,6 @@
 import { cache } from "react";
 import { productRepository } from "../../../../repositories";
+import { safeRead } from "../../../../errors/safe-read";
 import { loadProductFeaturesForStore } from "../../../../features/products/repository/loadProductFeatures";
 // Returns a React.cache()-wrapped fetch gated on one listing type.
 // The guard prevents cross-type URL collisions (e.g. /auctions/classified-slug returning wrong product).
@@ -7,7 +8,7 @@ export function makeGetListingForDetail(type) {
     return cache(async (slugOrId) => {
         if (!slugOrId)
             return null;
-        const product = await productRepository.findByIdOrSlug(slugOrId).catch(() => undefined);
+        const product = await productRepository.findByIdOrSlug(slugOrId);
         if (!product || product.listingType !== type)
             return null;
         return product;
@@ -15,7 +16,11 @@ export function makeGetListingForDetail(type) {
 }
 // Product-feature badges are keyed by store, not listing type.
 // Per-type data.ts files re-export this under a type-specific name.
-export const getProductFeaturesForStore = cache(async (storeId) => loadProductFeaturesForStore(storeId).catch(() => []));
+export const getProductFeaturesForStore = cache(async (storeId) => safeRead(() => loadProductFeaturesForStore(storeId), {
+    route: "/products",
+    key: "products.getProductFeaturesForStore",
+    fallback: [],
+}));
 // Returns a React.cache()-wrapped function for store SSR first-page data.
 // Export names in stores/data.ts stay identical so consumers need no changes.
 export function makeGetStoreListingsInitial(type, pageSize) {

package/dist/_internal/server/features/stores/data.js

@@ -5,7 +5,7 @@ import { STORES_PRODUCTS_PAGE_SIZE, STORES_SITEMAP_LIMIT, } from "../../../share
 import { makeGetStoreListingsInitial } from "../shared/listing-data-factory";
 /** Full store document by slug — deduped per request via React.cache(). */
 export const getStoreForDetail = cache(async (slug) => {
-    return (await storeRepository.findBySlug(slug).catch(() => undefined)) ?? null;
+    return (await storeRepository.findBySlug(slug)) ?? null;
 });
 // Collapse of three near-identical 14-line functions via factory — export names unchanged.
 export const listStoreProductsInitial = makeGetStoreListingsInitial("standard", STORES_PRODUCTS_PAGE_SIZE);

package/dist/_internal/server/features/sublisting-categories/data.js

@@ -1,5 +1,5 @@
 import { cache } from "react";
 import { categoriesRepository } from "../../../../repositories";
 export const getSublistingCategoryForDetail = cache(async (slug) => {
-    return categoriesRepository.findBySlugAndType(slug, "sublisting").catch(() => null);
+    return categoriesRepository.findBySlugAndType(slug, "sublisting");
 });

package/dist/_internal/server/jobs/core/auctionSettlement.js

@@ -1,6 +1,7 @@
 import { bidRepository, cartRepository, productRepository, storeRepository, } from "../../../../repositories";
 import { sendNotification } from "../../../../features/admin/actions/notification-actions";
 import { normalizeError } from "../../../../errors/normalize";
+import { safeRead } from "../../../../errors/safe-read";
 import { AUCTION_MESSAGES, BID_MESSAGES } from "../handlers/messages";
 import { ROUTES } from "../../../../next/routing/route-map";
 import { CART_LANE, LANE_CHECKOUT_WINDOW_MS } from "../../../shared/checkout/lanes";
@@ -94,7 +95,11 @@ async function settleAuction(ctx, product) {
         productRepository.updateStatusInBatch(batch, product.id, "archived");
         await batch.commit();
         const reserveStore = product.storeId
-            ? await storeRepository.findById(product.storeId).catch(() => null)
+            ? await safeRead(() => storeRepository.findById(product.storeId), {
+                route: "job:auctionSettlement",
+                key: "auctionSettlement.reserveNotMet.store",
+                fallback: null,
+            })
             : null;
         if (reserveStore?.ownerId) {
             await sendNotification({

package/dist/_internal/server/jobs/core/onOrderStatusChange.js

@@ -1,5 +1,3 @@
-import { normalizeError } from "../../../../errors/normalize";
-import { getAdminRealtimeDb } from "../../../../providers/db-firebase";
 import { decryptPii } from "../../../../security/index";
 import { sendNotification } from "../../../../features/admin/actions/notification-actions";
 import { ORDER_MESSAGES } from "../handlers/messages";
@@ -58,19 +56,13 @@ export async function handleOrderStatusChange(input, ctx) {
             userEmail,
             orderWhatsappAddonPaid: after.whatsappNotifyAddon === true,
         });
-        try {
-            await getAdminRealtimeDb().ref(`notifications/${after.userId}`).push({
-                type: config.type,
-                title: config.title,
-                message: messageText,
-                timestamp: Date.now(),
-                read: false,
-            });
-        }
-        catch (rtdbError) {
-            void normalizeError(rtdbError);
-            ctx.logger.error("Realtime DB push failed (non-fatal)", rtdbError);
-        }
+        // The RTDB mirror that used to live here has been removed. `sendNotification`
+        // above is the real path (in-app + email + WhatsApp); the extra
+        // `notifications/{uid}` push was a duplicate that NOTHING read — no client
+        // subscription to that node has ever existed — and nothing pruned, so it
+        // accumulated one node per order transition per user forever. Its rule's
+        // `.type` validator also only allowed `info|success|warning|error`, none of
+        // which are the values written here (`order_confirmed`, `order_shipped`, …).
         ctx.logger.info(`Order ${orderId} status → ${newStatus}`, { userId: after.userId });
     }
     catch (error) {

package/dist/_internal/server/jobs/core/revenueRollup.js

@@ -12,7 +12,13 @@
 import { orderRepository } from "../../../../repositories";
 import { analyticsRollupRepository } from "../../../../repositories";
 export async function runRevenueRollup(ctx) {
-    const deliveredOrders = await orderRepository.findByStatus("delivered").catch(() => []);
+    // No `.catch(() => [])` here on purpose: an empty list is a legitimate
+    // outcome that writes `totalRevenue: 0`, so swallowing a query failure would
+    // overwrite yesterday's correct rollup with a confident zero that the
+    // dashboard has no way to distinguish from "no delivered orders". Let it
+    // throw — the job runner records the failure and the stale-but-correct
+    // singleton stays put.
+    const deliveredOrders = await orderRepository.findByStatus("delivered");
     const totalRevenue = deliveredOrders.reduce((sum, order) => sum + (Number(order.totalPrice ?? 0) || 0), 0);
     await analyticsRollupRepository.setDashboardRollup({
         totalRevenue,

package/dist/client/api/useApiQuery.js

@@ -4,7 +4,13 @@ import * as React from "react";
 import { useQuery, } from "@tanstack/react-query";
 import { useToast } from "../../ui/components/Toast";
 import { ApiError } from "./ApiError";
-import { getErrorDisplay } from "../../errors/error-display-map";
+import { toUserMessage } from "../../errors/error-display-map";
+/**
+ * Appended to the "stale data" warning. Authored copy, never derived from the
+ * failure — a background refetch that dies on a `MODULE_NOT_FOUND` must not
+ * print a require stack into a toast (audit-raw-error-text).
+ */
+const REFRESH_HINT = "Please check your connection and try again.";
 export function useApiQuery(options) {
     const { showToast } = useToast();
     const { silentBackgroundFailures, translate, reportClientError, ...rest } = options;
@@ -22,9 +28,10 @@ export function useApiQuery(options) {
             return;
         const err = result.error;
         if (err instanceof ApiError) {
-            const display = getErrorDisplay(err.code);
-            const message = translate?.(display.messageKey) ?? err.message;
-            showToast(`Couldn't refresh latest data: ${message}`, "warning");
+            const message = toUserMessage(err.code, translate, {
+                fallback: REFRESH_HINT,
+            });
+            showToast(`Couldn't refresh latest data. ${message}`, "warning");
             if (reportClientError) {
                 try {
                     reportClientError({
@@ -39,8 +46,12 @@ export function useApiQuery(options) {
             }
         }
         else {
-            const message = err instanceof Error ? err.message : "Unknown error";
-            showToast(`Couldn't refresh latest data: ${message}`, "warning");
+            // No stable code on a non-ApiError rejection, so there is nothing to
+            // resolve — go straight to the authored hint rather than the raw text.
+            const message = toUserMessage(undefined, translate, {
+                fallback: REFRESH_HINT,
+            });
+            showToast(`Couldn't refresh latest data. ${message}`, "warning");
         }
     }, [
         result.isError,

package/dist/client.d.ts

@@ -1,6 +1,7 @@
 export { HTTP_ERROR_CODES, mapToHttpError } from "./errors/error-mapping";
 export type { HttpErrorCode, MappedError } from "./errors/error-mapping";
 export { ERROR_DISPLAY_MAP, getErrorDisplay } from "./errors/error-display-map";
+export { toUserMessage, GENERIC_USER_MESSAGE } from "./errors/error-display-map";
 export type { ErrorDisplayEntry } from "./errors/error-display-map";
 export { RazorpayUnreachableError } from "./errors/razorpay-unreachable";
 export type { ActionResult } from "./utils/action-result";

package/dist/client.js

@@ -4,6 +4,9 @@
 // Used by useApiMutation / useApiQuery / Button surface-error to route ApiError → toast or inline field error.
 export { HTTP_ERROR_CODES, mapToHttpError } from "./errors/error-mapping";
 export { ERROR_DISPLAY_MAP, getErrorDisplay } from "./errors/error-display-map";
+// toUserMessage — the only sanctioned path from a failure to user-facing copy.
+// It terminates in a constant, so a thrown value's own .message never surfaces.
+export { toUserMessage, GENERIC_USER_MESSAGE } from "./errors/error-display-map";
 export { RazorpayUnreachableError } from "./errors/razorpay-unreachable";
 export { isOk, unwrap } from "./utils/action-result";
 // [CLIENT-SAFE] Client error class + surface-error router + reporter primitives.

package/dist/contracts/client-realtime.d.ts

@@ -13,6 +13,12 @@ export interface RealtimeSnapshot {
 /** Unsubscribe function returned by subscribe */
 export type Unsubscribe = () => void;
 export interface IClientRealtimeProvider {
+    /**
+     * A provider on its own Firebase app for this claim scope, so concurrent
+     * channels do not overwrite each other's auth. Optional: a provider that
+     * cannot isolate returns itself, keeping the old shared-app behaviour.
+     */
+    forScope?(scope: string): IClientRealtimeProvider;
     /** Authenticate the realtime connection with a custom token */
     signInWithToken(token: string): Promise<void>;
     /** Sign out of the realtime connection */

package/dist/contracts/realtime-session.d.ts

@@ -1,3 +1,4 @@
+import { type IClientRealtimeProvider } from "./client-realtime";
 export interface RealtimeToken {
     customToken: string;
     expiresAt: number;
@@ -12,16 +13,15 @@ export interface RealtimeToken {
  * @returns a release function. **Always call it** — the session is only torn
  *          down when every lease is released.
  */
-export declare function acquireRealtimeSession(scope: string, getToken: () => Promise<RealtimeToken>): Promise<() => void>;
-/**
- * Take a lease WITHOUT signing in — for a consumer that manages its own
- * sign-in but must still participate in the reference count.
- *
- * `useRealtimeEvent` is the case: its token carries a job-scoped `bulkJobId`
- * claim it receives from the caller, so it cannot use `acquireRealtimeSession`'s
- * fetcher. It still must not be able to sign the shared app out from under
- * another channel, which is precisely what its `cleanup()` used to do.
- */
-export declare function acquireExternalRealtimeLease(): () => void;
-/** Test/diagnostic only. */
+export interface RealtimeLease {
+    /**
+     * Subscribe through THIS provider, not the global one — it is bound to the
+     * app this scope signed in on. Using the global provider would read from an
+     * app with someone else's claims.
+     */
+    provider: IClientRealtimeProvider;
+    release: () => void;
+}
+export declare function acquireRealtimeSession(scope: string, getToken: () => Promise<RealtimeToken>): Promise<RealtimeLease>;
+/** Test/diagnostic only — total leases across every scope. */
 export declare function activeRealtimeLeases(): number;

package/dist/contracts/realtime-session.js

@@ -1,7 +1,11 @@
 import { normalizeError } from "../errors/normalize";
-import { getClientRealtimeProvider } from "./client-realtime";
+import { getClientRealtimeProvider, } from "./client-realtime";
 /**
- * Shared, REFERENCE-COUNTED sign-in for the one client realtime app.
+ * PER-SCOPE, reference-counted sign-in for the client realtime channels.
+ *
+ * Each claim scope gets its own Firebase app (via `provider.forScope`), because
+ * Firebase Auth state is per-app and two channels legitimately need two
+ * different claim sets at the same time.
  *
  * WHY THIS EXISTS — two distinct bugs, one cause.
  *
@@ -21,98 +25,89 @@ import { getClientRealtimeProvider } from "./client-realtime";
  *    bulk token (carrying `bulkJobId`), killing an in-flight job subscription.
  *    Whoever finished last broke whoever was still working.
  *
- * The fix for (2) is not "sign out more carefully" — it is that **no individual
- * consumer may decide to sign out at all**. Each acquires a lease and releases
- * it; the session ends only when the last lease is gone.
+ * (2) needed BOTH halves, and only one was done at first:
+ *   - sign-OUT: no consumer may decide to sign out. Each takes a lease; the
+ *     session ends only when the last lease for that scope is gone.
+ *   - sign-IN: ref-counting cannot help here, because nothing is being shared
+ *     by agreement — a bulk job and a message thread need different claims
+ *     simultaneously. The answer is separate apps, not coordination.
  *
- * Tokens differ per channel (different claims), so `acquire` takes a fetcher and
- * re-signs when the token it holds is for a different scope or has expired.
+ * 🛑 Subscribe through `lease.provider`, never `getClientRealtimeProvider()`.
+ * The global one is the root app; the lease's is the app your scope actually
+ * authenticated on.
  */
 /** Refresh a little early — a token that expires mid-subscription is a silent drop. */
 const EXPIRY_SKEW_MS = 60000;
-let leases = 0;
-let currentScope = null;
-let expiresAt = 0;
-let inFlight = null;
 /**
- * Ensure the shared realtime app is signed in for `scope`, and take a lease.
+ * One entry per claim scope, each on its OWN Firebase app.
  *
- * @param scope    an identifier for the claim set (e.g. `"messages"`,
- *                 `"chat:<id>"`). Signing in again for the SAME scope while a
- *                 valid token is held is a no-op.
- * @param getToken fetches a fresh custom token. Called only when needed.
- * @returns a release function. **Always call it** — the session is only torn
- *          down when every lease is released.
+ * 🛑 This used to be three module-level singletons — `currentScope`,
+ * `expiresAt`, `leases` — describing ONE shared app. That shape could not
+ * express the real situation: two channels legitimately need two different
+ * claim sets at the same time, and Firebase Auth state is per-app, so every
+ * sign-in replaced the previous one's claims. Ref-counting only stopped a
+ * finishing channel from signing the others OUT; it could not stop a starting
+ * channel from signing itself IN over them.
  */
+const scopes = new Map();
 export async function acquireRealtimeSession(scope, getToken) {
-    const lease = { scope };
-    leases++;
-    const needsSignIn = currentScope !== lease.scope || Date.now() > expiresAt - EXPIRY_SKEW_MS;
-    if (needsSignIn) {
-        // Collapse concurrent acquires — several hooks mount in the same tick and
-        // would otherwise each fetch a token and race to sign in.
-        inFlight ?? (inFlight = (async () => {
+    const root = getClientRealtimeProvider();
+    let state = scopes.get(scope);
+    if (!state) {
+        // `forScope` is optional on the contract: a provider that cannot isolate
+        // falls back to the shared app, which is the old behaviour rather than a
+        // crash.
+        state = {
+            leases: 0,
+            expiresAt: 0,
+            inFlight: null,
+            provider: root.forScope?.(scope) ?? root,
+        };
+        scopes.set(scope, state);
+    }
+    state.leases++;
+    if (Date.now() > state.expiresAt - EXPIRY_SKEW_MS) {
+        // Collapse concurrent acquires for the SAME scope — several hooks mount in
+        // one tick and would otherwise each fetch a token and race to sign in.
+        state.inFlight ?? (state.inFlight = (async () => {
             try {
                 const token = await getToken();
-                await getClientRealtimeProvider().signInWithToken(token.customToken);
-                currentScope = lease.scope;
-                expiresAt = token.expiresAt;
+                await state.provider.signInWithToken(token.customToken);
+                state.expiresAt = token.expiresAt;
             }
             finally {
-                inFlight = null;
+                state.inFlight = null;
             }
         })());
-        await inFlight;
+        await state.inFlight;
     }
     let released = false;
-    return () => {
-        if (released)
-            return; // React StrictMode double-invokes cleanups
-        released = true;
-        leases = Math.max(0, leases - 1);
-        if (leases > 0)
-            return;
-        currentScope = null;
-        expiresAt = 0;
-        getClientRealtimeProvider()
-            .signOut()
-            .catch((err) => {
-            void normalizeError(err);
-        });
-    };
-}
-/**
- * Take a lease WITHOUT signing in — for a consumer that manages its own
- * sign-in but must still participate in the reference count.
- *
- * `useRealtimeEvent` is the case: its token carries a job-scoped `bulkJobId`
- * claim it receives from the caller, so it cannot use `acquireRealtimeSession`'s
- * fetcher. It still must not be able to sign the shared app out from under
- * another channel, which is precisely what its `cleanup()` used to do.
- */
-export function acquireExternalRealtimeLease() {
-    leases++;
-    // Its own sign-in has replaced whatever scope was active; forget the cached
-    // one so the next acquire() re-authenticates rather than trusting a token
-    // that is no longer installed.
-    currentScope = null;
-    expiresAt = 0;
-    let released = false;
-    return () => {
-        if (released)
-            return;
-        released = true;
-        leases = Math.max(0, leases - 1);
-        if (leases > 0)
-            return;
-        getClientRealtimeProvider()
-            .signOut()
-            .catch((err) => {
-            void normalizeError(err);
-        });
+    return {
+        provider: state.provider,
+        release: () => {
+            if (released)
+                return; // React StrictMode double-invokes cleanups
+            released = true;
+            const cur = scopes.get(scope);
+            if (!cur)
+                return;
+            cur.leases = Math.max(0, cur.leases - 1);
+            if (cur.leases > 0)
+                return;
+            // Last holder of THIS scope. Signing out touches only this scope's app,
+            // so it cannot disturb any other channel.
+            cur.expiresAt = 0;
+            scopes.delete(scope);
+            cur.provider.signOut().catch((err) => {
+                void normalizeError(err);
+            });
+        },
     };
 }
-/** Test/diagnostic only. */
+/** Test/diagnostic only — total leases across every scope. */
 export function activeRealtimeLeases() {
-    return leases;
+    let total = 0;
+    for (const s of scopes.values())
+        total += s.leases;
+    return total;
 }

package/dist/errors/index.d.ts

@@ -12,7 +12,7 @@ export { DatabaseError } from "./database-error";
 export { RazorpayUnreachableError } from "./razorpay-unreachable";
 export { handleApiError, logError, isAppError } from "./error-handler";
 export { mapToHttpError, HTTP_ERROR_CODES, type MappedError, type HttpErrorCode, } from "./error-mapping";
-export { ERROR_DISPLAY_MAP, getErrorDisplay, type ErrorDisplayEntry, } from "./error-display-map";
+export { ERROR_DISPLAY_MAP, getErrorDisplay, toUserMessage, GENERIC_USER_MESSAGE, type ErrorDisplayEntry, } from "./error-display-map";
 export { safeRead, installDegradedReadReporter, type DegradedReadReport, } from "./safe-read";
 export { normalizeError, getErrorMessage, isAuthError, isApiNormalized, isAppNormalized, isFirebaseAuthNormalized, isFirebaseFirestoreNormalized, isFirebaseStorageNormalized, isNativeNormalized, isNetworkNormalized, isUnknownNormalized, isZodNormalized, } from "./normalize";
 export type { NormalizedError, NormalizedApiError, NormalizedAppError, NormalizedFirebaseAuthError, NormalizedFirebaseFirestoreError, NormalizedFirebaseStorageError, NormalizedNativeError, NormalizedNetworkError, NormalizedUnknownThrownValue, NormalizedZodError, } from "./normalize";

package/dist/errors/index.js

@@ -17,7 +17,7 @@ export { RazorpayUnreachableError } from "./razorpay-unreachable";
 export { handleApiError, logError, isAppError } from "./error-handler";
 // Code→HTTP mapper (server) — and the i18n / inline-field map (client-safe)
 export { mapToHttpError, HTTP_ERROR_CODES, } from "./error-mapping";
-export { ERROR_DISPLAY_MAP, getErrorDisplay, } from "./error-display-map";
+export { ERROR_DISPLAY_MAP, getErrorDisplay, toUserMessage, GENERIC_USER_MESSAGE, } from "./error-display-map";
 // safeRead is server-only (uses the persisted log reporter)
 export { safeRead, installDegradedReadReporter, } from "./safe-read";
 // W3 — catch-clause normalizer. Every catch (e: unknown) funnels through