@larksuiteoapi/node-sdk 1.62.1 → 1.63.0

package/es/index.js

@@ -85418,10 +85418,16 @@ class WSClient {
                     timeout: 15000,
                 });
                 if (code !== ErrorCode.ok) {
-                    this.logger.error('[ws]', `code: ${code}, ${code === ErrorCode.system_busy ? msg : 'system busy'}`);
-                    if (code === ErrorCode.system_busy || code === ErrorCode.internal_error) {
-                        return false;
+                    const reason = code === ErrorCode.system_busy ? 'system busy' : msg;
+                    this.logger.error('[ws]', `code: ${code}, ${reason}`);
+                    if (code === ErrorCode.internal_error) {
+                        return { ok: false, retryable: true };
                     }
+                    return {
+                        ok: false,
+                        retryable: false,
+                        error: `pullConnectConfig failed: code=${code}, msg=${reason}`,
+                    };
                 }
                 const { device_id, service_id } = qs.parse(URL);
                 this.wsConfig.updateWs({
@@ -85434,11 +85440,11 @@ class WSClient {
                     reconnectNonce: ClientConfig.ReconnectNonce * 1000
                 });
                 this.logger.debug('[ws]', `get connect config success, ws url: ${URL}`);
-                return true;
+                return { ok: true };
             }
             catch (e) {
                 this.logger.error('[ws]', (e === null || e === void 0 ? void 0 : e.message) || 'system busy');
-                return false;
+                return { ok: false, retryable: true };
             }
         });
     }
