@adriangalilea/utils 0.17.1 → 0.19.0

package/dist/bot/payments/payload.js

@@ -0,0 +1,69 @@
+/**
+ * Invoice payload codec. Telegram echoes the `invoice_payload` string
+ * back on `pre_checkout_query` and `successful_payment`; we use it to
+ * recover the `(productKey, userId)` pair that the in-flight purchase
+ * refers to.
+ *
+ * Constraints from Telegram:
+ *   - Max 128 bytes.
+ *   - Must be a string (we use printable ASCII).
+ *
+ * Format: `${productKey}|${userId}`
+ *
+ * The `|` delimiter is unambiguous because productKey is one of:
+ *   - `vip.${number}`        — only digits and `.`
+ *   - `credits.${number}`    — only digits and `.`
+ *   - `perks.${key}`         — key restricted to `/^[a-z][a-z0-9_]*$/i`
+ *                              by `config.ts` validation
+ *
+ * None of those contain `|`, so the first `|` is always the delimiter.
+ * Worst case length is ~`perks.${64-char-key}|${20-digit-int}` ≈ 90 bytes
+ * — comfortably under the 128-byte cap. We assert the length to fail
+ * loud if the cap is ever approached.
+ */
+import { panic } from "../../offensive.js";
+const MAX_PAYLOAD_BYTES = 128;
+/**
+ * Build the `invoice_payload` string for a `sendInvoice` call. Throws
+ * `Panic` if the result would exceed Telegram's 128-byte cap — that's
+ * either a bad productKey or a userId out of bounds, both of which are
+ * bugs we want to scream about.
+ */
+export const encodePayload = (productKey, userId) => {
+    if (!productKey.length) {
+        panic("bot/payments/payload: encodePayload called with empty productKey");
+    }
+    if (!Number.isInteger(userId) || userId <= 0) {
+        panic(`bot/payments/payload: encodePayload userId must be positive integer (got ${userId})`);
+    }
+    const payload = `${productKey}|${userId}`;
+    // ASCII-only by construction (productKey shape + decimal digits), so
+    // .length === byte length. Cheap check.
+    if (payload.length > MAX_PAYLOAD_BYTES) {
+        panic(`bot/payments/payload: encoded payload ${payload.length}B exceeds Telegram's ` +
+            `${MAX_PAYLOAD_BYTES}B cap. productKey="${productKey}" userId=${userId}`);
+    }
+    return payload;
+};
+/**
+ * Decode the `invoice_payload` Telegram echoes back. Returns `undefined`
+ * (NOT throws) on malformed input — Telegram could in principle deliver
+ * a payload from a different bot version, and we want the pre_checkout
+ * handler to be able to reject it gracefully rather than crashing.
+ */
+export const decodePayload = (payload) => {
+    if (typeof payload !== "string" || payload.length === 0)
+        return undefined;
+    const idx = payload.indexOf("|");
+    if (idx <= 0 || idx === payload.length - 1)
+        return undefined;
+    const productKey = payload.slice(0, idx);
+    const userIdStr = payload.slice(idx + 1);
+    if (!/^\d+$/.test(userIdStr))
+        return undefined;
+    const userId = Number.parseInt(userIdStr, 10);
+    if (!Number.isInteger(userId) || userId <= 0)
+        return undefined;
+    return { productKey, userId };
+};
+//# sourceMappingURL=payload.js.map

