@mohasinac/appkit 4.42.1 → 4.42.2

package/dist/_internal/server/features/offers/adapters.d.ts

@@ -81,15 +81,37 @@ export interface Offer {
 }
 export interface OfferAdapterOptions {
     /**
-     * Include `buyerUid`/`buyerName`/`buyerEmail`.
+     * What to do with `buyerUid`/`buyerName`/`buyerEmail`.
      *
-     * Default **false**, deliberately. The seller-facing route masks buyer
-     * identity, and a route that forgot to call `maskOfferForSeller` would
-     * previously have shipped it verbatim — there was no adapter to stop it.
-     * Making the omission the default means forgetting the flag under-shares
-     * rather than leaks.
+     * | value | emits |
+     * |---|---|
+     * | `"omit"` (default) | nothing — the three keys are absent |
+     * | `"masked"` | `buyerName` `"M*** U***"`, `buyerEmail` `"m***@***.in"`, no uid |
+     * | `"full"` | verbatim |
+     *
+     * 🛑 **This replaced a boolean, because the boolean had no way to say
+     * "masked" and the seller route needed exactly that.** It worked around the
+     * gap by calling `maskOfferForSeller(o)` and then adapting with the flag
+     * OFF — so the mask ran, produced a masked name, and the adapter deleted it
+     * on the very next line. Every one of the 13 rows on `/store/offers` read
+     * **"Unknown buyer"**, measured live as tyson@beybladearena.in, and so did
+     * the detail modal.
+     *
+     * That is worse than cosmetic: a seller could not tell two offers on the same
+     * listing apart, which is the one thing they need when two people are bidding
+     * up the same item. It also silently disagreed with the sibling server action
+     * `listSellerOffers`, which masks and returns the name — two seller read
+     * paths, two answers (Root Cause #38), and a mask whose output was discarded
+     * (Root Cause #50).
+     *
+     * Masking now happens INSIDE the adapter, so a caller cannot apply one half.
+     * `"masked"` deliberately omits `buyerUid` as well: a uid is not a display
+     * value and there is nothing to partially reveal about it.
+     *
+     * The default stays the safe one — a caller that says nothing under-shares
+     * rather than leaks, which is why the old boolean defaulted false too.
      */
-    includeBuyerIdentity?: boolean;
+    buyerIdentity?: "omit" | "masked" | "full";
 }
 export declare function offerDocumentToOffer(doc: OfferDocument, opts?: OfferAdapterOptions): Offer;
 /**

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

@@ -10,12 +10,25 @@
  *
  * Mirrors `orders/adapters.ts`, including its `toIsoOrUndefined` helper.
  */
+// Display masking only — `pii-mask.ts` is the crypto-FREE half that Root Cause
+// #24 split out of `pii-encrypt.ts` precisely so it could be imported freely.
+import { maskEmail, maskName } from "../../../../security/pii-mask";
 function toIsoOrUndefined(value) {
     return value instanceof Date ? value.toISOString() : undefined;
 }
 function toIso(value) {
     return value instanceof Date ? value.toISOString() : String(value);
 }
