@adriangalilea/utils 0.18.0 → 0.20.0

package/dist/bot/payments/callbacks.js

@@ -0,0 +1,102 @@
+/**
+ * Callback-query handler bodies — extracted from `plugin.ts` per the
+ * `bot/CLAUDE.md` plugin file convention (callbacks.ts owns the
+ * `.callbackQuery()` handler bodies; plugin.ts is wiring only).
+ *
+ * The CallbackData schemas themselves live with their owning feature
+ * (waiver.ts, refund.ts) — those modules also export `buildXxxHandler`
+ * factories for handlers that need richer dependencies (refund's flow
+ * needs `stores + storage + cfg`). This file holds the simpler
+ * inline-style handlers that didn't justify their own factory.
+ *
+ *   - `buildWaiverConsentHandler({ cfg, catalog })`
+ *       persists consent, deletes the prompt message, re-enters the
+ *       invoice flow for the carried productKey.
+ *   - `buildWaiverCancelHandler()`
+ *       acknowledges the tap and edits the prompt to a "canceled"
+ *       message.
+ *   - `buildRefundCloseHandler()`
+ *       admin-only: deletes the DM notification on the close button.
+ */
+import { say } from "../../say/index.js";
+import { narrow } from "../ctx.js";
+import { presentInvoice } from "./invoice.js";
+import { persistWaiverOnSession } from "./waiver.js";
+const FALLBACK_LANG = "en";
+// ─── waiver consent ───────────────────────────────────────────────
+export const buildWaiverConsentHandler = (args) => async (ctx) => {
+    const c = narrow(ctx);
+    const lang = c.session.language ?? FALLBACK_LANG;
+    const userId = c.from?.id;
+    if (!userId) {
+        await c.answer({
+            text: say({
+                en: "Could not identify you.",
+                es: "No se pudo identificarte.",
+            }, lang),
+        });
+        return;
+    }
+    const product = args.catalog.byKey.get(c.queryData.pk);
+    if (!product) {
+        await c.answer({
+            text: say({ en: "Unknown product.", es: "Producto desconocido." }, lang),
+        });
+        return;
+    }
+    // Persist consent on the user's session (cur ctx IS the user
+    // since they're tapping their own message).
+    persistWaiverOnSession(narrow(c), args.cfg.waiver.version, lang);
+    // Acknowledge the tap with a toast, then DELETE the consent
+    // prompt entirely. Previously we edited the body to
+    // "✅ Consent recorded. Sending invoice…" which goes stale the
+    // moment the invoice payment sheet appears underneath — visible
+    // noise in the chat history forever after. The toast confirms
+    // what happened; the user's next interaction is the Telegram
+    // payment sheet itself.
+    await c.answer({
+        text: say({ en: "✅ Consent recorded.", es: "✅ Consentimiento registrado." }, lang),
+    });
+    try {
+        await c.message?.delete?.();
+    }
+    catch {
+        /* message too old to delete — ignore */
+    }
+    // Re-enter the invoice flow now that consent is fresh.
+    await presentInvoice(narrow(c), args.cfg, args.catalog, product.id);
+};
+// ─── waiver cancel ────────────────────────────────────────────────
+export const buildWaiverCancelHandler = () => async (ctx) => {
+    const c = narrow(ctx);
+    const lang = c.session.language ?? FALLBACK_LANG;
+    await c.answer({
+        text: say({ en: "Canceled.", es: "Cancelado." }, lang),
+    });
+    try {
+        await c.editText(say({ en: "❌ Purchase canceled.", es: "❌ Compra cancelada." }, lang));
+    }
+    catch {
+        /* ignore — message too old to edit */
+    }
+};
+// ─── refund close (admin-only) ────────────────────────────────────
+export const buildRefundCloseHandler = () => async (ctx) => {
+    const c = narrow(ctx);
+    const lang = c.session.language ?? FALLBACK_LANG;
+    if (!c.isAdmin) {
+        await c.answer({
+            text: say({ en: "Admin only.", es: "Solo admin." }, lang),
+            show_alert: true,
+        });
+        return;
+    }
+    await c.answer({});
+    try {
+        await c.message?.delete?.();
+    }
+    catch {
+        /* ignore — message too old to delete */
+    }
+};
+//# sourceMappingURL=callbacks.js.map

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

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

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

