@mohasinac/appkit 4.61.0 → 4.62.1

package/dist/_internal/server/jobs/core/runJobOnce.js

@@ -0,0 +1,195 @@
+/**
+ * Run ONE attempt of a job, and decide what happens next (Phase 8).
+ *
+ * ## 🛑 ONE dispatch path, shared by the trigger and the retry sweep
+ *
+ * `handleJobCreated` is the `jobs/{jobId}` create trigger; `runDueJobRetries`
+ * is the sweep that picks up scheduled retries. Both call THIS, so there is
+ * exactly one place that knows how to run a job, classify its failure and
+ * schedule the next attempt. Two dispatch paths would drift the first time one
+ * of them learned something — which is the shape of every defect in this
+ * plan's § "Recurrent Root Cause Patterns" that begins "a fix applied to the
+ * route but never back-ported".
+ *
+ * ## 🛑 A retry is a NEW DOCUMENT
+ *
+ * `onJobCreated` fires on CREATE. Re-running a job by flipping its status back
+ * to `pending` would never wake the trigger, so the job would sit `pending`
+ * forever looking scheduled — a stall that reads as "queued". So a retry is a
+ * fresh `jobs` document carrying `attempt + 1`, `parentJobId` and a
+ * `nextAttemptAt`, and the sweep is what runs it when due.
+ *
+ * ## What is retryable
+ *
+ * `mapToHttpError(err).status >= 500`. Reused rather than invented: that
+ * function already encodes "is this our fault or the caller's" for every error
+ * class in the codebase, and a second classification would answer differently
+ * the first time either changed.
+ *
+ * A 4xx is terminal IMMEDIATELY — no backoff, no attempts burned. A validation
+ * failure does not become valid by waiting, and retrying it three times over
+ * 35 minutes just delays the case by 35 minutes.
+ */
+import { normalizeError } from "../../../../errors/normalize.js";
+import { mapToHttpError } from "../../../../errors/error-mapping.js";
+import { jobsRepository } from "../../../../repositories/index.js";
+import { paymentCasesRepository } from "../../../../features/payment-cases/repository/payment-cases.repository.js";
+import { getAdminRealtimeDb } from "../../../../providers/db-firebase/index.js";
+import { RTDB_PATHS } from "../../../../providers/db-firebase/rtdb-paths.js";
+import { JOB_BACKOFF_MS, JOB_MAX_ATTEMPTS, } from "../../../../features/jobs/schemas/firestore.js";
+import { JOB_RUNNERS } from "./jobRunners.js";
+async function pingBulkEvent(jobId, payload, ctx) {
+    try {
+        await getAdminRealtimeDb()
+            .ref(`${RTDB_PATHS.BULK_EVENTS}/${jobId}`)
+            .set({ ...payload, updatedAt: Date.now() });
+    }
+    catch (err) {
+        void normalizeError(err);
+        ctx.logger.warn("runJobOnce: RTDB ping failed (non-fatal)", {
+            jobId,
+            error: err instanceof Error ? err.message : String(err),
+        });
+    }
+}
+/**
+ * The delay before the next attempt.
+ *
+ * 🛑 Clamped to the LAST element rather than indexing past the end. An
+ * out-of-range index yields `undefined`, `new Date(Date.now() + undefined)` is
+ * `Invalid Date`, and the sweep's `nextAttemptAt <= now` comparison is false
+ * for an invalid date forever — so the retry would be scheduled and never run.
+ * A stall that looks like a queue is the exact failure this phase removes.
+ */
+function backoffFor(attempt) {
+    const idx = Math.max(0, Math.min(attempt - 1, JOB_BACKOFF_MS.length - 1));
+    return JOB_BACKOFF_MS[idx];
+}
+/**
+ * Run one attempt. Marks the job done, schedules a retry, or declares it dead.
+ *
+ * Never throws: a job's failure is recorded on the job, and letting it escape
+ * would make the Firebase trigger retry the whole handler — a second,
+ * uncontrolled retry mechanism layered under this one, which is precisely the
+ * doubling that cost 55 sessions in Root Cause #91 (`run.mjs`'s internal retry
+ * multiplying the pool's).
+ */
+export async function runJobOnce(input, ctx) {
+    const { jobId, job } = input;
+    const attempt = job.attempt ?? 1;
+    const maxAttempts = job.maxAttempts ?? JOB_MAX_ATTEMPTS;
+    await jobsRepository.markProcessing(jobId);
+    const runner = JOB_RUNNERS[job.jobType];
+    if (!runner) {
+        /*
+         * 🛑 Terminal immediately, and DEAD rather than failed. An unregistered
+         * jobType cannot become registered by waiting, and the thing that would
+         * fix it is a deploy — so this is the clearest possible case for a human,
+         * not a retry. It is also the failure mode of the seed-loader registry
+         * (Root Cause #90): a missing map entry whose symptom is silence.
+         */
+        const error = `No runner registered for jobType: ${job.jobType}`;
+        await jobsRepository.markDead(jobId, error);
+        await pingBulkEvent(jobId, { status: "failed", action: job.jobType, error }, ctx);
+        await openDeadJobCase(jobId, job, error, ctx);
+        ctx.logger.error("runJobOnce: unregistered jobType", null, { jobId, jobType: job.jobType });
+        return;
+    }
+    try {
+        const result = await runner(job.payload, ctx);
+        await jobsRepository.markDone(jobId, result);
+        await pingBulkEvent(jobId, { status: "success", action: job.jobType, ...result }, ctx);
+        ctx.logger.info("runJobOnce: job complete", {
+            jobId,
+            jobType: job.jobType,
+            attempt,
+            summary: result.summary,
+        });
+        return;
+    }
+    catch (err) {
+        void normalizeError(err);
+        const message = err instanceof Error ? err.message : String(err);
+        /*
+         * 🛑 `mapToHttpError` rather than a bespoke test. It already decides "ours
+         * or theirs" for every error class here, so a 5xx is a transient fault
+         * worth retrying and a 4xx is a permanent one that will fail identically
+         * in five minutes.
+         */
+        const status = mapToHttpError(err).status;
+        const retryable = status >= 500;
+        const attemptsLeft = attempt < maxAttempts;
+        if (retryable && attemptsLeft) {
+            const nextAttemptAt = new Date(Date.now() + backoffFor(attempt));
+            /*
+             * 🛑 The NEW document is created BEFORE this one is marked failed. The
+             * reverse ordering leaves a window where the job reads as failed with no
+             * retry scheduled — and if the process dies in that window, nothing
+             * retries and nothing says so. This way the worst case is a scheduled
+             * retry whose parent still reads `processing`, which the sweep handles
+             * and a human can see.
+             */
+            const retryId = await jobsRepository.createRetry(jobId, job, {
+                attempt: attempt + 1,
+                maxAttempts,
+                nextAttemptAt,
+            });
+            await jobsRepository.markFailed(jobId, message);
+            /*
+             * The client is told "retrying", not "failed". `useBulkEvent` watches
+             * for a terminal state, and reporting failure here would stop a progress
+             * UI on a job that is still going.
+             */
+            await pingBulkEvent(jobId, { status: "retrying", action: job.jobType, error: message, retryJobId: retryId }, ctx);
+            ctx.logger.warn("runJobOnce: attempt failed, retry scheduled", {
+                jobId,
+                retryId,
+                jobType: job.jobType,
+                attempt,
+                status,
+                nextAttemptAt: nextAttemptAt.toISOString(),
+            });
+            return;
+        }
+        await jobsRepository.markDead(jobId, message);
+        await pingBulkEvent(jobId, { status: "failed", action: job.jobType, error: message }, ctx);
+        await openDeadJobCase(jobId, job, message, ctx);
+        ctx.logger.error("runJobOnce: job DEAD", err, {
+            jobId,
+            jobType: job.jobType,
+            attempt,
+            status,
+            reason: retryable ? "attempts exhausted" : "permanent failure",
+        });
+    }
+}
+/**
+ * A dead job is a case, not a log line.
+ *
+ * 🛑 Keyed on the ORIGINAL job id (`parentJobId ?? jobId`), so three exhausted
+ * attempts of one job produce ONE case rather than three. `openOrObserve`
+ * increments its own counter — the property that makes it safe to open a case
+ * from a hot path at all.
+ *
+ * Best-effort: a job is already dead by this point, and failing to file the
+ * case must not turn that into a thrown error from a trigger.
+ */
+async function openDeadJobCase(jobId, job, error, ctx) {
+    const subjectId = job.parentJobId ?? jobId;
+    try {
+        await paymentCasesRepository().openOrObserve({
+            kind: "dead_job",
+            subjectId,
+            severity: "error",
+            entityType: "job",
+            entityId: subjectId,
+            title: `Job ${job.jobType} gave up after ${job.attempt ?? 1} attempt(s)`,
+            detail: `The last error was: ${error}. ` +
+                `Requested by ${job.requestedBy}. The job document holds the payload.`,
+        });
+    }
+    catch (err) {
+        void normalizeError(err);
+        ctx.logger.error("runJobOnce: could not open dead_job case", err, { jobId });
+    }
+}

