@mohasinac/appkit 4.62.0 → 4.63.0

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

package/dist/_internal/shared/features/orders/dispute-reasons.d.ts

@@ -0,0 +1,113 @@
+/**
+ * Dispute KINDS and the gate each one must pass.
+ *
+ * ## Why the kind is closed and the reason list is not
+ *
+ * The owner's two rules are policy:
+ *
+ * > An item dispute can only be raised after the order was received. A
+ * > "not reached" dispute is allowed once the ETD is more than 3 days past.
+ *
+ * A gate cannot branch on a user-created string. `return-reasons.ts` already
+ * makes this argument in its own header — *"'No returns, unless the buyer
+ * didn't get what they paid for' is not a policy that can be enforced against
+ * a free-text box: it needs a machine-readable statement of what went
+ * wrong"* — and it applies with more force here, because these two gates are
+ * MUTUALLY EXCLUSIVE.
+ *
+ * So there are two levels:
+ *
+ * 1. **`DisputeKind` — closed, here, two values.** It picks the gate.
+ * 2. **`disputeReasons` — a staff-creatable Firestore collection.** Every row
+ *    carries a `kind`, so a new reason inherits an existing gate and cannot
+ *    invent one. That list is for triage and analytics, never for policy.
+ *
+ * ## What this replaces
+ *
+ * `raiseOrderDisputeAction` took `reason: string` and checked only that it was
+ * non-empty. So today a buyer can file "it never arrived" on an order that was
+ * delivered last week, and "it arrived damaged" on one still in transit — both
+ * nonsense, both accepted, and both raising a `severity: "error"` fraud-category
+ * admin alert. The gate is the point of this file.
+ */
+export declare const DISPUTE_KIND: readonly ["item", "not_reached"];
+export type DisputeKind = (typeof DISPUTE_KIND)[number];
+/**
+ * 🛑 `Record<DisputeKind, string>`, so a third kind is a COMPILE error here
+ * rather than a dispute that renders `undefined` and passes no gate.
+ */
+export declare const DISPUTE_KIND_LABEL: Record<DisputeKind, string>;
+export declare function isDisputeKind(value: unknown): value is DisputeKind;
+/**
+ * How long after dispatch a parcel is ASSUMED to have been deliverable, when
+ * the courier gave us no estimate.
+ *
+ * 🛑 This exists so the `not_reached` gate is reachable AT ALL. There is no
+ * courier ETD on an order today: nothing platform-books (`createShipment` has
+ * zero callers), and a self-shipping seller types a tracking number with no
+ * estimate attached. Gate solely on a stored ETD and no buyer could ever file
+ * a non-delivery dispute — a gate nobody can pass is the same as no feature.
+ *
+ * Published through `PublishedValueKey` so the policy page and this gate
+ * cannot disagree (Phase 9).
+ */
+export declare const DISPUTE_TRANSIT_WINDOW_DAYS = 7;
+/**
+ * The owner's "more than 3 days" grace, measured from the ETD.
+ *
+ * Separate from the transit window on purpose: one is "when should it have
+ * arrived", the other is "how long after that before we believe it is lost".
+ * Folding them into a single 10 would make neither number explicable on a
+ * policy page.
+ */
+export declare const DISPUTE_NOT_REACHED_GRACE_DAYS = 3;
+/** Fields the gates read. Narrow, so a caller need not hold a whole order. */
+export interface DisputeGateOrder {
+    deliveryDate?: Date | null;
+    completedAt?: Date | null;
+    shippingDate?: Date | null;
+    estimatedDeliveryDate?: Date | null;
+}
+export type DisputeGateResult = {
+    allowed: true;
+}
+/** `message` is buyer-facing and must name the next action, not just refuse. */
+ | {
+    allowed: false;
+    message: string;
+};
+/**
+ * The effective ETD, and WHY we think so.
+ *
+ * Exported because the buyer-facing form needs to show the date they can file
+ * from — telling someone "not yet" without saying when is a dead end.
+ */
+export declare function resolveDisputeEtd(order: DisputeGateOrder, transitWindowDays?: number): {
+    etd: Date;
+    source: "courier" | "assumed";
+} | null;
+/** The date from which a `not_reached` dispute becomes filable. */
+export declare function disputeNotReachedFilableFrom(order: DisputeGateOrder, graceDays?: number): Date | null;
+/**
+ * 🛑 `Record<DisputeKind, …>`. A third kind cannot be added without deciding
+ * what gates it — which is the whole reason the kind is closed.
+ */
+export declare const DISPUTE_GATE: Record<DisputeKind, (order: DisputeGateOrder, now?: Date) => DisputeGateResult>;
+/**
+ * Convenience wrapper so callers do not index the record by hand.
+ *
+ * 🛑 Takes the NARROW `DisputeGateOrder`, and an `OrderDocument` satisfies it
+ * structurally — so no adapter is needed and none should be added.
+ *
+ * A first draft had a `toDisputeGateOrder(order: OrderDocument)` helper, which
+ * meant this module imported the order schema while the order schema imports
+ * `DisputeKind` from here. That cycle is type-only and therefore erased, so it
+ * would have compiled and run — but it is also entirely avoidable, and a
+ * module that defines a policy should not depend on the document the policy is
+ * applied to. `return-reasons.ts` beside it has no imports at all for the same
+ * reason.
+ *
+ * Nothing leaks by passing the whole order in: what crosses back out is a
+ * `DisputeGateResult`, never the document (Root Cause #70).
+ */
+export declare function checkDisputeGate(kind: DisputeKind, order: DisputeGateOrder, now?: Date): DisputeGateResult;

