@adriangalilea/utils 0.17.1 → 0.19.0

package/dist/bot/payments/invoice.js

@@ -0,0 +1,213 @@
+/**
+ * `sendInvoice` wrappers — one per product kind, plus the high-level
+ * `presentInvoice` entry that the `ctx.payments.invoice(...)` surface
+ * routes to.
+ *
+ * Stars-only by design (see CLAUDE.md §1, §2). Every invoice goes out
+ * with `currency: 'XTR'` and `provider_token: ""` — Telegram rejects
+ * provider_token for XTR. The `prices` array must contain exactly one
+ * `LabeledPrice` for XTR per the Bot API docs.
+ *
+ * The function calls `bot.api.sendInvoice` directly (not `ctx.sendInvoice`)
+ * so the same path works from both message and callback_query contexts
+ * — `message_thread_id` is plumbed explicitly so threaded replies land
+ * in the right thread regardless of which mixin would otherwise inject it.
+ *
+ * https://core.telegram.org/bots/api#sendinvoice
+ * https://core.telegram.org/bots/payments-stars
+ */
+import { panic, SourcedError } from "../../offensive.js";
+import { say } from "../../say/index.js";
+import { createLogger } from "../../universal/log.js";
+import { encodePayload } from "./payload.js";
+import { renderConsentBody, waiverKeyboard } from "./waiver.js";
+const log = createLogger("bot/payments");
+// Telegram caps from the Bot API (sendInvoice §):
+const TITLE_MAX = 32;
+const DESCRIPTION_MAX = 255;
+const FALLBACK_LANG = "en";
+// ─── small helpers ─────────────────────────────────────────────────
+const ctxLang = (ctx) => ctx.session?.language ?? FALLBACK_LANG;
+const ctxChatId = (ctx) => {
+    const id = ctx.chat?.id ?? ctx.message?.chat?.id;
+    if (id === undefined) {
+        panic("bot/payments/invoice: ctx is missing chat.id (neither top-level nor message.chat)");
+    }
+    return id;
+};
+const ctxThreadId = (ctx) => ctx.threadId ?? ctx.message?.threadId;
+/**
+ * Resolve a Polyglot to a single string with a fallback chain. Trims
+ * + caps at `maxLen`.
+ */
+const resolveLabel = (value, lang, maxLen) => {
+    if (!value)
+        return undefined;
+    const v = value[lang] ?? value[FALLBACK_LANG] ?? Object.values(value)[0];
+    if (typeof v !== "string")
+        return undefined;
+    const trimmed = v.trim();
+    return trimmed.length > maxLen ? trimmed.slice(0, maxLen) : trimmed;
+};
+// ─── title / description per product kind ──────────────────────────
+const titleFor = (product, cfg, lang) => {
+    if (product.id.startsWith("vip.")) {
+        return (resolveLabel(product.name, lang, TITLE_MAX) ??
+            say({ en: "VIP", es: "VIP" }, lang));
+    }
+    if (product.id.startsWith("credits.")) {
+        const p = product;
+        const explicit = resolveLabel(p.name, lang, TITLE_MAX);
+        if (explicit)
+            return explicit;
+        const unit = resolveLabel(cfg.credits?.unit, lang, 32) ??
+            "credits";
+        // "100 credits" / "100 mensajes" — fits in 32 chars for reasonable values.
+        const base = `${p.creditsGranted} ${unit}`;
+        return base.length > TITLE_MAX ? base.slice(0, TITLE_MAX) : base;
+    }
+    // perk
+    return (resolveLabel(product.name, lang, TITLE_MAX) ??
+        product.key);
+};
+const descriptionFor = (product, cfg, lang) => {
+    if (product.id.startsWith("vip.")) {
+        const v = product;
+        const name = resolveLabel(v.name, lang, 24) ?? say({ en: "VIP", es: "VIP" }, lang);
+        const baseEn = `30 days of ${name} access`;
+        const baseEs = `30 días de acceso ${name}`;
+        const base = say({ en: baseEn, es: baseEs }, lang);
+        if (v.creditsGranted > 0) {
+            const unit = resolveLabel(cfg.credits?.unit, lang, 24) ??
+                "credits";
+            const tailEn = `. Includes ${v.creditsGranted} ${unit} per month.`;
+            const tailEs = `. Incluye ${v.creditsGranted} ${unit} al mes.`;
+            const tail = say({ en: tailEn, es: tailEs }, lang);
+            const full = base + tail;
+            return full.length > DESCRIPTION_MAX
+                ? full.slice(0, DESCRIPTION_MAX)
+                : full;
+        }
+        return base.length > DESCRIPTION_MAX
+            ? base.slice(0, DESCRIPTION_MAX)
+            : base;
+    }
+    if (product.id.startsWith("credits.")) {
+        const p = product;
+        const unit = resolveLabel(cfg.credits?.unit, lang, 24) ??
+            "credits";
+        const base = say({
+            en: `Top up your balance by ${p.creditsGranted} ${unit}.`,
+            es: `Recarga tu saldo con ${p.creditsGranted} ${unit}.`,
+        }, lang);
+        return base.length > DESCRIPTION_MAX
+            ? base.slice(0, DESCRIPTION_MAX)
+            : base;
+    }
+    // perk
+    const p = product;
+    const name = resolveLabel(p.name, lang, 24) ?? p.key;
+    const base = say({
+        en: `Unlock ${name} — one-time.`,
+        es: `Desbloquear ${name} — único pago.`,
+    }, lang);
+    return base.length > DESCRIPTION_MAX ? base.slice(0, DESCRIPTION_MAX) : base;
+};
+// ─── core send ─────────────────────────────────────────────────────
+/**
+ * Issue a Telegram Stars invoice for `product`. Caller is expected to
+ * have already cleared waiver consent — `presentInvoice` (the public
+ * entry) handles that gate. This function does the wire call only.
+ *
+ * Wraps Telegram-side failures in a typed `SourcedError({ source:
+ * 'telegram', operation: 'sendInvoice' })` so the catch boundary in
+ * `plugin.ts` can render a localized fallback message.
+ */
+export const sendInvoiceForProduct = async (ctx, cfg, product, userId) => {
+    const lang = ctxLang(ctx);
+    const chatId = ctxChatId(ctx);
+    const threadId = ctxThreadId(ctx);
+    const title = titleFor(product, cfg, lang);
+    const description = descriptionFor(product, cfg, lang);
+    const payload = encodePayload(product.id, userId);
+    const priceLabel = resolveLabel(product.name, lang, 32) ??
+        title;
+    const params = {
+        chat_id: chatId,
+        ...(threadId !== undefined && { message_thread_id: threadId }),
+        title,
+        description,
+        payload,
+        provider_token: "", // XTR — must be empty
+        currency: "XTR",
+        prices: [{ label: priceLabel, amount: product.xtr }],
+    };
+    if (product.id.startsWith("vip.")) {
+        params.subscription_period = product.periodSeconds;
+    }
+    log.event(`sendInvoice → telegram: product=${product.id} user=${userId} xtr=${product.xtr} title="${title}" subscription_period=${params.subscription_period ?? "none"}`);
+    try {
+        await ctx.bot.api.sendInvoice(params);
+        log.success(`sendInvoice accepted by telegram: product=${product.id} user=${userId}`);
+    }
+    catch (e) {
+        const msg = e instanceof Error ? e.message : String(e);
+        log.error(`sendInvoice rejected by telegram: ${msg}`);
+        // Hint on the specific subscription-export setup gotcha — there's
+        // no documented fix path in gramio/telegram docs, so surface ours.
+        if (msg.includes("SUBSCRIPTION_EXPORT_MISSING")) {
+            log.warn("hint: open BotFather → /mybots → your bot → Bot Settings → Star Subscriptions and link a Fragment payout method before sending subscription invoices");
+        }
+        throw new SourcedError({
+            source: "telegram",
+            operation: "sendInvoice",
+            message: msg,
+            cause: e,
+            context: { productKey: product.id, userId, chatId, threadId },
+        });
+    }
+};
+/**
+ * High-level entry for `ctx.payments.invoice(productKey)`.
+ *
+ * Validates the productKey against the catalog, gates on waiver
+ * freshness, and either:
+ *
+ *   - sends the consent prompt (one-tap "✅ Consiento" button carrying
+ *     the productKey, so the user resumes the purchase on tap), OR
+ *   - calls `sendInvoiceForProduct` directly when consent is already
+ *     fresh.
+ *
+ * Returns a discriminated tag so callers can branch on what the user
+ * saw — useful for `require()`-style helpers.
+ */
+export const presentInvoice = async (ctx, cfg, catalog, productKey) => {
+    const product = catalog.byKey.get(productKey);
+    if (!product) {
+        log.warn(`presentInvoice unknown productKey "${productKey}"`);
+        const lang = ctxLang(ctx);
+        await ctx.send(say({
+            en: `❌ Unknown product "${productKey}".`,
+            es: `❌ Producto desconocido "${productKey}".`,
+        }, lang));
+        return "unknown_product";
+    }
+    const userId = ctx.from?.id;
+    if (!userId) {
+        panic("bot/payments/invoice: presentInvoice called with no ctx.from.id");
+    }
+    const stored = ctx.session?.pay?.waiver;
+    const fresh = stored && stored.version === cfg.waiver.version;
+    if (!fresh) {
+        log.info(`presentInvoice: waiver ${stored ? `stale (${stored.version} ≠ ${cfg.waiver.version})` : "missing"} — sending consent prompt for ${product.id} user=${userId}`);
+        const lang = ctxLang(ctx);
+        await ctx.send(renderConsentBody(cfg, lang), {
+            reply_markup: waiverKeyboard(cfg, product.id, lang),
+        });
+        return "waiver_prompt_sent";
+    }
+    log.info(`presentInvoice: waiver fresh — going straight to sendInvoice for ${product.id} user=${userId}`);
+    await sendInvoiceForProduct(ctx, cfg, product, userId);
+    return "invoice_sent";
+};
+//# sourceMappingURL=invoice.js.map

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

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

