@theopenbee/channel-sdk 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,59 @@
-# Temporary Holding Version
+# @theopenbee/channel-sdk
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Node.js SDK for building openbee channel plugins. It implements the stdio JSON-RPC protocol described in [`docs/channel-plugin-protocol.md`](https://github.com/theopenbee/openbee/blob/main/docs/channel-plugin-protocol.md), so a plugin only has to connect to its chat platform.
+
+Requires Node.js 20 or newer.
+
+```sh
+npm install @theopenbee/channel-sdk
+```
+
+## Usage
+
+```js
+import { defineChannel, ConfigError } from "@theopenbee/channel-sdk";
+
+defineChannel({
+  async start(ctx) {
+    if (!ctx.config.token) throw new ConfigError("token is required");
+    const client = await connect(ctx.config.token);
+    client.on("message", (m) =>
+      ctx.dispatch({ chat_id: m.channelId, sender_id: m.authorId, message_id: m.id, text: m.text }),
+    );
+    return { stop: () => client.close() };
+  },
+  async send(msg, ctx, signal) {
+    await deliver(msg, { signal });
+  },
+});
+```
+
+## What the SDK handles
+
+- Line-delimited JSON-RPC framing on stdin/stdout, request ids, `$/cancelRequest` (exposed as the `AbortSignal` passed to `send`).
+- `initialize`: builds the context and calls `start`. Throwing `ConfigError` reports a config problem (`-32001`) and openbee will not restart the plugin; any other error exits the process so openbee restarts it.
+- `shutdown` and stdin EOF: calls `stop` and exits. A plugin must never outlive openbee.
+- `console.log`, `console.info` and `console.debug` are redirected to stderr so they cannot corrupt the protocol stream; stderr lines end up in the openbee log.
+- Uncaught exceptions and unhandled rejections are written to stderr and exit with code 1.
+
+## Context
+
+| Field | Description |
+|---|---|
+| `channelId` | Channel id from the manifest |
+| `config` | Resolved config from `bee.platforms.<id>` (defaults applied, `enabled` and `bot_name` removed) |
+| `botName` | The configured bot display name |
+| `language` | openbee UI language (`en` or `zh`) |
+| `dataDir` | Private writable directory for this plugin |
+| `mediaDir` | Directory where inbound attachments must be stored |
+| `dispatch(msg)` | Hand an inbound message to openbee |
+| `saveMedia(data, ext)` | Write an attachment into `mediaDir` and return its path |
+| `log.debug/info/warn/error(message, fields?)` | Structured logs in the openbee log |
+
+## Development
+
+```sh
+pnpm install
+pnpm build
+pnpm test
+```

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+import type { ChannelDefinition } from "./types.js";
+export * from "./types.js";
+export { PROTOCOL_VERSION } from "./rpc.js";
+export declare class ConfigError extends Error {
+    constructor(message: string);
+}
+export interface ChannelIO {
+    input: NodeJS.ReadableStream;
+    output: NodeJS.WritableStream;
+}
+export declare function defineChannel(def: ChannelDefinition, io?: ChannelIO): void;

package/dist/index.js

@@ -0,0 +1,158 @@
+import { randomBytes } from "node:crypto";
+import { writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { format } from "node:util";
+import { CODE_CONFIG_INVALID, CODE_INTERNAL_ERROR, CODE_METHOD_NOT_FOUND, CODE_REQUEST_CANCELLED, CODE_REQUEST_FAILED, Peer, PROTOCOL_VERSION, } from "./rpc.js";
+export * from "./types.js";
+export { PROTOCOL_VERSION } from "./rpc.js";
+export class ConfigError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "ConfigError";
+    }
+}
+function redirectConsole() {
+    const toStderr = (...args) => {
+        process.stderr.write(format(...args) + "\n");
+    };
+    console.log = toStderr;
+    console.info = toStderr;
+    console.debug = toStderr;
+}
+function installCrashHandlers() {
+    const crash = (err) => {
+        process.stderr.write(`fatal: ${err instanceof Error ? (err.stack ?? err.message) : String(err)}\n`);
+        process.exit(1);
+    };
+    process.on("uncaughtException", crash);
+    process.on("unhandledRejection", crash);
+}
+function errorMessage(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+export function defineChannel(def, io) {
+    const input = io?.input ?? process.stdin;
+    const output = io?.output ?? process.stdout;
+    if (output === process.stdout) {
+        redirectConsole();
+        installCrashHandlers();
+    }
+    const peer = new Peer(input, output);
+    const inflight = new Map();
+    let ctx;
+    let handle = undefined;
+    let stopping;
+    const stop = () => {
+        if (!stopping) {
+            stopping = (async () => {
+                for (const controller of inflight.values())
+                    controller.abort();
+                try {
+                    await handle?.stop?.();
+                }
+                catch (err) {
+                    process.stderr.write(`stop failed: ${errorMessage(err)}\n`);
+                }
+            })();
+        }
+        return stopping;
+    };
+    const exit = (code) => {
+        output.write("", () => process.exit(code));
+    };
+    const log = (level) => (message, fields) => {
+        void peer.notify("log", fields ? { level, message, fields } : { level, message });
+    };
+    const buildContext = (p) => ({
+        channelId: p.channel_id,
+        config: p.config ?? {},
+        botName: p.bot_name ?? "",
+        language: p.language ?? "en",
+        dataDir: p.data_dir,
+        mediaDir: p.media_dir,
+        openbeeVersion: p.openbee_version ?? "",
+        dispatch: (message) => {
+            void peer.notify("inbound", message);
+        },
+        saveMedia: async (data, ext) => {
+            const suffix = ext ? (ext.startsWith(".") ? ext : "." + ext) : "";
+            const path = join(p.media_dir, `${Date.now()}-${randomBytes(4).toString("hex")}${suffix}`);
+            await writeFile(path, data);
+            return path;
+        },
+        log: { debug: log("debug"), info: log("info"), warn: log("warn"), error: log("error") },
+    });
+    const handleInitialize = async (id, params) => {
+        ctx = buildContext(params);
+        try {
+            handle = await def.start(ctx);
+        }
+        catch (err) {
+            if (err instanceof ConfigError) {
+                await peer.respondError(id, CODE_CONFIG_INVALID, err.message);
+            }
+            else {
+                await peer.respondError(id, CODE_INTERNAL_ERROR, errorMessage(err));
+            }
+            exit(1);
+            return;
+        }
+        await peer.respond(id, { protocol_version: PROTOCOL_VERSION });
+    };
+    const handleSend = async (id, params) => {
+        if (!ctx) {
+            await peer.respondError(id, CODE_REQUEST_FAILED, "channel is not initialized");
+            return;
+        }
+        const controller = new AbortController();
+        inflight.set(id, controller);
+        try {
+            const result = await def.send(params, ctx, controller.signal);
+            if (controller.signal.aborted) {
+                await peer.respondError(id, CODE_REQUEST_CANCELLED, "request cancelled");
+            }
+            else {
+                await peer.respond(id, result ?? {});
+            }
+        }
+        catch (err) {
+            const code = controller.signal.aborted ? CODE_REQUEST_CANCELLED : CODE_REQUEST_FAILED;
+            await peer.respondError(id, code, errorMessage(err));
+        }
+        finally {
+            inflight.delete(id);
+        }
+    };
+    const handleShutdown = async (id) => {
+        await stop();
+        await peer.respond(id, {});
+        exit(0);
+    };
+    const onMessage = (msg) => {
+        const { id, method, params } = msg;
+        if (method === "$/cancelRequest") {
+            const target = params?.id;
+            if (target !== undefined)
+                inflight.get(target)?.abort();
+            return;
+        }
+        if (id === undefined || id === null || !method)
+            return;
+        switch (method) {
+            case "initialize":
+                void handleInitialize(id, params);
+                return;
+            case "send":
+                void handleSend(id, params);
+                return;
+            case "shutdown":
+                void handleShutdown(id);
+                return;
+            default:
+                void peer.respondError(id, CODE_METHOD_NOT_FOUND, `method not found: ${method}`);
+        }
+    };
+    peer.listen(onMessage, () => {
+        void stop().then(() => exit(0));
+    });
+}

package/dist/rpc.d.ts

@@ -0,0 +1,27 @@
+export declare const PROTOCOL_VERSION = 1;
+export declare const CODE_CONFIG_INVALID = -32001;
+export declare const CODE_METHOD_NOT_FOUND = -32601;
+export declare const CODE_INTERNAL_ERROR = -32603;
+export declare const CODE_REQUEST_FAILED = -32000;
+export declare const CODE_REQUEST_CANCELLED = -32800;
+export type MessageId = number | string;
+export interface IncomingMessage {
+    id?: MessageId;
+    method?: string;
+    params?: unknown;
+}
+export declare class RpcError extends Error {
+    readonly code: number;
+    constructor(code: number, message: string);
+}
+export declare class Peer {
+    private readonly input;
+    private readonly output;
+    private queue;
+    constructor(input: NodeJS.ReadableStream, output: NodeJS.WritableStream);
+    listen(onMessage: (msg: IncomingMessage) => void, onClose: () => void): void;
+    notify(method: string, params?: unknown): Promise<void>;
+    respond(id: MessageId, result: unknown): Promise<void>;
+    respondError(id: MessageId, code: number, message: string): Promise<void>;
+    private write;
+}

package/dist/rpc.js

@@ -0,0 +1,57 @@
+import { createInterface } from "node:readline";
+export const PROTOCOL_VERSION = 1;
+export const CODE_CONFIG_INVALID = -32001;
+export const CODE_METHOD_NOT_FOUND = -32601;
+export const CODE_INTERNAL_ERROR = -32603;
+export const CODE_REQUEST_FAILED = -32000;
+export const CODE_REQUEST_CANCELLED = -32800;
+export class RpcError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+    }
+}
+export class Peer {
+    input;
+    output;
+    queue = Promise.resolve();
+    constructor(input, output) {
+        this.input = input;
+        this.output = output;
+    }
+    listen(onMessage, onClose) {
+        const rl = createInterface({ input: this.input, crlfDelay: Infinity });
+        rl.on("line", (line) => {
+            const trimmed = line.trim();
+            if (!trimmed)
+                return;
+            let msg;
+            try {
+                msg = JSON.parse(trimmed);
+            }
+            catch {
+                return;
+            }
+            if (msg && typeof msg === "object")
+                onMessage(msg);
+        });
+        rl.on("close", onClose);
+    }
+    notify(method, params) {
+        return this.write({ jsonrpc: "2.0", method, params });
+    }
+    respond(id, result) {
+        return this.write({ jsonrpc: "2.0", id, result: result ?? {} });
+    }
+    respondError(id, code, message) {
+        return this.write({ jsonrpc: "2.0", id, error: { code, message } });
+    }
+    write(obj) {
+        const line = JSON.stringify(obj) + "\n";
+        this.queue = this.queue.then(() => new Promise((resolve) => {
+            this.output.write(line, () => resolve());
+        }));
+        return this.queue;
+    }
+}

