@mohasinac/appkit 4.63.5 → 4.64.0

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

@@ -0,0 +1,412 @@
+/**
+ * Core: MONTHLY seller-standing rollup — grants and revokes the Trusted
+ * Seller tier, and with it early payout.
+ *
+ * ## What it writes
+ *
+ * `stores/{id}.standing` — the cached metrics (this IS the cache; the seller's
+ * progress panel, the public badge and the admin view all read it off the
+ * store document they already load, and none of them recomputes anything).
+ * On a transition it also writes `sellerTier` and `trustedSeller` TOGETHER.
+ *
+ * 🛑 `trustedSeller` moves MONEY. It is read by both payout sweeps
+ * (`weeklyPayoutEligibility`, `autoPayoutEligibility`) via
+ * `storeRepository.findTrustedStoreIds()`, and it means the store is paid at
+ * SHIPPING instead of at delivery — so the platform carries a lost parcel with
+ * the money already gone. That is why this job is the only automatic writer,
+ * why every transition gets an audit row, and why an admin can pin a store
+ * with `standing.tierLockedByAdmin`.
+ *
+ * 🛑 The flag's author wrote, at `store.repository.ts`: *"trust is granted by
+ * hand, one store at a time, on risk grounds. If this ever saturates, the
+ * grant has stopped being deliberate."* Automatic granting is exactly that
+ * case, accepted deliberately by the owner. The mitigations are real and must
+ * not be quietly dropped: both a distinct-BUYER and a distinct-ADDRESS floor,
+ * self-bought orders excluded, test data excluded, and the 500-store bound on
+ * `findTrustedStoreIds` left in place so saturation is visible.
+ */
+import { storeRepository } from "../../../../repositories/index.js";
+import { ORDER_FIELDS, REVIEW_FIELDS } from "../../../../constants/field-names.js";
+import { recordAdminAction } from "../../features/audit-log/actions.js";
+import { AdminAuditActionValues } from "../../../../features/audit-log/schemas/firestore.js";
+import { sendNotification } from "../../../../features/admin/actions/notification-actions.js";
+import { normalizeError } from "../../../../errors/normalize.js";
+import { evaluateSellerStanding, SELLER_STANDING_DEFAULTS, SELLER_TIER, } from "../../../shared/features/seller-standing/config.js";
+const EMPTY_RESULT = {
+    examined: 0,
+    written: 0,
+    granted: [],
+    revoked: [],
+    locked: 0,
+    skippedNotMonthEnd: true,
+};
+/** Firestore page size for the two windowed scans. */
+const SCAN_PAGE = 500;
+// ---------------------------------------------------------------------------
+// The month-end guard
+// ---------------------------------------------------------------------------
+/**
+ * 🛑 THIS IS WHY THE CRON IS `0 2 28-31 * *` AND NOT `0 0 31 * *`.
+ *
+ * Cloud Scheduler uses unix-cron, which has no `L` (last-day) token. A cron on
+ * day 31 **never fires in February, April, June, September or November** — it
+ * would silently skip 5 of 12 months, and the symptom is not an error but a
+ * tier that updates "sometimes". So the schedule fires on each of the last four
+ * candidate days and this guard keeps exactly the real one.
+ *
+ * Uses UTC parts throughout, matching the scheduler's declared `timeZone: UTC`.
+ * A local-time implementation would disagree with the trigger near midnight.
+ */
+export function isLastDayOfMonth(d) {
+    const next = new Date(Date.UTC(d.getUTCFullYear(), d.getUTCMonth(), d.getUTCDate() + 1));
+    return next.getUTCMonth() !== d.getUTCMonth();
+}
+/** The next month-end at or after `d`, for the seller-facing `nextComputeAt`. */
+export function nextLastDayOfMonth(d) {
+    // Day 0 of the following month is the last day of this one.
+    const endOfThis = new Date(Date.UTC(d.getUTCFullYear(), d.getUTCMonth() + 1, 0));
+    if (endOfThis.getTime() > d.getTime())
+        return endOfThis;
+    return new Date(Date.UTC(d.getUTCFullYear(), d.getUTCMonth() + 2, 0));
+}
+const emptyTally = () => ({
+    deliveredOrders: 0,
+    buyers: new Set(),
+    addresses: new Set(),
+    ratingSum: 0,
+    ratingCount: 0,
+});
+function toMetrics(t) {
+    return {
+        deliveredOrders: t.deliveredOrders,
+        distinctBuyers: t.buyers.size,
+        distinctAddresses: t.addresses.size,
+        ratedOrders: t.ratingCount,
+        /*
+         * 0 when there are no ratings, never NaN. `ratingSum / 0` is NaN, and NaN
+         * fails every `>=` comparison — which happens to give the right verdict
+         * here but writes NaN into Firestore, where it is rejected outright on
+         * some paths and renders as "NaN" in the seller's panel on others.
+         */
+        averageRating: t.ratingCount === 0 ? 0 : t.ratingSum / t.ratingCount,
+    };
+}
+function isTestRow(data) {
+    /*
+     * Both spellings. `isTestData` is the legacy boolean and `seedPurpose` is
+     * the newer field it is derived from; a row may carry either, so testing one
+     * would let the other through and let a tester fixture count toward a real
+     * money-moving grant.
+     */
+    if (data.isTestData === true)
+        return true;
+    return data.seedPurpose === "test" || data.seedPurpose === "tester";
+}
+export async function runSellerStandingRollup(ctx, opts = {}) {
+    if (!opts.force && !isLastDayOfMonth(ctx.now)) {
+        ctx.logger.info("sellerStandingRollup: not month-end, skipping", {
+            now: ctx.now.toISOString(),
+        });
+        return { ...EMPTY_RESULT };
+    }
+    /*
+     * 🛑 The CONSTANT, not a settings read.
+     *
+     * This briefly folded an admin override from `siteSettings.sellerStanding`
+     * onto the defaults. That made the job disagree with `/seller-guide` and
+     * `/help/seller-badges`, which render their criteria from the code defaults
+     * — so retuning the numbers would have changed what the tier is granted on
+     * while both public pages went on promising the old figures. One constant,
+     * every surface, agreeing by construction.
+     */
+    const thresholds = SELLER_STANDING_DEFAULTS;
+    const cutoff = new Date(ctx.now.getTime() - thresholds.windowDays * 24 * 60 * 60 * 1000);
+    const nextComputeAt = nextLastDayOfMonth(ctx.now);
+    ctx.logger.info("sellerStandingRollup: starting", {
+        windowDays: thresholds.windowDays,
+        cutoff: cutoff.toISOString(),
+        forced: Boolean(opts.force),
+    });
+    // ── Stores ───────────────────────────────────────────────────────────────
+    /*
+     * Enumerate STORES, not the orders' distinct storeIds. A store that sold
+     * nothing this window must still be evaluated, because that is precisely the
+     * store whose tier should be REVOKED — a reconciler built from the events
+     * that exist can only ever add (Root Cause #102).
+     */
+    const stores = new Map();
+    const storeSnap = await ctx.db
+        .collection("stores")
+        .select("ownerId", "status", "sellerTier", "trustedSeller", "tierLockedByAdmin")
+        .get();
+    for (const doc of storeSnap.docs) {
+        const d = doc.data();
+        stores.set(doc.id, {
+            id: doc.id,
+            ownerId: d.ownerId,
+            status: d.status,
+            sellerTier: d.sellerTier,
+            trustedSeller: d.trustedSeller,
+            tierLockedByAdmin: d.tierLockedByAdmin === true,
+        });
+    }
+    const tallies = new Map();
+    const tally = (storeId) => {
+        let t = tallies.get(storeId);
+        if (!t) {
+            t = emptyTally();
+            tallies.set(storeId, t);
+        }
+        return t;
+    };
+    // ── Orders in the window ─────────────────────────────────────────────────
+    /*
+     * 🛑 Windowed on `orderDate`, which is REQUIRED, not on `deliveryDate`,
+     * which is optional and written by exactly one job (`obligationSweep`). A
+     * Firestore inequality EXCLUDES every document lacking the field, so a range
+     * on `deliveryDate` would silently drop every order a seller marked
+     * delivered by hand — returning a confident undercount with no error
+     * anywhere (Root Cause #100).
+     *
+     * One collection-wide windowed scan rather than a query per store: a
+     * per-store `storeId == X AND orderDate >= cutoff` needs a composite index,
+     * and a missing one fails as FAILED_PRECONDITION that every caller here
+     * would have to not-swallow (Root Cause #2). A single-field inequality is
+     * served by the automatic index. `status` is filtered in memory for the same
+     * reason.
+     */
+    let orderCursor = null;
+    let ordersScanned = 0;
+    for (;;) {
+        let q = ctx.db
+            .collection("orders")
+            .where(ORDER_FIELDS.ORDER_DATE, ">=", cutoff)
+            .orderBy(ORDER_FIELDS.ORDER_DATE, "asc")
+            .limit(SCAN_PAGE);
+        if (orderCursor)
+            q = q.startAfter(orderCursor);
+        const snap = await q.get();
+        if (snap.empty)
+            break;
+        for (const doc of snap.docs) {
+            const d = doc.data();
+            ordersScanned += 1;
+            if (d.status !== "delivered")
+                continue;
+            if (isTestRow(d))
+                continue;
+            const storeId = d.storeId;
+            if (!storeId)
+                continue;
+            const store = stores.get(storeId);
+            if (!store)
+                continue;
+            const userId = d.userId;
+            /*
+             * 🛑 Self-bought orders do not count. Without this a seller reaches the
+             * tier — and early payout — by buying from themselves 25 times, which is
+             * the cheapest possible attack on a criterion that releases money early.
+             */
+            if (userId && store.ownerId && userId === store.ownerId)
+                continue;
+            const t = tally(storeId);
+            t.deliveredOrders += 1;
+            if (userId)
+                t.buyers.add(userId);
+            /*
+             * 🛑 `deliveryAddressId` — the `addresses` row this order was taken
+             * from. It is a provenance pointer, NOT PII and NOT encrypted, so
+             * counting distinct values needs no decryption and no fingerprint of
+             * our own.
+             *
+             * Orders predating the delivery snapshot carry none and contribute
+             * nothing to this criterion. That is forward-only by design: inventing
+             * a key from `deliveryPincode` instead would count two different
+             * households in one pincode as one address, and the encrypted
+             * `deliveryAddressLine1` cannot be read here at all.
+             *
+             * Honest about its limit: a determined seller can save the same physical
+             * place as several address rows. The distinct-BUYER floor is the real
+             * defence; this one raises the cost.
+             */
+            if (d.deliveryAddressId)
+                t.addresses.add(d.deliveryAddressId);
+        }
+        orderCursor = snap.docs[snap.docs.length - 1];
+        if (snap.size < SCAN_PAGE)
+            break;
+    }
+    // ── Reviews in the window ────────────────────────────────────────────────
+    /*
+     * Windowed on `createdAt`, which every document carries via `BaseDocument`.
+     * `ReviewDocument` has no `publishedAt` field at all — CLAUDE.md's seed
+     * table says it does, and that is stale.
+     */
+    let reviewCursor = null;
+    for (;;) {
+        let q = ctx.db
+            .collection("reviews")
+            .where(REVIEW_FIELDS.CREATED_AT, ">=", cutoff)
+            .orderBy(REVIEW_FIELDS.CREATED_AT, "asc")
+            .limit(SCAN_PAGE);
+        if (reviewCursor)
+            q = q.startAfter(reviewCursor);
+        const snap = await q.get();
+        if (snap.empty)
+            break;
+        for (const doc of snap.docs) {
+            const d = doc.data();
+            if (d.status !== "approved")
+                continue;
+            if (isTestRow(d))
+                continue;
+            const storeId = d.storeId;
+            if (!storeId || !stores.has(storeId))
+                continue;
+            const rating = Number(d.rating);
+            if (!Number.isFinite(rating))
+                continue;
+            const t = tally(storeId);
+            t.ratingSum += rating;
+            t.ratingCount += 1;
+        }
+        reviewCursor = snap.docs[snap.docs.length - 1];
+        if (snap.size < SCAN_PAGE)
+            break;
+    }
+    // ── Evaluate + write ─────────────────────────────────────────────────────
+    /*
+     * 🛑 Through the REPOSITORY, not `ctx.db.update()`.
+     *
+     * `adminUpdate` runs `withStoreHistory`, and `sellerTier` / `trustedSeller`
+     * are both in `STORE_TRACKED_FIELDS` — so a transition earns a
+     * `statusHistory` entry stamped `actorRole: "system"`. A raw document write
+     * would move money with no timeline entry, which is the one thing the
+     * timeline exists for on this field.
+     *
+     * `prior` is the projected shell rather than a full document, which is safe
+     * and deliberate: `withHistory` diffs only `tracked` fields that appear in
+     * the PATCH, and the patch only ever carries `standing` (untracked),
+     * `sellerTier` and `trustedSeller` — both of which the shell selects. The
+     * cast says exactly that and nothing more.
+     */
+    const writeStore = (store, patch) => storeRepository.adminUpdate(store.id, patch, { actor: { role: "system" }, trigger: "sellerStandingRollup" }, store);
+    const granted = [];
+    const revoked = [];
+    let written = 0;
+    let locked = 0;
+    for (const store of stores.values()) {
+        const metrics = toMetrics(tallies.get(store.id) ?? emptyTally());
+        const verdict = evaluateSellerStanding(metrics, thresholds);
+        /*
+         * `standing` is a pure MEASUREMENT — no admin state in it. The pin lives
+         * at the top level precisely so this object can be rebuilt wholesale every
+         * month without carrying a decision forward or needing to be merged.
+         */
+        const standing = {
+            computedAt: ctx.now,
+            nextComputeAt,
+            windowDays: thresholds.windowDays,
+            ...metrics,
+            met: verdict.met,
+        };
+        /*
+         * An admin-pinned store still gets a REFRESHED `standing` — the seller
+         * should see their real figures — but its tier is left exactly where the
+         * admin put it. Writing the metrics while not acting on them is the whole
+         * point of the lock.
+         */
+        if (store.tierLockedByAdmin) {
+            locked += 1;
+            await writeStore(store, { standing });
+            written += 1;
+            continue;
+        }
+        /*
+         * 🛑 A store that is not ACTIVE can never hold the tier. Suspension
+         * already clears it immediately (see `storeRepository.setStatus`), and
+         * this is the belt: a suspended store must not be re-granted early payout
+         * by a month-end run just because its 90-day history still looks good.
+         */
+        const eligible = store.status === "active" && verdict.tier === SELLER_TIER.TRUSTED;
+        const currentTier = store.sellerTier ?? SELLER_TIER.SELLER;
+        const nextTier = eligible ? SELLER_TIER.TRUSTED : SELLER_TIER.SELLER;
+        const update = { standing };
+        const isTransition = nextTier !== currentTier || Boolean(store.trustedSeller) !== eligible;
+        if (isTransition) {
+            update.sellerTier = nextTier;
+            update.trustedSeller = eligible;
+            if (eligible)
+                granted.push(store.id);
+            else
+                revoked.push(store.id);
+        }
+        await writeStore(store, update);
+        written += 1;
+        if (!isTransition)
+            continue;
+        /*
+         * 🛑 Audit and notify on a REAL transition only. Re-saving the monthly
+         * `standing` on an unchanged store would otherwise write an audit row
+         * describing a decision nobody made and email a seller about nothing —
+         * and a log of non-events is how a log stops being read. Same rule the
+         * admin PATCH route applies to this exact field.
+         */
+        void recordAdminAction({
+            actorUid: "system",
+            action: AdminAuditActionValues.STORE_TRUST_CHANGE,
+            targetType: "store",
+            targetId: store.id,
+            targetLabel: store.id,
+            reason: eligible
+                ? "Met every Trusted Seller criterion at the monthly recompute"
+                : "Fell below a Trusted Seller criterion at the monthly recompute",
+            metadata: {
+                trustedSeller: eligible,
+                previous: Boolean(store.trustedSeller),
+                sellerTier: nextTier,
+                trigger: "sellerStandingRollup",
+                ...metrics,
+            },
+        });
+        if (!store.ownerId)
+            continue;
+        /*
+         * The seller is told, because the consequence is concrete in both
+         * directions: gaining the tier changes when they get paid, and losing it
+         * changes it back. Fire-and-forget — a notification failure must not
+         * abort a sweep that has already written the tier.
+         */
+        void sendNotification({
+            userId: store.ownerId,
+            type: "system",
+            priority: "normal",
+            title: eligible ? "You're now a Trusted Seller" : "Trusted Seller status paused",
+            message: eligible
+                ? "Your store met every Trusted Seller criterion this month. Your badge is live and your payouts now start when you ship, rather than on delivery."
+                : `Your store no longer meets every Trusted Seller criterion, so the badge is paused and payouts return to starting on delivery. ${verdict.unmetCount === 1 ? "One criterion" : `${verdict.unmetCount} criteria`} to regain it — see your seller guide for the current figures.`,
+        }).catch((err) => {
+            const e = normalizeError(err);
+            ctx.logger.warn("sellerStandingRollup: notification failed", {
+                storeId: store.id,
+                error: e.message,
+            });
+        });
+    }
+    ctx.logger.info("sellerStandingRollup: complete", {
+        examined: stores.size,
+        ordersScanned,
+        written,
+        granted: granted.length,
+        revoked: revoked.length,
+        locked,
+    });
+    return {
+        examined: stores.size,
+        written,
+        granted,
+        revoked,
+        locked,
+        skippedNotMonthEnd: false,
+    };
+}