package/dist/bot/payments/payload.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"payload.js","sourceRoot":"","sources":["../../../src/bot/payments/payload.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAC;AAE3C,MAAM,iBAAiB,GAAG,GAAG,CAAC;AAO9B;;;;;GAKG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,CAAC,UAAkB,EAAE,MAAc,EAAU,EAAE;IAC3E,IAAI,CAAC,UAAU,CAAC,MAAM,EAAE,CAAC;QACxB,KAAK,CAAC,kEAAkE,CAAC,CAAC;IAC3E,CAAC;IACD,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,MAAM,CAAC,IAAI,MAAM,IAAI,CAAC,EAAE,CAAC;QAC9C,KAAK,CACJ,4EAA4E,MAAM,GAAG,CACrF,CAAC;IACH,CAAC;IACD,MAAM,OAAO,GAAG,GAAG,UAAU,IAAI,MAAM,EAAE,CAAC;IAC1C,qEAAqE;IACrE,wCAAwC;IACxC,IAAI,OAAO,CAAC,MAAM,GAAG,iBAAiB,EAAE,CAAC;QACxC,KAAK,CACJ,yCAAyC,OAAO,CAAC,MAAM,uBAAuB;YAC7E,GAAG,iBAAiB,sBAAsB,UAAU,YAAY,MAAM,EAAE,CACzE,CAAC;IACH,CAAC;IACD,OAAO,OAAO,CAAC;AAChB,CAAC,CAAC;AAEF;;;;;GAKG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,CAAC,OAAe,EAA8B,EAAE;IAC5E,IAAI,OAAO,OAAO,KAAK,QAAQ,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,SAAS,CAAC;IAC1E,MAAM,GAAG,GAAG,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;IACjC,IAAI,GAAG,IAAI,CAAC,IAAI,GAAG,KAAK,OAAO,CAAC,MAAM,GAAG,CAAC;QAAE,OAAO,SAAS,CAAC;IAC7D,MAAM,UAAU,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;IACzC,MAAM,SAAS,GAAG,OAAO,CAAC,KAAK,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC;IACzC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,SAAS,CAAC;QAAE,OAAO,SAAS,CAAC;IAC/C,MAAM,MAAM,GAAG,MAAM,CAAC,QAAQ,CAAC,SAAS,EAAE,EAAE,CAAC,CAAC;IAC9C,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,MAAM,CAAC,IAAI,MAAM,IAAI,CAAC;QAAE,OAAO,SAAS,CAAC;IAC/D,OAAO,EAAE,UAAU,EAAE,MAAM,EAAE,CAAC;AAC/B,CAAC,CAAC"}

package/dist/bot/payments/payouts.d.ts

@@ -0,0 +1,88 @@
+/**
+ * Fragment payout ledger — the bot author's accounting surface.
+ *
+ * Fragment Corp redeems your accumulated XTR balance into TON paid to
+ * the configured wallet. That payout is the **income event** for
+ * Spanish autónomo IRPF purposes (CLAUDE.md §4); the per-charge log on
+ * Telegram's side is informational. We persist each payout you receive
+ * here, optionally tagged with the Spanish factura number, and provide
+ * an `export()` helper that joins charges falling in the payout's time
+ * window — that's what your gestor needs.
+ *
+ * Calling pattern (called by the bot author, NOT from inside an event
+ * handler):
+ *
+ *   import { Bot } from 'gramio'
+ *   const bot = new Bot(token); await bot.start()
+ *
+ *   // After confirming a Fragment payout to your TON wallet:
+ *   await payments.payouts.record(bot, {
+ *     ton: 12.34,
+ *     eurAtReceipt: 47.20,
+ *     fromMs: Date.parse('2026-05-01'),
+ *     toMs:   Date.parse('2026-06-01'),
+ *   })
+ *
+ *   // For the monthly gestor export:
+ *   const data = await payments.payouts.exportForUsers(bot, userIds, {
+ *     from: Date.parse('2026-05-01'),
+ *     to:   Date.parse('2026-06-01'),
+ *   })
+ *
+ * Fragment doesn't tag payouts with specific charges, so the join is
+ * **time-windowed**: payouts get `{ fromMs, toMs }` and the export
+ * pulls every `ChargeRecord` whose `receivedAt` falls inside.
+ */
+import type { AnyBot } from "gramio";
+import type { PaymentsStores } from "./stores.js";
+import type { ChargeRecord, PayoutRecord } from "./types.js";
+export type RecordPayoutInput = {
+    /** Amount of TON received from Fragment. */
+    ton: number;
+    /** EUR value at receipt time (snapshot — exchange rates move). */
+    eurAtReceipt: number;
+    /** Window covered by this payout, lower bound (ms since epoch). */
+    fromMs: number;
+    /** Window covered by this payout, upper bound (ms since epoch). */
+    toMs: number;
+    /** Optional Spanish factura number issued for this payout. */
+    facturaNumber?: string;
+    /** Override the auto-generated batchId. Default: `payout_${toMs}`. */
+    batchId?: string;
+};
+export declare const recordPayout: (bot: AnyBot, stores: PaymentsStores, input: RecordPayoutInput) => Promise<PayoutRecord>;
+export declare const listPayouts: (bot: AnyBot, stores: PaymentsStores) => Promise<PayoutRecord[]>;
+export type ExportInput = {
+    /** Window lower bound, ms since epoch. */
+    from: number;
+    /** Window upper bound, ms since epoch. */
+    to: number;
+};
+export type ExportResult = {
+    payouts: PayoutRecord[];
+    charges: ChargeRecord[];
+};
+/**
+ * Build the payout-only dataset for a time window. Returns every
+ * `PayoutRecord` whose `[fromMs, toMs]` overlaps the requested window.
+ *
+ * The `charges` field is intentionally empty — without a global charge
+ * index (v2 TODO) we can't enumerate every user's charges from one
+ * call. Use `exportPayoutsForUsers` with an explicit user-id list.
+ */
+export declare const exportPayouts: (bot: AnyBot, stores: PaymentsStores, input: ExportInput) => Promise<ExportResult>;
+/**
+ * Same as `exportPayouts` but with an explicit user-id list to scan.
+ * Pulls every NON-refunded `ChargeRecord` whose `receivedAt` falls in
+ * the requested window, joined by time rather than payout identity
+ * (Fragment doesn't expose that mapping).
+ */
+export declare const exportPayoutsForUsers: (bot: AnyBot, stores: PaymentsStores, userIds: ReadonlyArray<number>, input: ExportInput) => Promise<ExportResult>;
+export type PayoutsApi = {
+    record: (bot: AnyBot, input: RecordPayoutInput) => Promise<PayoutRecord>;
+    list: (bot: AnyBot) => Promise<PayoutRecord[]>;
+    export: (bot: AnyBot, input: ExportInput) => Promise<ExportResult>;
+    exportForUsers: (bot: AnyBot, userIds: ReadonlyArray<number>, input: ExportInput) => Promise<ExportResult>;
+};
+export declare const buildPayoutsApi: (stores: PaymentsStores) => PayoutsApi;
+//# sourceMappingURL=payouts.d.ts.map