package/dist/bot/payments/menu-item.d.ts

@@ -0,0 +1,41 @@
+/**
+ * `payments.menuItem` — single drop-in entry for `botMenu({ items: […] })`.
+ *
+ * Label, style, and submenu adapt to the user's current state via live
+ * resolvers reading `ctx.session.pay.*` (see `bot/CLAUDE.md` § "Snapshot
+ * vs live derives"). The plugin owns the whole submenu — bot author
+ * just adds `payments.menuItem` to their items array.
+ *
+ * Submenu shape (v1):
+ *
+ *   /settings → 💎 VIP
+ *   ├── ── tier cards ──
+ *   │   [💎 VIP — 500 ⭐]               buy / current state via style
+ *   │   [🌟 VIP Max — 2000 ⭐]
+ *   ├── ── credits packs (if axis used) ──
+ *   │   [💬 +100 — 100 ⭐]
+ *   │   [💬 +500 — 400 ⭐]
+ *   ├── ── perks (if axis used) ──
+ *   │   [🎁 Voice mode — 1500 ⭐]      hidden when owned
+ *   ├── ── manage (when vip active) ──
+ *   │   [⛔ Cancel renewal]            or [↩️ Resume renewal] when canceled
+ *   ├── 💬 Help / refunds → ctx.send(paysupport blurb)
+ *   ├── ⬅️ Back  ✖️ Close             (botMenu auto-renders these in submenus)
+ *
+ * What's deliberately NOT here yet:
+ *
+ *   - Per-charge **History** view + in-menu refund request. The compliance
+ *     surface (`/paysupport` + admin-mediated refund) is fulfilled by
+ *     the admin commands and the message-side flow in `refund.ts`. The
+ *     history UI is a v2 follow-up (see CLAUDE.md §"Open follow-ups").
+ *
+ *   - Deep-link `require()` → exact rung. v1 opens VIP root; deep-linking
+ *     needs menu-state encoding in callback data.
+ */
+import type { MenuItem } from "../menu.js";
+import type { BotPaymentsConfig, ProductCatalog } from "./types.js";
+export declare const buildPaymentsMenuItem: (args: {
+    cfg: BotPaymentsConfig<string>;
+    catalog: ProductCatalog;
+}) => MenuItem;
+//# sourceMappingURL=menu-item.d.ts.map

