@adriangalilea/utils 0.18.0 → 0.19.0

package/dist/bot/payments/types.js

@@ -0,0 +1,39 @@
+/**
+ * Type surface for `bot/payments`. Two layers:
+ *
+ *   1. **Config shapes** the consumer authors (`BotPaymentsConfig`).
+ *   2. **Derived types** the consumer reads through `ctx.payments`
+ *      (`TierKey`, `AtLeastKey`, `ProductKey`) — narrowed from their
+ *      config so e.g. `atLeast('vip.5')` is a TS error when only 2
+ *      rungs are declared.
+ *
+ * Internal types (the ledger records, the catalog) live below and aren't
+ * exported through the package entrypoint.
+ *
+ * See `CLAUDE.md` in this folder for the design rationale.
+ */
+/** Internal value Telegram expects on the wire (seconds). */
+export const SUBSCRIPTION_PERIOD_SECONDS = {
+    "30d": 2_592_000,
+};
+/**
+ * Fallback when `legal.privacyUrl` is omitted. Identical to the menu
+ * plugin's default — both surface the same policy text.
+ */
+export const DEFAULT_PRIVACY_URL = "https://telegram.org/privacy-tpa";
+// ─── error sentinel ────────────────────────────────────────────────
+/**
+ * Thrown by `credits.consume(n)` when the balance is below `n`.
+ * `tryConsume(n)` returns `false` instead.
+ */
+export class InsufficientCredits extends Error {
+    requested;
+    available;
+    constructor(requested, available) {
+        super(`InsufficientCredits: requested ${requested}, available ${available}`);
+        this.name = "InsufficientCredits";
+        this.requested = requested;
+        this.available = available;
+    }
+}
+//# sourceMappingURL=types.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/bot/payments/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAcH,6DAA6D;AAC7D,MAAM,CAAC,MAAM,2BAA2B,GAEpC;IACH,KAAK,EAAE,SAAS;CAChB,CAAC;AAwFF;;;GAGG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,kCAAkC,CAAC;AAoQtE,sEAAsE;AAEtE;;;GAGG;AACH,MAAM,OAAO,mBAAoB,SAAQ,KAAK;IACpC,SAAS,CAAS;IAClB,SAAS,CAAS;IAC3B,YAAY,SAAiB,EAAE,SAAiB;QAC/C,KAAK,CACJ,kCAAkC,SAAS,eAAe,SAAS,EAAE,CACrE,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,qBAAqB,CAAC;QAClC,IAAI,CAAC,SAAS,GAAG,SAAS,CAAC;QAC3B,IAAI,CAAC,SAAS,GAAG,SAAS,CAAC;IAC5B,CAAC;CACD"}

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

