@mohasinac/appkit 4.58.0 → 4.60.0

package/dist/_internal/server/features/payment-cases/disputes.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Turn a `payment.dispute.*` webhook into a case with the gateway's own clock
+ * on it.
+ *
+ * ## Why a dispute is the sharpest case kind
+ *
+ * Every other case in this collection has a deadline we invented or no deadline
+ * at all. A dispute has `respond_by`, set by the gateway, and **missing it loses
+ * the money by default** — irrespective of whether we were right. That single
+ * property is why `paymentCases` exists as its own queue rather than as rows in
+ * `serverErrors`: an error log is read when someone is curious, and this needs
+ * to be read before a date.
+ *
+ * ## 🛑 THIS HANDLER IS READS ONLY
+ *
+ * It fetches, it records, it notifies. It never contests, never submits
+ * evidence, never accepts liability. `IPaymentProvider` deliberately has no
+ * `contestDispute` (see the 🛑 on that contract), and `acceptDispute` requires
+ * an explicit irrevocability confirmation plus an admin uid — so neither is
+ * reachable from here even by accident.
+ *
+ * Submitting evidence is irreversible and is judged by a third party looking at
+ * documents. That decision belongs to a human in Razorpay's own dashboard. A
+ * later session wanting to "complete the dispute feature" should read this
+ * paragraph: the feature is complete, and this is the shape.
+ */
+import type { Dispute } from "../../../../contracts/payment";
+/**
+ * Which `payment.dispute.*` events exist.
+ *
+ * 🛑 TRAINING-SOURCED NAMES, NOT VERIFIED. The plan's capability matrix marks
+ * these `TRAINING` and says to read the live dashboard's event picker before
+ * trusting them — and that has not happened, because it needs the dashboard.
+ *
+ * This is why the route matches on the **`payment.dispute.` PREFIX** rather
+ * than on an exact list: a dispute event whose name we guessed wrong still
+ * classifies as a dispute, still gets a case, and still carries its
+ * `respond_by`. Guessing a name wrong then costs a slightly less precise title,
+ * not a missed chargeback. `razorpay.webhooks.all()` enumerates the real
+ * subscription set for free whenever someone has credentials to hand.
+ */
+export declare const DISPUTE_EVENT_PREFIX = "payment.dispute.";
+export interface DisputeWebhookEntity {
+    id?: string;
+    payment_id?: string;
+    amount?: number;
+    currency?: string;
+    amount_deducted?: number;
+    reason_code?: string;
+    respond_by?: number;
+    status?: string;
+    phase?: string;
+    created_at?: number;
+}
+/**
+ * Record a dispute as a case.
+ *
+ * Returns the case id, or `null` when the payload carried no usable dispute —
+ * in which case the caller still has a `gatewayEvents` row with the verbatim
+ * body, so nothing is lost.
+ */
+export declare function ingestDispute(entity: DisputeWebhookEntity, opts: {
+    gateway: string;
+    gatewayEventId?: string;
+    rawEvent: string;
+}): Promise<string | null>;
+/**
+ * Poll the gateway for every dispute it knows about and reconcile them into
+ * cases. Phase 4's R4 calls this; it is idempotent by construction, since
+ * `openOrObserve` is.
+ *
+ * Takes the already-normalised `Dispute[]` from the provider adapter, which has
+ * done the unit conversions — so this function performs none, and there is one
+ * place per direction that does.
+ */
+export declare function reconcileDisputes(disputes: readonly Dispute[]): Promise<number>;

package/dist/_internal/server/features/payment-cases/disputes.js

