@mohasinac/appkit 4.62.1 → 4.63.1

package/dist/_internal/shared/features/ledger/rules.js

@@ -0,0 +1,221 @@
+/**
+ * What each business event posts.
+ *
+ * ## 🛑 THIS FILE IS THE WHOLE SAFETY ARGUMENT
+ *
+ * "Every journal entry is machine-generated from a business event" is the
+ * one constraint that makes a ledger maintained by a web application
+ * trustworthy. If a human has to remember that a gateway fee is
+ * `Dr Bank Charges / Cr Bank`, it will eventually be posted backwards — and
+ * a backwards entry still balances, so nothing downstream objects. These
+ * functions are where that memory lives instead.
+ *
+ * Pure, and returning a `PostingInput` rather than writing: the caller hands
+ * the result to `journalRepository.post`, which is the only thing that
+ * touches Firestore and the only thing that checks the period lock. That
+ * separation is also what lets `verify-posting-rules` exercise the rules
+ * against real order shapes without a database.
+ *
+ * ## 🛑 Codes are referenced through ACCOUNT, never as bare strings
+ *
+ * A literal `"2200"` scattered across six rules is six chances to type
+ * `"2000"`, and a posting to an account that does not exist is silently
+ * dropped from the P&L by `profitAndLoss`'s unknown-account skip. One map,
+ * named, so a wrong code is a compile error.
+ */
+/** The accounts these rules post to. Codes match `chartOfAccountsSeedData`. */
+export const ACCOUNT = {
+    BANK: "1100",
+    COURIER_FLOAT: "1150",
+    GATEWAY_RECEIVABLE: "1200",
+    INPUT_GST: "1300",
+    SELLER_PAYABLE: "2100",
+    ACCOUNTS_PAYABLE: "2300",
+    OUTPUT_GST: "2200",
+    BUYER_DEPOSITS: "2400",
+    REFUNDS_PAYABLE: "2500",
+    OPENING_EQUITY: "3900",
+    COMMISSION_INCOME: "4100",
+    SHIPPING_RECOVERED: "4200",
+    ADDON_INCOME: "4300",
+    GATEWAY_CHARGES: "5100",
+    FREIGHT_PAID: "5200",
+};
+/** Drop legs that rounded to nothing, so a zero fee does not fail `assertBalanced`. */
+function compact(lines) {
+    return lines.filter((l) => (l.debit ?? 0) !== 0 || (l.credit ?? 0) !== 0);
+}
+const r2 = (n) => Math.round((n ?? 0) * 100) / 100;
+/**
+ * A paid order.
+ *
+ * 🛑 **The seller payable is the RESIDUAL, not a computed share.** Everything
+ * the platform keeps is recognised explicitly — commission, its GST, the
+ * shipping the buyer paid, add-ons, and output GST — and what remains is what
+ * the seller is owed. Computing the seller's share independently and letting
+ * the two meet in the middle is how a rounding difference becomes an
+ * unbalanced entry that `assertBalanced` then refuses at checkout, turning a
+ * half-paisa into a failed order.
+ *
+ * 🛑 **Output GST is a LIABILITY, which is the entire point of the exercise.**
+ * `revenueRollup.totalRevenue` sums `order.totalPrice`, so today's "revenue"
+ * includes tax owed to the government and freight owed to a courier. Crediting
+ * 2200 here is what separates turnover from takings for the first time.
+ *
+ * 🛑 The debit is to GATEWAY RECEIVABLE, not Bank. Money captured is not
+ * money arrived — the settlement lands days later, net of MDR, and
+ * `settlementPosting` is what clears this account. Debiting Bank here would
+ * overstate cash by the whole float for the length of the settlement cycle.
+ */
+export function orderPlacedPosting(o) {
+    const commission = r2(o.platformFee ?? 0);
+    const commissionGst = r2(o.platformFeeGst ?? 0);
+    const shipping = r2(o.shippingFee ?? 0);
+    const addons = r2(o.addonFees ?? 0);
+    const outputGst = r2((o.gstAmount ?? 0) + commissionGst);
+    const sellerPayable = r2(o.totalPrice - commission - commissionGst - shipping - addons - (o.gstAmount ?? 0));
+    return {
+        entryDate: o.placedAt,
+        sourceEvent: "order-placed",
+        sourceId: o.orderId,
+        narration: `Order ${o.orderId}`,
+        lines: compact([
+            { accountCode: ACCOUNT.GATEWAY_RECEIVABLE, debit: r2(o.totalPrice), credit: 0, memo: "Captured, awaiting settlement" },
+            { accountCode: ACCOUNT.SELLER_PAYABLE, debit: 0, credit: sellerPayable, counterpartyId: o.storeId, memo: "Owed to the seller" },
+            { accountCode: ACCOUNT.OUTPUT_GST, debit: 0, credit: outputGst, memo: "Tax collected, owed to the government" },
+            { accountCode: ACCOUNT.COMMISSION_INCOME, debit: 0, credit: commission },
+            { accountCode: ACCOUNT.SHIPPING_RECOVERED, debit: 0, credit: shipping },
+            { accountCode: ACCOUNT.ADDON_INCOME, debit: 0, credit: addons },
+        ]),
+    };
+}
+/**
+ * A gateway settlement arriving in the bank.
+ *
+ * 🛑 `fee` here is the gateway's REAL charge from the settlement report, and
+ * it is NOT `PayoutDocument.gatewayFee` — that field is our own withholding
+ * against a seller's gross, a different number with a different meaning.
+ * Posting one as the other overstates our costs and understates what we
+ * withheld, in opposite directions, so the error compounds.
+ *
+ * 🛑 The GST on the fee is an ASSET (input credit), not an expense. Nothing
+ * in this codebase could receive input tax before Part 4, so this was simply
+ * unrecoverable — which is money, every month, that was never claimable.
+ */
+export function settlementPosting(s) {
+    const net = r2(s.gross - s.fee - s.feeGst);
+    return {
+        entryDate: s.settledAt,
+        sourceEvent: "settlement-ingest",
+        sourceId: s.settlementId,
+        narration: `Settlement ${s.settlementId}`,
+        lines: compact([
+            { accountCode: ACCOUNT.BANK, debit: net, credit: 0 },
+            { accountCode: ACCOUNT.GATEWAY_CHARGES, debit: r2(s.fee), credit: 0, memo: "MDR from the settlement report" },
+            { accountCode: ACCOUNT.INPUT_GST, debit: r2(s.feeGst), credit: 0, memo: "ITC on the gateway fee" },
+            { accountCode: ACCOUNT.GATEWAY_RECEIVABLE, debit: 0, credit: r2(s.gross) },
+        ]),
+    };
+}
+/**
+ * Paying a seller.
+ *
+ * Clears the payable raised at order time against real cash. Two legs and no
+ * income or expense — paying a debt is not a cost, and treating it as one
+ * double-counts every sale.
+ */
+export function payoutPosting(p) {
+    return {
+        entryDate: p.paidAt,
+        sourceEvent: "payout-paid",
+        sourceId: p.payoutId,
+        narration: `Payout ${p.payoutId} to ${p.storeId}`,
+        lines: [
+            { accountCode: ACCOUNT.SELLER_PAYABLE, debit: r2(p.amount), credit: 0, counterpartyId: p.storeId },
+            { accountCode: ACCOUNT.BANK, debit: 0, credit: r2(p.amount) },
+        ],
+    };
+}
+/**
+ * Which expense account each category posts to.
+ *
+ * 🛑 A `Record<ExpenseCategory, …>`, so adding a category is a COMPILE
+ * ERROR until someone says where it lands. The alternative — a lookup with
+ * a default — silently files every new kind of spend into "other", and
+ * "other" growing is indistinguishable from nobody having noticed.
+ *
+ * 🛑 `asset` maps to a BALANCE-SHEET account, not an expense, and that is
+ * the one entry here that changes a P&L. A camera bought for ₹80,000 is not
+ * an ₹80,000 trading loss in the month it was bought; depreciation is the
+ * CA's and this system deliberately does not attempt it.
+ */
+const EXPENSE_ACCOUNT = {
+    freight: ACCOUNT.FREIGHT_PAID,
+    "platform-software": "5500",
+    wages: "5400",
+    packaging: "5900",
+    asset: "1500",
+    other: "5900",
+};
+/**
+ * A bill.
+ *
+ * 🛑 The funding leg depends on whether it was PAID, and conflating the two
+ * is the commonest small-business bookkeeping error: crediting Bank for a
+ * bill not yet paid shows cash leaving that is still there, and crediting
+ * Accounts payable for one already settled leaves a debt that does not
+ * exist. Both balance; both are wrong; neither announces itself.
+ *
+ * 🛑 `inputGst` is DEBITED to an asset, never added to the cost. Expensing
+ * it is how input credit silently stops being claimable — the money is
+ * spent either way, but only one of the two gets it back.
+ */
+export function expensePosting(e) {
+    const net = r2(e.amount);
+    const gst = r2(e.inputGst ?? 0);
+    return {
+        entryDate: e.billDate,
+        sourceEvent: "expense-recorded",
+        sourceId: e.expenseId,
+        narration: `${e.vendorName} — ${e.category}`,
+        lines: compact([
+            { accountCode: EXPENSE_ACCOUNT[e.category], debit: net, credit: 0, ...(e.vendorId ? { counterpartyId: e.vendorId } : {}) },
+            { accountCode: ACCOUNT.INPUT_GST, debit: gst, credit: 0, memo: "ITC on this bill" },
+            {
+                accountCode: e.paid ? ACCOUNT.BANK : ACCOUNT.ACCOUNTS_PAYABLE,
+                debit: 0,
+                credit: r2(net + gst),
+                ...(e.vendorId ? { counterpartyId: e.vendorId } : {}),
+            },
+        ]),
+    };
+}
+/**
+ * A refund.
+ *
+ * 🛑 **A refund is NOT a negative sale, and that distinction is why the top
+ * line is currently wrong.** `revenueRollup` removes a fully-refunded order
+ * from its sum entirely and does not reduce it at all for a partial — so
+ * revenue silently rewrites itself retroactively, and no two runs of the same
+ * report over the same period agree.
+ *
+ * Here it is its own event with its own date: the sale stays in the month it
+ * happened, the refund lands in the month it happened, and both are visible.
+ *
+ * 🛑 It DEBITS output GST, reclaiming tax already declared. Omitting that leg
+ * means paying GST on money that was given back.
+ */
+export function refundPosting(r) {
+    const gst = r2(r.gstAmount ?? 0);
+    return {
+        entryDate: r.refundedAt,
+        sourceEvent: "order-refunded",
+        sourceId: r.refundId,
+        narration: `Refund ${r.refundId} on order ${r.orderId}`,
+        lines: compact([
+            { accountCode: ACCOUNT.COMMISSION_INCOME, debit: r2(r.amount - gst), credit: 0, memo: "Sale reversed" },
+            { accountCode: ACCOUNT.OUTPUT_GST, debit: gst, credit: 0, memo: "Tax reclaimed on the refunded amount" },
+            { accountCode: ACCOUNT.REFUNDS_PAYABLE, debit: 0, credit: r2(r.amount) },
+        ]),
+    };
+}