package/dist/bot/payments/payouts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"payouts.d.ts","sourceRoot":"","sources":["../../../src/bot/payments/payouts.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAGrC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAClD,OAAO,KAAK,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAwB7D,MAAM,MAAM,iBAAiB,GAAG;IAC/B,4CAA4C;IAC5C,GAAG,EAAE,MAAM,CAAC;IACZ,kEAAkE;IAClE,YAAY,EAAE,MAAM,CAAC;IACrB,mEAAmE;IACnE,MAAM,EAAE,MAAM,CAAC;IACf,mEAAmE;IACnE,IAAI,EAAE,MAAM,CAAC;IACb,8DAA8D;IAC9D,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,sEAAsE;IACtE,OAAO,CAAC,EAAE,MAAM,CAAC;CACjB,CAAC;AAyBF,eAAO,MAAM,YAAY,GACxB,KAAK,MAAM,EACX,QAAQ,cAAc,EACtB,OAAO,iBAAiB,KACtB,OAAO,CAAC,YAAY,CAMtB,CAAC;AAEF,eAAO,MAAM,WAAW,GACvB,KAAK,MAAM,EACX,QAAQ,cAAc,KACpB,OAAO,CAAC,YAAY,EAAE,CAOxB,CAAC;AAEF,MAAM,MAAM,WAAW,GAAG;IACzB,0CAA0C;IAC1C,IAAI,EAAE,MAAM,CAAC;IACb,0CAA0C;IAC1C,EAAE,EAAE,MAAM,CAAC;CACX,CAAC;AAEF,MAAM,MAAM,YAAY,GAAG;IAC1B,OAAO,EAAE,YAAY,EAAE,CAAC;IACxB,OAAO,EAAE,YAAY,EAAE,CAAC;CACxB,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,aAAa,GACzB,KAAK,MAAM,EACX,QAAQ,cAAc,EACtB,OAAO,WAAW,KAChB,OAAO,CAAC,YAAY,CAWtB,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,qBAAqB,GACjC,KAAK,MAAM,EACX,QAAQ,cAAc,EACtB,SAAS,aAAa,CAAC,MAAM,CAAC,EAC9B,OAAO,WAAW,KAChB,OAAO,CAAC,YAAY,CAqBtB,CAAC;AAIF,MAAM,MAAM,UAAU,GAAG;IACxB,MAAM,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,iBAAiB,KAAK,OAAO,CAAC,YAAY,CAAC,CAAC;IACzE,IAAI,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,YAAY,EAAE,CAAC,CAAC;IAC/C,MAAM,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,WAAW,KAAK,OAAO,CAAC,YAAY,CAAC,CAAC;IACnE,cAAc,EAAE,CACf,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,aAAa,CAAC,MAAM,CAAC,EAC9B,KAAK,EAAE,WAAW,KACd,OAAO,CAAC,YAAY,CAAC,CAAC;CAC3B,CAAC;AAEF,eAAO,MAAM,eAAe,GAAI,QAAQ,cAAc,KAAG,UAMvD,CAAC"}

package/dist/bot/payments/payouts.js