package/dist/_internal/server/jobs/core/weeklyPayoutEligibility.js

@@ -8,7 +8,7 @@ import { getDefaultCurrency } from "../../../../core/index.js";
 import { computePayoutDeduction } from "../../../shared/fees/calculator.js";
 import { payoutCutoff } from "../../../shared/fees/payout-hold.js";
 import { PROTECTION_CLAIM_WINDOW_HOURS } from "../../../shared/features/shipping/protections.js";
-import { ordersTaxableValue, ordersShippingReimbursement, } from "../../../shared/checkout/order-math.js";
+import { ordersTaxableValue, ordersShippingReimbursement, ordersPointsBorneByStore, } from "../../../shared/checkout/order-math.js";
 export async function runWeeklyPayoutEligibility(ctx) {
     // `FEATURE_PAYOUTS` gate deleted 2026-10-19 — see `autoPayoutEligibility.ts`.
     const siteSettings = await siteSettingsRepository.getSingleton();
@@ -75,7 +75,15 @@ export async function runWeeklyPayoutEligibility(ctx) {
          * `{ id, data }` wrappers, and passing the wrapper would read every field
          * as undefined and silently reimburse zero.
          */
-        ordersShippingReimbursement(orders.map((o) => o.data)));
+        ordersShippingReimbursement(orders.map((o) => o.data)), 
+        /*
+         * D46/D47 — the store-funded points, both ends. Must match
+         * `autoPayoutEligibility` exactly, for the reason stated above
+         * `grossAmount`: the weekly run and the automatic one pay the same orders,
+         * and a term present in one and absent in the other is a seller paid two
+         * different amounts depending on which job got there first.
+         */
+        ordersPointsBorneByStore(orders.map((o) => o.data)));
         /*
          * 🛑 REVEALED before building a payout — see the identical note in
          * `autoPayoutEligibility.ts`. `findById` is ciphertext-by-default and

package/dist/_internal/server/jobs/handlers/onOrderStatusChange.js

@@ -1,4 +1,21 @@
 import { handleOrderStatusChange, } from "../core/onOrderStatusChange.js";
+/*
+ * 🛑 Bound as **`documentUpdated`**, which is what Phase 7's numbering needs
+ * and is already what this function uses — verified rather than assumed.
+ *
+ * `paymentStatus: pending → paid` is frequently the ONLY field that moves on a
+ * COD or manual order, and `documentUpdated` fires on any update, so the
+ * handler sees it. `documentCreated` would miss every one of them, and
+ * `documentWritten` would add nothing except a wake-up on create, where an
+ * order is `pending` and there is nothing to number.
+ *
+ * 🛑 What makes a write-back from this handler safe is the allocation claim:
+ * it updates `orders` only when IT allocated, so the re-fire caused by its own
+ * write finds the claim taken and writes nothing. That is the guard Root Cause
+ * #92's 12M-invocation loop lacked — there the no-op check compared Firestore
+ * maps with `JSON.stringify`, which is key-order sensitive and could never
+ * match, so every invocation wrote and every write re-triggered.
+ */
 export const onOrderStatusChangeHandler = async (event, ctx) => {
     await handleOrderStatusChange({ orderId: event.params.orderId, before: event.before, after: event.after }, ctx);
 };

