@excitedjs/feishu-transport 0.0.1

package/dist/transport/connection.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Pure log-line builders for the Feishu WebSocket connection lifecycle.
+ *
+ * `createFeishuTransport` wires the SDK's connection callbacks to these, so a
+ * dropped or failed connection is always surfaced on the host's stderr instead
+ * of disappearing into the SDK's reconnect loop. The wording lives here — pure
+ * and free of any SDK dependency — so it is unit-testable. Ported verbatim from
+ * claudemux.
+ */
+/** The connection dropped and the SDK has begun a reconnect cycle. */
+export declare function reconnectingLogLine(): string;
+/** The reconnect cycle restored the connection. */
+export declare function reconnectedLogLine(): string;
+/**
+ * The SDK reported a connection error and stopped — a non-recoverable error,
+ * or an exhausted retry budget. The channel needs a restart to reconnect.
+ */
+export declare function connectionErrorLogLine(err: unknown): string;
+/**
+ * The initial connection never came up within the startup grace window.
+ * `sdkGaveUp` is true when the SDK has already stopped retrying on its own,
+ * false when it is still looping and the channel is the one stopping it.
+ */
+export declare function startupTimeoutLogLine(graceMs: number, sdkGaveUp: boolean): string;
+//# sourceMappingURL=connection.d.ts.map

package/dist/transport/connection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"connection.d.ts","sourceRoot":"","sources":["../../src/transport/connection.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAOH,sEAAsE;AACtE,wBAAgB,mBAAmB,IAAI,MAAM,CAE5C;AAED,mDAAmD;AACnD,wBAAgB,kBAAkB,IAAI,MAAM,CAE3C;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,CAE3D;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,OAAO,GAAG,MAAM,CASjF"}

package/dist/transport/connection.js