@@ -0,0 +1,81 @@
+/**
+ * Art. 103(m) TRLGDCU waiver flow.
+ *
+ * Three things have to happen together (see CLAUDE.md §5):
+ *
+ *   1. The user expresses *prior express consent* to begin execution.
+ *   2. They acknowledge they thereby lose the 14-day right of withdrawal.
+ *   3. The contract is confirmed on a durable medium.
+ *
+ * This module owns #1 and #2 via a separate, unbundled consent prompt
+ * — one inline message with the waiver text plus a single affirmative
+ * button. Bundling this into ToS acceptance voids the waiver under
+ * Spanish consumer law. #3 is satisfied implicitly by Telegram: every
+ * outgoing message the bot sends is preserved in the chat (durable).
+ *
+ * The bot author supplies the wording (Polyglot text + version string).
+ * Bumping `waiver.version` forces re-consent on the next purchase
+ * attempt; old consents stay attached to old charges for audit (see
+ * `ChargeRecord.waiverSnapshot`).
+ */
+import type { Storage } from "@gramio/storage";
+import { InlineKeyboard } from "gramio";
+import { type BotPaymentsConfig, type PaymentsSession, type WaiverRecord } from "./types.js";
+/**
+ * Callback fired when the user taps "✅ Consiento y comprendo" in the
+ * waiver consent prompt. Carries the productKey of the in-flight
+ * purchase so we can resume after persisting consent.
+ *
+ * `pk` (productKey) follows the shape validated by `payload.ts` —
+ * `vip.N` / `credits.N` / `perks.X` — all ASCII-safe.
+ */
+export declare const waiverConsentCb: import("gramio").CallbackData<Record<never, never>, Record<never, never>>;
+/** Fired when the user taps "❌ Cancelar" in the consent prompt. */
+export declare const waiverCancelCb: import("gramio").CallbackData<Record<never, never>, Record<never, never>>;
+/**
+ * Returns true when the stored consent matches the current waiver
+ * version — i.e. no re-consent needed before a purchase.
+ */
+export declare const isWaiverFresh: (stored: WaiverRecord | undefined, currentVersion: string) => boolean;
+/**
+ * Build the inline keyboard that accompanies the consent prompt. Three
+ * buttons:
+ *
+ *   📖 Términos — URL to `legal.termsUrl` (informational, not the
+ *                  affirmative action)
+ *   🔒 Privacidad — URL to `legal.privacyUrl` (same)
+ *   ✅ Consiento y comprendo — the single affirmative action
+ *   ❌ Cancelar — back out without consenting
+ *
+ * The "✅" button carries the productKey the user was about to buy, so
+ * the consent handler can resume the invoice flow on tap.
+ */
+export declare const waiverKeyboard: (cfg: BotPaymentsConfig<string>, productKey: string, lang: string) => InlineKeyboard;
+/**
+ * Render the consent body the user sees. Includes a short, neutral
+ * header above the wording supplied by the bot author. The header is
+ * separated by a blank line so reading order matches what consumer
+ * authorities expect (waiver text is unambiguous and prominent).
+ */
+export declare const renderConsentBody: (cfg: BotPaymentsConfig<string>, lang: string) => string;
+/**
+ * Persist a fresh waiver record onto the current ctx's session. Callers
+ * own the session shape via a structural narrow — this avoids a generic
+ * type bloom across the plugin.
+ */
+export declare const persistWaiverOnSession: (ctx: {
+    session: {
+        pay?: PaymentsSession;
+    };
+}, version: string, locale: string) => WaiverRecord;
+/**
+ * Persist a waiver record onto a SPECIFIC user's stored session (used
+ * when the consent tap arrives on a different ctx than the original
+ * `invoice()` call — rare, but possible if the user wedges multiple
+ * flows). The cross-user write is via storage directly, mirroring the
+ * pattern in `access-control.ts`.
+ */
+export declare const persistWaiverForUser: (storage: Storage, ctx: {
+    bot: unknown;
+}, userId: number, version: string, locale: string) => Promise<WaiverRecord>;
+//# sourceMappingURL=waiver.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"waiver.d.ts","sourceRoot":"","sources":["../../../src/bot/payments/waiver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,iBAAiB,CAAC;AAC/C,OAAO,EAAE,cAAc,EAAE,MAAM,QAAQ,CAAC;AAMxC,OAAO,EACN,KAAK,iBAAiB,EAEtB,KAAK,eAAe,EACpB,KAAK,YAAY,EACjB,MAAM,YAAY,CAAC;AAOpB;;;;;;;GAOG;AACH,eAAO,MAAM,eAAe,2EAA8C,CAAC;AAE3E,mEAAmE;AACnE,eAAO,MAAM,cAAc,2EAA+B,CAAC;AAI3D;;;GAGG;AACH,eAAO,MAAM,aAAa,GACzB,QAAQ,YAAY,GAAG,SAAS,EAChC,gBAAgB,MAAM,KACpB,OAGF,CAAC;AAiBF;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,cAAc,GAC1B,KAAK,iBAAiB,CAAC,MAAM,CAAC,EAC9B,YAAY,MAAM,EAClB,MAAM,MAAM,KACV,cA8BF,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,iBAAiB,GAC7B,KAAK,iBAAiB,CAAC,MAAM,CAAC,EAC9B,MAAM,MAAM,KACV,MAWU,CAAC;AAId;;;;GAIG;AACH,eAAO,MAAM,sBAAsB,GAClC,KAAK;IAAE,OAAO,EAAE;QAAE,GAAG,CAAC,EAAE,eAAe,CAAA;KAAE,CAAA;CAAE,EAC3C,SAAS,MAAM,EACf,QAAQ,MAAM,KACZ,YAUF,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,oBAAoB,GAChC,SAAS,OAAO,EAChB,KAAK;IAAE,GAAG,EAAE,OAAO,CAAA;CAAE,EACrB,QAAQ,MAAM,EACd,SAAS,MAAM,EACf,QAAQ,MAAM,KACZ,OAAO,CAAC,YAAY,CAatB,CAAC"}