package/dist/_internal/shared/features/orders/dispute-reasons.js

@@ -0,0 +1,181 @@
+/**
+ * Dispute KINDS and the gate each one must pass.
+ *
+ * ## Why the kind is closed and the reason list is not
+ *
+ * The owner's two rules are policy:
+ *
+ * > An item dispute can only be raised after the order was received. A
+ * > "not reached" dispute is allowed once the ETD is more than 3 days past.
+ *
+ * A gate cannot branch on a user-created string. `return-reasons.ts` already
+ * makes this argument in its own header — *"'No returns, unless the buyer
+ * didn't get what they paid for' is not a policy that can be enforced against
+ * a free-text box: it needs a machine-readable statement of what went
+ * wrong"* — and it applies with more force here, because these two gates are
+ * MUTUALLY EXCLUSIVE.
+ *
+ * So there are two levels:
+ *
+ * 1. **`DisputeKind` — closed, here, two values.** It picks the gate.
+ * 2. **`disputeReasons` — a staff-creatable Firestore collection.** Every row
+ *    carries a `kind`, so a new reason inherits an existing gate and cannot
+ *    invent one. That list is for triage and analytics, never for policy.
+ *
+ * ## What this replaces
+ *
+ * `raiseOrderDisputeAction` took `reason: string` and checked only that it was
+ * non-empty. So today a buyer can file "it never arrived" on an order that was
+ * delivered last week, and "it arrived damaged" on one still in transit — both
+ * nonsense, both accepted, and both raising a `severity: "error"` fraud-category
+ * admin alert. The gate is the point of this file.
+ */
+export const DISPUTE_KIND = ["item", "not_reached"];
+/**
+ * 🛑 `Record<DisputeKind, string>`, so a third kind is a COMPILE error here
+ * rather than a dispute that renders `undefined` and passes no gate.
+ */
+export const DISPUTE_KIND_LABEL = {
+    item: "There's a problem with what I received",
+    not_reached: "My order hasn't arrived",
+};
+export function isDisputeKind(value) {
+    return typeof value === "string" && DISPUTE_KIND.includes(value);
+}
+/**
+ * How long after dispatch a parcel is ASSUMED to have been deliverable, when
+ * the courier gave us no estimate.
+ *
+ * 🛑 This exists so the `not_reached` gate is reachable AT ALL. There is no
+ * courier ETD on an order today: nothing platform-books (`createShipment` has
+ * zero callers), and a self-shipping seller types a tracking number with no
+ * estimate attached. Gate solely on a stored ETD and no buyer could ever file
+ * a non-delivery dispute — a gate nobody can pass is the same as no feature.
+ *
+ * Published through `PublishedValueKey` so the policy page and this gate
+ * cannot disagree (Phase 9).
+ */
+export const DISPUTE_TRANSIT_WINDOW_DAYS = 7;
+/**
+ * The owner's "more than 3 days" grace, measured from the ETD.
+ *
+ * Separate from the transit window on purpose: one is "when should it have
+ * arrived", the other is "how long after that before we believe it is lost".
+ * Folding them into a single 10 would make neither number explicable on a
+ * policy page.
+ */
+export const DISPUTE_NOT_REACHED_GRACE_DAYS = 3;
+const DAY_MS = 24 * 60 * 60 * 1000;
+function asDate(v) {
+    if (!v)
+        return null;
+    const d = v instanceof Date ? v : new Date(v);
+    return Number.isFinite(d.getTime()) ? d : null;
+}
+function fmt(d) {
+    return d.toLocaleDateString("en-IN", { day: "numeric", month: "short", year: "numeric" });
+}
+/**
+ * The effective ETD, and WHY we think so.
+ *
+ * Exported because the buyer-facing form needs to show the date they can file
+ * from — telling someone "not yet" without saying when is a dead end.
+ */
+export function resolveDisputeEtd(order, transitWindowDays = DISPUTE_TRANSIT_WINDOW_DAYS) {
+    const courier = asDate(order.estimatedDeliveryDate);
+    if (courier)
+        return { etd: courier, source: "courier" };
+    const shipped = asDate(order.shippingDate);
+    if (shipped) {
+        return { etd: new Date(shipped.getTime() + transitWindowDays * DAY_MS), source: "assumed" };
+    }
+    return null;
+}
+/** The date from which a `not_reached` dispute becomes filable. */
+export function disputeNotReachedFilableFrom(order, graceDays = DISPUTE_NOT_REACHED_GRACE_DAYS) {
+    const resolved = resolveDisputeEtd(order);
+    if (!resolved)
+        return null;
+    return new Date(resolved.etd.getTime() + graceDays * DAY_MS);
+}
+/**
+ * 🛑 `Record<DisputeKind, …>`. A third kind cannot be added without deciding
+ * what gates it — which is the whole reason the kind is closed.
+ */
+export const DISPUTE_GATE = {
+    /**
+     * You cannot judge an item you have not seen.
+     *
+     * `completedAt` counts as well as `deliveryDate`: a buyer who pressed "Mark
+     * complete" has told us they received it, and refusing them because no
+     * courier scan landed would be refusing the more reliable signal of the two.
+     */
+    item: (order) => {
+        if (asDate(order.deliveryDate) || asDate(order.completedAt))
+            return { allowed: true };
+        return {
+            allowed: false,
+            message: "You can report a problem with an item once it arrives. If it hasn't arrived, raise a delivery issue instead.",
+        };
+    },
+    /**
+     * Only valid BEFORE receipt, and only once the parcel is genuinely late.
+     *
+     * Three refusals, each pointing somewhere:
+     *  - delivered → the wrong kind; offer the item route or a return.
+     *  - never dispatched → not a courier problem at all. That is the
+     *    `seller-dispatch` obligation's job, and it is already running.
+     *  - too early → say the date, not just "not yet".
+     */
+    not_reached: (order, now = new Date()) => {
+        const delivered = asDate(order.deliveryDate);
+        if (delivered) {
+            return {
+                allowed: false,
+                message: `This order was marked delivered on ${fmt(delivered)}. If something is wrong with what arrived, report a problem with the item instead.`,
+            };
+        }
+        if (!asDate(order.shippingDate) && !asDate(order.estimatedDeliveryDate)) {
+            return {
+                allowed: false,
+                message: "This order hasn't been dispatched yet, so there's nothing in transit to chase. We already track late dispatch and will act on it without you needing to do anything.",
+            };
+        }
+        const filableFrom = disputeNotReachedFilableFrom(order);
+        if (!filableFrom) {
+            // Unreachable given the check above; kept rather than asserted, because
+            // a thrown non-null assertion here would be a 500 on a buyer action.
+            return {
+                allowed: false,
+                message: "We can't work out an expected delivery date for this order yet. Contact support.",
+            };
+        }
+        if (now.getTime() < filableFrom.getTime()) {
+            return {
+                allowed: false,
+                message: `It's still within the expected delivery window. If it hasn't arrived by ${fmt(filableFrom)}, you can raise a delivery issue then.`,
+            };
+        }
+        return { allowed: true };
+    },
+};
+/**
+ * Convenience wrapper so callers do not index the record by hand.
+ *
+ * 🛑 Takes the NARROW `DisputeGateOrder`, and an `OrderDocument` satisfies it
+ * structurally — so no adapter is needed and none should be added.
+ *
+ * A first draft had a `toDisputeGateOrder(order: OrderDocument)` helper, which
+ * meant this module imported the order schema while the order schema imports
+ * `DisputeKind` from here. That cycle is type-only and therefore erased, so it
+ * would have compiled and run — but it is also entirely avoidable, and a
+ * module that defines a policy should not depend on the document the policy is
+ * applied to. `return-reasons.ts` beside it has no imports at all for the same
+ * reason.
+ *
+ * Nothing leaks by passing the whole order in: what crosses back out is a
+ * `DisputeGateResult`, never the document (Root Cause #70).
+ */
+export function checkDisputeGate(kind, order, now) {
+    return DISPUTE_GATE[kind](order, now);
+}

