@mohasinac/appkit 4.62.1 → 4.63.1

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

@@ -174,6 +174,68 @@ export declare const RefundStatusValues: {
     readonly REJECTED: "rejected";
 };
 /** Firestore storage shape for an order line item â€" distinct from the API display model OrderItem */
+/**
+ * The PII inside one amendment.
+ *
+ * 🛑 BARE keys, and `ORDER_PII_FIELDS` uses the `deliveryAmendments[].…`
+ * form for the same five fields. Two notations, two scopes, both correct:
+ * the `[]` form is for the whole ORDER document, where the hook has to walk
+ * into the array; these bare names are for ONE amendment object, where they
+ * are genuinely top-level.
+ *
+ * 🛑 This list was first justified as "`encryptPiiFields` CANNOT cover an
+ * array" — CLAUDE.md's wording, and FALSE. `encryptInArray` has always
+ * handled `a[].b`, in both directions. The real rule is that the encryptor
+ * does not infer: a field is covered only where it is NAMED, in the notation
+ * matching the object the list is applied to.
+ */
+export declare const AMENDMENT_PII_FIELDS: readonly ["fullName", "phone", "addressLine1", "addressLine2", "landmark"];
+/**
+ * A correction to the delivery address after the order was placed.
+ *
+ * 🛑 Carries the FULL new address, not a diff. A diff would make the current
+ * address reconstructable only by replaying every entry in order, so one
+ * malformed entry in the middle makes everything after it unreadable — and
+ * the parcel label is produced from the current address.
+ *
+ * PII in here is the same problem as everywhere else: `encryptPiiFields` does
+ * not descend into arrays, so these values are NOT encrypted by that
+ * mechanism. `scrubAmendmentPii` is what handles them; see its header.
+ */
+export interface DeliveryAmendment {
+    at: Date;
+    /** Who asked. `actorRole` distinguishes a buyer correction from a support fix. */
+    actorUid?: string;
+    actorRole: "buyer" | "seller" | "admin" | "system";
+    reason?: string;
+    fullName: string;
+    phone: string;
+    addressLine1: string;
+    addressLine2?: string;
+    landmark?: string;
+    city: string;
+    state: string;
+    pincode: string;
+    country: string;
+}
+/**
+ * How much seller prose a single order line carries.
+ *
+ * 🛑 A Firestore document caps at 1 MiB and `items[]` is inline on the order.
+ * 2,000 characters × 20 lines is ~40 KB of description — comfortable. The
+ * same field unbounded is a rejected write at checkout, and the checkout is
+ * the one operation in the system that must never fail for a reason the buyer
+ * cannot act on.
+ */
+export declare const ORDER_ITEM_DESCRIPTION_MAX = 2000;
+/**
+ * How many spec rows one order line keeps.
+ *
+ * Capped by COUNT rather than characters: a spec table is rows, and half a
+ * row is worse than a missing one — "Weight: 4" with the unit cut off reads
+ * as a fact rather than as truncation.
+ */
+export declare const ORDER_ITEM_SPECIFICATIONS_MAX = 30;
 export interface OrderDocumentItem {
     productId: string;
     productTitle: string;
@@ -261,6 +323,37 @@ export interface OrderDocumentItem {
     /** Which kind of multi-member line produced these rows. */
     groupSource?: "bundle" | "product-group" | "grouped-listing";
     /** P-8 GST — snapshotted from the product at order time so the invoice stays accurate even if the product's HSN/rate later changes. */
+    /**
+     * The listing description as it read at purchase.
+     *
+     * 🛑 BOUNDED at `ORDER_ITEM_DESCRIPTION_MAX`, with `descriptionTruncated`
+     * recording that it was cut. A Firestore document caps at 1 MiB and this is
+     * free-form seller prose on every line of every order — an unbounded copy
+     * on a 20-line order is a rejected write AT CHECKOUT, which fails the one
+     * operation that must not fail. Truncation is recorded rather than silent
+     * for the same reason `statusHistoryTruncated` exists: a short description
+     * and a cut one must not read alike.
+     */
+    description?: string;
+    descriptionTruncated?: boolean;
+    /** The spec table as it read at purchase. */
+    specifications?: Array<{
+        name: string;
+        value: string;
+        unit?: string;
+    }>;
+    /**
+     * For a composed listing, the parts it was sold as containing.
+     *
+     * Ids and names only — the part CATALOGUE is a live reference work and
+     * copying its entries onto every order line would duplicate a research
+     * corpus per purchase. What matters for a dispute is which parts were
+     * claimed, not their current catalogue entry.
+     */
+    parts?: Array<{
+        code: string;
+        name: string;
+    }>;
     hsnCode?: string;
     gstRate?: 0 | 5 | 12 | 18 | 28;
     /**
@@ -425,7 +518,64 @@ export interface OrderDocument extends BaseDocument {
     paymentStatus: PaymentStatus;
     paymentId?: string;
     paymentMethod?: string;
+    /**
+     * 🛑 LEGACY. Never written for an order created after Part 14.
+     *
+     * Flat free text with no pincode, no phone and no address id — which is why
+     * `placeOfSupply` had to be written separately rather than derived, and why
+     * parcel booking could not be built at all (`CreateShipmentInput` needs a
+     * structured `{name, phone, addressLine1, city, state, pincode, country}`).
+     *
+     * It is ALSO in `ORDER_UPDATABLE_FIELDS`, so it is editable after the order
+     * — meaning it never recorded what the buyer actually chose. And it was
+     * never encrypted: `ORDER_PII_FIELDS` is `userName` / `userEmail` /
+     * `sellerEmail`, so every delivery address on every order up to now sits in
+     * Firestore in plaintext, despite the docs saying otherwise.
+     *
+     * Read it only as a fallback for orders that predate `deliveryAddress*`,
+     * and render it labelled as legacy. Forward-only; no backfill — parsing a
+     * state out of free text to file a tax return is the thing the
+     * `placeOfSupply` comment below already refuses.
+     */
     shippingAddress?: string;
+    /** PII — encrypted. See `ORDER_PII_FIELDS`. */
+    deliveryFullName?: Encrypted<string>;
+    /** PII — encrypted. */
+    deliveryPhone?: Encrypted<string>;
+    /** PII — encrypted. */
+    deliveryAddressLine1?: Encrypted<string>;
+    /** PII — encrypted. Optional second line / apartment. */
+    deliveryAddressLine2?: Encrypted<string>;
+    /** PII — encrypted. */
+    deliveryLandmark?: Encrypted<string>;
+    deliveryCity?: string;
+    deliveryState?: string;
+    deliveryPincode?: string;
+    deliveryCountry?: string;
+    /**
+     * The `addresses` row this was taken from, for provenance only.
+     *
+     * 🛑 Never resolved at read time. The row can be edited or deleted after the
+     * order, and following it would make the invoice disagree with what the
+     * buyer chose — which is the entire failure a snapshot exists to prevent.
+     */
+    deliveryAddressId?: string;
+    /**
+     * Corrections after the fact, newest LAST. Append-only.
+     *
+     * 🛑 Its OWN array, not a passenger on `statusHistory`.
+     *
+     * `statusHistory` caps at 50 with FIFO eviction. Address edits riding that
+     * log would compete with status transitions for the same slots and evict
+     * the thing the timeline exists to show — and on a chatty order the
+     * creation entry goes first, which is precisely the value reconstruction
+     * depends on. The creation snapshot is a FIELD above for the same reason: a
+     * field cannot be truncated.
+     *
+     * Dispatch reads the latest amendment (or the snapshot when there is none).
+     * The invoice always reads the snapshot.
+     */
+    deliveryAmendments?: DeliveryAmendment[];
     trackingNumber?: string;
     notes?: string;
     orderDate: Date;
@@ -1130,6 +1280,58 @@ export interface OrderDocument extends BaseDocument {
     /** Buyer's required "this payment is genuine, no fraudulent tricks/chargebacks" agreement — server-validated, not just a client-side disable. */
     buyerFraudAgreementAccepted?: boolean;
     buyerFraudAgreementAcceptedAt?: Date;
+    /**
+     * ── D55: the pre-order BALANCE, which is a second payment ──────────────
+     *
+     * 🛑 Its own block rather than reusing the fields above, and that is the
+     * decision this whole feature turns on. Every field above describes ONE
+     * payment; a pre-order has two, months apart. Reusing `paymentProofUrl`
+     * for the balance overwrites the deposit's proof — the evidence for the
+     * payment that created the order — and `paymentReviewOutcome` then means
+     * two different things depending on when you read it.
+     *
+     * Worse, `paymentWindowTimeout` sweeps orders that are `pending`/`pending`
+     * with no `paymentProofUrl`, so clearing that field to collect a balance
+     * would make the sweep cancel and restock a PAID order.
+     *
+     * The balance is therefore its own small state machine beside the
+     * deposit's, sharing the review vocabulary but none of the storage.
+     */
+    balance?: {
+        /**
+         * 🛑 SNAPSHOTTED, not recomputed — D61, and the worst case in the
+         * codebase for it: a deposit-to-balance gap is months. It is copied from
+         * `sourceContext.balanceDue` at the moment the collection is opened, so
+         * a price change, a tax-rate change or a re-quote in between cannot move
+         * what the buyer was told they owe. Recomputing at payment time is how a
+         * buyer who agreed to ₹4,000 is charged ₹4,400.
+         */
+        amount: number;
+        /**
+         * `manual` only, today, and the field exists so the absence is explicit.
+         *
+         * 🛑 The AUTO path is not merely unbuilt — it is blocked on things
+         * outside this repo. A months-long gap cannot use authorise-then-capture
+         * (capture windows are days), so it needs a real RBI-compliant mandate:
+         * AFA at creation, a pre-debit notice at least 24 HOURS before every
+         * debit, and a max amount fixed at registration. Razorpay must also have
+         * recurring enabled, and production runs TEST keys with
+         * `razorpayEnabled` defaulting false. Declaring the union now means
+         * adding `auto` later is a compile-checked change rather than a new
+         * field nobody wires.
+         */
+        method: "manual";
+        status: "awaiting" | "submitted" | "paid" | "rejected";
+        /** Set when the collection is opened, so the buyer has a stated window. */
+        dueBy?: Date;
+        proofUrl?: string;
+        transactionId?: string;
+        submittedAt?: Date;
+        reviewedBy?: string;
+        reviewedAt?: Date;
+        /** Required on `rejected`, for the same reason a refund reason is. */
+        reviewNote?: string;
+    };
     /** Which of the three admin review actions was taken on this order's payment proof. */
     paymentReviewOutcome?: "approved" | "reupload_requested" | "rejected_fraud";
     /** Admin's reason text — required for both `reupload_requested` and `rejected_fraud`. */

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

@@ -48,6 +48,49 @@ export const RefundStatusValues = {
     COMPLETED: "completed",
     REJECTED: "rejected",
 };
+/** Firestore storage shape for an order line item â€" distinct from the API display model OrderItem */
+/**
+ * The PII inside one amendment.
+ *
+ * 🛑 BARE keys, and `ORDER_PII_FIELDS` uses the `deliveryAmendments[].…`
+ * form for the same five fields. Two notations, two scopes, both correct:
+ * the `[]` form is for the whole ORDER document, where the hook has to walk
+ * into the array; these bare names are for ONE amendment object, where they
+ * are genuinely top-level.
+ *
+ * 🛑 This list was first justified as "`encryptPiiFields` CANNOT cover an
+ * array" — CLAUDE.md's wording, and FALSE. `encryptInArray` has always
+ * handled `a[].b`, in both directions. The real rule is that the encryptor
+ * does not infer: a field is covered only where it is NAMED, in the notation
+ * matching the object the list is applied to.
+ */
+export const AMENDMENT_PII_FIELDS = [
+    "fullName",
+    "phone",
+    "addressLine1",
+    "addressLine2",
+    /* Encrypted on the snapshot as `deliveryLandmark`; the two must agree or the
+     * same datum is protected before a correction and exposed after it. */
+    "landmark",
+];
+/**
+ * How much seller prose a single order line carries.
+ *
+ * 🛑 A Firestore document caps at 1 MiB and `items[]` is inline on the order.
+ * 2,000 characters × 20 lines is ~40 KB of description — comfortable. The
+ * same field unbounded is a rejected write at checkout, and the checkout is
+ * the one operation in the system that must never fail for a reason the buyer
+ * cannot act on.
+ */
+export const ORDER_ITEM_DESCRIPTION_MAX = 2000;
+/**
+ * How many spec rows one order line keeps.
+ *
+ * Capped by COUNT rather than characters: a spec table is rows, and half a
+ * row is worse than a missing one — "Weight: 4" with the unit cut off reads
+ * as a fact rather than as truncation.
+ */
+export const ORDER_ITEM_SPECIFICATIONS_MAX = 30;
 export const ORDER_COLLECTION = "orders";
 /**
  * At-most-once gate for refunds. Document id = `sha256(idempotencyKey)`,

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

@@ -684,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[];
@@ -700,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;
@@ -843,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[];
@@ -859,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;

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

@@ -287,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/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;