package/dist/bot/payments/waiver.js

@@ -0,0 +1,145 @@
+/**
+ * Art. 103(m) TRLGDCU waiver flow.
+ *
+ * Three things have to happen together (see CLAUDE.md §5):
+ *
+ *   1. The user expresses *prior express consent* to begin execution.
+ *   2. They acknowledge they thereby lose the 14-day right of withdrawal.
+ *   3. The contract is confirmed on a durable medium.
+ *
+ * This module owns #1 and #2 via a separate, unbundled consent prompt
+ * — one inline message with the waiver text plus a single affirmative
+ * button. Bundling this into ToS acceptance voids the waiver under
+ * Spanish consumer law. #3 is satisfied implicitly by Telegram: every
+ * outgoing message the bot sends is preserved in the chat (durable).
+ *
+ * The bot author supplies the wording (Polyglot text + version string).
+ * Bumping `waiver.version` forces re-consent on the next purchase
+ * attempt; old consents stay attached to old charges for audit (see
+ * `ChargeRecord.waiverSnapshot`).
+ */
+import { InlineKeyboard } from "gramio";
+import { say } from "../../say/index.js";
+import { createLogger } from "../../universal/log.js";
+import { callbackNs } from "../callbacks.js";
+import { botStorageKey } from "../kit.js";
+import { DEFAULT_PRIVACY_URL, } from "./types.js";
+const FALLBACK_LANG = "en";
+const log = createLogger("bot/payments");
+const cb = callbackNs("pay");
+/**
+ * Callback fired when the user taps "✅ Consiento y comprendo" in the
+ * waiver consent prompt. Carries the productKey of the in-flight
+ * purchase so we can resume after persisting consent.
+ *
+ * `pk` (productKey) follows the shape validated by `payload.ts` —
+ * `vip.N` / `credits.N` / `perks.X` — all ASCII-safe.
+ */
+export const waiverConsentCb = cb.data("waiver:consent", { pk: "string" });
+/** Fired when the user taps "❌ Cancelar" in the consent prompt. */
+export const waiverCancelCb = cb.data("waiver:cancel", {});
+// ─── pure helpers ──────────────────────────────────────────────────
+/**
+ * Returns true when the stored consent matches the current waiver
+ * version — i.e. no re-consent needed before a purchase.
+ */
+export const isWaiverFresh = (stored, currentVersion) => {
+    if (!stored)
+        return false;
+    return stored.version === currentVersion;
+};
+/**
+ * Resolve the waiver text Polyglot to a single string for the recipient's
+ * locale, with `'en'` fallback. Matches `say()`'s semantics for the
+ * dynamic-string escape hatch.
+ */
+const resolveWaiverText = (cfg, lang) => {
+    const text = cfg.waiver.text;
+    return text[lang] ?? text[FALLBACK_LANG] ?? Object.values(text)[0] ?? "";
+};
+// ─── consent prompt rendering ──────────────────────────────────────
+/**
+ * Build the inline keyboard that accompanies the consent prompt. Three
+ * buttons:
+ *
+ *   📖 Términos — URL to `legal.termsUrl` (informational, not the
+ *                  affirmative action)
+ *   🔒 Privacidad — URL to `legal.privacyUrl` (same)
+ *   ✅ Consiento y comprendo — the single affirmative action
+ *   ❌ Cancelar — back out without consenting
+ *
+ * The "✅" button carries the productKey the user was about to buy, so
+ * the consent handler can resume the invoice flow on tap.
+ */
+export const waiverKeyboard = (cfg, productKey, lang) => {
+    const kb = new InlineKeyboard();
+    const termsUrl = cfg.legal.termsUrl;
+    const privacyUrl = cfg.legal.privacyUrl ?? DEFAULT_PRIVACY_URL;
+    // Terms button only renders if the bot configured a termsUrl —
+    // there's no Telegram-side standard ToS to default to. Privacy
+    // always renders; it falls back to Telegram's Standard Bot Privacy
+    // Policy when unset (covers what this library retains by default).
+    if (termsUrl) {
+        kb.url(say({ en: "📖 Terms", es: "📖 Términos" }, lang), termsUrl);
+    }
+    kb.url(say({ en: "🔒 Privacy", es: "🔒 Privacidad" }, lang), privacyUrl);
+    kb.row();
+    kb.text(say({
+        en: "✅ I consent and understand",
+        es: "✅ Consiento y comprendo",
+    }, lang), waiverConsentCb.pack({ pk: productKey }), { style: "primary" });
+    kb.row();
+    kb.text(say({ en: "❌ Cancel", es: "❌ Cancelar" }, lang), waiverCancelCb.pack({}));
+    return kb;
+};
+/**
+ * Render the consent body the user sees. Includes a short, neutral
+ * header above the wording supplied by the bot author. The header is
+ * separated by a blank line so reading order matches what consumer
+ * authorities expect (waiver text is unambiguous and prominent).
+ */
+export const renderConsentBody = (cfg, lang) => [
+    say({
+        en: "Before continuing, please read and consent:",
+        es: "Antes de continuar, lee y consiente:",
+    }, lang),
+    "",
+    resolveWaiverText(cfg, lang),
+].join("\n");
+// ─── persistence ───────────────────────────────────────────────────
+/**
+ * Persist a fresh waiver record onto the current ctx's session. Callers
+ * own the session shape via a structural narrow — this avoids a generic
+ * type bloom across the plugin.
+ */
+export const persistWaiverOnSession = (ctx, version, locale) => {
+    const record = {
+        at: Date.now(),
+        version,
+        locale,
+    };
+    ctx.session.pay ??= {};
+    ctx.session.pay.waiver = record;
+    log.success(`waiver consent persisted: version=${version} locale=${locale}`);
+    return record;
+};
+/**
+ * Persist a waiver record onto a SPECIFIC user's stored session (used
+ * when the consent tap arrives on a different ctx than the original
+ * `invoice()` call — rare, but possible if the user wedges multiple
+ * flows). The cross-user write is via storage directly, mirroring the
+ * pattern in `access-control.ts`.
+ */
+export const persistWaiverForUser = async (storage, ctx, userId, version, locale) => {
+    const key = botStorageKey(ctx, userId);
+    const full = ((await storage.get(key)) ?? {});
+    const record = {
+        at: Date.now(),
+        version,
+        locale,
+    };
+    full.pay = { ...(full.pay ?? {}), waiver: record };
+    await storage.set(key, full);
+    return record;
+};
+//# sourceMappingURL=waiver.js.map

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

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

