@yaebal/panel 0.0.1 → 0.0.2

package/README.md

@@ -1,9 +1,15 @@
 # @yaebal/panel
 
 an operator panel for [yaebal](https://github.com/neverlane/yaebal) bots: view
-incoming private-chat messages and reply from the browser. ships as a
+incoming private-chat messages and reply from the browser, live. ships as a
 self-contained `fetch` handler — mount it on any HTTP framework.
 
+- **login page** on the panel root — paste your token, no secrets in the url
+- **realtime** updates over server-sent events, with a polling safety net
+- **media**: photos, docs, voice, video and albums — both directions, in the browser
+- **persistence** via a pluggable `PanelStore` (in-memory + sqlite included)
+- CORS, basePath mounting and failed-auth rate limiting
+
 ## install
 
 ```sh
@@ -15,6 +21,7 @@ pnpm add @yaebal/panel
 ```ts
 import { Bot } from "@yaebal/core";
 import { MemoryPanelStore, recorder, panelHandler } from "@yaebal/panel";
+import { serve } from "@yaebal/panel/serve";
 
 const bot = new Bot(token);
 const store = new MemoryPanelStore();
@@ -22,13 +29,137 @@ const store = new MemoryPanelStore();
 bot.install(recorder(store)); // log incoming private messages
 bot.start();
 
-// serve the panel (auth via a required token)
+// serve the panel — a fetch handler: (Request) => Promise<Response>
+const handler = panelHandler(bot.api, store, { token: process.env.PANEL_TOKEN! });
+serve(handler, { port: 8080 });
+// open http://localhost:8080 and paste your token on the login screen
+```
+
+The panel root serves a small SPA: a centered login (token input + **authorize**
+button), then the live chat view. The token is kept in `sessionStorage` and sent as
+`Authorization: Bearer …` — it never rides in the page url.
+
+## mounting
+
+`panelHandler` returns a plain `(Request) => Promise<Response>` — it binds no port of
+its own. pick a port when you wire it into a server.
+
+```ts
+// node 20+ — `serve` ships in the box (native `node:http`, no deps)
+import { serve } from "@yaebal/panel/serve";
+
+serve(handler, { port: 8080, onListen: ({ port }) => console.log(`panel on :${port}`) });
+
+// bun
+Bun.serve({ port: 8080, fetch: handler });
+
+// deno
+Deno.serve({ port: 8080 }, handler);
+
+// hono / any fetch framework
+app.all("/panel/*", (c) => handler(c.req.raw)); // pair with basePath: "/panel"
+```
+
+`serve` is a separate entry (`@yaebal/panel/serve`) so the main module stays free of
+`node:` imports for edge bundles. on cloudflare workers, deno deploy or vercel edge
+just export the handler as the `fetch` entry — same handler, no port:
+
+```ts
+export default { fetch: handler };
+```
+
+## options
+
+```ts
+panelHandler(bot.api, store, {
+  token: process.env.PANEL_TOKEN!,   // required shared secret
+  basePath: "/panel",                // mount under a sub-path (default: root)
+  cors: "https://ops.example",       // allow a browser origin (or a list, or "*")
+  rateLimit: { max: 10, windowMs: 60_000 }, // throttle failed auth (default); false to disable
+});
+```
+
+- **`basePath`** — the UI builds its api urls from this, so no extra rewriting is
+  needed when you mount under a prefix.
+- **`rateLimit`** — after `max` bad tokens within `windowMs`, a client gets `429`
+  with `Retry-After` until the window passes. keyed by `x-forwarded-for` / `x-real-ip`
+  by default; override with `clientKey`.
+
+## persistence
+
+implement `PanelStore` (`record` / `chats` / `history`, optional `subscribe` for
+realtime) to keep conversations in redis, postgres, etc. a sqlite-backed store built
+on node's native `node:sqlite` ships in the box:
+
+```ts
+import { SqlitePanelStore } from "@yaebal/panel/sqlite";
+
+const store = new SqlitePanelStore({ path: "./panel.db" }); // or ":memory:"
+bot.install(recorder(store));
 const handler = panelHandler(bot.api, store, { token: process.env.PANEL_TOKEN! });
-// handler: (Request) => Promise<Response> — open /?token=<PANEL_TOKEN>
 ```
 
-implement `PanelStore` (`record` / `chats` / `history`) to persist conversations
-in redis, postgres, etc. instead of the in-memory default.
+`subscribe` is what powers the SSE stream — a store without it still works, the UI
+just falls back to polling.
+
+## media
+
+photos, documents, voice notes, video and **albums** flow both ways:
+
+- **incoming** — the recorder stores each attachment's `file_id` (and album id). the
+  browser renders them inline: images, `<video>`, `<audio>`, or a download link for
+  documents. consecutive messages sharing a `media_group_id` are shown as one album.
+- **outgoing** — the 📎 button in the composer uploads a file; the panel picks
+  `sendPhoto` / `sendVideo` / `sendVoice` / `sendDocument` / … from its mime type
+  (the text box becomes the caption).
+
+media bytes are **proxied** through `GET /api/file?id=<file_id>` (the panel calls
+`getFile` and streams the result) so the bot token never reaches the browser. this
+needs an api with `call()` / `fileUrl()` — the real `@yaebal/core` `Api` has both;
+without them, media routes answer `501` and text still works.
+
+## what the recorder captures
+
+incoming **private-chat** messages only. text and captions are stored verbatim;
+a media-only message is previewed in the chat list as a `[photo]` / `[document]` /
+`[voice]` / … placeholder. when you reply with text from the panel, the api accepts
+`text` plus optional `parse_mode`, `reply_to_message_id` and `reply_parameters`,
+forwarded to `sendMessage`.
+
+`recorder` only sees **incoming** updates. to also capture replies the bot sends
+*elsewhere* (e.g. `ctx.reply(...)` in your own handlers), hook the api with
+`recordOutgoing` — and tell the panel to stop recording its own sends so they
+aren't logged twice:
+
+```ts
+import { recordOutgoing } from "@yaebal/panel";
+
+recordOutgoing(bot.api, store); // logs every outgoing sendMessage to a private chat
+const handler = panelHandler(bot.api, store, {
+  token: process.env.PANEL_TOKEN!,
+  recordSends: false, // recordOutgoing already covers panel replies
+});
+```
+
+## api routes
+
+mounted relative to `basePath` (default root). all but the page require the token.
+
+```text
+GET  /                       → login + chat SPA (public)
+GET  /api/chats              → PanelChat[]  (sorted by lastDate desc)
+GET  /api/chats/:id          → PanelMessage[]  (?before=&limit= to page)
+GET  /api/stream             → text/event-stream of record events
+GET  /api/file?id=<file_id>  → proxied file bytes (getFile + stream)
+POST /api/chats/:id/send     → json { text, … } → sendMessage
+                               multipart { file, caption?, type? } → sendPhoto/Document/…
+```
+
+## example
+
+a runnable, full-featured bot lives in
+[`examples/panel`](https://github.com/neverlane/yaebal/tree/master/examples/panel) —
+media both ways, `recordOutgoing`, login page and SSE, served on node.
 
 ---
 

package/lib/index.d.ts

@@ -1,9 +1,23 @@
 import type { Context, Plugin } from "@yaebal/core";
 export { PANEL_HTML } from "./panel-html.js";
+/** downloadable file kinds carried by a message (each maps to one `file_id`). */
+export type AttachmentType = "photo" | "video" | "animation" | "audio" | "voice" | "video_note" | "document" | "sticker";
+/** a downloadable attachment, referenced by telegram `file_id`. */
+export interface PanelAttachment {
+    type: AttachmentType;
+    fileId: string;
+    fileName?: string;
+    mimeType?: string;
+}
 export interface PanelMessage {
     direction: "in" | "out";
+    /** caption / text, or a `[kind]` placeholder when the message is media-only. */
     text: string;
     date: number;
+    /** downloadable attachments, fetched lazily through `GET /api/file?id=…`. */
+    attachments?: PanelAttachment[];
+    /** telegram album id — consecutive messages sharing it are one media group. */
+    mediaGroupId?: string;
 }
 export interface PanelChat {
     id: number;
@@ -11,6 +25,19 @@ export interface PanelChat {
     lastText: string;
     lastDate: number;
 }
+/** options for reading a slice of a conversation. */
+export interface HistoryOptions {
+    /** return only messages strictly older than this unix timestamp (for "load earlier"). */
+    before?: number;
+    /** cap the result to the most recent N messages within the window. */
+    limit?: number;
+}
+/** a change the panel may want to react to in real time. */
+export interface PanelEvent {
+    type: "record";
+    chatId: number;
+    direction: "in" | "out";
+}
 /** where conversations are kept for the panel to read. implement for persistence. */
 export interface PanelStore {
     record(chat: {
@@ -18,7 +45,9 @@ export interface PanelStore {
         name?: string;
     }, message: PanelMessage): void | Promise<void>;
     chats(): PanelChat[] | Promise<PanelChat[]>;
-    history(chatId: number): PanelMessage[] | Promise<PanelMessage[]>;
+    history(chatId: number, options?: HistoryOptions): PanelMessage[] | Promise<PanelMessage[]>;
+    /** optional realtime hook — return an unsubscribe fn. enables the panel's SSE stream. */
+    subscribe?(listener: (event: PanelEvent) => void): () => void;
 }
 /** defaults to in-memory store. Lost on restart — swap for a persistent one in production. */
 export declare class MemoryPanelStore implements PanelStore {
@@ -28,21 +57,75 @@ export declare class MemoryPanelStore implements PanelStore {
         name?: string;
     }, message: PanelMessage): void;
     chats(): PanelChat[];
-    history(chatId: number): PanelMessage[];
+    history(chatId: number, options?: HistoryOptions): PanelMessage[];
+    subscribe(listener: (event: PanelEvent) => void): () => void;
 }
 /** records incoming private-chat text into the store so the panel can show it. */
 export declare function recorder(store: PanelStore): Plugin<Context, Record<never, never>>;
-interface SendApi {
+/**
+ * what {@link panelHandler} needs from the api. `sendMessage` is required; `call` and
+ * `fileUrl` unlock media (file proxying + operator uploads) and are present on the real
+ * `@yaebal/core` `Api`. without them, media routes answer `501`.
+ */
+interface PanelApi {
     sendMessage(params: Record<string, unknown>): Promise<unknown>;
+    call?<T = unknown>(method: string, params?: Record<string, unknown>): Promise<T>;
+    fileUrl?(filePath: string): string;
+}
+/** the slice of `@yaebal/core`'s `Api` that {@link recordOutgoing} needs. */
+interface AfterHookApi {
+    after(hook: (method: string, result: unknown) => unknown): unknown;
 }
+/**
+ * record replies the bot sends *outside* the panel (e.g. `ctx.reply(...)` or `ctx.replyWithPhoto(...)`
+ * in your handlers) so they show up in the conversation too. hooks the api's `after` stage and logs
+ * every successful `send*` call (including `sendMediaGroup`, which returns an array) to a private chat.
+ *
+ * pairs with `panelHandler(..., { recordSends: false })` — the panel records its own sends,
+ * so disable that to avoid double entries when this is installed.
+ *
+ * ```ts
+ * recordOutgoing(bot.api, store);
+ * const handler = panelHandler(bot.api, store, { token, recordSends: false });
+ * ```
+ */
+export declare function recordOutgoing<A extends AfterHookApi>(api: A, store: PanelStore): A;
 export interface PanelOptions {
     /** shared secret required to open the panel and call its api. */
     token: string;
+    /**
+     * allowed CORS origin(s) for the panel api. omit for same-origin only (default).
+     * pass `"*"` to allow any origin, or an explicit list to echo a matching `Origin` back.
+     */
+    cors?: string | string[];
+    /**
+     * mount prefix when the handler does not live at the server root, e.g. `"/panel"`.
+     * the UI builds its api urls from this, so no extra rewriting is needed. default `""`.
+     */
+    basePath?: string;
+    /**
+     * throttle failed auth attempts per client. defaults to 10 failures / 60s, then `429`
+     * until the window passes. pass `false` to disable.
+     */
+    rateLimit?: {
+        max?: number;
+        windowMs?: number;
+    } | false;
+    /**
+     * derive a client key for rate limiting. defaults to `x-forwarded-for` / `x-real-ip`,
+     * falling back to a single shared bucket when no proxy header is present.
+     */
+    clientKey?: (request: Request) => string;
+    /**
+     * record replies sent from the panel into the store. default `true`. set to `false`
+     * when you use {@link recordOutgoing}, which already captures every outgoing message.
+     */
+    recordSends?: boolean;
 }
 /**
- * a fetch-style handler for the operator panel: serves the ui at `/`, and a small
- * api to list chats, read a conversation, and send a reply. mount it on any
- * fetch-compatible server. open it at `/?token=<your token>`.
+ * a fetch-style handler for the operator panel: serves the login + chat UI at the mount
+ * root, and a small api to list chats, read a conversation, stream updates, and send a
+ * reply. mount it on any fetch-compatible server.
  */
-export declare function panelHandler(api: SendApi, store: PanelStore, options: PanelOptions): (request: Request) => Promise<Response>;
+export declare function panelHandler(api: PanelApi, store: PanelStore, options: PanelOptions): (request: Request) => Promise<Response>;
 //# sourceMappingURL=index.d.ts.map

package/lib/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAgBpD,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAE7C,MAAM,WAAW,YAAY;IAC5B,SAAS,EAAE,IAAI,GAAG,KAAK,CAAC;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;CACb;AAED,MAAM,WAAW,SAAS;IACzB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;CACjB;AAED,qFAAqF;AACrF,MAAM,WAAW,UAAU;IAC1B,MAAM,CAAC,IAAI,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,EAAE,OAAO,EAAE,YAAY,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACzF,KAAK,IAAI,SAAS,EAAE,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC,CAAC;IAC5C,OAAO,CAAC,MAAM,EAAE,MAAM,GAAG,YAAY,EAAE,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC,CAAC;CAClE;AAED,8FAA8F;AAC9F,qBAAa,gBAAiB,YAAW,UAAU;;IAIlD,MAAM,CAAC,IAAI,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,EAAE,OAAO,EAAE,YAAY,GAAG,IAAI;IAiBxE,KAAK,IAAI,SAAS,EAAE;IAIpB,OAAO,CAAC,MAAM,EAAE,MAAM,GAAG,YAAY,EAAE;CAGvC;AAED,kFAAkF;AAClF,wBAAgB,QAAQ,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,CAAC,OAAO,EAAE,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC,CAqBjF;AAED,UAAU,OAAO;IAChB,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CAC/D;AAED,MAAM,WAAW,YAAY;IAC5B,iEAAiE;IACjE,KAAK,EAAE,MAAM,CAAC;CACd;AAQD;;;;GAIG;AACH,wBAAgB,YAAY,CAC3B,GAAG,EAAE,OAAO,EACZ,KAAK,EAAE,UAAU,EACjB,OAAO,EAAE,YAAY,GACnB,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,CAAC,QAAQ,CAAC,CAuDzC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}