package/dist/_internal/shared/features/orders/refund-copy.d.ts

@@ -35,7 +35,7 @@ export declare const REFUND_COPY: {
         readonly reasonSelectPlaceholder: "Choose a reason";
         readonly reasonNoteLabel: "Anything else we should know? (optional)";
         readonly alreadyRefundedMessage: "A refund has already been processed on this order. No further disputes or refund requests can be filed.";
-        readonly acknowledgments: readonly ["I understand this refund request, once approved, permanently removes my ability to file any dispute or RMA claim on this order.", "I confirm the item has not been used, worn, or damaged by me, and I am returning it in original condition (if a return is required).", "I understand the refund amount may take 5–7 business days to reflect and that platform fees may be non-recoverable."];
+        readonly acknowledgments: readonly ["I understand this refund request, once approved, permanently removes my ability to file any dispute or RMA claim on this order.", "I confirm the item has not been used, worn, or damaged by me, and I am returning it in original condition (if a return is required).", "I understand the refund amount may take {{refundBusinessDaysMin}}–{{refundBusinessDaysMax}} business days to reflect and that platform fees may be non-recoverable."];
     };
     readonly siblingPayments: {
         readonly heading: (count: number) => string;

package/dist/_internal/shared/features/orders/refund-copy.js

@@ -38,7 +38,24 @@ export const REFUND_COPY = {
         acknowledgments: [
             "I understand this refund request, once approved, permanently removes my ability to file any dispute or RMA claim on this order.",
             "I confirm the item has not been used, worn, or damaged by me, and I am returning it in original condition (if a return is required).",
-            "I understand the refund amount may take 5–7 business days to reflect and that platform fees may be non-recoverable.",
+            /*
+             * 🛑 Phase 9 — TOKENS, resolved by `resolvePublishedCopy` at render.
+             *
+             * This literal was one of the three contradicting owners of the refund
+             * timeline: "5–7 business days" here, "5–7 business days via Razorpay"
+             * on the policy page (naming a gateway that was not even the one in
+             * use), and "3–5 business days" in the FAQ. Three statements of one
+             * fact, no reconciliation, and the FAQ one admin-editable so it could
+             * drift further after deployment.
+             *
+             * The caller renders this through `resolvePublishedCopy`, so the number
+             * now has exactly one definition. Note this string is an
+             * ACKNOWLEDGEMENT the buyer ticks — a token left unresolved here would
+             * appear in something they are agreeing to, which is the strongest
+             * possible argument for the unknown-token rule leaving `{{…}}` visible
+             * rather than blanking it.
+             */
+            "I understand the refund amount may take {{refundBusinessDaysMin}}–{{refundBusinessDaysMax}} business days to reflect and that platform fees may be non-recoverable.",
         ],
     },
     siblingPayments: {

package/dist/_internal/shared/features/payouts/pay-period.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Pay periods for employee payouts — ONE resolver, two cadences.
+ *
+ * ## 🛑 Why this is a module and not a ternary at each call site
+ *
+ * Two cadences means two period-boundary rules, and a reopened ticket can
+ * straddle a boundary differently per employee: the same reopen is inside the
+ * period for a monthly payee and across it for a weekly one. A branch written
+ * at each call site is two chances per site to disagree about where a week
+ * starts — and the symptom is a payslip that is quietly short, which nobody
+ * reports as a bug because nobody has the other number to compare it to.
+ *
+ * So the period is resolved once, from a date and a cadence, and every caller
+ * takes the pair it returns.
+ *
+ * ## 🛑 Go-forward, no clawback
+ *
+ * A payslip is final once issued. If a ticket is reopened after the period it
+ * was paid in has closed, the money is not recovered and the period is not
+ * recomputed — the ticket simply does not count again in the period where it
+ * is next resolved. Recomputing a closed period would mean an employee's pay
+ * changing after they were told what it was, which is a worse failure than
+ * occasionally paying for work that was later reopened.
+ */
+export type PayCadence = "weekly" | "monthly";
+export declare const PAY_CADENCE_VALUES: readonly ["weekly", "monthly"];
+export interface PayPeriod {
+    start: Date;
+    /** EXCLUSIVE. See the note below — this is the half-open convention. */
+    end: Date;
+    cadence: PayCadence;
+}
+/**
+ * The period containing `when`.
+ *
+ * ## 🛑 Half-open: `start <= t < end`
+ *
+ * An inclusive end means the last millisecond of a period is also the first of
+ * the next, so a ticket resolved exactly at midnight is counted twice — paid
+ * in two periods — or, if one side uses `<` and the other `<=`, in neither.
+ * Half-open makes both impossible by construction, and every consumer must
+ * compare with `< end`, never `<= end`.
+ *
+ * ## 🛑 Weeks start MONDAY
+ *
+ * `Date.getDay()` returns 0 for Sunday, so the naive `d - d.getDay()` produces
+ * a Sunday-start week. India's working week is Monday–Saturday and a support
+ * rota is read that way, so a Sunday boundary would split every weekend across
+ * two payslips. The `(day + 6) % 7` shift is what makes Monday day 0.
+ *
+ * ## 🛑 Local midnight, not UTC
+ *
+ * Wages are a human-calendar concept: an employee's Monday is their Monday.
+ * `setHours(0,0,0,0)` is local, and the server runs in the deployment's zone —
+ * which is why `periodLabel` renders the same boundary a payslip prints.
+ */
+export declare function payPeriodFor(when: Date, cadence: PayCadence): PayPeriod;
+/** The period immediately before the one containing `when`. */
+export declare function previousPayPeriod(when: Date, cadence: PayCadence): PayPeriod;
+/** Half-open membership. The ONLY correct way to ask; see `payPeriodFor`. */
+export declare function isWithinPeriod(t: Date, period: PayPeriod): boolean;
+/**
+ * What a payslip prints.
+ *
+ * 🛑 Renders the end as the LAST DAY INSIDE the period, not the exclusive
+ * boundary. "1 Jan – 1 Feb" on a January payslip reads as an overlap with
+ * February's and invites someone to "fix" the half-open convention that makes
+ * the arithmetic correct.
+ */
+export declare function periodLabel(period: PayPeriod, locale?: string): string;
+/**
+ * The tickets a period actually pays for.
+ *
+ * 🛑 **Tickets STILL RESOLVED at period end — not tickets closed during it.**
+ * Paying per ticket closed rewards closing rather than resolving: close it,
+ * let the buyer reopen it, close it again, and it pays twice. So a ticket
+ * counts only when it is resolved, was resolved inside the period, and is
+ * still resolved when the period ends.
+ *
+ * A reopen therefore removes the ticket from that period even if the reopen
+ * happened after the resolution — which is why this takes the whole ticket
+ * rather than a timestamp, and why `resolvedBy` must be CLEARED on reopen.
+ */
+export interface PayableTicket {
+    id: string;
+    resolvedAt?: Date | null;
+    resolvedBy?: string | null;
+    /** The live status, read at the moment the period is computed. */
+    isResolved: boolean;
+}
+export declare function resolvedTicketsForPeriod(tickets: readonly PayableTicket[], employeeUid: string, period: PayPeriod): string[];