@@ -85477,18 +85483,17 @@ class WSClient {
             this.isConnecting = true;
             // Invalidate any in-flight reconnect loops from previous sessions
             const currentGeneration = ++this.reconnectGeneration;
-            const tryConnect = () => {
+            const tryConnect = () => __awaiter(this, void 0, void 0, function* () {
                 this.reconnectInfo.lastConnectTime = Date.now();
-                return this.pullConnectConfig()
-                    .then(isSuccess => isSuccess ? this.connect() : Promise.resolve(false))
-                    .then(isSuccess => {
-                    if (isSuccess) {
-                        this.communicate();
-                        return Promise.resolve(true);
-                    }
-                    return Promise.resolve(false);
-                });
-            };
+                const pullResult = yield this.pullConnectConfig();
+                if (!pullResult.ok)
+                    return pullResult;
+                const connected = yield this.connect();
+                if (!connected)
+                    return { ok: false, retryable: true };
+                this.communicate();
+                return { ok: true };
+            });
             if (this.pingInterval) {
                 clearTimeout(this.pingInterval);
             }
@@ -85500,17 +85505,25 @@ class WSClient {
                 if (wsInstance) {
                     wsInstance === null || wsInstance === void 0 ? void 0 : wsInstance.terminate();
                 }
-                let isSuccess = false;
+                let result = { ok: false, retryable: true };
                 try {
-                    isSuccess = yield tryConnect();
+                    result = yield tryConnect();
                 }
                 finally {
                     this.isConnecting = false;
                 }
-                if (isSuccess) {
+                if (result.ok) {
                     this.hasEverConnected = true;
                     this.safeInvoke('onReady', this.onReady);
                 }
+                else if (!result.retryable) {
+                    // Non-recoverable error from pullConnectConfig — bail out without retry.
+                    // Reset hasEverConnected so a subsequent start() is treated as a fresh
+                    // session (onReady fires, not onReconnected).
+                    this.hasEverConnected = false;
+                    this.safeInvoke('onError', this.onError, new Error(result.error));
+                    return;
+                }
                 else {
                     this.logger.error('[ws]', 'connect failed');
                     yield this.reConnect();
@@ -85542,13 +85555,13 @@ class WSClient {
                             return;
                         }
                         count++;
-                        const isSuccess = yield tryConnect();
+                        const result = yield tryConnect();
                         // Re-check after async operation in case a new session started
                         if (currentGeneration !== this.reconnectGeneration) {
                             return;
                         }
                         // if reconnectCount < 0, the reconnect time is infinite
-                        if (isSuccess) {
+                        if (result.ok) {
                             this.logger.debug('[ws]', 'reconnect success');
                             if (this.hasEverConnected) {
                                 this.safeInvoke('onReconnected', this.onReconnected);
@@ -85560,6 +85573,15 @@ class WSClient {
                             this.isConnecting = false;
                             return;
                         }
+                        if (!result.retryable) {
+                            // Non-recoverable error — abort the loop, do not schedule another attempt.
+                            // Reset hasEverConnected so a subsequent start() is treated as a fresh
+                            // session (onReady fires, not onReconnected).
+                            this.isConnecting = false;
+                            this.hasEverConnected = false;
+                            this.safeInvoke('onError', this.onError, new Error(result.error));
+                            return;
+                        }
                         this.logger.info('ws', `unable to connect to the server after trying ${count} times")`);
                         if (reconnectCount >= 0 && count >= reconnectCount) {
                             this.isConnecting = false;
@@ -89149,7 +89171,7 @@ function dispatchConvert(raw, msgType, ctx) {
     });
 }
 
-function normalizeCardAction(event) {
+function normalizeCardAction(event, opts) {
     var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m;
     const messageId = (_b = (_a = event.context) === null || _a === void 0 ? void 0 : _a.open_message_id) !== null && _b !== void 0 ? _b : event.open_message_id;
     const chatId = (_d = (_c = event.context) === null || _c === void 0 ? void 0 : _c.open_chat_id) !== null && _d !== void 0 ? _d : event.open_chat_id;
@@ -89170,10 +89192,11 @@ function normalizeCardAction(event) {
             name: (_l = event.action) === null || _l === void 0 ? void 0 : _l.name,
             option: (_m = event.action) === null || _m === void 0 ? void 0 : _m.option,
         },
+        raw: (opts === null || opts === void 0 ? void 0 : opts.includeRaw) ? event : undefined,
     };
 }
 
-function normalizeReaction(event, action) {
+function normalizeReaction(event, action, opts) {
     var _a, _b, _c, _d;
     const messageId = event.message_id;
     const emojiType = (_a = event.reaction_type) === null || _a === void 0 ? void 0 : _a.emoji_type;
@@ -89191,6 +89214,7 @@ function normalizeReaction(event, action) {
         emojiType,
         action,
         actionTime: actionTime != null && Number.isFinite(actionTime) ? actionTime : undefined,
+        raw: (opts === null || opts === void 0 ? void 0 : opts.includeRaw) ? event : undefined,
     };
 }
 
@@ -89637,6 +89661,7 @@ class LarkChannel {
         });
     }
     registerDispatcherHandlers() {
+        var _a, _b;
         // `im.v1.message.get(mid)` on a merge_forward message returns
         // `data.items[]` as a flat list: the parent message first (no
         // `upper_message_id`) followed by every descendant, each with
@@ -89647,23 +89672,26 @@ class LarkChannel {
         // `container_id_type: 'message'`, which Feishu rejects — 'message'
         // isn't a valid container type.)
         const fetchSubMessages = (mid) => __awaiter(this, void 0, void 0, function* () {
-            var _a, _b, _c, _d;
+            var _c, _d, _e, _f;
             try {
                 const r = yield this.rawClient.im.v1.message.get({
                     path: { message_id: mid },
                 });
-                const items = (_b = (_a = r.data) === null || _a === void 0 ? void 0 : _a.items) !== null && _b !== void 0 ? _b : [];
+                const items = (_d = (_c = r.data) === null || _c === void 0 ? void 0 : _c.items) !== null && _d !== void 0 ? _d : [];
                 return items;
             }
             catch (e) {
-                (_d = (_c = this.logger).warn) === null || _d === void 0 ? void 0 : _d.call(_c, 'channel: fetchSubMessages failed', e);
+                (_f = (_e = this.logger).warn) === null || _f === void 0 ? void 0 : _f.call(_e, 'channel: fetchSubMessages failed', e);
                 return [];
             }
         });
+        // Unified raw-event flag: prefer the new `includeRawEvent` option,
+        // fall back to the legacy `includeRawInMessage` for back-compat.
+        const includeRaw = (_b = (_a = this.opts.includeRawEvent) !== null && _a !== void 0 ? _a : this.opts.includeRawInMessage) !== null && _b !== void 0 ? _b : false;
         const normalizeOpts = {
             botIdentity: this.botIdentity,
             stripBotMentions: true,
-            includeRaw: this.opts.includeRawInMessage,
+            includeRaw,
             fetchSubMessages,
         };
         this.dispatcher.register({
@@ -89683,7 +89711,7 @@ class LarkChannel {
             // collapsed by the dedup cache. A genuine Feishu re-delivery
             // of the same click still hashes to the same key.
             'card.action.trigger': (raw) => __awaiter(this, void 0, void 0, function* () {
-                const evt = normalizeCardAction(raw);
+                const evt = normalizeCardAction(raw, { includeRaw });
                 if (!evt)
                     return;
                 const actionId = cardActionId(evt.action);
@@ -89695,14 +89723,14 @@ class LarkChannel {
             }),
             // Reactions — dedup only
             'im.message.reaction.created_v1': (raw) => __awaiter(this, void 0, void 0, function* () {
-                const evt = normalizeReaction(raw, 'added');
+                const evt = normalizeReaction(raw, 'added', { includeRaw });
                 if (!evt)
                     return;
                 const key = reactionKey(evt);
                 yield this.safety.pushLight(key, () => { var _a, _b; return (_b = (_a = this.handlers).reaction) === null || _b === void 0 ? void 0 : _b.call(_a, evt); });
             }),
             'im.message.reaction.deleted_v1': (raw) => __awaiter(this, void 0, void 0, function* () {
-                const evt = normalizeReaction(raw, 'removed');
+                const evt = normalizeReaction(raw, 'removed', { includeRaw });
                 if (!evt)
                     return;
                 const key = reactionKey(evt);
@@ -89711,9 +89739,7 @@ class LarkChannel {
             // Bot added — direct fire, no safety
             'im.chat.member.bot.added_v1': (raw) => {
                 var _a, _b;
-                const evt = normalizeBotAdded(raw, {
-                    includeRaw: this.opts.includeRawInMessage,
-                });
+                const evt = normalizeBotAdded(raw, { includeRaw });
                 if (!evt)
                     return;
                 try {
@@ -89725,9 +89751,7 @@ class LarkChannel {
             },
             // Drive comments — dedup + lock + queue (by fileToken)
             'drive.notice.comment_add_v1': (raw) => __awaiter(this, void 0, void 0, function* () {
-                const evt = normalizeComment(raw, {
-                    includeRaw: this.opts.includeRawInMessage,
-                });
+                const evt = normalizeComment(raw, { includeRaw });
                 if (!evt)
                     return;
                 yield this.safety.pushAction(`comment:${evt.fileToken}:${evt.commentId}`, evt.fileToken, () => __awaiter(this, void 0, void 0, function* () {

package/lib/index.js

@@ -85436,10 +85436,16 @@ class WSClient {
                     timeout: 15000,
                 });
                 if (code !== ErrorCode.ok) {
-                    this.logger.error('[ws]', `code: ${code}, ${code === ErrorCode.system_busy ? msg : 'system busy'}`);
-                    if (code === ErrorCode.system_busy || code === ErrorCode.internal_error) {
-                        return false;
+                    const reason = code === ErrorCode.system_busy ? 'system busy' : msg;
+                    this.logger.error('[ws]', `code: ${code}, ${reason}`);
+                    if (code === ErrorCode.internal_error) {
+                        return { ok: false, retryable: true };
                     }
+                    return {
+                        ok: false,
+                        retryable: false,
+                        error: `pullConnectConfig failed: code=${code}, msg=${reason}`,
+                    };
                 }
                 const { device_id, service_id } = qs__default["default"].parse(URL);
                 this.wsConfig.updateWs({
@@ -85452,11 +85458,11 @@ class WSClient {
                     reconnectNonce: ClientConfig.ReconnectNonce * 1000
                 });
                 this.logger.debug('[ws]', `get connect config success, ws url: ${URL}`);
-                return true;
+                return { ok: true };
             }
             catch (e) {
                 this.logger.error('[ws]', (e === null || e === void 0 ? void 0 : e.message) || 'system busy');
-                return false;
+                return { ok: false, retryable: true };
             }
         });
     }
@@ -85495,18 +85501,17 @@ class WSClient {
             this.isConnecting = true;
             // Invalidate any in-flight reconnect loops from previous sessions
             const currentGeneration = ++this.reconnectGeneration;
-            const tryConnect = () => {
+            const tryConnect = () => __awaiter(this, void 0, void 0, function* () {
                 this.reconnectInfo.lastConnectTime = Date.now();
-                return this.pullConnectConfig()
-                    .then(isSuccess => isSuccess ? this.connect() : Promise.resolve(false))
-                    .then(isSuccess => {
-                    if (isSuccess) {
-                        this.communicate();
-                        return Promise.resolve(true);
-                    }
-                    return Promise.resolve(false);
-                });
-            };
+                const pullResult = yield this.pullConnectConfig();
+                if (!pullResult.ok)
+                    return pullResult;
+                const connected = yield this.connect();
+                if (!connected)
+                    return { ok: false, retryable: true };
+                this.communicate();
+                return { ok: true };
+            });
             if (this.pingInterval) {
                 clearTimeout(this.pingInterval);
             }
@@ -85518,17 +85523,25 @@ class WSClient {
                 if (wsInstance) {
                     wsInstance === null || wsInstance === void 0 ? void 0 : wsInstance.terminate();
                 }
-                let isSuccess = false;
+                let result = { ok: false, retryable: true };
                 try {
-                    isSuccess = yield tryConnect();
+                    result = yield tryConnect();
                 }
                 finally {
                     this.isConnecting = false;
                 }
-                if (isSuccess) {
+                if (result.ok) {
                     this.hasEverConnected = true;
                     this.safeInvoke('onReady', this.onReady);
                 }
+                else if (!result.retryable) {
+                    // Non-recoverable error from pullConnectConfig — bail out without retry.
+                    // Reset hasEverConnected so a subsequent start() is treated as a fresh
+                    // session (onReady fires, not onReconnected).
+                    this.hasEverConnected = false;
+                    this.safeInvoke('onError', this.onError, new Error(result.error));
+                    return;
+                }
                 else {
                     this.logger.error('[ws]', 'connect failed');
                     yield this.reConnect();
@@ -85560,13 +85573,13 @@ class WSClient {
                             return;
                         }
                         count++;
-                        const isSuccess = yield tryConnect();
+                        const result = yield tryConnect();
                         // Re-check after async operation in case a new session started
                         if (currentGeneration !== this.reconnectGeneration) {
                             return;
                         }
                         // if reconnectCount < 0, the reconnect time is infinite
-                        if (isSuccess) {
+                        if (result.ok) {
                             this.logger.debug('[ws]', 'reconnect success');
                             if (this.hasEverConnected) {
                                 this.safeInvoke('onReconnected', this.onReconnected);
@@ -85578,6 +85591,15 @@ class WSClient {
                             this.isConnecting = false;
                             return;
                         }
+                        if (!result.retryable) {
+                            // Non-recoverable error — abort the loop, do not schedule another attempt.
+                            // Reset hasEverConnected so a subsequent start() is treated as a fresh
+                            // session (onReady fires, not onReconnected).
+                            this.isConnecting = false;
+                            this.hasEverConnected = false;
+                            this.safeInvoke('onError', this.onError, new Error(result.error));
+                            return;
+                        }
                         this.logger.info('ws', `unable to connect to the server after trying ${count} times")`);
                         if (reconnectCount >= 0 && count >= reconnectCount) {
                             this.isConnecting = false;
@@ -89167,7 +89189,7 @@ function dispatchConvert(raw, msgType, ctx) {
     });
 }
 
-function normalizeCardAction(event) {
+function normalizeCardAction(event, opts) {
     var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m;
     const messageId = (_b = (_a = event.context) === null || _a === void 0 ? void 0 : _a.open_message_id) !== null && _b !== void 0 ? _b : event.open_message_id;
     const chatId = (_d = (_c = event.context) === null || _c === void 0 ? void 0 : _c.open_chat_id) !== null && _d !== void 0 ? _d : event.open_chat_id;
@@ -89188,10 +89210,11 @@ function normalizeCardAction(event) {
             name: (_l = event.action) === null || _l === void 0 ? void 0 : _l.name,
             option: (_m = event.action) === null || _m === void 0 ? void 0 : _m.option,
         },
+        raw: (opts === null || opts === void 0 ? void 0 : opts.includeRaw) ? event : undefined,
     };
 }
 
-function normalizeReaction(event, action) {
+function normalizeReaction(event, action, opts) {
     var _a, _b, _c, _d;
     const messageId = event.message_id;
     const emojiType = (_a = event.reaction_type) === null || _a === void 0 ? void 0 : _a.emoji_type;
@@ -89209,6 +89232,7 @@ function normalizeReaction(event, action) {
         emojiType,
         action,
         actionTime: actionTime != null && Number.isFinite(actionTime) ? actionTime : undefined,
+        raw: (opts === null || opts === void 0 ? void 0 : opts.includeRaw) ? event : undefined,
     };
 }
 
@@ -89655,6 +89679,7 @@ class LarkChannel {
         });
     }
     registerDispatcherHandlers() {
+        var _a, _b;
         // `im.v1.message.get(mid)` on a merge_forward message returns
         // `data.items[]` as a flat list: the parent message first (no
         // `upper_message_id`) followed by every descendant, each with
@@ -89665,23 +89690,26 @@ class LarkChannel {
         // `container_id_type: 'message'`, which Feishu rejects — 'message'
         // isn't a valid container type.)
         const fetchSubMessages = (mid) => __awaiter(this, void 0, void 0, function* () {
-            var _a, _b, _c, _d;
+            var _c, _d, _e, _f;
             try {
                 const r = yield this.rawClient.im.v1.message.get({
                     path: { message_id: mid },
                 });
-                const items = (_b = (_a = r.data) === null || _a === void 0 ? void 0 : _a.items) !== null && _b !== void 0 ? _b : [];
+                const items = (_d = (_c = r.data) === null || _c === void 0 ? void 0 : _c.items) !== null && _d !== void 0 ? _d : [];
                 return items;
             }
             catch (e) {
-                (_d = (_c = this.logger).warn) === null || _d === void 0 ? void 0 : _d.call(_c, 'channel: fetchSubMessages failed', e);
+                (_f = (_e = this.logger).warn) === null || _f === void 0 ? void 0 : _f.call(_e, 'channel: fetchSubMessages failed', e);
                 return [];
             }
         });
+        // Unified raw-event flag: prefer the new `includeRawEvent` option,
+        // fall back to the legacy `includeRawInMessage` for back-compat.
+        const includeRaw = (_b = (_a = this.opts.includeRawEvent) !== null && _a !== void 0 ? _a : this.opts.includeRawInMessage) !== null && _b !== void 0 ? _b : false;
         const normalizeOpts = {
             botIdentity: this.botIdentity,
             stripBotMentions: true,
-            includeRaw: this.opts.includeRawInMessage,
+            includeRaw,
             fetchSubMessages,
         };
         this.dispatcher.register({
@@ -89701,7 +89729,7 @@ class LarkChannel {
             // collapsed by the dedup cache. A genuine Feishu re-delivery
             // of the same click still hashes to the same key.
             'card.action.trigger': (raw) => __awaiter(this, void 0, void 0, function* () {
-                const evt = normalizeCardAction(raw);
+                const evt = normalizeCardAction(raw, { includeRaw });
                 if (!evt)
                     return;
                 const actionId = cardActionId(evt.action);
@@ -89713,14 +89741,14 @@ class LarkChannel {
             }),
             // Reactions — dedup only
             'im.message.reaction.created_v1': (raw) => __awaiter(this, void 0, void 0, function* () {
-                const evt = normalizeReaction(raw, 'added');
+                const evt = normalizeReaction(raw, 'added', { includeRaw });
                 if (!evt)
                     return;
                 const key = reactionKey(evt);
                 yield this.safety.pushLight(key, () => { var _a, _b; return (_b = (_a = this.handlers).reaction) === null || _b === void 0 ? void 0 : _b.call(_a, evt); });
             }),
             'im.message.reaction.deleted_v1': (raw) => __awaiter(this, void 0, void 0, function* () {
-                const evt = normalizeReaction(raw, 'removed');
+                const evt = normalizeReaction(raw, 'removed', { includeRaw });
                 if (!evt)
                     return;
                 const key = reactionKey(evt);
@@ -89729,9 +89757,7 @@ class LarkChannel {
             // Bot added — direct fire, no safety
             'im.chat.member.bot.added_v1': (raw) => {
                 var _a, _b;
-                const evt = normalizeBotAdded(raw, {
-                    includeRaw: this.opts.includeRawInMessage,
-                });
+                const evt = normalizeBotAdded(raw, { includeRaw });
                 if (!evt)
                     return;
                 try {
@@ -89743,9 +89769,7 @@ class LarkChannel {
             },
             // Drive comments — dedup + lock + queue (by fileToken)
             'drive.notice.comment_add_v1': (raw) => __awaiter(this, void 0, void 0, function* () {
-                const evt = normalizeComment(raw, {
-                    includeRaw: this.opts.includeRawInMessage,
-                });
+                const evt = normalizeComment(raw, { includeRaw });
                 if (!evt)
                     return;
                 yield this.safety.pushAction(`comment:${evt.fileToken}:${evt.commentId}`, evt.fileToken, () => __awaiter(this, void 0, void 0, function* () {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@larksuiteoapi/node-sdk",
-  "version": "1.62.1",
+  "version": "1.63.0",
   "description": "larksuite open sdk for nodejs",
   "keywords": [
     "feishu",

package/types/index.d.ts

@@ -293069,6 +293069,7 @@ interface IConstructorParams {
     /** Fires after the reconnect loop successfully re-establishes the connection. */
     onReconnected?: () => void;
 }
+
 declare class WSClient {
     private wsConfig;
     private logger;
@@ -293411,6 +293412,7 @@ interface CardActionEvent {
         name?: string;
         option?: string;
     };
+    raw?: unknown;
 }
 interface ReactionEvent {
     messageId: string;
@@ -293421,6 +293423,7 @@ interface ReactionEvent {
     emojiType: string;
     action: 'added' | 'removed';
     actionTime?: number;
+    raw?: unknown;
 }
 interface BotAddedEvent {
     chatId: string;
@@ -293480,6 +293483,15 @@ interface LarkChannelOptions {
     httpInstance?: HttpInstance;
     /** Caller tag appended to User-Agent as `source/<name>`. */
     source?: string;
+    /**
+     * Attach the raw Feishu event body on every normalized event
+     * (`message`, `cardAction`, `reaction`, `botAdded`, `comment`) as
+     * `evt.raw`. Useful when a handler needs fields that the normalizer
+     * dropped (e.g. `tenant_key`, `host`, `event_id`, vendor-specific
+     * extensions). Off by default — payloads are smaller and stricter.
+     */
+    includeRawEvent?: boolean;
+    /** @deprecated Use `includeRawEvent` instead. Retained for backward compatibility. */
     includeRawInMessage?: boolean;
 }
 interface WebhookOptions {
@@ -293703,7 +293715,9 @@ interface RawCardActionEvent {
         timezone?: string;
     };
 }
-declare function normalizeCardAction(event: RawCardActionEvent): CardActionEvent | null;
+declare function normalizeCardAction(event: RawCardActionEvent, opts?: {
+    includeRaw?: boolean;
+}): CardActionEvent | null;
 
 interface RawReactionEvent {
     message_id?: string;
@@ -293718,7 +293732,9 @@ interface RawReactionEvent {
     };
     action_time?: string;
 }
-declare function normalizeReaction(event: RawReactionEvent, action: 'added' | 'removed'): ReactionEvent | null;
+declare function normalizeReaction(event: RawReactionEvent, action: 'added' | 'removed', opts?: {
+    includeRaw?: boolean;
+}): ReactionEvent | null;
 
 interface RawBotAddedEvent {
     chat_id?: string;