@@ -0,0 +1,26 @@
+/**
+ * Slash-command handlers. The `/paysupport` command is mandated by
+ * Telegram Bot Developer ToS §6.5 — every bot accepting payments must
+ * expose a way for users to reach support about charges.
+ *
+ * The actual command registration (`.command("paysupport", { … }, fn)`)
+ * happens in `plugin.ts`; this module owns the body + the response
+ * text so wording stays in one place.
+ */
+import type { BotPaymentsConfig } from "./types.js";
+/**
+ * Mandatory `/paysupport` text. ToS §6.5 requires every bot accepting
+ * payments to expose this. Brief message pointing the user to the menu
+ * (where the refund flow lives) and to the human admin contact.
+ *
+ * Exported because tests + future admin tooling may want to render the
+ * exact wording the bot uses without going through the command handler.
+ */
+export declare const buildPaysupportText: (cfg: BotPaymentsConfig<string>, lang: string) => string;
+/**
+ * Returns the `/paysupport` command handler. Pure factory — `plugin.ts`
+ * calls this once at construction and passes the result to gramio's
+ * `.command()`.
+ */
+export declare const buildPaysupportCommand: (cfg: BotPaymentsConfig<string>) => (ctx: unknown) => Promise<void>;
+//# sourceMappingURL=commands.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"commands.d.ts","sourceRoot":"","sources":["../../../src/bot/payments/commands.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH,OAAO,KAAK,EAAE,iBAAiB,EAAmB,MAAM,YAAY,CAAC;AAMrE;;;;;;;GAOG;AACH,eAAO,MAAM,mBAAmB,GAC/B,KAAK,iBAAiB,CAAC,MAAM,CAAC,EAC9B,MAAM,MAAM,KACV,MAeD,CAAC;AAEH;;;;GAIG;AACH,eAAO,MAAM,sBAAsB,GACjC,KAAK,iBAAiB,CAAC,MAAM,CAAC,MACxB,KAAK,OAAO,KAAG,OAAO,CAAC,IAAI,CAIjC,CAAC"}

package/dist/bot/payments/commands.js