@@ -0,0 +1,241 @@
+/**
+ * Turn a `payment.dispute.*` webhook into a case with the gateway's own clock
+ * on it.
+ *
+ * ## Why a dispute is the sharpest case kind
+ *
+ * Every other case in this collection has a deadline we invented or no deadline
+ * at all. A dispute has `respond_by`, set by the gateway, and **missing it loses
+ * the money by default** — irrespective of whether we were right. That single
+ * property is why `paymentCases` exists as its own queue rather than as rows in
+ * `serverErrors`: an error log is read when someone is curious, and this needs
+ * to be read before a date.
+ *
+ * ## 🛑 THIS HANDLER IS READS ONLY
+ *
+ * It fetches, it records, it notifies. It never contests, never submits
+ * evidence, never accepts liability. `IPaymentProvider` deliberately has no
+ * `contestDispute` (see the 🛑 on that contract), and `acceptDispute` requires
+ * an explicit irrevocability confirmation plus an admin uid — so neither is
+ * reachable from here even by accident.
+ *
+ * Submitting evidence is irreversible and is judged by a third party looking at
+ * documents. That decision belongs to a human in Razorpay's own dashboard. A
+ * later session wanting to "complete the dispute feature" should read this
+ * paragraph: the feature is complete, and this is the shape.
+ */
+import { normalizeError } from "../../../../errors/normalize.js";
+import { serverLogger } from "../../../../monitoring/index.js";
+import { paiseToRupees, rupeesToPaise } from "../../../../core/money.js";
+import { paymentCasesRepository } from "../../../../features/payment-cases/repository/payment-cases.repository.js";
+import { orderRepository } from "../../../../features/orders/repository/orders.repository.js";
+/**
+ * Dispute statuses, as Razorpay spells them.
+ *
+ * 🛑 NOT a TypeScript union on `Dispute.status` — the SDK declares that field
+ * as `string` and the value set is the gateway's to change. These constants are
+ * for COMPARISON, and every comparison below treats an unrecognised value as
+ * "still open", which fails in the safe direction: an unknown state leaves the
+ * case needing attention rather than silently closing it.
+ */
+const DISPUTE_CLOSED_STATUSES = new Set(["won", "lost", "closed"]);
+/**
+ * Which `payment.dispute.*` events exist.
+ *
+ * 🛑 TRAINING-SOURCED NAMES, NOT VERIFIED. The plan's capability matrix marks
+ * these `TRAINING` and says to read the live dashboard's event picker before
+ * trusting them — and that has not happened, because it needs the dashboard.
+ *
+ * This is why the route matches on the **`payment.dispute.` PREFIX** rather
+ * than on an exact list: a dispute event whose name we guessed wrong still
+ * classifies as a dispute, still gets a case, and still carries its
+ * `respond_by`. Guessing a name wrong then costs a slightly less precise title,
+ * not a missed chargeback. `razorpay.webhooks.all()` enumerates the real
+ * subscription set for free whenever someone has credentials to hand.
+ */
+export const DISPUTE_EVENT_PREFIX = "payment.dispute.";
+/**
+ * Severity from the dispute's own state.
+ *
+ * Always at least `warning`, and `error` while a response is still owed —
+ * because that is the window in which a human can still change the outcome.
+ * A closed dispute drops to `warning`: it still needs handling (a lost dispute
+ * means a payout clawback and an order-status decision) but no longer has a
+ * clock.
+ *
+ * 🛑 `openOrObserve` only ever escalates, so a `won`/`lost` event arriving
+ * after the `created` one will NOT downgrade the case from `error`. That is
+ * deliberate and is the correct direction: the operator was told this was
+ * urgent, and the fact that the window closed does not make the consequence
+ * smaller.
+ */
+function severityFor(status) {
+    return status && DISPUTE_CLOSED_STATUSES.has(status) ? "warning" : "error";
+}
+/**
+ * Record a dispute as a case.
+ *
+ * Returns the case id, or `null` when the payload carried no usable dispute —
+ * in which case the caller still has a `gatewayEvents` row with the verbatim
+ * body, so nothing is lost.
+ */
+export async function ingestDispute(entity, opts) {
+    const disputeId = entity.id;
+    const paymentId = entity.payment_id;
+    if (!disputeId || !paymentId) {
+        serverLogger.error("dispute ingest: payload carried no dispute id or payment id", {
+            rawEvent: opts.rawEvent,
+        });
+        return null;
+    }
+    /*
+     * 🛑 Two conversions, both silent when wrong, and they fail differently.
+     *
+     *   amount / amount_deducted — currency SUBUNITS → rupees, via the shared
+     *     helper. Hand-writing `/ 100` here would be blocked by
+     *     `audit-money-units`, and rightly: six money fields survived the 2026-05
+     *     migration with the wrong unit precisely because the arithmetic was
+     *     scattered rather than named.
+     *
+     *   respond_by — Unix SECONDS → Date, so `* 1000`. Getting this wrong yields
+     *     21 January 1970, which does not throw and does not read as a unit bug —
+     *     it reads as corrupt data, and it would make a live deadline sort as
+     *     decades overdue, so an escalation query would either flood on it or
+     *     ignore it. There is no helper for this one because it is a timestamp,
+     *     not money.
+     */
+    const amount = typeof entity.amount === "number" ? paiseToRupees(entity.amount) : undefined;
+    const amountDeducted = typeof entity.amount_deducted === "number"
+        ? paiseToRupees(entity.amount_deducted)
+        : undefined;
+    const respondBy = typeof entity.respond_by === "number" ? new Date(entity.respond_by * 1000) : undefined;
+    /*
+     * Which of OUR orders this dispute concerns. Best-effort: a dispute on a
+     * payment we cannot find is MORE urgent, not less — it means either our
+     * records are wrong or somebody is disputing a payment we never recorded —
+     * so a failed lookup must not stop the case being opened.
+     */
+    let orderIds = [];
+    try {
+        const orders = await orderRepository.findByPaymentId(paymentId);
+        orderIds = orders.map((o) => o.id);
+    }
+    catch (err) {
+        void normalizeError(err);
+        serverLogger.warn("dispute ingest: order lookup failed — opening the case regardless", {
+            paymentId,
+        });
+    }
+    const status = entity.status ?? "unknown";
+    const detailLines = [
+        `Gateway: ${opts.gateway}`,
+        `Event: ${opts.rawEvent}`,
+        `Dispute: ${disputeId}`,
+        `Payment: ${paymentId}`,
+        `Status: ${status}${entity.phase ? ` (phase ${entity.phase})` : ""}`,
+        entity.reason_code ? `Reason code: ${entity.reason_code}` : null,
+        amount !== undefined ? `Amount disputed: ${amount}` : null,
+        amountDeducted !== undefined && amountDeducted > 0
+            ? `Already deducted from our balance: ${amountDeducted}`
+            : null,
+        respondBy ? `Respond by: ${respondBy.toISOString()}` : "Respond by: not supplied",
+        orderIds.length
+            ? `Our orders: ${orderIds.join(", ")}`
+            : "🛑 No order found for this payment — records disagree with the gateway",
+        "",
+        "Respond in the gateway's own dashboard. This system does not submit evidence.",
+    ].filter((line) => line !== null);
+    const result = await paymentCasesRepository().openOrObserve({
+        kind: "dispute",
+        /*
+         * Keyed on the DISPUTE id, so every event in one dispute's lifecycle —
+         * created, under_review, won/lost, closed — lands on ONE case rather than
+         * four. That is the whole mechanism; keying on the event id would produce a
+         * case per notification.
+         */
+        subjectId: disputeId,
+        severity: severityFor(entity.status),
+        title: `Chargeback ${status} — ${disputeId}`,
+        detail: detailLines.join("\n"),
+        entityType: orderIds.length > 0 ? "order" : "payment",
+        entityId: orderIds[0] ?? paymentId,
+        ...(respondBy ? { dueAt: respondBy } : {}),
+        ...(amount !== undefined ? { amountAtRisk: amount } : {}),
+        ...(opts.gatewayEventId ? { gatewayEventIds: [opts.gatewayEventId] } : {}),
+        ...(orderIds.length ? { orderIds } : {}),
+        gatewayPaymentId: paymentId,
+    });
+    /*
+     * 🛑 A closed dispute MARKS SELF-HEALED AND STAYS OPEN.
+     *
+     * "Razorpay closed the dispute" and "we have finished handling it" are
+     * different facts, and the gap between them is work: a LOST dispute needs a
+     * payout clawback from the seller and a decision about the order's status,
+     * and a WON one still needs the order un-flagged. Auto-closing on the
+     * gateway's say-so would file both as done.
+     */
+    if (entity.status && DISPUTE_CLOSED_STATUSES.has(entity.status)) {
+        await paymentCasesRepository().markSelfHealed(result.id);
+        serverLogger.info("dispute ingest: gateway closed the dispute — case left open for a human", {
+            disputeId,
+            status: entity.status,
+            caseId: result.id,
+        });
+    }
+    serverLogger.warn("dispute ingest: case recorded", {
+        disputeId,
+        paymentId,
+        caseId: result.id,
+        created: result.created,
+        dueAt: respondBy?.toISOString(),
+    });
+    return result.id;
+}
+/**
+ * Poll the gateway for every dispute it knows about and reconcile them into
+ * cases. Phase 4's R4 calls this; it is idempotent by construction, since
+ * `openOrObserve` is.
+ *
+ * Takes the already-normalised `Dispute[]` from the provider adapter, which has
+ * done the unit conversions — so this function performs none, and there is one
+ * place per direction that does.
+ */
+export async function reconcileDisputes(disputes) {
+    let recorded = 0;
+    for (const d of disputes) {
+        try {
+            await ingestDispute({
+                id: d.id,
+                payment_id: d.paymentId,
+                /*
+                 * Converted BACK to subunits, because `ingestDispute` takes a
+                 * WEBHOOK-shaped entity (subunits) while `Dispute` is already in
+                 * rupees. One input contract rather than two — the alternative is an
+                 * "already converted" boolean, which is exactly the kind of flag that
+                 * ends up wrong at one of two call sites.
+                 *
+                 * Via `rupeesToPaise`, not `* 100`: the round-trip must use the same
+                 * rounding as the forward conversion, or a ₹1,499.50 dispute comes
+                 * back a paisa light and the `amountAtRisk` on the case disagrees
+                 * with the gateway by a rounding error nobody can explain.
+                 */
+                amount: rupeesToPaise(d.amount),
+                currency: d.currency,
+                amount_deducted: rupeesToPaise(d.amountDeducted),
+                reason_code: d.reasonCode,
+                respond_by: Math.floor(d.respondBy.getTime() / 1000),
+                status: d.status,
+                phase: d.phase,
+                created_at: Math.floor(d.createdAt.getTime() / 1000),
+            }, { gateway: d.gateway, rawEvent: "reconcile.disputes.all" });
+            recorded += 1;
+        }
+        catch (err) {
+            void normalizeError(err);
+            serverLogger.error("dispute reconcile: one dispute failed — continuing", {
+                disputeId: d.id,
+            });
+        }
+    }
+    return recorded;
+}

