morok-bot-sdk 1.0.1

package/dist/bot.d.ts

@@ -0,0 +1,232 @@
+/**
+ * Public orchestrator. Use MorokBot.fromFile(...) to construct
+ * The ctor is private because .morokbot parsing and state-dir setup need IO
+ *
+ * Lifecycle:
+ *   fromFile: parse .morokbot, build modules (no network IO)
+ *   start(): import keys, fsck state, /auth/bot-session, WS handshake, prekey replenish + background loop
+ *   stop(): prekey loop -> ws -> pending sends -> done
+ *
+ * `error` fires on recoverable failures (decrypt errors, exceptions thrown by developer handlers)
+ * start() itself throws on fatal init errors (bad .morokbot, 401, etc.)
+ */
+import { EventEmitter } from 'node:events';
+import type { BotConfig, IncomingMessage, CommandInvocation, BotStartEvent, BotStopEvent, ReactionEvent, ControlEvent, BotControl, ConversationAddedEvent, ConversationKickedEvent, DisconnectInfo, AttachmentInput } from './types.js';
+import { type SendResult } from './flow/direct.js';
+export interface SendArgs {
+    /**
+     * DM target, numeric userId or username (the SDK resolves a username via `GET /users/:username`)
+     * Mutually exclusive with `conversation`
+     */
+    peer?: number | string;
+    /**
+     * Group-chat / channel target, numeric conversationId. Mutually exclusive with `peer`
+     * The bot must already be a member, obtain `conversationId` from a `conversation_added` event,
+     * or from an incoming `IncomingMessage.conversationId` when responding to one
+     */
+    conversation?: number;
+    /**
+     * Message text. Required when `attachment` is absent
+     * Sent alongside a `'file'` attachment, it becomes the caption
+     * Ignored (with a debug log) for `'voice'` and `'video_note'` attachments,
+     * the FE renderer has no caption slot for those
+     */
+    text?: string;
+    /**
+     * Single attachment (file / voice / video_note). Mutually exclusive with `attachments`
+     */
+    attachment?: AttachmentInput;
+    /**
+     * Gallery of 2-10 file attachments shipped in one message, the bubble renders as a grid on the FE
+     * voice and video_note are not allowed in a gallery
+     * (server caps and FE renderer both expect `kind: 'file'` per item). Mutually exclusive with `attachment`
+     */
+    attachments?: AttachmentInput[];
+    replyToId?: number;
+    replyToClientMsgId?: string;
+    threadRootId?: number;
+    /** Disappearing-message TTL in seconds. Server-validated */
+    expiresInSeconds?: number;
+}
+export interface ReplyArgs {
+    text?: string;
+    attachment?: AttachmentInput;
+    attachments?: AttachmentInput[];
+    expiresInSeconds?: number;
+}
+interface MorokBotEvents {
+    message: (msg: IncomingMessage) => void | Promise<void>;
+    command: (cmd: CommandInvocation) => void | Promise<void>;
+    start: (e: BotStartEvent) => void | Promise<void>;
+    stop: (e: BotStopEvent) => void | Promise<void>;
+    reaction: (e: ReactionEvent) => void | Promise<void>;
+    control: (e: ControlEvent) => void | Promise<void>;
+    conversation_added: (e: ConversationAddedEvent) => void | Promise<void>;
+    conversation_kicked: (e: ConversationKickedEvent) => void | Promise<void>;
+    disconnect: (info: DisconnectInfo) => void | Promise<void>;
+    error: (err: Error) => void | Promise<void>;
+}
+export declare class MorokBot extends EventEmitter {
+    private readonly file;
+    private readonly stateDir;
+    private readonly apiBaseUrl;
+    private readonly wsUrlVal;
+    private readonly logger?;
+    private readonly bgIntervalMs;
+    private readonly replenishThreshold;
+    private readonly replenishTarget;
+    private readonly autoBackfillOnJoin;
+    private readonly serveBackfillRequests;
+    private signal?;
+    private http?;
+    private ws?;
+    private direct?;
+    private receive?;
+    private groups?;
+    private chanStore?;
+    private gsStore?;
+    private convCache?;
+    private stateLock?;
+    private prekey?;
+    private botUserId?;
+    private running;
+    /** Set true synchronously when start() enters, before any await, so a second concurrent start() returns
+     *  without opening a second WS. Separate from `running` so isConnected stays accurate during boot */
+    private starting;
+    /** Flipped by stop() while start() is mid-flight. start() checks it at every checkpoint,
+     *  and throws into its own catch so teardown runs and nothing is left open */
+    private stopRequested;
+    private constructor();
+    /** Read + validate the .morokbot file and build the bot. No network IO, call start() to connect */
+    static fromFile(config: BotConfig & {
+        tokenFile: string;
+    }): Promise<MorokBot>;
+    /** Connect. Resolves after WS auth + boot prekey replenish. Throws on fatal init errors. Idempotent */
+    start(): Promise<void>;
+    private assertResolvedUserId;
+    /**
+     * One-shot device-certificate publish (D cross-signing). Signs a certificate over this device's identity key
+     * under the .morokbot account signing key (XSK) and commits it via POST /crypto/cross-signing,
+     * so peers verify the bot's device against its account key and render a cross-signed safety number
+     * (routes/developer.ts:556 documents this obligation)
+     *
+     * Best-effort and idempotent: re-submitting the same (XSK, cert) on every start succeeds server-side
+     * Any failure (network, 409 XSK_ALREADY_SET / IDENTITY_ROTATED, missing XSK) is logged and non-fatal,
+     * the bot keeps running uncertified while peers fall back to TOFU
+     *  One device per bot, so the FE's multi-device XSK propagation races don't apply here
+     *
+     * Skipped silently when the .morokbot predates cross-signing (no accountSigningKey), matching the FE
+     */
+    private ensureCrossSigning;
+    /** Clean shutdown. Stops background loops, closes the socket, rejects pending sends,
+     *  releases the state lock. Idempotent. If start() is mid-flight, stopRequested makes it abort
+     *  at the next checkpoint into its catch path */
+    stop(): Promise<void>;
+    get isConnected(): boolean;
+    /** Bot's own userId. Available after start() resolves */
+    get userId(): number;
+    send(args: SendArgs): Promise<SendResult>;
+    private sendDirect;
+    private sendGroup;
+    /** Rotate the channel-key. Mints a fresh 32-byte secret, wraps it to every other member device,
+     *  POSTs to /channel-key/rotate. The server allows any member,
+     *  so the bot's call is functionally identical to a human admin's */
+    rotateChannelKey(conversationId: number): Promise<{
+        epoch: number;
+    }>;
+    /** Share locally-known channel-key epochs with another member's devices
+     *  Useful when the bot is the only online member at the moment a new joiner needs history
+     *
+     *  target.deviceIds optional, absent = fetch via /prekeys/:userId/devices
+     *  opts.epochs optional, absent = all local epochs. Server filters pre-join epochs by joined_secret_version */
+    backfillChannelKeys(conversationId: number, target: {
+        userId: number;
+        deviceIds?: number[];
+    }, opts?: {
+        epochs?: number[];
+    }): Promise<{
+        accepted: number;
+    }>;
+    /**
+     * Rotate group_secret and channel-key in one server transaction
+     * Run after kicking a leaker so a stale ex-member can't unseal future bundles with the old group_secret
+     *
+     * Server constraints (POST /groups/:id/group-secret/rotate):
+     *   - conv type must be GROUP
+     *   - conv must be private or the caller must be owner
+     *   - bot must hold the current group_secret (auto-fetched)
+     *
+     * Error codes (axios error.response.data.code):
+     *   SECRET_VERSION_STALE : someone else rotated, retry
+     *   NOT_PRIVATE          : bot lacks permission
+     *   DIST_MISMATCH        : membership shifted mid-rotate
+     *   NO_READY_DEVICES     : no recipient had an SPK
+     *
+     * Also re-seals every locally-known historical epoch under the new group_secret (server's resealHistorical field)
+     * After a rotate, no epoch is unsealable with the old secret
+     * If the bot is missing some historical epochs it reseals what it has, the rest can be patched on a later rotate
+     */
+    rotateGroupSecret(conversationId: number): Promise<{
+        epoch: number;
+        version: number;
+    }>;
+    /**
+     * Replace the bot's slash-command catalogue (the /-autocomplete the composer offers users)
+     * Call after start(). Defining handlers does not advertise commands, the catalogue is separate
+     * Server bounds: up to 32 entries, name /^[a-z][a-z0-9_]{0,31}$/, description trimmed to 256 chars
+     * An empty array clears it. Idempotent, safe to call on every start
+     */
+    setMyCommands(commands: ReadonlyArray<{
+        command: string;
+        description: string;
+        sortOrder?: number;
+    }>): Promise<{
+        count: number;
+    }>;
+    setMyControls(controls: ReadonlyArray<BotControl>): Promise<{
+        count: number;
+    }>;
+    /**
+     * Set the control buttons for ONE user's chat without touching the global menu others see
+     * Use it to drive a stateful flow, for example search results as buttons or a step-by-step wizard
+     * Pass the user id from an incoming message or control event (sender.userId)
+     * The override is short-lived on the server and survives that user's reload
+     * An empty array shows no buttons, call clearControlsFor to revert to the global menu
+     * Bounds match setMyControls, up to 16 top-level and 64 total nodes and depth 4
+     */
+    setControlsFor(peerUserId: number, controls: ReadonlyArray<BotControl>): Promise<{
+        count: number;
+    }>;
+    /**
+     * Drop a user's per-chat control override and revert them to the global menu set by setMyControls
+     * Call this when the flow ends
+     */
+    clearControlsFor(peerUserId: number): Promise<void>;
+    /** Reply to an incoming message. Threads replyToId/clientMsgId,
+     *  routes DM vs group/channel by msg.conversationType */
+    reply(msg: IncomingMessage, args: ReplyArgs): Promise<SendResult>;
+    /**
+     * React to a message with a unicode symbol (any character, emoji included)
+     * DM reactions are encrypted per peer device (Signal), group-chat/channel reactions under the shared channel-key
+     * The reactor (this bot) is never echoed its own reaction back,
+     * so this resolves as soon as the frame is queued, there is no own-echo to await
+     * Re-reacting with a different symbol replaces the bot's previous one server-side
+     *
+     * `msg` is an incoming message or command. It carries messageId, conversationId,
+     * conversationType and sender. In a DM the reaction is encrypted to msg.sender (the peer)
+     */
+    react(msg: IncomingMessage, unicode: string): Promise<void>;
+    /**
+     * Remove this bot's reaction from a message. The server keys deletion off (messageId, reactorUserId),
+     * so no ciphertext is needed. One frame clears every distribution shape the bot wrote
+     */
+    unreact(msg: IncomingMessage): Promise<void>;
+    /** Resolve userId or username to a userId. Usernames hit GET /users/:username every time
+     *  (bots usually pass userId from an incoming message, so the miss is rare) */
+    private resolvePeerUserId;
+    on<K extends keyof MorokBotEvents>(event: K, listener: MorokBotEvents[K]): this;
+    off<K extends keyof MorokBotEvents>(event: K, listener: MorokBotEvents[K]): this;
+    emit<K extends keyof MorokBotEvents>(event: K, ...args: Parameters<MorokBotEvents[K]>): boolean;
+}
+export {};
+//# sourceMappingURL=bot.d.ts.map

package/dist/bot.d.ts.map

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