@mohasinac/appkit 4.62.0 → 4.63.0

package/dist/features/orders/schemas/index.d.ts

@@ -145,6 +145,15 @@ export declare const orderRefundEventSchema: z.ZodObject<{
     proofDocumentUrl: z.ZodOptional<z.ZodString>;
     proofDocumentMimeType: z.ZodOptional<z.ZodString>;
     overrideReason: z.ZodOptional<z.ZodString>;
+    creditNoteNumber: z.ZodOptional<z.ZodString>;
+    creditNoteIssuedAt: z.ZodOptional<z.ZodUnion<[z.ZodDate, z.ZodString, z.ZodObject<{
+        toDate: z.ZodFunction<z.ZodTuple<[], z.ZodUnknown>, z.ZodDate>;
+    }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+        toDate: z.ZodFunction<z.ZodTuple<[], z.ZodUnknown>, z.ZodDate>;
+    }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+        toDate: z.ZodFunction<z.ZodTuple<[], z.ZodUnknown>, z.ZodDate>;
+    }, z.ZodTypeAny, "passthrough">>]>>;
+    creditNoteStoragePath: z.ZodOptional<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
     type: "full" | "partial";
     amount: number;
@@ -155,8 +164,8 @@ export declare const orderRefundEventSchema: z.ZodObject<{
     }, z.ZodTypeAny, "passthrough">;
     refundedBy: string;
     status?: "failed" | "processed" | "reserved" | undefined;
-    failureReason?: string | undefined;
     gateway?: string | undefined;
+    failureReason?: string | undefined;
     itemIds?: string[] | undefined;
     reasonCode?: string | undefined;
     gatewayRefundId?: string | undefined;
