@adriangalilea/utils 0.26.0 → 0.28.0

package/README.md

@@ -385,7 +385,9 @@ Then `pnpm install`. Every `ctx.send` / `ctx.sendDocument` / `ctx.reply` / etc.
 |---|---|
 | `@adriangalilea/utils/bot/ctx` | Structural ctx types (`BotMessageCtx`, `BotCallbackCtx`, …) and the `narrow<T>(ctx)` cast helper. Pure typing — no runtime state. |
 | `@adriangalilea/utils/bot/keys` | The bot-id key namespace, a **persisted contract**: `botId(ctx)`, `botStorageKey(ctx, userId)` → `bot-<id>:<userId>`, `botSubKey(ctx, sub)` → `bot-<id>:<sub>`. Every storage key the library writes derives from here, and those keys live in YOUR Redis/D1 rows — the shape never changes. Pure functions of `ctx.bot.info.id` (no env/fs), which is what keeps the whole bot surface Worker-safe. |
-| `@adriangalilea/utils/bot/kit` | `gracefulStart(bot, opts?)` — SIGINT/SIGTERM → `bot.stop()` → exit; force-kills if shutdown hangs. DMs the admin `@<bot> started.` / `@<bot> shutting down.` by default when `KEV.TELEGRAM_ADMIN_ID` is set (graceful only — crashes don't trigger `onStop`); pass `notifyAdmin: false` to disable or `notifyAdmin: 12345` for an explicit chat id.<br>`adminContext({ adminId? })` — reads `TELEGRAM_ADMIN_ID` from `kev` (with optional hardcoded fallback), decorates `ctx.adminId` + `ctx.isAdmin`.<br>`botSession(opts)` — **drop-in replacement for `@gramio/session`'s `session()`** that auto-namespaces every key as `bot-<id>:<senderId>` using `ctx.bot.info.id` (populated by `getMe()` at startup). Use this instead of `session()` — full stop. Multiple bots sharing one Redis stay isolated by construction; every plugin in this package derives the same prefix internally via `botStorageKey(ctx, userId)` / `botSubKey(ctx, sub)` (from `bot/keys`). No regex, no manual prefix argument, no way to forget.<br>`prefixStorage(storage, prefix)` — escape hatch for adding a top-level prefix on top of the bot-id namespace; almost never needed. |
+| `@adriangalilea/utils/bot/kit` | The Node-only corner. `gracefulStart(bot, opts?)` — SIGINT/SIGTERM → `bot.stop()` → exit; force-kills if shutdown hangs. DMs the admin `@<bot> started.` / `@<bot> shutting down.` by default when `KEV.TELEGRAM_ADMIN_ID` is set (graceful only — crashes don't trigger `onStop`); pass `notifyAdmin: false` to disable or `notifyAdmin: 12345` for an explicit chat id.<br>`adminContext({ adminId? })` — reads `TELEGRAM_ADMIN_ID` from `kev` (with optional hardcoded fallback), decorates `ctx.adminId` + `ctx.isAdmin`.<br>Also re-exports `botSession` / `prefixStorage` from `bot/session` so Node consumers keep one import. |
+| `@adriangalilea/utils/bot/session` | `botSession(opts)` — **drop-in replacement for `@gramio/session`'s `session()`** that auto-namespaces every key as `bot-<id>:<senderId>` using `ctx.bot.info.id` (populated by `getMe()` at startup). Use this instead of `session()` — full stop. Multiple bots sharing one Redis/D1 stay isolated by construction; every plugin in this package derives the same prefix internally via `botStorageKey(ctx, userId)` / `botSubKey(ctx, sub)` (from `bot/keys`). No regex, no manual prefix argument, no way to forget.<br>`prefixStorage(storage, prefix)` — escape hatch for adding a top-level prefix on top of the bot-id namespace; almost never needed. Worker-safe (used to live in `bot/kit`, which forced Worker bots to hand-roll the keying). |
+| `@adriangalilea/utils/bot/notify` | Best-effort admin DMs, worker-safe (you pass the ids; no env, no process). `notifyAdmins(bot, adminIds, text, extra?)` — DM each admin, failures logged and swallowed (a notification must never take the bot down). `alertAdminError(bot, adminIds, label, error, throttle?)` — truncated `🚨 label\nName: message`, rate-limited through a caller-owned `alertThrottle(ms?)` so a failure storm sends one alert per window. `gracefulStart`'s start/stop DMs are built on this. |
 | `@adriangalilea/utils/bot/access-control` | Personal-bot ACL — gates non-admin/non-default users; admin gets DM with `[✅ Aprobar][❌ Denegar]` on first attempt; `/access` opens a persistent menu (revoke / reapprove / list pending). Backed by `@gramio/session` per-user + a small index. **Native alternative**: BotFather → Bot Settings → Access → "Restrict bot usage" — flat allow-list at Telegram. Use this plugin when you want in-bot approval flow instead of a BotFather round-trip; both can coexist. |
 | `@adriangalilea/utils/bot/allow-list` | Static allow-list by **id and/or @username** — stateless, no session/storage. `allowList({ ids?, usernames? })` is a plugin that decorates `ctx.allowed` (boolean); gate in your handlers (`if (!ctx.allowed) return`). `makeAllowList(...)` is the pure framework-free predicate. The light counterpart to `access-control` (which adds an approve/deny flow + revocable store, needing session+storage). Username caveat: a `@username` is optional and mutable, and the Bot API can't resolve username→id ahead of time — prefer `ids` when known, `usernames` is the pragmatic fallback. |
 | `@adriangalilea/utils/bot/coalesce` | Joins client-split inbound messages back into one. When a user pastes >4096 chars, Telegram clients fragment it into separate `message` updates with no marker. Middleware detects the burst and emits one combined event. |
@@ -398,7 +400,8 @@ Standard wiring:
 ```typescript
 import { Bot } from 'gramio'
 import { redisStorage } from '@gramio/storage-redis'
-import { adminContext, botSession, gracefulStart } from '@adriangalilea/utils/bot/kit'
+import { adminContext, gracefulStart } from '@adriangalilea/utils/bot/kit'
+import { botSession } from '@adriangalilea/utils/bot/session'
 import { accessControl } from '@adriangalilea/utils/bot/access-control'
 import { llmStream, llmHistory } from '@adriangalilea/utils/bot/llm'
 

package/dist/bot/callbacks.d.ts

@@ -49,6 +49,16 @@
 import { CallbackData } from "gramio";
 type FieldType = "string" | "number" | "string?" | "number?";
 type FieldDef = Readonly<Record<string, FieldType>>;
+type RequiredFieldKeys<F extends FieldDef> = {
+    [K in keyof F]: F[K] extends "string" | "number" ? K : never;
+}[keyof F];
+type FieldBase<T extends FieldType> = T extends `string${string}` ? string : number;
+type SchemaOf<F extends FieldDef> = {
+    [K in RequiredFieldKeys<F> & string]: FieldBase<F[K]>;
+} & {
+    [K in Exclude<keyof F, RequiredFieldKeys<F>> & string]?: FieldBase<F[K]>;
+};
+type TypedCallbackData<F extends FieldDef> = CallbackData<SchemaOf<F>, SchemaOf<F>>;
 export type CallbackNamespace = {
     readonly prefix: string;
     /**
@@ -61,7 +71,7 @@ export type CallbackNamespace = {
      * HMR / dual-import). A second registration with different fields
      * panics — that's a programming error, not a runtime issue.
      */
-    data: <F extends FieldDef>(name: string, fields: F) => CallbackData;
+    data: <F extends FieldDef>(name: string, fields: F) => TypedCallbackData<F>;
 };
 /**
  * Reserve a callback-data prefix for a plugin. Returns a namespace

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

@@ -1 +1 @@
-{"version":3,"file":"callbacks.d.ts","sourceRoot":"","sources":["../../src/bot/callbacks.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,QAAQ,CAAC;AAMtC,KAAK,SAAS,GAAG,QAAQ,GAAG,QAAQ,GAAG,SAAS,GAAG,SAAS,CAAC;AAE7D,KAAK,QAAQ,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC,CAAC;AAsCpD,MAAM,MAAM,iBAAiB,GAAG;IAC/B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB;;;;;;;;;OASG;IACH,IAAI,EAAE,CAAC,CAAC,SAAS,QAAQ,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC,KAAK,YAAY,CAAC;CACpE,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,UAAU,GAAI,QAAQ,MAAM,KAAG,iBAgC3C,CAAC;AAIF;;;GAGG;AACH,eAAO,MAAM,mBAAmB,QAAO,aAAa,CAAC;IACpD,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,QAAQ,CAAC;CACjB,CAIG,CAAC;AAEL;;;GAGG;AACH,eAAO,MAAM,sBAAsB,QAAO,IAEzC,CAAC"}
+{"version":3,"file":"callbacks.d.ts","sourceRoot":"","sources":["../../src/bot/callbacks.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,QAAQ,CAAC;AAMtC,KAAK,SAAS,GAAG,QAAQ,GAAG,QAAQ,GAAG,SAAS,GAAG,SAAS,CAAC;AAE7D,KAAK,QAAQ,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC,CAAC;AAMpD,KAAK,iBAAiB,CAAC,CAAC,SAAS,QAAQ,IAAI;KAC3C,CAAC,IAAI,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,QAAQ,GAAG,QAAQ,GAAG,CAAC,GAAG,KAAK;CAC5D,CAAC,MAAM,CAAC,CAAC,CAAC;AACX,KAAK,SAAS,CAAC,CAAC,SAAS,SAAS,IAAI,CAAC,SAAS,SAAS,MAAM,EAAE,GAC9D,MAAM,GACN,MAAM,CAAC;AACV,KAAK,QAAQ,CAAC,CAAC,SAAS,QAAQ,IAAI;KAClC,CAAC,IAAI,iBAAiB,CAAC,CAAC,CAAC,GAAG,MAAM,GAAG,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;CACrD,GAAG;KACF,CAAC,IAAI,OAAO,CAAC,MAAM,CAAC,EAAE,iBAAiB,CAAC,CAAC,CAAC,CAAC,GAAG,MAAM,CAAC,CAAC,EAAE,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;CACxE,CAAC;AACF,KAAK,iBAAiB,CAAC,CAAC,SAAS,QAAQ,IAAI,YAAY,CACxD,QAAQ,CAAC,CAAC,CAAC,EACX,QAAQ,CAAC,CAAC,CAAC,CACX,CAAC;AAsCF,MAAM,MAAM,iBAAiB,GAAG;IAC/B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB;;;;;;;;;OASG;IACH,IAAI,EAAE,CAAC,CAAC,SAAS,QAAQ,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC,KAAK,iBAAiB,CAAC,CAAC,CAAC,CAAC;CAC5E,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,UAAU,GAAI,QAAQ,MAAM,KAAG,iBAsC3C,CAAC;AAIF;;;GAGG;AACH,eAAO,MAAM,mBAAmB,QAAO,aAAa,CAAC;IACpD,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,QAAQ,CAAC;CACjB,CAIG,CAAC;AAEL;;;GAGG;AACH,eAAO,MAAM,sBAAsB,QAAO,IAEzC,CAAC"}

package/dist/bot/callbacks.js

@@ -101,10 +101,13 @@ export const callbackNs = (prefix) => {
                         `with different fields ${JSON.stringify(existing.fields)}; ` +
                         `re-registration tried ${JSON.stringify(fields)}.`);
                 }
+                // fieldsEqual just proved the stored schema IS F's schema.
                 return existing.cb;
             }
             const cb = buildCallbackData(fullName, fields);
             registry.set(fullName, { fullName, fields, cb });
+            // buildCallbackData accumulates exactly F's fields at runtime; the
+            // erased builder type is re-asserted here, once, at the boundary.
             return cb;
         },
     };

package/dist/bot/callbacks.js.map

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

package/dist/bot/index.d.ts

@@ -20,6 +20,7 @@ export * from "./kit.js";
 export * from "./language.js";
 export * from "./llm.js";
 export * from "./menu.js";
+export * from "./notify.js";
 export * from "./payments/index.js";
 export * from "./storage.js";
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/bot/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,cAAc,qBAAqB,CAAC;AACpC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,eAAe,CAAC;AAC9B,cAAc,UAAU,CAAC;AACzB,cAAc,WAAW,CAAC;AAC1B,cAAc,UAAU,CAAC;AACzB,cAAc,eAAe,CAAC;AAC9B,cAAc,UAAU,CAAC;AACzB,cAAc,WAAW,CAAC;AAC1B,cAAc,qBAAqB,CAAC;AACpC,cAAc,cAAc,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/bot/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,cAAc,qBAAqB,CAAC;AACpC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,eAAe,CAAC;AAC9B,cAAc,UAAU,CAAC;AACzB,cAAc,WAAW,CAAC;AAC1B,cAAc,UAAU,CAAC;AACzB,cAAc,eAAe,CAAC;AAC9B,cAAc,UAAU,CAAC;AACzB,cAAc,WAAW,CAAC;AAC1B,cAAc,aAAa,CAAC;AAC5B,cAAc,qBAAqB,CAAC;AACpC,cAAc,cAAc,CAAC"}

package/dist/bot/index.js

@@ -20,6 +20,7 @@ export * from "./kit.js";
 export * from "./language.js";
 export * from "./llm.js";
 export * from "./menu.js";
+export * from "./notify.js";
 export * from "./payments/index.js";
 export * from "./storage.js";
 //# sourceMappingURL=index.js.map

package/dist/bot/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/bot/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,cAAc,qBAAqB,CAAC;AACpC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,eAAe,CAAC;AAC9B,cAAc,UAAU,CAAC;AACzB,cAAc,WAAW,CAAC;AAC1B,cAAc,UAAU,CAAC;AACzB,cAAc,eAAe,CAAC;AAC9B,cAAc,UAAU,CAAC;AACzB,cAAc,WAAW,CAAC;AAC1B,cAAc,qBAAqB,CAAC;AACpC,cAAc,cAAc,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/bot/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,cAAc,qBAAqB,CAAC;AACpC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,eAAe,CAAC;AAC9B,cAAc,UAAU,CAAC;AACzB,cAAc,WAAW,CAAC;AAC1B,cAAc,UAAU,CAAC;AACzB,cAAc,eAAe,CAAC;AAC9B,cAAc,UAAU,CAAC;AACzB,cAAc,WAAW,CAAC;AAC1B,cAAc,aAAa,CAAC;AAC5B,cAAc,qBAAqB,CAAC;AACpC,cAAc,cAAc,CAAC"}

package/dist/bot/kit.d.ts

@@ -1,5 +1,9 @@
 /**
- * Foundational helpers every bot wants.
+ * Foundational helpers for NODE bots — the library's deliberately
+ * Node-only corner (process signals, KEV env resolution). Worker bots
+ * use the worker-safe subpaths instead: `bot/session` (namespaced
+ * sessions) and `bot/notify` (admin DMs) hold the pieces that used to
+ * live here but never needed an OS.
  *
  *   `gracefulStart(bot, opts?)` — wires SIGINT/SIGTERM to bot.stop(),
  *     runs an optional shutdown hook, force-kills if it hangs. DMs the
@@ -12,15 +16,9 @@
  *     every context with `ctx.adminId` (number) and `ctx.isAdmin`
  *     (boolean). Throws at startup if neither source provides an id.
  *
- *   `botSession(opts)` — drop-in replacement for `@gramio/session`'s
- *     `session()` that AUTOMATICALLY namespaces every key with the
- *     calling bot's id (parsed from `ctx.bot.options.token`). When
- *     several bots share one Redis instance, each writes to a disjoint
- *     keyspace (`bot-<id>:<senderId>`) with no manual wiring. Every
- *     plugin in this package (`accessControl`, `botMenu`,
- *     `llmHistory`, …) derives the SAME prefix from `ctx.bot` for its
- *     own storage access, so the whole package stays isolated by
- *     construction. Use this instead of `session()` — full stop.
+ *   `botSession` / `prefixStorage` — re-exported from `bot/session` so
+ *     Node consumers keep one import; the implementation is worker-safe
+ *     and lives there.
  *
  * Peer deps: `gramio`, `@gramio/session`, `@gramio/storage`.
  *
@@ -39,10 +37,9 @@
  *
  * await gracefulStart(bot, { onShutdown: () => db.end() })
  */
-import { type SessionOptions, session } from "@gramio/session";
-import type { Storage } from "@gramio/storage";
 import type { Plugin as PluginType } from "gramio";
 import { type AnyBot } from "gramio";
+export { botSession, prefixStorage } from "./session.js";
 export type GracefulStartOptions = {
     /** Runs after `bot.stop()` resolves, before `process.exit`. Close DBs, flush logs. */
     onShutdown?: () => Promise<void> | void;
@@ -88,52 +85,5 @@ export declare const adminContext: (opts?: AdminContextOptions) => PluginType<{}
         isAdmin: boolean;
     };
 }, {}>;
-/**
- * Drop-in replacement for `@gramio/session`'s `session()` that forces
- * the storage key to include the calling bot's id. Equivalent to
- * passing `getSessionKey: (ctx) => bot-${id}:${senderId}` explicitly,
- * but baked in so no consumer can forget.
- *
- * Returns a plain `@gramio/session` plugin — same shape, same derives,
- * fully interchangeable in `.extend(userSession)` chains and plugin
- * options like `accessControl({ session: userSession, … })`.
- *
- * `getSessionKey` can still be overridden for advanced cases (e.g. a
- * per-chat session in groups); the override is wrapped so it still
- * receives the `bot-<id>:` prefix. Don't override unless you know what
- * you're doing — every plugin in this package expects the
- * `bot-<id>:<userId>` shape for cross-user storage reads.
- *
- * @example
- * import { redisStorage } from '@gramio/storage-redis'
- * import { botSession } from '@adriangalilea/utils/bot/kit'
- *
- * const storage = redisStorage()    // shared across N bots, safe
- *
- * const userSession = botSession({
- *   storage,
- *   key: 'session',
- *   initial: () => ({}),
- * })
- *
- * bot.extend(userSession)
- */
-export declare const botSession: <Data = unknown, Key extends string = "session", Lazy extends boolean = false>(opts: SessionOptions<Data, Key, Lazy>) => ReturnType<typeof session<Data, Key, Lazy>>;
-/**
- * Wraps any `@gramio/storage` adapter so every key gets a fixed
- * `${prefix}` prepended.
- *
- * **You almost never need this.** The library's plugins are isolated
- * by bot id automatically when you wire `botSession` (see above) —
- * `prefixStorage` exists for edge cases:
- *
- *   - Sharing a Redis instance with a NON-bot system, and you want a
- *     top-level prefix on top of the bot-id namespace.
- *   - Migrating from an older deployment that used a custom prefix.
- *
- * In those cases the wrapper composes cleanly with `botSession`'s
- * internal prefix: final keys look like `${prefix}bot-<id>:<userId>`.
- */
-export declare const prefixStorage: (storage: Storage, prefix: string) => Storage;
 export type { PluginType };
 //# sourceMappingURL=kit.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"kit.d.ts","sourceRoot":"","sources":["../../src/bot/kit.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH,OAAO,EAAE,KAAK,cAAc,EAAE,OAAO,EAAE,MAAM,iBAAiB,CAAC;AAC/D,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,iBAAiB,CAAC;AAC/C,OAAO,KAAK,EAAE,MAAM,IAAI,UAAU,EAAE,MAAM,QAAQ,CAAC;AACnD,OAAO,EAAE,KAAK,MAAM,EAAU,MAAM,QAAQ,CAAC;AAM7C,MAAM,MAAM,oBAAoB,GAAG;IAClC,sFAAsF;IACtF,UAAU,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IACxC,yDAAyD;IACzD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,qEAAqE;IACrE,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,6DAA6D;IAC7D,GAAG,CAAC,EAAE,CAAC,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC,GAAG,KAAK,CAAC;IACtC;;;;;;;;;;;;;;;;;;;OAmBG;IACH,WAAW,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC;CAC/B,CAAC;AAEF,eAAO,MAAM,aAAa,GACzB,KAAK,MAAM,EACX,OAAM,oBAAyB,KAC7B,OAAO,CAAC,IAAI,CAiFd,CAAC;AAIF,MAAM,MAAM,mBAAmB,GAAG;IACjC,qEAAqE;IACrE,OAAO,CAAC,EAAE,MAAM,CAAC;CACjB,CAAC;AAEF,eAAO,MAAM,YAAY,GAAI,OAAM,mBAAwB;;;;;;;;MAqB1D,CAAC;AAIF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,eAAO,MAAM,UAAU,GACtB,IAAI,GAAG,OAAO,EACd,GAAG,SAAS,MAAM,GAAG,SAAS,EAC9B,IAAI,SAAS,OAAO,GAAG,KAAK,EAE5B,MAAM,cAAc,CAAC,IAAI,EAAE,GAAG,EAAE,IAAI,CAAC,KACnC,UAAU,CAAC,OAAO,OAAO,CAAC,IAAI,EAAE,GAAG,EAAE,IAAI,CAAC,CA0B5C,CAAC;AAIF;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,aAAa,GAAI,SAAS,OAAO,EAAE,QAAQ,MAAM,KAAG,OAShE,CAAC;AAIF,YAAY,EAAE,UAAU,EAAE,CAAC"}
+{"version":3,"file":"kit.d.ts","sourceRoot":"","sources":["../../src/bot/kit.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,OAAO,KAAK,EAAE,MAAM,IAAI,UAAU,EAAE,MAAM,QAAQ,CAAC;AACnD,OAAO,EAAE,KAAK,MAAM,EAAU,MAAM,QAAQ,CAAC;AAI7C,OAAO,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAIzD,MAAM,MAAM,oBAAoB,GAAG;IAClC,sFAAsF;IACtF,UAAU,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IACxC,yDAAyD;IACzD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,qEAAqE;IACrE,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,6DAA6D;IAC7D,GAAG,CAAC,EAAE,CAAC,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC,GAAG,KAAK,CAAC;IACtC;;;;;;;;;;;;;;;;;;;OAmBG;IACH,WAAW,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC;CAC/B,CAAC;AAEF,eAAO,MAAM,aAAa,GACzB,KAAK,MAAM,EACX,OAAM,oBAAyB,KAC7B,OAAO,CAAC,IAAI,CAmEd,CAAC;AAIF,MAAM,MAAM,mBAAmB,GAAG;IACjC,qEAAqE;IACrE,OAAO,CAAC,EAAE,MAAM,CAAC;CACjB,CAAC;AAEF,eAAO,MAAM,YAAY,GAAI,OAAM,mBAAwB;;;;;;;;MAqB1D,CAAC;AAIF,YAAY,EAAE,UAAU,EAAE,CAAC"}

package/dist/bot/kit.js

@@ -1,48 +1,7 @@
-/**
- * Foundational helpers every bot wants.
- *
- *   `gracefulStart(bot, opts?)` — wires SIGINT/SIGTERM to bot.stop(),
- *     runs an optional shutdown hook, force-kills if it hangs. DMs the
- *     admin on start/stop by default (`@<bot> started.` /
- *     `@<bot> shutting down.`) when `KEV.TELEGRAM_ADMIN_ID` is set —
- *     pass `notifyAdmin: false` to disable.
- *
- *   `adminContext({ adminId? })` — reads admin Telegram id from KEV
- *     (`TELEGRAM_ADMIN_ID`) with optional hardcoded fallback. Decorates
- *     every context with `ctx.adminId` (number) and `ctx.isAdmin`
- *     (boolean). Throws at startup if neither source provides an id.
- *
- *   `botSession(opts)` — drop-in replacement for `@gramio/session`'s
- *     `session()` that AUTOMATICALLY namespaces every key with the
- *     calling bot's id (parsed from `ctx.bot.options.token`). When
- *     several bots share one Redis instance, each writes to a disjoint
- *     keyspace (`bot-<id>:<senderId>`) with no manual wiring. Every
- *     plugin in this package (`accessControl`, `botMenu`,
- *     `llmHistory`, …) derives the SAME prefix from `ctx.bot` for its
- *     own storage access, so the whole package stays isolated by
- *     construction. Use this instead of `session()` — full stop.
- *
- * Peer deps: `gramio`, `@gramio/session`, `@gramio/storage`.
- *
- * @example
- * import { Bot } from 'gramio'
- * import { redisStorage } from '@gramio/storage-redis'
- * import { adminContext, gracefulStart, botSession } from '@adriangalilea/utils/bot/kit'
- *
- * const storage = redisStorage()                          // share across bots, safe
- * const userSession = botSession({ storage, initial: () => ({}) })
- *
- * const bot = new Bot(process.env.BOT_TOKEN!)
- *   .extend(adminContext({ adminId: 190202471 }))         // KEV wins, 190… is fallback
- *   .extend(userSession)
- *   .command('whoami', (ctx) => ctx.send(`admin? ${ctx.isAdmin}`))
- *
- * await gracefulStart(bot, { onShutdown: () => db.end() })
- */
-import { session } from "@gramio/session";
 import { Plugin } from "gramio";
 import { kev } from "../platform/kev.js";
-import { botId } from "./keys.js";
+import { notifyAdmins } from "./notify.js";
+export { botSession, prefixStorage } from "./session.js";
 export const gracefulStart = async (bot, opts = {}) => {
     const log = opts.log === false ? () => { } : (opts.log ?? ((m) => console.log(m)));
     const forceMs = opts.forceExitAfterMs ?? 10_000;
@@ -93,28 +52,8 @@ export const gracefulStart = async (bot, opts = {}) => {
             "Pass a number explicitly, set the env var, or remove notifyAdmin.");
     }
     if (adminId) {
-        bot.onStart(async ({ info }) => {
-            try {
-                await bot.api.sendMessage({
-                    chat_id: adminId,
-                    text: `@${info.username} started.`,
-                });
-            }
-            catch (e) {
-                console.error("[bot] notifyAdmin (start) failed", e);
-            }
-        });
-        bot.onStop(async ({ info }) => {
-            try {
-                await bot.api.sendMessage({
-                    chat_id: adminId,
-                    text: `@${info.username} shutting down.`,
-                });
-            }
-            catch (e) {
-                console.error("[bot] notifyAdmin (stop) failed", e);
-            }
-        });
+        bot.onStart(({ info }) => notifyAdmins(bot, [adminId], `@${info.username} started.`));
+        bot.onStop(({ info }) => notifyAdmins(bot, [adminId], `@${info.username} shutting down.`));
     }
     await bot.start();
 };
@@ -136,81 +75,4 @@ export const adminContext = (opts = {}) => {
         isAdmin: "senderId" in ctx && ctx.senderId === adminId,
     }));
 };
-// ─── botSession ────────────────────────────────────────────────────
-/**
- * Drop-in replacement for `@gramio/session`'s `session()` that forces
- * the storage key to include the calling bot's id. Equivalent to
- * passing `getSessionKey: (ctx) => bot-${id}:${senderId}` explicitly,
- * but baked in so no consumer can forget.
- *
- * Returns a plain `@gramio/session` plugin — same shape, same derives,
- * fully interchangeable in `.extend(userSession)` chains and plugin
- * options like `accessControl({ session: userSession, … })`.
- *
- * `getSessionKey` can still be overridden for advanced cases (e.g. a
- * per-chat session in groups); the override is wrapped so it still
- * receives the `bot-<id>:` prefix. Don't override unless you know what
- * you're doing — every plugin in this package expects the
- * `bot-<id>:<userId>` shape for cross-user storage reads.
- *
- * @example
- * import { redisStorage } from '@gramio/storage-redis'
- * import { botSession } from '@adriangalilea/utils/bot/kit'
- *
- * const storage = redisStorage()    // shared across N bots, safe
- *
- * const userSession = botSession({
- *   storage,
- *   key: 'session',
- *   initial: () => ({}),
- * })
- *
- * bot.extend(userSession)
- */
-export const botSession = (opts) => {
-    const userKeyer = opts.getSessionKey;
-    return session({
-        ...opts,
-        // The session plugin types `getSessionKey` against `ContextType<BotLike, Events>`
-        // — too narrow for our generic wrapper. We only need `bot.info.id` +
-        // `senderId`, both of which gramio guarantees on every event the session
-        // plugin processes (bot.info is populated by bot.start / bot.init before
-        // any handler fires). Structural cast at the boundary keeps the public
-        // API generic-friendly without forcing consumers to specify Event unions.
-        getSessionKey: (async (ctxRaw) => {
-            const ctx = ctxRaw;
-            const prefix = `bot-${botId(ctx)}:`;
-            if (userKeyer) {
-                const inner = await userKeyer(ctx);
-                return `${prefix}${inner}`;
-            }
-            return `${prefix}${ctx.senderId ?? ""}`;
-        }),
-    });
-};
-// ─── prefixStorage (escape hatch) ──────────────────────────────────
-/**
- * Wraps any `@gramio/storage` adapter so every key gets a fixed
- * `${prefix}` prepended.
- *
- * **You almost never need this.** The library's plugins are isolated
- * by bot id automatically when you wire `botSession` (see above) —
- * `prefixStorage` exists for edge cases:
- *
- *   - Sharing a Redis instance with a NON-bot system, and you want a
- *     top-level prefix on top of the bot-id namespace.
- *   - Migrating from an older deployment that used a custom prefix.
- *
- * In those cases the wrapper composes cleanly with `botSession`'s
- * internal prefix: final keys look like `${prefix}bot-<id>:<userId>`.
- */
-export const prefixStorage = (storage, prefix) => {
-    const k = (key) => `${prefix}${String(key)}`;
-    return {
-        get: (key) => storage.get(k(key)),
-        has: (key) => storage.has(k(key)),
-        set: (key, value) => storage.set(k(key), value),
-        delete: (key) => storage.delete(k(key)),
-    };
-};
 //# sourceMappingURL=kit.js.map

package/dist/bot/kit.js.map

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

package/dist/bot/notify.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Admin notifications — best-effort DMs to the bot's operator(s).
+ * Worker-safe: no env, no process; the caller passes the admin ids
+ * (from wherever its runtime keeps them: KEV on Node, D1/env on a
+ * Worker).
+ *
+ * Everything here is FIRE-AND-FORGET BY CONTRACT: a notification must
+ * never take the bot down, so failures are logged (console.error —
+ * visible in a Worker tail and a Node terminal alike) and swallowed.
+ *
+ *   `notifyAdmins(bot, adminIds, text, extra?)` — DM each admin.
+ *   `alertAdminError(bot, adminIds, label, error, throttle?)` — DM a
+ *     truncated `🚨 label\nName: message`, rate-limited through a
+ *     caller-owned throttle so a failure storm can't flood anyone.
+ *   `alertThrottle(ms?)` — make that throttle (per-process on Node,
+ *     per-isolate on a Worker; own one per subsystem if you want
+ *     independent budgets).
+ *
+ * @example
+ * import { alertAdminError, alertThrottle, notifyAdmins } from '@adriangalilea/utils/bot/notify'
+ *
+ * const errorAlerts = alertThrottle()          // 60s budget, module-level
+ * bot.onError(({ kind, error }) => void alertAdminError(bot, adminIds, `error [${kind}]`, error, errorAlerts))
+ * await notifyAdmins(bot, adminIds, `@${bot.info.username} deployed.`)
+ */
+/** The one API surface a notification needs — satisfied by any gramio `Bot`. */
+export type NotifyBot = {
+    api: {
+        sendMessage: (params: {
+            chat_id: number;
+            text: string;
+        }) => Promise<unknown>;
+    };
+};
+/**
+ * DM `text` to every admin id, best-effort: each failure is logged and
+ * swallowed (one unreachable admin must not block the rest, and a
+ * notification must never throw into the calling flow). `extra` merges
+ * into the sendMessage params (reply_markup, link_preview_options, …).
+ */
+export declare function notifyAdmins(bot: NotifyBot, adminIds: readonly number[], text: string, extra?: Record<string, unknown>): Promise<void>;
+/**
+ * Rate-limit state for {@link alertAdminError}, owned by the CALLER so
+ * scope is explicit (per-process on Node, per-isolate on a Worker) and
+ * independent subsystems can hold independent budgets.
+ */
+export type AlertThrottle = {
+    ms: number;
+    lastAt: number;
+};
+/** A fresh throttle: at most one alert per `ms` (default 60s). */
+export declare const alertThrottle: (ms?: number) => AlertThrottle;
+/**
+ * DM the admins a truncated error (`🚨 label\nName: message`), gated by
+ * `throttle` so a failure storm sends one alert per window, not one per
+ * failure. No throttle = every call sends.
+ */
+export declare function alertAdminError(bot: NotifyBot, adminIds: readonly number[], label: string, error: unknown, throttle?: AlertThrottle): Promise<void>;
+//# sourceMappingURL=notify.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"notify.d.ts","sourceRoot":"","sources":["../../src/bot/notify.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,gFAAgF;AAChF,MAAM,MAAM,SAAS,GAAG;IACvB,GAAG,EAAE;QACJ,WAAW,EAAE,CAAC,MAAM,EAAE;YACrB,OAAO,EAAE,MAAM,CAAC;YAChB,IAAI,EAAE,MAAM,CAAC;SACb,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;KACvB,CAAC;CACF,CAAC;AAKF;;;;;GAKG;AACH,wBAAsB,YAAY,CACjC,GAAG,EAAE,SAAS,EACd,QAAQ,EAAE,SAAS,MAAM,EAAE,EAC3B,IAAI,EAAE,MAAM,EACZ,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC7B,OAAO,CAAC,IAAI,CAAC,CAWf;AAED;;;;GAIG;AACH,MAAM,MAAM,aAAa,GAAG;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAE3D,kEAAkE;AAClE,eAAO,MAAM,aAAa,GAAI,WAAW,KAAG,aAG1C,CAAC;AAEH;;;;GAIG;AACH,wBAAsB,eAAe,CACpC,GAAG,EAAE,SAAS,EACd,QAAQ,EAAE,SAAS,MAAM,EAAE,EAC3B,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,OAAO,EACd,QAAQ,CAAC,EAAE,aAAa,GACtB,OAAO,CAAC,IAAI,CAAC,CASf"}

package/dist/bot/notify.js

@@ -0,0 +1,62 @@
+/**
+ * Admin notifications — best-effort DMs to the bot's operator(s).
+ * Worker-safe: no env, no process; the caller passes the admin ids
+ * (from wherever its runtime keeps them: KEV on Node, D1/env on a
+ * Worker).
+ *
+ * Everything here is FIRE-AND-FORGET BY CONTRACT: a notification must
+ * never take the bot down, so failures are logged (console.error —
+ * visible in a Worker tail and a Node terminal alike) and swallowed.
+ *
+ *   `notifyAdmins(bot, adminIds, text, extra?)` — DM each admin.
+ *   `alertAdminError(bot, adminIds, label, error, throttle?)` — DM a
+ *     truncated `🚨 label\nName: message`, rate-limited through a
+ *     caller-owned throttle so a failure storm can't flood anyone.
+ *   `alertThrottle(ms?)` — make that throttle (per-process on Node,
+ *     per-isolate on a Worker; own one per subsystem if you want
+ *     independent budgets).
+ *
+ * @example
+ * import { alertAdminError, alertThrottle, notifyAdmins } from '@adriangalilea/utils/bot/notify'
+ *
+ * const errorAlerts = alertThrottle()          // 60s budget, module-level
+ * bot.onError(({ kind, error }) => void alertAdminError(bot, adminIds, `error [${kind}]`, error, errorAlerts))
+ * await notifyAdmins(bot, adminIds, `@${bot.info.username} deployed.`)
+ */
+/** Telegram's hard per-message limit; longer texts are truncated, never split. */
+const MAX_CHARS = 4096;
+/**
+ * DM `text` to every admin id, best-effort: each failure is logged and
+ * swallowed (one unreachable admin must not block the rest, and a
+ * notification must never throw into the calling flow). `extra` merges
+ * into the sendMessage params (reply_markup, link_preview_options, …).
+ */
+export async function notifyAdmins(bot, adminIds, text, extra) {
+    const body = text.slice(0, MAX_CHARS);
+    await Promise.all(adminIds
+        .filter((id) => id > 0)
+        .map((id) => bot.api
+        .sendMessage({ ...extra, chat_id: id, text: body })
+        .catch((e) => console.error(`[bot/notify] admin ${id} failed:`, e))));
+}
+/** A fresh throttle: at most one alert per `ms` (default 60s). */
+export const alertThrottle = (ms = 60_000) => ({
+    ms,
+    lastAt: 0,
+});
+/**
+ * DM the admins a truncated error (`🚨 label\nName: message`), gated by
+ * `throttle` so a failure storm sends one alert per window, not one per
+ * failure. No throttle = every call sends.
+ */
+export async function alertAdminError(bot, adminIds, label, error, throttle) {
+    if (throttle) {
+        const now = Date.now();
+        if (now - throttle.lastAt < throttle.ms)
+            return;
+        throttle.lastAt = now;
+    }
+    const message = error instanceof Error ? `${error.name}: ${error.message}` : String(error);
+    await notifyAdmins(bot, adminIds, `🚨 ${label}\n${message}`);
+}
+//# sourceMappingURL=notify.js.map

package/dist/bot/notify.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"notify.js","sourceRoot":"","sources":["../../src/bot/notify.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAYH,kFAAkF;AAClF,MAAM,SAAS,GAAG,IAAI,CAAC;AAEvB;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CACjC,GAAc,EACd,QAA2B,EAC3B,IAAY,EACZ,KAA+B;IAE/B,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,SAAS,CAAC,CAAC;IACtC,MAAM,OAAO,CAAC,GAAG,CAChB,QAAQ;SACN,MAAM,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,GAAG,CAAC,CAAC;SACtB,GAAG,CAAC,CAAC,EAAE,EAAE,EAAE,CACX,GAAG,CAAC,GAAG;SACL,WAAW,CAAC,EAAE,GAAG,KAAK,EAAE,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;SAClD,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC,sBAAsB,EAAE,UAAU,EAAE,CAAC,CAAC,CAAC,CACpE,CACF,CAAC;AACH,CAAC;AASD,kEAAkE;AAClE,MAAM,CAAC,MAAM,aAAa,GAAG,CAAC,EAAE,GAAG,MAAM,EAAiB,EAAE,CAAC,CAAC;IAC7D,EAAE;IACF,MAAM,EAAE,CAAC;CACT,CAAC,CAAC;AAEH;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CACpC,GAAc,EACd,QAA2B,EAC3B,KAAa,EACb,KAAc,EACd,QAAwB;IAExB,IAAI,QAAQ,EAAE,CAAC;QACd,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QACvB,IAAI,GAAG,GAAG,QAAQ,CAAC,MAAM,GAAG,QAAQ,CAAC,EAAE;YAAE,OAAO;QAChD,QAAQ,CAAC,MAAM,GAAG,GAAG,CAAC;IACvB,CAAC;IACD,MAAM,OAAO,GACZ,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,KAAK,CAAC,IAAI,KAAK,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IAC5E,MAAM,YAAY,CAAC,GAAG,EAAE,QAAQ,EAAE,MAAM,KAAK,KAAK,OAAO,EAAE,CAAC,CAAC;AAC9D,CAAC"}

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

@@ -29,13 +29,25 @@ import type { BotCallbackCtx } from "../ctx.js";
 import type { PaymentsStores } from "./stores.js";
 import type { BotPaymentsConfig, PaymentsSession } from "./types.js";
 /** User tap on a charge entry — opens confirmation overlay then admin DM. */
-export declare const refundRequestCb: import("gramio").CallbackData<Record<never, never>, Record<never, never>>;
+export declare const refundRequestCb: import("gramio").CallbackData<{
+    cid: string;
+} & {}, {
+    cid: string;
+} & {}>;
 /** Admin tap on the DM notification — approve. */
-export declare const refundApproveCb: import("gramio").CallbackData<Record<never, never>, Record<never, never>>;
+export declare const refundApproveCb: import("gramio").CallbackData<{
+    cid: string;
+} & {}, {
+    cid: string;
+} & {}>;
 /** Admin tap on the DM notification — deny. */
-export declare const refundDenyCb: import("gramio").CallbackData<Record<never, never>, Record<never, never>>;
+export declare const refundDenyCb: import("gramio").CallbackData<{
+    cid: string;
+} & {}, {
+    cid: string;
+} & {}>;
 /** Admin tap on the DM notification — close (no action). */
-export declare const refundCloseCb: import("gramio").CallbackData<Record<never, never>, Record<never, never>>;
+export declare const refundCloseCb: import("gramio").CallbackData<{} & {}, {} & {}>;
 /** Strict bot.api surface this module exercises. */
 type RefundBotApi = {
     refundStarPayment: (params: {

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

@@ -1 +1 @@
-{"version":3,"file":"refund.d.ts","sourceRoot":"","sources":["../../../src/bot/payments/refund.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,iBAAiB,CAAC;AAM/C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAGhD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAClD,OAAO,KAAK,EACX,iBAAiB,EAEjB,eAAe,EACf,MAAM,YAAY,CAAC;AASpB,6EAA6E;AAC7E,eAAO,MAAM,eAAe,2EAA+C,CAAC;AAC5E,kDAAkD;AAClD,eAAO,MAAM,eAAe,2EAA+C,CAAC;AAC5E,+CAA+C;AAC/C,eAAO,MAAM,YAAY,2EAA4C,CAAC;AACtE,4DAA4D;AAC5D,eAAO,MAAM,aAAa,2EAA8B,CAAC;AAIzD,oDAAoD;AACpD,KAAK,YAAY,GAAG;IACnB,iBAAiB,EAAE,CAAC,MAAM,EAAE;QAC3B,OAAO,EAAE,MAAM,CAAC;QAChB,0BAA0B,EAAE,MAAM,CAAC;KACnC,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IACvB,wBAAwB,EAAE,CAAC,MAAM,EAAE;QAClC,OAAO,EAAE,MAAM,CAAC;QAChB,0BAA0B,EAAE,MAAM,CAAC;QACnC,WAAW,EAAE,OAAO,CAAC;KACrB,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IACvB,WAAW,EAAE,CAAC,MAAM,EAAE;QACrB,OAAO,EAAE,MAAM,CAAC;QAChB,iBAAiB,CAAC,EAAE,MAAM,CAAC;QAC3B,IAAI,EAAE,MAAM,CAAC;QACb,YAAY,CAAC,EAAE,OAAO,CAAC;KACvB,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;CACvB,CAAC;AAEF,KAAK,WAAW,GAAG;IAAE,GAAG,CAAC,EAAE,eAAe,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAEhE;;;;;GAKG;AACH,KAAK,SAAS,GAAG,cAAc,CAAC,WAAW,EAAE;IAAE,GAAG,EAAE,MAAM,CAAA;CAAE,EAAE,YAAY,CAAC,GAAG;IAC7E,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,OAAO,CAAC;CACjB,CAAC;AAqIF,MAAM,MAAM,qBAAqB,GAAG;IACnC,MAAM,EAAE,cAAc,CAAC;IACvB;;;;;OAKG;IACH,OAAO,EAAE,OAAO,CAAC;IACjB,GAAG,EAAE,iBAAiB,CAAC,MAAM,CAAC,CAAC;CAC/B,CAAC;AAEF;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,yBAAyB,GACpC,MAAM,qBAAqB,MAE3B,KAAK,SAAS,GAAG;IAAE,SAAS,EAAE;QAAE,GAAG,EAAE,MAAM,CAAA;KAAE,CAAA;CAAE,KAC7C,OAAO,CAAC,MAAM,GAAG,SAAS,CA8D5B,CAAC;AAEH;;;;;GAKG;AACH,eAAO,MAAM,yBAAyB,GACpC,MAAM,qBAAqB,MACrB,KAAK,SAAS,GAAG;IAAE,SAAS,EAAE;QAAE,GAAG,EAAE,MAAM,CAAA;KAAE,CAAA;CAAE,KAAG,OAAO,CAAC,IAAI,CAiGpE,CAAC;AAEH;;;;GAIG;AACH,eAAO,MAAM,sBAAsB,GACjC,MAAM,qBAAqB,MACrB,KAAK,SAAS,GAAG;IAAE,SAAS,EAAE;QAAE,GAAG,EAAE,MAAM,CAAA;KAAE,CAAA;CAAE,KAAG,OAAO,CAAC,IAAI,CAyCpE,CAAC"}
+{"version":3,"file":"refund.d.ts","sourceRoot":"","sources":["../../../src/bot/payments/refund.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,iBAAiB,CAAC;AAM/C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAGhD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAClD,OAAO,KAAK,EACX,iBAAiB,EAEjB,eAAe,EACf,MAAM,YAAY,CAAC;AASpB,6EAA6E;AAC7E,eAAO,MAAM,eAAe;;;;OAA+C,CAAC;AAC5E,kDAAkD;AAClD,eAAO,MAAM,eAAe;;;;OAA+C,CAAC;AAC5E,+CAA+C;AAC/C,eAAO,MAAM,YAAY;;;;OAA4C,CAAC;AACtE,4DAA4D;AAC5D,eAAO,MAAM,aAAa,iDAA8B,CAAC;AAIzD,oDAAoD;AACpD,KAAK,YAAY,GAAG;IACnB,iBAAiB,EAAE,CAAC,MAAM,EAAE;QAC3B,OAAO,EAAE,MAAM,CAAC;QAChB,0BAA0B,EAAE,MAAM,CAAC;KACnC,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IACvB,wBAAwB,EAAE,CAAC,MAAM,EAAE;QAClC,OAAO,EAAE,MAAM,CAAC;QAChB,0BAA0B,EAAE,MAAM,CAAC;QACnC,WAAW,EAAE,OAAO,CAAC;KACrB,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IACvB,WAAW,EAAE,CAAC,MAAM,EAAE;QACrB,OAAO,EAAE,MAAM,CAAC;QAChB,iBAAiB,CAAC,EAAE,MAAM,CAAC;QAC3B,IAAI,EAAE,MAAM,CAAC;QACb,YAAY,CAAC,EAAE,OAAO,CAAC;KACvB,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;CACvB,CAAC;AAEF,KAAK,WAAW,GAAG;IAAE,GAAG,CAAC,EAAE,eAAe,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAEhE;;;;;GAKG;AACH,KAAK,SAAS,GAAG,cAAc,CAAC,WAAW,EAAE;IAAE,GAAG,EAAE,MAAM,CAAA;CAAE,EAAE,YAAY,CAAC,GAAG;IAC7E,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,OAAO,CAAC;CACjB,CAAC;AAqIF,MAAM,MAAM,qBAAqB,GAAG;IACnC,MAAM,EAAE,cAAc,CAAC;IACvB;;;;;OAKG;IACH,OAAO,EAAE,OAAO,CAAC;IACjB,GAAG,EAAE,iBAAiB,CAAC,MAAM,CAAC,CAAC;CAC/B,CAAC;AAEF;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,yBAAyB,GACpC,MAAM,qBAAqB,MAE3B,KAAK,SAAS,GAAG;IAAE,SAAS,EAAE;QAAE,GAAG,EAAE,MAAM,CAAA;KAAE,CAAA;CAAE,KAC7C,OAAO,CAAC,MAAM,GAAG,SAAS,CA8D5B,CAAC;AAEH;;;;;GAKG;AACH,eAAO,MAAM,yBAAyB,GACpC,MAAM,qBAAqB,MACrB,KAAK,SAAS,GAAG;IAAE,SAAS,EAAE;QAAE,GAAG,EAAE,MAAM,CAAA;KAAE,CAAA;CAAE,KAAG,OAAO,CAAC,IAAI,CAiGpE,CAAC;AAEH;;;;GAIG;AACH,eAAO,MAAM,sBAAsB,GACjC,MAAM,qBAAqB,MACrB,KAAK,SAAS,GAAG;IAAE,SAAS,EAAE;QAAE,GAAG,EAAE,MAAM,CAAA;KAAE,CAAA;CAAE,KAAG,OAAO,CAAC,IAAI,CAyCpE,CAAC"}

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

@@ -29,9 +29,13 @@ import { type BotPaymentsConfig, type PaymentsSession, type WaiverRecord } from
  * `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>>;
+export declare const waiverConsentCb: import("gramio").CallbackData<{
+    pk: string;
+} & {}, {
+    pk: string;
+} & {}>;
 /** Fired when the user taps "❌ Cancelar" in the consent prompt. */
-export declare const waiverCancelCb: import("gramio").CallbackData<Record<never, never>, Record<never, never>>;
+export declare const waiverCancelCb: import("gramio").CallbackData<{} & {}, {} & {}>;
 /**
  * Returns true when the stored consent matches the current waiver
  * version — i.e. no re-consent needed before a purchase.

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

@@ -1 +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,EAGtB,KAAK,eAAe,EACpB,KAAK,YAAY,EACjB,MAAM,YAAY,CAAC;AAMpB;;;;;;;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"}
+{"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,EAGtB,KAAK,eAAe,EACpB,KAAK,YAAY,EACjB,MAAM,YAAY,CAAC;AAMpB;;;;;;;GAOG;AACH,eAAO,MAAM,eAAe;;;;OAA8C,CAAC;AAE3E,mEAAmE;AACnE,eAAO,MAAM,cAAc,iDAA+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/session.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Bot-namespaced session storage — worker-safe (no env, no process, no
+ * signals; runs identically on Node and Cloudflare Workers).
+ *
+ *   `botSession(opts)` — drop-in replacement for `@gramio/session`'s
+ *     `session()` that AUTOMATICALLY namespaces every key with the
+ *     calling bot's id (parsed from `ctx.bot.options.token`). When
+ *     several bots share one storage instance, each writes to a
+ *     disjoint keyspace (`bot-<id>:<senderId>`) with no manual wiring.
+ *     Every plugin in this package (`accessControl`, `botMenu`,
+ *     `llmHistory`, …) derives the SAME prefix from `ctx.bot` for its
+ *     own storage access, so the whole package stays isolated by
+ *     construction. Use this instead of `session()` — full stop.
+ *
+ *   `prefixStorage(storage, prefix)` — escape hatch that prepends a
+ *     fixed prefix to every key of any `@gramio/storage` adapter.
+ *
+ * Peer deps: `gramio`, `@gramio/session`, `@gramio/storage`.
+ *
+ * @example
+ * import { redisStorage } from '@gramio/storage-redis'
+ * import { botSession } from '@adriangalilea/utils/bot/session'
+ *
+ * const storage = redisStorage()                          // share across bots, safe
+ * const userSession = botSession({ storage, initial: () => ({}) })
+ * bot.extend(userSession)
+ */
+import { type SessionOptions, session } from "@gramio/session";
+import type { Storage } from "@gramio/storage";
+/**
+ * Drop-in replacement for `@gramio/session`'s `session()` that forces
+ * the storage key to include the calling bot's id. Equivalent to
+ * passing `getSessionKey: (ctx) => bot-${id}:${senderId}` explicitly,
+ * but baked in so no consumer can forget.
+ *
+ * Returns a plain `@gramio/session` plugin — same shape, same derives,
+ * fully interchangeable in `.extend(userSession)` chains and plugin
+ * options like `accessControl({ session: userSession, … })`.
+ *
+ * `getSessionKey` can still be overridden for advanced cases (e.g. a
+ * per-chat session in groups); the override is wrapped so it still
+ * receives the `bot-<id>:` prefix. Don't override unless you know what
+ * you're doing — every plugin in this package expects the
+ * `bot-<id>:<userId>` shape for cross-user storage reads.
+ */
+export declare const botSession: <Data = unknown, Key extends string = "session", Lazy extends boolean = false>(opts: SessionOptions<Data, Key, Lazy>) => ReturnType<typeof session<Data, Key, Lazy>>;
+/**
+ * Wraps any `@gramio/storage` adapter so every key gets a fixed
+ * `${prefix}` prepended.
+ *
+ * **You almost never need this.** The library's plugins are isolated
+ * by bot id automatically when you wire `botSession` (see above) —
+ * `prefixStorage` exists for edge cases:
+ *
+ *   - Sharing a Redis instance with a NON-bot system, and you want a
+ *     top-level prefix on top of the bot-id namespace.
+ *   - Migrating from an older deployment that used a custom prefix.
+ *
+ * In those cases the wrapper composes cleanly with `botSession`'s
+ * internal prefix: final keys look like `${prefix}bot-<id>:<userId>`.
+ */
+export declare const prefixStorage: (storage: Storage, prefix: string) => Storage;
+//# sourceMappingURL=session.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../../src/bot/session.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,OAAO,EAAE,KAAK,cAAc,EAAE,OAAO,EAAE,MAAM,iBAAiB,CAAC;AAC/D,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,iBAAiB,CAAC;AAK/C;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,UAAU,GACtB,IAAI,GAAG,OAAO,EACd,GAAG,SAAS,MAAM,GAAG,SAAS,EAC9B,IAAI,SAAS,OAAO,GAAG,KAAK,EAE5B,MAAM,cAAc,CAAC,IAAI,EAAE,GAAG,EAAE,IAAI,CAAC,KACnC,UAAU,CAAC,OAAO,OAAO,CAAC,IAAI,EAAE,GAAG,EAAE,IAAI,CAAC,CA0B5C,CAAC;AAIF;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,aAAa,GAAI,SAAS,OAAO,EAAE,QAAQ,MAAM,KAAG,OAShE,CAAC"}

package/dist/bot/session.js

@@ -0,0 +1,93 @@
+/**
+ * Bot-namespaced session storage — worker-safe (no env, no process, no
+ * signals; runs identically on Node and Cloudflare Workers).
+ *
+ *   `botSession(opts)` — drop-in replacement for `@gramio/session`'s
+ *     `session()` that AUTOMATICALLY namespaces every key with the
+ *     calling bot's id (parsed from `ctx.bot.options.token`). When
+ *     several bots share one storage instance, each writes to a
+ *     disjoint keyspace (`bot-<id>:<senderId>`) with no manual wiring.
+ *     Every plugin in this package (`accessControl`, `botMenu`,
+ *     `llmHistory`, …) derives the SAME prefix from `ctx.bot` for its
+ *     own storage access, so the whole package stays isolated by
+ *     construction. Use this instead of `session()` — full stop.
+ *
+ *   `prefixStorage(storage, prefix)` — escape hatch that prepends a
+ *     fixed prefix to every key of any `@gramio/storage` adapter.
+ *
+ * Peer deps: `gramio`, `@gramio/session`, `@gramio/storage`.
+ *
+ * @example
+ * import { redisStorage } from '@gramio/storage-redis'
+ * import { botSession } from '@adriangalilea/utils/bot/session'
+ *
+ * const storage = redisStorage()                          // share across bots, safe
+ * const userSession = botSession({ storage, initial: () => ({}) })
+ * bot.extend(userSession)
+ */
+import { session } from "@gramio/session";
+import { botId } from "./keys.js";
+// ─── botSession ────────────────────────────────────────────────────
+/**
+ * Drop-in replacement for `@gramio/session`'s `session()` that forces
+ * the storage key to include the calling bot's id. Equivalent to
+ * passing `getSessionKey: (ctx) => bot-${id}:${senderId}` explicitly,
+ * but baked in so no consumer can forget.
+ *
+ * Returns a plain `@gramio/session` plugin — same shape, same derives,
+ * fully interchangeable in `.extend(userSession)` chains and plugin
+ * options like `accessControl({ session: userSession, … })`.
+ *
+ * `getSessionKey` can still be overridden for advanced cases (e.g. a
+ * per-chat session in groups); the override is wrapped so it still
+ * receives the `bot-<id>:` prefix. Don't override unless you know what
+ * you're doing — every plugin in this package expects the
+ * `bot-<id>:<userId>` shape for cross-user storage reads.
+ */
+export const botSession = (opts) => {
+    const userKeyer = opts.getSessionKey;
+    return session({
+        ...opts,
+        // The session plugin types `getSessionKey` against `ContextType<BotLike, Events>`
+        // — too narrow for our generic wrapper. We only need `bot.info.id` +
+        // `senderId`, both of which gramio guarantees on every event the session
+        // plugin processes (bot.info is populated by bot.start / bot.init before
+        // any handler fires). Structural cast at the boundary keeps the public
+        // API generic-friendly without forcing consumers to specify Event unions.
+        getSessionKey: (async (ctxRaw) => {
+            const ctx = ctxRaw;
+            const prefix = `bot-${botId(ctx)}:`;
+            if (userKeyer) {
+                const inner = await userKeyer(ctx);
+                return `${prefix}${inner}`;
+            }
+            return `${prefix}${ctx.senderId ?? ""}`;
+        }),
+    });
+};
+// ─── prefixStorage (escape hatch) ──────────────────────────────────
+/**
+ * Wraps any `@gramio/storage` adapter so every key gets a fixed
+ * `${prefix}` prepended.
+ *
+ * **You almost never need this.** The library's plugins are isolated
+ * by bot id automatically when you wire `botSession` (see above) —
+ * `prefixStorage` exists for edge cases:
+ *
+ *   - Sharing a Redis instance with a NON-bot system, and you want a
+ *     top-level prefix on top of the bot-id namespace.
+ *   - Migrating from an older deployment that used a custom prefix.
+ *
+ * In those cases the wrapper composes cleanly with `botSession`'s
+ * internal prefix: final keys look like `${prefix}bot-<id>:<userId>`.
+ */
+export const prefixStorage = (storage, prefix) => {
+    const k = (key) => `${prefix}${String(key)}`;
+    return {
+        get: (key) => storage.get(k(key)),
+        has: (key) => storage.has(k(key)),
+        set: (key, value) => storage.set(k(key), value),
+        delete: (key) => storage.delete(k(key)),
+    };
+};
+//# sourceMappingURL=session.js.map

package/dist/bot/session.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.js","sourceRoot":"","sources":["../../src/bot/session.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,OAAO,EAAuB,OAAO,EAAE,MAAM,iBAAiB,CAAC;AAE/D,OAAO,EAAE,KAAK,EAAE,MAAM,WAAW,CAAC;AAElC,sEAAsE;AAEtE;;;;;;;;;;;;;;;GAeG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG,CAKzB,IAAqC,EACS,EAAE;IAChD,MAAM,SAAS,GAAG,IAAI,CAAC,aAAa,CAAC;IAKrC,OAAO,OAAO,CAAkB;QAC/B,GAAG,IAAI;QACP,kFAAkF;QAClF,qEAAqE;QACrE,yEAAyE;QACzE,yEAAyE;QACzE,uEAAuE;QACvE,0EAA0E;QAC1E,aAAa,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE;YAChC,MAAM,GAAG,GAAG,MAAgB,CAAC;YAC7B,MAAM,MAAM,GAAG,OAAO,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC;YACpC,IAAI,SAAS,EAAE,CAAC;gBACf,MAAM,KAAK,GAAG,MACb,SACA,CAAC,GAAG,CAAC,CAAC;gBACP,OAAO,GAAG,MAAM,GAAG,KAAK,EAAE,CAAC;YAC5B,CAAC;YACD,OAAO,GAAG,MAAM,GAAG,GAAG,CAAC,QAAQ,IAAI,EAAE,EAAE,CAAC;QACzC,CAAC,CAAqD;KACtD,CAAgD,CAAC;AACnD,CAAC,CAAC;AAEF,sEAAsE;AAEtE;;;;;;;;;;;;;;GAcG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,CAAC,OAAgB,EAAE,MAAc,EAAW,EAAE;IAC1E,MAAM,CAAC,GAAG,CAAC,GAA6B,EAAU,EAAE,CACnD,GAAG,MAAM,GAAG,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC;IAC3B,OAAO;QACN,GAAG,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;QACjC,GAAG,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;QACjC,GAAG,EAAE,CAAC,GAAG,EAAE,KAAK,EAAE,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,EAAE,KAAK,CAAC;QAC/C,MAAM,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;KACvC,CAAC;AACH,CAAC,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@adriangalilea/utils",
-	"version": "0.26.0",
+	"version": "0.28.0",
 	"description": "TypeScript utilities - logger, currency, formatter, GramIO bot plugins, and more",
 	"main": "./dist/index.js",
 	"types": "./dist/index.d.ts",
@@ -87,6 +87,14 @@
 		"./bot/callbacks": {
 			"types": "./dist/bot/callbacks.d.ts",
 			"default": "./dist/bot/callbacks.js"
+		},
+		"./bot/session": {
+			"types": "./dist/bot/session.d.ts",
+			"default": "./dist/bot/session.js"
+		},
+		"./bot/notify": {
+			"types": "./dist/bot/notify.d.ts",
+			"default": "./dist/bot/notify.js"
 		}
 	},
 	"files": [