@larksuiteoapi/node-sdk 1.14.0 → 1.15.0

package/README.md

@@ -185,6 +185,74 @@ const res = await client. request({
     params: {},
 });
 ````
+#### Message Card
+When sending [message card](https://open.feishu.cn/document/ukTMukTMukTM/uczM3QjL3MzN04yNzcDN)， it will first be in the [message card builder](https://open.feishu.cn/document/ukTMukTMukTM/uYzM3QjL2MzN04iNzcDN/message-card-builder) to build a message card template, get the generated template json, replace the content-related parts with data, and use the result as a parameter to support the message card api. Such as sending a simple message card with `title` and `content`:
+```typescript
+client.im.message.create({
+  params: {
+    receive_id_type: 'chat_id',
+  },
+  data: {
+    receive_id: 'your receive_id',
+    content: JSON.stringify({
+        "config": {
+          "wide_screen_mode": true
+        },
+        "elements": [
+          {
+            "tag": "markdown",
+            "content": "Card Content"
+          }
+        ],
+        "header": {
+          "template": "blue",
+          "title": {
+            "content": "Card Title",
+            "tag": "plain_text"
+          }
+        }
+      }
+    ),
+    msg_type: 'interactive'
+  }
+})
+```
+![](doc/msg-card.png)
+There will be a problem: **If the content of the message card is relatively rich, the generated template json is relatively large, and there will be more content that needs to be filled with data, and manual maintenance is more cumbersome**. To solve this problem, The Open-Platform provides the ability of [Template Message](https://open.feishu.cn/document/tools-and-resources/message-card-builder#3e1f2c7c).When sending a message card, you only need to provide the template id and the data content of the template. The sdk encapsulates this ability in terms of calling, and the interface that supports message cards will synchronously add a ByCard calling method, only need to pass `template_id` and `template_variable`. The above call can be rewritten as:
+```typescript
+client.im.message.createByCard({
+  params: {
+    receive_id_type: 'chat_id',
+  },
+  data: {
+    receive_id: 'your receive_id',
+    template_id: 'your template_id',
+    template_variable: {
+      content: "Card Content",
+      title: "Card Title"
+    }
+  }
+});
+```
+If you want to quickly experience Message Card, you can use a basic card built into the sdk:
+```typescript
+import * as lark from '@larksuiteoapi/node-sdk';
+
+client.im.message.create({
+  params: {
+    receive_id_type: 'chat_id',
+  },
+  data: {
+    receive_id: 'your receive_id',
+    content: lark.messageCard.defaultCard({
+      title: 'Card Title',
+      content: 'Card Content'
+    }),
+    msg_type: 'interactive'
+  }
+})
+```
+![](doc/msg-card.png)
 
 #### Configure request options
 If you want to modify the parameters of the request during the API call, such as carrying some headers, custom tenantToken, etc., you can use the second parameter of the request method to modify:

package/README.zh.md

@@ -184,6 +184,75 @@ const res = await client.request({
     params: {},
 });
 ```
+#### 消息卡片
+在发送[消息卡片](https://open.feishu.cn/document/ukTMukTMukTM/uczM3QjL3MzN04yNzcDN)信息时，会先在[消息卡片搭建工具](https://open.feishu.cn/document/ukTMukTMukTM/uYzM3QjL2MzN04iNzcDN/message-card-builder)中搭建出消息卡片的模版，拿到生成的模版json，用数据替换其中内容相关的部分，将结果作为支持消息卡片api的参数来使用。如发送一个简单的具有`title`和`content`的消息卡片：
+```typescript
+client.im.message.create({
+  params: {
+    receive_id_type: 'chat_id',
+  },
+  data: {
+    receive_id: 'your receive_id',
+    content: JSON.stringify({
+        "config": {
+          "wide_screen_mode": true
+        },
+        "elements": [
+          {
+            "tag": "markdown",
+            "content": "Card Content"
+          }
+        ],
+        "header": {
+          "template": "blue",
+          "title": {
+            "content": "Card Title",
+            "tag": "plain_text"
+          }
+        }
+      }
+    ),
+    msg_type: 'interactive'
+  }
+})
+```
+![](doc/msg-card.png)
+这样使用会有一个问题：**如果消息卡片内容比较丰富，生成的模版json比较大，与之相关需要数据填充的内容部分也会比较多，手动维护比较繁琐**。针对这个问题，开放平台提供了[模版消息](https://open.feishu.cn/document/tools-and-resources/message-card-builder#3e1f2c7c)的能力，发送消息卡片时只需要提供模版id和模版的数据内容即可。sdk对这个能力进行了调用上的封装，支持消息卡片的接口会同步的增加一个ByCard的调用方式，只需要传递`template_id`和`template_variable`即可。如上面的调用可以改写成：
+```typescript
+client.im.message.createByCard({
+  params: {
+    receive_id_type: 'chat_id',
+  },
+  data: {
+    receive_id: 'your receive_id',
+    template_id: 'your template_id',
+    template_variable: {
+      content: "Card Content",
+      title: "Card Title"
+    }
+  }
+});
+```
+如果想要快速体验消息卡片，可以使用sdk中内置的一个基础卡片:
+```typescript
+import * as lark from '@larksuiteoapi/node-sdk';
+
+client.im.message.create({
+  params: {
+    receive_id_type: 'chat_id',
+  },
+  data: {
+    receive_id: 'your receive_id',
+    content: lark.messageCard.defaultCard({
+      title: 'Card Title',
+      content: 'Card Content'
+    }),
+    msg_type: 'interactive'
+  }
+})
+```
+效果同上：
+![](doc/msg-card.png)
 
 #### 配置请求选项
 如果想在api调用过程中修改请求的参数，如携带一些header，自定义tenantToken等，则可以使用请求方法的第二个参数来进行修改：

package/es/index.js

@@ -14951,6 +14951,70 @@ class Client$1 {
                         throw e;
                     });
                 }),
+                /**
+                 * {@link https://open.feishu.cn/api-explorer?project=im&resource=message&apiName=create&version=v1 click to debug }
+                 *
+                 * {@link https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/im-v1/message/create document }
+                 *
+                 * 通过模版消息卡片发送消息
+                 *
+                 * 注意事项:;- 需要开启[机器人能力](https://open.feishu.cn/document/uAjLw4CM/ugTN1YjL4UTN24CO1UjN/trouble-shooting/how-to-enable-bot-ability)  ;- 给用户发送消息，需要机器人对用户有[可用性](https://open.feishu.cn/document/home/introduction-to-scope-and-authorization/availability);- 给群组发送消息，需要机器人在群组中
+                 */
+                createByCard: (payload, options) => __awaiter(this, void 0, void 0, function* () {
+                    const { headers, params, data, path } = yield this.formatPayload(payload, options);
+                    const { template_id, template_variable } = data, rest = __rest(data, ["template_id", "template_variable"]);
+                    const targetData = Object.assign({ msg_type: "interactive", content: JSON.stringify({
+                            type: "template",
+                            data: {
+                                template_id: template_id,
+                                template_variable: template_variable,
+                            },
+                        }) }, rest);
+                    return this.httpInstance
+                        .request({
+                        url: fillApiPath(`${this.domain}/open-apis/im/v1/messages`, path),
+                        method: "POST",
+                        data: targetData,
+                        params,
+                        headers,
+                    })
+                        .catch((e) => {
+                        this.logger.error(formatErrors(e));
+                        throw e;
+                    });
+                }),
+                /**
+                 * {@link https://open.feishu.cn/api-explorer?project=im&resource=message&apiName=reply&version=v1 click to debug }
+                 *
+                 * {@link https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/im-v1/message/reply document }
+                 *
+                 * 通过模版消息卡片回复消息
+                 *
+                 * 注意事项:;- 需要开启[机器人能力](https://open.feishu.cn/document/uAjLw4CM/ugTN1YjL4UTN24CO1UjN/trouble-shooting/how-to-enable-bot-ability)  ;- 回复私聊消息，需要机器人对用户有[可用性](https://open.feishu.cn/document/home/introduction-to-scope-and-authorization/availability);- 回复群组消息，需要机器人在群中
+                 */
+                replyByCard: (payload, options) => __awaiter(this, void 0, void 0, function* () {
+                    const { headers, params, data, path } = yield this.formatPayload(payload, options);
+                    const { template_id, template_variable } = data, rest = __rest(data, ["template_id", "template_variable"]);
+                    const targetData = Object.assign({ msg_type: "interactive", content: JSON.stringify({
+                            type: "template",
+                            data: {
+                                template_id: template_id,
+                                template_variable: template_variable,
+                            },
+                        }) }, rest);
+                    return this.httpInstance
+                        .request({
+                        url: fillApiPath(`${this.domain}/open-apis/im/v1/messages/:message_id/reply`, path),
+                        method: "POST",
+                        data: targetData,
+                        params,
+                        headers,
+                    })
+                        .catch((e) => {
+                        this.logger.error(formatErrors(e));
+                        throw e;
+                    });
+                }),
             },
             /**
              * 消息 - 表情回复
@@ -22027,4 +22091,31 @@ const adaptKoaRouter = (dispatcher, options) => (ctx, next) => __awaiter(void 0,
     yield next();
 });
 
-export { AESCipher, AppType, CAppTicket, CTenantAccessToken, CardActionHandler, Client, Domain, EventDispatcher, LoggerLevel, adaptDefault, adaptExpress, adaptKoa, adaptKoaRouter, defaultHttpInstance, generateChallenge, withAll, withHelpDeskCredential, withTenantKey, withTenantToken, withUserAccessToken };
+const defaultCard = (variables) => {
+    const { title, content } = variables;
+    return JSON.stringify({
+        "config": {
+            "wide_screen_mode": true
+        },
+        "elements": [
+            {
+                "tag": "markdown",
+                "content": content
+            }
+        ],
+        "header": {
+            "template": "blue",
+            "title": {
+                "content": title,
+                "tag": "plain_text"
+            }
+        }
+    });
+};
+
+var messageCard = /*#__PURE__*/Object.freeze({
+    __proto__: null,
+    defaultCard: defaultCard
+});
+
+export { AESCipher, AppType, CAppTicket, CTenantAccessToken, CardActionHandler, Client, Domain, EventDispatcher, LoggerLevel, adaptDefault, adaptExpress, adaptKoa, adaptKoaRouter, defaultHttpInstance, generateChallenge, messageCard, withAll, withHelpDeskCredential, withTenantKey, withTenantToken, withUserAccessToken };

package/lib/index.js

@@ -14966,6 +14966,70 @@ class Client$1 {
                         throw e;
                     });
                 }),
+                /**
+                 * {@link https://open.feishu.cn/api-explorer?project=im&resource=message&apiName=create&version=v1 click to debug }
+                 *
+                 * {@link https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/im-v1/message/create document }
+                 *
+                 * 通过模版消息卡片发送消息
+                 *
+                 * 注意事项:;- 需要开启[机器人能力](https://open.feishu.cn/document/uAjLw4CM/ugTN1YjL4UTN24CO1UjN/trouble-shooting/how-to-enable-bot-ability)  ;- 给用户发送消息，需要机器人对用户有[可用性](https://open.feishu.cn/document/home/introduction-to-scope-and-authorization/availability);- 给群组发送消息，需要机器人在群组中
+                 */
+                createByCard: (payload, options) => __awaiter(this, void 0, void 0, function* () {
+                    const { headers, params, data, path } = yield this.formatPayload(payload, options);
+                    const { template_id, template_variable } = data, rest = __rest(data, ["template_id", "template_variable"]);
+                    const targetData = Object.assign({ msg_type: "interactive", content: JSON.stringify({
+                            type: "template",
+                            data: {
+                                template_id: template_id,
+                                template_variable: template_variable,
+                            },
+                        }) }, rest);
+                    return this.httpInstance
+                        .request({
+                        url: fillApiPath(`${this.domain}/open-apis/im/v1/messages`, path),
+                        method: "POST",
+                        data: targetData,
+                        params,
+                        headers,
+                    })
+                        .catch((e) => {
+                        this.logger.error(formatErrors(e));
+                        throw e;
+                    });
+                }),
+                /**
+                 * {@link https://open.feishu.cn/api-explorer?project=im&resource=message&apiName=reply&version=v1 click to debug }
+                 *
+                 * {@link https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/im-v1/message/reply document }
+                 *
+                 * 通过模版消息卡片回复消息
+                 *
+                 * 注意事项:;- 需要开启[机器人能力](https://open.feishu.cn/document/uAjLw4CM/ugTN1YjL4UTN24CO1UjN/trouble-shooting/how-to-enable-bot-ability)  ;- 回复私聊消息，需要机器人对用户有[可用性](https://open.feishu.cn/document/home/introduction-to-scope-and-authorization/availability);- 回复群组消息，需要机器人在群中
+                 */
+                replyByCard: (payload, options) => __awaiter(this, void 0, void 0, function* () {
+                    const { headers, params, data, path } = yield this.formatPayload(payload, options);
+                    const { template_id, template_variable } = data, rest = __rest(data, ["template_id", "template_variable"]);
+                    const targetData = Object.assign({ msg_type: "interactive", content: JSON.stringify({
+                            type: "template",
+                            data: {
+                                template_id: template_id,
+                                template_variable: template_variable,
+                            },
+                        }) }, rest);
+                    return this.httpInstance
+                        .request({
+                        url: fillApiPath(`${this.domain}/open-apis/im/v1/messages/:message_id/reply`, path),
+                        method: "POST",
+                        data: targetData,
+                        params,
+                        headers,
+                    })
+                        .catch((e) => {
+                        this.logger.error(formatErrors(e));
+                        throw e;
+                    });
+                }),
             },
             /**
              * 消息 - 表情回复
@@ -22042,6 +22106,33 @@ const adaptKoaRouter = (dispatcher, options) => (ctx, next) => __awaiter(void 0,
     yield next();
 });
 
+const defaultCard = (variables) => {
+    const { title, content } = variables;
+    return JSON.stringify({
+        "config": {
+            "wide_screen_mode": true
+        },
+        "elements": [
+            {
+                "tag": "markdown",
+                "content": content
+            }
+        ],
+        "header": {
+            "template": "blue",
+            "title": {
+                "content": title,
+                "tag": "plain_text"
+            }
+        }
+    });
+};
+
+var messageCard = /*#__PURE__*/Object.freeze({
+    __proto__: null,
+    defaultCard: defaultCard
+});
+
 exports.AESCipher = AESCipher;
 exports.CAppTicket = CAppTicket;
 exports.CTenantAccessToken = CTenantAccessToken;
@@ -22054,6 +22145,7 @@ exports.adaptKoa = adaptKoa;
 exports.adaptKoaRouter = adaptKoaRouter;
 exports.defaultHttpInstance = defaultHttpInstance;
 exports.generateChallenge = generateChallenge;
+exports.messageCard = messageCard;
 exports.withAll = withAll;
 exports.withHelpDeskCredential = withHelpDeskCredential;
 exports.withTenantKey = withTenantKey;

package/package.json

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

package/types/index.d.ts

@@ -46474,6 +46474,107 @@ declare abstract class Client$1 {
                     invalid_user_id_list: Array<string>;
                 } | undefined;
             }>;
+            /**
+             * {@link https://open.feishu.cn/api-explorer?project=im&resource=message&apiName=create&version=v1 click to debug }
+             *
+             * {@link https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/im-v1/message/create document }
+             *
+             * 通过模版消息卡片发送消息
+             *
+             * 注意事项:;- 需要开启[机器人能力](https://open.feishu.cn/document/uAjLw4CM/ugTN1YjL4UTN24CO1UjN/trouble-shooting/how-to-enable-bot-ability)  ;- 给用户发送消息，需要机器人对用户有[可用性](https://open.feishu.cn/document/home/introduction-to-scope-and-authorization/availability);- 给群组发送消息，需要机器人在群组中
+             */
+            createByCard: (payload?: {
+                data: {
+                    receive_id: string;
+                    uuid?: string;
+                    template_id: string;
+                    template_variable?: Record<string, any>;
+                };
+                params: {
+                    receive_id_type: "open_id" | "user_id" | "union_id" | "email" | "chat_id";
+                };
+            }, options?: IRequestOptions$1) => Promise<{
+                code?: number | undefined;
+                msg?: string | undefined;
+                data?: {
+                    message_id?: string | undefined;
+                    root_id?: string | undefined;
+                    parent_id?: string | undefined;
+                    msg_type?: string | undefined;
+                    create_time?: string | undefined;
+                    update_time?: string | undefined;
+                    deleted?: boolean | undefined;
+                    updated?: boolean | undefined;
+                    chat_id?: string | undefined;
+                    sender?: {
+                        id: string;
+                        id_type: string;
+                        sender_type: string;
+                        tenant_key?: string | undefined;
+                    } | undefined;
+                    body?: {
+                        content: string;
+                    } | undefined;
+                    mentions?: {
+                        key: string;
+                        id: string;
+                        id_type: string;
+                        name: string;
+                        tenant_key?: string | undefined;
+                    }[] | undefined;
+                    upper_message_id?: string | undefined;
+                } | undefined;
+            }>;
+            /**
+             * {@link https://open.feishu.cn/api-explorer?project=im&resource=message&apiName=reply&version=v1 click to debug }
+             *
+             * {@link https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/im-v1/message/reply document }
+             *
+             * 通过模版消息卡片回复消息
+             *
+             * 注意事项:;- 需要开启[机器人能力](https://open.feishu.cn/document/uAjLw4CM/ugTN1YjL4UTN24CO1UjN/trouble-shooting/how-to-enable-bot-ability)  ;- 回复私聊消息，需要机器人对用户有[可用性](https://open.feishu.cn/document/home/introduction-to-scope-and-authorization/availability);- 回复群组消息，需要机器人在群中
+             */
+            replyByCard: (payload?: {
+                data: {
+                    uuid?: string;
+                    template_id: string;
+                    template_variable?: Record<string, any>;
+                };
+                path: {
+                    message_id: string;
+                };
+            }, options?: IRequestOptions$1) => Promise<{
+                code?: number | undefined;
+                msg?: string | undefined;
+                data?: {
+                    message_id?: string | undefined;
+                    root_id?: string | undefined;
+                    parent_id?: string | undefined;
+                    msg_type?: string | undefined;
+                    create_time?: string | undefined;
+                    update_time?: string | undefined;
+                    deleted?: boolean | undefined;
+                    updated?: boolean | undefined;
+                    chat_id?: string | undefined;
+                    sender?: {
+                        id: string;
+                        id_type: string;
+                        sender_type: string;
+                        tenant_key?: string | undefined;
+                    } | undefined;
+                    body?: {
+                        content: string;
+                    } | undefined;
+                    mentions?: {
+                        key: string;
+                        id: string;
+                        id_type: string;
+                        name: string;
+                        tenant_key?: string | undefined;
+                    }[] | undefined;
+                    upper_message_id?: string | undefined;
+                } | undefined;
+            }>;
         };
         /**
          * 消息 - 表情回复
@@ -58851,4 +58952,16 @@ interface InteractiveCardSelectMenuActionItem extends InteractiveCardActionBaseI
     value?: Record<string, any>;
 }
 
-export { AESCipher, AppType, CAppTicket, CTenantAccessToken, Cache, CardActionHandler, Client, Domain, EventDispatcher, IHandles as EventHandles, HttpInstance, HttpRequestOptions, InteractiveCard, InteractiveCardActionEvent, InteractiveCardActionItem, InteractiveCardButtonActionItem, InteractiveCardDatePickerActionItem, InteractiveCardDivElement, InteractiveCardDividerElement, InteractiveCardElement, InteractiveCardField, InteractiveCardImageElement, InteractiveCardImageItem, InteractiveCardLarkMdItem, InteractiveCardMarkdownElement, InteractiveCardNoteElement, InteractiveCardOverflowActionItem, InteractiveCardPlainTextItem, InteractiveCardSelectMenuActionItem, InteractiveCardTextItem, InteractiveCardTitle, InteractiveCardUrlItem, InterfaceCardActionElement, LoggerLevel, adaptDefault, adaptExpress, adaptKoa, adaptKoaRouter, defaultHttpInstance, generateChallenge, withAll, withHelpDeskCredential, withTenantKey, withTenantToken, withUserAccessToken };
+declare const defaultCard: (variables: {
+    title: string;
+    content: string;
+}) => string;
+
+declare const messageCard_defaultCard: typeof defaultCard;
+declare namespace messageCard {
+  export {
+    messageCard_defaultCard as defaultCard,
+  };
+}
+
+export { AESCipher, AppType, CAppTicket, CTenantAccessToken, Cache, CardActionHandler, Client, Domain, EventDispatcher, IHandles as EventHandles, HttpInstance, HttpRequestOptions, InteractiveCard, InteractiveCardActionEvent, InteractiveCardActionItem, InteractiveCardButtonActionItem, InteractiveCardDatePickerActionItem, InteractiveCardDivElement, InteractiveCardDividerElement, InteractiveCardElement, InteractiveCardField, InteractiveCardImageElement, InteractiveCardImageItem, InteractiveCardLarkMdItem, InteractiveCardMarkdownElement, InteractiveCardNoteElement, InteractiveCardOverflowActionItem, InteractiveCardPlainTextItem, InteractiveCardSelectMenuActionItem, InteractiveCardTextItem, InteractiveCardTitle, InteractiveCardUrlItem, InterfaceCardActionElement, LoggerLevel, adaptDefault, adaptExpress, adaptKoa, adaptKoaRouter, defaultHttpInstance, generateChallenge, messageCard, withAll, withHelpDeskCredential, withTenantKey, withTenantToken, withUserAccessToken };