package/dist/_internal/server/jobs/handlers/index.d.ts

@@ -32,6 +32,7 @@ export { hardBanReinstatementHandler } from "./hardBanReinstatement";
 export { paymentReviewAutoApproveHandler } from "./paymentReviewAutoApprove";
 export { productStatsSyncHandler } from "./productStatsSync";
 export { revenueRollupHandler } from "./revenueRollup";
+export { sellerStandingRollupHandler } from "./sellerStandingRollup";
 export { priceIndexRollupHandler } from "./priceIndexRollup";
 export { marketPriceRollupHandler } from "./marketPriceRollup";
 export { searchIndexBuildHandler } from "./searchIndexBuild";

package/dist/_internal/server/jobs/handlers/index.js

@@ -32,6 +32,7 @@ export { hardBanReinstatementHandler } from "./hardBanReinstatement.js";
 export { paymentReviewAutoApproveHandler } from "./paymentReviewAutoApprove.js";
 export { productStatsSyncHandler } from "./productStatsSync.js";
 export { revenueRollupHandler } from "./revenueRollup.js";
+export { sellerStandingRollupHandler } from "./sellerStandingRollup.js";
 export { priceIndexRollupHandler } from "./priceIndexRollup.js";
 export { marketPriceRollupHandler } from "./marketPriceRollup.js";
 export { searchIndexBuildHandler } from "./searchIndexBuild.js";