@@ -0,0 +1,41 @@
+/**
+ * Slash-command handlers. The `/paysupport` command is mandated by
+ * Telegram Bot Developer ToS §6.5 — every bot accepting payments must
+ * expose a way for users to reach support about charges.
+ *
+ * The actual command registration (`.command("paysupport", { … }, fn)`)
+ * happens in `plugin.ts`; this module owns the body + the response
+ * text so wording stays in one place.
+ */
+import { say } from "../../say/index.js";
+import { narrow } from "../ctx.js";
+const FALLBACK_LANG = "en";
+/**
+ * Mandatory `/paysupport` text. ToS §6.5 requires every bot accepting
+ * payments to expose this. Brief message pointing the user to the menu
+ * (where the refund flow lives) and to the human admin contact.
+ *
+ * Exported because tests + future admin tooling may want to render the
+ * exact wording the bot uses without going through the command handler.
+ */
+export const buildPaysupportText = (cfg, lang) => say({
+    en: `Need help with a payment?\n\n` +
+        `• Open /settings → 💎 VIP → 📜 History to see your charges and request a refund.\n` +
+        `• Or contact: ${cfg.paysupport}\n\n` +
+        `Refund disputes are handled by the admin within Telegram.`,
+    es: `¿Necesitas ayuda con un pago?\n\n` +
+        `• Abre /settings → 💎 VIP → 📜 Historial para ver tus cargos y solicitar reembolso.\n` +
+        `• O contacta: ${cfg.paysupport}\n\n` +
+        `Las disputas las gestiona el admin dentro de Telegram.`,
+}, lang);
+/**
+ * Returns the `/paysupport` command handler. Pure factory — `plugin.ts`
+ * calls this once at construction and passes the result to gramio's
+ * `.command()`.
+ */
+export const buildPaysupportCommand = (cfg) => async (ctx) => {
+    const c = narrow(ctx);
+    const lang = c.session.language ?? FALLBACK_LANG;
+    await c.send(buildPaysupportText(cfg, lang));
+};
+//# sourceMappingURL=commands.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"commands.js","sourceRoot":"","sources":["../../../src/bot/payments/commands.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,GAAG,EAAE,MAAM,oBAAoB,CAAC;AACzC,OAAO,EAAsB,MAAM,EAAE,MAAM,WAAW,CAAC;AAGvD,MAAM,aAAa,GAAG,IAAI,CAAC;AAI3B;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAClC,GAA8B,EAC9B,IAAY,EACH,EAAE,CACX,GAAG,CACF;IACC,EAAE,EACD,+BAA+B;QAC/B,oFAAoF;QACpF,iBAAiB,GAAG,CAAC,UAAU,MAAM;QACrC,2DAA2D;IAC5D,EAAE,EACD,mCAAmC;QACnC,uFAAuF;QACvF,iBAAiB,GAAG,CAAC,UAAU,MAAM;QACrC,wDAAwD;CACzD,EACD,IAAI,CACJ,CAAC;AAEH;;;;GAIG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAClC,CAAC,GAA8B,EAAE,EAAE,CACnC,KAAK,EAAE,GAAY,EAAiB,EAAE;IACrC,MAAM,CAAC,GAAG,MAAM,CAA6B,GAAG,CAAC,CAAC;IAClD,MAAM,IAAI,GAAG,CAAC,CAAC,OAAO,CAAC,QAAQ,IAAI,aAAa,CAAC;IACjD,MAAM,CAAC,CAAC,IAAI,CAAC,mBAAmB,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC,CAAC;AAC9C,CAAC,CAAC"}

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

@@ -0,0 +1,30 @@
+/**
+ * Construction-time validation + catalog build.
+ *
+ * `validateConfig(cfg)` is the gate. It throws `Panic` on every shape
+ * problem the bot author can introduce — a misconfigured payments
+ * plugin should scream at startup, not silently misbehave at runtime
+ * (see `src/offensive.ts` and CLAUDE.md §"Failure modes").
+ *
+ * `buildCatalog(cfg)` produces the normalized `ProductCatalog` the rest
+ * of the plugin consults (positional ids resolved, polyglots passed
+ * through, O(1) lookup by ProductKey).
+ *
+ * Both are pure — no gramio, no storage, no side effects.
+ */
+import { type BotPaymentsConfig, type ProductCatalog } from "./types.js";
+/**
+ * Validates the config and returns the **locales set** that the plugin
+ * will use for cross-checking other Polyglots. Derived from
+ * `waiver.text` (the single mandatory Polyglot) — every other Polyglot
+ * in the config must cover the same locales.
+ *
+ * Throws `Panic` on any structural problem.
+ */
+export declare const validateConfig: (cfg: BotPaymentsConfig<string>) => ReadonlySet<string>;
+/**
+ * Materialize the validated config into the runtime catalog. Assumes
+ * `validateConfig(cfg)` has already been called and passed.
+ */
+export declare const buildCatalog: (cfg: BotPaymentsConfig<string>) => ProductCatalog;
+//# sourceMappingURL=config.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../../src/bot/payments/config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAIH,OAAO,EACN,KAAK,iBAAiB,EAGtB,KAAK,cAAc,EAGnB,MAAM,YAAY,CAAC;AAwCpB;;;;;;;GAOG;AACH,eAAO,MAAM,cAAc,GAC1B,KAAK,iBAAiB,CAAC,MAAM,CAAC,KAC5B,WAAW,CAAC,MAAM,CAuFpB,CAAC;AAIF;;;GAGG;AACH,eAAO,MAAM,YAAY,GACxB,KAAK,iBAAiB,CAAC,MAAM,CAAC,KAC5B,cA2CF,CAAC"}