@@ -0,0 +1,133 @@
+/**
+ * Fragment payout ledger — the bot author's accounting surface.
+ *
+ * Fragment Corp redeems your accumulated XTR balance into TON paid to
+ * the configured wallet. That payout is the **income event** for
+ * Spanish autónomo IRPF purposes (CLAUDE.md §4); the per-charge log on
+ * Telegram's side is informational. We persist each payout you receive
+ * here, optionally tagged with the Spanish factura number, and provide
+ * an `export()` helper that joins charges falling in the payout's time
+ * window — that's what your gestor needs.
+ *
+ * Calling pattern (called by the bot author, NOT from inside an event
+ * handler):
+ *
+ *   import { Bot } from 'gramio'
+ *   const bot = new Bot(token); await bot.start()
+ *
+ *   // After confirming a Fragment payout to your TON wallet:
+ *   await payments.payouts.record(bot, {
+ *     ton: 12.34,
+ *     eurAtReceipt: 47.20,
+ *     fromMs: Date.parse('2026-05-01'),
+ *     toMs:   Date.parse('2026-06-01'),
+ *   })
+ *
+ *   // For the monthly gestor export:
+ *   const data = await payments.payouts.exportForUsers(bot, userIds, {
+ *     from: Date.parse('2026-05-01'),
+ *     to:   Date.parse('2026-06-01'),
+ *   })
+ *
+ * Fragment doesn't tag payouts with specific charges, so the join is
+ * **time-windowed**: payouts get `{ fromMs, toMs }` and the export
+ * pulls every `ChargeRecord` whose `receivedAt` falls inside.
+ */
+import { panic } from "../../offensive.js";
+// ─── adapter for the offline-call shape ────────────────────────────
+/**
+ * Construct the `BotIdCtx` shape `bot/storage` needs when called outside
+ * an event (just `{ bot: { info: bot.info } }`). Mirrors the
+ * `simulateAccessRequest` pattern in `access-control.ts`.
+ *
+ * Throws if the bot's `info` isn't populated yet — usually because the
+ * caller forgot to `await bot.start()` (or `bot.init()`) first.
+ */
+const ctxFor = (bot) => {
+    const info = bot.info;
+    if (!info) {
+        panic("bot/payments/payouts: bot.info is undefined — call bot.start() (or bot.init()) first");
+    }
+    return { bot: { info } };
+};
+const buildPayoutRecord = (input) => {
+    if (input.ton <= 0)
+        panic(`bot/payments/payouts: ton must be positive (got ${input.ton})`);
+    if (input.eurAtReceipt < 0)
+        panic(`bot/payments/payouts: eurAtReceipt must be >= 0 (got ${input.eurAtReceipt})`);
+    if (input.fromMs >= input.toMs)
+        panic(`bot/payments/payouts: fromMs must be < toMs (got ${input.fromMs} / ${input.toMs})`);
+    const batchId = input.batchId ?? `payout_${input.toMs}`;
+    return {
+        batchId,
+        fromMs: input.fromMs,
+        toMs: input.toMs,
+        tonAmount: input.ton,
+        eurAtReceipt: input.eurAtReceipt,
+        recordedAt: Date.now(),
+        facturaNumber: input.facturaNumber,
+    };
+};
+export const recordPayout = async (bot, stores, input) => {
+    const ctx = ctxFor(bot);
+    const record = buildPayoutRecord(input);
+    await stores.payouts.set(ctx, record.batchId, record);
+    await stores.payoutsIndex.prepend(ctx, record.batchId);
+    return record;
+};
+export const listPayouts = async (bot, stores) => {
+    const ctx = ctxFor(bot);
+    const ids = await stores.payoutsIndex.list(ctx);
+    const records = await Promise.all(ids.map((id) => stores.payouts.get(ctx, id)));
+    return records.filter((r) => r !== undefined);
+};
+/**
+ * Build the payout-only dataset for a time window. Returns every
+ * `PayoutRecord` whose `[fromMs, toMs]` overlaps the requested window.
+ *
+ * The `charges` field is intentionally empty — without a global charge
+ * index (v2 TODO) we can't enumerate every user's charges from one
+ * call. Use `exportPayoutsForUsers` with an explicit user-id list.
+ */
+export const exportPayouts = async (bot, stores, input) => {
+    if (input.from >= input.to) {
+        panic(`bot/payments/payouts: export from must be < to (got ${input.from} / ${input.to})`);
+    }
+    const allPayouts = await listPayouts(bot, stores);
+    const payouts = allPayouts.filter((p) => !(p.toMs < input.from || p.fromMs > input.to));
+    return { payouts, charges: [] };
+};
+/**
+ * Same as `exportPayouts` but with an explicit user-id list to scan.
+ * Pulls every NON-refunded `ChargeRecord` whose `receivedAt` falls in
+ * the requested window, joined by time rather than payout identity
+ * (Fragment doesn't expose that mapping).
+ */
+export const exportPayoutsForUsers = async (bot, stores, userIds, input) => {
+    const ctx = ctxFor(bot);
+    const allPayouts = await listPayouts(bot, stores);
+    const payouts = allPayouts.filter((p) => !(p.toMs < input.from || p.fromMs > input.to));
+    const allCharges = [];
+    for (const userId of userIds) {
+        const chargeIds = await stores.userCharges(userId).list(ctx);
+        for (const cid of chargeIds) {
+            const c = await stores.charges.get(ctx, cid);
+            if (!c)
+                continue;
+            if (c.paysupportState === "refunded")
+                continue;
+            if (c.receivedAt >= input.from && c.receivedAt <= input.to) {
+                allCharges.push(c);
+            }
+        }
+    }
+    allCharges.sort((a, b) => a.receivedAt - b.receivedAt);
+    return { payouts, charges: allCharges };
+};
+export const buildPayoutsApi = (stores) => ({
+    record: (bot, input) => recordPayout(bot, stores, input),
+    list: (bot) => listPayouts(bot, stores),
+    export: (bot, input) => exportPayouts(bot, stores, input),
+    exportForUsers: (bot, userIds, input) => exportPayoutsForUsers(bot, stores, userIds, input),
+});
+//# sourceMappingURL=payouts.js.map