@@ -0,0 +1,42 @@
+/**
+ * Pure log-line builders for the Feishu WebSocket connection lifecycle.
+ *
+ * `createFeishuTransport` wires the SDK's connection callbacks to these, so a
+ * dropped or failed connection is always surfaced on the host's stderr instead
+ * of disappearing into the SDK's reconnect loop. The wording lives here — pure
+ * and free of any SDK dependency — so it is unit-testable. Ported verbatim from
+ * claudemux.
+ */
+/** Extract a human-readable detail from an unknown thrown value. */
+function detail(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+/** The connection dropped and the SDK has begun a reconnect cycle. */
+export function reconnectingLogLine() {
+    return 'Feishu connection lost — the SDK is reconnecting.';
+}
+/** The reconnect cycle restored the connection. */
+export function reconnectedLogLine() {
+    return 'Feishu connection re-established.';
+}
+/**
+ * The SDK reported a connection error and stopped — a non-recoverable error,
+ * or an exhausted retry budget. The channel needs a restart to reconnect.
+ */
+export function connectionErrorLogLine(err) {
+    return `Feishu connection failed and the SDK stopped retrying: ${detail(err)}`;
+}
+/**
+ * The initial connection never came up within the startup grace window.
+ * `sdkGaveUp` is true when the SDK has already stopped retrying on its own,
+ * false when it is still looping and the channel is the one stopping it.
+ */
+export function startupTimeoutLogLine(graceMs, sdkGaveUp) {
+    const secs = Math.round(graceMs / 1000);
+    const tail = sdkGaveUp
+        ? 'the SDK has stopped retrying'
+        : 'stopping the connection attempt so it does not retry in a tight loop';
+    return (`Feishu connection did not come up within ${secs}s of startup; ${tail}. ` +
+        'Inbound events will not arrive until the channel is restarted.');
+}
+//# sourceMappingURL=connection.js.map

package/dist/transport/connection.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"connection.js","sourceRoot":"","sources":["../../src/transport/connection.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,oEAAoE;AACpE,SAAS,MAAM,CAAC,GAAY;IAC1B,OAAO,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAA;AACzD,CAAC;AAED,sEAAsE;AACtE,MAAM,UAAU,mBAAmB;IACjC,OAAO,mDAAmD,CAAA;AAC5D,CAAC;AAED,mDAAmD;AACnD,MAAM,UAAU,kBAAkB;IAChC,OAAO,mCAAmC,CAAA;AAC5C,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,sBAAsB,CAAC,GAAY;IACjD,OAAO,0DAA0D,MAAM,CAAC,GAAG,CAAC,EAAE,CAAA;AAChF,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,qBAAqB,CAAC,OAAe,EAAE,SAAkB;IACvE,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,GAAG,IAAI,CAAC,CAAA;IACvC,MAAM,IAAI,GAAG,SAAS;QACpB,CAAC,CAAC,8BAA8B;QAChC,CAAC,CAAC,sEAAsE,CAAA;IAC1E,OAAO,CACL,4CAA4C,IAAI,iBAAiB,IAAI,IAAI;QACzE,gEAAgE,CACjE,CAAA;AACH,CAAC"}

package/dist/transport/feishu.d.ts

@@ -0,0 +1,222 @@
+/**
+ * The Feishu platform boundary — the only module in the workspace that imports
+ * the Feishu SDK.
+ *
+ * Everything that talks to Feishu — the inbound long-lived WebSocket and the
+ * outbound message API — sits behind the `FeishuTransport` interface. A host
+ * depends only on that interface, so its wiring can be exercised against an
+ * injected fake with no live connection.
+ *
+ * The transport is event-type agnostic. `start` is handed a route table mapping
+ * each Feishu event_type to a callback and registers every entry with the SDK's
+ * event dispatcher; decoding a specific event's payload is the job of that
+ * event's handler (see `../parse`), not this module. Adding a new event type to
+ * a host therefore never touches this file.
+ *
+ * Cross-process single-instance election is intentionally **not** here. dreamux
+ * gives each dispatcher its own bot identity (election is moot), and claudemux
+ * wraps this transport with its own elected-transport layer. Core opens the
+ * inbound WebSocket directly; whether exactly one process may do so is the
+ * host's concern, layered on top. (claudemux#155 §二 / dreamux#25 §7.2.)
+ *
+ * Ported from claudemux's `feishu-channel/src/feishu.ts` (the source of truth),
+ * with the instance-lock removed, `sendText` upgraded to the structured
+ * `send(OutboundTarget, …)` contract, and `botOpenId` renamed to `selfId`.
+ */
+import * as lark from '@larksuiteoapi/node-sdk';
+import type { OutboundTarget } from '../contract/outbound.js';
+/** Outcome of an outbound send. */
+export interface FeishuSendResult {
+    /**
+     * message_ids of every card the send produced, in order. A Markdown body
+     * that fits one card produces one entry; a longer body that the renderer
+     * split over several cards produces several. Empty when Feishu omitted the
+     * message_ids.
+     */
+    messageIds: string[];
+}
+/**
+ * Build the `content` string for a Feishu plain-text message — the legacy
+ * `msg_type: 'text'` payload, used by `editText`'s fallback path so an edit
+ * on a message that was sent before this channel switched to interactive
+ * cards still works.
+ */
+export declare function textMessageContent(text: string): string;
+/**
+ * Safe ceiling for the serialised card `content` string. Stays a few hundred
+ * bytes below the documented 30 KB request-body limit so HTTP headers and the
+ * `{ params, data: { receive_id, msg_type, content } }` envelope still fit.
+ */
+export declare const FEISHU_CARD_CONTENT_SAFE_BYTES: number;
+/** One reply within a fetched document-comment thread. */
+export interface FeishuDocCommentReply {
+    /** reply_id of this reply; `''` when Feishu omitted it. */
+    replyId: string;
+    /** open_id of the reply's author. */
+    authorId: string;
+    /** Raw Feishu rich-content elements of the reply body, rendered by the handler. */
+    elements: unknown[];
+}
+/**
+ * A document comment and its reply thread, fetched to enrich a comment event.
+ *
+ * The `drive.notice.comment_add_v1` payload carries only the comment's ids, so
+ * the comment text is fetched separately — this is the fetched result.
+ */
+export interface FeishuDocComment {
+    /** False for a comment anchored to a text selection; `quote` then holds it. */
+    isWhole: boolean;
+    /** The selected text a local-selection comment is anchored to; `''` otherwise. */
+    quote: string;
+    /** The comment's replies, oldest first. */
+    replies: FeishuDocCommentReply[];
+}
+/** A document's human-readable identity, fetched to render a comment event. */
+export interface FeishuDocMeta {
+    /** Document title. */
+    title: string;
+    /** Browser URL of the document. */
+    url: string;
+}
+/**
+ * One comment as `drive.v1.fileComment.batchQuery` returns it — only the
+ * fields the channel reads. The SDK's response type carries more; this is the
+ * structural subset `commentFromBatchQuery` decodes, and the shape a unit
+ * test builds a fixture against.
+ */
+interface RawCommentItem {
+    comment_id?: string;
+    is_whole?: boolean;
+    quote?: string;
+    reply_list?: {
+        replies?: Array<{
+            reply_id?: string;
+            user_id?: string;
+            content?: {
+                elements?: unknown[];
+            };
+        }>;
+    };
+}
+/**
+ * Pick the comment with `commentId` out of a `fileComment.batchQuery` response
+ * and shape it into a `FeishuDocComment`. Returns `null` when the response
+ * carried no such comment. Pure: no I/O, never throws — exported so the decode
+ * is unit-tested without a live Feishu connection.
+ */
+export declare function commentFromBatchQuery(items: RawCommentItem[], commentId: string): FeishuDocComment | null;
+/**
+ * A single inbound-event route handler. Receives the raw event payload exactly
+ * as the Feishu SDK delivered it; decoding it is the handler's job (`../parse`).
+ *
+ * Deferred-ACK invariant (claudemux#155 §七.3 / dreamux#25 §7.3): the Feishu SDK
+ * sends the platform ACK frame only **after** this promise resolves. The
+ * returned promise MUST therefore resolve only once the message is durable in
+ * the host (dreamux: the SQLite `enqueueInbound` INSERT; claudemux: the inbox
+ * tmp+rename). Returning before durability — or returning a non-promise — would
+ * ACK an unpersisted message and lose it on a crash. The type is
+ * `=> Promise<void>`, not `=> void | Promise<void>`, precisely to keep that
+ * gate from being bypassed by a synchronous handler.
+ */
+export type RouteHandler = (raw: unknown) => Promise<void>;
+/**
+ * Inbound event routes: Feishu event_type → handler. A host builds this from
+ * its event registry; the transport registers every entry with the SDK's event
+ * dispatcher.
+ */
+export type InboundRoutes = Record<string, RouteHandler>;
+/**
+ * The platform boundary a host depends on. The real implementation
+ * (`createFeishuTransport`) wraps the Feishu SDK; tests inject a fake so the
+ * inbound and outbound wiring runs without a live Feishu connection.
+ */
+export interface FeishuTransport {
+    /** The app id this transport was created with. */
+    readonly appId: string;
+    /**
+     * open_id of the bot itself, for group mention-gating. `undefined` until
+     * `start` has resolved it (and stays `undefined` if resolution failed).
+     */
+    readonly selfId: string | undefined;
+    /**
+     * Open the inbound WebSocket and dispatch every subscribed event_type through
+     * `routes`. Core opens the connection directly — single-instance election, if
+     * a deployment needs it, is layered on top by the host. **Rejects** if the
+     * connection does not come up within the startup grace window, so a host can
+     * fail a dispatcher loudly instead of registering a silently-dark bot.
+     */
+    start(routes: InboundRoutes): Promise<void>;
+    /**
+     * Send a text message to the target chat. Routed by `chat_id`, never by a
+     * message_id, so a forged reply target cannot redirect the message into an
+     * unrelated conversation.
+     *
+     * PR1 reads only `target.chatId` (behavior-identical to the old
+     * `sendText(chatId, text)`). Honoring `target.replyToMessageId` (reply-threading
+     * via `im.message.reply`) and `target.mentionUserIds` (auto @-back) lands in
+     * dreamux#25 PR2 (gap ④), with its own tests; `target.conversationKey` is a
+     * channel-layer routing hint the transport never reads.
+     */
+    send(target: OutboundTarget, text: string): Promise<FeishuSendResult>;
+    /**
+     * Add an emoji reaction to a message and return the reaction_id Feishu
+     * assigned. That id is what `removeReaction` needs to take the same reaction
+     * back off; Feishu can omit it, in which case an empty string is returned.
+     */
+    addReaction(messageId: string, emoji: string): Promise<string>;
+    /**
+     * Remove a reaction from a message, identified by the reaction_id that
+     * `addReaction` returned. Feishu only lets the app that added a reaction
+     * remove it, so this is always paired with a prior `addReaction` from the
+     * same channel.
+     */
+    removeReaction(messageId: string, reactionId: string): Promise<void>;
+    /** Replace the text of a message the bot previously sent. */
+    editText(messageId: string, text: string): Promise<void>;
+    /**
+     * Fetch one document comment and its reply thread. The comment-add event
+     * payload carries no comment text, so the doc-comment handler calls this to
+     * fill it in. Best-effort: returns `null` for a file type with no comment
+     * API or on any API failure, and never throws — a failure degrades the
+     * notification rather than dropping the event.
+     */
+    fetchDocComment(fileToken: string, fileType: string, commentId: string): Promise<FeishuDocComment | null>;
+    /**
+     * Fetch a document's title and URL, so a comment notification names the
+     * document a human would recognize. Best-effort: returns `null` for a file
+     * type with no metadata API or on any API failure, and never throws.
+     */
+    fetchDocMeta(fileToken: string, fileType: string): Promise<FeishuDocMeta | null>;
+    /** Close the connection and release every resource it holds. */
+    close(): Promise<void>;
+}
+/** Feishu self-built-app credentials. */
+export interface FeishuCredentials {
+    appId: string;
+    appSecret: string;
+}
+/**
+ * Optional knobs for `createFeishuTransport`. The `client` seam lets unit
+ * tests inject a stub of just the SDK methods this module touches, so the
+ * outbound paths (`send`, `editText`, the doc-comment fetchers) are covered
+ * without a live Feishu app.
+ */
+export interface FeishuTransportOptions {
+    /**
+     * SDK client to use for outbound API calls. Default: a fresh `lark.Client`
+     * built from `creds`. Tests pass a stub; production never sets this.
+     */
+    client?: lark.Client;
+}
+/**
+ * The real Feishu transport, wrapping the official SDK.
+ *
+ * Inbound: a `WSClient` opens a long-lived WebSocket and an `EventDispatcher`
+ * routes every subscribed event_type to its callback. Outbound: a `Client`
+ * calls the `im` message API; it manages the `tenant_access_token` internally.
+ * The outbound paths are unit-tested through the `client` seam in
+ * `FeishuTransportOptions`; inbound still needs a live Feishu connection.
+ */
+export declare function createFeishuTransport(creds: FeishuCredentials, options?: FeishuTransportOptions): FeishuTransport;
+export {};
+//# sourceMappingURL=feishu.d.ts.map

package/dist/transport/feishu.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"feishu.d.ts","sourceRoot":"","sources":["../../src/transport/feishu.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,KAAK,IAAI,MAAM,yBAAyB,CAAA;AAE/C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAA;AA0C7D,mCAAmC;AACnC,MAAM,WAAW,gBAAgB;IAC/B;;;;;OAKG;IACH,UAAU,EAAE,MAAM,EAAE,CAAA;CACrB;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEvD;AAED;;;;GAIG;AACH,eAAO,MAAM,8BAA8B,QAAY,CAAA;AAyCvD,0DAA0D;AAC1D,MAAM,WAAW,qBAAqB;IACpC,2DAA2D;IAC3D,OAAO,EAAE,MAAM,CAAA;IACf,qCAAqC;IACrC,QAAQ,EAAE,MAAM,CAAA;IAChB,mFAAmF;IACnF,QAAQ,EAAE,OAAO,EAAE,CAAA;CACpB;AAED;;;;;GAKG;AACH,MAAM,WAAW,gBAAgB;IAC/B,+EAA+E;IAC/E,OAAO,EAAE,OAAO,CAAA;IAChB,kFAAkF;IAClF,KAAK,EAAE,MAAM,CAAA;IACb,2CAA2C;IAC3C,OAAO,EAAE,qBAAqB,EAAE,CAAA;CACjC;AAED,+EAA+E;AAC/E,MAAM,WAAW,aAAa;IAC5B,sBAAsB;IACtB,KAAK,EAAE,MAAM,CAAA;IACb,mCAAmC;IACnC,GAAG,EAAE,MAAM,CAAA;CACZ;AAaD;;;;;GAKG;AACH,UAAU,cAAc;IACtB,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,UAAU,CAAC,EAAE;QACX,OAAO,CAAC,EAAE,KAAK,CAAC;YACd,QAAQ,CAAC,EAAE,MAAM,CAAA;YACjB,OAAO,CAAC,EAAE,MAAM,CAAA;YAChB,OAAO,CAAC,EAAE;gBAAE,QAAQ,CAAC,EAAE,OAAO,EAAE,CAAA;aAAE,CAAA;SACnC,CAAC,CAAA;KACH,CAAA;CACF;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,cAAc,EAAE,EACvB,SAAS,EAAE,MAAM,GAChB,gBAAgB,GAAG,IAAI,CASzB;AAwBD;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,YAAY,GAAG,CAAC,GAAG,EAAE,OAAO,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;AAE1D;;;;GAIG;AACH,MAAM,MAAM,aAAa,GAAG,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,CAAA;AAExD;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC9B,kDAAkD;IAClD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB;;;OAGG;IACH,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAA;IACnC;;;;;;OAMG;IACH,KAAK,CAAC,MAAM,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAC3C;;;;;;;;;;OAUG;IACH,IAAI,CAAC,MAAM,EAAE,cAAc,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAAA;IACrE;;;;OAIG;IACH,WAAW,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAA;IAC9D;;;;;OAKG;IACH,cAAc,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IACpE,6DAA6D;IAC7D,QAAQ,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IACxD;;;;;;OAMG;IACH,eAAe,CACb,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,gBAAgB,GAAG,IAAI,CAAC,CAAA;IACnC;;;;OAIG;IACH,YAAY,CAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC,CAAA;IAChF,gEAAgE;IAChE,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;CACvB;AAED,yCAAyC;AACzC,MAAM,WAAW,iBAAiB;IAChC,KAAK,EAAE,MAAM,CAAA;IACb,SAAS,EAAE,MAAM,CAAA;CAClB;AAED;;;;;GAKG;AACH,MAAM,WAAW,sBAAsB;IACrC;;;OAGG;IACH,MAAM,CAAC,EAAE,IAAI,CAAC,MAAM,CAAA;CACrB;AAED;;;;;;;;GAQG;AACH,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,iBAAiB,EACxB,OAAO,GAAE,sBAA2B,GACnC,eAAe,CAmOjB"}