@mohasinac/appkit 4.59.0 → 4.60.0

package/dist/features/orders/repository/orders.repository.d.ts

@@ -23,6 +23,33 @@ export interface OrderWriteContext {
      * the refund itself on the timeline rather than an array-length delta.
      */
     extraChanges?: Record<string, FieldChange>;
+    /**
+     * Bypass the status transition guard. **For the admin order editor only.**
+     *
+     * 🛑 The override is RECORDED in `statusHistory`, never silent — an override
+     * that leaves no trace is indistinguishable from the bug the guard exists to
+     * catch, so a later reader cannot tell a deliberate correction from a
+     * regression that slipped through.
+     *
+     * Do not pass this from a route that takes its status from a request body.
+     * Two of `updateStatus`'s four callers do exactly that (see
+     * `constants/transitions.ts`), and handing them the override would restore
+     * the hole the guard closes.
+     */
+    allowStatusOverride?: boolean;
+}
+/**
+ * An illegal status transition was refused.
+ *
+ * Its own class so the webhook ingest can distinguish "this event is LATE"
+ * from "this event is broken": a replayed `order.paid` arriving after the order
+ * shipped is not wrong, it is out of date, and the correct ack is 200 with a
+ * `status: "conflict"` row rather than a 500 asking the gateway to retry a
+ * regression it can never win.
+ */
+export declare class OrderStatusError extends Error {
+    readonly code = "ORDER_STATUS_TRANSITION_INVALID";
+    constructor(message: string);
 }
 declare class OrderRepository extends BaseRepository<OrderDocument> {
     constructor();
@@ -70,6 +97,19 @@ declare class OrderRepository extends BaseRepository<OrderDocument> {
      * cannot say who cancelled an order is a much weaker record.
      */
     private updateWithHistory;
+    /**
+     * Open/close this order's obligations to match what its own facts imply.
+     *
+     * Public so the obligation sweep can re-run it after acting, and so a
+     * backfill can reconcile existing orders without a synthetic write.
+     */
+    reconcileObligationsFor(order: OrderDocument, 
+    /**
+     * The pre-write document, so the close set is `was-open MINUS is-open`
+     * rather than every kind that is not open. Omit ONLY for a deliberate
+     * backfill — see `reconcileObligations`' own 🛑 on the cost.
+     */
+    previous?: OrderDocument | null): Promise<void>;
     updateStatus(orderId: string, status: OrderStatus, additionalData?: Partial<OrderDocument>, ctx?: OrderWriteContext): Promise<OrderDocument>;
     assignWorker(orderId: string, workerId: string): Promise<OrderDocument>;
     unassignWorker(orderId: string): Promise<OrderDocument>;
@@ -307,6 +347,72 @@ declare class OrderRepository extends BaseRepository<OrderDocument> {
      * Append one refund event to the order and mark it non-contestable.
      * If `becomeRefunded` is true, also transitions the order status to "refunded".
      */
+    /**
+     * PHASE A — reserve a refund slot atomically, enforcing the cumulative cap.
+     *
+     * 🛑 WHY A TRANSACTION, AND WHY NOT `arrayUnion` (D1 + D6).
+     *
+     * `postRefundEvent` below does `findById` then `[...existing, event]` — a
+     * read-then-write. Two concurrent refunds both read the same `existing` and
+     * the second write **overwrites the first's append, losing an event
+     * entirely**. And the cap check lived in the ACTION, outside any
+     * transaction, so it was TOCTOU: two requests could each see a clear cap and
+     * both proceed. Combined with the cap comparing against `totalPrice` rather
+     * than the remaining balance (D1), ₹500 and another ₹500 both passed on a
+     * ₹600 order — **two real gateway refunds, both successful.**
+     *
+     * `arrayUnion` is the obvious fix and is WRONG here on three counts: it
+     * cannot evaluate the cumulative cap (the whole point), it cannot build the
+     * `withHistory` entry, and it dedupes by DEEP EQUALITY — so two legitimate
+     * identical ₹100 partial refunds would silently merge into one.
+     *
+     * The entry lands with `status: "reserved"`, which `committedRefundTotal`
+     * counts. That is what makes the reservation real: a concurrent request sees
+     * the pending amount and cannot refund against a balance already spoken for.
+     * A later `failed` settlement releases it simply by being skipped.
+     *
+     * Throws rather than returning a flag — a caller that ignores a boolean here
+     * calls the gateway anyway, which is the failure this prevents.
+     */
+    reserveRefund(orderId: string, event: OrderRefundEvent, 
+    /** Resolved by the caller from `refundCapacity`; see `refundable-base.ts`. */
+    opts: {
+        refundableBase: number;
+        epsilon: number;
+    }): Promise<void>;
+    /**
+     * PHASE B — settle a reserved refund: `processed` with the gateway's id, or
+     * `failed`, which releases the reservation.
+     *
+     * Runs AFTER the provider call, which must sit outside any transaction: a
+     * Firestore transaction retries its body, and a retried network call is a
+     * second refund. This is the only ordering in which "money left the gateway
+     * and we have no record of it" is impossible — a crash between the provider
+     * call and this write leaves a `reserved` entry and an unsettled claim,
+     * which is exactly the shape Phase 4's reconciler looks for.
+     *
+     * Goes through `updateWithHistory`, so the TIMELINE entry is written at
+     * settlement rather than at reservation. That is deliberate: the history
+     * should record money that moved, not an intent that may yet fail.
+     */
+    settleRefund(orderId: string, refundId: string, outcome: {
+        status: "processed";
+        gatewayRefundId?: string;
+        gateway?: string;
+        providerFields?: Record<string, string>;
+    } | {
+        status: "failed";
+        failureReason?: string;
+    }, becomeRefunded?: boolean, ctx?: OrderWriteContext): Promise<OrderDocument>;
+    /**
+     * 🛑 LEGACY — prefer `reserveRefund` + `settleRefund`.
+     *
+     * Kept because several non-gateway paths (manual refunds with no provider
+     * call, and the out-of-stock auto-refund) post a single terminal event with
+     * nothing to reserve against. Its read-then-write append is still a lost-
+     * update risk under concurrency (D6); do not route a new gateway refund
+     * through it.
+     */
     postRefundEvent(orderId: string, event: OrderRefundEvent, becomeRefunded?: boolean, ctx?: OrderWriteContext): Promise<OrderDocument>;
     /** Fetch all orders sharing a paymentBatchId (for sibling-orders display). */
     findByPaymentBatchId(batchId: string): Promise<OrderDocument[]>;
@@ -392,11 +498,6 @@ declare class OrderRepository extends BaseRepository<OrderDocument> {
      * once it's delivered (a seller-enabled `allowShipBeforeEmiComplete` item
      * can be delivered long before EMI collection finishes).
      */
-    getEligibleForPayoutSweep(): Promise<Array<{
-        id: string;
-        ref: DocumentReference;
-        data: OrderDocument;
-    }>>;
     /**
      * Cloud Functions: find auto-payout eligible delivered orders older than windowDays business days.
      * @param windowDays - number of business days since delivery
@@ -404,7 +505,9 @@ declare class OrderRepository extends BaseRepository<OrderDocument> {
      *
      * See {@link getEligibleForPayoutSweep} for the EMI-incomplete exclusion rationale.
      */
-    getEligibleAutomatic(cutoff: Date): Promise<Array<{
+    getEligibleAutomatic(cutoff: Date, opts?: {
+        onWarn?: (msg: string, meta?: Record<string, JsonValue>) => void;
+    }): Promise<Array<{
         id: string;
         ref: DocumentReference;
         data: OrderDocument;