package/dist/bot/payments/payouts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"payouts.js","sourceRoot":"","sources":["../../../src/bot/payments/payouts.ts"],"names":[],"mappings":"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"}

package/dist/bot/payments/plugin.d.ts

@@ -0,0 +1,271 @@
+/**
+ * `botPayments({...})` — the top-level factory + GramIO plugin
+ * assembly.
+ *
+ * This file is **wiring only** per `bot/CLAUDE.md` § plugin file
+ * convention. Every handler body lives in its concern-specific
+ * neighbour (`derive.ts` / `handlers.ts` / `callbacks.ts` /
+ * `commands.ts` / `refund.ts`); this file's job is to stitch them
+ * into a `Plugin` chain.
+ *
+ * What gets wired:
+ *
+ *   - `ctx.payments.*` surface via `.derive()`        →  `derive.ts`
+ *   - `pre_checkout_query` handler                    →  `handlers.ts`
+ *   - `successful_payment` (dedicated event)          →  `handlers.ts`
+ *   - Waiver consent / cancel callbacks               →  `callbacks.ts` + `waiver.ts`
+ *   - Refund request / approve / deny / close         →  `callbacks.ts` + `refund.ts`
+ *   - `/paysupport` slash command                     →  `commands.ts`
+ *
+ * Returned alongside the plugin: `menuItem` (drop-in for `botMenu`),
+ * `payouts` (Fragment ledger), `admin` (read helpers for custom
+ * admin commands), and `onFulfilled` (event hook registration).
+ *
+ * See `CLAUDE.md` in this folder for the design rationale and flows.
+ */
+import type { session } from "@gramio/session";
+import type { Storage } from "@gramio/storage";
+import { type DeriveDefinitions, Plugin } from "gramio";
+import { buildCatalog } from "./config.js";
+import { type PaymentsDerived } from "./derive.js";
+import { buildPaymentsMenuItem } from "./menu-item.js";
+import { type PayoutsApi } from "./payouts.js";
+import { type PaymentsStores } from "./stores.js";
+import type { AtLeastKey, BotPaymentsConfig, ChargeRecord, FulfillmentEvent, PaymentsSession, ProductKey, TierKey } from "./types.js";
+type SessionLike = {
+    pay?: PaymentsSession;
+    language?: string;
+};
+type PaySessionPluginRef = ReturnType<typeof session<SessionLike, "session">>;
+type TierFn<Cfg extends BotPaymentsConfig<string>> = (() => TierKey<Cfg>) & {
+    level: () => number;
+    /**
+     * Resolved display label of the current rung in `ctx.session.language`,
+     * or `undefined` on free tier. Named `label` (not `name`) because
+     * `Function.prototype.name` is read-only in strict mode and we attach
+     * this onto a callable.
+     */
+    label: () => string | undefined;
+};
+export type PaymentsCtx<Cfg extends BotPaymentsConfig<string>> = {
+    atLeast: (id: AtLeastKey<Cfg>) => boolean;
+    tier: TierFn<Cfg>;
+    has: (perkId: string) => boolean;
+    credits: PaymentsDerived["credits"];
+    require: (id: AtLeastKey<Cfg>, opts?: {
+        feature?: {
+            en: string;
+            es: string;
+        } | string;
+    }) => Promise<boolean>;
+    invoice: (productKey: ProductKey<Cfg>) => Promise<"invoice_sent" | "waiver_prompt_sent" | "unknown_product">;
+};
+/**
+ * Admin-side read helpers exposed on `payments.admin.*`. Bot authors
+ * use these when writing custom admin commands (e.g. `/refunds`) that
+ * bypass the user-initiated refund-request flow. ctx only needs
+ * `.bot.info.id` for namespacing — pass any real gramio ctx or a
+ * synthetic `{ bot: { info: bot.info } }` for offline scripts.
+ */
+export type PaymentsAdmin = {
+    /** Every non-pruned charge for a user, newest-first. */
+    listCharges: (ctx: {
+        bot: {
+            info: {
+                id: number;
+            };
+        };
+    }, userId: number) => Promise<ReadonlyArray<ChargeRecord>>;
+    /** One charge by id; `undefined` if not found. */
+    getCharge: (ctx: {
+        bot: {
+            info: {
+                id: number;
+            };
+        };
+    }, chargeId: string) => Promise<ChargeRecord | undefined>;
+};
+export type BotPaymentsResult<Cfg extends BotPaymentsConfig<string>> = {
+    plugin: ReturnType<typeof buildPlugin>;
+    menuItem: ReturnType<typeof buildPaymentsMenuItem>;
+    payouts: PayoutsApi;
+    admin: PaymentsAdmin;
+    onFulfilled: (productKey: ProductKey<Cfg> | "*", handler: (event: FulfillmentEvent, ctx: unknown) => void) => void;
+};
+export type BotPaymentsOptions<Cfg extends BotPaymentsConfig<string>> = Cfg & {
+    /** Shared session plugin. Required — see CLAUDE.md §"Storage layout". */
+    session: PaySessionPluginRef;
+    /**
+     * Storage backend for the global ledger (charges, payouts, refunds,
+     * idempotency). MUST be the same instance backing `session`.
+     */
+    storage: Storage;
+};
+declare const buildPlugin: (args: {
+    cfg: BotPaymentsConfig<string>;
+    catalog: ReturnType<typeof buildCatalog>;
+    sessionPlugin: PaySessionPluginRef;
+    storage: Storage;
+    stores: PaymentsStores;
+    onFulfilledMap: Map<string, Array<(event: FulfillmentEvent, ctx: unknown) => void>>;
+}) => Plugin<Record<string, never>, DeriveDefinitions & {
+    global: {
+        payments: PaymentsCtx<BotPaymentsConfig<string>>;
+    };
+} & {
+    message: {
+        session: SessionLike & {
+            $clear: () => Promise<void>;
+        };
+    };
+    channel_post: {
+        session: SessionLike & {
+            $clear: () => Promise<void>;
+        };
+    };
+    inline_query: {
+        session: SessionLike & {
+            $clear: () => Promise<void>;
+        };
+    };
+    chosen_inline_result: {
+        session: SessionLike & {
+            $clear: () => Promise<void>;
+        };
+    };
+    callback_query: {
+        session: SessionLike & {
+            $clear: () => Promise<void>;
+        };
+    };
+    shipping_query: {
+        session: SessionLike & {
+            $clear: () => Promise<void>;
+        };
+    };
+    pre_checkout_query: {
+        session: SessionLike & {
+            $clear: () => Promise<void>;
+        };
+    };
+    poll_answer: {
+        session: SessionLike & {
+            $clear: () => Promise<void>;
+        };
+    };
+    chat_join_request: {
+        session: SessionLike & {
+            $clear: () => Promise<void>;
+        };
+    };
+    new_chat_members: {
+        session: SessionLike & {
+            $clear: () => Promise<void>;
+        };
+    };
+    new_chat_title: {
+        session: SessionLike & {
+            $clear: () => Promise<void>;
+        };
+    };
+    new_chat_photo: {
+        session: SessionLike & {
+            $clear: () => Promise<void>;
+        };
+    };
+    delete_chat_photo: {
+        session: SessionLike & {
+            $clear: () => Promise<void>;
+        };
+    };
+    group_chat_created: {
+        session: SessionLike & {
+            $clear: () => Promise<void>;
+        };
+    };
+    message_auto_delete_timer_changed: {
+        session: SessionLike & {
+            $clear: () => Promise<void>;
+        };
+    };
+    migrate_to_chat_id: {
+        session: SessionLike & {
+            $clear: () => Promise<void>;
+        };
+    };
+    migrate_from_chat_id: {
+        session: SessionLike & {
+            $clear: () => Promise<void>;
+        };
+    };
+    pinned_message: {
+        session: SessionLike & {
+            $clear: () => Promise<void>;
+        };
+    };
+    invoice: {
+        session: SessionLike & {
+            $clear: () => Promise<void>;
+        };
+    };
+    successful_payment: {
+        session: SessionLike & {
+            $clear: () => Promise<void>;
+        };
+    };
+    chat_shared: {
+        session: SessionLike & {
+            $clear: () => Promise<void>;
+        };
+    };
+    proximity_alert_triggered: {
+        session: SessionLike & {
+            $clear: () => Promise<void>;
+        };
+    };
+    video_chat_scheduled: {
+        session: SessionLike & {
+            $clear: () => Promise<void>;
+        };
+    };
+    video_chat_started: {
+        session: SessionLike & {
+            $clear: () => Promise<void>;
+        };
+    };
+    video_chat_ended: {
+        session: SessionLike & {
+            $clear: () => Promise<void>;
+        };
+    };
+    video_chat_participants_invited: {
+        session: SessionLike & {
+            $clear: () => Promise<void>;
+        };
+    };
+    web_app_data: {
+        session: SessionLike & {
+            $clear: () => Promise<void>;
+        };
+    };
+    location: {
+        session: SessionLike & {
+            $clear: () => Promise<void>;
+        };
+    };
+    passport_data: {
+        session: SessionLike & {
+            $clear: () => Promise<void>;
+        };
+    };
+} & {
+    message: {
+        payments: PaymentsCtx<BotPaymentsConfig<string>>;
+    };
+    callback_query: {
+        payments: PaymentsCtx<BotPaymentsConfig<string>>;
+    };
+}, {}>;
+export declare const botPayments: <const Cfg extends BotPaymentsConfig<string>>(opts: BotPaymentsOptions<Cfg>) => BotPaymentsResult<Cfg>;
+export {};
+//# sourceMappingURL=plugin.d.ts.map

