@nhtio/rocket-chat-openclaw-integration 0.1.0-master-7f84cdcb

package/index.d.mts

@@ -0,0 +1,751 @@
+import { OpenClawPluginApi } from 'openclaw/plugin-sdk/core';
+import { OpenClawPluginConfigSchema } from 'openclaw/plugin-sdk/core';
+import { PluginRuntime } from 'openclaw/plugin-sdk/core';
+
+/**
+ * Determine whether a prefix command is allowed.
+ *
+ * Risky commands (!model, !stop) require operator authorization.
+ */
+export declare function authorizeCommand(params: {
+    account: ResolvedRocketChatAccount;
+    chatType: RocketChatChatType;
+    sender: RocketChatSender;
+    command: 'status' | 'model' | 'stop';
+}): PolicyDecision;
+
+/**
+ * Decide whether an inbound message is authorized to be processed.
+ *
+ * This is the single top-level policy function for v1.
+ */
+export declare function authorizeInboundMessage(params: {
+    account: ResolvedRocketChatAccount;
+    chatType: RocketChatChatType;
+    roomId: string;
+    sender: RocketChatSender;
+    text: string;
+}): PolicyDecision;
+
+/**
+ * Build a REST request for Rocket.Chat `GET /api/v1/me`.
+ */
+export declare function buildMeRequest(params: RocketChatMeParams): RocketChatMeRequest;
+
+/**
+ * Build a REST request for Rocket.Chat `chat.postMessage`.
+ *
+ * Reference: https://developer.rocket.chat/reference/api/rest-api/endpoints/messaging/chat-endpoints/postmessage
+ */
+export declare function buildPostMessageRequest(params: RocketChatPostMessageParams): RocketChatPostMessageRequest;
+
+/**
+ * Build a REST request for Rocket.Chat `chat.react`.
+ *
+ * Reference: https://developer.rocket.chat/apidocs/react-to-message
+ */
+export declare function buildReactRequest(params: RocketChatReactParams): RocketChatReactRequest;
+
+/**
+ * Determine chat type for a room.
+ *
+ * v1: this is config-driven. The caller can supply an explicit room type map.
+ */
+export declare function classifyChatType(params: {
+    roomId: string;
+    roomTypeById?: Record<string, RocketChatChatType>;
+}): RocketChatChatType;
+
+/**
+ * Compute the canonical conversation ids for OpenClaw session grammar.
+ */
+export declare function computeSessionConversation(params: {
+    roomId: string;
+    threadId?: string;
+}): RocketChatSessionConversation;
+
+/**
+ * Options for periodic credential revalidation.
+ */
+export declare interface CredentialRevalidationOptions {
+    /** Revalidation cadence in milliseconds. */
+    intervalMs: number;
+}
+
+/** DDP connect frame. */
+export declare interface DdpConnectFrame {
+    msg: 'connect';
+    version: '1';
+    support: ['1'];
+}
+
+/**
+ * Log in using a resume token.
+ *
+ * In v1 we treat the Rocket.Chat PAT as the resume token for DDP login.
+ */
+export declare function ddpLoginWithResume(params: {
+    ddp: DdpMethodClient;
+    resumeToken: string;
+}): Promise<unknown>;
+
+/**
+ * Correlates DDP method calls with result frames.
+ */
+export declare class DdpMethodClient {
+    private readonly transport;
+    private nextId;
+    private pending;
+    constructor(transport: DdpTransport);
+    /**
+     * Call a DDP method.
+     */
+    call(method: string, params?: unknown[]): Promise<unknown>;
+}
+
+export declare interface DdpMethodFrame {
+    msg: 'method';
+    method: string;
+    id: string;
+    params?: unknown[];
+}
+
+/** DDP ping frame. */
+export declare interface DdpPingFrame {
+    msg: 'ping';
+}
+
+/** DDP pong frame. */
+export declare interface DdpPongFrame {
+    msg: 'pong';
+}
+
+export declare interface DdpReadyFrame {
+    msg: 'ready';
+    subs: string[];
+}
+
+export declare interface DdpResultFrame {
+    msg: 'result';
+    id: string;
+    result?: unknown;
+    error?: unknown;
+}
+
+export declare interface DdpSubFrame {
+    msg: 'sub';
+    id: string;
+    name: string;
+    params: unknown[];
+}
+
+/**
+ * Minimal subscription client.
+ */
+export declare class DdpSubscriptionClient {
+    private readonly transport;
+    private nextId;
+    constructor(transport: DdpTransport);
+    /**
+     * Subscribe to a DDP stream.
+     *
+     * Resolves once the server acknowledges the subscription via a `ready` frame.
+     */
+    subscribe(name: string, params: unknown[]): Promise<{
+        subId: string;
+    }>;
+    /**
+     * Subscribe to the stream of room messages.
+     */
+    subscribeRoomMessages(roomId: string): Promise<{
+        subId: string;
+    }>;
+}
+
+/**
+ * A minimal transport interface for Rocket.Chat DDP.
+ *
+ * This abstraction keeps DDP protocol logic unit-testable without a real WebSocket.
+ */
+export declare interface DdpTransport {
+    /**
+     * Register a callback for incoming DDP frames.
+     *
+     * The callback MUST be invoked for every parsed JSON frame.
+     */
+    onMessage(cb: (msg: unknown) => void): void;
+    /**
+     * Register a callback invoked when the underlying transport closes.
+     */
+    onClose(cb: (info?: {
+        code?: number;
+        reason?: string;
+    }) => void): void;
+    /**
+     * Send a JSON-serializable frame.
+     */
+    send(msg: unknown): void;
+    /**
+     * Close the underlying transport.
+     */
+    close(info?: {
+        code?: number;
+        reason?: string;
+    }): void;
+}
+
+/**
+ * Decode a `stream-room-messages` event payload into a normalized message shape.
+ *
+ * We support a couple of common payload shapes:
+ * - direct message object
+ * - DDP changed envelope with fields.args[0] = message
+ */
+export declare function decodeRoomMessageEvent(raw: unknown): {
+    roomId: string;
+    messageId: string;
+    text: string;
+    sender: RocketChatSender;
+    threadId?: string;
+} | null;
+
+/**
+ * OpenClaw Rocket.Chat channel plugin entrypoint.
+ *
+ * This is a packaging skeleton only.
+ * - No Rocket.Chat networking is implemented yet.
+ * - The plugin exists so OpenClaw can discover/install the package as a channel plugin.
+ */
+declare const _default: {
+    id: string;
+    name: string;
+    description: string;
+    configSchema: OpenClawPluginConfigSchema;
+    register: (api: OpenClawPluginApi) => void;
+    channelPlugin: never;
+    setChannelRuntime?: (runtime: PluginRuntime) => void;
+};
+export default _default;
+
+/**
+ * Default DM policy for Rocket.Chat.
+ *
+ * v1 default is `pairing` (Slack-aligned).
+ */
+export declare const DEFAULT_DM_POLICY: RocketChatDmPolicy;
+
+/**
+ * Default group policy for Rocket.Chat.
+ *
+ * v1 default is `allowlist` (fail closed).
+ */
+export declare const DEFAULT_GROUP_POLICY: RocketChatGroupPolicy;
+
+/**
+ * Default setting for mention gating in group chats.
+ */
+export declare const DEFAULT_REQUIRE_MENTION = true;
+
+/**
+ * Map a parsed Rocket.Chat prefix command into an OpenClaw command message.
+ */
+export declare function dispatchPrefixCommand(params: {
+    account: ResolvedRocketChatAccount;
+    chatType: RocketChatChatType;
+    sender: RocketChatSender;
+    parsed: RocketChatPrefixCommand;
+}): RocketChatCommandDispatch;
+
+/**
+ * A deterministic in-memory transport for unit testing DDP protocol logic.
+ */
+export declare class FakeDdpTransport implements DdpTransport {
+    private messageHandlers;
+    private closeHandlers;
+    /** Outbound frames sent by the client. */
+    readonly sent: unknown[];
+    /** Whether close() has been called. */
+    closed: boolean;
+    onMessage(cb: (msg: unknown) => void): void;
+    onClose(cb: (info?: {
+        code?: number;
+        reason?: string;
+    }) => void): void;
+    send(msg: unknown): void;
+    close(info?: {
+        code?: number;
+        reason?: string;
+    }): void;
+    /**
+     * Inject an inbound message as if it arrived from Rocket.Chat.
+     */
+    inject(msg: unknown): void;
+}
+
+/**
+ * Validate current credentials by calling Rocket.Chat `GET /api/v1/me`.
+ */
+export declare function getMe(params: RocketChatMeParams & {
+    fetcher?: (input: string, init?: RequestInit) => Promise<Response>;
+}): Promise<unknown>;
+
+/**
+ * Result of attempting to normalize an inbound message.
+ */
+export declare type InboundNormalizeResult = {
+    ok: true;
+    value: RocketChatInboundMessage;
+} | {
+    ok: false;
+    reason: string;
+};
+
+/**
+ * Install baseline protocol handlers.
+ *
+ * Responsibilities:
+ * - send initial connect
+ * - respond to ping with pong
+ */
+export declare function installDdpProtocol(params: {
+    transport: DdpTransport;
+}): {
+    sendConnect: () => void;
+};
+
+/**
+ * Create the initial DDP connect frame.
+ */
+export declare function makeConnectFrame(): DdpConnectFrame;
+
+/**
+ * Parse Rocket.Chat prefix commands.
+ *
+ * Rules:
+ * - Only treat as command if the trimmed message begins with '!'.
+ * - Commands supported: !status, !stop, !model <name>
+ */
+export declare function parsePrefixCommand(text: string): RocketChatPrefixCommand;
+
+/**
+ * The result of applying policy checks to an inbound message.
+ */
+export declare interface PolicyDecision {
+    allowed: boolean;
+    reason?: string;
+}
+
+/**
+ * Post a message using Rocket.Chat REST API.
+ *
+ * This function accepts an optional fetch implementation to keep unit tests deterministic.
+ */
+export declare function postMessage(params: RocketChatPostMessageParams & {
+    fetcher?: (input: string, init?: RequestInit) => Promise<Response>;
+}): Promise<unknown>;
+
+/**
+ * Normalize, classify, and authorize an inbound Rocket.Chat message event.
+ */
+export declare function processInboundRoomMessage(params: {
+    account: ResolvedRocketChatAccount;
+    rawEvent: unknown;
+    roomTypeById?: Record<string, 'direct' | 'group'>;
+}): InboundNormalizeResult;
+
+/**
+ * Set or unset a reaction using Rocket.Chat REST API.
+ */
+export declare function reactToMessage(params: RocketChatReactParams & {
+    fetcher?: (input: string, init?: RequestInit) => Promise<Response>;
+}): Promise<unknown>;
+
+/**
+ * Compute the effective channel config.
+ *
+ * This applies defaults, but does not validate credentials.
+ */
+export declare function resolveChannelDefaults(cfg: RocketChatChannelConfig | undefined): Required<Pick<RocketChatChannelConfig, 'dmPolicy' | 'groupPolicy'>> & RocketChatChannelConfig;
+
+/**
+ * Resolved account config for a specific OpenClaw agent id.
+ */
+export declare interface ResolvedRocketChatAccount {
+    /** OpenClaw agent id / account id key. */
+    accountId: string;
+    /** Whether this account is enabled after all merges. */
+    enabled: boolean;
+    /** Rocket.Chat server base URL (https://...). */
+    serverUrl: string;
+    /** Rocket.Chat bot user id. */
+    userId: string;
+    /** Rocket.Chat bot username (for mention gating). */
+    username: string;
+    /** Rocket.Chat personal access token. */
+    pat: string;
+    /** Effective DM policy. */
+    dmPolicy: NonNullable<RocketChatChannelConfig['dmPolicy']>;
+    /** Effective group policy. */
+    groupPolicy: NonNullable<RocketChatChannelConfig['groupPolicy']>;
+    /** Effective sender allowlist. */
+    allowFrom: string[];
+    /** Effective operator allowlist for risky commands. */
+    commandAllowFrom: string[];
+    /** Effective per-room config. */
+    rooms: Record<string, RocketChatRoomConfig>;
+    /** Default mention gating for group chats when room override is not present. */
+    defaultRequireMention: boolean;
+}
+
+/**
+ * Resolve the effective Rocket.Chat account configuration for a given agent id.
+ *
+ * Merging rules:
+ * - Top-level `channels.rocketchat` is the base.
+ * - `channels.rocketchat.accounts[accountId]` overrides base.
+ *
+ * Validation rules:
+ * - If the merged account is enabled, it must have: serverUrl, userId, username, pat.
+ */
+export declare function resolveRocketChatAccount(params: {
+    cfg: RocketChatOpenClawConfig;
+    accountId: string;
+}): ResolvedRocketChatAccount;
+
+/**
+ * Close the transport immediately when we determine the account is unauthorized.
+ *
+ * v1 spec requirement:
+ * - On any auth error/unauthorized response on the WebSocket (or any REST call),
+ *   the plugin MUST immediately close the WebSocket and stop processing events
+ *   for that account.
+ */
+export declare function revokeOnUnauthorized(params: {
+    transport: DdpTransport;
+    reason: string;
+}): void;
+
+/**
+ * Per-account Rocket.Chat credentials and overrides.
+ */
+export declare interface RocketChatAccountConfig {
+    /** Enable/disable this account. */
+    enabled?: boolean;
+    /** Rocket.Chat server base URL (must be https:// for production). */
+    serverUrl?: string;
+    /** Rocket.Chat user id for the bot account. */
+    userId?: string;
+    /** Rocket.Chat username for the bot account (used for mention gating). */
+    username?: string;
+    /**
+     * Rocket.Chat personal access token.
+     *
+     * Treated as a credential equivalent to a password.
+     */
+    pat?: string;
+    /** DM access policy override for this account. */
+    dmPolicy?: RocketChatDmPolicy;
+    /** Group chat access policy override for this account. */
+    groupPolicy?: RocketChatGroupPolicy;
+    /** Sender allowlist override for this account. */
+    allowFrom?: string[];
+    /** Operator allowlist override for this account (for !model / !stop). */
+    commandAllowFrom?: string[];
+    /** Room allowlist override for this account. */
+    rooms?: Record<string, RocketChatRoomConfig>;
+}
+
+/**
+ * Top-level channel config under `channels.rocketchat`.
+ */
+export declare interface RocketChatChannelConfig {
+    /** Globally enable/disable the channel plugin. */
+    enabled?: boolean;
+    /** Default Rocket.Chat server base URL (https://...). */
+    serverUrl?: string;
+    /** Default DM policy (v1 default is pairing). */
+    dmPolicy?: RocketChatDmPolicy;
+    /** Default group policy (v1 default is allowlist). */
+    groupPolicy?: RocketChatGroupPolicy;
+    /** Global allowlist of senders permitted to interact. */
+    allowFrom?: string[];
+    /** Global operator allowlist for !model/!stop. */
+    commandAllowFrom?: string[];
+    /** Per-room allowlists and mention gating overrides. */
+    rooms?: Record<string, RocketChatRoomConfig>;
+    /** Per-account config keyed by OpenClaw agent id. */
+    accounts?: Record<string, RocketChatAccountConfig>;
+}
+
+/**
+ * Chat type classification used by the Rocket.Chat channel plugin.
+ *
+ * - `direct`: 1:1 DM
+ * - `group`: any multi-user room (public channel or private group)
+ */
+export declare type RocketChatChatType = 'direct' | 'group';
+
+/**
+ * Minimal Rocket.Chat client used by the OpenClaw channel plugin.
+ *
+ * v1 scope:
+ * - DDP connect + ping/pong
+ * - DDP login using resume token (PAT)
+ * - subscribe to stream-room-messages
+ *
+ * This class is intentionally transport-agnostic so it can be unit-tested.
+ */
+export declare class RocketChatClient {
+    private readonly ddp;
+    private readonly subs;
+    private readonly protocol;
+    constructor(transport: DdpTransport);
+    /**
+     * Start the DDP session by sending the connect frame.
+     */
+    connect(): void;
+    /**
+     * Authenticate the DDP session.
+     */
+    loginWithResume(resumeToken: string): Promise<void>;
+    /**
+     * Subscribe to inbound room message streams for the provided rooms.
+     */
+    subscribeRoomMessages(roomIds: string[]): Promise<void>;
+    /**
+     * Convenience helper for the common connect/login/subscribe sequence.
+     */
+    start(params: {
+        resumeToken: string;
+        roomIds: string[];
+    }): Promise<void>;
+}
+
+/**
+ * Normalized command dispatch instruction.
+ */
+export declare type RocketChatCommandDispatch = {
+    ok: true;
+    kind: 'openclaw-command';
+    commandText: string;
+} | {
+    ok: false;
+    reason: string;
+};
+
+/**
+ * Supported DM access policies.
+ *
+ * This mirrors the Slack-style semantics referenced in the project spec:
+ * - `pairing`: requires pairing approval for new DM contacts (v1 may stub the pairing flow).
+ * - `allowlist`: only allowlisted users may DM.
+ * - `open`: allow any DM sender (still subject to safety controls; requires explicit allowlist `"*"`).
+ * - `disabled`: no DMs are processed.
+ */
+export declare type RocketChatDmPolicy = 'pairing' | 'allowlist' | 'open' | 'disabled';
+
+/**
+ * Supported group chat policies.
+ *
+ * Group chat = any multi-user room (public channels + private groups).
+ */
+export declare type RocketChatGroupPolicy = 'open' | 'allowlist' | 'disabled';
+
+/**
+ * Normalized inbound message event.
+ */
+export declare interface RocketChatInboundMessage {
+    /** Rocket.Chat room id. */
+    roomId: string;
+    /** Rocket.Chat message id. */
+    messageId: string;
+    /** Message text. */
+    text: string;
+    /** Sender identity. */
+    sender: RocketChatSender;
+    /** Chat type (DM vs group). */
+    chatType: RocketChatChatType;
+    /** Optional thread id when the message belongs to a thread. */
+    threadId?: string;
+}
+
+export declare interface RocketChatMeParams {
+    serverUrl: string;
+    userId: string;
+    authToken: string;
+}
+
+export declare interface RocketChatMeRequest {
+    url: string;
+    method: 'GET';
+    headers: Record<string, string>;
+}
+
+/**
+ * Minimal OpenClaw config shape needed by this library.
+ *
+ * We intentionally avoid importing OpenClaw config types directly in v1 so this
+ * package can be unit-tested without binding to OpenClaw internal type shapes.
+ */
+export declare interface RocketChatOpenClawConfig {
+    channels?: {
+        rocketchat?: RocketChatChannelConfig;
+    };
+}
+
+export declare interface RocketChatPostMessageParams {
+    /** Rocket.Chat base server URL, for example https://chat.example.com */
+    serverUrl: string;
+    /** Rocket.Chat user id for auth. */
+    userId: string;
+    /** Rocket.Chat personal access token for auth. */
+    authToken: string;
+    /** Room id to post into. */
+    roomId: string;
+    /** Message text. */
+    text: string;
+    /** Optional thread message id (Rocket.Chat tmid). */
+    threadId?: string;
+}
+
+export declare interface RocketChatPostMessageRequest {
+    url: string;
+    method: 'POST';
+    headers: Record<string, string>;
+    body: string;
+}
+
+export declare type RocketChatPrefixCommand = {
+    kind: 'command';
+    name: 'status';
+    raw: string;
+} | {
+    kind: 'command';
+    name: 'stop';
+    raw: string;
+} | {
+    kind: 'command';
+    name: 'model';
+    raw: string;
+    model: string;
+} | {
+    kind: 'not-a-command';
+};
+
+export declare type RocketChatPrefixCommandName = 'status' | 'model' | 'stop';
+
+export declare interface RocketChatReactParams {
+    /** Rocket.Chat base server URL, for example https://chat.example.com */
+    serverUrl: string;
+    /** Rocket.Chat user id for auth. */
+    userId: string;
+    /** Rocket.Chat personal access token for auth. */
+    authToken: string;
+    /** Message id to react to. */
+    messageId: string;
+    /** Emoji name (without surrounding colons), e.g. "smile". */
+    emoji: string;
+    /** Whether to add or remove the reaction. */
+    shouldReact: boolean;
+}
+
+export declare interface RocketChatReactRequest {
+    url: string;
+    method: 'POST';
+    headers: Record<string, string>;
+    body: string;
+}
+
+/**
+ * Per-room configuration.
+ */
+export declare interface RocketChatRoomConfig {
+    /**
+     * Optional allowlist of Rocket.Chat user identifiers allowed to interact in this room.
+     *
+     * When omitted, the account/global allowlists are used.
+     */
+    users?: string[];
+    /**
+     * Override for mention gating in this room.
+     *
+     * When true, group chat messages must include `@<botUsername>` to be processed.
+     */
+    requireMention?: boolean;
+}
+
+/**
+ * Normalized sender identity.
+ *
+ * We keep this intentionally minimal so it can map to multiple Rocket.Chat payload shapes.
+ */
+export declare interface RocketChatSender {
+    /** Rocket.Chat user id. */
+    id: string;
+    /** Rocket.Chat username (without @). */
+    username?: string;
+}
+
+/**
+ * Rocket.Chat session key components.
+ */
+export declare interface RocketChatSessionConversation {
+    /** Base conversation id (room). */
+    baseConversationId: string;
+    /** Optional thread id (when replying in a thread). */
+    threadId?: string;
+}
+
+/**
+ * Factory for creating a transport per account.
+ */
+export declare type RocketChatTransportFactory = (params: {
+    account: ResolvedRocketChatAccount;
+}) => DdpTransport;
+
+/**
+ * Start a periodic credential revalidation loop.
+ *
+ * This provides a bound on worst-case revocation latency for long-lived sessions.
+ * v1 target: <= 5 minutes.
+ */
+export declare function startCredentialRevalidation(params: {
+    transport: DdpTransport;
+    validateOnce: () => Promise<{
+        ok: true;
+    } | {
+        ok: false;
+        reason: string;
+    }>;
+    options: CredentialRevalidationOptions;
+}): {
+    stop: () => void;
+};
+
+/**
+ * Start (connect/login/subscribe) a Rocket.Chat client for a single account.
+ *
+ * v1 security requirements:
+ * - periodic credential revalidation to bound revocation latency
+ */
+export declare function startRocketChatAccount(params: {
+    account: ResolvedRocketChatAccount;
+    roomIds: string[];
+    createTransport: RocketChatTransportFactory;
+    /** Override credential revalidation cadence. Default is 5 minutes. */
+    revalidateIntervalMs?: number;
+    /** Optional fetch injection for credential validation. */
+    fetcher?: (input: string, init?: RequestInit) => Promise<Response>;
+}): Promise<{
+    client: RocketChatClient;
+    stop: () => void;
+}>;
+
+/**
+ * The current version of the package.
+ *
+ * @tip This constant is replaced during the build process with the actual version of the package.
+ */
+export declare const version: string;
+
+export { }