package/dist/_internal/shared/features/offers/coordination.d.ts

@@ -0,0 +1,122 @@
+/**
+ * Coordinated purchase — several people chipping in on one listing.
+ *
+ * ## 🛑 It is a SPECIALISED OFFER. Almost nothing here is new.
+ *
+ * Owner, 2026-10-22: *"it is not a variant, it is similar to an offer, which
+ * the seller enables on the listing, then the customer can coordinate on it,
+ * it is a specialized offer."*
+ *
+ * What that framing DELETES is the valuable part, because every one of these
+ * is a thing somebody would otherwise build:
+ *
+ * | Looks required | Actually |
+ * |---|---|
+ * | a 7th `OrderSourceContext` variant | none — it is `offer-accepted`, and the provenance card renders that branch already |
+ * | an `orderType` tab | none — the Offer-wins tab covers it |
+ * | a commit / settlement path | the offer lifecycle: `made → countered → accepted → paid`, with its chain fields, `checkoutDeadline` and lapse sweep |
+ * | a new money term | none — `unitPriceFor` honours `lockedPrice`, so tax, payout base, refund ceiling and the invoice all follow |
+ * | a cart lane | none — the existing `offer` lane, not locked, lapsing at `checkoutDeadline` |
+ *
+ * So this module holds exactly two things the offer did not already have: WHO
+ * is chipping in and how much, and WHERE each of them wants their parcel.
+ *
+ * The arithmetic is Part 2's and is not re-derived here — `resolveSplit` and
+ * `lockedPriceWithSurplus` live in `checkout/split.ts`, already committed,
+ * already carrying the rounding-remainder discipline and the
+ * goods-not-landed-cost argument that makes the surplus a correct charge.
+ */
+import type { SplitContribution } from "../../checkout/split";
+/**
+ * 🛑 FIVE, and the ceiling is about carrier quotes rather than taste.
+ *
+ * Each distinct destination needs its own `Shipment` and its own real
+ * `checkServiceability` call, so members multiply outbound API calls on a
+ * path a buyer is waiting on — against Rule #6's ~3-round-trip budget and a
+ * 10s function ceiling. Five is what fits with room for the rest of checkout.
+ *
+ * It is NOT a statement that six people may not club together; it is the
+ * number of parcels one offer can quote for synchronously. Raising it means
+ * moving quoting off the request path first.
+ */
+export declare const SHARED_PURCHASE_MAX_MEMBERS = 5;
+/**
+ * One contributor.
+ *
+ * ## 🛑 There is deliberately NO member NAME field
+ *
+ * 🛑 **CORRECTED — the reason first given here was false.** It said
+ * `encryptPiiFields` *"is a FLAT top-level loop that never descends into
+ * arrays"*, taken from CLAUDE.md and wrong: the function handles dotted paths
+ * and `array[].key` via `encryptInArray`, and `CONVERSATION_PII_FIELDS` ships
+ * `"lastMessage.body"` in production.
+ *
+ * The real argument is narrower and still decisive. The encryptor does not
+ * INFER — a field is protected only where it is NAMED, in notation matching
+ * the object the list is applied to. So a `name` here would need
+ * `"coordination.members[].name"` in `OFFER_PII_FIELDS`, and the near-miss
+ * `"name"` would read as covered in review while storing plaintext: both are
+ * `string`, and `Encrypted<string>` is erased at runtime.
+ *
+ * A member is a uid; names resolve from it at render time. That costs one
+ * lookup the renderer was making anyway and removes the field from the
+ * document entirely, which is stronger than encrypting it — there is nothing
+ * to classify, nothing to retain, and nothing to get the notation wrong for.
+ */
+export interface CoordinationMember extends SplitContribution {
+    /** Firebase Auth uid of the person chipping in. */
+    uid: string;
+    /**
+     * WHERE this member's parcel goes — an ID into `addresses`, never a copy.
+     *
+     * 🛑 **A reference, and this is not a style preference.** Copying the
+     * address inline would put a name, a phone number and a street into the
+     * offer document — a cart-adjacent record with no encryption story and no
+     * retention story, which is two new obligations to serve one picker.
+     *
+     * 🛑 **The id MUST be verified server-side to belong to the submitting
+     * buyer.** An id is guessable in a way an address is not: without the check,
+     * a member supplies any `addresses` document id and the parcel ships to a
+     * stranger's house at the coordinator's expense. See `assertOwnedAddresses`.
+     *
+     * Absent means "same as the coordinator's" — one parcel, which is the
+     * ordinary case and must not require every member to pick.
+     */
+    destinationAddressId?: string;
+}
+export interface OfferCoordination {
+    /**
+     * The coordinator is the offer's own `buyerUid` and is NOT repeated here.
+     *
+     * A second copy is a mirror, and a mirror drifts the first time a write
+     * path sets one and not the other (Root Cause #42). The coordinator is also
+     * a contributing member, so they appear in `members` like everyone else —
+     * what makes them the coordinator is owning the offer.
+     */
+    members: CoordinationMember[];
+    /**
+     * The landed cost the split was resolved against, snapshotted at the moment
+     * the coordinator committed.
+     *
+     * 🛑 Snapshotted, not recomputed. Shipping and fees move; a split agreed on
+     * Monday must still mean the same amounts on Friday, and recomputing would
+     * silently re-divide what people already agreed to pay.
+     */
+    landedCostAtSplit: number;
+    /** `contributed − landedCostAtSplit`, which rides on `lockedPrice`. */
+    surplus: number;
+}
+/**
+ * Is this set of members committable?
+ *
+ * Returns a MESSAGE rather than a boolean, for the same reason
+ * `rejectRateChange` does: "too many members" and "the split is short" need
+ * different corrections, and a bare `false` makes the form guess.
+ *
+ * 🛑 It does NOT check the split arithmetic — `resolveSplit` owns that, and
+ * duplicating the `Σ(contributions) ≥ landedCost` test here would be a second
+ * implementation of the one invariant Part 2 exists to hold.
+ */
+export declare function rejectCoordination(members: readonly CoordinationMember[]): string | null;
+/** The distinct destinations this offer will have to ship to. */
+export declare function destinationIds(members: readonly CoordinationMember[]): string[];

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