package/dist/bot/payments/config.js

@@ -0,0 +1,166 @@
+/**
+ * Construction-time validation + catalog build.
+ *
+ * `validateConfig(cfg)` is the gate. It throws `Panic` on every shape
+ * problem the bot author can introduce — a misconfigured payments
+ * plugin should scream at startup, not silently misbehave at runtime
+ * (see `src/offensive.ts` and CLAUDE.md §"Failure modes").
+ *
+ * `buildCatalog(cfg)` produces the normalized `ProductCatalog` the rest
+ * of the plugin consults (positional ids resolved, polyglots passed
+ * through, O(1) lookup by ProductKey).
+ *
+ * Both are pure — no gramio, no storage, no side effects.
+ */
+import { panic } from "../../offensive.js";
+import { SUBSCRIPTION_PERIOD_SECONDS, } from "./types.js";
+// ─── validation ────────────────────────────────────────────────────
+const requireNonEmptyString = (value, where) => {
+    if (typeof value !== "string" || value.length === 0) {
+        panic(`bot/payments: ${where} must be a non-empty string (got ${value})`);
+    }
+    return value;
+};
+const requirePositiveInt = (value, where) => {
+    if (typeof value !== "number" || !Number.isInteger(value) || value <= 0) {
+        panic(`bot/payments: ${where} must be a positive integer (got ${value})`);
+    }
+    return value;
+};
+const polyglotKeys = (p) => Object.keys(p).filter((k) => typeof p[k] === "string");
+const requirePolyglotCovers = (p, locales, where) => {
+    if (!p || typeof p !== "object") {
+        panic(`bot/payments: ${where} must be a Polyglot object`);
+    }
+    if (locales.size === 0)
+        return; // no required-locales declared — accept anything non-empty
+    for (const loc of locales) {
+        const v = p[loc];
+        if (typeof v !== "string" || v.length === 0) {
+            panic(`bot/payments: ${where} is missing a non-empty entry for locale "${loc}"`);
+        }
+    }
+};
+/**
+ * Validates the config and returns the **locales set** that the plugin
+ * will use for cross-checking other Polyglots. Derived from
+ * `waiver.text` (the single mandatory Polyglot) — every other Polyglot
+ * in the config must cover the same locales.
+ *
+ * Throws `Panic` on any structural problem.
+ */
+export const validateConfig = (cfg) => {
+    if (!cfg || typeof cfg !== "object") {
+        panic("bot/payments: config must be an object");
+    }
+    requireNonEmptyString(cfg.paysupport, "paysupport");
+    requireNonEmptyString(cfg.legal?.sellerName, "legal.sellerName");
+    requireNonEmptyString(cfg.legal?.nif, "legal.nif");
+    // termsUrl and privacyUrl are OPTIONAL. privacyUrl gets a sensible
+    // Telegram-side default at use time (waiver.ts). termsUrl, when
+    // omitted, hides the 📖 Terms button from the consent prompt — no
+    // canonical Telegram ToS to fall back to.
+    if (cfg.legal?.termsUrl !== undefined) {
+        requireNonEmptyString(cfg.legal.termsUrl, "legal.termsUrl");
+    }
+    if (cfg.legal?.privacyUrl !== undefined) {
+        requireNonEmptyString(cfg.legal.privacyUrl, "legal.privacyUrl");
+    }
+    requireNonEmptyString(cfg.waiver?.version, "waiver.version");
+    const waiverKeys = polyglotKeys(cfg.waiver?.text ?? {});
+    if (waiverKeys.length === 0) {
+        panic("bot/payments: waiver.text must declare at least one locale with non-empty content");
+    }
+    const locales = new Set(waiverKeys);
+    const hasVip = Array.isArray(cfg.vip) && cfg.vip.length > 0;
+    const hasCredits = !!cfg.credits &&
+        Array.isArray(cfg.credits.packs) &&
+        cfg.credits.packs.length > 0;
+    const hasPerks = !!cfg.perks && Object.keys(cfg.perks).length > 0;
+    if (!hasVip && !hasCredits && !hasPerks) {
+        panic("bot/payments: declare at least one of `vip`, `credits.packs`, or `perks` — " +
+            "a payments plugin with no products has nothing to sell");
+    }
+    if (hasVip) {
+        cfg.vip?.forEach((rung, i) => {
+            const at = `vip[${i}]`;
+            requirePositiveInt(rung.xtr, `${at}.xtr`);
+            if (rung.period !== "30d") {
+                panic(`bot/payments: ${at}.period must be "30d" (Telegram supports no other ` +
+                    `subscription period as of 2026) — got "${rung.period}"`);
+            }
+            requirePolyglotCovers(rung.name, locales, `${at}.name`);
+            if (rung.grants?.credits !== undefined) {
+                requirePositiveInt(rung.grants.credits, `${at}.grants.credits`);
+            }
+        });
+    }
+    if (hasCredits) {
+        const c = cfg.credits;
+        if (!c)
+            panic("bot/payments: credits config disappeared mid-validation");
+        requirePolyglotCovers(c.unit, locales, "credits.unit");
+        c.packs.forEach((pack, i) => {
+            const at = `credits.packs[${i}]`;
+            requirePositiveInt(pack.xtr, `${at}.xtr`);
+            requirePositiveInt(pack.grants?.credits, `${at}.grants.credits`);
+            if (pack.name) {
+                requirePolyglotCovers(pack.name, locales, `${at}.name`);
+            }
+        });
+    }
+    if (hasPerks && cfg.perks) {
+        for (const [key, perk] of Object.entries(cfg.perks)) {
+            const at = `perks.${key}`;
+            if (!/^[a-z][a-z0-9_]*$/i.test(key)) {
+                panic(`bot/payments: perk key "${key}" must match /^[a-z][a-z0-9_]*$/i (used in ` +
+                    `payload encoding, must be safe)`);
+            }
+            requirePositiveInt(perk.xtr, `${at}.xtr`);
+            requirePolyglotCovers(perk.name, locales, `${at}.name`);
+        }
+    }
+    return locales;
+};
+// ─── catalog build ─────────────────────────────────────────────────
+/**
+ * Materialize the validated config into the runtime catalog. Assumes
+ * `validateConfig(cfg)` has already been called and passed.
+ */
+export const buildCatalog = (cfg) => {
+    const vip = (cfg.vip ?? []).map((rung, i) => ({
+        id: `vip.${i + 1}`,
+        rank: i + 1,
+        xtr: rung.xtr,
+        periodSeconds: SUBSCRIPTION_PERIOD_SECONDS[rung.period],
+        name: rung.name,
+        creditsGranted: rung.grants?.credits ?? 0,
+    }));
+    const creditsPacks = (cfg.credits?.packs ?? []).map((pack, i) => ({
+        id: `credits.${i + 1}`,
+        xtr: pack.xtr,
+        creditsGranted: pack.grants.credits,
+        name: pack.name,
+    }));
+    const perks = Object.entries(cfg.perks ?? {}).map(([key, perk]) => ({
+        id: `perks.${key}`,
+        key,
+        xtr: perk.xtr,
+        name: perk.name,
+    }));
+    const byKey = new Map();
+    for (const r of vip)
+        byKey.set(r.id, r);
+    for (const p of creditsPacks)
+        byKey.set(p.id, p);
+    for (const p of perks)
+        byKey.set(p.id, p);
+    return {
+        vip,
+        creditsUnit: cfg.credits?.unit,
+        creditsPacks,
+        perks,
+        byKey,
+    };
+};
+//# sourceMappingURL=config.js.map

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

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

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