@@ -166,6 +175,11 @@ export declare const orderRefundEventSchema: z.ZodObject<{
     proofDocumentUrl?: string | undefined;
     proofDocumentMimeType?: string | undefined;
     overrideReason?: string | undefined;
+    creditNoteNumber?: string | undefined;
+    creditNoteIssuedAt?: string | Date | z.objectOutputType<{
+        toDate: z.ZodFunction<z.ZodTuple<[], z.ZodUnknown>, z.ZodDate>;
+    }, z.ZodTypeAny, "passthrough"> | undefined;
+    creditNoteStoragePath?: string | undefined;
 }, {
     type: "full" | "partial";
     amount: number;
@@ -176,8 +190,8 @@ export declare const orderRefundEventSchema: z.ZodObject<{
     }, z.ZodTypeAny, "passthrough">;
     refundedBy: string;
     status?: "failed" | "processed" | "reserved" | undefined;
-    failureReason?: string | undefined;
     gateway?: string | undefined;
+    failureReason?: string | undefined;
     itemIds?: string[] | undefined;
     reasonCode?: string | undefined;
     gatewayRefundId?: string | undefined;
@@ -187,6 +201,11 @@ export declare const orderRefundEventSchema: z.ZodObject<{
     proofDocumentUrl?: string | undefined;
     proofDocumentMimeType?: string | undefined;
     overrideReason?: string | undefined;
+    creditNoteNumber?: string | undefined;
+    creditNoteIssuedAt?: string | Date | z.objectInputType<{
+        toDate: z.ZodFunction<z.ZodTuple<[], z.ZodUnknown>, z.ZodDate>;
+    }, z.ZodTypeAny, "passthrough"> | undefined;
+    creditNoteStoragePath?: string | undefined;
 }>;
 export declare const appliedOrderDiscountSchema: z.ZodObject<{
     code: z.ZodString;
@@ -499,6 +518,15 @@ export declare const orderFirestoreSchema: z.ZodObject<{
         proofDocumentUrl: z.ZodOptional<z.ZodString>;
         proofDocumentMimeType: z.ZodOptional<z.ZodString>;
         overrideReason: z.ZodOptional<z.ZodString>;
+        creditNoteNumber: z.ZodOptional<z.ZodString>;
+        creditNoteIssuedAt: z.ZodOptional<z.ZodUnion<[z.ZodDate, z.ZodString, z.ZodObject<{
+            toDate: z.ZodFunction<z.ZodTuple<[], z.ZodUnknown>, z.ZodDate>;
+        }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+            toDate: z.ZodFunction<z.ZodTuple<[], z.ZodUnknown>, z.ZodDate>;
+        }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+            toDate: z.ZodFunction<z.ZodTuple<[], z.ZodUnknown>, z.ZodDate>;
+        }, z.ZodTypeAny, "passthrough">>]>>;
+        creditNoteStoragePath: z.ZodOptional<z.ZodString>;
     }, "strip", z.ZodTypeAny, {
         type: "full" | "partial";
         amount: number;
@@ -509,8 +537,8 @@ export declare const orderFirestoreSchema: z.ZodObject<{
         }, z.ZodTypeAny, "passthrough">;
         refundedBy: string;
         status?: "failed" | "processed" | "reserved" | undefined;
-        failureReason?: string | undefined;
         gateway?: string | undefined;
+        failureReason?: string | undefined;
         itemIds?: string[] | undefined;
         reasonCode?: string | undefined;
         gatewayRefundId?: string | undefined;
@@ -520,6 +548,11 @@ export declare const orderFirestoreSchema: z.ZodObject<{
         proofDocumentUrl?: string | undefined;
         proofDocumentMimeType?: string | undefined;
         overrideReason?: string | undefined;
+        creditNoteNumber?: string | undefined;
+        creditNoteIssuedAt?: string | Date | z.objectOutputType<{
+            toDate: z.ZodFunction<z.ZodTuple<[], z.ZodUnknown>, z.ZodDate>;
+        }, z.ZodTypeAny, "passthrough"> | undefined;
+        creditNoteStoragePath?: string | undefined;
     }, {
         type: "full" | "partial";
         amount: number;
@@ -530,8 +563,8 @@ export declare const orderFirestoreSchema: z.ZodObject<{
         }, z.ZodTypeAny, "passthrough">;
         refundedBy: string;
         status?: "failed" | "processed" | "reserved" | undefined;
-        failureReason?: string | undefined;
         gateway?: string | undefined;
+        failureReason?: string | undefined;
         itemIds?: string[] | undefined;
         reasonCode?: string | undefined;
         gatewayRefundId?: string | undefined;
@@ -541,6 +574,11 @@ export declare const orderFirestoreSchema: z.ZodObject<{
         proofDocumentUrl?: string | undefined;
         proofDocumentMimeType?: string | undefined;
         overrideReason?: string | undefined;
+        creditNoteNumber?: string | undefined;
+        creditNoteIssuedAt?: string | Date | z.objectInputType<{
+            toDate: z.ZodFunction<z.ZodTuple<[], z.ZodUnknown>, z.ZodDate>;
+        }, z.ZodTypeAny, "passthrough"> | undefined;
+        creditNoteStoragePath?: string | undefined;
     }>, "many">>;
     contestable: z.ZodOptional<z.ZodBoolean>;
     adminBypassBy: z.ZodOptional<z.ZodString>;
@@ -646,6 +684,7 @@ export declare const orderFirestoreSchema: z.ZodObject<{
         prizeRevealStatus?: "closed" | "open" | "pending" | "revealed" | undefined;
     }[] | undefined;
     bundleId?: string | undefined;
+    orderType?: string | undefined;
     prizeWon?: {
         title: string;
         images: string[];
@@ -662,7 +701,6 @@ export declare const orderFirestoreSchema: z.ZodObject<{
         bin: string;
     } | undefined;
     offerId?: string | undefined;
-    orderType?: string | undefined;
     isNonRefundable?: boolean | undefined;
     imageUrls?: string[] | undefined;
     refundFeeDeducted?: number | undefined;
@@ -711,8 +749,8 @@ export declare const orderFirestoreSchema: z.ZodObject<{
         }, z.ZodTypeAny, "passthrough">;
         refundedBy: string;
         status?: "failed" | "processed" | "reserved" | undefined;
-        failureReason?: string | undefined;
         gateway?: string | undefined;
+        failureReason?: string | undefined;
         itemIds?: string[] | undefined;
         reasonCode?: string | undefined;
         gatewayRefundId?: string | undefined;
@@ -722,6 +760,11 @@ export declare const orderFirestoreSchema: z.ZodObject<{
         proofDocumentUrl?: string | undefined;
         proofDocumentMimeType?: string | undefined;
         overrideReason?: string | undefined;
+        creditNoteNumber?: string | undefined;
+        creditNoteIssuedAt?: string | Date | z.objectOutputType<{
+            toDate: z.ZodFunction<z.ZodTuple<[], z.ZodUnknown>, z.ZodDate>;
+        }, z.ZodTypeAny, "passthrough"> | undefined;
+        creditNoteStoragePath?: string | undefined;
     }[] | undefined;
     contestable?: boolean | undefined;
     adminBypassBy?: string | undefined;
@@ -800,6 +843,7 @@ export declare const orderFirestoreSchema: z.ZodObject<{
         prizeRevealStatus?: "closed" | "open" | "pending" | "revealed" | undefined;
     }[] | undefined;
     bundleId?: string | undefined;
+    orderType?: string | undefined;
     prizeWon?: {
         title: string;
         images: string[];
@@ -816,7 +860,6 @@ export declare const orderFirestoreSchema: z.ZodObject<{
         bin: string;
     } | undefined;
     offerId?: string | undefined;
-    orderType?: string | undefined;
     isNonRefundable?: boolean | undefined;
     imageUrls?: string[] | undefined;
     refundFeeDeducted?: number | undefined;
@@ -865,8 +908,8 @@ export declare const orderFirestoreSchema: z.ZodObject<{
         }, z.ZodTypeAny, "passthrough">;
         refundedBy: string;
         status?: "failed" | "processed" | "reserved" | undefined;
-        failureReason?: string | undefined;
         gateway?: string | undefined;
+        failureReason?: string | undefined;
         itemIds?: string[] | undefined;
         reasonCode?: string | undefined;
         gatewayRefundId?: string | undefined;
@@ -876,6 +919,11 @@ export declare const orderFirestoreSchema: z.ZodObject<{
         proofDocumentUrl?: string | undefined;
         proofDocumentMimeType?: string | undefined;
         overrideReason?: string | undefined;
+        creditNoteNumber?: string | undefined;
+        creditNoteIssuedAt?: string | Date | z.objectInputType<{
+            toDate: z.ZodFunction<z.ZodTuple<[], z.ZodUnknown>, z.ZodDate>;
+        }, z.ZodTypeAny, "passthrough"> | undefined;
+        creditNoteStoragePath?: string | undefined;
     }[] | undefined;
     contestable?: boolean | undefined;
     adminBypassBy?: string | undefined;

package/dist/features/orders/schemas/index.js

@@ -87,6 +87,18 @@ export const orderRefundEventSchema = z.object({
     proofDocumentUrl: z.string().optional(),
     proofDocumentMimeType: z.string().optional(),
     overrideReason: z.string().optional(),
+    /*
+     * Phase 7 credit note. Added HERE in the same change as the interface, per
+     * the 🛑 above: `z.object()` STRIPS unknown keys, so a field present on the
+     * interface and absent here is REMOVED on parse — it does not error, it
+     * vanishes. That is exactly how this schema silently discarded
+     * `razorpayRefundId`, and a credit-note number discarded on parse is a
+     * numbered document with nothing pointing at it: the number is consumed, the
+     * series has no gap, and no refund claims it.
+     */
+    creditNoteNumber: z.string().optional(),
+    creditNoteIssuedAt: firestoreDateSchema.optional(),
+    creditNoteStoragePath: z.string().optional(),
 });
 export const appliedOrderDiscountSchema = z.object({
     code: z.string(),

package/dist/features/orders/types/index.d.ts

@@ -250,6 +250,32 @@ export interface Order {
     platformFee?: number;
     /** COD handling fee, charged only on cash-on-delivery orders. */
     codHandlingFee?: number;
+    /**
+     * D46/D47 — points spent on this order, in points (1 point = ₹1).
+     *
+     * Absent on every order placed before the tender existed, and absent on any
+     * order that used none.
+     */
+    pointsApplied?: number;
+    /**
+     * What was actually COLLECTED: `total − pointsApplied`.
+     *
+     * 🛑 Read it as **`amountDue ?? total`**, never `amountDue ?? 0`. Absent means
+     * "no points were used, so the whole total was collected"; zero would mean
+     * the order was free. The two are a long way apart on a receipt, and the
+     * wrong default turns every historical order into a ₹0 one.
+     */
+    amountDue?: number;
+    /**
+     * The invoice number from the gapless FY series, e.g. `LIR/26-27/0001`
+     * (Phase 7).
+     *
+     * Absent until the order is paid, and absent on every order placed before
+     * the series existed — so the invoice page must render its own fallback
+     * rather than printing "undefined" where a statutory field belongs.
+     */
+    invoiceNumber?: string;
+    invoiceIssuedAt?: string;
     trackingNumber?: string;
     shippingCarrier?: string;
     /** Carrier tracking page URL — rendered as an external link that opens in a new tab. No live-tracking API integration; this is just the passthrough URL a seller/admin entered. */
@@ -261,6 +287,27 @@ export interface Order {
     timelineTruncated?: number;
     /** How the buyer acquired the right to buy. Written once, at creation. */
     sourceContext?: OrderSourceContext;
+    /**
+     * D55 — the pre-order balance, once the seller has OPENED it for collection.
+     *
+     * 🛑 Absent until then, and that is the difference between "a balance
+     * exists" (`sourceContext.balanceDue > 0`, true from the moment the order
+     * was placed) and "a balance is payable". The buyer's panel gates on this
+     * field, so forgetting it in `orderDocumentToOrder` would render the
+     * "nothing to pay" branch on every order forever — Root Cause #57, which
+     * is what made the whole manual-payment flow dead for weeks.
+     */
+    balance?: {
+        amount: number;
+        method: "manual";
+        status: "awaiting" | "submitted" | "paid" | "rejected";
+        dueBy?: string;
+        proofUrl?: string;
+        transactionId?: string;
+        submittedAt?: string;
+        reviewedAt?: string;
+        reviewNote?: string;
+    };
     physicalLocation?: {
         zone: string;
         shelf: string;

package/dist/features/orders/utils/courier-block.d.ts

@@ -0,0 +1,25 @@
+/**
+ * "Is this order waiting on OUR courier problem?" — one predicate, so the
+ * obligation engine, the seller's UI and the admin digest cannot disagree.
+ *
+ * Deliberately a function over the document rather than a stored boolean: a
+ * denormalised `isCourierBlocked` mirror drifts the first time a write path
+ * forgets it (Root Cause #42), and the field it derives from is right there.
+ */
+import type { OrderDocument } from "../schemas/firestore";
+/** The subset actually read, so callers need not hold a whole order. */
+export interface CourierBlockBearing {
+    courierBlock?: OrderDocument["courierBlock"];
+    shippingDate?: Date | null;
+}
+/**
+ * True while a courier booking we attempted is still unresolved.
+ *
+ * 🛑 A block is CLEARED by the parcel actually going out, not by anything
+ * clearing the field. So a `shippingDate` wins over a stale `courierBlock`:
+ * if the seller gave up waiting and posted it themselves, the order is
+ * dispatched and the block is history, even if nobody deleted it. Reading the
+ * field alone would pause the dispatch clock forever on an order that had in
+ * fact shipped.
+ */
+export declare function hasOpenCourierBlock(order: CourierBlockBearing): boolean;

package/dist/features/orders/utils/courier-block.js

@@ -0,0 +1,23 @@
+/**
+ * "Is this order waiting on OUR courier problem?" — one predicate, so the
+ * obligation engine, the seller's UI and the admin digest cannot disagree.
+ *
+ * Deliberately a function over the document rather than a stored boolean: a
+ * denormalised `isCourierBlocked` mirror drifts the first time a write path
+ * forgets it (Root Cause #42), and the field it derives from is right there.
+ */
+/**
+ * True while a courier booking we attempted is still unresolved.
+ *
+ * 🛑 A block is CLEARED by the parcel actually going out, not by anything
+ * clearing the field. So a `shippingDate` wins over a stale `courierBlock`:
+ * if the seller gave up waiting and posted it themselves, the order is
+ * dispatched and the block is history, even if nobody deleted it. Reading the
+ * field alone would pause the dispatch clock forever on an order that had in
+ * fact shipped.
+ */
+export function hasOpenCourierBlock(order) {
+    if (!order.courierBlock)
+        return false;
+    return !order.shippingDate;
+}

package/dist/features/payment-cases/schemas/firestore.d.ts

@@ -107,7 +107,32 @@ export type PaymentCaseKind = "missing_order" | "unprocessed_event" | "status_co
  * Keyed on the USER, so a persistently broken mirror is one case with a
  * rising `observedCount` rather than a new row every night.
  */
- | "ledger_drift";
+ | "ledger_drift"
+/**
+ * We could not book a courier, so one or more PAID orders cannot be
+ * dispatched by us.
+ *
+ * The commonest cause is our own prepaid courier wallet running dry —
+ * Shiprocket has no recharge API, so the top-up is irreducibly a human
+ * action, which is exactly what a case is for.
+ *
+ * 🛑 KEYED ON THE WALLET (the provider), NOT ON THE ORDER. Fifty blocked
+ * orders are ONE problem with one fix, and the daily email ceiling applies
+ * to staff mail too (`send-guard.ts:92`) — so a per-order case would open
+ * fifty rows and spend the whole 80/day budget telling an operator the same
+ * thing fifty times, leaving them blind to everything else. `openOrObserve`
+ * raises `observedCount` instead, which also makes "how many orders are
+ * stuck behind this" readable at a glance.
+ *
+ * 🛑 Its own kind rather than `shipping_unpriced`, which means we could not
+ * work out what shipping COSTS. Here the price is known and the money to pay
+ * it is not there. The kind chips are what an operator triages by, and this
+ * is the fourth time this file has had to say so — the shortcut is always
+ * attractive because a plausible kind already exists.
+ *
+ * `severity: "error"`: a buyer has paid and their parcel is not moving.
+ */
+ | "courier_unavailable";
 /**
  * Identical to `ReportStatus`, deliberately — see the header. `actioned` means
  * a human did something; `dismissed` means a human decided nothing was wrong.

package/dist/features/payment-cases/schemas/firestore.js

@@ -81,6 +81,7 @@ const PAYMENT_CASE_KIND_MAP = {
     protection_claim: true,
     manual_refund_due: true,
     ledger_drift: true,
+    courier_unavailable: true,
 };
 export const PAYMENT_CASE_KINDS = Object.keys(PAYMENT_CASE_KIND_MAP);
 const PAYMENT_CASE_STATUS_MAP = {

package/dist/features/payments/repository/payout.repository.js

@@ -220,8 +220,9 @@ export class PayoutRepository extends BaseRepository {
             trigger: ctx?.trigger ?? defaultTrigger,
             reason: ctx?.reason,
             note: ctx?.note,
-            // `sellerEmail` / `upiId` — `encryptPiiFields` never descends into
-            // arrays, so either reaching `changes` would persist in PLAINTEXT.
+            // `sellerEmail` / `upiId` — `encryptPiiFields` covers only NAMED paths,
+            // and nothing declares them under `statusHistory[].changes`, so either
+            // one reaching `changes` would persist in PLAINTEXT.
             piiFields: PAYOUT_PII_FIELDS,
         });
         return withEntry ?? patch;

package/dist/features/payments/schemas/firestore.d.ts

@@ -5,6 +5,7 @@ import { type GeneratePayoutIdInput } from "../../../utils/id-generators";
 import type { BaseDocument } from "../../../_internal/shared/types/base-document";
 import type { StatusChangeEntry } from "../../../_internal/shared/history/types";
 import type { Encrypted, Plaintext } from "../../../security/encrypted";
+import type { PayCadence } from "../../../_internal/shared/features/payouts/pay-period";
 export interface PayoutBankAccount {
     accountHolderName: string;
     accountNumberMasked: string;
@@ -45,7 +46,29 @@ export type PayoutPaymentMethod = "bank_transfer" | "upi";
  * asterisks". The distinction is which named method you called.
  */
 export type PayoutPlain = Plaintext<PayoutDocument>;
-export interface PayoutDocument extends BaseDocument {
+/**
+ * 🛑 **A seller payout settles a LIABILITY. An employee payout is an EXPENSE.**
+ *
+ * One undiscriminated shape misstates both statements at once — wages vanish
+ * from the P&L and reappear as settled seller liabilities — so `payeeType` is
+ * a discriminated union rather than an optional field.
+ *
+ * ## Why `PayoutDocument` still names the STORE variant
+ *
+ * Every one of the ~30 existing readers means a seller payout, and every one
+ * of them is correct. Renaming the type they import would turn a safety change
+ * into a mechanical sweep, and the sweep is where the real mistakes go in.
+ * `PayoutDocument = StorePayoutDocument` keeps them compiling and correct;
+ * anything that must handle BOTH takes `AnyPayoutDocument` and is forced by
+ * `tsc` to narrow.
+ *
+ * 🛑 `payeeType` is REQUIRED here, not optional-with-a-default. That breaks
+ * the five sites that CONSTRUCT a payout, which is the entire point — a row
+ * written without it is a row the books cannot classify, and an optional
+ * discriminant defers that discovery to a reader rather than a writer.
+ */
+export interface StorePayoutDocument extends BaseDocument {
+    payeeType: "store";
     storeId: string;
     sellerName: string;
     sellerEmail: Encrypted<string>;
@@ -92,6 +115,74 @@ export interface PayoutDocument extends BaseDocument {
     statusHistory?: StatusChangeEntry[];
     statusHistoryTruncated?: number;
 }
+/**
+ * Wages for a period, earned by resolving support tickets.
+ *
+ * ## 🛑 `platformFee` is ABSENT, not zero
+ *
+ * A `0` would read as "we took no commission on these wages", which is a
+ * statement about a transaction that did not happen. Commission is not a
+ * concept between a platform and its own staff, and the books must be able to
+ * tell "not applicable" from "nil" — a nil commission is a seller payout where
+ * the rate happened to resolve to zero, and those post differently.
+ *
+ * The same argument removes `storeId`, `sellerName`, `sellerEmail`,
+ * `grossAmount`, `platformFeeRate`, `gatewayFee*`, `orderIds` and
+ * `refundDeductions`. A field that cannot apply is omitted so `tsc` refuses
+ * the read, rather than present-and-empty so a reader quietly gets a falsy
+ * value.
+ */
+export interface EmployeePayoutDocument extends BaseDocument {
+    payeeType: "employee";
+    employeeUid: string;
+    employeeName: string;
+    /** PII, same treatment as a seller's. */
+    employeeEmail: Encrypted<string>;
+    amount: number;
+    currency: string;
+    status: PayoutStatus;
+    paymentMethod: PayoutPaymentMethod;
+    bankAccount?: PayoutBankAccount;
+    upiId?: Encrypted<string>;
+    /**
+     * The tickets this payslip is for.
+     *
+     * 🛑 Tickets **still resolved at period end**, not tickets closed during it.
+     * Paying per ticket closed rewards closing rather than resolving, so a
+     * reopened ticket does not count — see `resolvedTicketsForPeriod`.
+     */
+    ticketIds: string[];
+    /** Resolved by `payPeriodFor`, never computed at a call site. */
+    periodStart: Date;
+    periodEnd: Date;
+    payCadence: PayCadence;
+    notes?: string;
+    adminNote?: string;
+    requestedAt: Date;
+    processedAt?: Date;
+    transactionId?: string;
+    statusHistory?: StatusChangeEntry[];
+    statusHistoryTruncated?: number;
+}
+/**
+ * What ~30 existing readers mean, and what they should keep meaning.
+ *
+ * Deliberately an alias rather than a rename: see the header on
+ * `StorePayoutDocument`.
+ */
+export type PayoutDocument = StorePayoutDocument;
+/** Use this ONLY where both kinds genuinely arrive together. */
+export type AnyPayoutDocument = StorePayoutDocument | EmployeePayoutDocument;
+/**
+ * 🛑 Narrow on the DISCRIMINANT, never on the presence of `storeId`.
+ *
+ * A `"storeId" in payout` test reads as equivalent and is not: it answers a
+ * question about the object in hand rather than about what the row IS, so a
+ * partially-populated or hand-built object answers it wrongly, silently, and
+ * in the direction that posts wages as a settled seller liability.
+ */
+export declare function isStorePayout(p: AnyPayoutDocument): p is StorePayoutDocument;
+export declare function isEmployeePayout(p: AnyPayoutDocument): p is EmployeePayoutDocument;
 /**
  * The fields whose changes earn a timeline entry.
  *

package/dist/features/payments/schemas/firestore.js

@@ -8,6 +8,20 @@ export const PayoutStatusValues = {
     PAID: "paid",
     FAILED: "failed",
 };
+/**
+ * 🛑 Narrow on the DISCRIMINANT, never on the presence of `storeId`.
+ *
+ * A `"storeId" in payout` test reads as equivalent and is not: it answers a
+ * question about the object in hand rather than about what the row IS, so a
+ * partially-populated or hand-built object answers it wrongly, silently, and
+ * in the direction that posts wages as a settled seller liability.
+ */
+export function isStorePayout(p) {
+    return p.payeeType === "store";
+}
+export function isEmployeePayout(p) {
+    return p.payeeType === "employee";
+}
 /**
  * The fields whose changes earn a timeline entry.
  *
@@ -36,6 +50,15 @@ export const PAYOUT_INDEXED_FIELDS = [
 ];
 export const DEFAULT_PLATFORM_FEE_RATE = 0.05;
 export const DEFAULT_PAYOUT_DATA = {
+    /*
+     * 🛑 Here as a BACKSTOP, not as the reason the field is set. Every caller
+     * passes `payeeType` explicitly and must keep doing so — a default that is
+     * the only writer makes the discriminant optional in practice, which is the
+     * exact failure the required field exists to prevent. This catches a row
+     * built by some path nobody enumerated and lands it on the correct side of
+     * the books rather than on neither.
+     */
+    payeeType: "store",
     status: "pending",
     platformFeeRate: DEFAULT_PLATFORM_FEE_RATE,
     orderIds: [],

package/dist/features/pricing/components/AdminPricingView.d.ts

@@ -0,0 +1,13 @@
+import React from "react";
+export interface AdminPricingViewProps {
+    /**
+     * The rate endpoint, supplied by the consumer.
+     *
+     * 🛑 REQUIRED, with no default. appkit cannot import `API_ROUTES` (that is
+     * consumer-side), so a default would be a path literal living in the
+     * library — a second place the route is written, and the one nobody updates
+     * when it moves. `audit-hardcoded-api-routes` blocks it, correctly.
+     */
+    endpoint: string;
+}
+export declare function AdminPricingView({ endpoint }: AdminPricingViewProps): React.JSX.Element;