@@ -0,0 +1,80 @@
+/**
+ * Coordinated purchase — several people chipping in on one listing.
+ *
+ * ## 🛑 It is a SPECIALISED OFFER. Almost nothing here is new.
+ *
+ * Owner, 2026-10-22: *"it is not a variant, it is similar to an offer, which
+ * the seller enables on the listing, then the customer can coordinate on it,
+ * it is a specialized offer."*
+ *
+ * What that framing DELETES is the valuable part, because every one of these
+ * is a thing somebody would otherwise build:
+ *
+ * | Looks required | Actually |
+ * |---|---|
+ * | a 7th `OrderSourceContext` variant | none — it is `offer-accepted`, and the provenance card renders that branch already |
+ * | an `orderType` tab | none — the Offer-wins tab covers it |
+ * | a commit / settlement path | the offer lifecycle: `made → countered → accepted → paid`, with its chain fields, `checkoutDeadline` and lapse sweep |
+ * | a new money term | none — `unitPriceFor` honours `lockedPrice`, so tax, payout base, refund ceiling and the invoice all follow |
+ * | a cart lane | none — the existing `offer` lane, not locked, lapsing at `checkoutDeadline` |
+ *
+ * So this module holds exactly two things the offer did not already have: WHO
+ * is chipping in and how much, and WHERE each of them wants their parcel.
+ *
+ * The arithmetic is Part 2's and is not re-derived here — `resolveSplit` and
+ * `lockedPriceWithSurplus` live in `checkout/split.ts`, already committed,
+ * already carrying the rounding-remainder discipline and the
+ * goods-not-landed-cost argument that makes the surplus a correct charge.
+ */
+/**
+ * 🛑 FIVE, and the ceiling is about carrier quotes rather than taste.
+ *
+ * Each distinct destination needs its own `Shipment` and its own real
+ * `checkServiceability` call, so members multiply outbound API calls on a
+ * path a buyer is waiting on — against Rule #6's ~3-round-trip budget and a
+ * 10s function ceiling. Five is what fits with room for the rest of checkout.
+ *
+ * It is NOT a statement that six people may not club together; it is the
+ * number of parcels one offer can quote for synchronously. Raising it means
+ * moving quoting off the request path first.
+ */
+export const SHARED_PURCHASE_MAX_MEMBERS = 5;
+/**
+ * Is this set of members committable?
+ *
+ * Returns a MESSAGE rather than a boolean, for the same reason
+ * `rejectRateChange` does: "too many members" and "the split is short" need
+ * different corrections, and a bare `false` makes the form guess.
+ *
+ * 🛑 It does NOT check the split arithmetic — `resolveSplit` owns that, and
+ * duplicating the `Σ(contributions) ≥ landedCost` test here would be a second
+ * implementation of the one invariant Part 2 exists to hold.
+ */
+export function rejectCoordination(members) {
+    if (members.length === 0)
+        return "A coordinated purchase needs at least one contributor.";
+    if (members.length > SHARED_PURCHASE_MAX_MEMBERS) {
+        return `A coordinated purchase is limited to ${SHARED_PURCHASE_MAX_MEMBERS} contributors.`;
+    }
+    const uids = new Set(members.map((m) => m.uid));
+    if (uids.size !== members.length) {
+        /*
+         * One person twice is almost always a UI slip, and letting it through
+         * means their two rows are summed into one charge they did not agree to.
+         */
+        return "The same person appears more than once.";
+    }
+    for (const m of members) {
+        if (m.splitMode === "percent" && (m.percent == null || m.percent <= 0 || m.percent > 100)) {
+            return "Every percentage share must be between 0 and 100.";
+        }
+        if (m.splitMode === "amount" && (m.amount == null || m.amount <= 0)) {
+            return "Every fixed share must be more than zero.";
+        }
+    }
+    return null;
+}
+/** The distinct destinations this offer will have to ship to. */
+export function destinationIds(members) {
+    return [...new Set(members.map((m) => m.destinationAddressId).filter((id) => !!id))];
+}