package/dist/_internal/server/notifications/channel-health.d.ts

@@ -10,10 +10,33 @@
  * its own outcome decides whether the circuit re-closes or re-opens.
  */
 /**
- * Email is the only outbound channel with a transport. "whatsapp" was the
- * other arm until 2026-10-20, when the Cloud API integration was removed.
+ * Email is the only outbound *notification* channel with a transport.
+ * "whatsapp" was the other arm until 2026-10-20, when the Cloud API
+ * integration was removed.
+ *
+ * ## 🛑 Phase 8 widened this to the RECONCILERS' reads — and only those
+ *
+ * `razorpay_read` and `shiprocket_read` name the one placement where "stop
+ * hammering a dead API" is the right behaviour. Two placements are **actively
+ * harmful** and must never be added:
+ *
+ * 1. **NOT the webhook ingest path.** An open breaker converts a transient
+ *    blip into a DROPPED money event — and dropping is precisely what a
+ *    breaker does. The ingest path's whole job is to persist first and ack
+ *    honestly so the gateway retries; a breaker there would ack a 5xx we never
+ *    recorded.
+ *
+ * 2. **NOT around `payment.refund()`.** A refund POST that timed out may have
+ *    SUCCEEDED, so retrying it issues two refunds — and the idempotency claim
+ *    does not help, because it is the same call with the same key making a
+ *    second network attempt. The two-phase reserve/settle exists so a human
+ *    can resolve that by reading the gateway, not so a breaker can guess.
+ *
+ * The names carry `_read` for exactly that reason: a reader is idempotent, so
+ * backing off costs only freshness. Anything that moves money is not a reader
+ * and does not belong in this union.
  */
