@mohasinac/appkit 4.62.0 → 4.63.0

package/dist/_internal/shared/features/ledger/rules.d.ts

@@ -0,0 +1,170 @@
+/**
+ * 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.
+ */
+import type { PostingInput } from "./posting";
+import type { ExpenseCategory } from "../../../../features/ledger/schemas/expenses";
+/** The accounts these rules post to. Codes match `chartOfAccountsSeedData`. */
+export declare const ACCOUNT: {
+    readonly BANK: "1100";
+    readonly COURIER_FLOAT: "1150";
+    readonly GATEWAY_RECEIVABLE: "1200";
+    readonly INPUT_GST: "1300";
+    readonly SELLER_PAYABLE: "2100";
+    readonly ACCOUNTS_PAYABLE: "2300";
+    readonly OUTPUT_GST: "2200";
+    readonly BUYER_DEPOSITS: "2400";
+    readonly REFUNDS_PAYABLE: "2500";
+    readonly OPENING_EQUITY: "3900";
+    readonly COMMISSION_INCOME: "4100";
+    readonly SHIPPING_RECOVERED: "4200";
+    readonly ADDON_INCOME: "4300";
+    readonly GATEWAY_CHARGES: "5100";
+    readonly FREIGHT_PAID: "5200";
+};
+export interface OrderPostingInput {
+    orderId: string;
+    storeId: string;
+    placedAt: Date;
+    /** What the buyer paid in total, GST included. */
+    totalPrice: number;
+    /** Product GST inside `totalPrice`. */
+    gstAmount?: number;
+    /** Our commission, and the GST we charge on it. */
+    platformFee?: number;
+    platformFeeGst?: number;
+    /** What the buyer paid for delivery, inside `totalPrice`. */
+    shippingFee?: number;
+    /** Gift wrap, protection, WhatsApp — inside `totalPrice`. */
+    addonFees?: number;
+}
+/**
+ * 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 declare function orderPlacedPosting(o: OrderPostingInput): PostingInput;
+export interface SettlementPostingInput {
+    settlementId: string;
+    settledAt: Date;
+    /** Gross captured in this settlement, matching what was debited to 1200. */
+    gross: number;
+    /** The gateway's real MDR for it. */
+    fee: number;
+    /** GST on that fee — an INPUT credit, not a cost. */
+    feeGst: number;
+}
+/**
+ * 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 declare function settlementPosting(s: SettlementPostingInput): PostingInput;
+export interface PayoutPostingInput {
+    payoutId: string;
+    storeId: string;
+    paidAt: Date;
+    amount: number;
+}
+/**
+ * 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 declare function payoutPosting(p: PayoutPostingInput): PostingInput;
+export interface ExpensePostingInput {
+    expenseId: string;
+    vendorId?: string;
+    vendorName: string;
+    category: ExpenseCategory;
+    billDate: Date;
+    amount: number;
+    inputGst?: number;
+    /** Paid outright, or on credit? Decides the funding leg. */
+    paid: boolean;
+}
+/**
+ * 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 declare function expensePosting(e: ExpensePostingInput): PostingInput;
+export interface RefundPostingInput {
+    orderId: string;
+    refundId: string;
+    refundedAt: Date;
+    amount: number;
+    /** The product GST inside the refunded amount, which is reclaimable. */
+    gstAmount?: number;
+}
+/**
+ * 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 declare function refundPosting(r: RefundPostingInput): PostingInput;

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))];
+}