package/dist/types.d.ts

@@ -0,0 +1,72 @@
+export type AttachmentType = "image" | "audio" | "video" | "document" | "sticker";
+export interface Attachment {
+    type: AttachmentType;
+    path: string;
+    name?: string;
+}
+export interface InboundMessage {
+    chat_id: string;
+    sender_id: string;
+    session_scope?: string;
+    message_id?: string;
+    text?: string;
+    attachments?: Attachment[];
+    raw?: string;
+    context?: Record<string, unknown>;
+    time?: number;
+}
+export interface ReplyTo {
+    message_id?: string;
+    raw?: string;
+}
+export interface SendRequest {
+    session_key: string;
+    chat_id: string;
+    session_scope: string;
+    proactive: boolean;
+    reply_to?: ReplyTo;
+    content?: string;
+    media?: {
+        path: string;
+        name: string;
+    };
+}
+export interface SendResult {
+    platform_message_id?: string;
+}
+export interface InitializeParams {
+    protocol_version: number;
+    openbee_version: string;
+    channel_id: string;
+    language: string;
+    bot_name: string;
+    config: Record<string, unknown>;
+    data_dir: string;
+    media_dir: string;
+}
+export type LogFields = Record<string, unknown>;
+export interface Logger {
+    debug(message: string, fields?: LogFields): void;
+    info(message: string, fields?: LogFields): void;
+    warn(message: string, fields?: LogFields): void;
+    error(message: string, fields?: LogFields): void;
+}
+export interface ChannelContext {
+    channelId: string;
+    config: Record<string, unknown>;
+    botName: string;
+    language: string;
+    dataDir: string;
+    mediaDir: string;
+    openbeeVersion: string;
+    dispatch(message: InboundMessage): void;
+    saveMedia(data: Uint8Array, ext: string): Promise<string>;
+    log: Logger;
+}
+export interface ChannelHandle {
+    stop?: () => void | Promise<void>;
+}
+export interface ChannelDefinition {
+    start(ctx: ChannelContext): Promise<ChannelHandle | void> | ChannelHandle | void;
+    send(message: SendRequest, ctx: ChannelContext, signal: AbortSignal): Promise<SendResult | void> | SendResult | void;
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -1,6 +1,42 @@
 {
   "name": "@theopenbee/channel-sdk",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "SDK for building openbee channel plugins",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/theopenbee/channel-sdk.git"
+  },
+  "homepage": "https://github.com/theopenbee/channel-sdk#readme",
+  "bugs": {
+    "url": "https://github.com/theopenbee/channel-sdk/issues"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "node --test test/*.test.mjs",
+    "prepack": "npm run build"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "typescript": "^5.7.0"
+  }
+}