+/** The three buyer keys, resolved per `buyerIdentity`. Absent keys stay absent. */
+function buyerIdentityFields(doc, mode) {
+    if (mode === "full") {
+        return { buyerUid: doc.buyerUid, buyerName: doc.buyerName, buyerEmail: doc.buyerEmail };
+    }
+    if (mode === "masked") {
+        return { buyerName: maskName(doc.buyerName), buyerEmail: maskEmail(doc.buyerEmail) };
+    }
+    return {};
+}
 export function offerDocumentToOffer(doc, opts = {}) {
     const superseded = doc.status === "withdrawn" && Boolean(doc.supersededByOfferId);
     return {
@@ -59,9 +72,7 @@ export function offerDocumentToOffer(doc, opts = {}) {
         superseded,
         cancelledByAdminUid: doc.cancelledByAdminUid,
         cancelReason: doc.cancelReason,
-        ...(opts.includeBuyerIdentity
-            ? { buyerUid: doc.buyerUid, buyerName: doc.buyerName, buyerEmail: doc.buyerEmail }
-            : {}),
+        ...buyerIdentityFields(doc, opts.buyerIdentity),
     };
 }
 /**

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

@@ -1,5 +1,41 @@
+/**
+ * 🛑 A date that is not a `Date` INSTANCE used to be silently dropped, and that
+ * is not a hypothetical — it blanked the buyer's tracking page.
+ *
+ * The old body was `value instanceof Date ? value.toISOString() : undefined`,
+ * and its parameter was typed `Date | undefined`, so TypeScript had no reason to
+ * object: `OrderDocument` declares these fields as `Date`. What Firestore hands
+ * back does not always agree. Measured end to end after a seller marked an order
+ * shipped: the stored document carried
+ * `shippingDate: "2026-09-29T09:06:22.381Z"` — an ISO **string**, because that is
+ * what the ship write path stores — while `orderDate`, written at creation, was a
+ * real `Date`. So the adapter mapped `orderDate` and dropped `shippingDate`, and
+ * `/user/orders/[id]/track` rendered the Shipped step with an em-dash placeholder
+ * beside a perfectly correct carrier and tracking number. Root Cause #57's shape:
+ * one field lost in an adapter, presenting as a UI that looks merely incomplete.
+ *
+ * Three shapes are accepted because all three genuinely occur here: a `Date`, a
+ * Firestore `Timestamp` (duck-typed on `toDate` rather than imported, so this
+ * file stays free of a firebase-admin import — appkit Export Rules), and an ISO
+ * string. Anything else, including an unparseable string, still yields
+ * `undefined` — a wrong date is worse than a missing one, and the timeline is
+ * built to render the em-dash honestly.
+ */
 function toIsoOrUndefined(value) {
-    return value instanceof Date ? value.toISOString() : undefined;
+    if (!value)
+        return undefined;
+    if (value instanceof Date) {
+        return Number.isNaN(value.getTime()) ? undefined : value.toISOString();
+    }
+    if (typeof value === "object" && typeof value.toDate === "function") {
+        const d = value.toDate();
+        return d instanceof Date && !Number.isNaN(d.getTime()) ? d.toISOString() : undefined;
+    }
+    if (typeof value === "string" || typeof value === "number") {
+        const d = new Date(value);
+        return Number.isNaN(d.getTime()) ? undefined : d.toISOString();
+    }
+    return undefined;
 }
 export function orderDocumentToOrder(doc) {
     const items = doc.items?.length
@@ -107,6 +143,23 @@ export function orderDocumentToOrder(doc) {
         shipmentProtectionAddon: doc.shipmentProtectionAddon,
         shipmentProtectionFee: doc.shipmentProtectionFee,
         platformFee: doc.platformFee,
+        /*
+         * 🛑 `gstAmount` -> `tax`, and codHandlingFee alongside it.
+         *
+         * The comment four lines up is about exactly this and the same block still
+         * dropped two fees. The invoice renders its GST line as
+         * `order.tax !== undefined && order.tax > 0`, and nothing ever set `tax`,
+         * so that line could never appear — Root Cause #57's silent "not
+         * applicable" fallback, on a financial document.
+         *
+         * Measured on a real order: the invoice listed Subtotal ₹899.00 and
+         * Shipping ₹77.00 against a stated Total of ₹997.80, leaving ₹21.80 with
+         * nothing to explain it (₹10 platform fee + ₹10 WhatsApp updates +
+         * ₹1.80 GST). An invoice whose lines do not sum to its own total is a
+         * GST-compliance problem, not a cosmetic one.
+         */
+        tax: doc.gstAmount,
+        codHandlingFee: doc.codHandlingFee,
         trackingNumber: doc.trackingNumber,
         shippingCarrier: doc.shippingCarrier,
         trackingUrl: doc.trackingUrl,

package/dist/client.d.ts

@@ -462,6 +462,7 @@ export { BecomeSellerView } from "./features/account/index";
 export type { BidDocument } from "./features/auctions/index";
 export type { ClaimedCouponDocument } from "./features/promotions/schemas";
 export { groupOrderItemsByLine } from "./features/orders/index";
+export { shortOrderRef } from "./features/orders/index";
 export type { LineOrderGroup, OutOfStockPolicy } from "./features/orders/index";
 export { MediaUploadField } from "./features/media/index";
 export { PrizeRevealModal } from "./features/products/components/PrizeRevealModal";

package/dist/client.js

@@ -467,6 +467,7 @@ export { Card, CardBody } from "./ui/index";
 export { SellerCouponsView, SellerCreateProductView, SellerEditProductView, useBecomeSeller, } from "./features/seller/index";
 export { BecomeSellerView } from "./features/account/index";
 export { groupOrderItemsByLine } from "./features/orders/index";
+export { shortOrderRef } from "./features/orders/index";
 export { MediaUploadField } from "./features/media/index";
 export { PrizeRevealModal } from "./features/products/components/PrizeRevealModal";
 export { useProduct } from "./features/products/index";

package/dist/features/account/components/UserOrdersView.js

@@ -9,6 +9,7 @@ import { PaginatedSelect } from "../../../ui/components/PaginatedSelect";
 import { DataListingView } from "../../admin/components/DataListingView";
 import { OrderCard } from "../../orders/components/OrdersList";
 import { useOrderScope } from "../../orders/components/OrderScopeTabs";
+import { useSearchParams } from "next/navigation";
 const CANCELLABLE_STATUSES = new Set(["pending", "confirmed", "processing"]);
 const TRACKABLE_STATUSES = new Set(["shipped"]);
 const SORT_OPTIONS = [
@@ -45,6 +46,33 @@ const STATUS_OPTIONS = [
 ];
 export function UserOrdersView({ onOrderClick }) {
     const orderScope = useOrderScope();
+    /*
+     * 🛑 A FILTERED empty result is not an empty account, and saying so is a lie
+     * the buyer has no way to check.
+     *
+     * Both empty states here read "You haven't placed any orders yet." That is
+     * correct for a new account and flatly wrong the moment a search or a status
+     * chip is what emptied the list. Measured: /user/orders?q=zzzznope on an
+     * account with roughly thirty real orders rendered exactly that sentence — a
+     * buyer searching for an order they could not find would reasonably conclude
+     * their whole history had gone.
+     *
+     * Same shape as the poll leaderboard fixed earlier in this run, where a
+     * withheld tally rendered as "No votes yet." beside a participant count of
+     * 365: an empty result must not be reported as an absolute zero when a filter
+     * is the reason.
+     *
+     * Read from the URL rather than threaded through `renderCards`, whose
+     * signature is `(rows, view, selection, isLoading)` and carries no filter
+     * state. `useUrlTable`/`useSearchParams` hold no local state, so a second
+     * reader against the same URL stays in sync with the listing's own
+     * (CLAUDE.md, Root Cause #35).
+     */
+    const searchParams = useSearchParams();
+    const hasNarrowingFilter = ["q", "search", "status", "orderType", "filters"].some((k) => Boolean(searchParams.get(k)));
+    const emptyMessage = hasNarrowingFilter
+        ? "No orders match your search or filters."
+        : "You haven't placed any orders yet.";
     const config = {
         portal: "user",
         title: "My Orders",
@@ -56,7 +84,7 @@ export function UserOrdersView({ onOrderClick }) {
             // match more.
             fields: ["id"],
         },
-        emptyLabel: "You haven't placed any orders yet.",
+        emptyLabel: emptyMessage,
         filterKeys: ["status", "orderType"],
         defaultSort: sortBy("createdAt", "DESC"),
         queryKey: ["user", "orders", "listing"],
@@ -82,7 +110,7 @@ export function UserOrdersView({ onOrderClick }) {
                 return (_jsx(Stack, { gap: "md", children: Array.from({ length: 3 }).map((_, i) => (_jsx(Div, { className: "h-24 animate-pulse border border-[var(--appkit-color-border)]", rounded: "xl" }, i))) }));
             }
             if (rows.length === 0) {
-                return _jsx(Text, { color: "muted", children: "You haven't placed any orders yet." });
+                return _jsx(Text, { color: "muted", children: emptyMessage });
             }
             return (_jsx(Grid, { gap: "md", className: "grid-cols-1", children: rows.map((order) => (_jsx(OrderCard, { order: order, onClick: onOrderClick, renderActions: () => (_jsxs(_Fragment, { children: [_jsx(Button, { asChild: true, variant: "outline", size: "sm", children: _jsx(TextLink, { href: String(ROUTES.USER.ORDER_DETAIL(order.id)), children: ACTIONS.USER["view-order"].label }) }), TRACKABLE_STATUSES.has(order.orderStatus) && (_jsx(Button, { asChild: true, variant: "ghost", size: "sm", children: _jsx(TextLink, { href: String(ROUTES.USER.ORDER_TRACK(order.id)), children: ACTIONS.USER["track-order"].label }) })), CANCELLABLE_STATUSES.has(order.orderStatus) && (_jsx(Button, { asChild: true, variant: "ghost", size: "sm", children: _jsx(TextLink, { href: String(ROUTES.USER.ORDER_CANCEL(order.id)), children: ACTIONS.USER["cancel-order"].label }) }))] })) }, order.id))) }));
         },

package/dist/features/account/hooks/useAddresses.d.ts

@@ -64,13 +64,28 @@ export declare function useCreateAddress(options?: {
 /**
  * Update options.
  *
- * `method` exists because the two portals disagree: `/api/user/addresses/[id]`
- * exports PATCH and `/api/store/addresses/[id]` exports PUT, and
- * `SellerAddressesView` hardcodes PUT against the latter. Changing the route's
- * verb would break that working call site, so the hook bends instead.
+ * 🛑 `method` DEFAULTS TO PUT, because both portals take PUT.
  *
- * Caught by `audit-client-verb-match` before the store pages were written —
- * this hook would have 405'd the moment they reused it.
+ * This defaulted to PATCH on the strength of a comment saying "the two portals
+ * disagree: `/api/user/addresses/[id]` exports PATCH and
+ * `/api/store/addresses/[id]` exports PUT". Measured against both route files,
+ * each exports **GET / PUT / DELETE** and NEITHER exports PATCH — so the
+ * premise was stale and the default was the only thing disagreeing with either
+ * of them. Every buyer edit sent `PATCH /api/user/addresses/{id}` and took a
+ * **405**, surfacing as `ApiClientError: Invalid JSON response`. The form stays
+ * on the edit page and the record is unchanged. (`EditAddressClient` does call
+ * `showToast("Failed to update address.", "error")` from `onError`; whether the
+ * buyer actually sees it was NOT established — every measurement landed after a
+ * toast's lifetime, so it is not claimed either way here.)
+ *
+ * The prop is kept rather than deleted so a portal that genuinely wants PATCH
+ * can ask for it, and `SellerAddressesView` keeps passing PUT explicitly.
+ *
+ * 🛑 That comment also cited `audit-client-verb-match` as proof this could
+ * not happen. The audit reports **clean** while the 405 is live: it resolves
+ * literal `apiClient.patch("/some/path")` calls, and cannot see a verb chosen
+ * at runtime by `method === "PUT" ? apiClient.put(...) : apiClient.patch(...)`.
+ * A gate you have not watched fail is not a gate (Root Cause #87).
  */
 export interface UpdateAddressOptions {
     byIdEndpoint?: (id: string) => string;

package/dist/features/account/hooks/useAddresses.js

@@ -46,7 +46,7 @@ export function useCreateAddress(options) {
 export function useUpdateAddress(id, options) {
     const queryClient = useQueryClient();
     const byIdEndpoint = options?.byIdEndpoint ?? DEFAULT_ENDPOINTS.byId;
-    const method = options?.method ?? "PATCH";
+    const method = options?.method ?? "PUT";
     return useMutation({
         mutationFn: (data) => method === "PUT"
             ? apiClient.put(byIdEndpoint(id), data)

package/dist/features/addresses/hooks/usePostalLookup.js

@@ -45,7 +45,64 @@ import * as React from "react";
 import { normalizeError } from "../../../errors/normalize";
 import { countryFor, isValidPostalCode } from "../../../constants/geo/countries";
 const ENDPOINT = "https://api.zippopotam.us";
+const INDIA_ENDPOINT = "https://api.postalpincode.in/pincode";
 const DEBOUNCE_MS = 400;
+/**
+ * 🛑 India does not go through Zippopotam, because Zippopotam has no city
+ * for an Indian PIN.
+ *
+ * Its `places[].place name` is the POST OFFICE, and measured against the five
+ * largest Indian cities not one of them returned the city:
+ *
+ *     560001 Bengaluru — "Rajbhavan"
+ *     400001 Mumbai    — "Haji S Musafarkhana"
+ *     110001 Delhi     — "Janpath"
+ *     700001 Kolkata   — "Lalbazar"
+ *     452001 Indore    — "Indore Jail Road"
+ *
+ * So the City field was filled with a street or locality on every Indian
+ * address, which is worse than leaving it blank: the buyer sees a
+ * plausible-looking filled field and has no reason to correct it, and the
+ * courier gets an address with no city. This hook's own promise — "typing a
+ * zipcode should fill in the city" — was never once kept in the only market
+ * this site serves.
+ *
+ * India Post publishes `District`, which IS the city (Bangalore, Mumbai,
+ * Indore). Note it uses the older spellings; that is the authority's own data
+ * and not ours to rewrite.
+ */
+async function lookupIndia(code, signal) {
+    const res = await fetch(`${INDIA_ENDPOINT}/${encodeURIComponent(code)}`, { signal });
+    if (!res.ok)
+        return null;
+    const json = (await res.json());
+    const row = json?.[0];
+    if (row?.Status !== "Success")
+        return null;
+    const offices = (row.PostOffice ?? []).filter(Boolean);
+    if (offices.length === 0)
+        return null;
+    /*
+     * The MOST COMMON district, not the first. A PIN on a boundary returns post
+     * offices from two districts — 400001 lists 'Mumbai' and 'Raigarh(MH)' —
+     * and the first row is not reliably the one the buyer means.
+     */
+    const tally = new Map();
+    for (const o of offices) {
+        const d = (o.District ?? "").trim();
+        if (d)
+            tally.set(d, (tally.get(d) ?? 0) + 1);
+    }
+    let city = "";
+    let best = 0;
+    for (const [d, n] of tally) {
+        if (n > best) {
+            city = d;
+            best = n;
+        }
+    }
+    return { city, state: (offices[0].State ?? "").trim() };
+}
 /**
  * Per-session cache, keyed `{country}:{postal}`.
  *
@@ -94,18 +151,33 @@ export function usePostalLookup({ onResolved, enabled = true, }) {
             const controller = new AbortController();
             abortRef.current = controller;
             setIsLooking(true);
-            void fetch(`${ENDPOINT}/${def.code.toLowerCase()}/${encodeURIComponent(code)}`, {
-                signal: controller.signal,
-            })
-                .then((res) => (res.ok ? res.json() : null))
-                .then((json) => {
-                const place = json?.places?.[0];
-                const result = place
-                    ? {
-                        city: place["place name"] ?? "",
-                        state: place.state ?? place["state abbreviation"] ?? "",
-                    }
-                    : null;
+            /*
+             * India has its own source — see `lookupIndia`. Everywhere else keeps
+             * Zippopotam, whose "place name" IS the city outside India.
+             */
+            const request = def.code.toUpperCase() === "IN"
+                ? lookupIndia(code, controller.signal)
+                : fetch(`${ENDPOINT}/${def.code.toLowerCase()}/${encodeURIComponent(code)}`, {
+                    signal: controller.signal,
+                })
+                    .then((res) => (res.ok ? res.json() : null))
+                    .then((json) => {
+                    const place = json?.places?.[0];
+                    return place
+                        ? {
+                            city: place["place name"] ?? "",
+                            state: place.state ?? place["state abbreviation"] ?? "",
+                        }
+                        : null;
+                });
+            void request
+                .then((resolved) => {
+                /*
+                 * A result with neither field is a miss, not a hit — handing the
+                 * form two empty strings would clear nothing and resolve nothing,
+                 * while caching it as success hides a real answer for the session.
+                 */
+                const result = resolved && (resolved.city || resolved.state) ? resolved : null;
                 CACHE.set(key, result);
                 if (result)
                     onResolvedRef.current(result);

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

@@ -65,10 +65,45 @@ const ADMIN_CATEGORIES_CONFIG = {
     columns: COLUMNS,
     mapRows: (response) => {
         const sourceItems = extractCategoryRows(response);
-        return toRecordArray(sourceItems).map((item, index) => ({
+        const rows = toRecordArray(sourceItems);
+        /*
+         * 🛑 THE PARENT COLUMN READ A FIELD THAT DOES NOT EXIST.
+         *
+         * It was `toStringValue(item.parentId, "root")`, and `CategoryDocument` has
+         * no `parentId` — the field is **`parentIds: string[]`**, the full ancestor
+         * chain. So the fallback fired on every row: measured on the live list, all
+         * **100** categories displayed "Parent: root" while their tiers ranged 0-4
+         * and only 22 were actually roots. The tier beside it renders correctly from
+         * the same document, which is what makes the wrong value so easy to trust.
+         *
+         * CLAUDE.md flags this exact confusion in the Seed Data Reference ("NOT a
+         * single `parentId`"), and `parentId` does still exist — as an optional
+         * field on a create/update INPUT shape, which is why it typechecks here and
+         * is undefined at runtime.
+         *
+         * `parentIds` is ordered ancestors-nearest-LAST ("matching how parentIds is
+         * read elsewhere", category-tree.ts), so the immediate parent is the final
+         * element. The name is shown where the list already knows it: every
+         * category is in this same response, so the lookup costs nothing and an id
+         * is a poor answer to "what is this filed under".
+         */
+        const nameById = new Map();
+        for (const r of rows) {
+            const id = toStringValue(r.id, "");
+            if (id)
+                nameById.set(id, toStringValue(r.name, id));
+        }
+        const parentLabel = (item) => {
+            const chain = Array.isArray(item.parentIds) ? item.parentIds : [];
+            const immediate = chain.length ? String(chain[chain.length - 1]) : "";
+            if (!immediate)
+                return "root";
+            return nameById.get(immediate) ?? immediate;
+        };
+        return rows.map((item, index) => ({
             id: toStringValue(item.id, `category-${index}`),
             primary: toStringValue(item.name, "Untitled category"),
-            secondary: `Slug: ${toStringValue(item.slug, "no-slug")} · Tier: ${typeof item.tier === "number" ? String(item.tier) : "-"} · Parent: ${toStringValue(item.parentId, "root")}`,
+            secondary: `Slug: ${toStringValue(item.slug, "no-slug")} · Tier: ${typeof item.tier === "number" ? String(item.tier) : "-"} · Parent: ${parentLabel(item)}`,
             status: typeof item.isActive === "boolean"
                 ? item.isActive
                     ? "Active"

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

@@ -36,7 +36,7 @@ import React, { useState } from "react";
 import { useQueryClient } from "@tanstack/react-query";
 import { FilterChipGroup, ListingLayout, RecordDetailModal, RowActionMenu, useToast, } from "../../../ui";
 import { ADMIN_ENDPOINTS } from "../../../constants/api-endpoints";
-import { ADMIN_OFFER_STATUS_TABS } from "../constants/filter-tabs";
+import { ADMIN_OFFER_STATUS_TABS, offerStatusLabel } from "../constants/filter-tabs";
 import { OfferPhaseTimeline } from "../../seller/components/OfferPhaseTimeline";
 import { QuickFormDrawer } from "../../shell/QuickFormDrawer";
 import { cancelOfferFormSchema } from "../../seller/schemas/offer-forms";
@@ -136,7 +136,7 @@ export function AdminOffersView({ children, ...props }) {
                 `Listed: ${toCurrency(item.listedPrice)}`,
                 `${toStringValue(item.buyerName, "Unknown buyer")} → ${toStringValue(item.storeName, "Unknown store")}`,
             ].join(" · "),
-            status: toStringValue(item.status, "pending"),
+            status: offerStatusLabel(toStringValue(item.status, "pending"), "admin"),
             updatedAt: toRelativeDate(item.updatedAt ?? item.createdAt),
             detail: item,
         })),

package/dist/features/admin/constants/filter-tabs.d.ts

@@ -650,6 +650,31 @@ export declare const SELLER_OFFER_STATUS_TABS: readonly [{
     readonly id: "paid";
     readonly label: "Paid";
 }];
+/**
+ * The display label for an offer status — the SAME words as that audience's
+ * own filter chips.
+ *
+ * 🛑 Both offer views rendered the raw stored value as the badge, so a seller
+ * filtered by a chip reading **"Rejected"** and the matching rows came back
+ * badged **"declined"** — two words for one state, on one screen. Every other
+ * badge was lowercase too ("pending", "accepted") while the fallback beside it
+ * was capitalised `"Pending"`, which is the tell that display-cased values were
+ * always the intent.
+ *
+ * 🛑 **`audience` is not ceremony — the two chip sets DISAGREE on purpose.**
+ * `declined` is "Rejected" to a seller (see the header above: kept for
+ * continuity with existing seller-facing wording) and "Declined" to an admin.
+ * A single shared lookup would therefore have printed "Rejected" on the admin
+ * screen beside its own "Declined" chip — reintroducing the exact mismatch
+ * this function exists to remove, one audience over.
+ *
+ * Deriving from the arrays rather than writing a third map is the point: a
+ * hand-written copy is how ten enumerations of one union came to disagree
+ * (Root Cause #61). An unrecognised value falls through to itself, so an
+ * eighth status shows up as its raw name rather than vanishing (Root Cause
+ * #72 — unknown must never render as absent).
+ */
+export declare function offerStatusLabel(status: string | null | undefined, audience: "seller" | "admin"): string;
 /** Seller > Bids — bid-state filter chip set. Uses the empty-sentinel
  *  variant (see `EMPTY_TAB`). */
 export declare const SELLER_BID_STATUS_TABS: readonly [{

package/dist/features/admin/constants/filter-tabs.js

@@ -360,6 +360,36 @@ export const SELLER_OFFER_STATUS_TABS = [
     { id: "withdrawn", label: "Withdrawn" },
     { id: "paid", label: "Paid" },
 ];
+/**
+ * The display label for an offer status — the SAME words as that audience's
+ * own filter chips.
+ *
+ * 🛑 Both offer views rendered the raw stored value as the badge, so a seller
+ * filtered by a chip reading **"Rejected"** and the matching rows came back
+ * badged **"declined"** — two words for one state, on one screen. Every other
+ * badge was lowercase too ("pending", "accepted") while the fallback beside it
+ * was capitalised `"Pending"`, which is the tell that display-cased values were
+ * always the intent.
+ *
+ * 🛑 **`audience` is not ceremony — the two chip sets DISAGREE on purpose.**
+ * `declined` is "Rejected" to a seller (see the header above: kept for
+ * continuity with existing seller-facing wording) and "Declined" to an admin.
+ * A single shared lookup would therefore have printed "Rejected" on the admin
+ * screen beside its own "Declined" chip — reintroducing the exact mismatch
+ * this function exists to remove, one audience over.
+ *
+ * Deriving from the arrays rather than writing a third map is the point: a
+ * hand-written copy is how ten enumerations of one union came to disagree
+ * (Root Cause #61). An unrecognised value falls through to itself, so an
+ * eighth status shows up as its raw name rather than vanishing (Root Cause
+ * #72 — unknown must never render as absent).
+ */
+export function offerStatusLabel(status, audience) {
+    if (!status)
+        return "Pending";
+    const tabs = audience === "admin" ? ADMIN_OFFER_STATUS_TABS : SELLER_OFFER_STATUS_TABS;
+    return tabs.find((t) => t.id === status)?.label ?? status;
+}
 /** Seller > Bids — bid-state filter chip set. Uses the empty-sentinel
  *  variant (see `EMPTY_TAB`). */
 export const SELLER_BID_STATUS_TABS = [

package/dist/features/admin/hooks/useAdminListingData.d.ts

@@ -41,5 +41,40 @@ export declare function useAdminListingData<TResponse, TRow extends {
 export declare function toRecordArray(value: unknown): ListingItemRecord[];
 export declare function toStringValue(value: unknown, fallback?: string): string;
 export declare function toCurrency(value: unknown): string;
+/**
+ * A timestamp as human-relative text — **in either direction**.
+ *
+ * 🛑 **Every FUTURE date used to render as "1m ago".** `deltaMs` is
+ * `now - date`, which is negative ahead of now; `deltaMs < hour` then matched,
+ * and `Math.max(1, Math.floor(negative))` clamped the result to exactly `1`.
+ * So a deadline 48 hours away and one 5 minutes away both read "1m ago", and
+ * the clamp is what hid it — without it the string would have been
+ * "-2880m ago", which nobody could have mistaken for working.
+ *
+ * Measured live on `/store/offers` as tyson@beybladearena.in: an offer accepted
+ * seconds earlier showed **"Buyer must pay by 1m ago"** against a real
+ * `checkoutDeadline` of `now + 48h` (`OFFER_CHECKOUT_WINDOW_MS`). The data was
+ * correct and the sentence told the seller — and on the admin view, the admin —
+ * that a buyer had already missed a window that had barely opened. On the
+ * buyer's own side that reads as "too late to pay for the thing you just
+ * negotiated", i.e. an abandoned purchase caused entirely by a formatter.
+ *
+ * Five call sites render a future-capable field today (offer `expiresAt` and
+ * `checkoutDeadline` on both the seller and admin views, and session
+ * `expiresAt`), and any of the other 61 becomes one the moment its field can
+ * hold a future date — which is why this is fixed here rather than at the call
+ * sites.
+ *
+ * The `Math.max(1, …)` floors stay for the PAST direction: they keep a
+ * 40-second-old row reading "1m ago" instead of "0m ago". They are applied to
+ * an absolute magnitude now, so they can no longer mask a sign error.
+ *
+ * NOTE ON ITS HOME: a pure date formatter belongs in `ui/` or
+ * `_internal/client/`, not in an admin hook module that 44 files reach into.
+ * Moving it means rewriting all 44 imports, so it stays put for now and the
+ * seller-side duplicate was deleted instead (see `useSellerListingData.ts`) —
+ * that copy had already drifted, returning "just now" for the same future date
+ * this one called "1m ago". Two answers to one question is the whole argument.
+ */
 export declare function toRelativeDate(value: unknown): string;
 export {};

package/dist/features/admin/hooks/useAdminListingData.js

@@ -63,6 +63,41 @@ export function toCurrency(value) {
     }
     return formatCurrency(value);
 }
+/**
+ * A timestamp as human-relative text — **in either direction**.
+ *
+ * 🛑 **Every FUTURE date used to render as "1m ago".** `deltaMs` is
+ * `now - date`, which is negative ahead of now; `deltaMs < hour` then matched,
+ * and `Math.max(1, Math.floor(negative))` clamped the result to exactly `1`.
+ * So a deadline 48 hours away and one 5 minutes away both read "1m ago", and
+ * the clamp is what hid it — without it the string would have been
+ * "-2880m ago", which nobody could have mistaken for working.
+ *
+ * Measured live on `/store/offers` as tyson@beybladearena.in: an offer accepted
+ * seconds earlier showed **"Buyer must pay by 1m ago"** against a real
+ * `checkoutDeadline` of `now + 48h` (`OFFER_CHECKOUT_WINDOW_MS`). The data was
+ * correct and the sentence told the seller — and on the admin view, the admin —
+ * that a buyer had already missed a window that had barely opened. On the
+ * buyer's own side that reads as "too late to pay for the thing you just
+ * negotiated", i.e. an abandoned purchase caused entirely by a formatter.
+ *
+ * Five call sites render a future-capable field today (offer `expiresAt` and
+ * `checkoutDeadline` on both the seller and admin views, and session
+ * `expiresAt`), and any of the other 61 becomes one the moment its field can
+ * hold a future date — which is why this is fixed here rather than at the call
+ * sites.
+ *
+ * The `Math.max(1, …)` floors stay for the PAST direction: they keep a
+ * 40-second-old row reading "1m ago" instead of "0m ago". They are applied to
+ * an absolute magnitude now, so they can no longer mask a sign error.
+ *
+ * NOTE ON ITS HOME: a pure date formatter belongs in `ui/` or
+ * `_internal/client/`, not in an admin hook module that 44 files reach into.
+ * Moving it means rewriting all 44 imports, so it stays put for now and the
+ * seller-side duplicate was deleted instead (see `useSellerListingData.ts`) —
+ * that copy had already drifted, returning "just now" for the same future date
+ * this one called "1m ago". Two answers to one question is the whole argument.
+ */
 export function toRelativeDate(value) {
     const date = parseDate(value);
     if (!date) {
@@ -72,17 +107,18 @@ export function toRelativeDate(value) {
     const minute = 60000;
     const hour = 60 * minute;
     const day = 24 * hour;
-    if (deltaMs < hour) {
-        const minutes = Math.max(1, Math.floor(deltaMs / minute));
-        return `${minutes}m ago`;
+    const future = deltaMs < 0;
+    const magnitude = Math.abs(deltaMs);
+    // "in 3h" vs "3h ago" — the only difference between the two directions.
+    const phrase = (n, unit) => (future ? `in ${n}${unit}` : `${n}${unit} ago`);
+    if (magnitude < hour) {
+        return phrase(Math.max(1, Math.floor(magnitude / minute)), "m");
     }
-    if (deltaMs < day) {
-        const hours = Math.max(1, Math.floor(deltaMs / hour));
-        return `${hours}h ago`;
+    if (magnitude < day) {
+        return phrase(Math.max(1, Math.floor(magnitude / hour)), "h");
     }
-    if (deltaMs < 7 * day) {
-        const days = Math.max(1, Math.floor(deltaMs / day));
-        return `${days}d ago`;
+    if (magnitude < 7 * day) {
+        return phrase(Math.max(1, Math.floor(magnitude / day)), "d");
     }
     return date.toLocaleDateString("en-IN", {
         day: "2-digit",