package/dist/_internal/server/jobs/handlers/sellerStandingRollup.d.ts

@@ -0,0 +1,12 @@
+import type { ScheduleHandler } from "../runtime/types";
+/**
+ * 🛑 No `force`. The schedule fires on days 28–31 and the core's month-end
+ * guard keeps exactly the real last day — see `isLastDayOfMonth` for why the
+ * cron cannot simply say "31".
+ *
+ * `ScheduleHandler` returns `void`, so the result object is dropped here. It
+ * is not lost: the core logs `granted`/`revoked`/`locked` counts, and it is
+ * returned for the admin recompute path and for verification, which call the
+ * core directly with `{ force: true }`.
+ */
+export declare const sellerStandingRollupHandler: ScheduleHandler;

package/dist/_internal/server/jobs/handlers/sellerStandingRollup.js

@@ -0,0 +1,14 @@
+import { runSellerStandingRollup } from "../core/sellerStandingRollup.js";
+/**
+ * 🛑 No `force`. The schedule fires on days 28–31 and the core's month-end
+ * guard keeps exactly the real last day — see `isLastDayOfMonth` for why the
+ * cron cannot simply say "31".
+ *
+ * `ScheduleHandler` returns `void`, so the result object is dropped here. It
+ * is not lost: the core logs `granted`/`revoked`/`locked` counts, and it is
+ * returned for the admin recompute path and for verification, which call the
+ * core directly with `{ force: true }`.
+ */
+export const sellerStandingRollupHandler = async (ctx) => {
+    await runSellerStandingRollup(ctx);
+};

