@adriangalilea/utils 0.18.0 → 0.19.0

package/dist/bot/payments/handlers.js

@@ -0,0 +1,284 @@
+/**
+ * Telegram event handlers: `pre_checkout_query`, `successful_payment`,
+ * and the auto-installed `/paysupport` command.
+ *
+ * Two hot paths the handlers MUST get right:
+ *
+ *   - `pre_checkout_query` has a **10 s hard deadline** at Telegram's
+ *     side. We answer synchronously after a single payload decode +
+ *     catalog lookup + xtr match check. No storage round-trips.
+ *
+ *   - `successful_payment` is **idempotent by `telegram_payment_charge_id`**.
+ *     We claim the chargeId via a sentinel key (`pay:idempotency:{id}`)
+ *     using set-if-absent semantics; a duplicate delivery returns a
+ *     no-op. Telegram retries this event in some failure modes (see
+ *     `sendInvoice` docs § Tips), so this guard is load-bearing.
+ *
+ * `/paysupport` is mandated by the Bot Developer ToS §6.5 — every bot
+ * accepting payments must surface a way for users to request refunds.
+ * We register the command and route users to `/settings → 💎 VIP`
+ * where the refund flow lives (mirrors how `bot/menu` keeps every
+ * user-facing flow under one slash command).
+ */
+import { panic, SourcedError } from "../../offensive.js";
+import { say } from "../../say/index.js";
+import { createLogger } from "../../universal/log.js";
+import { decodePayload } from "./payload.js";
+import { applyCharge } from "./state.js";
+const log = createLogger("bot/payments");
+const FALLBACK_LANG = "en";
+const ctxLang = (ctx) => ctx.session?.language ?? FALLBACK_LANG;
+// ─── pre_checkout_query handler ────────────────────────────────────
+/**
+ * Validate the in-flight purchase synchronously and ack within 10 s.
+ *
+ *   - Currency must be `XTR` (we only sell digital goods; fiat would
+ *     have a `provider_token` and not reach this plugin).
+ *   - Payload must decode + match `ctx.from.id` (anti-tamper).
+ *   - Product must exist in the catalog.
+ *   - `total_amount` must match the catalog's declared xtr — defense
+ *     against a stale invoice or a config edit between invoice send
+ *     and tap.
+ *
+ * On any failure: ack `ok: false` with a brief localized reason. The
+ * user sees Telegram's "Payment failed" sheet with that reason.
+ */
+export const buildPreCheckoutHandler = (catalog) => async (ctx) => {
+    log.event(`pre_checkout_query received: user=${ctx.from.id} currency=${ctx.currency} amount=${ctx.totalAmount} payload="${ctx.invoicePayload}" id=${ctx.id}`);
+    const reject = async (reasonEn, reasonEs) => {
+        log.warn(`pre_checkout rejecting: ${reasonEn} (id=${ctx.id})`);
+        try {
+            await ctx.bot.api.answerPreCheckoutQuery({
+                pre_checkout_query_id: ctx.id,
+                ok: false,
+                // We don't have ctx.session on pre_checkout (it's a different
+                // event scope per gramio), so we can't read user lang. Default
+                // to a bilingual blurb that's intelligible to both en/es users.
+                error_message: `${reasonEn} · ${reasonEs}`,
+            });
+        }
+        catch (e) {
+            log.error(`answerPreCheckoutQuery(false) failed: ${e}`);
+        }
+    };
+    if (ctx.currency !== "XTR") {
+        await reject("Unsupported currency.", "Moneda no soportada.");
+        return;
+    }
+    const decoded = decodePayload(ctx.invoicePayload);
+    if (!decoded) {
+        await reject("Malformed invoice.", "Factura inválida.");
+        return;
+    }
+    if (decoded.userId !== ctx.from.id) {
+        await reject("User mismatch.", "Usuario no coincide.");
+        return;
+    }
+    const product = catalog.byKey.get(decoded.productKey);
+    if (!product) {
+        await reject("Unknown product.", "Producto desconocido.");
+        return;
+    }
+    if (product.xtr !== ctx.totalAmount) {
+        await reject(`Price changed (expected ${product.xtr}, got ${ctx.totalAmount}).`, "Precio cambiado.");
+        return;
+    }
+    log.success(`pre_checkout approving: product=${decoded.productKey} user=${ctx.from.id} amount=${ctx.totalAmount}`);
+    try {
+        await ctx.bot.api.answerPreCheckoutQuery({
+            pre_checkout_query_id: ctx.id,
+            ok: true,
+        });
+    }
+    catch (e) {
+        log.error(`answerPreCheckoutQuery(true) failed: ${e}`);
+    }
+};
+// ─── successful_payment handler ────────────────────────────────────
+const buildChargeRecord = (product, userId, payment, waiverSnapshot) => {
+    const base = {
+        chargeId: payment.telegram_payment_charge_id,
+        userId,
+        productKey: product.id,
+        xtr: payment.total_amount,
+        receivedAt: Date.now(),
+        payload: payment.invoice_payload,
+        waiverSnapshot,
+        paysupportState: "none",
+        refundedAt: null,
+        payoutBatchId: null,
+        creditsGranted: 0,
+    };
+    if (product.id.startsWith("vip.")) {
+        const v = product;
+        return {
+            ...base,
+            vipRung: v.rank,
+            subscriptionExpiresAt: payment.subscription_expiration_date,
+            creditsGranted: v.creditsGranted,
+        };
+    }
+    if (product.id.startsWith("credits.")) {
+        const c = product;
+        return { ...base, creditsGranted: c.creditsGranted };
+    }
+    // perk
+    const p = product;
+    return { ...base, perkKey: p.key };
+};
+/**
+ * Process a `successful_payment` event. Idempotent on chargeId.
+ *
+ * On first delivery:
+ *   1. Decode payload, look up product
+ *   2. Persist `ChargeRecord` + idempotency sentinel + user index
+ *   3. Mutate `ctx.session.pay.*` via `applyCharge`
+ *   4. Auto-cancel any LOWER vip rung (tier upgrade case)
+ *   5. Send user confirmation + emit onFulfilled hooks
+ *
+ * On duplicate delivery: returns silently.
+ */
+export const buildSuccessfulPaymentHandler = (opts) => async (ctx) => {
+    const payment = ctx.eventPayment?.payload;
+    if (!payment) {
+        log.warn("successful_payment handler fired but ctx.eventPayment.payload is undefined — gramio context shape changed?");
+        return;
+    }
+    if (payment.currency !== "XTR")
+        return; // fiat — not ours
+    log.event(`successful_payment received: chargeId=${payment.telegram_payment_charge_id} amount=${payment.total_amount} payload="${payment.invoice_payload}" subExpires=${payment.subscription_expiration_date ?? "n/a"}`);
+    const decoded = decodePayload(payment.invoice_payload);
+    if (!decoded) {
+        log.error(`successful_payment un-decodable payload — fulfillment skipped: chargeId=${payment.telegram_payment_charge_id} payload="${payment.invoice_payload}"`);
+        return;
+    }
+    const userId = ctx.from?.id ?? decoded.userId;
+    // Idempotency: claim chargeId via the sentinel store. Returns
+    // `true` on first claim, `false` if already claimed (duplicate
+    // delivery — Telegram retries `successful_payment` in some
+    // failure modes per the sendInvoice doc). NOT atomic under
+    // concurrent load (storage doesn't expose setNX); the window is
+    // bounded by Telegram's retry delay and acceptable for v1.
+    const claimed = await opts.stores.idempotency.claim(ctx, payment.telegram_payment_charge_id);
+    if (!claimed) {
+        log.info(`successful_payment idempotent no-op: chargeId=${payment.telegram_payment_charge_id} already fulfilled`);
+        return;
+    }
+    const product = opts.catalog.byKey.get(decoded.productKey);
+    if (!product) {
+        log.error(`successful_payment for unknown productKey "${decoded.productKey}" — config drift? chargeId=${payment.telegram_payment_charge_id}`);
+        return;
+    }
+    const waiverSnapshot = ctx.session.pay?.waiver;
+    if (!waiverSnapshot) {
+        // Should never happen: every invoice flow gates on waiver
+        // freshness. If we reach this point, our own gating logic has
+        // a hole. Scream so it gets found, but DON'T drop the user's
+        // money — finish fulfillment with a synthetic "missing
+        // snapshot" entry that's auditable. The `panic` is
+        // intentionally after the persistence path on purpose to keep
+        // the user whole; the next event will crash.
+        log.error(`CRITICAL: successful_payment without prior waiver — gate bypassed? userId=${userId} chargeId=${payment.telegram_payment_charge_id}`);
+    }
+    const charge = buildChargeRecord(product, userId, payment, waiverSnapshot ?? {
+        at: Date.now(),
+        version: opts.cfg.waiver.version,
+        locale: ctxLang(ctx),
+    });
+    // 1. Write the charge log + per-user index.
+    // (Idempotency sentinel was already claimed above.)
+    await opts.stores.charges.set(ctx, charge.chargeId, charge);
+    await opts.stores.userCharges(userId).prepend(ctx, charge.chargeId);
+    log.info(`charge persisted: chargeId=${charge.chargeId} product=${charge.productKey} user=${userId} xtr=${charge.xtr} creditsGranted=${charge.creditsGranted}`);
+    // 2. Apply to session (cache). Capture the previous vip chargeId
+    // FIRST so we can cancel its renewal below if this was an upgrade.
+    const previousVipChargeId = ctx.session.pay?.vip?.chargeId;
+    const previousVipRung = ctx.session.pay?.vip?.rung;
+    applyCharge(ctx.session, charge);
+    // 3. Tier-upgrade auto-cancel: when the user buys a HIGHER rung
+    // than their currently-active subscription, cancel the lower one's
+    // auto-renewal so they aren't double-billed at the next cycle. The
+    // lower rung keeps access until its period end — Telegram handles
+    // that silently because the higher rung's rank-based `atLeast`
+    // check already satisfies any vip.N check from now on.
+    if (charge.vipRung !== undefined &&
+        previousVipChargeId &&
+        previousVipChargeId !== charge.chargeId &&
+        previousVipRung !== undefined &&
+        previousVipRung < charge.vipRung) {
+        try {
+            await ctx.bot.api.editUserStarSubscription({
+                user_id: userId,
+                telegram_payment_charge_id: previousVipChargeId,
+                is_canceled: true,
+            });
+            log.info(`auto-canceled previous vip rung ${previousVipRung} on upgrade to ${charge.vipRung} (user=${userId})`);
+        }
+        catch (e) {
+            // Already canceled, expired, etc. Log; don't block fulfillment.
+            log.warn(`auto-cancel previous vip subscription failed (likely already canceled/expired): user=${userId} previousChargeId=${previousVipChargeId} err=${e instanceof Error ? e.message : String(e)}`);
+        }
+    }
+    // 4. User-facing confirmation
+    const lang = ctxLang(ctx);
+    await ctx.send(buildSuccessMessage(product, opts.cfg, lang));
+    // 5. Fire onFulfilled hooks (fire-and-forget)
+    const event = {
+        productKey: product.id,
+        userId,
+        chargeId: charge.chargeId,
+        xtr: charge.xtr,
+        receivedAt: charge.receivedAt,
+    };
+    const fireBucket = (key) => {
+        const arr = opts.onFulfilled.get(key);
+        if (!arr)
+            return;
+        for (const fn of arr) {
+            try {
+                fn(event, ctx);
+            }
+            catch (e) {
+                log.error(`onFulfilled handler for "${key}" threw: ${e}`);
+            }
+        }
+    };
+    fireBucket(product.id);
+    fireBucket("*");
+    log.success(`fulfillment complete: product=${product.id} user=${userId} chargeId=${charge.chargeId}`);
+    // 6. Sanity-fail AFTER everything has been persisted + the user
+    // has their confirmation — defensive, see CRITICAL log above.
+    if (!waiverSnapshot) {
+        panic("bot/payments: successful_payment fulfilled without a stored waiver " +
+            "snapshot. Gate logic has a hole. User was made whole; investigate.");
+    }
+};
+const buildSuccessMessage = (product, cfg, lang) => {
+    if (product.id.startsWith("vip.")) {
+        const v = product;
+        const name = v.name[lang] ??
+            v.name[FALLBACK_LANG] ??
+            "VIP";
+        return say({
+            en: `✅ Welcome to ${name}! Active for 30 days.`,
+            es: `✅ ¡Bienvenido a ${name}! Activo durante 30 días.`,
+        }, lang);
+    }
+    if (product.id.startsWith("credits.")) {
+        const c = product;
+        const unit = cfg.credits?.unit?.[lang] ??
+            "credits";
+        return say({
+            en: `✅ +${c.creditsGranted} ${unit} added to your balance.`,
+            es: `✅ +${c.creditsGranted} ${unit} añadidos a tu saldo.`,
+        }, lang);
+    }
+    const p = product;
+    const name = p.name[lang] ??
+        p.name[FALLBACK_LANG] ??
+        p.key;
+    return say({ en: `✅ Unlocked: ${name}.`, es: `✅ Desbloqueado: ${name}.` }, lang);
+};
+// ─── re-export SourcedError for catch sites ───────────────────────
+export { SourcedError };
+//# sourceMappingURL=handlers.js.map

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

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

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

