@mohasinac/appkit 4.71.0 → 4.72.0

package/dist/_internal/shared/features/layout/config.d.ts

@@ -12,7 +12,15 @@ export declare const DASHBOARD_SIDEBAR_WIDTH: {
     expanded: string;
     compact: string;
 };
-/** Per-variant accent token map. Drives DashboardSidebar active-item styling. */
+/**
+ * Per-variant accent token map — AdminSidebar/SellerSidebar/UserSidebar's
+ * active-item styling (point 12, overhaul brief's per-portal wayfinding).
+ *
+ * Phase 4D (2026-11): until then this was DEAD — each of the three sidebars
+ * hardcoded its own copy of these exact classes rather than reading from
+ * here, so a future change to this map would silently stop matching what
+ * actually renders. All three now reference it directly.
+ */
 export declare const DASHBOARD_ACCENT_CLASSES: Record<DashboardVariant, {
     activeBg: string;
     activeText: string;

package/dist/_internal/shared/features/layout/config.js

@@ -15,7 +15,15 @@ export const DASHBOARD_SIDEBAR_WIDTH = {
     expanded: "lg:w-64",
     compact: "lg:w-16",
 };
-/** Per-variant accent token map. Drives DashboardSidebar active-item styling. */
+/**
+ * Per-variant accent token map — AdminSidebar/SellerSidebar/UserSidebar's
+ * active-item styling (point 12, overhaul brief's per-portal wayfinding).
+ *
+ * Phase 4D (2026-11): until then this was DEAD — each of the three sidebars
+ * hardcoded its own copy of these exact classes rather than reading from
+ * here, so a future change to this map would silently stop matching what
+ * actually renders. All three now reference it directly.
+ */
 export const DASHBOARD_ACCENT_CLASSES = {
     admin: {
         activeBg: "bg-[var(--appkit-color-surface-elevated)]",
@@ -28,8 +36,20 @@ export const DASHBOARD_ACCENT_CLASSES = {
         hoverBg: "hover:bg-[var(--appkit-color-surface)]",
     },
     user: {
-        activeBg: "bg-primary-50 dark:bg-primary-900/25",
-        activeText: "text-primary-700 dark:text-primary-300",
+        /*
+         * 🛑 NOT `bg-primary-*`/`text-primary-*`. The dark theme preset
+         * rebrands `primary` to crimson red (tokens.css, "primary = Crimson
+         * Red"), so the active-nav highlight on every user-portal sidebar item
+         * read as an error/danger bar, not a brand accent — found live via
+         * owner screenshot, 2026-11-02. Matching admin's neutral
+         * `surface-elevated` would also have fixed the danger-color misread,
+         * but would make admin and user visually indistinguishable, defeating
+         * Phase 4D's own per-portal wayfinding goal (point 12) — store already
+         * owns `warning`/amber for the same reason admin owns neutral. `info`
+         * (teal/blue) is the third distinct, non-status-danger hue available.
+         */
+        activeBg: "bg-info-surface",
+        activeText: "text-info",
         hoverBg: "hover:bg-[var(--appkit-color-surface)]",
     },
 };

package/dist/_internal/shared/features/notifications/action-url.js

@@ -161,7 +161,7 @@ export const TYPE_AUDIENCE = {
     review_replied: "buyer",
     catalogue_images_stale: "buyer",
     // Seller-facing.
-    auction_ended: "seller", // "your auction closed with no winner"
+    collector_drop_ended: "seller", // "your collector drop closed with no winner"
     offer_received: "seller",
     review_approved: "seller",
     // Account-level, which lives in the user portal for everyone.

package/dist/_internal/shared/features/notifications/email-eligibility.d.ts

@@ -23,11 +23,11 @@
  * Resend's free tier is 100 emails/day, and three call sites could exhaust it
  * on their own:
  *
- *   · `auctionSettlement` sends `bid_lost` to every losing bidder, up to 50 in
- *     PARALLEL per auction, and settles all expired auctions concurrently —
- *     two auctions is the whole day;
+ *   · `collectorDropSettlement` sends `bid_lost` to every losing bidder, up to 50 in
+ *     PARALLEL per collector drop, and settles all expired collector drops concurrently —
+ *     two collector drops is the whole day;
  *   · `onScamReportCreate` fanned out one send per employee, up to 100;
- *   · `bid_outbid` is one email per bid per bidder on a live auction.
+ *   · `bid_outbid` is one email per bid per bidder on a live collector drop.
  *
  * The gate runs FIRST in `sendNotification`'s channel conjunctions — before the
  * settings read, before the budget counter — so those 50 sends now exit with

package/dist/_internal/shared/features/notifications/email-eligibility.js

@@ -23,11 +23,11 @@
  * Resend's free tier is 100 emails/day, and three call sites could exhaust it
  * on their own:
  *
- *   · `auctionSettlement` sends `bid_lost` to every losing bidder, up to 50 in
- *     PARALLEL per auction, and settles all expired auctions concurrently —
- *     two auctions is the whole day;
+ *   · `collectorDropSettlement` sends `bid_lost` to every losing bidder, up to 50 in
+ *     PARALLEL per collector drop, and settles all expired collector drops concurrently —
+ *     two collector drops is the whole day;
  *   · `onScamReportCreate` fanned out one send per employee, up to 100;
- *   · `bid_outbid` is one email per bid per bidder on a live auction.
+ *   · `bid_outbid` is one email per bid per bidder on a live collector drop.
  *
  * The gate runs FIRST in `sendNotification`'s channel conjunctions — before the
  * settings read, before the budget counter — so those 50 sends now exit with
@@ -67,7 +67,7 @@ export const EMAIL_ELIGIBLE_TYPES = {
     offer_expired: true,
     offer_counter_accepted: true,
     // Won, and on a clock: the winner forfeits the lot if they miss the payment
-    // deadline. This is the one auction type that survives, and it survives
+    // deadline. This is the one collector drop type that survives, and it survives
     // BECAUSE of the deadline — not because winning is nice to hear about.
     bid_won: true,
     // Someone must claim this, and the claim window closes.
@@ -81,14 +81,14 @@ export const EMAIL_ELIGIBLE_TYPES = {
     welcome: true,
     system: true,
     // ── Bell only. ────────────────────────────────────────────────────────────
-    // The three auction fan-outs. `bid_lost` is up to 50 parallel sends per
-    // settled auction; `bid_outbid` is one per bid per bidder; `bid_placed`
-    // pings the seller on every single bid. All three are visible on the auction
+    // The three collector drop fan-outs. `bid_lost` is up to 50 parallel sends per
+    // settled collector drop; `bid_outbid` is one per bid per bidder; `bid_placed`
+    // pings the seller on every single bid. All three are visible on the collector drop
     // page and in the bell, and none of them is a deadline.
     bid_lost: false,
     bid_outbid: false,
     bid_placed: false,
-    auction_ended: false,
+    collector_drop_ended: false,
     // Marketing. The likeliest way to get the sending domain flagged, and the
     // first thing a recipient marks as spam — which damages deliverability for
     // the transactional mail above.

package/dist/_internal/shared/features/offers/config.js

@@ -8,7 +8,7 @@
  *      at a matching percentage the two rounding rules could differ by a rupee —
  *      the button seeding an amount its own submit then bounced.
  * WHAT: One percentage default and one floor function, imported by every gate.
- *       Same discipline as `resolveMinBid` in the auctions config next door.
+ *       Same discipline as `resolveMinBid` in the collector drops config next door.
  *
  * EXPORTS:
  *   DEFAULT_MIN_OFFER_PERCENT, minOfferAmount, isOfferAmountValid,

package/dist/_internal/shared/features/orders/schema.d.ts

@@ -107,14 +107,14 @@ export declare const updateOrderStatusSchema: z.ZodObject<{
 }, "strip", z.ZodTypeAny, {
     status: "cancelled" | "processing" | "shipped" | "delivered" | "return_requested" | "refunded";
     orderId: string;
-    trackingNumber?: string | undefined;
     note?: string | undefined;
+    trackingNumber?: string | undefined;
     carrier?: string | undefined;
 }, {
     status: "cancelled" | "processing" | "shipped" | "delivered" | "return_requested" | "refunded";
     orderId: string;
-    trackingNumber?: string | undefined;
     note?: string | undefined;
+    trackingNumber?: string | undefined;
     carrier?: string | undefined;
 }>;
 export declare const cancelOrderSchema: z.ZodObject<{

package/dist/_internal/shared/features/orders/workflow-registry.d.ts

@@ -0,0 +1,145 @@
+/**
+ * Order workflow registry — per-listing-type lifecycle rules as DATA.
+ *
+ * ## Why this exists
+ *
+ * Order behaviour already differs per listing type, but those differences live
+ * as scattered `if (listingType === ...)` conditionals. That is the same defect
+ * the capability registry exists to fix, and it has already produced a
+ * documented failure mode once: the `ListingType` union's own comment records
+ * 21 named branch sites of which only 11 are compile-checked, with two already
+ * drifted when it was written.
+ *
+ * So the rules become a table, and every guard reads from it. The acceptance
+ * test is that no order/refund code compares `listingType` to a string literal.
+ *
+ * ## 🛑 The gap this closes
+ *
+ * `ORDER_CANCELLABLE_STATUSES = ["pending", "confirmed"]` lets a buyer cancel a
+ * CONFIRMED order. For a surprise/clearance item that contradicts the stated
+ * rule — "once it is confirmed or shipped, it is no more changed", and once it
+ * ships, is revealed, or reaches customs, "it cannot be refunded or cancelled
+ * by any party unless done by the admin".
+ *
+ * A blanket status list cannot express that, because the lock depends on BOTH
+ * the order status AND the item's reveal state. Hence a predicate per type
+ * rather than a constant.
+ *
+ * ## Deliberately NOT here
+ *
+ * Admin override. Admin may act on a locked order by design, and that path is
+ * audited separately — folding it in here would make every predicate take an
+ * actor and obscure the buyer-facing rule this file is about.
+ */
+import type { ListingType } from "../../../../features/products/types/index";
+/** Lifecycle position, mirroring `OrderStatus` without importing the union. */
+export type WorkflowStatus = "pending" | "confirmed" | "processing" | "shipped" | "delivered" | "cancelled" | "refunded" | "return_requested" | "returned";
+/**
+ * Whether a concealed item has been opened.
+ *
+ * Lives on the ORDER ITEM, never the product: two buyers of the same product
+ * are in different states, and the transition is what gates refund eligibility.
+ */
+export type RevealState = "unrevealed" | "revealed";
+export interface OrderWorkflowContext {
+    status: WorkflowStatus;
+    /** Absent for types that cannot conceal — see `supportsSurpriseReveal`. */
+    revealState?: RevealState;
+    /** True once a carrier or customs holds the goods; locks everything. */
+    inCustody?: boolean;
+}
+export interface OrderWorkflowRule {
+    /** May the BUYER still cancel? Admin override is out of scope — see header. */
+    cancellableByBuyer: (ctx: OrderWorkflowContext) => boolean;
+    /** Why not, for a UI that should explain rather than grey a button out. */
+    cancelBlockedReason: (ctx: OrderWorkflowContext) => string | null;
+}
+/**
+ * Resolve the rule for a listing type.
+ *
+ * Keyed off the CAPABILITY, not the type name — so enabling surprise on another
+ * type is a capability-table edit and this file needs no change. That is the
+ * governing principle applied to order rules.
+ */
+export declare function workflowRuleFor(type: ListingType): OrderWorkflowRule;
+/**
+ * How a paid line actually gets delivered.
+ *
+ *   `"ship"`            — a parcel moves; the shipment IS the fulfilment event
+ *   `"instant-digital"` — completes with no human action when payment lands
+ *   `"manual-digital"`  — waits for an explicit release by the seller/staff
+ *   `"none"`            — nothing to fulfil (local handover, chat-only types)
+ */
+export type FulfilmentMode = "ship" | "instant-digital" | "manual-digital" | "none";
+/**
+ * The per-listing half of the fulfilment decision.
+ *
+ * Structurally typed rather than importing `ProductDocument`, so this module
+ * stays dependency-light and the same call works from a product, a cart line
+ * or an order line that only carries the meta it needs.
+ */
+export interface FulfilmentOptIn {
+    digitalCode?: {
+        codeDeliveryMethod?: "auto-claim" | "manual-email";
+    } | null;
+}
+/**
+ * Resolve the fulfilment mode for a line. **Call this instead of comparing a
+ * listing type to a string at a fulfilment site.**
+ *
+ * ## 🛑 The defect this closes
+ *
+ * `digitalCode.codeDeliveryMethod` is seller-settable (`"auto-claim" |
+ * "manual-email"`), is in the seller form, is validated by the request schema,
+ * and **two seeded products already carry `"manual-email"`** — but it had no
+ * reader on any fulfilment path. Checkout decided with
+ * `listingType === "digital-code"` and auto-claimed a code regardless, so a
+ * seller who chose manual release got instant issue anyway. The setting looked
+ * implemented and did nothing.
+ *
+ * ## Two levels, as everywhere else
+ *
+ * `supportsDeferredFulfilment` (type CAN wait for a human) × the per-listing
+ * opt-in (this seller CHOSE to). Deferring without the capability is ignored
+ * rather than honoured — a type with no release action and no pending state
+ * would otherwise strand a paid order with nothing able to complete it. A flag
+ * that cannot be acted on must not change behaviour.
+ *
+ * Enabling manual release on another type is then a capability-row edit plus
+ * that type's own opt-in flag; this function does not change.
+ */
+export declare function fulfilmentModeFor(type: ListingType | undefined, listing?: FulfilmentOptIn | null): FulfilmentMode;
+/**
+ * Does this line complete on its own the moment payment lands?
+ *
+ * The predicate a checkout/payment path should gate auto-fulfilment on. `false`
+ * for a manual-release line, which is the whole point — and it is expressed
+ * positively so the call site reads as a capability question rather than as
+ * "not one of these types".
+ */
+export declare function fulfilsOnPayment(type: ListingType | undefined, listing?: FulfilmentOptIn | null): boolean;
+/** Does this line need a release action from a human before it is delivered? */
+export declare function awaitsManualRelease(type: ListingType | undefined, listing?: FulfilmentOptIn | null): boolean;
+/**
+ * Must checkout collect a shipping address for this line?
+ *
+ * The `requiresShippingAddress` slot of the registry shape, derived from the
+ * `supportsShipping` capability rather than stored twice — two booleans that
+ * can disagree about whether an address is needed is a checkout that either
+ * blocks a digital purchase or ships a code to nowhere.
+ */
+export declare function requiresShippingAddress(type: ListingType | undefined): boolean;
+/** Convenience: may the buyer cancel this line? */
+export declare function canBuyerCancel(type: ListingType, ctx: OrderWorkflowContext): boolean;
+/**
+ * Whole-order cancellability.
+ *
+ * 🛑 Deliberately the AND of every line, not the OR. A buyer cancelling a mixed
+ * order containing one revealed surprise item must not take the whole order
+ * with it — the strictest line governs. Partial cancellation is a separate
+ * feature, not something to fall out of a loose predicate here.
+ */
+export declare function canBuyerCancelOrder(lines: ReadonlyArray<{
+    listingType?: ListingType;
+    ctx: OrderWorkflowContext;
+}>): boolean;

package/dist/_internal/shared/features/orders/workflow-registry.js

@@ -0,0 +1,197 @@
+/**
+ * Order workflow registry — per-listing-type lifecycle rules as DATA.
+ *
+ * ## Why this exists
+ *
+ * Order behaviour already differs per listing type, but those differences live
+ * as scattered `if (listingType === ...)` conditionals. That is the same defect
+ * the capability registry exists to fix, and it has already produced a
+ * documented failure mode once: the `ListingType` union's own comment records
+ * 21 named branch sites of which only 11 are compile-checked, with two already
+ * drifted when it was written.
+ *
+ * So the rules become a table, and every guard reads from it. The acceptance
+ * test is that no order/refund code compares `listingType` to a string literal.
+ *
+ * ## 🛑 The gap this closes
+ *
+ * `ORDER_CANCELLABLE_STATUSES = ["pending", "confirmed"]` lets a buyer cancel a
+ * CONFIRMED order. For a surprise/clearance item that contradicts the stated
+ * rule — "once it is confirmed or shipped, it is no more changed", and once it
+ * ships, is revealed, or reaches customs, "it cannot be refunded or cancelled
+ * by any party unless done by the admin".
+ *
+ * A blanket status list cannot express that, because the lock depends on BOTH
+ * the order status AND the item's reveal state. Hence a predicate per type
+ * rather than a constant.
+ *
+ * ## Deliberately NOT here
+ *
+ * Admin override. Admin may act on a locked order by design, and that path is
+ * audited separately — folding it in here would make every predicate take an
+ * actor and obscure the buyer-facing rule this file is about.
+ */
+import { supportsSurpriseReveal, supportsDeferredFulfilment, hasInstantFulfillment, supportsShipping, } from "../../listing-types/capabilities.js";
+/** Statuses after which nothing is buyer-cancellable, for ANY type. */
+const TERMINAL_OR_IN_FLIGHT = new Set([
+    "processing",
+    "shipped",
+    "delivered",
+    "cancelled",
+    "refunded",
+    "return_requested",
+    "returned",
+]);
+/**
+ * Baseline retail lifecycle: cancellable until the seller starts acting on it.
+ *
+ * Note this KEEPS `confirmed` cancellable, matching today's behaviour for
+ * ordinary goods. Only concealable types tighten it, and they tighten it for a
+ * stated reason rather than as a blanket policy change.
+ */
+function standardRule() {
+    return {
+        cancellableByBuyer: (ctx) => !ctx.inCustody && !TERMINAL_OR_IN_FLIGHT.has(ctx.status),
+        cancelBlockedReason: (ctx) => {
+            if (ctx.inCustody)
+                return "The parcel is already with the carrier or customs.";
+            if (TERMINAL_OR_IN_FLIGHT.has(ctx.status)) {
+                return "This order has moved past the point where it can be cancelled.";
+            }
+            return null;
+        },
+    };
+}
+/**
+ * Concealable lifecycle: the baseline, plus ONE additional lock — reveal.
+ *
+ * **Cancellable while UNREVEALED, and not a moment longer.** Confirmation does
+ * NOT lock it; reveal does. Owner, 2026-11-07: *"it can be cancelled till the
+ * reveal status is not true; once revealed it will be uncancellable and
+ * non-refundable."*
+ *
+ * One predicate covers BOTH clearance modes, which is why it is expressed this
+ * way rather than as two rules:
+ *
+ *   · **immediate reveal** — contents are revealed on the order-details page
+ *     once payment succeeds (not at checkout). The item is therefore `revealed`
+ *     from the outset, so this rule locks it immediately. Correct: the buyer
+ *     did not gamble on anything they can now back out of.
+ *   · **surprise / delayed reveal** — stays `unrevealed`, and so stays
+ *     cancellable, until the buyer reveals at their discretion OR the seller
+ *     ships (shipment auto-reveals, making the allocation public).
+ *
+ * 🛑 An earlier version of this rule also required `status === "pending"`. That
+ * was too strict and is corrected here — it would have stopped a buyer
+ * cancelling an unrevealed surprise order after confirmation, which the owner
+ * explicitly allows.
+ *
+ * Claims for "what arrived is not what was revealed" are deliberately NOT
+ * modelled here — that is the existing item-not-as-described claim type in
+ * support, adjudicated against the immutable allocation record.
+ */
+function concealableRule() {
+    const base = standardRule();
+    return {
+        cancellableByBuyer: (ctx) => base.cancellableByBuyer(ctx) && ctx.revealState !== "revealed",
+        cancelBlockedReason: (ctx) => {
+            const baseReason = base.cancelBlockedReason(ctx);
+            if (baseReason)
+                return baseReason;
+            if (ctx.revealState === "revealed") {
+                return "Revealed items cannot be cancelled or refunded — you were warned before revealing.";
+            }
+            return null;
+        },
+    };
+}
+/**
+ * Resolve the rule for a listing type.
+ *
+ * Keyed off the CAPABILITY, not the type name — so enabling surprise on another
+ * type is a capability-table edit and this file needs no change. That is the
+ * governing principle applied to order rules.
+ */
+export function workflowRuleFor(type) {
+    return supportsSurpriseReveal(type) ? concealableRule() : standardRule();
+}
+/**
+ * Resolve the fulfilment mode for a line. **Call this instead of comparing a
+ * listing type to a string at a fulfilment site.**
+ *
+ * ## 🛑 The defect this closes
+ *
+ * `digitalCode.codeDeliveryMethod` is seller-settable (`"auto-claim" |
+ * "manual-email"`), is in the seller form, is validated by the request schema,
+ * and **two seeded products already carry `"manual-email"`** — but it had no
+ * reader on any fulfilment path. Checkout decided with
+ * `listingType === "digital-code"` and auto-claimed a code regardless, so a
+ * seller who chose manual release got instant issue anyway. The setting looked
+ * implemented and did nothing.
+ *
+ * ## Two levels, as everywhere else
+ *
+ * `supportsDeferredFulfilment` (type CAN wait for a human) × the per-listing
+ * opt-in (this seller CHOSE to). Deferring without the capability is ignored
+ * rather than honoured — a type with no release action and no pending state
+ * would otherwise strand a paid order with nothing able to complete it. A flag
+ * that cannot be acted on must not change behaviour.
+ *
+ * Enabling manual release on another type is then a capability-row edit plus
+ * that type's own opt-in flag; this function does not change.
+ */
+export function fulfilmentModeFor(type, listing) {
+    const t = type ?? "standard";
+    if (supportsShipping(t))
+        return "ship";
+    if (supportsDeferredFulfilment(t) &&
+        listing?.digitalCode?.codeDeliveryMethod === "manual-email") {
+        return "manual-digital";
+    }
+    if (hasInstantFulfillment(t))
+        return "instant-digital";
+    return "none";
+}
+/**
+ * Does this line complete on its own the moment payment lands?
+ *
+ * The predicate a checkout/payment path should gate auto-fulfilment on. `false`
+ * for a manual-release line, which is the whole point — and it is expressed
+ * positively so the call site reads as a capability question rather than as
+ * "not one of these types".
+ */
+export function fulfilsOnPayment(type, listing) {
+    return fulfilmentModeFor(type, listing) === "instant-digital";
+}
+/** Does this line need a release action from a human before it is delivered? */
+export function awaitsManualRelease(type, listing) {
+    return fulfilmentModeFor(type, listing) === "manual-digital";
+}
+/**
+ * Must checkout collect a shipping address for this line?
+ *
+ * The `requiresShippingAddress` slot of the registry shape, derived from the
+ * `supportsShipping` capability rather than stored twice — two booleans that
+ * can disagree about whether an address is needed is a checkout that either
+ * blocks a digital purchase or ships a code to nowhere.
+ */
+export function requiresShippingAddress(type) {
+    return fulfilmentModeFor(type) === "ship";
+}
+/** Convenience: may the buyer cancel this line? */
+export function canBuyerCancel(type, ctx) {
+    return workflowRuleFor(type).cancellableByBuyer(ctx);
+}
+/**
+ * Whole-order cancellability.
+ *
+ * 🛑 Deliberately the AND of every line, not the OR. A buyer cancelling a mixed
+ * order containing one revealed surprise item must not take the whole order
+ * with it — the strictest line governs. Partial cancellation is a separate
+ * feature, not something to fall out of a loose predicate here.
+ */
+export function canBuyerCancelOrder(lines) {
+    if (lines.length === 0)
+        return false;
+    return lines.every((l) => l.listingType ? canBuyerCancel(l.listingType, l.ctx) : standardRule().cancellableByBuyer(l.ctx));
+}

package/dist/_internal/shared/features/payouts/destination.d.ts

@@ -0,0 +1,101 @@
+/**
+ * `AAAA0XXXXXX` — four bank letters, a literal `0`, six branch characters.
+ *
+ * 🛑 This is the FIFTH place this pattern appeared and the only one intended to
+ * survive. The others, measured 2026-10-31:
+ *   · `features/seller/components/SellerPayoutSettingsView.tsx:126`
+ *   · `features/store-extensions/schemas/payout-method-form.ts:45`
+ *   · `src/actions/seller.actions.ts:122`
+ *   · `src/app/api/store/payout-settings/route.ts:101`
+ * Five copies of one format is five chances to disagree about what a valid
+ * IFSC is (Root Cause #75), and the two that mattered — the appkit write path
+ * and the action that calls it — had NO copy at all.
+ */
+export declare const IFSC_PATTERN: RegExp;
+/** `handle@psp` — the shape the existing seller form and payout-method schema both already enforce. */
+export declare const UPI_VPA_PATTERN: RegExp;
+/**
+ * `AAAAA9999A` — five letters, four digits, one letter.
+ *
+ * 🛑 Shape only, and there is no checksum to add: unlike a GSTIN (whose 15th
+ * character IS a base-36 check digit, which is why `isValidGstin` can verify
+ * more than a shape) a PAN carries no check character that can be recomputed.
+ * The fourth letter encodes holder type and the fifth the surname initial, and
+ * neither is something we can validate against anything we hold. So a
+ * well-formed PAN is a well-formed PAN and nothing more — do not add a
+ * "verified" meaning to this function later.
+ */
+export declare const PAN_PATTERN: RegExp;
+export declare function isValidIfsc(raw: string | undefined | null): boolean;
+export declare function isValidUpiVpa(raw: string | undefined | null): boolean;
+export declare function isValidPan(raw: string | undefined | null): boolean;
+/** Upper-cased and trimmed, or `undefined` for a blank — a PAN is never stored mixed-case. */
+export declare function normalisePan(raw: string | undefined | null): string | undefined;
+/**
+ * The verification lifecycle, and who writes each value.
+ *
+ * 🛑 `unverified` is the DEFAULT and an absent field means exactly that. It is
+ * not "unknown": a destination nobody has checked is unverified, and reading
+ * absence as anything better is how `isConfigured: true` came to mean nothing.
+ */
+export declare const PAYOUT_VERIFICATION: {
+    /** Format-valid at most. Written by this module on every destination change. */
+    readonly UNVERIFIED: "unverified";
+    /** Handed to a gateway; its answer has not arrived. Written by the registration job. */
+    readonly PENDING: "pending";
+    /** A gateway accepted the destination. Written ONLY from a gateway response. */
+    readonly VERIFIED: "verified";
+    /** A gateway refused it. `verificationMessage` carries its reason verbatim. */
+    readonly FAILED: "failed";
+};
+export type PayoutVerificationStatus = (typeof PAYOUT_VERIFICATION)[keyof typeof PAYOUT_VERIFICATION];
+export interface PayoutDestinationIssue {
+    /** Dotted field path, so `applyZodIssues`-shaped callers can attach it. */
+    path: string;
+    message: string;
+}
+/** The subset of `SellerPayoutDetails` these rules read. */
+export interface PayoutDestinationLike {
+    method: "upi" | "bank_transfer";
+    upiId?: string;
+    bankAccount?: {
+        accountHolderName?: string;
+        accountNumber?: string;
+        ifscCode?: string;
+        bankName?: string;
+    };
+}
+/**
+ * Everything wrong with this destination, as a list rather than a throw.
+ *
+ * A list because both call sites need all of it at once: the server action
+ * attaches one issue per field, and the registration job records WHY a store
+ * could not be onboarded. Stopping at the first problem would make a seller fix
+ * one field per round trip.
+ *
+ * 🛑 Reports on what is PRESENT. A bank destination with no `accountNumber` is
+ * reported as missing, because the seller form supports "leave blank to keep
+ * the saved number" and the keep-existing semantics belong to the write path —
+ * so the write path passes the RESOLVED destination (merged with what is
+ * stored), never the raw form values. Checking the form values here would
+ * reject every legitimate blank re-save.
+ */
+export declare function payoutDestinationIssues(details: PayoutDestinationLike | undefined | null): PayoutDestinationIssue[];
+/**
+ * Is this destination well-formed? **This, and only this, is what
+ * `isConfigured` means.**
+ */
+export declare function payoutDestinationIsWellFormed(details: PayoutDestinationLike | undefined | null): boolean;
+/**
+ * The verification fields to write alongside a CHANGED destination.
+ *
+ * Returned as an object to spread rather than applied in place, so the write
+ * path cannot forget the message and the timestamp while remembering the
+ * status — three fields that must move together or the UI shows a stale reason
+ * under a fresh status.
+ */
+export declare function resetVerificationOnChange(): {
+    verificationStatus: PayoutVerificationStatus;
+    verificationMessage?: string;
+    verifiedAt?: Date;
+};