morok-bot-sdk 1.0.1

package/dist/types.d.ts

@@ -0,0 +1,254 @@
+/**
+ * Public types. Adding fields is non-breaking, renaming or removing needs a major bump
+ */
+export interface BotConfig {
+    /**
+     * Path to the .morokbot file from the web wizard. Read once at construction,
+     * keys are imported into stateDir on first start and the file is not re-read after that
+     */
+    tokenFile?: string;
+    /**
+     * Where Signal state lives: identity, sessions, prekeys, plus channel-key and group-secret state
+     * Default ./bot-state/, holds private keys after import, so chmod 0700 it
+     * Must be exclusive to one bot. Two processes on one stateDir corrupt each other's state,
+     * the SDK takes a best-effort pid lock but give each bot its own directory
+     */
+    stateDir?: string;
+    /** Default https://app.morok.me. Override for self-host / dev */
+    apiBaseUrl?: string;
+    /** Default derived from apiBaseUrl (http->ws, https->wss, +/ws) */
+    wsUrl?: string;
+    /** Replenish OTPKs when count falls below this, default 100 */
+    replenishThreshold?: number;
+    /** Target OTPK count after replenish, default 200, the server per call cap */
+    replenishTarget?: number;
+    /** Background loop interval in ms, default 5 minutes. 0 disables it,
+     *  which drains the prekey pool in production, so use only in tests */
+    backgroundIntervalMs?: number;
+    /** Pino-shaped logger or anything with info/warn/error/debug. Default is silent */
+    logger?: SdkLogger;
+    /**
+     * If true, call backfillChannelKeys whenever a member joins a group/channel the bot is in,
+     * so a new joiner can read history when the bot is the only online member
+     * Off by default, backfill is expensive on convs with many devices and epochs
+     * Safe to enable, the server filters by joined_secret_version so pre-join history can't leak
+     */
+    autoBackfillOnJoin?: boolean;
+    serveBackfillRequests?: boolean;
+}
+export interface SdkLogger {
+    info: (obj: object, msg?: string) => void;
+    warn: (obj: object, msg?: string) => void;
+    error: (obj: object, msg?: string) => void;
+    debug: (obj: object, msg?: string) => void;
+}
+export interface MorokbotKeyPair {
+    pub: string;
+    priv: string;
+}
+export interface MorokbotSignedPreKey {
+    keyId: number;
+    pub: string;
+    priv: string;
+    signature: string;
+}
+export interface MorokbotOneTimePreKey {
+    keyId: number;
+    pub: string;
+    priv: string;
+}
+export interface MorokbotFile {
+    version: 1;
+    botUserId: number;
+    username: string;
+    token: string;
+    registrationId: number;
+    identityKey: MorokbotKeyPair;
+    /** Account-level cross-signing key. Optional for legacy wizards that pre-date it, new wizards always include it */
+    accountSigningKey?: MorokbotKeyPair;
+    signedPreKey: MorokbotSignedPreKey;
+    oneTimePreKeys: MorokbotOneTimePreKey[];
+}
+/** A user. Resolved lazily on first mention and cached */
+export interface Peer {
+    userId: number;
+    username: string;
+    displayName: string | null;
+}
+/** DIRECT = peer-to-bot DM, GROUP and CHANNEL = channel-key flows. Routes bot.reply to peer or conversation */
+export type ConversationType = 'DIRECT' | 'GROUP' | 'CHANNEL';
+export interface IncomingMessage {
+    /** Persistent server id (messages.id) */
+    messageId: number;
+    conversationId: number;
+    conversationType: ConversationType;
+    sender: Peer;
+    senderDeviceId: number;
+    /** Text body, or the caption that came with an attachment, empty string if none. Always a string */
+    text: string;
+    /** Single-attachment messages. undefined when the message is a gallery (see `gallery` below) or text-only */
+    attachment?: IncomingAttachment;
+    /** Multi-attachment bubble (2-10 items). Mutually exclusive with `attachment` */
+    gallery?: IncomingGallery;
+    /** Sender-stable id shared by every fan-out copy of one logical send. bot.reply threads it through
+     *  so a reply targets the logical message across all device copies */
+    clientMsgId: string | null;
+    replyToId: number | null;
+    threadRootId: number | null;
+    createdAt: Date;
+}
+export interface CommandInvocation extends IncomingMessage {
+    /** Command name without the leading slash */
+    command: string;
+    /** Everything after the command name, trimmed. Empty if none */
+    args: string;
+    /** args split on whitespace */
+    argv: string[];
+}
+export interface BotStartEvent {
+    peer: Peer;
+    startedAt: Date;
+}
+export interface BotStopEvent {
+    peer: Peer;
+    stoppedAt: Date;
+}
+/** Bot was added to a group or channel. By the time the handler fires the SDK has pulled the channel-key copies,
+ *  so an immediate group_message decrypts */
+export interface ConversationAddedEvent {
+    conversationId: number;
+    conversationType: 'GROUP' | 'CHANNEL';
+    /** Title if the group has one, null otherwise */
+    title: string | null;
+    addedAt: Date;
+}
+/** Bot was removed. The SDK drops local state before the handler fires, no further messages decrypt unless re-added */
+export interface ConversationKickedEvent {
+    conversationId: number;
+    /** 'kicked' = admin removed, 'left' = conversation destroyed */
+    reason: 'kicked' | 'left';
+    /** Admin who initiated, if known */
+    actorUserId: number | null;
+    removedAt: Date;
+}
+export interface ReactionEvent {
+    /** Server id of the reactor's fan-out twin of the reacted-to message
+     *  To find which message was reacted to, match clientMsgId below */
+    messageId: number;
+    /** Logical id shared by every fan-out copy of the reacted-to message,
+     *  matching clientMsgId on IncomingMessage and SendResult. null on legacy rows without client_msg_id */
+    clientMsgId: string | null;
+    reactor: Peer;
+    /** Decoded reaction content, any unicode string and not only an emoji
+     *  The bot receives the reaction envelope and decrypts it like a message
+     *  null on a removal or if a group reaction's channel-key has not reached the bot yet */
+    unicode: string | null;
+    /** false = reactor removed their previous reaction */
+    added: boolean;
+}
+export interface DisconnectInfo {
+    reason: 'transport' | 'auth' | 'shutdown';
+    code?: number | string;
+    /** false on shutdown, true otherwise (SDK will reconnect) */
+    willReconnect: boolean;
+}
+export interface BotCommand {
+    command: string;
+    description: string;
+    sortOrder: number;
+}
+export interface BotControl {
+    id: string;
+    label: string;
+    icon?: string;
+    command?: string;
+    children?: BotControl[];
+}
+export interface ControlEvent {
+    controlId: string;
+    sender: Peer;
+    conversationId: number;
+    conversationType: ConversationType;
+}
+/**
+ * Video note shape name, an open string passed to the receiver, which renders the names it knows
+ * and shows circle for anything else. Plain string so a new receiver shape works without an SDK release
+ *
+ * Names the receiver renders: circle, square, slanted, pill, oval, arch, diamond, pentagon, gem, clamShell,
+ * sunny, cookie1, cookie2, cookie3, cookie4, clover1, clover2, burst, softBurst, puffyDiamond, pixelCircle, heart
+ */
+export type VideoNoteShape = string;
+/** One attachment per send. Use SendArgs.attachments for galleries */
+export type AttachmentInput = {
+    kind: 'file';
+    /** Raw bytes. Buffer or Uint8Array */
+    data: Buffer | Uint8Array;
+    /** Filename shown on the receiver's download UI */
+    name: string;
+    /** Mime. Defaults to application/octet-stream */
+    mime?: string;
+} | {
+    kind: 'voice';
+    data: Buffer | Uint8Array;
+    /** Seconds. Receiver clamps to [0.1, 600] (10-min cap for voice notes) */
+    duration: number;
+    /** Up to 64 ints in [0..100] */
+    waveform?: number[];
+    /** Defaults to audio/ogg */
+    mime?: string;
+} | {
+    kind: 'video_note';
+    data: Buffer | Uint8Array;
+    /** Seconds. Receiver clamps to [0.5, 300] (5-min cap for video notes) */
+    duration: number;
+    /** Default 'circle' */
+    shape?: VideoNoteShape;
+    /** Defaults to video/webm */
+    mime?: string;
+};
+/**
+ * Inbound attachment. download() is lazy, bytes hit the network only when called and return decrypted plaintext,
+ * the server never had the key. mime is sender-supplied, treat it as a hint with no security guarantee
+ */
+export interface IncomingAttachment {
+    kind: 'file' | 'voice' | 'video_note';
+    fileId: number;
+    sha256: string;
+    /** Sender-supplied */
+    mime: string;
+    /** Plaintext size in bytes */
+    size: number;
+    /** Filename for 'file'. null for voice / video_note */
+    name: string | null;
+    /** Seconds, present on voice / video_note */
+    duration?: number;
+    /** Peaks 0..100, present on voice */
+    waveform?: number[];
+    /** Present on video_note */
+    shape?: VideoNoteShape;
+    /** Upload-time VT verdict, or null if pending or out of scope. The SDK does not subscribe to live updates */
+    virusTotalVerdict: 'clean' | 'suspicious' | 'malware' | string | null;
+    /** Resolves with plaintext bytes, rejects on 404 / 410 / tamper */
+    download: () => Promise<Buffer>;
+}
+/** One item inside a gallery. Files have a download(), contact and location items just carry metadata */
+export type IncomingGalleryItem = {
+    kind: 'file';
+    attachment: IncomingAttachment;
+} | {
+    kind: 'contact';
+    userId: number;
+    username?: string;
+    displayName?: string;
+    avatarUrl?: string;
+    avatarUnicode?: string;
+} | {
+    kind: 'location';
+    lat: number;
+    lng: number;
+};
+/** 2-10 items in one bubble. Caption (if any) is surfaced on IncomingMessage.text */
+export interface IncomingGallery {
+    items: IncomingGalleryItem[];
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AAKH,MAAM,WAAW,SAAS;IACtB;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAA;IAElB;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAA;IAEjB,iEAAiE;IACjE,UAAU,CAAC,EAAE,MAAM,CAAA;IAEnB,mEAAmE;IACnE,KAAK,CAAC,EAAE,MAAM,CAAA;IAEd,+DAA+D;IAC/D,kBAAkB,CAAC,EAAE,MAAM,CAAA;IAE3B,8EAA8E;IAC9E,eAAe,CAAC,EAAE,MAAM,CAAA;IAExB;2EACuE;IACvE,oBAAoB,CAAC,EAAE,MAAM,CAAA;IAE7B,mFAAmF;IACnF,MAAM,CAAC,EAAE,SAAS,CAAA;IAElB;;;;;OAKG;IACH,kBAAkB,CAAC,EAAE,OAAO,CAAA;IAE5B,qBAAqB,CAAC,EAAE,OAAO,CAAA;CAClC;AAED,MAAM,WAAW,SAAS;IACtB,IAAI,EAAG,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,KAAK,IAAI,CAAA;IAC1C,IAAI,EAAG,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,KAAK,IAAI,CAAA;IAC1C,KAAK,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,KAAK,IAAI,CAAA;IAC1C,KAAK,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,KAAK,IAAI,CAAA;CAC7C;AAKD,MAAM,WAAW,eAAe;IAC5B,GAAG,EAAG,MAAM,CAAA;IACZ,IAAI,EAAE,MAAM,CAAA;CACf;AAED,MAAM,WAAW,oBAAoB;IACjC,KAAK,EAAM,MAAM,CAAA;IACjB,GAAG,EAAQ,MAAM,CAAA;IACjB,IAAI,EAAO,MAAM,CAAA;IACjB,SAAS,EAAE,MAAM,CAAA;CACpB;AAED,MAAM,WAAW,qBAAqB;IAClC,KAAK,EAAE,MAAM,CAAA;IACb,GAAG,EAAI,MAAM,CAAA;IACb,IAAI,EAAG,MAAM,CAAA;CAChB;AAED,MAAM,WAAW,YAAY;IACzB,OAAO,EAAY,CAAC,CAAA;IACpB,SAAS,EAAU,MAAM,CAAA;IACzB,QAAQ,EAAW,MAAM,CAAA;IACzB,KAAK,EAAc,MAAM,CAAA;IACzB,cAAc,EAAK,MAAM,CAAA;IACzB,WAAW,EAAQ,eAAe,CAAA;IAClC,mHAAmH;IACnH,iBAAiB,CAAC,EAAE,eAAe,CAAA;IACnC,YAAY,EAAO,oBAAoB,CAAA;IACvC,cAAc,EAAK,qBAAqB,EAAE,CAAA;CAC7C;AAKD,0DAA0D;AAC1D,MAAM,WAAW,IAAI;IACjB,MAAM,EAAO,MAAM,CAAA;IACnB,QAAQ,EAAK,MAAM,CAAA;IACnB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAA;CAC7B;AAED,+GAA+G;AAC/G,MAAM,MAAM,gBAAgB,GAAG,QAAQ,GAAG,OAAO,GAAG,SAAS,CAAA;AAG7D,MAAM,WAAW,eAAe;IAC5B,yCAAyC;IACzC,SAAS,EAAQ,MAAM,CAAA;IACvB,cAAc,EAAG,MAAM,CAAA;IACvB,gBAAgB,EAAE,gBAAgB,CAAA;IAClC,MAAM,EAAW,IAAI,CAAA;IACrB,cAAc,EAAG,MAAM,CAAA;IACvB,oGAAoG;IACpG,IAAI,EAAa,MAAM,CAAA;IACvB,6GAA6G;IAC7G,UAAU,CAAC,EAAM,kBAAkB,CAAA;IACnC,iFAAiF;IACjF,OAAO,CAAC,EAAS,eAAe,CAAA;IAChC;0EACsE;IACtE,WAAW,EAAM,MAAM,GAAG,IAAI,CAAA;IAC9B,SAAS,EAAQ,MAAM,GAAG,IAAI,CAAA;IAC9B,YAAY,EAAK,MAAM,GAAG,IAAI,CAAA;IAC9B,SAAS,EAAQ,IAAI,CAAA;CACxB;AAED,MAAM,WAAW,iBAAkB,SAAQ,eAAe;IACtD,6CAA6C;IAC7C,OAAO,EAAG,MAAM,CAAA;IAChB,gEAAgE;IAChE,IAAI,EAAM,MAAM,CAAA;IAChB,+BAA+B;IAC/B,IAAI,EAAM,MAAM,EAAE,CAAA;CACrB;AAED,MAAM,WAAW,aAAa;IAC1B,IAAI,EAAO,IAAI,CAAA;IACf,SAAS,EAAE,IAAI,CAAA;CAClB;AAED,MAAM,WAAW,YAAY;IACzB,IAAI,EAAO,IAAI,CAAA;IACf,SAAS,EAAE,IAAI,CAAA;CAClB;AAED;6CAC6C;AAC7C,MAAM,WAAW,sBAAsB;IACnC,cAAc,EAAI,MAAM,CAAA;IACxB,gBAAgB,EAAE,OAAO,GAAG,SAAS,CAAA;IACrC,iDAAiD;IACjD,KAAK,EAAa,MAAM,GAAG,IAAI,CAAA;IAC/B,OAAO,EAAW,IAAI,CAAA;CACzB;AAED,uHAAuH;AACvH,MAAM,WAAW,uBAAuB;IACpC,cAAc,EAAI,MAAM,CAAA;IACxB,gEAAgE;IAChE,MAAM,EAAY,QAAQ,GAAG,MAAM,CAAA;IACnC,oCAAoC;IACpC,WAAW,EAAO,MAAM,GAAG,IAAI,CAAA;IAC/B,SAAS,EAAS,IAAI,CAAA;CACzB;AAED,MAAM,WAAW,aAAa;IAC1B;wEACoE;IACpE,SAAS,EAAK,MAAM,CAAA;IACpB;4GACwG;IACxG,WAAW,EAAG,MAAM,GAAG,IAAI,CAAA;IAC3B,OAAO,EAAO,IAAI,CAAA;IAClB;;6FAEyF;IACzF,OAAO,EAAO,MAAM,GAAG,IAAI,CAAA;IAC3B,sDAAsD;IACtD,KAAK,EAAS,OAAO,CAAA;CACxB;AAED,MAAM,WAAW,cAAc;IAC3B,MAAM,EAAE,WAAW,GAAG,MAAM,GAAG,UAAU,CAAA;IACzC,IAAI,CAAC,EAAG,MAAM,GAAG,MAAM,CAAA;IACvB,6DAA6D;IAC7D,aAAa,EAAE,OAAO,CAAA;CACzB;AAKD,MAAM,WAAW,UAAU;IACvB,OAAO,EAAM,MAAM,CAAA;IACnB,WAAW,EAAE,MAAM,CAAA;IACnB,SAAS,EAAI,MAAM,CAAA;CACtB;AAED,MAAM,WAAW,UAAU;IACvB,EAAE,EAAQ,MAAM,CAAA;IAChB,KAAK,EAAK,MAAM,CAAA;IAChB,IAAI,CAAC,EAAK,MAAM,CAAA;IAChB,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,QAAQ,CAAC,EAAE,UAAU,EAAE,CAAA;CAC1B;AAED,MAAM,WAAW,YAAY;IACzB,SAAS,EAAS,MAAM,CAAA;IACxB,MAAM,EAAY,IAAI,CAAA;IACtB,cAAc,EAAI,MAAM,CAAA;IACxB,gBAAgB,EAAE,gBAAgB,CAAA;CACrC;AAKD;;;;;;GAMG;AACH,MAAM,MAAM,cAAc,GAAG,MAAM,CAAA;AAEnC,sEAAsE;AACtE,MAAM,MAAM,eAAe,GACrB;IACE,IAAI,EAAE,MAAM,CAAA;IACZ,sCAAsC;IACtC,IAAI,EAAE,MAAM,GAAG,UAAU,CAAA;IACzB,mDAAmD;IACnD,IAAI,EAAE,MAAM,CAAA;IACZ,iDAAiD;IACjD,IAAI,CAAC,EAAE,MAAM,CAAA;CAChB,GACC;IACE,IAAI,EAAE,OAAO,CAAA;IACb,IAAI,EAAE,MAAM,GAAG,UAAU,CAAA;IACzB,0EAA0E;IAC1E,QAAQ,EAAE,MAAM,CAAA;IAChB,gCAAgC;IAChC,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAA;IACnB,4BAA4B;IAC5B,IAAI,CAAC,EAAE,MAAM,CAAA;CAChB,GACC;IACE,IAAI,EAAE,YAAY,CAAA;IAClB,IAAI,EAAE,MAAM,GAAG,UAAU,CAAA;IACzB,yEAAyE;IACzE,QAAQ,EAAE,MAAM,CAAA;IAChB,uBAAuB;IACvB,KAAK,CAAC,EAAE,cAAc,CAAA;IACtB,6BAA6B;IAC7B,IAAI,CAAC,EAAE,MAAM,CAAA;CAChB,CAAA;AAGL;;;GAGG;AACH,MAAM,WAAW,kBAAkB;IAC/B,IAAI,EAAM,MAAM,GAAG,OAAO,GAAG,YAAY,CAAA;IACzC,MAAM,EAAI,MAAM,CAAA;IAChB,MAAM,EAAI,MAAM,CAAA;IAChB,sBAAsB;IACtB,IAAI,EAAM,MAAM,CAAA;IAChB,8BAA8B;IAC9B,IAAI,EAAM,MAAM,CAAA;IAChB,uDAAuD;IACvD,IAAI,EAAM,MAAM,GAAG,IAAI,CAAA;IACvB,6CAA6C;IAC7C,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,qCAAqC;IACrC,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAA;IACnB,4BAA4B;IAC5B,KAAK,CAAC,EAAI,cAAc,CAAA;IACxB,6GAA6G;IAC7G,iBAAiB,EAAE,OAAO,GAAG,YAAY,GAAG,SAAS,GAAG,MAAM,GAAG,IAAI,CAAA;IACrE,mEAAmE;IACnE,QAAQ,EAAG,MAAM,OAAO,CAAC,MAAM,CAAC,CAAA;CACnC;AAGD,yGAAyG;AACzG,MAAM,MAAM,mBAAmB,GACzB;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,kBAAkB,CAAA;CAAE,GAChD;IACE,IAAI,EAAE,SAAS,CAAA;IACf,MAAM,EAAE,MAAM,CAAA;IACd,QAAQ,CAAC,EAAK,MAAM,CAAA;IACpB,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,SAAS,CAAC,EAAI,MAAM,CAAA;IACpB,aAAa,CAAC,EAAE,MAAM,CAAA;CACzB,GACC;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,CAAA;AAGpD,qFAAqF;AACrF,MAAM,WAAW,eAAe;IAC5B,KAAK,EAAE,mBAAmB,EAAE,CAAA;CAC/B"}

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "morok-bot-sdk",
+  "version": "1.0.1",
+  "description": "Node.js SDK for building bots on the Morok E2E messaging platform",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "README.ru.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build":     "tsc -p tsconfig.json --declaration false --declarationMap false && tsc -p tsconfig.json --emitDeclarationOnly --removeComments false",
+    "clean":     "rm -rf dist docs-api",
+    "dev":       "tsx watch src/index.ts",
+    "typecheck": "tsc --noEmit",
+    "test":      "vitest run",
+    "test:watch":"vitest",
+    "docs:api":  "typedoc"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "dependencies": {
+    "@privacyresearch/libsignal-protocol-typescript": "^0.0.16",
+    "axios": "^1.15.0",
+    "ws":    "^8.20.0",
+    "zod":   "^3.23.8"
+  },
+  "devDependencies": {
+    "@types/node": "^22.7.4",
+    "@types/ws":   "^8.18.1",
+    "tsx":         "^4.19.2",
+    "typedoc":     "^0.28.0",
+    "typescript":  "^5.9.3",
+    "vitest":      "^2.1.4"
+  },
+  "license": "Apache-2.0",
+  "keywords": ["morok", "bot", "sdk", "e2e", "signal", "messaging", "encryption"],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/geloid/morok-bot-sdk.git"
+  },
+  "homepage": "https://morok.me",
+  "bugs": {
+    "url": "https://github.com/geloid/morok-bot-sdk/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}