@mohasinac/appkit 4.62.0 → 4.63.0

package/dist/next/routing/route-map.d.ts

@@ -21,6 +21,8 @@ export declare const DEFAULT_ROUTE_MAP: {
         readonly AUCTIONS: "/auctions";
         readonly AUCTION_DETAIL: (id: string) => string;
         readonly PRE_ORDERS: "/pre-orders";
+        /** D56 — the public rate card + self-serve booking form. */
+        readonly ADVERTISE: "/advertise";
         readonly PRE_ORDER_DETAIL: (id: string) => string;
         readonly BUNDLES: "/bundles";
         readonly BUNDLE_DETAIL: (slug: string) => string;
@@ -157,6 +159,16 @@ export declare const DEFAULT_ROUTE_MAP: {
     };
     readonly USER: {
         readonly DASHBOARD: "/user";
+        /**
+         * A dashboard SECTION hub — the screens of one sidebar group, each with a
+         * sentence on what it is for.
+         *
+         * One parametric route serves every section of the portal; the slug is
+         * `hubSectionSlug(group.title)` and is DERIVED, so there is no list of
+         * section keys here to drift from the nav. `audit-dashboard-hub-coverage`
+         * cross-checks the two.
+         */
+        readonly SECTION: (slug: string) => string;
         readonly PROFILE: "/user/profile";
         readonly SETTINGS: "/user/settings";
         readonly ORDERS: "/user/orders";
@@ -177,6 +189,17 @@ export declare const DEFAULT_ROUTE_MAP: {
         readonly ORDER_CLAIM: (id: string) => string;
         readonly ORDER_INVOICE: (id: string) => string;
         readonly ORDER_PAYMENT: (id: string) => string;
+        /**
+         * Raise a dispute on one order.
+         *
+         * Deep-linkable on purpose: a notification `actionUrl` points here, and
+         * `/user/orders/view/{id}` carries a "Report a problem" button to the same
+         * place. One surface, two ways in — an email link that works only while
+         * the buyer still has the email is the shape Root Cause #57 records,
+         * where `ORDER_PAYMENT` had exactly ONE caller and a buyer who navigated
+         * away could not get back.
+         */
+        readonly ORDER_DISPUTE: (id: string) => string;
         readonly NOTIFICATIONS: "/user/notifications";
         /** Plan §10 — claimed-coupons wallet (Active / Expired / Used tabs). */
         readonly CLAIMED_COUPONS: "/user/coupons";
@@ -198,6 +221,8 @@ export declare const DEFAULT_ROUTE_MAP: {
         readonly SUPPORT_NEW: "/user/support/new";
         readonly SUPPORT_TICKET: (id: string) => string;
         readonly PRE_ORDERS: "/user/pre-orders";
+        /** D56 — the advertiser's own bookings and their moderation state. */
+        readonly AD_BOOKINGS: "/user/ad-bookings";
         readonly DIGITAL_CODES: "/user/digital-codes";
         readonly PRIZE_DRAWS: "/user/prize-draws";
         readonly EVENTS: "/user/events";
@@ -210,6 +235,8 @@ export declare const DEFAULT_ROUTE_MAP: {
     };
     readonly STORE: {
         readonly DASHBOARD: "/store";
+        /** A dashboard SECTION hub — see `USER.SECTION` for the derivation. */
+        readonly SECTION: (slug: string) => string;
         readonly PRODUCTS: "/store/products";
         readonly PRODUCTS_NEW: "/store/products/new";
         readonly PRODUCTS_EDIT: (id: string) => string;
@@ -300,6 +327,18 @@ export declare const DEFAULT_ROUTE_MAP: {
     };
     readonly ADMIN: {
         readonly DASHBOARD: "/admin/dashboard";
+        /**
+         * The sectioned landing at `/admin` — what used to `redirect()` to
+         * `DASHBOARD`.
+         *
+         * 🛑 `DASHBOARD` is `/admin/dashboard` and stays a separate page: it is the
+         * metrics screen, and the sidebar's "Dashboard" entry points at it. This
+         * key is the index that lists the twelve sections. Collapsing the two would
+         * either bury the metrics or make the index unreachable.
+         */
+        readonly HOME: "/admin";
+        /** A dashboard SECTION hub — see `USER.SECTION` for the derivation. */
+        readonly SECTION: (slug: string) => string;
         readonly SHIPMENTS: "/admin/shipments";
         readonly INVENTORY_BOXES: "/admin/inventory/boxes";
         readonly INVENTORY_BOX_DETAIL: (id: string) => string;
@@ -315,6 +354,7 @@ export declare const DEFAULT_ROUTE_MAP: {
         readonly USER_DETAIL: (id: string) => string;
         readonly USER_EDIT: (id: string) => string;
         readonly SITE: "/admin/site";
+        readonly INTEGRATIONS: "/admin/integrations";
         readonly CAROUSEL: "/admin/carousel";
         readonly CAROUSEL_NEW: "/admin/carousel/new";
         readonly CAROUSEL_EDIT: (id: string) => string;
@@ -374,9 +414,20 @@ export declare const DEFAULT_ROUTE_MAP: {
         readonly ANALYTICS: "/admin/analytics";
         readonly PAYOUTS: "/admin/payouts";
         readonly PAYOUT_DETAIL: (id: string) => string;
+        readonly PRICING: "/admin/pricing";
         readonly AUDIT_LOG: "/admin/audit-log";
         readonly MONEY_CASES: "/admin/money-cases";
         readonly MONEY_CASE_DETAIL: (id: string) => string;
+        /**
+         * Phase 7 — the GSTR-1 draft export.
+         *
+         * 🛑 Under Finance for the same reason `MONEY_CASES` is, and the reason is
+         * stronger here: the export contains the company's tax position for a
+         * quarter plus every buyer's place of supply. That is not a maintenance
+         * diagnostic, and it is admin-only — deliberately not granted to
+         * `maintenance_employee`.
+         */
+        readonly INVOICING: "/admin/invoicing";
         readonly PROTECTION_CLAIMS: "/admin/protection-claims";
         readonly MAINTENANCE_GATEWAY_EVENTS: "/admin/maintenance/gateway-events";
         readonly MAINTENANCE_OBLIGATIONS: "/admin/maintenance/obligations";
@@ -389,6 +440,8 @@ export declare const DEFAULT_ROUTE_MAP: {
         readonly ADS: "/admin/ads";
         readonly ADS_NEW: "/admin/ads/new";
         readonly ADS_EDIT: (id: string) => string;
+        /** D56 — the self-serve creative moderation queue. */
+        readonly AD_BOOKINGS: "/admin/ads/bookings";
         readonly NEWSLETTER: "/admin/newsletter";
         readonly CONTACT: "/admin/contact";
         readonly SESSIONS: "/admin/sessions";
@@ -423,6 +476,8 @@ export declare const DEFAULT_ROUTE_MAP: {
         readonly TEAM_NEW: "/admin/team/new";
         readonly TEAM_EDIT: (id: string) => string;
         readonly SUPPORT_TICKETS: "/admin/support-tickets";
+        /** Staff curation of the reasons a buyer can pick when disputing. */
+        readonly DISPUTE_REASONS: "/admin/dispute-reasons";
         readonly SUPPORT_TICKET_BY_ID: (id: string) => string;
         readonly SCAMMERS: "/admin/scammers";
         readonly SCAMMER_BY_ID: (id: string) => string;
@@ -475,6 +530,8 @@ export declare const ROUTES: {
         readonly AUCTIONS: "/auctions";
         readonly AUCTION_DETAIL: (id: string) => string;
         readonly PRE_ORDERS: "/pre-orders";
+        /** D56 — the public rate card + self-serve booking form. */
+        readonly ADVERTISE: "/advertise";
         readonly PRE_ORDER_DETAIL: (id: string) => string;
         readonly BUNDLES: "/bundles";
         readonly BUNDLE_DETAIL: (slug: string) => string;
@@ -611,6 +668,16 @@ export declare const ROUTES: {
     };
     readonly USER: {
         readonly DASHBOARD: "/user";
+        /**
+         * A dashboard SECTION hub — the screens of one sidebar group, each with a
+         * sentence on what it is for.
+         *
+         * One parametric route serves every section of the portal; the slug is
+         * `hubSectionSlug(group.title)` and is DERIVED, so there is no list of
+         * section keys here to drift from the nav. `audit-dashboard-hub-coverage`
+         * cross-checks the two.
+         */
+        readonly SECTION: (slug: string) => string;
         readonly PROFILE: "/user/profile";
         readonly SETTINGS: "/user/settings";
         readonly ORDERS: "/user/orders";
@@ -631,6 +698,17 @@ export declare const ROUTES: {
         readonly ORDER_CLAIM: (id: string) => string;
         readonly ORDER_INVOICE: (id: string) => string;
         readonly ORDER_PAYMENT: (id: string) => string;
+        /**
+         * Raise a dispute on one order.
+         *
+         * Deep-linkable on purpose: a notification `actionUrl` points here, and
+         * `/user/orders/view/{id}` carries a "Report a problem" button to the same
+         * place. One surface, two ways in — an email link that works only while
+         * the buyer still has the email is the shape Root Cause #57 records,
+         * where `ORDER_PAYMENT` had exactly ONE caller and a buyer who navigated
+         * away could not get back.
+         */
+        readonly ORDER_DISPUTE: (id: string) => string;
         readonly NOTIFICATIONS: "/user/notifications";
         /** Plan §10 — claimed-coupons wallet (Active / Expired / Used tabs). */
         readonly CLAIMED_COUPONS: "/user/coupons";
@@ -652,6 +730,8 @@ export declare const ROUTES: {
         readonly SUPPORT_NEW: "/user/support/new";
         readonly SUPPORT_TICKET: (id: string) => string;
         readonly PRE_ORDERS: "/user/pre-orders";
+        /** D56 — the advertiser's own bookings and their moderation state. */
+        readonly AD_BOOKINGS: "/user/ad-bookings";
         readonly DIGITAL_CODES: "/user/digital-codes";
         readonly PRIZE_DRAWS: "/user/prize-draws";
         readonly EVENTS: "/user/events";
@@ -664,6 +744,8 @@ export declare const ROUTES: {
     };
     readonly STORE: {
         readonly DASHBOARD: "/store";
+        /** A dashboard SECTION hub — see `USER.SECTION` for the derivation. */
+        readonly SECTION: (slug: string) => string;
         readonly PRODUCTS: "/store/products";
         readonly PRODUCTS_NEW: "/store/products/new";
         readonly PRODUCTS_EDIT: (id: string) => string;
@@ -754,6 +836,18 @@ export declare const ROUTES: {
     };
     readonly ADMIN: {
         readonly DASHBOARD: "/admin/dashboard";
+        /**
+         * The sectioned landing at `/admin` — what used to `redirect()` to
+         * `DASHBOARD`.
+         *
+         * 🛑 `DASHBOARD` is `/admin/dashboard` and stays a separate page: it is the
+         * metrics screen, and the sidebar's "Dashboard" entry points at it. This
+         * key is the index that lists the twelve sections. Collapsing the two would
+         * either bury the metrics or make the index unreachable.
+         */
+        readonly HOME: "/admin";
+        /** A dashboard SECTION hub — see `USER.SECTION` for the derivation. */
+        readonly SECTION: (slug: string) => string;
         readonly SHIPMENTS: "/admin/shipments";
         readonly INVENTORY_BOXES: "/admin/inventory/boxes";
         readonly INVENTORY_BOX_DETAIL: (id: string) => string;
@@ -769,6 +863,7 @@ export declare const ROUTES: {
         readonly USER_DETAIL: (id: string) => string;
         readonly USER_EDIT: (id: string) => string;
         readonly SITE: "/admin/site";
+        readonly INTEGRATIONS: "/admin/integrations";
         readonly CAROUSEL: "/admin/carousel";
         readonly CAROUSEL_NEW: "/admin/carousel/new";
         readonly CAROUSEL_EDIT: (id: string) => string;
@@ -828,9 +923,20 @@ export declare const ROUTES: {
         readonly ANALYTICS: "/admin/analytics";
         readonly PAYOUTS: "/admin/payouts";
         readonly PAYOUT_DETAIL: (id: string) => string;
+        readonly PRICING: "/admin/pricing";
         readonly AUDIT_LOG: "/admin/audit-log";
         readonly MONEY_CASES: "/admin/money-cases";
         readonly MONEY_CASE_DETAIL: (id: string) => string;
+        /**
+         * Phase 7 — the GSTR-1 draft export.
+         *
+         * 🛑 Under Finance for the same reason `MONEY_CASES` is, and the reason is
+         * stronger here: the export contains the company's tax position for a
+         * quarter plus every buyer's place of supply. That is not a maintenance
+         * diagnostic, and it is admin-only — deliberately not granted to
+         * `maintenance_employee`.
+         */
+        readonly INVOICING: "/admin/invoicing";
         readonly PROTECTION_CLAIMS: "/admin/protection-claims";
         readonly MAINTENANCE_GATEWAY_EVENTS: "/admin/maintenance/gateway-events";
         readonly MAINTENANCE_OBLIGATIONS: "/admin/maintenance/obligations";
@@ -843,6 +949,8 @@ export declare const ROUTES: {
         readonly ADS: "/admin/ads";
         readonly ADS_NEW: "/admin/ads/new";
         readonly ADS_EDIT: (id: string) => string;
+        /** D56 — the self-serve creative moderation queue. */
+        readonly AD_BOOKINGS: "/admin/ads/bookings";
         readonly NEWSLETTER: "/admin/newsletter";
         readonly CONTACT: "/admin/contact";
         readonly SESSIONS: "/admin/sessions";
@@ -877,6 +985,8 @@ export declare const ROUTES: {
         readonly TEAM_NEW: "/admin/team/new";
         readonly TEAM_EDIT: (id: string) => string;
         readonly SUPPORT_TICKETS: "/admin/support-tickets";
+        /** Staff curation of the reasons a buyer can pick when disputing. */
+        readonly DISPUTE_REASONS: "/admin/dispute-reasons";
         readonly SUPPORT_TICKET_BY_ID: (id: string) => string;
         readonly SCAMMERS: "/admin/scammers";
         readonly SCAMMER_BY_ID: (id: string) => string;
@@ -920,6 +1030,8 @@ export declare const ROUTES: {
 /** @deprecated Use ROUTES.STORE instead */
 export declare const SELLER_ROUTES: {
     readonly DASHBOARD: "/store";
+    /** A dashboard SECTION hub — see `USER.SECTION` for the derivation. */
+    readonly SECTION: (slug: string) => string;
     readonly PRODUCTS: "/store/products";
     readonly PRODUCTS_NEW: "/store/products/new";
     readonly PRODUCTS_EDIT: (id: string) => string;

package/dist/next/routing/route-map.js

@@ -9,6 +9,8 @@ export const DEFAULT_ROUTE_MAP = {
         AUCTIONS: "/auctions",
         AUCTION_DETAIL: (id) => `/auctions/${id}`,
         PRE_ORDERS: "/pre-orders",
+        /** D56 — the public rate card + self-serve booking form. */
+        ADVERTISE: "/advertise",
         PRE_ORDER_DETAIL: (id) => `/pre-orders/${id}`,
         // SB1-J — bundles + prize draws (additive, pages not yet built)
         BUNDLES: "/bundles",
@@ -261,6 +263,16 @@ export const DEFAULT_ROUTE_MAP = {
     },
     USER: {
         DASHBOARD: "/user",
+        /**
+         * A dashboard SECTION hub — the screens of one sidebar group, each with a
+         * sentence on what it is for.
+         *
+         * One parametric route serves every section of the portal; the slug is
+         * `hubSectionSlug(group.title)` and is DERIVED, so there is no list of
+         * section keys here to drift from the nav. `audit-dashboard-hub-coverage`
+         * cross-checks the two.
+         */
+        SECTION: (slug) => `/user/sections/${slug}`,
         PROFILE: "/user/profile",
         SETTINGS: "/user/settings",
         ORDERS: "/user/orders",
@@ -297,6 +309,17 @@ export const DEFAULT_ROUTE_MAP = {
         ORDER_CLAIM: (id) => `/user/orders/${id}/claim`,
         ORDER_INVOICE: (id) => `/user/orders/${id}/invoice`,
         ORDER_PAYMENT: (id) => `/user/orders/${id}/payment`,
+        /**
+         * Raise a dispute on one order.
+         *
+         * Deep-linkable on purpose: a notification `actionUrl` points here, and
+         * `/user/orders/view/{id}` carries a "Report a problem" button to the same
+         * place. One surface, two ways in — an email link that works only while
+         * the buyer still has the email is the shape Root Cause #57 records,
+         * where `ORDER_PAYMENT` had exactly ONE caller and a buyer who navigated
+         * away could not get back.
+         */
+        ORDER_DISPUTE: (id) => `/user/orders/${id}/dispute`,
         NOTIFICATIONS: "/user/notifications",
         /** Plan §10 — claimed-coupons wallet (Active / Expired / Used tabs). */
         CLAIMED_COUPONS: "/user/coupons",
@@ -333,6 +356,8 @@ export const DEFAULT_ROUTE_MAP = {
         SUPPORT_NEW: "/user/support/new",
         SUPPORT_TICKET: (id) => `/user/support/${id}`,
         PRE_ORDERS: "/user/pre-orders",
+        /** D56 — the advertiser's own bookings and their moderation state. */
+        AD_BOOKINGS: "/user/ad-bookings",
         DIGITAL_CODES: "/user/digital-codes",
         PRIZE_DRAWS: "/user/prize-draws",
         EVENTS: "/user/events",
@@ -345,6 +370,8 @@ export const DEFAULT_ROUTE_MAP = {
     },
     STORE: {
         DASHBOARD: "/store",
+        /** A dashboard SECTION hub — see `USER.SECTION` for the derivation. */
+        SECTION: (slug) => `/store/sections/${slug}`,
         PRODUCTS: "/store/products",
         PRODUCTS_NEW: "/store/products/new",
         PRODUCTS_EDIT: (id) => `/store/products/${id}/edit`,
@@ -441,6 +468,18 @@ export const DEFAULT_ROUTE_MAP = {
     },
     ADMIN: {
         DASHBOARD: "/admin/dashboard",
+        /**
+         * The sectioned landing at `/admin` — what used to `redirect()` to
+         * `DASHBOARD`.
+         *
+         * 🛑 `DASHBOARD` is `/admin/dashboard` and stays a separate page: it is the
+         * metrics screen, and the sidebar's "Dashboard" entry points at it. This
+         * key is the index that lists the twelve sections. Collapsing the two would
+         * either bury the metrics or make the index unreachable.
+         */
+        HOME: "/admin",
+        /** A dashboard SECTION hub — see `USER.SECTION` for the derivation. */
+        SECTION: (slug) => `/admin/sections/${slug}`,
         SHIPMENTS: "/admin/shipments",
         /*
          * 🛑 There is deliberately NO `INVENTORY: "/admin/inventory"` key.
@@ -476,6 +515,15 @@ export const DEFAULT_ROUTE_MAP = {
         USER_DETAIL: (id) => `/admin/users/${id}`,
         USER_EDIT: (id) => `/admin/users/${id}/edit`,
         SITE: "/admin/site",
+        /*
+         * The integration kill switches — its OWN page, not a Site Settings tab.
+         *
+         * A switch that stops money has to be findable without hunting a tab
+         * strip, and this is the one surface where all four are visible together
+         * (which matters, because their off-states are not comparable: three stop
+         * something and one selects a working alternative).
+         */
+        INTEGRATIONS: "/admin/integrations",
         CAROUSEL: "/admin/carousel",
         CAROUSEL_NEW: "/admin/carousel/new",
         CAROUSEL_EDIT: (id) => `/admin/carousel/${id}/edit`,
@@ -563,6 +611,7 @@ export const DEFAULT_ROUTE_MAP = {
         ANALYTICS: "/admin/analytics",
         PAYOUTS: "/admin/payouts",
         PAYOUT_DETAIL: (id) => `/admin/payouts/${id}/view`,
+        PRICING: "/admin/pricing",
         AUDIT_LOG: "/admin/audit-log",
         /*
          * 🛑 MONEY_CASES is deliberately NOT under `/admin/maintenance/`.
@@ -579,6 +628,16 @@ export const DEFAULT_ROUTE_MAP = {
          */
         MONEY_CASES: "/admin/money-cases",
         MONEY_CASE_DETAIL: (id) => `/admin/money-cases/${id}`,
+        /**
+         * Phase 7 — the GSTR-1 draft export.
+         *
+         * 🛑 Under Finance for the same reason `MONEY_CASES` is, and the reason is
+         * stronger here: the export contains the company's tax position for a
+         * quarter plus every buyer's place of supply. That is not a maintenance
+         * diagnostic, and it is admin-only — deliberately not granted to
+         * `maintenance_employee`.
+         */
+        INVOICING: "/admin/invoicing",
         PROTECTION_CLAIMS: "/admin/protection-claims",
         MAINTENANCE_GATEWAY_EVENTS: "/admin/maintenance/gateway-events",
         MAINTENANCE_OBLIGATIONS: "/admin/maintenance/obligations",
@@ -591,6 +650,8 @@ export const DEFAULT_ROUTE_MAP = {
         ADS: "/admin/ads",
         ADS_NEW: "/admin/ads/new",
         ADS_EDIT: (id) => `/admin/ads/${id}/edit`,
+        /** D56 — the self-serve creative moderation queue. */
+        AD_BOOKINGS: "/admin/ads/bookings",
         NEWSLETTER: "/admin/newsletter",
         CONTACT: "/admin/contact",
         SESSIONS: "/admin/sessions",
@@ -634,6 +695,8 @@ export const DEFAULT_ROUTE_MAP = {
         TEAM_NEW: "/admin/team/new",
         TEAM_EDIT: (id) => `/admin/team/${id}/edit`,
         SUPPORT_TICKETS: "/admin/support-tickets",
+        /** Staff curation of the reasons a buyer can pick when disputing. */
+        DISPUTE_REASONS: "/admin/dispute-reasons",
         SUPPORT_TICKET_BY_ID: (id) => `/admin/support-tickets/${id}`,
         SCAMMERS: "/admin/scammers",
         SCAMMER_BY_ID: (id) => `/admin/scammers/${id}`,

package/dist/providers/shipping-shiprocket/index.d.ts

@@ -66,7 +66,7 @@
  * @tag access:server-only
  */
 import { IShippingProvider } from "../../contracts";
-import type { CreateShipmentInput, Shipment, TrackingInfo, ServiceabilityResult } from "../../contracts";
+import type { CreateShipmentInput, Shipment, TrackingInfo, ServiceabilityResult, WalletBalance } from "../../contracts";
 export interface ShiprocketConfig {
     /** The API user's email. See the header on why this is not a "login id". */
     email: string;
@@ -74,6 +74,21 @@ export interface ShiprocketConfig {
     /** Shiprocket pickup-location nickname, as registered in their dashboard. */
     pickupLocation?: string;
 }
+/**
+ * Does this upstream error body look like "your wallet is empty"?
+ *
+ * 🛑 The substring list is UNVERIFIED and that is acceptable, because of where
+ * it sits in the design: a funding failure and any other booking failure take
+ * the SAME path — the order gets a `courierBlock`, the admin is alerted, the
+ * seller is offered retry-or-self-ship. Classifying only changes the WORDING
+ * of the operator's alert. So a false negative costs a less specific message
+ * and never a wrong action, which is why this is allowed to be a heuristic
+ * rather than something this plan pretended to have confirmed.
+ *
+ * Triggering the real error would mean deliberately booking a shipment against
+ * a drained wallet, which is not a probe anyone should run on a live account.
+ */
+export declare function looksLikeInsufficientFunds(body: string): boolean;
 export declare class ShiprocketShippingProvider extends IShippingProvider {
     private readonly config;
     readonly name = "shiprocket";
@@ -119,6 +134,17 @@ export declare class ShiprocketShippingProvider extends IShippingProvider {
      */
     createShipment(data: CreateShipmentInput): Promise<Shipment>;
     trackShipment(trackingId: string): Promise<TrackingInfo>;
+    /**
+     * The prepaid wallet balance. Read-only; never charges anything.
+     *
+     * 🛑 Returns `{ known: false, supported: true }` on ANY failure rather than
+     * `0`. Shiprocket HAS a wallet, so `supported` is true regardless — the
+     * caller must treat "unreadable" as "attempt the booking anyway and let the
+     * attempt's own failure decide", because refusing on an unreadable balance
+     * would block every order on a transient network blip. A `0` here is a real
+     * decision to skip; an unreadable balance is not.
+     */
+    getWalletBalance(): Promise<WalletBalance>;
     cancelShipment(shipmentId: string): Promise<void>;
     checkServiceability(pincode: string, weight: number): Promise<ServiceabilityResult>;
     generateLabel(shipmentId: string): Promise<ArrayBuffer>;

package/dist/providers/shipping-shiprocket/index.js

@@ -117,6 +117,42 @@ const serviceabilityResponse = z.object({
             .nullish(),
     }),
 });
+/*
+ * Measured against the live API 2026-10-22 (read-only probe, one auth + GETs):
+ *
+ *   GET /account/details/wallet-balance -> 200 { data: { balance_amount: string } }
+ *   GET /account/details                -> 404
+ *
+ * 🛑 `balance_amount` is a STRING, and there is NO credit-limit field — so
+ * postpaid headroom is not readable from this API at all. See `WalletBalance`
+ * in contracts/shipping.ts for why no such field is declared.
+ */
+const walletBalanceResponse = z.object({
+    data: z.object({
+        balance_amount: z.union([z.number(), z.string()]).nullish(),
+    }),
+});
+/**
+ * Does this upstream error body look like "your wallet is empty"?
+ *
+ * 🛑 The substring list is UNVERIFIED and that is acceptable, because of where
+ * it sits in the design: a funding failure and any other booking failure take
+ * the SAME path — the order gets a `courierBlock`, the admin is alerted, the
+ * seller is offered retry-or-self-ship. Classifying only changes the WORDING
+ * of the operator's alert. So a false negative costs a less specific message
+ * and never a wrong action, which is why this is allowed to be a heuristic
+ * rather than something this plan pretended to have confirmed.
+ *
+ * Triggering the real error would mean deliberately booking a shipment against
+ * a drained wallet, which is not a probe anyone should run on a live account.
+ */
+export function looksLikeInsufficientFunds(body) {
+    const s = body.toLowerCase();
+    return (s.includes("insufficient") ||
+        s.includes("low balance") ||
+        s.includes("recharge") ||
+        (s.includes("wallet") && s.includes("balance")));
+}
 function num(v, fallback = 0) {
     const n = typeof v === "string" ? Number.parseFloat(v) : v;
     return typeof n === "number" && Number.isFinite(n) ? n : fallback;
@@ -230,7 +266,24 @@ export class ShiprocketShippingProvider extends IShippingProvider {
             res = await attempt(true);
         }
         if (!res.ok) {
-            throw new ApiError(502, `Shiprocket ${path} failed (${res.status}).`, { code: "SHIPROCKET_REQUEST_FAILED" });
+            /*
+             * The body is read and carried, not discarded.
+             *
+             * It used to throw on `res.status` alone, which meant a funding failure
+             * and a malformed-address failure were indistinguishable to every
+             * caller — and the first of those is the one an operator can actually
+             * fix, by topping up.
+             *
+             * Truncated, because an upstream error page can be a whole HTML
+             * document and this string ends up in a log line.
+             */
+            const body = await res.text().catch(() => "");
+            const insufficient = looksLikeInsufficientFunds(body);
+            throw new ApiError(502, `Shiprocket ${path} failed (${res.status}).`, {
+                code: insufficient ? "SHIPROCKET_INSUFFICIENT_FUNDS" : "SHIPROCKET_REQUEST_FAILED",
+                upstreamStatus: res.status,
+                upstreamBody: body.slice(0, 500),
+            });
         }
         const json = await res.json();
         return parseUpstream(contract, json, path);
@@ -331,6 +384,36 @@ export class ShiprocketShippingProvider extends IShippingProvider {
             })),
         };
     }
+    /**
+     * The prepaid wallet balance. Read-only; never charges anything.
+     *
+     * 🛑 Returns `{ known: false, supported: true }` on ANY failure rather than
+     * `0`. Shiprocket HAS a wallet, so `supported` is true regardless — the
+     * caller must treat "unreadable" as "attempt the booking anyway and let the
+     * attempt's own failure decide", because refusing on an unreadable balance
+     * would block every order on a transient network blip. A `0` here is a real
+     * decision to skip; an unreadable balance is not.
+     */
+    async getWalletBalance() {
+        try {
+            const out = await this.call("/account/details/wallet-balance", { method: "GET" }, walletBalanceResponse);
+            const raw = out.data.balance_amount;
+            /*
+             * `num()` would silently fold an unparseable string into its fallback,
+             * which is exactly the 0-means-unknown conflation this type exists to
+             * prevent. Parsed explicitly so a bad payload reports `known: false`.
+             */
+            const parsed = typeof raw === "string" ? Number.parseFloat(raw) : raw;
+            if (typeof parsed !== "number" || !Number.isFinite(parsed)) {
+                return { known: false, supported: true, reason: "unparseable balance_amount" };
+            }
+            return { known: true, amount: parsed, currency: "INR" };
+        }
+        catch (err) {
+            const normalized = normalizeError(err);
+            return { known: false, supported: true, reason: normalized.message };
+        }
+    }
     async cancelShipment(shipmentId) {
         await this.call("/orders/cancel", { method: "POST", body: JSON.stringify({ ids: [shipmentId] }) }, 
         // Their cancel returns a message envelope we do not read; accepting any

package/dist/react/contexts/SessionContext.d.ts

@@ -40,7 +40,23 @@ export interface SessionUser {
     /** Orthogonal to isTester — unlocks admin-only checklist items and real /admin/** RBAC access. */
     canTestAdmin?: boolean;
     publicProfile?: FirestoreDocument;
-    stats?: FirestoreDocument;
+    /**
+     * Buyer activity counts, DERIVED by `/api/user/profile` — orders placed,
+     * auctions won, reviews written. Each is optional and `undefined` means the
+     * count could not be taken, which is NOT the same as zero: render nothing.
+     *
+     * 🛑 Not the `users/{uid}.stats` document field, which has no writer at all
+     * and holds seed literals. Do not "restore" it by reading the profile
+     * document here; see `getBuyerActivityStats`.
+     *
+     * Seller numbers are deliberately absent. This is the account holder's own
+     * record; what their store has sold belongs to the store.
+     */
+    stats?: {
+        totalOrders?: number;
+        auctionsWon?: number;
+        reviewsCount?: number;
+    };
     metadata?: FirestoreDocument;
     scamAwarenessAcknowledgedAt?: Date | null;
     /** RBAC permission keys granted to this user (from their role's permission set). */