@@ -0,0 +1,75 @@
+/**
+ * `ctx.payments` derive — the per-event ctx decoration.
+ *
+ * Extracted from `plugin.ts` to keep that file pure wiring per the
+ * `bot/CLAUDE.md` plugin file convention. Everything that reads or
+ * mutates session state inside an event handler goes through one of
+ * the methods this module attaches:
+ *
+ *   - `ctx.payments.atLeast(id)`   — tier gate (lazy expiry)
+ *   - `ctx.payments.tier()`        — current rung (`'free' | 'vip.N'`)
+ *   - `ctx.payments.tier.level()`  — integer rank
+ *   - `ctx.payments.tier.label()`  — resolved Polyglot label
+ *   - `ctx.payments.credits.*`     — balance / consume / tryConsume
+ *   - `ctx.payments.has(perkId)`   — perk ownership boolean
+ *   - `ctx.payments.require(...)`  — gate + localized upgrade prompt
+ *   - `ctx.payments.invoice(key)`  — purchase entry (waiver-gated)
+ *
+ * Returned shape is a function so `plugin.ts` can drop it directly
+ * into `.derive(["message", "callback_query"], buildPaymentsDerive({...}))`.
+ */
+import { type BotPaymentsConfig, type ProductCatalog } from "./types.js";
+type TierKey = "free" | `vip.${number}`;
+/**
+ * Callable `tier` namespace. Matches `PaymentsCtx['tier']` from `plugin.ts`
+ * — exported there as the public surface. Repeated minimally here so
+ * derive.ts isn't import-cycle dependent on plugin.ts.
+ */
+export type TierFn = (() => TierKey) & {
+    level: () => number;
+    label: () => string | undefined;
+};
+export type CreditsApi = {
+    balance: () => number;
+    consume: (n: number) => void;
+    tryConsume: (n: number) => boolean;
+};
+export type RequireOpts = {
+    feature?: {
+        en: string;
+        es: string;
+    } | string;
+};
+/**
+ * What `buildPaymentsDerive` attaches under `ctx.payments`. Plugin.ts
+ * casts this to the typed `PaymentsCtx<Cfg>` (with positional ladder
+ * narrowing) before exposing it to bot authors — TypeScript can't
+ * preserve the generic narrowing through a function-shaped derive
+ * factory cleanly, so the strict type lives at the public surface.
+ */
+export type PaymentsDerived = {
+    atLeast: (id: string) => boolean;
+    tier: TierFn;
+    has: (perkId: string) => boolean;
+    credits: CreditsApi;
+    require: (id: string, opts?: RequireOpts) => Promise<boolean>;
+    invoice: (productKey: string) => Promise<"invoice_sent" | "waiver_prompt_sent" | "unknown_product">;
+};
+export type BuildPaymentsDeriveArgs = {
+    /** Resolved product catalogue (rungs, packs, perks). */
+    catalog: ProductCatalog;
+    /**
+     * Full config — currently only consulted inside `invoice()` for the
+     * waiver wording + product display strings via `presentInvoice`.
+     */
+    cfg: BotPaymentsConfig<string>;
+};
+/**
+ * Returns the function you pass to gramio's `.derive([events], fn)`.
+ * The returned function takes ctx, returns `{ payments }`.
+ */
+export declare const buildPaymentsDerive: ({ cfg, catalog, }: BuildPaymentsDeriveArgs) => (ctx: unknown) => {
+    payments: PaymentsDerived;
+};
+export {};
+//# sourceMappingURL=derive.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"derive.d.ts","sourceRoot":"","sources":["../../../src/bot/payments/derive.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAMH,OAAO,EACN,KAAK,iBAAiB,EAGtB,KAAK,cAAc,EACnB,MAAM,YAAY,CAAC;AAMpB,KAAK,OAAO,GAAG,MAAM,GAAG,OAAO,MAAM,EAAE,CAAC;AAExC;;;;GAIG;AACH,MAAM,MAAM,MAAM,GAAG,CAAC,MAAM,OAAO,CAAC,GAAG;IACtC,KAAK,EAAE,MAAM,MAAM,CAAC;IACpB,KAAK,EAAE,MAAM,MAAM,GAAG,SAAS,CAAC;CAChC,CAAC;AAEF,MAAM,MAAM,UAAU,GAAG;IACxB,OAAO,EAAE,MAAM,MAAM,CAAC;IACtB,OAAO,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,IAAI,CAAC;IAC7B,UAAU,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC;CACnC,CAAC;AAEF,MAAM,MAAM,WAAW,GAAG;IACzB,OAAO,CAAC,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,EAAE,EAAE,MAAM,CAAA;KAAE,GAAG,MAAM,CAAC;CAC9C,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,MAAM,eAAe,GAAG;IAC7B,OAAO,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC;IACjC,OAAO,EAAE,UAAU,CAAC;IACpB,OAAO,EAAE,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,WAAW,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IAC9D,OAAO,EAAE,CACR,UAAU,EAAE,MAAM,KACd,OAAO,CAAC,cAAc,GAAG,oBAAoB,GAAG,iBAAiB,CAAC,CAAC;CACxE,CAAC;AAEF,MAAM,MAAM,uBAAuB,GAAG;IACrC,wDAAwD;IACxD,OAAO,EAAE,cAAc,CAAC;IACxB;;;OAGG;IACH,GAAG,EAAE,iBAAiB,CAAC,MAAM,CAAC,CAAC;CAC/B,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,mBAAmB,GAAI,mBAGjC,uBAAuB,MACjB,KAAK,OAAO,KAAG;IAAE,QAAQ,EAAE,eAAe,CAAA;CA+IlD,CAAC"}