@@ -0,0 +1,17 @@
+/**
+ * `bot/payments` — public exports.
+ *
+ * The factory `botPayments({...})` is the only thing most consumers
+ * need; everything else is exported for advanced wiring, tests, and
+ * type narrowing at consumer side.
+ *
+ * See `CLAUDE.md` in this folder for the design rationale + compliance
+ * memo (Spanish autónomo, Art. 103(m), Telegram Stars seller-of-record
+ * analysis, …).
+ */
+export type { ExportInput, ExportResult, PayoutsApi, RecordPayoutInput, } from "./payouts.js";
+export type { BotPaymentsOptions, BotPaymentsResult, PaymentsCtx, } from "./plugin.js";
+export { botPayments } from "./plugin.js";
+export type { AtLeastKey, BotPaymentsConfig, ChargeRecord, CreditsConfig, CreditsPack, DerivedPaymentsState, FulfillmentEvent, LegalConfig, PaymentsSession, PayoutRecord, PaysupportState, Perk, PerkState, PerksConfig, ProductKey, SubscriptionPeriod, TierKey, VipRung, VipState, WaiverConfig, WaiverRecord, } from "./types.js";
+export { InsufficientCredits } from "./types.js";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/bot/payments/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,YAAY,EACX,WAAW,EACX,YAAY,EACZ,UAAU,EACV,iBAAiB,GACjB,MAAM,cAAc,CAAC;AACtB,YAAY,EACX,kBAAkB,EAClB,iBAAiB,EACjB,WAAW,GACX,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC1C,YAAY,EACX,UAAU,EACV,iBAAiB,EACjB,YAAY,EACZ,aAAa,EACb,WAAW,EACX,oBAAoB,EACpB,gBAAgB,EAChB,WAAW,EACX,eAAe,EACf,YAAY,EACZ,eAAe,EACf,IAAI,EACJ,SAAS,EACT,WAAW,EACX,UAAU,EACV,kBAAkB,EAClB,OAAO,EACP,OAAO,EACP,QAAQ,EACR,YAAY,EACZ,YAAY,GACZ,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC"}

