@larksuiteoapi/node-sdk 1.62.0 → 1.62.2

package/es/index.js

@@ -146,19 +146,21 @@ function getSdkVersion() {
 function sanitizeSource(raw) {
     return raw.replace(/[^a-zA-Z0-9._-]/g, '_').slice(0, 64);
 }
-/**
- * Build the User-Agent value. When `source` is provided it appends a
- * `source/<sanitized>` product token, e.g.
- *     oapi-node-sdk/1.62.0 source/cursor-bot
- * Falsy or all-invalid-char `source` values produce the base UA without
- * the extra token.
- */
-function buildUserAgent(source) {
-    const base = `oapi-node-sdk/${getSdkVersion()}`;
-    if (!source)
-        return base;
-    const clean = sanitizeSource(source);
-    return clean ? `${base} source/${clean}` : base;
+function buildUserAgent(source, opts) {
+    let ua = `oapi-node-sdk/${getSdkVersion()}`;
+    if (source) {
+        const clean = sanitizeSource(source);
+        if (clean)
+            ua += ` source/${clean}`;
+    }
+    if (opts === null || opts === void 0 ? void 0 : opts.extraTags) {
+        for (const t of opts.extraTags) {
+            const clean = sanitizeSource(t);
+            if (clean)
+                ua += ` ${clean}`;
+        }
+    }
+    return ua;
 }
 
 const defaultHttpInstance = axios.create();
@@ -83993,7 +83995,7 @@ class Client extends Client$1 {
         this.appId = params.appId;
         this.appSecret = params.appSecret;
         this.disableTokenCache = params.disableTokenCache;
-        this.userAgent = buildUserAgent(params.source);
+        this.userAgent = buildUserAgent(params.source, { extraTags: params.extraUaTags });
         assert(!this.appId, () => this.logger.error('appId is needed'));
         assert(!this.appSecret, () => this.logger.error('appSecret is needed'));
         this.helpDeskId = params.helpDeskId;
@@ -85362,8 +85364,8 @@ class WSClient {
         /** True if the WS has ever connected successfully in this client's
          *  lifetime — used to distinguish first-connect from reconnect. */
         this.hasEverConnected = false;
-        const { appId, appSecret, agent, domain = Domain.Feishu, httpInstance = defaultHttpInstance, loggerLevel = LoggerLevel.info, logger = defaultLogger, autoReconnect = true, source, onReady, onError, onReconnecting, onReconnected, } = params;
-        this.userAgent = buildUserAgent(source);
+        const { appId, appSecret, agent, domain = Domain.Feishu, httpInstance = defaultHttpInstance, loggerLevel = LoggerLevel.info, logger = defaultLogger, autoReconnect = true, source, extraUaTags, onReady, onError, onReconnecting, onReconnected, } = params;
+        this.userAgent = buildUserAgent(source, { extraTags: extraUaTags });
         this.logger = new LoggerProxy(loggerLevel, logger);
         assert(!appId, () => this.logger.error('appId is needed'));
         assert(!appSecret, () => this.logger.error('appSecret is needed'));
@@ -89147,7 +89149,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;
@@ -89168,10 +89170,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;
@@ -89189,6 +89192,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,
     };
 }
 
@@ -89328,6 +89332,7 @@ class LarkChannel {
             logger: opts.logger,
             loggerLevel: opts.loggerLevel,
             source: opts.source,
+            extraUaTags: ['channel'],
         });
         this.dispatcher = new EventDispatcher({
             verificationToken: (_d = opts.webhook) === null || _d === void 0 ? void 0 : _d.verificationToken,
@@ -89405,6 +89410,7 @@ class LarkChannel {
                 httpInstance: this.opts.httpInstance,
                 autoReconnect: true,
                 source: this.opts.source,
+                extraUaTags: ['channel'],
                 onReady: () => {
                     if (settled)
                         return;
@@ -89633,6 +89639,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
@@ -89643,23 +89650,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({
@@ -89679,7 +89689,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);
@@ -89691,14 +89701,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);
@@ -89707,9 +89717,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 {
@@ -89721,9 +89729,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

@@ -164,19 +164,21 @@ function getSdkVersion() {
 function sanitizeSource(raw) {
     return raw.replace(/[^a-zA-Z0-9._-]/g, '_').slice(0, 64);
 }
-/**
- * Build the User-Agent value. When `source` is provided it appends a
- * `source/<sanitized>` product token, e.g.
- *     oapi-node-sdk/1.62.0 source/cursor-bot
- * Falsy or all-invalid-char `source` values produce the base UA without
- * the extra token.
- */
-function buildUserAgent(source) {
-    const base = `oapi-node-sdk/${getSdkVersion()}`;
-    if (!source)
-        return base;
-    const clean = sanitizeSource(source);
-    return clean ? `${base} source/${clean}` : base;
+function buildUserAgent(source, opts) {
+    let ua = `oapi-node-sdk/${getSdkVersion()}`;
+    if (source) {
+        const clean = sanitizeSource(source);
+        if (clean)
+            ua += ` source/${clean}`;
+    }
+    if (opts === null || opts === void 0 ? void 0 : opts.extraTags) {
+        for (const t of opts.extraTags) {
+            const clean = sanitizeSource(t);
+            if (clean)
+                ua += ` ${clean}`;
+        }
+    }
+    return ua;
 }
 
 const defaultHttpInstance = axios__default["default"].create();
@@ -84011,7 +84013,7 @@ class Client extends Client$1 {
         this.appId = params.appId;
         this.appSecret = params.appSecret;
         this.disableTokenCache = params.disableTokenCache;
-        this.userAgent = buildUserAgent(params.source);
+        this.userAgent = buildUserAgent(params.source, { extraTags: params.extraUaTags });
         assert(!this.appId, () => this.logger.error('appId is needed'));
         assert(!this.appSecret, () => this.logger.error('appSecret is needed'));
         this.helpDeskId = params.helpDeskId;
@@ -85380,8 +85382,8 @@ class WSClient {
         /** True if the WS has ever connected successfully in this client's
          *  lifetime — used to distinguish first-connect from reconnect. */
         this.hasEverConnected = false;
-        const { appId, appSecret, agent, domain = exports.Domain.Feishu, httpInstance = defaultHttpInstance, loggerLevel = exports.LoggerLevel.info, logger = defaultLogger, autoReconnect = true, source, onReady, onError, onReconnecting, onReconnected, } = params;
-        this.userAgent = buildUserAgent(source);
+        const { appId, appSecret, agent, domain = exports.Domain.Feishu, httpInstance = defaultHttpInstance, loggerLevel = exports.LoggerLevel.info, logger = defaultLogger, autoReconnect = true, source, extraUaTags, onReady, onError, onReconnecting, onReconnected, } = params;
+        this.userAgent = buildUserAgent(source, { extraTags: extraUaTags });
         this.logger = new LoggerProxy(loggerLevel, logger);
         assert(!appId, () => this.logger.error('appId is needed'));
         assert(!appSecret, () => this.logger.error('appSecret is needed'));
@@ -89165,7 +89167,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;
@@ -89186,10 +89188,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;
@@ -89207,6 +89210,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,
     };
 }
 
@@ -89346,6 +89350,7 @@ class LarkChannel {
             logger: opts.logger,
             loggerLevel: opts.loggerLevel,
             source: opts.source,
+            extraUaTags: ['channel'],
         });
         this.dispatcher = new EventDispatcher({
             verificationToken: (_d = opts.webhook) === null || _d === void 0 ? void 0 : _d.verificationToken,
@@ -89423,6 +89428,7 @@ class LarkChannel {
                 httpInstance: this.opts.httpInstance,
                 autoReconnect: true,
                 source: this.opts.source,
+                extraUaTags: ['channel'],
                 onReady: () => {
                     if (settled)
                         return;
@@ -89651,6 +89657,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
@@ -89661,23 +89668,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({
@@ -89697,7 +89707,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);
@@ -89709,14 +89719,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);
@@ -89725,9 +89735,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 {
@@ -89739,9 +89747,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.0",
+  "version": "1.62.2",
   "description": "larksuite open sdk for nodejs",
   "keywords": [
     "feishu",

package/types/index.d.ts

@@ -112,6 +112,8 @@ interface IClientParams {
     httpInstance?: HttpInstance;
     /** Caller tag appended to User-Agent as `source/<name>`. */
     source?: string;
+    /** @internal Extra bare tokens appended to User-Agent, set by sub-modules. */
+    extraUaTags?: string[];
 }
 interface IPayload {
     params?: Record<string, any>;
@@ -293052,6 +293054,8 @@ interface IConstructorParams {
     agent?: any;
     /** Caller tag appended to User-Agent as `source/<name>`. */
     source?: string;
+    /** @internal Extra bare tokens appended to User-Agent, set by sub-modules. */
+    extraUaTags?: string[];
     /** Fires once when the first WebSocket handshake succeeds. */
     onReady?: () => void;
     /**
@@ -293407,6 +293411,7 @@ interface CardActionEvent {
         name?: string;
         option?: string;
     };
+    raw?: unknown;
 }
 interface ReactionEvent {
     messageId: string;
@@ -293417,6 +293422,7 @@ interface ReactionEvent {
     emojiType: string;
     action: 'added' | 'removed';
     actionTime?: number;
+    raw?: unknown;
 }
 interface BotAddedEvent {
     chatId: string;
@@ -293476,6 +293482,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 {
@@ -293699,7 +293714,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;
@@ -293714,7 +293731,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;