package/dist/bot/payments/plugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../../../src/bot/payments/plugin.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,iBAAiB,CAAC;AAC/C,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,iBAAiB,CAAC;AAC/C,OAAO,EAAE,KAAK,iBAAiB,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAUxD,OAAO,EAAE,YAAY,EAAkB,MAAM,aAAa,CAAC;AAC3D,OAAO,EAAuB,KAAK,eAAe,EAAE,MAAM,aAAa,CAAC;AAKxE,OAAO,EAAE,qBAAqB,EAAE,MAAM,gBAAgB,CAAC;AACvD,OAAO,EAAmB,KAAK,UAAU,EAAE,MAAM,cAAc,CAAC;AAUhE,OAAO,EAAe,KAAK,cAAc,EAAE,MAAM,aAAa,CAAC;AAC/D,OAAO,KAAK,EACX,UAAU,EACV,iBAAiB,EACjB,YAAY,EACZ,gBAAgB,EAChB,eAAe,EACf,UAAU,EACV,OAAO,EACP,MAAM,YAAY,CAAC;AAKpB,KAAK,WAAW,GAAG;IAAE,GAAG,CAAC,EAAE,eAAe,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAChE,KAAK,mBAAmB,GAAG,UAAU,CAAC,OAAO,OAAO,CAAC,WAAW,EAAE,SAAS,CAAC,CAAC,CAAC;AAW9E,KAAK,MAAM,CAAC,GAAG,SAAS,iBAAiB,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,OAAO,CAAC,GAAG,CAAC,CAAC,GAAG;IAC3E,KAAK,EAAE,MAAM,MAAM,CAAC;IACpB;;;;;OAKG;IACH,KAAK,EAAE,MAAM,MAAM,GAAG,SAAS,CAAC;CAChC,CAAC;AAEF,MAAM,MAAM,WAAW,CAAC,GAAG,SAAS,iBAAiB,CAAC,MAAM,CAAC,IAAI;IAChE,OAAO,EAAE,CAAC,EAAE,EAAE,UAAU,CAAC,GAAG,CAAC,KAAK,OAAO,CAAC;IAC1C,IAAI,EAAE,MAAM,CAAC,GAAG,CAAC,CAAC;IAClB,GAAG,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC;IACjC,OAAO,EAAE,eAAe,CAAC,SAAS,CAAC,CAAC;IACpC,OAAO,EAAE,CACR,EAAE,EAAE,UAAU,CAAC,GAAG,CAAC,EACnB,IAAI,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE;YAAE,EAAE,EAAE,MAAM,CAAC;YAAC,EAAE,EAAE,MAAM,CAAA;SAAE,GAAG,MAAM,CAAA;KAAE,KACpD,OAAO,CAAC,OAAO,CAAC,CAAC;IACtB,OAAO,EAAE,CACR,UAAU,EAAE,UAAU,CAAC,GAAG,CAAC,KACvB,OAAO,CAAC,cAAc,GAAG,oBAAoB,GAAG,iBAAiB,CAAC,CAAC;CACxE,CAAC;AAIF;;;;;;GAMG;AACH,MAAM,MAAM,aAAa,GAAG;IAC3B,wDAAwD;IACxD,WAAW,EAAE,CACZ,GAAG,EAAE;QAAE,GAAG,EAAE;YAAE,IAAI,EAAE;gBAAE,EAAE,EAAE,MAAM,CAAA;aAAE,CAAA;SAAE,CAAA;KAAE,EACtC,MAAM,EAAE,MAAM,KACV,OAAO,CAAC,aAAa,CAAC,YAAY,CAAC,CAAC,CAAC;IAC1C,kDAAkD;IAClD,SAAS,EAAE,CACV,GAAG,EAAE;QAAE,GAAG,EAAE;YAAE,IAAI,EAAE;gBAAE,EAAE,EAAE,MAAM,CAAA;aAAE,CAAA;SAAE,CAAA;KAAE,EACtC,QAAQ,EAAE,MAAM,KACZ,OAAO,CAAC,YAAY,GAAG,SAAS,CAAC,CAAC;CACvC,CAAC;AAEF,MAAM,MAAM,iBAAiB,CAAC,GAAG,SAAS,iBAAiB,CAAC,MAAM,CAAC,IAAI;IACtE,MAAM,EAAE,UAAU,CAAC,OAAO,WAAW,CAAC,CAAC;IACvC,QAAQ,EAAE,UAAU,CAAC,OAAO,qBAAqB,CAAC,CAAC;IACnD,OAAO,EAAE,UAAU,CAAC;IACpB,KAAK,EAAE,aAAa,CAAC;IACrB,WAAW,EAAE,CACZ,UAAU,EAAE,UAAU,CAAC,GAAG,CAAC,GAAG,GAAG,EACjC,OAAO,EAAE,CAAC,KAAK,EAAE,gBAAgB,EAAE,GAAG,EAAE,OAAO,KAAK,IAAI,KACpD,IAAI,CAAC;CACV,CAAC;AAIF,MAAM,MAAM,kBAAkB,CAAC,GAAG,SAAS,iBAAiB,CAAC,MAAM,CAAC,IAAI,GAAG,GAAG;IAC7E,yEAAyE;IACzE,OAAO,EAAE,mBAAmB,CAAC;IAC7B;;;OAGG;IACH,OAAO,EAAE,OAAO,CAAC;CACjB,CAAC;AAIF,QAAA,MAAM,WAAW,GAAI,MAAM;IAC1B,GAAG,EAAE,iBAAiB,CAAC,MAAM,CAAC,CAAC;IAC/B,OAAO,EAAE,UAAU,CAAC,OAAO,YAAY,CAAC,CAAC;IACzC,aAAa,EAAE,mBAAmB,CAAC;IACnC,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,EAAE,cAAc,CAAC;IACvB,cAAc,EAAE,GAAG,CAClB,MAAM,EACN,KAAK,CAAC,CAAC,KAAK,EAAE,gBAAgB,EAAE,GAAG,EAAE,OAAO,KAAK,IAAI,CAAC,CACtD,CAAC;CACF;;kBAIiC,WAAW,CAAC,iBAAiB,CAAC,MAAM,CAAC,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;kBAAtC,WAAW,CAAC,iBAAiB,CAAC,MAAM,CAAC,CAAC;;;kBAAtC,WAAW,CAAC,iBAAiB,CAAC,MAAM,CAAC,CAAC;;MAuFvE,CAAC;AAIF,eAAO,MAAM,WAAW,GAAI,KAAK,CAAC,GAAG,SAAS,iBAAiB,CAAC,MAAM,CAAC,EACtE,MAAM,kBAAkB,CAAC,GAAG,CAAC,KAC3B,iBAAiB,CAAC,GAAG,CAmDvB,CAAC"}