package/dist/_internal/shared/features/orders/delivery-snapshot.d.ts

@@ -0,0 +1,114 @@
+/**
+ * The delivery snapshot — what the buyer chose, frozen at checkout.
+ *
+ * ## 🛑 Why the fields are flat and ugly
+ *
+ * 🛑 **CORRECTED.** This read "`encryptPiiFields` is a flat top-level loop
+ * that never descends", which is FALSE — it handles `a.b` and `a[].b` via
+ * `encryptInArray`, and `CONVERSATION_PII_FIELDS` ships `lastMessage.body`.
+ *
+ * What it does not do is INFER. A nested `deliveryAddress: {fullName, …}`
+ * is covered only if somebody writes `deliveryAddress.fullName` into
+ * `ORDER_PII_FIELDS`, and the near-miss `"fullName"` reads as covering it
+ * while storing plaintext.
+ *
+ * The decisive argument is not tidiness: **an unencrypted nested field looks
+ * identical to an encrypted one in every inspection** — both are `string`,
+ * and `Encrypted<string>` is erased at runtime. Flat keys cannot
+ * silently half-apply, because `ORDER_PII_FIELDS` either names them or does
+ * not and the audit can see which.
+ *
+ * ## 🛑 Four fields are deliberately NOT encrypted
+ *
+ * `city` / `state` / `pincode` / `country` decide tax and serviceability and
+ * must stay QUERYABLE. An encrypted pincode cannot be filtered, grouped into
+ * a courier manifest, or read by `placeOfSupply` without a decrypt per row.
+ * They are not PII in any useful sense on their own.
+ */
+import type { AddressPlain } from "../../../../features/addresses/schemas/firestore";
+/** The plaintext shape — what a caller builds and what the repository encrypts. */
+export interface DeliverySnapshot {
+    deliveryFullName: string;
+    deliveryPhone: string;
+    deliveryAddressLine1: string;
+    deliveryAddressLine2?: string;
+    deliveryLandmark?: string;
+    deliveryCity: string;
+    deliveryState: string;
+    deliveryPincode: string;
+    deliveryCountry: string;
+    deliveryAddressId: string;
+}
+/**
+ * Freeze a chosen address onto an order.
+ *
+ * 🛑 Takes the resolved DOCUMENT, never an id. Resolving here would mean a
+ * second read on the money path, and — worse — would invite a caller to pass
+ * an id it had not verified belongs to the buyer. The checkout already loads
+ * and ownership-checks the address; this just copies it.
+ *
+ * 🛑 Takes `AddressPlain`, not `AddressDocument`, and that is the point.
+ * `addressesRepository` encrypts `fullName` / `phone` / `addressLine1` on
+ * write, so a raw `findById` returns CIPHERTEXT — snapshotting it would put
+ * `enc:v1:…` on the invoice, and nothing would catch it because both are
+ * `string` at runtime and `Encrypted<string>` is erased.
+ *
+ * Demanding the revealed type makes the mistake a COMPILE error instead of a
+ * comment nobody reads. Call `addressesRepository.revealAddress(doc)` first.
+ */
+export declare function snapshotDeliveryAddress(address: AddressPlain): DeliverySnapshot;
+/** Everything a carrier booking needs, in `CreateShipmentInput`'s shape. */
+export interface DeliveryParty {
+    name: string;
+    phone: string;
+    addressLine1: string;
+    addressLine2?: string;
+    city: string;
+    state: string;
+    pincode: string;
+    country: string;
+}
+/**
+ * What the PARCEL goes to — the latest amendment, or the snapshot.
+ *
+ * 🛑 This is the one read that must NOT use the snapshot, and the invoice is
+ * the one that must. A buyer who corrects their address before dispatch
+ * expects the parcel to follow; the invoice records what was agreed when they
+ * paid. Collapsing the two is how a parcel goes to the old address or an
+ * invoice silently restates itself.
+ *
+ * Returns `null` rather than a partial party when a required field is
+ * missing — a booking built from blanks is accepted by the carrier and
+ * delivered nowhere.
+ */
+export declare function deliveryPartyFor(order: {
+    deliveryFullName?: string;
+    deliveryPhone?: string;
+    deliveryAddressLine1?: string;
+    deliveryAddressLine2?: string;
+    deliveryCity?: string;
+    deliveryState?: string;
+    deliveryPincode?: string;
+    deliveryCountry?: string;
+    deliveryAmendments?: Array<{
+        fullName: string;
+        phone: string;
+        addressLine1: string;
+        addressLine2?: string;
+        city: string;
+        state: string;
+        pincode: string;
+        country: string;
+    }>;
+}): DeliveryParty | null;
+/**
+ * The state the tax split was decided from.
+ *
+ * 🛑 Reads the SNAPSHOT, never an amendment. Place of supply is fixed at the
+ * time of supply; an address correction after the fact does not re-decide
+ * CGST/SGST versus IGST on an invoice that has been issued and may have been
+ * filed. That is the same forward-only rule `/admin/pricing` holds for rates.
+ */
+export declare function placeOfSupplyFrom(order: {
+    deliveryState?: string;
+}): string | undefined;