package/dist/_internal/shared/actions/action-registry.js

@@ -771,6 +771,22 @@ export const ACTIONS = {
         },
     },
     STORE: {
+        /*
+         * Open a storefront — the submit button for the store-creation form.
+         *
+         * No `confirmation`: creating a store is additive, reversible by the
+         * seller, and produces a `pending` / non-public document that no buyer can
+         * see until an admin approves it. A dialog here would be friction on the
+         * one step the seller came to perform.
+         */
+        "create-store": {
+            iconKey: "create",
+            id: "store.create-store",
+            label: "Create my store",
+            ariaLabel: "Create your store",
+            description: "Create the seller's storefront. The store starts pending and private until an admin approves it.",
+            kind: "primary",
+        },
         "follow": {
             iconKey: "wishlist",
             id: "store.follow",
@@ -2228,6 +2244,51 @@ export const ACTIONS = {
                 confirmKind: "danger",
             },
         },
+        /*
+         * 🛑 Approve/reject a seller's PENDING store — the step that was missing.
+         *
+         * A store is created `status: "pending"`, `isPublic: false`, and until
+         * 2026-10-24 nothing in any admin UI could move it: `AdminStoresView` had
+         * verify and suspend row actions only, and the one action named for this
+         * job (`adminUpdateStoreStatus`) writes the USER-level `storeStatus`
+         * mirror and never touches the store document — so wiring that would have
+         * marked the applicant approved while leaving their store invisible, with
+         * no error. Both of these go through the store PATCH route, i.e. through
+         * `storeRepository.setStatus`, which is the only writer that keeps
+         * `status` and `isPublic` in step (Root Cause #42).
+         *
+         * Approve carries a confirmation despite being `primary`: it is what makes
+         * a storefront publicly visible, and that is outward-facing.
+         */
+        "approve-store": {
+            iconKey: "approve",
+            id: "admin.approve-store",
+            label: "Approve store",
+            ariaLabel: "Approve this store and make it public",
+            description: "Approve a pending store — sets it active and makes its listings visible to buyers.",
+            kind: "primary",
+            permissions: ["admin"],
+            confirmation: {
+                title: "Approve this store?",
+                body: "The store becomes active and its listings become visible to buyers. The seller will be notified.",
+                confirmLabel: "Approve store",
+            },
+        },
+        "reject-store": {
+            iconKey: "reject",
+            id: "admin.reject-store",
+            label: "Reject store",
+            ariaLabel: "Reject this store application",
+            description: "Reject a pending store application — the store stays hidden from buyers.",
+            kind: "danger",
+            permissions: ["admin"],
+            confirmation: {
+                title: "Reject this store application?",
+                body: "The store will not be published and the seller will be notified. You can approve it later if they resolve the issue.",
+                confirmLabel: "Reject store",
+                confirmKind: "danger",
+            },
+        },
         // ── Review moderation ──────────────────────────────────────────────────
         "approve-review": {
             iconKey: "approve",

package/dist/_internal/shared/features/seller-standing/config.d.ts

@@ -0,0 +1,130 @@
+/**
+ * Seller standing — the ONE definition of what earns the Trusted Seller tier.
+ *
+ * ## Why this is a single pure module
+ *
+ * Four surfaces must agree about the criteria: the monthly rollup job that
+ * grants and revokes, the seller's in-dashboard progress panel, the public
+ * `/seller-guide` criteria table, and the admin trust guide. Four hand-written
+ * copies of "25 delivered orders in 90 days" is Root Cause #73/#75's shape —
+ * the copy that gets fixed is never the copy the reader believes. So the
+ * thresholds, the predicate AND the display rows all come from here.
+ *
+ * 🛑 It had a fifth copy before this existed, and it was prose:
+ * `AdminStoresGuideView` told admins the verified badge was "awarded when the
+ * store has a consistent track record (>=20 delivered orders, >=4.0 rating, 3+
+ * months active)" — numbers no code has ever read, attached to a field nothing
+ * computes. That sentence is what the whole feature was remembered as being.
+ *
+ * ## Pure, and that is load-bearing
+ *
+ * No Firestore, no clock, no `Date.now()`. The job passes in metrics it has
+ * already measured and the UI passes in metrics it has already loaded, so the
+ * same input always produces the same verdict and the panel can never disagree
+ * with the grant.
+ */
+/**
+ * 🛑 A `Record<Criterion, true>`, not a string array.
+ *
+ * Adding a criterion then becomes a COMPILE error at every site that must
+ * display or evaluate it — the thresholds, the labels, the verdict's `met`
+ * map. An array lets a new criterion be evaluated while silently rendering
+ * nowhere, which is how ten hand-maintained enumerations of one union drifted
+ * in Root Cause #61.
+ */
+declare const SELLER_STANDING_CRITERION_MAP: {
+    readonly deliveredOrders: true;
+    readonly distinctBuyers: true;
+    readonly distinctAddresses: true;
+    readonly ratedOrders: true;
+    readonly averageRating: true;
+};
+export type SellerStandingCriterion = keyof typeof SELLER_STANDING_CRITERION_MAP;
+export declare const SELLER_STANDING_CRITERIA: SellerStandingCriterion[];
+/** The two tiers. Ordered: `trusted` is strictly above `seller`. */
+export type SellerTier = "seller" | "trusted";
+export declare const SELLER_TIER: {
+    readonly SELLER: "seller";
+    readonly TRUSTED: "trusted";
+};
+export interface SellerStandingThresholds {
+    /** The rolling window every metric is measured over. */
+    windowDays: number;
+    minDeliveredOrders: number;
+    minDistinctBuyers: number;
+    minDistinctAddresses: number;
+    minRatedOrders: number;
+    /** A mean, 1–5. Compared with `>=`. */
+    minAverageRating: number;
+}
+/**
+ * The shipped defaults.
+ *
+ * 🛑 Every count is measured INSIDE `windowDays`, not lifetime. That is the
+ * strict reading and it was chosen deliberately: the tier grants early payout,
+ * so it has to describe a seller who is shipping reliably *now*, not one who
+ * did two years ago. The consequence worth knowing up front is that on a
+ * freshly seeded catalogue **nobody qualifies**, and that is the correct
+ * result rather than a broken job.
+ *
+ * Admin-overridable via `siteSettings.sellerStanding` so the bar can be tuned
+ * once real volume exists, without a deploy.
+ */
+export declare const SELLER_STANDING_DEFAULTS: SellerStandingThresholds;
+export interface SellerStandingMetrics {
+    /** Delivered orders inside the window, excluding self-bought and test rows. */
+    deliveredOrders: number;
+    /** Distinct buyer uids across those orders. */
+    distinctBuyers: number;
+    /** Distinct shipping-address fingerprints across those orders. */
+    distinctAddresses: number;
+    /** Approved reviews inside the window. */
+    ratedOrders: number;
+    /** Mean of those reviews' ratings, 1–5. `0` when there are none. */
+    averageRating: number;
+}
+export interface SellerStandingVerdict {
+    tier: SellerTier;
+    met: Record<SellerStandingCriterion, boolean>;
+    /** How many criteria are still short — drives "1 criterion to go". */
+    unmetCount: number;
+}
+/**
+ * Does this seller currently meet the bar?
+ *
+ * 🛑 ALL criteria must hold. There is no scoring and no partial credit: the
+ * reward is being paid before delivery, so "mostly reliable" is not a state
+ * this can grant on.
+ */
+export declare function evaluateSellerStanding(metrics: SellerStandingMetrics, thresholds?: SellerStandingThresholds): SellerStandingVerdict;
+export declare const SELLER_STANDING_CRITERION_LABELS: Record<SellerStandingCriterion, string>;
+/**
+ * Why each criterion exists, in the seller's words. Rendered on the guide
+ * pages — a bar with no stated reason reads as arbitrary, and two of these
+ * exist specifically to make the tier hard to manufacture.
+ */
+export declare const SELLER_STANDING_CRITERION_WHY: Record<SellerStandingCriterion, string>;
+export type SellerStandingRowKind = "count" | "rating";
+export interface SellerStandingRow {
+    criterion: SellerStandingCriterion;
+    label: string;
+    why: string;
+    kind: SellerStandingRowKind;
+    /** The seller's current figure. `null` when standing has never been computed. */
+    actual: number | null;
+    target: number;
+    met: boolean;
+}
+/**
+ * One row per criterion, for rendering.
+ *
+ * `metrics` may be null — a store whose standing has never been computed shows
+ * every target with no figure beside it, which is honest. 🛑 It must NOT show
+ * zeros: a confident "0 of 25" on a store that simply has not been measured
+ * yet is the same lie as a counter that has never been written reading as 0
+ * (Root Cause #72).
+ */
+export declare function sellerStandingRows(metrics: SellerStandingMetrics | null | undefined, thresholds?: SellerStandingThresholds): SellerStandingRow[];
+/** `4` → `"4.0"`, `25` → `"25"`. Keeps rating and count formatting in one place. */
+export declare function formatSellerStandingValue(value: number, kind: SellerStandingRowKind): string;
+export {};