package/dist/bot/storage.d.ts

@@ -0,0 +1,154 @@
+/**
+ * Typed storage abstraction for `bot/*` plugins.
+ *
+ * Replaces the per-plugin `botSubKey + storage.get/set` boilerplate
+ * with three small primitives that automatically:
+ *
+ *   - **Namespace by bot id.** Every key gets `bot-<id>:` prefixed via
+ *     `ctx.bot.info.id`, so multiple bots sharing one Redis stay
+ *     isolated by construction (see `bot/CLAUDE.md` § Multi-bot
+ *     isolation). No plugin has to remember to wrap.
+ *
+ *   - **Validate on read** (optional). Pass any `{ parse(data:
+ *     unknown): T }` validator (zod / valibot / arktype / yours) and a
+ *     mis-shaped record from storage throws a clear `SourcedError`
+ *     instead of NaN-ing downstream. Omit the validator and you get
+ *     the same untyped read as before.
+ *
+ *   - **Stay typed end-to-end.** `botRecord<ChargeRecord>(...)` returns
+ *     a `BotRecord<ChargeRecord>` and `.get()` is `Promise<ChargeRecord
+ *     | undefined>`. No casts at the call site.
+ *
+ * ## Three primitives
+ *
+ *   - `botRecord<T>(storage, prefix, validator?)` — get/set/delete a
+ *     single typed value keyed by an id (`pay:charge:<chargeId>`,
+ *     `ac:user:<userId>`, …). Most plugin state.
+ *
+ *   - `botIndex(storage, prefix, opts?)` — a capped, prepend-friendly
+ *     `string[]` stored under a single key. Use for "recent N
+ *     charges", "pending access requests", etc.
+ *
+ *   - `botSentinel(storage, prefix)` — a presence flag (`"1"` / absent)
+ *     for idempotency. `claim(ctx, id)` returns `true` only on first
+ *     call; subsequent calls return `false` without setting. Note:
+ *     read-then-write is NOT atomic under concurrent load; for
+ *     production we'd want a storage backend with `setNX` semantics.
+ *
+ * ## Why not couple to zod?
+ *
+ * The validator parameter is typed as `{ parse(data: unknown): T }` —
+ * a structural shape that zod schemas, valibot, ArkType, and hand-rolled
+ * type guards all satisfy. The library has zero zod imports; consumers
+ * bring whichever validator they prefer.
+ */
+import type { Storage } from "@gramio/storage";
+import type { BotIdCtx } from "./ctx.js";
+/**
+ * Anything with a synchronous `parse(unknown): T`. zod schemas satisfy
+ * this natively (`.parse` throws on invalid input). Custom guards work
+ * the same way: `{ parse: (d) => { if (!ok(d)) throw new Error(...); return d as T } }`.
+ */
+export type RecordValidator<T> = {
+    parse: (data: unknown) => T;
+};
+export type BotRecord<T> = {
+    /** Storage key for `id` under this record's prefix. */
+    keyFor: (ctx: BotIdCtx, id: string) => string;
+    /** `undefined` on miss; throws `SourcedError` on validator failure. */
+    get: (ctx: BotIdCtx, id: string) => Promise<T | undefined>;
+    /** Overwrites unconditionally. Use `botSentinel` if you need set-if-absent. */
+    set: (ctx: BotIdCtx, id: string, value: T) => Promise<void>;
+    /** Hard delete. No-op if absent. */
+    delete: (ctx: BotIdCtx, id: string) => Promise<void>;
+    /** `true` if a record exists at `id` (no read, no validation). */
+    has: (ctx: BotIdCtx, id: string) => Promise<boolean>;
+};
+/**
+ * Typed record store, auto-namespaced by bot id.
+ *
+ * @example  per-charge record with zod validation
+ *
+ *   const charges = botRecord<ChargeRecord>(
+ *     storage,
+ *     'pay:charge',
+ *     ChargeRecordSchema,   // any zod.ZodType<ChargeRecord>
+ *   )
+ *   await charges.set(ctx, chargeId, charge)
+ *   const c = await charges.get(ctx, chargeId)
+ *
+ * @example  without a validator (backwards-compatible behaviour)
+ *
+ *   const charges = botRecord<ChargeRecord>(storage, 'pay:charge')
+ *   const c = await charges.get(ctx, chargeId)  // typed but unchecked
+ */
+export declare const botRecord: <T>(storage: Storage, prefix: string, validator?: RecordValidator<T>) => BotRecord<T>;
+export type BotIndexOptions = {
+    /**
+     * Maximum number of ids retained. New `prepend` calls past this
+     * limit drop the OLDEST id. Omit for an unbounded index (a
+     * footgun for high-volume bots — set a cap).
+     */
+    capacity?: number;
+};
+export type BotIndex = {
+    keyFor: (ctx: BotIdCtx) => string;
+    /** Newest-first list of ids, capped to `capacity` if configured. */
+    list: (ctx: BotIdCtx) => Promise<string[]>;
+    /** Insert `id` at the front. Idempotent: re-prepending an existing
+     *  id moves it to the front. Returns the new length post-cap. */
+    prepend: (ctx: BotIdCtx, id: string) => Promise<number>;
+    /** Remove `id`. No-op if absent. Returns whether anything was removed. */
+    remove: (ctx: BotIdCtx, id: string) => Promise<boolean>;
+    /** Wipe the whole index. */
+    clear: (ctx: BotIdCtx) => Promise<void>;
+};
+/**
+ * Newest-first capped list of ids stored under a single key. Designed
+ * for "user's last N charges", "pending access requests", "recent
+ * payouts" — small, ordered, bounded.
+ *
+ * `prepend(id)` is the only mutator. Re-prepending an existing id moves
+ * it to the front (de-duplication). At-cap inserts drop the tail.
+ */
+export declare const botIndex: (storage: Storage, prefix: string, opts?: BotIndexOptions) => BotIndex;
+export type BotSentinel = {
+    keyFor: (ctx: BotIdCtx, id: string) => string;
+    /**
+     * Attempt to claim `id`. Returns `true` on first claim (and
+     * persists), `false` if already claimed (no write).
+     *
+     * NOT atomic under concurrent load — the read and write happen as
+     * two ops. For at-most-once semantics under contention, swap the
+     * storage backend for one with `setNX` (e.g. `@gramio/storage-redis`
+     * with a `setIfNotExists` helper) and override this method. For
+     * single-process polling bots (the v1 target), the race window is
+     * bounded by Telegram's retry delay and acceptable.
+     */
+    claim: (ctx: BotIdCtx, id: string) => Promise<boolean>;
+    /** `true` if `id` has been claimed. No write. */
+    check: (ctx: BotIdCtx, id: string) => Promise<boolean>;
+    /** Release a claim. Returns whether anything was released. */
+    release: (ctx: BotIdCtx, id: string) => Promise<boolean>;
+};
+/**
+ * Presence-flag store for idempotency. Each id is either claimed
+ * (storage has the key) or not (storage doesn't). The stored value is
+ * an opaque sentinel string — readers only care about presence.
+ *
+ * @example  idempotent successful_payment fulfillment
+ *
+ *   const idem = botSentinel(storage, 'pay:idem')
+ *   if (!(await idem.claim(ctx, chargeId))) return  // duplicate, no-op
+ *   await fulfill(charge)
+ */
+export declare const botSentinel: (storage: Storage, prefix: string) => BotSentinel;
+/**
+ * Wrap any `BotRecord` with trace-level logging for every read/write.
+ * Useful when debugging a specific plugin's storage flow without
+ * polluting every other plugin's logs. Defaults off.
+ *
+ *   const charges = withTracing(botRecord<ChargeRecord>(...), 'pay:charge')
+ */
+export declare const withTracing: <T>(record: BotRecord<T>, label: string) => BotRecord<T>;
+//# sourceMappingURL=storage.d.ts.map

