@adriangalilea/utils 0.5.0 → 0.7.0

package/README.md

@@ -200,6 +200,7 @@ Every `SourcedError` carries `source`, `operation`, `status`, `context`, and the
 - **XDG**: XDG Base Directory paths — reads env vars set by [xdg-dirs](https://github.com/adriangalilea/xdg-dirs), falls back to spec defaults
 - **Unseen**: Persistent dedup filter — "what's new since last time?" for cron/monitoring workflows
 - **Project Discovery**: Find project/monorepo roots, detect JS/TS projects
+- **Bot plugins (GramIO)**: `kit` (graceful shutdown + admin context), `access-control` (gate + approve/deny menu, backed by sessions), `llm-stream` (streaming LLM markdown to Telegram with graceful degradation)
 
 ### XDG Base Directories
 
@@ -249,6 +250,51 @@ newMessages = [{ id: '2', from: 'bob', text: 'hey' }]
 
 Saves state to: `$XDG_STATE_HOME/unseen/{name}.json`
 
+### Telegram bot plugins (GramIO)
+
+Plugins for personal Telegram bots built on [GramIO](https://gramio.dev). Each plugin lives at its own subpath; peer deps (`gramio`, `@gramio/storage`, `@gramio/session`, `@gramio/format`, `marked`) are **all optional** — install only what you import.
+
+```bash
+pnpm add @adriangalilea/utils gramio @gramio/storage @gramio/session
+```
+
+| Subpath | What it does |
+|---|---|
+| `@adriangalilea/utils/bot/kit` | `gracefulStart(bot)` — SIGINT/SIGTERM → `bot.stop()` → exit; force-kills if shutdown hangs.<br>`adminContext({ adminId? })` — reads `TELEGRAM_ADMIN_ID` from `kev` (with optional hardcoded fallback), decorates `ctx.adminId` + `ctx.isAdmin`. |
+| `@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. |
+| `@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. |
+| `@adriangalilea/utils/bot/llm-stream` | `ctx.startStream()` for LLM token streams. Debounced `editMessageText`, splits at 4000 chars on paragraph/line/word boundary, parses Markdown locally so malformed mid-stream markup degrades to plain text instead of failing. |
+
+Standard wiring:
+
+```typescript
+import { Bot } from 'gramio'
+import { redisStorage } from '@gramio/storage-redis'
+import { adminContext, gracefulStart } from '@adriangalilea/utils/bot/kit'
+import { accessControl } from '@adriangalilea/utils/bot/access-control'
+import { llmStream } from '@adriangalilea/utils/bot/llm-stream'
+
+const storage = redisStorage()                      // ONE instance, shared
+
+const bot = new Bot(process.env.BOT_TOKEN!)
+  .extend(adminContext({ adminId: 190202471 }))     // KEV.TELEGRAM_ADMIN_ID overrides
+  .extend(accessControl({ storage, defaults: [] })) // gate; depends on adminContext
+  .extend(llmStream())
+  .command('chat', async (ctx) => {
+    const stream = ctx.startStream()
+    for await (const chunk of yourLLM()) await stream.append(chunk.text)
+    await stream.end()
+  })
+
+await gracefulStart(bot)
+```
+
+Inside handlers, `ctx.access` is a typed discriminated union — `{ allowed: true, source: 'admin' | 'default' | 'store', record? }` or `{ allowed: false, reason }`. `ctx.adminId` and `ctx.isAdmin` are available on every event from `adminContext`.
+
+For tests/demos without a second Telegram account, `simulateAccessRequest(bot, storage, adminId, fakeUser, msg)` injects a synthetic pending request so admin can exercise the approve/deny flow.
+
+See `src/bot/CLAUDE.md` for storage layout, design decisions, and gotchas.
+
 ## Release
 
 Bump version in `package.json` (and `jsr.json`), push to `main`. CI handles everything:

package/dist/bot/access-control.d.ts

@@ -0,0 +1,339 @@
+/**
+ * Access control for personal GramIO bots — a one-stop guard +
+ * approve/deny + revocable allow-list with an inline admin menu.
+ *
+ *                stranger DMs your bot
+ *                       │
+ *                       ▼
+ *      ┌──── plugin gate (this file) ────────────────────┐
+ *      │  ctx.from.id  ∈  admin / defaults / approved?   │
+ *      │     yes → next()                                │
+ *      │     no  → drop + notify admin (rate-limited)    │
+ *      └─────────────────────────────────────────────────┘
+ *                       │
+ *           admin gets DM with [✅ Aprobar] [❌ Denegar]
+ *                       │
+ *                  admin taps
+ *                       │
+ *      stranger's session updated  ·  stranger gets DM
+ *
+ * **Storage layout.** Per-user state lives in its own key, written
+ * through `@gramio/session` so the gate read on the hot path costs
+ * nothing extra (session is loaded for the user already). A single
+ * tiny index key keeps track of who's pending / approved / denied so
+ * the `/access` admin menu can list without scanning the whole DB.
+ *
+ *     storage:
+ *       access:<userId>        → AccessRecord  (the user's session)
+ *       ac:index               → { pending, approved, denied }
+ *
+ * **Cross-user mutations.** When you tap `[✅ Aprobar]` on Pepe's
+ * notification, ctx is *yours* (the admin), so `ctx.access` is your
+ * own record. To mutate Pepe's record we hit the storage at the same
+ * key format we registered the session with (`access:<id>`) and
+ * update the index. This isn't a hack — it's our own module
+ * coordinating with itself.
+ *
+ * **Composes with `adminContext`** (kit.ts) — that plugin must be
+ * extended first or `bot.start()` throws. Inside this plugin,
+ * `ctx.adminId` and `ctx.isAdmin` are typed.
+ *
+ * Peer deps: `gramio`, `@gramio/storage`, `@gramio/session`.
+ *
+ * @example
+ * import { Bot } from 'gramio'
+ * import { redisStorage } from '@gramio/storage-redis'
+ * import { adminContext, gracefulStart } from '@adriangalilea/utils/bot/kit'
+ * import { accessControl } from '@adriangalilea/utils/bot/access-control'
+ *
+ * const storage = redisStorage()
+ *
+ * const bot = new Bot(process.env.BOT_TOKEN!)
+ *   .extend(adminContext({ adminId: 190202471 }))
+ *   .extend(accessControl({ storage, defaults: [1158734055] }))
+ *   .command('start', (ctx) => ctx.send(`hola, source=${ctx.access.source}`))
+ *
+ * await gracefulStart(bot)
+ */
+import { type AnyBot, type DeriveDefinitions, Plugin } from 'gramio';
+import { type Storage } from '@gramio/storage';
+export type AccessStatus = 'unknown' | 'pending' | 'approved' | 'denied';
+export type AccessUser = {
+    id: number;
+    firstName?: string;
+    lastName?: string;
+    username?: string;
+};
+/**
+ * The shape persisted per-user via session at `access:<userId>`.
+ * `unknown` is the initial state (session never seen this user).
+ */
+export type AccessRecord = {
+    status: AccessStatus;
+    user?: AccessUser;
+    /** Chat to DM the user back. For private chats this equals user.id. */
+    chatId?: number;
+    requestedAt?: number;
+    approvedAt?: number;
+    approvedBy?: number;
+    deniedAt?: number;
+    deniedBy?: number;
+    /** First message text from the request (truncated). */
+    firstMessage?: string;
+    lastActivityAt?: number;
+    messageCount?: number;
+    /** Counts attempts after the initial request — used by the throttle. */
+    rejectedAttempts?: number;
+    lastNotifiedAt?: number;
+};
+export type AccessIndex = {
+    pending: number[];
+    approved: number[];
+    denied: number[];
+};
+export type AccessSource = 'admin' | 'default' | 'store';
+/**
+ * What handlers downstream see on `ctx.access`. A discriminated union —
+ * use the `allowed` field to narrow.
+ */
+export type AccessInfo = {
+    allowed: true;
+    source: AccessSource;
+    /** The persisted record, when source is 'store'. */
+    record?: AccessRecord;
+} | {
+    allowed: false;
+    reason: 'denied' | 'pending' | 'unknown' | 'no-sender';
+};
+export type AccessControlOptions = {
+    /** Persistence. Default `inMemoryStorage()` (data lost on restart — warns once). */
+    storage?: Storage;
+    /** Always-allowed user ids, hardcoded. Bypass the entire flow. */
+    defaults?: ReadonlyArray<number>;
+    /** Reply sent to denied users on first attempt. `false` to silence. */
+    denyMessage?: string | false;
+    /** Min ms between repeat admin notifications for the same user. Default 6h. */
+    notifyThrottleMs?: number;
+    /** Callbacks for your own logging / metrics. */
+    onAccessRequest?: (info: {
+        user: AccessUser;
+        firstMessage?: string;
+    }) => void;
+    onApprove?: (info: {
+        userId: number;
+        approvedBy: number;
+    }) => void;
+    onDeny?: (info: {
+        userId: number;
+        deniedBy: number;
+    }) => void;
+};
+type AdminDerives = {
+    adminId: number;
+    isAdmin: boolean;
+};
+type AccessSessionDerives = {
+    _accessSession: AccessRecord;
+};
+type AccessDerives = {
+    access: AccessInfo;
+};
+export declare const accessControl: (opts?: AccessControlOptions) => Plugin<{}, DeriveDefinitions & {
+    global: AdminDerives & AccessSessionDerives & AccessDerives;
+} & {
+    message: {
+        _accessSession: AccessRecord & {
+            $clear: () => Promise<void>;
+        };
+    };
+    channel_post: {
+        _accessSession: AccessRecord & {
+            $clear: () => Promise<void>;
+        };
+    };
+    inline_query: {
+        _accessSession: AccessRecord & {
+            $clear: () => Promise<void>;
+        };
+    };
+    chosen_inline_result: {
+        _accessSession: AccessRecord & {
+            $clear: () => Promise<void>;
+        };
+    };
+    callback_query: {
+        _accessSession: AccessRecord & {
+            $clear: () => Promise<void>;
+        };
+    };
+    shipping_query: {
+        _accessSession: AccessRecord & {
+            $clear: () => Promise<void>;
+        };
+    };
+    pre_checkout_query: {
+        _accessSession: AccessRecord & {
+            $clear: () => Promise<void>;
+        };
+    };
+    poll_answer: {
+        _accessSession: AccessRecord & {
+            $clear: () => Promise<void>;
+        };
+    };
+    chat_join_request: {
+        _accessSession: AccessRecord & {
+            $clear: () => Promise<void>;
+        };
+    };
+    new_chat_members: {
+        _accessSession: AccessRecord & {
+            $clear: () => Promise<void>;
+        };
+    };
+    new_chat_title: {
+        _accessSession: AccessRecord & {
+            $clear: () => Promise<void>;
+        };
+    };
+    new_chat_photo: {
+        _accessSession: AccessRecord & {
+            $clear: () => Promise<void>;
+        };
+    };
+    delete_chat_photo: {
+        _accessSession: AccessRecord & {
+            $clear: () => Promise<void>;
+        };
+    };
+    group_chat_created: {
+        _accessSession: AccessRecord & {
+            $clear: () => Promise<void>;
+        };
+    };
+    message_auto_delete_timer_changed: {
+        _accessSession: AccessRecord & {
+            $clear: () => Promise<void>;
+        };
+    };
+    migrate_to_chat_id: {
+        _accessSession: AccessRecord & {
+            $clear: () => Promise<void>;
+        };
+    };
+    migrate_from_chat_id: {
+        _accessSession: AccessRecord & {
+            $clear: () => Promise<void>;
+        };
+    };
+    pinned_message: {
+        _accessSession: AccessRecord & {
+            $clear: () => Promise<void>;
+        };
+    };
+    invoice: {
+        _accessSession: AccessRecord & {
+            $clear: () => Promise<void>;
+        };
+    };
+    successful_payment: {
+        _accessSession: AccessRecord & {
+            $clear: () => Promise<void>;
+        };
+    };
+    chat_shared: {
+        _accessSession: AccessRecord & {
+            $clear: () => Promise<void>;
+        };
+    };
+    proximity_alert_triggered: {
+        _accessSession: AccessRecord & {
+            $clear: () => Promise<void>;
+        };
+    };
+    video_chat_scheduled: {
+        _accessSession: AccessRecord & {
+            $clear: () => Promise<void>;
+        };
+    };
+    video_chat_started: {
+        _accessSession: AccessRecord & {
+            $clear: () => Promise<void>;
+        };
+    };
+    video_chat_ended: {
+        _accessSession: AccessRecord & {
+            $clear: () => Promise<void>;
+        };
+    };
+    video_chat_participants_invited: {
+        _accessSession: AccessRecord & {
+            $clear: () => Promise<void>;
+        };
+    };
+    web_app_data: {
+        _accessSession: AccessRecord & {
+            $clear: () => Promise<void>;
+        };
+    };
+    location: {
+        _accessSession: AccessRecord & {
+            $clear: () => Promise<void>;
+        };
+    };
+    passport_data: {
+        _accessSession: AccessRecord & {
+            $clear: () => Promise<void>;
+        };
+    };
+} & {
+    global: {
+        access: {
+            allowed: false;
+            reason: "no-sender";
+            source?: undefined;
+            record?: undefined;
+        };
+    } | {
+        access: {
+            allowed: true;
+            source: "admin";
+            reason?: undefined;
+            record?: undefined;
+        };
+    } | {
+        access: {
+            allowed: true;
+            source: "default";
+            reason?: undefined;
+            record?: undefined;
+        };
+    } | {
+        access: {
+            allowed: true;
+            source: "store";
+            record: AccessRecord;
+            reason?: undefined;
+        };
+    } | {
+        access: {
+            allowed: false;
+            reason: "unknown" | "pending" | "denied";
+            source?: undefined;
+            record?: undefined;
+        };
+    };
+}, {}>;
+/**
+ * Inject a synthetic access request — for tests/demos when you can't
+ * easily spin up a second Telegram account. Writes a `pending` record
+ * to storage at the same key the plugin's session would, updates the
+ * index, then DMs the admin with the real
+ * `[✅ Aprobar][❌ Denegar]` keyboard. Tapping those buttons exercises
+ * the real callback handlers end-to-end.
+ *
+ * Pass the SAME `storage` instance you passed to `accessControl({ storage })`.
+ */
+export declare const simulateAccessRequest: (bot: AnyBot, storage: Storage, adminId: number, fakeUser: AccessUser, message?: string) => Promise<void>;
+export {};
+//# sourceMappingURL=access-control.d.ts.map

package/dist/bot/access-control.d.ts.map

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