-export type NotificationChannel = "email";
+export type NotificationChannel = "email" | "razorpay_read" | "shiprocket_read";
 /**
  * Returns false only when the circuit is open and still within its cooldown
  * window. Any other state (closed, or open-but-cooldown-elapsed) is treated

package/dist/_internal/shared/actions/action-registry.js

@@ -1427,6 +1427,40 @@ export const ACTIONS = {
                 confirmKind: "danger",
             },
         },
+        /*
+         * 🛑 The confirmation names the consequence rather than the mechanism.
+         * "Revoke session" means nothing to a buyer; "that device is signed out"
+         * is the fact they need to weigh, and the warning about their own device
+         * is the one mistake this control makes easy to make.
+         */
+        "revoke-session": {
+            iconKey: "lock",
+            id: "user.revoke-session",
+            label: "Sign out device",
+            ariaLabel: "Sign out this device",
+            description: "End an active session so that device has to sign in again.",
+            kind: "danger",
+            confirmation: {
+                title: "Sign out this device?",
+                body: "Whoever is using it will be signed out and will need your password to get back in. If this is the device you are on right now, you will be signed out too.",
+                confirmLabel: "Sign out device",
+                confirmKind: "danger",
+            },
+        },
+        "delete-payment-method": {
+            iconKey: "delete",
+            id: "user.delete-payment-method",
+            label: "Remove card",
+            ariaLabel: "Remove this saved payment method",
+            description: "Remove a saved payment method from the account.",
+            kind: "danger",
+            confirmation: {
+                title: "Remove this payment method?",
+                body: "It will no longer appear at checkout. Any order already placed with it is unaffected.",
+                confirmLabel: "Remove",
+                confirmKind: "danger",
+            },
+        },
         "set-default-address": {
             iconKey: "confirm",
             id: "user.set-default-address",
@@ -2397,17 +2431,44 @@ export const ACTIONS = {
             kind: "ghost",
             permissions: ["admin"],
         },
+        "activate-carousel": {
+            iconKey: "resume",
+            id: "admin.activate-carousel",
+            label: "Activate",
+            ariaLabel: "Show this slide in the carousel",
+            description: "Set a carousel slide to active so the hero carousel renders it.",
+            kind: "primary",
+            permissions: ["admin"],
+        },
+        "deactivate-carousel": {
+            iconKey: "hide",
+            id: "admin.deactivate-carousel",
+            label: "Deactivate",
+            ariaLabel: "Hide this slide from the carousel",
+            description: "Set a carousel slide to inactive without deleting it.",
+            kind: "secondary",
+            permissions: ["admin"],
+        },
         /*
-         * Homepage sections have no bucket of their own, so their edit leaf lives
-         * here beside the carousel pair for the same reason — both are homepage
-         * chrome an admin edits from a list rather than from a detail page.
+         * Homepage sections have no bucket of their own, so their leaves live here
+         * beside the carousel ones for the same reason — both are homepage chrome
+         * an admin edits from a list rather than from a detail page.
+         *
+         * 🛑 `delete-section` exists but is NOT reachable from the public homepage.
+         * Section `order` is POSITIONAL, so removing one leaves a gap in its
+         * neighbours' numbering — not something to offer from a public page, where
+         * the only confirmation a person gets is a dialog.
          *
-         * 🛑 There is deliberately NO `delete-section` counterpart. Section `order`
-         * is POSITIONAL, so removing one silently renumbers its neighbours — not
-         * something to offer from the public homepage, where the only confirmation
-         * a person gets is a dialog. `OwnerQuickActions` enforces the absence by
-         * omitting `remove` from the SECTION mapping, so no call site can pass a
-         * delete handler and have it render.
+         * That prohibition is enforced INDEPENDENTLY of this registry, which is
+         * why the leaf can exist: `RESOURCE_LEAVES.SECTION` in `OwnerQuickActions`
+         * omits `remove`, and `showDelete` gates on `leaves.remove` rather than on
+         * what a call site passes — so the pencil strip renders no bin regardless.
+         * This comment read "there is deliberately NO delete-section counterpart"
+         * until 2026-10-22, when the admin sections listing gained a real one.
+         *
+         * The listing is the right home for it: it owns these records, it shows
+         * the `order` column the gap appears in, and its Reorder panel has a
+         * Reindex 1..N button beside it to close one.
          */
         "edit-section": {
             iconKey: "edit",
@@ -2418,6 +2479,62 @@ export const ACTIONS = {
             kind: "ghost",
             permissions: ["admin"],
         },
+        "enable-section": {
+            iconKey: "resume",
+            id: "admin.enable-section",
+            label: "Enable",
+            ariaLabel: "Enable this homepage section",
+            description: "Render this section on its surface again.",
+            kind: "primary",
+            permissions: ["admin"],
+        },
+        "disable-section": {
+            iconKey: "hide",
+            id: "admin.disable-section",
+            label: "Disable",
+            ariaLabel: "Disable this homepage section",
+            description: "Stop rendering this section without deleting it or its saved config.",
+            kind: "secondary",
+            permissions: ["admin"],
+        },
+        "delete-section": {
+            iconKey: "delete",
+            id: "admin.delete-section",
+            label: "Delete Section",
+            ariaLabel: "Delete this homepage section",
+            description: "Permanently remove this homepage section and its saved config.",
+            kind: "danger",
+            permissions: ["admin"],
+            confirmation: {
+                title: "Delete this section?",
+                /*
+                 * The last sentence is load-bearing: it names the reversible
+                 * alternative at the moment of the irreversible choice, and that
+                 * alternative is one click away in the same row.
+                 */
+                body: "The section and its saved config are removed permanently. Display order is positional, so the sections after it keep their current numbers and a gap is left — Reorder sections → Reindex 1..N closes it. To hide the section from the homepage while keeping its config, disable it instead.",
+                confirmLabel: "Delete section",
+                confirmKind: "danger",
+            },
+        },
+        "show-nav-item": {
+            iconKey: "view",
+            id: "admin.show-nav-item",
+            label: "Show",
+            ariaLabel: "Show this navigation item",
+            description: "Make a navigation item visible in the sidebar and menus.",
+            kind: "primary",
+            permissions: ["admin"],
+        },
+        "hide-nav-item": {
+            iconKey: "hide",
+            id: "admin.hide-nav-item",
+            label: "Hide",
+            ariaLabel: "Hide this navigation item",
+            description: "Hide a navigation item without deleting it.",
+            kind: "secondary",
+            permissions: ["admin"],
+        },
         "delete-carousel": {
             iconKey: "delete",
             id: "admin.delete-carousel",
@@ -3085,6 +3202,29 @@ export const ACTIONS = {
                 confirmKind: "danger",
             },
         },
+        /*
+         * 🛑 Distinct from `clear-previews` and `discard-staged`, which are
+         * SESSION/STAGING operations over files no record points at yet. This one
+         * removes a FINALISED asset, so the confirmation has to say what nothing
+         * else in this bucket has to: the bytes are referenced by whatever already
+         * embedded them, and the proxy resolves `/media/<shortId>` through the
+         * `mediaAssets` row — so deleting is how a live page gets a broken image.
+         */
+        "delete-media": {
+            iconKey: "delete",
+            id: "media.delete-media",
+            label: "Delete file",
+            ariaLabel: "Delete this media file",
+            description: "Permanently delete a media file and the asset row that resolves it.",
+            kind: "danger",
+            permissions: ["admin"],
+            confirmation: {
+                title: "Delete this file?",
+                body: "The file is removed from storage and stops resolving. Any product, blog post or section still embedding it will show a broken image — this cannot be undone.",
+                confirmLabel: "Delete file",
+                confirmKind: "danger",
+            },
+        },
     },
     SUPPORT: {
         "create-ticket": {
@@ -3116,6 +3256,34 @@ export const ACTIONS = {
                 confirmLabel: "Close ticket",
             },
         },
+        /*
+         * Raising a dispute on an order.
+         *
+         * Filed under SUPPORT rather than a new ORDER bucket: there is no such
+         * bucket, and a dispute's destination is a support investigation. A first
+         * draft of the form wrote `ACTIONS.ORDERS?.["raise-dispute"]`, where the
+         * optional chain would have silently resolved to `undefined` and rendered
+         * a button with no label, no aria-label and no confirmation — which is
+         * precisely what Rule #7 exists to stop.
+         *
+         * NO `confirmation`, deliberately. It is not destructive: nothing is
+         * cancelled, no money moves, and the action's own docstring says it "does
+         * not itself reverse payment/order status". A confirm dialog in front of
+         * "tell us something went wrong" adds friction to the one path a buyer
+         * with a problem needs to be able to take.
+         */
+        "raise-dispute": {
+            // `report`, which IS the Flag glyph (icon-registry.ts:133). `"flag"` is
+            // not a registered key — and because `iconKey` is typed `IconKey` rather
+            // than `string`, that would have been a compile error rather than the
+            // silent no-op it used to be.
+            iconKey: "report",
+            id: "support.raise-dispute",
+            label: "Report this",
+            ariaLabel: "Report a problem with this order",
+            description: "Raise a dispute on an order for support to investigate.",
+            kind: "primary",
+        },
     },
     TESTER: {
         "save-note": {

package/dist/_internal/shared/checkout/coupon-discount.d.ts

@@ -32,12 +32,54 @@ export interface GroupCouponDiscountResult {
     appliedDiscounts: {
         code: string;
         couponId?: string;
+        /**
+         * 🛑 This is NOT `CouponType`, and the two are easy to confuse now that
+         * both live in this file. This one records WHERE the discount came from —
+         * a coupon the buyer typed, a deal, or an automatic rule — and it is what
+         * the order document stores in `appliedDiscounts[]`.
+         *
+         * `CartAppliedCoupon.type` is the coupon's own kind (`percentage`,
+         * `points_earn`, …) and is what the loop below skips on. Reading one where
+         * the other is meant would compile cleanly and be wrong: every value of
+         * this union is absent from that one, so the `points_earn` skip would
+         * never fire and a points coupon would discount the order.
+         */
         type: "coupon" | "deal" | "auto";
         discountAmount: number;
         scope?: "admin" | "seller";
         storeId?: string;
     }[];
 }
+/**
+ * What the CART-level call returns: the same totals, plus the per-group
+ * breakdown.
+ *
+ * 🛑 A separate interface rather than one optional field on the result above.
+ * `computeGroupCouponDiscount` scores ONE group, so it has no per-group list
+ * to report and never will — giving it an empty `perGroup` would be a value
+ * that type-checks and means nothing, and the capture route's points tender
+ * reads this array positionally. A caller that gets `[]` where it expected one
+ * entry per group apportions every point against group zero.
+ */
+export interface CartCouponDiscountResult extends GroupCouponDiscountResult {
+    /**
+     * The per-group discount, in the order the groups were passed.
+     *
+     * 🛑 Surfaced rather than aggregated-and-forgotten. It was already being
+     * computed inside the loop below and then summed away — the same shape as
+     * `CheckoutPricingPreviewStore`'s per-store fees, which existed only as an
+     * aggregate until a seller card needed them.
+     *
+     * The caller that needs it is the capture route's points tender: the
+     * per-group base includes that group's own discount, and re-deriving it
+     * there would be a second copy of the apportionment rule (Root Cause #75) on
+     * the one path D37 proves gets left behind.
+     */
+    perGroup: {
+        storeId: string | undefined;
+        couponDiscount: number;
+    }[];
+}
 /**
  * Prorates every buyer-applied coupon against one seller-group's total.
  *
@@ -70,4 +112,4 @@ export declare function computeCartCouponDiscount(appliedCoupons: CartAppliedCou
         itemId: string;
         lineTotal: number;
     }[];
-}[]): GroupCouponDiscountResult;
+}[]): CartCouponDiscountResult;

package/dist/_internal/shared/checkout/coupon-discount.js

@@ -42,6 +42,20 @@ export function computeGroupCouponDiscount(appliedCoupons, groupLines, groupTota
     let couponDiscount = 0;
     const appliedDiscounts = [];
     for (const coupon of appliedCoupons) {
+        /*
+         * 🛑 D51 — a `points_earn` coupon DISCOUNTS NOTHING. It awards points on
+         * the post-discount amount paid, and it carries `pointsPercent` rather than
+         * a discount value.
+         *
+         * Skipped here rather than relied on to carry `discountAmount: 0`. The
+         * apply route writes whatever `validateCouponForCart` returned, and a
+         * points coupon that ever came back with a non-zero `discountAmount` —
+         * through a mis-seeded `discount.value`, or an admin editing a coupon's
+         * type after creation — would silently discount the order AND award points.
+         * A type check cannot be bypassed by bad data; a zero cannot be relied on.
+         */
+        if (coupon.type === "points_earn")
+            continue;
         let couponGroupDiscount = 0;
         const isSellerScoped = coupon.scope === "seller" && coupon.storeId;
         if (isSellerScoped) {
@@ -93,11 +107,22 @@ export function computeCartCouponDiscount(appliedCoupons, groups) {
     const cartSubtotal = groups.reduce((sum, g) => sum + g.lines.reduce((s, l) => s + l.lineTotal, 0), 0);
     let couponDiscount = 0;
     const appliedDiscounts = [];
+    const perGroup = [];
     for (const group of groups) {
         const groupTotal = group.lines.reduce((s, l) => s + l.lineTotal, 0);
         const res = computeGroupCouponDiscount(appliedCoupons, group.lines, groupTotal, cartSubtotal, group.storeId);
         couponDiscount += res.couponDiscount;
         appliedDiscounts.push(...res.appliedDiscounts);
+        /*
+         * 🛑 NOT rounded here, and the aggregate below IS. Rounding each group
+         * then summing can differ from summing then rounding by a paisa per group,
+         * and the aggregate is what the gateway captures — so the group figures
+         * stay raw and the caller rounds its own composed base once, exactly as
+         * `createOrderForGroup` does with a single `roundRupees` on `orderTotal`
+         * (D42). A rounded-then-summed discount is how a total ends up a paisa
+         * short of its own lines.
+         */
+        perGroup.push({ storeId: group.storeId, couponDiscount: res.couponDiscount });
     }
-    return { couponDiscount: roundRupees(couponDiscount), appliedDiscounts };
+    return { couponDiscount: roundRupees(couponDiscount), appliedDiscounts, perGroup };
 }