package/dist/bot/storage.d.ts.map

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

package/dist/bot/storage.js

@@ -0,0 +1,222 @@
+/**
+ * Typed storage abstraction for `bot/*` plugins.
+ *
+ * Replaces the per-plugin `botSubKey + storage.get/set` boilerplate
+ * with three small primitives that automatically:
+ *
+ *   - **Namespace by bot id.** Every key gets `bot-<id>:` prefixed via
+ *     `ctx.bot.info.id`, so multiple bots sharing one Redis stay
+ *     isolated by construction (see `bot/CLAUDE.md` § Multi-bot
+ *     isolation). No plugin has to remember to wrap.
+ *
+ *   - **Validate on read** (optional). Pass any `{ parse(data:
+ *     unknown): T }` validator (zod / valibot / arktype / yours) and a
+ *     mis-shaped record from storage throws a clear `SourcedError`
+ *     instead of NaN-ing downstream. Omit the validator and you get
+ *     the same untyped read as before.
+ *
+ *   - **Stay typed end-to-end.** `botRecord<ChargeRecord>(...)` returns
+ *     a `BotRecord<ChargeRecord>` and `.get()` is `Promise<ChargeRecord
+ *     | undefined>`. No casts at the call site.
+ *
+ * ## Three primitives
+ *
+ *   - `botRecord<T>(storage, prefix, validator?)` — get/set/delete a
+ *     single typed value keyed by an id (`pay:charge:<chargeId>`,
+ *     `ac:user:<userId>`, …). Most plugin state.
+ *
+ *   - `botIndex(storage, prefix, opts?)` — a capped, prepend-friendly
+ *     `string[]` stored under a single key. Use for "recent N
+ *     charges", "pending access requests", etc.
+ *
+ *   - `botSentinel(storage, prefix)` — a presence flag (`"1"` / absent)
+ *     for idempotency. `claim(ctx, id)` returns `true` only on first
+ *     call; subsequent calls return `false` without setting. Note:
+ *     read-then-write is NOT atomic under concurrent load; for
+ *     production we'd want a storage backend with `setNX` semantics.
+ *
+ * ## Why not couple to zod?
+ *
+ * The validator parameter is typed as `{ parse(data: unknown): T }` —
+ * a structural shape that zod schemas, valibot, ArkType, and hand-rolled
+ * type guards all satisfy. The library has zero zod imports; consumers
+ * bring whichever validator they prefer.
+ */
+import { SourcedError } from "../offensive.js";
+import { createLogger } from "../universal/log.js";
+const log = createLogger("bot/storage");
+const botIdOf = (ctx) => {
+    const id = ctx.bot?.info?.id;
+    if (typeof id !== "number") {
+        throw new SourcedError({
+            source: "storage",
+            operation: "key",
+            message: "ctx.bot.info.id is missing — called before bot.start()/bot.init()?",
+        });
+    }
+    return id;
+};
+/**
+ * Build the namespaced key for a record / index / sentinel. Matches
+ * the format `botSubKey` / `botStorageKey` in `kit.ts` use, so the
+ * abstractions compose with anything that still consumes those.
+ */
+const buildKey = (ctx, prefix, id) => {
+    const base = `bot-${botIdOf(ctx)}:${prefix}`;
+    return id !== undefined ? `${base}:${id}` : base;
+};
+const parseOr = (raw, validator, key) => {
+    if (!validator)
+        return raw;
+    try {
+        return validator.parse(raw);
+    }
+    catch (cause) {
+        throw new SourcedError({
+            source: "storage",
+            operation: "validate",
+            message: cause instanceof Error
+                ? cause.message
+                : "validator threw a non-Error value",
+            cause,
+            context: { key },
+        });
+    }
+};
+/**
+ * Typed record store, auto-namespaced by bot id.
+ *
+ * @example  per-charge record with zod validation
+ *
+ *   const charges = botRecord<ChargeRecord>(
+ *     storage,
+ *     'pay:charge',
+ *     ChargeRecordSchema,   // any zod.ZodType<ChargeRecord>
+ *   )
+ *   await charges.set(ctx, chargeId, charge)
+ *   const c = await charges.get(ctx, chargeId)
+ *
+ * @example  without a validator (backwards-compatible behaviour)
+ *
+ *   const charges = botRecord<ChargeRecord>(storage, 'pay:charge')
+ *   const c = await charges.get(ctx, chargeId)  // typed but unchecked
+ */
+export const botRecord = (storage, prefix, validator) => ({
+    keyFor: (ctx, id) => buildKey(ctx, prefix, id),
+    get: async (ctx, id) => {
+        const key = buildKey(ctx, prefix, id);
+        const raw = await storage.get(key);
+        if (raw === undefined)
+            return undefined;
+        return parseOr(raw, validator, key);
+    },
+    // `@gramio/storage`'s methods return `MaybePromise<T>` (sync- or
+    // async-storage agnostic). We normalize to `Promise<T>` via
+    // `Promise.resolve` so callers don't have to care which backend
+    // they're on.
+    set: async (ctx, id, value) => void (await storage.set(buildKey(ctx, prefix, id), value)),
+    delete: async (ctx, id) => void (await storage.delete(buildKey(ctx, prefix, id))),
+    has: async (ctx, id) => (await storage.has(buildKey(ctx, prefix, id))) === true,
+});
+/**
+ * Newest-first capped list of ids stored under a single key. Designed
+ * for "user's last N charges", "pending access requests", "recent
+ * payouts" — small, ordered, bounded.
+ *
+ * `prepend(id)` is the only mutator. Re-prepending an existing id moves
+ * it to the front (de-duplication). At-cap inserts drop the tail.
+ */
+export const botIndex = (storage, prefix, opts = {}) => {
+    const cap = opts.capacity;
+    return {
+        keyFor: (ctx) => buildKey(ctx, prefix),
+        list: async (ctx) => {
+            const key = buildKey(ctx, prefix);
+            return (await storage.get(key)) ?? [];
+        },
+        prepend: async (ctx, id) => {
+            const key = buildKey(ctx, prefix);
+            const existing = (await storage.get(key)) ?? [];
+            // De-dup: remove if present, then unshift. Cap at the end.
+            const filtered = existing.filter((x) => x !== id);
+            filtered.unshift(id);
+            const trimmed = cap !== undefined && filtered.length > cap
+                ? filtered.slice(0, cap)
+                : filtered;
+            await storage.set(key, trimmed);
+            return trimmed.length;
+        },
+        remove: async (ctx, id) => {
+            const key = buildKey(ctx, prefix);
+            const existing = (await storage.get(key)) ?? [];
+            const filtered = existing.filter((x) => x !== id);
+            if (filtered.length === existing.length)
+                return false;
+            await storage.set(key, filtered);
+            return true;
+        },
+        clear: async (ctx) => void (await storage.delete(buildKey(ctx, prefix))),
+    };
+};
+/**
+ * Presence-flag store for idempotency. Each id is either claimed
+ * (storage has the key) or not (storage doesn't). The stored value is
+ * an opaque sentinel string — readers only care about presence.
+ *
+ * @example  idempotent successful_payment fulfillment
+ *
+ *   const idem = botSentinel(storage, 'pay:idem')
+ *   if (!(await idem.claim(ctx, chargeId))) return  // duplicate, no-op
+ *   await fulfill(charge)
+ */
+export const botSentinel = (storage, prefix) => {
+    const SENTINEL = "1";
+    return {
+        keyFor: (ctx, id) => buildKey(ctx, prefix, id),
+        claim: async (ctx, id) => {
+            const key = buildKey(ctx, prefix, id);
+            const existing = await storage.get(key);
+            if (existing !== undefined)
+                return false;
+            await storage.set(key, SENTINEL);
+            return true;
+        },
+        check: async (ctx, id) => {
+            const key = buildKey(ctx, prefix, id);
+            return (await storage.get(key)) !== undefined;
+        },
+        release: async (ctx, id) => {
+            const key = buildKey(ctx, prefix, id);
+            if ((await storage.get(key)) === undefined)
+                return false;
+            await storage.delete(key);
+            return true;
+        },
+    };
+};
+// ─── observability hook (opt-in) ──────────────────────────────────
+/**
+ * Wrap any `BotRecord` with trace-level logging for every read/write.
+ * Useful when debugging a specific plugin's storage flow without
+ * polluting every other plugin's logs. Defaults off.
+ *
+ *   const charges = withTracing(botRecord<ChargeRecord>(...), 'pay:charge')
+ */
+export const withTracing = (record, label) => ({
+    keyFor: record.keyFor,
+    get: async (ctx, id) => {
+        const result = await record.get(ctx, id);
+        log.trace(`${label}.get(${id}) → ${result === undefined ? "miss" : "hit"}`);
+        return result;
+    },
+    set: async (ctx, id, value) => {
+        await record.set(ctx, id, value);
+        log.trace(`${label}.set(${id})`);
+    },
+    delete: async (ctx, id) => {
+        await record.delete(ctx, id);
+        log.trace(`${label}.delete(${id})`);
+    },
+    has: (ctx, id) => record.has(ctx, id),
+});
+//# sourceMappingURL=storage.js.map