package/dist/_internal/server/features/payment-cases/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * payment-cases — server surface.
+ *
+ * A narrow barrel for one feature's public entry points (Root Cause #18), not a
+ * convenience hub. The repository is imported directly by anything that
+ * queries; only the ingest/reconcile helpers go through here, because those are
+ * what a route or a job calls.
+ */
+export { ingestDispute, reconcileDisputes, DISPUTE_EVENT_PREFIX, type DisputeWebhookEntity, } from "./disputes";

package/dist/_internal/server/features/payment-cases/index.js

@@ -0,0 +1,9 @@
+/**
+ * payment-cases — server surface.
+ *
+ * A narrow barrel for one feature's public entry points (Root Cause #18), not a
+ * convenience hub. The repository is imported directly by anything that
+ * queries; only the ingest/reconcile helpers go through here, because those are
+ * what a route or a job calls.
+ */
+export { ingestDispute, reconcileDisputes, DISPUTE_EVENT_PREFIX, } from "./disputes.js";

package/dist/_internal/server/features/payouts/actions.d.ts

@@ -9,12 +9,37 @@ export type ApplyRefundDeductionInput = {
     platformFeeRate?: number;
     reason: string;
 };
-export type ApplyRefundDeductionResult = {
+/**
+ * Where the clawback landed.
+ *
+ * 🛑 Deliberately has NO `{ applied: false }` member. That shape is what let
+ * four lines of caller code treat "we could not recover the money" as an
+ * unremarkable outcome. Every variant here names a destination, and
+ * `unrecovered` is explicit about being a debt rather than a non-event.
+ *
+ * `applied` is kept as the discriminant for source compatibility with the two
+ * existing readers, so this is a widening rather than a rename.
+ */
+export type ApplyRefundDeductionResult = 
+/** Netted off a pending payout before it was sent. The good case. */
+{
     applied: true;
+    to: "payout";
     payoutId: string;
     netAmount: number;
-} | {
+}
+/**
+ * The payout has already settled, or this order was not in it. The seller
+ * holds money for returned goods and WE CANNOT TAKE IT BACK from here.
+ * `recordedAs` is the durable row an operator can act on.
+ */
+ | {
     applied: false;
-    reason: string;
+    to: "unrecovered";
+    reason: "no_pending_payout" | "order_not_in_payout";
+    storeId: string;
+    orderId: string;
+    amount: number;
+    recordedAs: string;
 };
 export declare function applyRefundDeductionAction(input: ApplyRefundDeductionInput): Promise<ActionResult<ApplyRefundDeductionResult>>;

package/dist/_internal/server/features/payouts/actions.js

@@ -3,17 +3,54 @@ import { wrapAction } from "@mohasinac/appkit/server";
 /**
  * applyRefundDeductionAction — deduct a refund from a seller's pending payout.
  *
- * Called fire-and-forget after processRefundAction succeeds:
+ * Called after processRefundAction succeeds:
  *   1. Locate the most recent pending payout for the order's store.
  *   2. If found and it covers the refunded order, apply the deduction.
- *   3. If no pending payout exists (already settled), return applied:false —
- *      the reduced net revenue is automatically reflected in the next payout
- *      cycle because the order revenue was never re-added.
+ *   3. Otherwise the money cannot be recovered automatically — record it.
  *
  * deductedAmount = refundedAmount × (1 − platformFeeRate).
  * The platform keeps its fee share on every refund.
+ *
+ * ──────────────────────────────────────────────────────────────────────────
+ * 🛑 THIS DOCSTRING USED TO CONTAIN A FALSE CLAIM, and it was load-bearing
+ * ──────────────────────────────────────────────────────────────────────────
+ *
+ * Step 3 read:
+ *
+ *   > If no pending payout exists (already settled), return applied:false —
+ *   > the reduced net revenue is automatically reflected in the next payout
+ *   > cycle because the order revenue was never re-added.
+ *
+ * **There is no such mechanism.** Verified 2026-10-21: there is no
+ * `sellerLedger`, no running balance, no carry-forward of any kind anywhere in
+ * the codebase, and each payout's `grossAmount` is computed fresh as
+ * `ordersTaxableValue(<this batch of newly delivered orders>)`. A refund on an
+ * order whose payout has ALREADY SETTLED is therefore never recovered — the
+ * seller keeps money for goods that came back, and nothing records that a
+ * clawback was attempted and failed.
+ *
+ * That claim is why the caller could reasonably write
+ * `.catch(() => {/* best-effort *\/})` and discard the result: the comment
+ * said the money was handled elsewhere. It was not.
+ *
+ * So the return type is now a DESTINATION rather than a boolean. Two reasons,
+ * and the second is the durable one:
+ *
+ *   1. It names where the money went, which is the question an operator
+ *      actually has.
+ *   2. A discriminated union with no `applied: false` member means the
+ *      "ignore the result" shape no longer type-checks into silence — the
+ *      caller has to acknowledge the unrecovered case. Making the bug
+ *      UNCOMPILABLE is stronger than asking nobody to reintroduce it.
+ *
+ * 🛑 This does NOT recover the money. Automatic recovery needs a seller
+ * ledger that can hold a negative balance and net it against the next payout,
+ * which is Phase 11 (books) and is deliberately not smuggled in here. What
+ * this change buys is that the loss is now VISIBLE — a durable row with the
+ * store, the order and the amount — instead of silently absorbed.
  */
 import { payoutRepository } from "../../../../repositories/index.js";
+import { serverErrorsRepository } from "../../../../features/server-errors/repository/server-errors.repository.js";
 import { ValidationError } from "../../../../errors/index.js";
 import { roundRupees } from "../../../../utils/number.formatter.js";
 export async function applyRefundDeductionAction(input) {
@@ -24,12 +61,44 @@ export async function applyRefundDeductionAction(input) {
         const feeRate = input.platformFeeRate ?? 0.05;
         const deductedAmount = roundRupees(input.refundedAmount * (1 - feeRate));
         const pending = await payoutRepository.findPendingByStore(input.storeId);
-        if (!pending) {
-            return { applied: false, reason: "no_pending_payout" };
-        }
-        if (!pending.orderIds.includes(input.orderId)) {
-            return { applied: false, reason: "order_not_in_payout" };
+        const unrecoverable = !pending
+            ? "no_pending_payout"
+            : !pending.orderIds.includes(input.orderId)
+                ? "order_not_in_payout"
+                : null;
+        if (unrecoverable) {
+            /*
+             * The seller has already been paid for an order that came back. Record
+             * it durably — this is the money, and a `warn` would scroll past in a
+             * log buffer that drops at ~4 KB/s.
+             *
+             * `/admin/maintenance/payment-rollbacks` already filters on
+             * `PAYMENT_ROLLBACK_*`, so this surfaces there with no new page.
+             *
+             * `record()` is documented never to throw, so this cannot turn a
+             * failed clawback into a failed refund — the refund has already been
+             * posted and must not be rolled back by an accounting side effect.
+             */
+            const code = `PAYMENT_ROLLBACK_${unrecoverable.toUpperCase()}`;
+            await serverErrorsRepository().record({
+                source: "vercel",
+                route: "applyRefundDeductionAction",
+                code,
+                message: `Clawback of ₹${deductedAmount} for order ${input.orderId} (store ${input.storeId}) could not be applied: ${unrecoverable}. ` +
+                    `The seller retains this amount for returned goods; there is no automatic recovery until a seller ledger exists.`,
+                requestId: input.refundId,
+            });
+            return {
+                applied: false,
+                to: "unrecovered",
+                reason: unrecoverable,
+                storeId: input.storeId,
+                orderId: input.orderId,
+                amount: deductedAmount,
+                recordedAs: code,
+            };
         }
+        // `pending` is non-null here: `unrecoverable` is only null when it is set.
         const updated = await payoutRepository.applyRefundDeduction(pending.id, {
             orderId: input.orderId,
             refundId: input.refundId,
@@ -37,6 +106,11 @@ export async function applyRefundDeductionAction(input) {
             deductedAmount,
             reason: input.reason,
         });
-        return { applied: true, payoutId: updated.id, netAmount: updated.netAmount ?? updated.amount };
+        return {
+            applied: true,
+            to: "payout",
+            payoutId: updated.id,
+            netAmount: updated.netAmount ?? updated.amount,
+        };
     });
 }

package/dist/_internal/server/features/points/adjust.d.ts

@@ -0,0 +1,61 @@
+import type { PointsAdjustFormValues } from "../../../../features/points/schemas/adjust-form";
+/**
+ * `admin_adjustment`'s first HUMAN writer.
+ *
+ * ## Why this is the last piece of D48 rather than the first
+ *
+ * `admin_adjustment` and `redemption_reversal` were both fully specified —
+ * signed-amount invariant, mandatory `adminReason`, the lot — and had **zero
+ * writers**. The reversal got one when cancellation was built. This is the
+ * other, and it was left until last on purpose: it is the only path by which a
+ * human can create spendable money from nothing, so it should not have existed
+ * before the ledger could expire a batch, consume FIFO, reverse a spend and
+ * reconcile against its own mirror. All four now do.
+ *
+ * ## 🛑 The one writer it must NOT be confused with
+ *
+ * `expireLapsedBatches` also appends `admin_adjustment`, with
+ * `actorUid: "system:points-expiry"`, and its docstring calls that **the one
+ * place a system actor may write an adjustment** — because expiry is a rule
+ * with a date attached rather than a discretionary decision.
+ *
+ * So this function takes a REAL `actorUid` and never that sentinel. Reusing it
+ * would make a human's decision indistinguishable from a scheduled rule in the
+ * one record that exists to tell them apart.
+ *
+ * ## Credits expire; debits and the reason do not
+ *
+ * A positive adjustment gets `pointsExpiryFrom(now)` like any other credit — an
+ * admin-granted goodwill credit is not more permanent than an earned one, and
+ * leaving `expiresAt` absent would mean NEVER EXPIRES, quietly making this the
+ * one way to mint a perpetual balance.
+ *
+ * A negative adjustment passes nothing, matching every other spend: there is
+ * nothing left to expire.
+ *
+ * ## Two records, deliberately
+ *
+ * The ledger entry answers "why does this account have 53 points". The
+ * `adminAuditLog` row answers "what have admins done lately". The second is the
+ * one you need when the account is not yet suspected, which is why a feature
+ * that already records `actorUid` on the entry still writes both.
+ *
+ * ## The buyer is told
+ *
+ * A balance that changes with no explanation is indistinguishable from a bug,
+ * and the buyer is the only party who cannot query the ledger. `description` is
+ * the buyer-facing line and is already mandatory in the schema; the
+ * notification carries it. `adminReason` is NOT sent — it is written for the
+ * next admin and may name an internal case.
+ *
+ * Best-effort: a notification that fails must not undo an applied adjustment,
+ * because the money has already moved and the ledger is the record that
+ * matters.
+ */
+export declare function adjustUserPoints(input: PointsAdjustFormValues, actor: {
+    uid: string;
+    name?: string;
+}): Promise<{
+    entryId: string;
+    balance: number;
+}>;