package/dist/bot/payments/derive.js

@@ -0,0 +1,151 @@
+/**
+ * `ctx.payments` derive — the per-event ctx decoration.
+ *
+ * Extracted from `plugin.ts` to keep that file pure wiring per the
+ * `bot/CLAUDE.md` plugin file convention. Everything that reads or
+ * mutates session state inside an event handler goes through one of
+ * the methods this module attaches:
+ *
+ *   - `ctx.payments.atLeast(id)`   — tier gate (lazy expiry)
+ *   - `ctx.payments.tier()`        — current rung (`'free' | 'vip.N'`)
+ *   - `ctx.payments.tier.level()`  — integer rank
+ *   - `ctx.payments.tier.label()`  — resolved Polyglot label
+ *   - `ctx.payments.credits.*`     — balance / consume / tryConsume
+ *   - `ctx.payments.has(perkId)`   — perk ownership boolean
+ *   - `ctx.payments.require(...)`  — gate + localized upgrade prompt
+ *   - `ctx.payments.invoice(key)`  — purchase entry (waiver-gated)
+ *
+ * Returned shape is a function so `plugin.ts` can drop it directly
+ * into `.derive(["message", "callback_query"], buildPaymentsDerive({...}))`.
+ */
+import { say } from "../../say/index.js";
+import { narrow } from "../ctx.js";
+import { menuNavCb } from "../menu.js";
+import { presentInvoice } from "./invoice.js";
+import { InsufficientCredits, } from "./types.js";
+const FALLBACK_LANG = "en";
+/**
+ * Returns the function you pass to gramio's `.derive([events], fn)`.
+ * The returned function takes ctx, returns `{ payments }`.
+ */
+export const buildPaymentsDerive = ({ cfg, catalog, }) => {
+    return (ctx) => {
+        // Single narrow at the top — every subsequent reference uses
+        // `c.<field>` and reads cleanly. The structural type is the
+        // intersection of message + callback_query event ctxs so this
+        // derive works for both event scopes (gramio's runtime dedup
+        // guarantees one execution per update).
+        const c = narrow(ctx);
+        // Lazy expiry — vip is only "active" while its expiresAt is in
+        // the future (CLAUDE.md §"sweep" deferred to v2). Pure read; no
+        // cleanup of stale `session.pay.vip` records.
+        const isVipActive = () => {
+            const v = c.session.pay?.vip;
+            if (!v)
+                return false;
+            return v.expiresAt * 1000 > Date.now();
+        };
+        const effectiveRung = () => {
+            if (!isVipActive())
+                return 0;
+            return c.session.pay?.vip?.rung ?? 0;
+        };
+        const atLeast = (id) => {
+            if (id === "free")
+                return true;
+            const rung = effectiveRung();
+            if (id === "vip")
+                return rung > 0;
+            if (id.startsWith("vip.")) {
+                const want = Number.parseInt(id.slice(4), 10);
+                return rung >= want;
+            }
+            return false;
+        };
+        const tierFn = (() => {
+            const rung = effectiveRung();
+            if (rung === 0)
+                return "free";
+            return `vip.${rung}`;
+        });
+        tierFn.level = () => effectiveRung();
+        tierFn.label = () => {
+            const rung = effectiveRung();
+            if (rung === 0)
+                return undefined;
+            const r = catalog.vip[rung - 1];
+            if (!r)
+                return undefined;
+            const lang = c.session.language ?? FALLBACK_LANG;
+            return (r.name[lang] ??
+                r.name[FALLBACK_LANG]);
+        };
+        const credits = {
+            balance: () => c.session.pay?.credits ?? 0,
+            consume: (n) => {
+                const current = c.session.pay?.credits ?? 0;
+                if (current < n)
+                    throw new InsufficientCredits(n, current);
+                c.session.pay ??= {};
+                c.session.pay.credits = current - n;
+            },
+            tryConsume: (n) => {
+                const current = c.session.pay?.credits ?? 0;
+                if (current < n)
+                    return false;
+                c.session.pay ??= {};
+                c.session.pay.credits = current - n;
+                return true;
+            },
+        };
+        const has = (perkId) => !!c.session.pay?.perks?.[perkId];
+        const requireFn = async (id, opts) => {
+            if (atLeast(id))
+                return true;
+            const lang = c.session.language ?? FALLBACK_LANG;
+            const featureName = opts?.feature === undefined
+                ? undefined
+                : typeof opts.feature === "string"
+                    ? opts.feature
+                    : (opts.feature[lang] ?? opts.feature.en);
+            const body = featureName !== undefined
+                ? say({
+                    en: `💎 "${featureName}" needs VIP. Tap below to upgrade.`,
+                    es: `💎 "${featureName}" necesita VIP. Toca abajo para mejorar.`,
+                }, lang)
+                : say({
+                    en: "💎 This needs VIP. Tap below to upgrade.",
+                    es: "💎 Esto necesita VIP. Toca abajo para mejorar.",
+                }, lang);
+            // Deep-link into our menuItem (id='pay') via botMenu's
+            // shared menuNavCb schema. v1 opens VIP root; deep-linking to
+            // a specific rung is a v2 TODO (see CLAUDE.md).
+            const button = say({ en: "💎 Open VIP plans", es: "💎 Ver planes VIP" }, lang);
+            await c.send(body, {
+                reply_markup: {
+                    inline_keyboard: [
+                        [
+                            {
+                                text: button,
+                                callback_data: menuNavCb.pack({ path: "pay" }),
+                            },
+                        ],
+                    ],
+                },
+            });
+            return false;
+        };
+        const invoiceFn = (productKey) => presentInvoice(narrow(c), cfg, catalog, productKey);
+        return {
+            payments: {
+                atLeast,
+                tier: tierFn,
+                has,
+                credits,
+                require: requireFn,
+                invoice: invoiceFn,
+            },
+        };
+    };
+};
+//# sourceMappingURL=derive.js.map

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

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