package/dist/bot/payments/index.js

@@ -0,0 +1,14 @@
+/**
+ * `bot/payments` — public exports.
+ *
+ * The factory `botPayments({...})` is the only thing most consumers
+ * need; everything else is exported for advanced wiring, tests, and
+ * type narrowing at consumer side.
+ *
+ * See `CLAUDE.md` in this folder for the design rationale + compliance
+ * memo (Spanish autónomo, Art. 103(m), Telegram Stars seller-of-record
+ * analysis, …).
+ */
+export { botPayments } from "./plugin.js";
+export { InsufficientCredits } from "./types.js";
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/bot/payments/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAaH,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAwB1C,OAAO,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC"}

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

@@ -0,0 +1,101 @@
+/**
+ * `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 type { BotPaymentsConfig, CreditsPackResolved, PaymentsSession, PerkResolved, ProductCatalog, VipRungResolved } from "./types.js";
+/**
+ * Structural shape we need from the calling ctx. Matches both
+ * `MessageContext` and `CallbackQueryContext` after gramio's mixins —
+ * we pull `chat.id` / `threadId` from either layout via short-circuits.
+ */
+export type InvoiceCtx = {
+    bot: {
+        api: {
+            sendInvoice: (params: SendInvoiceParams) => Promise<unknown>;
+        };
+    };
+    from?: {
+        id: number;
+    };
+    chat?: {
+        id: number;
+    };
+    threadId?: number;
+    message?: {
+        threadId?: number;
+        chat?: {
+            id: number;
+        };
+    };
+    session?: {
+        pay?: PaymentsSession;
+        language?: string;
+    };
+};
+/** Subset of the Telegram `sendInvoice` schema this module needs. */
+type SendInvoiceParams = {
+    chat_id: number;
+    message_thread_id?: number;
+    title: string;
+    description: string;
+    payload: string;
+    provider_token: string;
+    currency: "XTR";
+    prices: Array<{
+        label: string;
+        amount: number;
+    }>;
+    subscription_period?: number;
+    start_parameter?: string;
+};
+/**
+ * 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 declare const sendInvoiceForProduct: (ctx: InvoiceCtx, cfg: BotPaymentsConfig<string>, product: VipRungResolved | CreditsPackResolved | PerkResolved, userId: number) => Promise<void>;
+/**
+ * What the entry returned to mean. `'invoice_sent'` = the user got a
+ * Telegram payment sheet; `'waiver_prompt_sent'` = the user got the
+ * consent prompt and must tap before the invoice goes out;
+ * `'unknown_product'` = the key didn't resolve and we already told the
+ * user nothing happened.
+ */
+export type PresentInvoiceResult = "invoice_sent" | "waiver_prompt_sent" | "unknown_product";
+/**
+ * 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 declare const presentInvoice: (ctx: InvoiceCtx & {
+    send: (text: string, params?: object) => Promise<unknown>;
+}, cfg: BotPaymentsConfig<string>, catalog: ProductCatalog, productKey: string) => Promise<PresentInvoiceResult>;
+export {};
+//# sourceMappingURL=invoice.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"invoice.d.ts","sourceRoot":"","sources":["../../../src/bot/payments/invoice.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAMH,OAAO,KAAK,EACX,iBAAiB,EACjB,mBAAmB,EACnB,eAAe,EACf,YAAY,EACZ,cAAc,EACd,eAAe,EACf,MAAM,YAAY,CAAC;AAWpB;;;;GAIG;AACH,MAAM,MAAM,UAAU,GAAG;IACxB,GAAG,EAAE;QACJ,GAAG,EAAE;YACJ,WAAW,EAAE,CAAC,MAAM,EAAE,iBAAiB,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;SAC7D,CAAC;KACF,CAAC;IACF,IAAI,CAAC,EAAE;QAAE,EAAE,EAAE,MAAM,CAAA;KAAE,CAAC;IACtB,IAAI,CAAC,EAAE;QAAE,EAAE,EAAE,MAAM,CAAA;KAAE,CAAC;IACtB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE;QAAE,QAAQ,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE;YAAE,EAAE,EAAE,MAAM,CAAA;SAAE,CAAA;KAAE,CAAC;IACvD,OAAO,CAAC,EAAE;QAAE,GAAG,CAAC,EAAE,eAAe,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CACvD,CAAC;AAEF,qEAAqE;AACrE,KAAK,iBAAiB,GAAG;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,cAAc,EAAE,MAAM,CAAC;IACvB,QAAQ,EAAE,KAAK,CAAC;IAChB,MAAM,EAAE,KAAK,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACjD,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,eAAe,CAAC,EAAE,MAAM,CAAC;CACzB,CAAC;AA8HF;;;;;;;;GAQG;AACH,eAAO,MAAM,qBAAqB,GACjC,KAAK,UAAU,EACf,KAAK,iBAAiB,CAAC,MAAM,CAAC,EAC9B,SAAS,eAAe,GAAG,mBAAmB,GAAG,YAAY,EAC7D,QAAQ,MAAM,KACZ,OAAO,CAAC,IAAI,CAsDd,CAAC;AAIF;;;;;;GAMG;AACH,MAAM,MAAM,oBAAoB,GAC7B,cAAc,GACd,oBAAoB,GACpB,iBAAiB,CAAC;AAErB;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,cAAc,GAC1B,KAAK,UAAU,GAAG;IACjB,IAAI,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;CAC1D,EACD,KAAK,iBAAiB,CAAC,MAAM,CAAC,EAC9B,SAAS,cAAc,EACvB,YAAY,MAAM,KAChB,OAAO,CAAC,oBAAoB,CAuC9B,CAAC"}

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