package/dist/bot/payments/menu-item.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"menu-item.d.ts","sourceRoot":"","sources":["../../../src/bot/payments/menu-item.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAIH,OAAO,KAAK,EAAW,QAAQ,EAAE,MAAM,YAAY,CAAC;AAEpD,OAAO,KAAK,EACX,iBAAiB,EAEjB,cAAc,EACd,MAAM,YAAY,CAAC;AAiCpB,eAAO,MAAM,qBAAqB,GAAI,MAAM;IAC3C,GAAG,EAAE,iBAAiB,CAAC,MAAM,CAAC,CAAC;IAC/B,OAAO,EAAE,cAAc,CAAC;CACxB,KAAG,QAqRH,CAAC"}

package/dist/bot/payments/menu-item.js

@@ -0,0 +1,259 @@
+/**
+ * `payments.menuItem` — single drop-in entry for `botMenu({ items: […] })`.
+ *
+ * Label, style, and submenu adapt to the user's current state via live
+ * resolvers reading `ctx.session.pay.*` (see `bot/CLAUDE.md` § "Snapshot
+ * vs live derives"). The plugin owns the whole submenu — bot author
+ * just adds `payments.menuItem` to their items array.
+ *
+ * Submenu shape (v1):
+ *
+ *   /settings → 💎 VIP
+ *   ├── ── tier cards ──
+ *   │   [💎 VIP — 500 ⭐]               buy / current state via style
+ *   │   [🌟 VIP Max — 2000 ⭐]
+ *   ├── ── credits packs (if axis used) ──
+ *   │   [💬 +100 — 100 ⭐]
+ *   │   [💬 +500 — 400 ⭐]
+ *   ├── ── perks (if axis used) ──
+ *   │   [🎁 Voice mode — 1500 ⭐]      hidden when owned
+ *   ├── ── manage (when vip active) ──
+ *   │   [⛔ Cancel renewal]            or [↩️ Resume renewal] when canceled
+ *   ├── 💬 Help / refunds → ctx.send(paysupport blurb)
+ *   ├── ⬅️ Back  ✖️ Close             (botMenu auto-renders these in submenus)
+ *
+ * What's deliberately NOT here yet:
+ *
+ *   - Per-charge **History** view + in-menu refund request. The compliance
+ *     surface (`/paysupport` + admin-mediated refund) is fulfilled by
+ *     the admin commands and the message-side flow in `refund.ts`. The
+ *     history UI is a v2 follow-up (see CLAUDE.md §"Open follow-ups").
+ *
+ *   - Deep-link `require()` → exact rung. v1 opens VIP root; deep-linking
+ *     needs menu-state encoding in callback data.
+ */
+import { say } from "../../say/index.js";
+import { narrow } from "../ctx.js";
+import { presentInvoice } from "./invoice.js";
+const FALLBACK_LANG = "en";
+const ctxLang = (ctx) => narrow(ctx).session?.language ?? FALLBACK_LANG;
+const ctxPay = (ctx) => narrow(ctx).session?.pay;
+const resolveName = (value, lang) => {
+    if (!value)
+        return "";
+    return value[lang] ?? value[FALLBACK_LANG] ?? Object.values(value)[0] ?? "";
+};
+// ─── public factory ────────────────────────────────────────────────
+export const buildPaymentsMenuItem = (args) => {
+    const { cfg, catalog } = args;
+    // Root entry label + style adapt to current tier.
+    const rootLabel = (ctx) => {
+        const lang = ctxLang(ctx);
+        const pay = ctxPay(ctx);
+        if (!pay?.vip) {
+            return say({ en: "💎 VIP", es: "💎 VIP" }, lang);
+        }
+        // Active subscription — show name + days remaining.
+        const rung = catalog.vip[pay.vip.rung - 1];
+        const name = rung
+            ? resolveName(rung.name, lang)
+            : "VIP";
+        const daysLeft = Math.max(0, Math.ceil((pay.vip.expiresAt * 1000 - Date.now()) / 86_400_000));
+        // Two visual states: active+renewing → no marker; canceled → "expira".
+        if (pay.vip.canceled) {
+            return say({
+                en: `💎 ${name} · expires in ${daysLeft} d`,
+                es: `💎 ${name} · expira en ${daysLeft} d`,
+            }, lang);
+        }
+        return say({ en: `💎 ${name} · ${daysLeft} d`, es: `💎 ${name} · ${daysLeft} d` }, lang);
+    };
+    const rootStyle = (ctx) => {
+        const pay = ctxPay(ctx);
+        if (!pay?.vip)
+            return "primary"; // free → blue, "buy me" affordance
+        if (pay.vip.canceled)
+            return "danger"; // about to lapse
+        return undefined; // active+renewing → neutral
+    };
+    // ── submenu items ───────────────────────────────────────────────
+    //
+    // Menu item ids must not contain `.` — bot/menu joins paths with
+    // `.` (`pay.<itemId>`), so a dot in the id collides with the path
+    // separator and `itemForPath()` mis-parses the segments → "Item
+    // not found" with no logging. We replace dots with `_` for the
+    // menu id only; the action closure still uses the canonical
+    // `productKey` ("vip.1", "credits.1", "perks.voice_mode") for the
+    // catalog lookup and invoice payload.
+    const menuId = (productKey) => productKey.replace(/\./g, "_");
+    const items = [];
+    // 1. Tier cards (one per declared rung)
+    for (const rung of catalog.vip) {
+        items.push({
+            id: menuId(rung.id), // e.g. 'vip_1' — path-safe menu id
+            label: (ctx) => {
+                const lang = ctxLang(ctx);
+                const name = resolveName(rung.name, lang);
+                const pay = ctxPay(ctx);
+                if (pay?.vip?.rung === rung.rank) {
+                    return say({
+                        en: `✓ ${name} — ${rung.xtr} ⭐ (current)`,
+                        es: `✓ ${name} — ${rung.xtr} ⭐ (actual)`,
+                    }, lang);
+                }
+                const isUpgrade = (pay?.vip?.rung ?? 0) < rung.rank;
+                const tag = isUpgrade
+                    ? say({ en: "Upgrade", es: "Subir" }, lang)
+                    : say({ en: "Switch", es: "Cambiar" }, lang);
+                return `💎 ${name} — ${rung.xtr} ⭐ · ${tag}`;
+            },
+            style: (ctx) => {
+                const pay = ctxPay(ctx);
+                if (pay?.vip?.rung === rung.rank)
+                    return "primary";
+                return undefined;
+            },
+            // Don't re-show the buy card for the currently-active rung —
+            // it's already labeled "current" and tapping would re-invoice
+            // the same product, which Telegram allows but isn't useful UX.
+            visible: (ctx) => ctxPay(ctx)?.vip?.rung !== rung.rank,
+            action: async (ctx) => {
+                await presentInvoice(narrow(ctx), cfg, catalog, rung.id);
+                // Toast is the only thing the menu plugin will send for this
+                // tap; the invoice / waiver prompt itself goes out as a
+                // fresh message via ctx.send inside presentInvoice.
+                return undefined;
+            },
+        });
+    }
+    // 2. Credits packs (if axis configured)
+    for (const pack of catalog.creditsPacks) {
+        items.push({
+            id: menuId(pack.id), // e.g. 'credits_1' — path-safe menu id
+            label: (ctx) => {
+                const lang = ctxLang(ctx);
+                const unit = catalog.creditsUnit
+                    ? resolveName(catalog.creditsUnit, lang)
+                    : "credits";
+                const explicit = pack.name
+                    ? resolveName(pack.name, lang)
+                    : undefined;
+                const body = explicit ?? `+${pack.creditsGranted} ${unit}`;
+                return `💬 ${body} — ${pack.xtr} ⭐`;
+            },
+            action: async (ctx) => {
+                await presentInvoice(narrow(ctx), cfg, catalog, pack.id);
+                return undefined;
+            },
+        });
+    }
+    // 3. Perks — hide when already owned (no "tap to re-buy" UX trap)
+    for (const perk of catalog.perks) {
+        items.push({
+            id: menuId(perk.id), // e.g. 'perks_voice_mode' — path-safe
+            label: (ctx) => {
+                const lang = ctxLang(ctx);
+                const name = resolveName(perk.name, lang);
+                return `🎁 ${name} — ${perk.xtr} ⭐`;
+            },
+            visible: (ctx) => !ctxPay(ctx)?.perks?.[perk.key],
+            action: async (ctx) => {
+                await presentInvoice(narrow(ctx), cfg, catalog, perk.id);
+                return undefined;
+            },
+        });
+    }
+    // 4. Manage: cancel renewal / resume renewal (single dynamic button)
+    items.push({
+        id: "manage",
+        label: (ctx) => {
+            const lang = ctxLang(ctx);
+            const pay = ctxPay(ctx);
+            if (!pay?.vip)
+                return ""; // hidden when free
+            return pay.vip.canceled
+                ? say({ en: "↩️ Resume renewal", es: "↩️ Reanudar renovación" }, lang)
+                : say({ en: "⛔ Cancel renewal", es: "⛔ Cancelar renovación" }, lang);
+        },
+        style: (ctx) => {
+            const pay = ctxPay(ctx);
+            return pay?.vip?.canceled ? "primary" : "danger";
+        },
+        visible: (ctx) => !!ctxPay(ctx)?.vip,
+        refresh: true,
+        confirm: {
+            prompt: {
+                en: "⚠️ Toggle auto-renewal for your VIP subscription?\n\n" +
+                    "Canceling: access continues until the current period ends; no renewal charge.\n" +
+                    "Resuming: auto-renewal turns back on.",
+                es: "⚠️ ¿Cambiar la renovación automática de tu suscripción VIP?\n\n" +
+                    "Cancelar: mantienes acceso hasta el fin del periodo actual; no se cobra renovación.\n" +
+                    "Reanudar: se vuelve a activar la renovación automática.",
+            },
+        },
+        action: async (ctx) => {
+            const lang = ctxLang(ctx);
+            const pay = ctxPay(ctx);
+            if (!pay?.vip) {
+                return say({ en: "Nothing to do.", es: "Nada que hacer." }, lang);
+            }
+            const c = narrow(ctx);
+            const userId = c.from?.id;
+            if (!userId) {
+                return say({ en: "No user.", es: "Sin usuario." }, lang);
+            }
+            const wantCanceled = !pay.vip.canceled;
+            try {
+                await c.bot.api.editUserStarSubscription({
+                    user_id: userId,
+                    telegram_payment_charge_id: pay.vip.chargeId,
+                    is_canceled: wantCanceled,
+                });
+            }
+            catch (e) {
+                console.error("[bot/payments/menu] editUserStarSubscription failed", e);
+                return say({ en: "Failed — try later.", es: "Falló — prueba luego." }, lang);
+            }
+            // Reflect the new state in session so the menu re-renders
+            // correctly (refresh: true will fire the label/style resolvers
+            // again immediately after this returns).
+            const session = c.session;
+            if (session.pay?.vip) {
+                session.pay = {
+                    ...session.pay,
+                    vip: { ...session.pay.vip, canceled: wantCanceled },
+                };
+            }
+            return wantCanceled
+                ? say({ en: "⛔ Renewal canceled.", es: "⛔ Renovación cancelada." }, lang)
+                : say({ en: "↩️ Renewal resumed.", es: "↩️ Renovación reanudada." }, lang);
+        },
+    });
+    // 5. Help / refunds — URL-style action that just sends the paysupport blurb
+    items.push({
+        id: "help",
+        label: (ctx) => say({ en: "💬 Help & refunds", es: "💬 Ayuda y reembolsos" }, ctxLang(ctx)),
+        action: async (ctx) => {
+            const lang = ctxLang(ctx);
+            const c = narrow(ctx);
+            await c.send(say({
+                en: `Need help with a payment?\n\n` +
+                    `• Contact: ${cfg.paysupport}\n` +
+                    `• Include the chargeId from your purchase confirmation.\n\n` +
+                    `Refunds are processed by the admin within Telegram.`,
+                es: `¿Necesitas ayuda con un pago?\n\n` +
+                    `• Contacto: ${cfg.paysupport}\n` +
+                    `• Incluye el chargeId de tu confirmación de compra.\n\n` +
+                    `Los reembolsos los gestiona el admin dentro de Telegram.`,
+            }, lang));
+            return undefined;
+        },
+    });
+    return {
+        id: "pay",
+        label: rootLabel,
+        style: rootStyle,
+        submenu: items,
+    };
+};
+//# sourceMappingURL=menu-item.js.map

package/dist/bot/payments/menu-item.js.map

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

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

@@ -0,0 +1,42 @@
+/**
+ * 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.
+ */
+export type DecodedPayload = {
+    readonly productKey: string;
+    readonly userId: number;
+};
+/**
+ * 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 declare const encodePayload: (productKey: string, userId: number) => string;
+/**
+ * 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 declare const decodePayload: (payload: string) => DecodedPayload | undefined;
+//# sourceMappingURL=payload.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"payload.d.ts","sourceRoot":"","sources":["../../../src/bot/payments/payload.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAMH,MAAM,MAAM,cAAc,GAAG;IAC5B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACxB,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,aAAa,GAAI,YAAY,MAAM,EAAE,QAAQ,MAAM,KAAG,MAmBlE,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,aAAa,GAAI,SAAS,MAAM,KAAG,cAAc,GAAG,SAUhE,CAAC"}