package/dist/_internal/shared/features/orders/delivery-snapshot.js

@@ -0,0 +1,116 @@
+/**
+ * The delivery snapshot — what the buyer chose, frozen at checkout.
+ *
+ * ## 🛑 Why the fields are flat and ugly
+ *
+ * 🛑 **CORRECTED.** This read "`encryptPiiFields` is a flat top-level loop
+ * that never descends", which is FALSE — it handles `a.b` and `a[].b` via
+ * `encryptInArray`, and `CONVERSATION_PII_FIELDS` ships `lastMessage.body`.
+ *
+ * What it does not do is INFER. A nested `deliveryAddress: {fullName, …}`
+ * is covered only if somebody writes `deliveryAddress.fullName` into
+ * `ORDER_PII_FIELDS`, and the near-miss `"fullName"` reads as covering it
+ * while storing plaintext.
+ *
+ * The decisive argument is not tidiness: **an unencrypted nested field looks
+ * identical to an encrypted one in every inspection** — both are `string`,
+ * and `Encrypted<string>` is erased at runtime. Flat keys cannot
+ * silently half-apply, because `ORDER_PII_FIELDS` either names them or does
+ * not and the audit can see which.
+ *
+ * ## 🛑 Four fields are deliberately NOT encrypted
+ *
+ * `city` / `state` / `pincode` / `country` decide tax and serviceability and
+ * must stay QUERYABLE. An encrypted pincode cannot be filtered, grouped into
+ * a courier manifest, or read by `placeOfSupply` without a decrypt per row.
+ * They are not PII in any useful sense on their own.
+ */
+/**
+ * Freeze a chosen address onto an order.
+ *
+ * 🛑 Takes the resolved DOCUMENT, never an id. Resolving here would mean a
+ * second read on the money path, and — worse — would invite a caller to pass
+ * an id it had not verified belongs to the buyer. The checkout already loads
+ * and ownership-checks the address; this just copies it.
+ *
+ * 🛑 Takes `AddressPlain`, not `AddressDocument`, and that is the point.
+ * `addressesRepository` encrypts `fullName` / `phone` / `addressLine1` on
+ * write, so a raw `findById` returns CIPHERTEXT — snapshotting it would put
+ * `enc:v1:…` on the invoice, and nothing would catch it because both are
+ * `string` at runtime and `Encrypted<string>` is erased.
+ *
+ * Demanding the revealed type makes the mistake a COMPILE error instead of a
+ * comment nobody reads. Call `addressesRepository.revealAddress(doc)` first.
+ */
+export function snapshotDeliveryAddress(address) {
+    return {
+        deliveryFullName: String(address.fullName ?? ""),
+        deliveryPhone: String(address.phone ?? ""),
+        deliveryAddressLine1: String(address.addressLine1 ?? ""),
+        ...(address.addressLine2 ? { deliveryAddressLine2: String(address.addressLine2) } : {}),
+        ...(address.landmark ? { deliveryLandmark: String(address.landmark) } : {}),
+        deliveryCity: address.city ?? "",
+        deliveryState: address.state ?? "",
+        deliveryPincode: address.postalCode ?? "",
+        deliveryCountry: address.country ?? "",
+        deliveryAddressId: address.id,
+    };
+}
+/**
+ * What the PARCEL goes to — the latest amendment, or the snapshot.
+ *
+ * 🛑 This is the one read that must NOT use the snapshot, and the invoice is
+ * the one that must. A buyer who corrects their address before dispatch
+ * expects the parcel to follow; the invoice records what was agreed when they
+ * paid. Collapsing the two is how a parcel goes to the old address or an
+ * invoice silently restates itself.
+ *
+ * Returns `null` rather than a partial party when a required field is
+ * missing — a booking built from blanks is accepted by the carrier and
+ * delivered nowhere.
+ */
+export function deliveryPartyFor(order) {
+    const latest = order.deliveryAmendments?.[order.deliveryAmendments.length - 1];
+    const party = latest
+        ? {
+            name: latest.fullName,
+            phone: latest.phone,
+            addressLine1: latest.addressLine1,
+            ...(latest.addressLine2 ? { addressLine2: latest.addressLine2 } : {}),
+            city: latest.city,
+            state: latest.state,
+            pincode: latest.pincode,
+            country: latest.country,
+        }
+        : {
+            name: order.deliveryFullName ?? "",
+            phone: order.deliveryPhone ?? "",
+            addressLine1: order.deliveryAddressLine1 ?? "",
+            ...(order.deliveryAddressLine2 ? { addressLine2: order.deliveryAddressLine2 } : {}),
+            city: order.deliveryCity ?? "",
+            state: order.deliveryState ?? "",
+            pincode: order.deliveryPincode ?? "",
+            country: order.deliveryCountry ?? "",
+        };
+    const required = [
+        party.name,
+        party.phone,
+        party.addressLine1,
+        party.city,
+        party.state,
+        party.pincode,
+        party.country,
+    ];
+    return required.every((v) => v.trim().length > 0) ? party : null;
+}
+/**
+ * The state the tax split was decided from.
+ *
+ * 🛑 Reads the SNAPSHOT, never an amendment. Place of supply is fixed at the
+ * time of supply; an address correction after the fact does not re-decide
+ * CGST/SGST versus IGST on an invoice that has been issued and may have been
+ * filed. That is the same forward-only rule `/admin/pricing` holds for rates.
+ */
+export function placeOfSupplyFrom(order) {
+    return order.deliveryState || undefined;
+}