@larksuiteoapi/node-sdk 1.2.3 → 1.3.0

package/README.md

@@ -403,6 +403,32 @@ const resule = await dispatcher.invoke(data);
 server.sendResult(result);
 ````
 
+#### challenge校验
+When configuring the event request address, The Open Platform will push a POST request in `application/json` format to the request address. The POST request is used to verify the validity of the configured request address, and the request body will carry a `challenge` field , **The application needs to return the received challenge value to the Open Platform within 1 second**. See: [ Document](https://open.feishu.cn/document/ukTMukTMukTM/uYDNxYjL2QTM24iN0EjN/event-subscription-configure-/request-url-configuration-case)
+
+The adapter provided by the sdk above encapsulates the verification logic. Set the `autoChallenge` field in the options parameter to true to enable:
+```typescript
+// adaptDefault
+lark.adaptDefault('/webhook/event', eventDispatcher, {
+    autoChallenge: true,
+});
+// express
+lark.adaptExpress(eventDispatcher, {
+    autoChallenge: true,
+});
+// koa
+lark.adaptKoa('/webhook/event', eventDispatcher, {
+    autoChallenge: true,
+});
+// koa-router
+router.post(
+    '/webhook/event',
+    lark.adaptKoaRouter(eventDispatcher, {
+        autoChallenge: true,
+    })
+);
+```
+
 ### [Message Card](https://open.feishu.cn/document/ukTMukTMukTM/uczM3QjL3MzN04yNzcDN)
 The processing of the Message Card is also a kind of Event processing. The only difference between the two is that the processor of the Message Card is used to respond to the events generated by the interaction between the user and the Message Card. If the processor has a return value (*the value structure should be in line with the structure defined by [Message Card Structure](https://open.feishu.cn/document/ukTMukTMukTM/uEjNwUjLxYDM14SM2ATN)*), then the return value is used to update the responded message card:
 
@@ -443,6 +469,10 @@ import * as lark from '@larksuiteoapi/node-sdk';
 
 new lark.AESCipher('encrypt key').decrypt('content');
 ````
+
+## Blog
+[ISV Application Development Guide](https://bytedance.feishu.cn/docx/RUZKdGwdyoH4KexMJgDcITQnn0b)
+
 ## LICENSE
 MIT
 

package/README.zh.md

@@ -402,6 +402,32 @@ const resule = await dispatcher.invoke(data);
 server.sendResult(result);
 ```
 
+#### challenge校验
+在配置事件请求地址时，开放平台会向请求地址推送一个`application/json`格式的 POST请求，该POST请求用于验证所配置的请求地址的合法性，请求体中会携带一个`challenge`字段，**应用需要在 1 秒内，将接收到的challenge值原样返回给飞书开放平台**。详见：[文档](https://open.feishu.cn/document/ukTMukTMukTM/uYDNxYjL2QTM24iN0EjN/event-subscription-configure-/request-url-configuration-case)
+
+上面sdk提供出的适配器内部封装了这部分验证的逻辑，将options参数中的`autoChallenge`字段设为true即可启用：
+```typescript
+// adaptDefault
+lark.adaptDefault('/webhook/event', eventDispatcher, {
+    autoChallenge: true,
+});
+// express
+lark.adaptExpress(eventDispatcher, {
+    autoChallenge: true,
+});
+// koa
+lark.adaptKoa('/webhook/event', eventDispatcher, {
+    autoChallenge: true,
+});
+// koa-router
+router.post(
+    '/webhook/event',
+    lark.adaptKoaRouter(eventDispatcher, {
+        autoChallenge: true,
+    })
+);
+```
+
 ### [消息卡片](https://open.feishu.cn/document/ukTMukTMukTM/uczM3QjL3MzN04yNzcDN)
 对消息卡片的处理亦是对事件处理的一种，两者的不同点仅在于消息卡片的处理器用于响应用户与消息卡片交互所产生的事件，若处理器有返回值（*返回值的数据结构理应为符合[消息卡片结构](https://open.feishu.cn/document/ukTMukTMukTM/uEjNwUjLxYDM14SM2ATN)所定义的结构*），则返回值被用来更新被响应的消息卡片：
 
@@ -442,6 +468,10 @@ import * as lark from '@larksuiteoapi/node-sdk';
 
 new lark.AESCipher('encrypt key').decrypt('content');
 ```
+
+## Blog
+[ISV（商店应用）开发指南](https://bytedance.feishu.cn/docx/RUZKdGwdyoH4KexMJgDcITQnn0b)
+
 ## 许可协议
 MIT
 

package/es/index.js

@@ -19214,13 +19214,40 @@ const pickRequestData = (req) => new Promise((resolve) => {
     });
 });
 
-const adaptDefault = (path, dispatcher) => (req, res) => __awaiter(void 0, void 0, void 0, function* () {
+const generateChallenge = (data, options) => {
+    if ('encrypt' in data && !options.encryptKey) {
+        throw new Error('auto-challenge need encryptKey, please check for missing in dispatcher');
+    }
+    const targetData = 'encrypt' in data
+        ? JSON.parse(new AESCipher(options.encryptKey).decrypt(data.encrypt))
+        : data;
+    return {
+        isChallenge: targetData.type === 'url_verification',
+        challenge: {
+            challenge: targetData.challenge,
+        },
+    };
+};
+
+const adaptDefault = (path, dispatcher, options) => (req, res) => __awaiter(void 0, void 0, void 0, function* () {
     if (req.url !== path) {
         return;
     }
     const data = Object.assign(Object.create({
         headers: req.headers,
     }), yield pickRequestData(req));
+    // 是否自动响应challange事件：
+    // https://open.feishu.cn/document/ukTMukTMukTM/uYDNxYjL2QTM24iN0EjN/event-subscription-configure-/request-url-configuration-case
+    const autoChallenge = get(options, 'autoChallenge', false);
+    if (autoChallenge) {
+        const { isChallenge, challenge } = generateChallenge(data, {
+            encryptKey: dispatcher.encryptKey,
+        });
+        if (isChallenge) {
+            res.end(JSON.stringify(challenge));
+            return;
+        }
+    }
     const value = yield dispatcher.invoke(data);
     // event don't need response
     if (dispatcher instanceof CardActionHandler) {
@@ -19244,6 +19271,18 @@ const adaptExpress = (dispatcher, options) => (req, res) => __awaiter(void 0, vo
     const data = Object.assign(Object.create({
         headers: req.headers,
     }), reqData);
+    // 是否自动响应challange事件：
+    // https://open.feishu.cn/document/ukTMukTMukTM/uYDNxYjL2QTM24iN0EjN/event-subscription-configure-/request-url-configuration-case
+    const autoChallenge = get(options, 'autoChallenge', false);
+    if (autoChallenge) {
+        const { isChallenge, challenge } = generateChallenge(data, {
+            encryptKey: dispatcher.encryptKey,
+        });
+        if (isChallenge) {
+            res.json(challenge);
+            return;
+        }
+    }
     const value = yield dispatcher.invoke(data);
     // event don't need response
     if (dispatcher instanceof CardActionHandler) {
@@ -19269,6 +19308,19 @@ const adaptKoa = (path, dispatcher, options) => (ctx, next) => __awaiter(void 0,
         const data = Object.assign(Object.create({
             headers: req.headers,
         }), reqData);
+        // 是否自动响应challange事件：
+        // https://open.feishu.cn/document/ukTMukTMukTM/uYDNxYjL2QTM24iN0EjN/event-subscription-configure-/request-url-configuration-case
+        const autoChallenge = get(options, 'autoChallenge', false);
+        if (autoChallenge) {
+            const { isChallenge, challenge } = generateChallenge(data, {
+                encryptKey: dispatcher.encryptKey,
+            });
+            if (isChallenge) {
+                ctx.body = challenge;
+                yield next();
+                return;
+            }
+        }
         const value = yield dispatcher.invoke(data);
         // event don't need response
         if (dispatcher instanceof CardActionHandler) {
@@ -19297,6 +19349,19 @@ const adaptKoaRouter = (dispatcher, options) => (ctx, next) => __awaiter(void 0,
     const data = Object.assign(Object.create({
         headers: req.headers,
     }), reqData);
+    // 是否自动响应challange事件：
+    // https://open.feishu.cn/document/ukTMukTMukTM/uYDNxYjL2QTM24iN0EjN/event-subscription-configure-/request-url-configuration-case
+    const autoChallenge = get(options, 'autoChallenge', false);
+    if (autoChallenge) {
+        const { isChallenge, challenge } = generateChallenge(data, {
+            encryptKey: dispatcher.encryptKey,
+        });
+        if (isChallenge) {
+            ctx.body = challenge;
+            yield next();
+            return;
+        }
+    }
     const value = yield dispatcher.invoke(data);
     // event don't need response
     if (dispatcher instanceof CardActionHandler) {

package/lib/index.js

@@ -19229,13 +19229,40 @@ const pickRequestData = (req) => new Promise((resolve) => {
     });
 });
 
-const adaptDefault = (path, dispatcher) => (req, res) => __awaiter(void 0, void 0, void 0, function* () {
+const generateChallenge = (data, options) => {
+    if ('encrypt' in data && !options.encryptKey) {
+        throw new Error('auto-challenge need encryptKey, please check for missing in dispatcher');
+    }
+    const targetData = 'encrypt' in data
+        ? JSON.parse(new AESCipher(options.encryptKey).decrypt(data.encrypt))
+        : data;
+    return {
+        isChallenge: targetData.type === 'url_verification',
+        challenge: {
+            challenge: targetData.challenge,
+        },
+    };
+};
+
+const adaptDefault = (path, dispatcher, options) => (req, res) => __awaiter(void 0, void 0, void 0, function* () {
     if (req.url !== path) {
         return;
     }
     const data = Object.assign(Object.create({
         headers: req.headers,
     }), yield pickRequestData(req));
+    // 是否自动响应challange事件：
+    // https://open.feishu.cn/document/ukTMukTMukTM/uYDNxYjL2QTM24iN0EjN/event-subscription-configure-/request-url-configuration-case
+    const autoChallenge = get__default["default"](options, 'autoChallenge', false);
+    if (autoChallenge) {
+        const { isChallenge, challenge } = generateChallenge(data, {
+            encryptKey: dispatcher.encryptKey,
+        });
+        if (isChallenge) {
+            res.end(JSON.stringify(challenge));
+            return;
+        }
+    }
     const value = yield dispatcher.invoke(data);
     // event don't need response
     if (dispatcher instanceof CardActionHandler) {
@@ -19259,6 +19286,18 @@ const adaptExpress = (dispatcher, options) => (req, res) => __awaiter(void 0, vo
     const data = Object.assign(Object.create({
         headers: req.headers,
     }), reqData);
+    // 是否自动响应challange事件：
+    // https://open.feishu.cn/document/ukTMukTMukTM/uYDNxYjL2QTM24iN0EjN/event-subscription-configure-/request-url-configuration-case
+    const autoChallenge = get__default["default"](options, 'autoChallenge', false);
+    if (autoChallenge) {
+        const { isChallenge, challenge } = generateChallenge(data, {
+            encryptKey: dispatcher.encryptKey,
+        });
+        if (isChallenge) {
+            res.json(challenge);
+            return;
+        }
+    }
     const value = yield dispatcher.invoke(data);
     // event don't need response
     if (dispatcher instanceof CardActionHandler) {
@@ -19284,6 +19323,19 @@ const adaptKoa = (path, dispatcher, options) => (ctx, next) => __awaiter(void 0,
         const data = Object.assign(Object.create({
             headers: req.headers,
         }), reqData);
+        // 是否自动响应challange事件：
+        // https://open.feishu.cn/document/ukTMukTMukTM/uYDNxYjL2QTM24iN0EjN/event-subscription-configure-/request-url-configuration-case
+        const autoChallenge = get__default["default"](options, 'autoChallenge', false);
+        if (autoChallenge) {
+            const { isChallenge, challenge } = generateChallenge(data, {
+                encryptKey: dispatcher.encryptKey,
+            });
+            if (isChallenge) {
+                ctx.body = challenge;
+                yield next();
+                return;
+            }
+        }
         const value = yield dispatcher.invoke(data);
         // event don't need response
         if (dispatcher instanceof CardActionHandler) {
@@ -19312,6 +19364,19 @@ const adaptKoaRouter = (dispatcher, options) => (ctx, next) => __awaiter(void 0,
     const data = Object.assign(Object.create({
         headers: req.headers,
     }), reqData);
+    // 是否自动响应challange事件：
+    // https://open.feishu.cn/document/ukTMukTMukTM/uYDNxYjL2QTM24iN0EjN/event-subscription-configure-/request-url-configuration-case
+    const autoChallenge = get__default["default"](options, 'autoChallenge', false);
+    if (autoChallenge) {
+        const { isChallenge, challenge } = generateChallenge(data, {
+            encryptKey: dispatcher.encryptKey,
+        });
+        if (isChallenge) {
+            ctx.body = challenge;
+            yield next();
+            return;
+        }
+    }
     const value = yield dispatcher.invoke(data);
     // event don't need response
     if (dispatcher instanceof CardActionHandler) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@larksuiteoapi/node-sdk",
-  "version": "1.2.3",
+  "version": "1.3.0",
   "description": "larksuite open sdk for nodejs",
   "keywords": [
     "feishu",
@@ -37,26 +37,31 @@
     "lodash.pickby": "^4.6.0"
   },
   "devDependencies": {
-    "@typescript-eslint/parser": "^5.27.1",
+    "@koa/router": "^12.0.0",
     "@rollup/plugin-alias": "^3.1.9",
     "@rollup/plugin-typescript": "^8.3.2",
     "@types/jest": "^28.1.3",
     "@types/lodash.get": "^4.4.7",
     "@types/lodash.merge": "^4.6.7",
     "@types/lodash.pick": "^4.4.7",
+    "@typescript-eslint/parser": "^5.27.1",
+    "body-parser": "^1.20.1",
     "eslint": "^8.17.0",
     "eslint-config-airbnb-base": "^15.0.0",
     "eslint-config-prettier": "^8.5.0",
     "eslint-plugin-import": "^2.26.0",
-    "prettier": "2.6.2",
+    "express": "^4.18.2",
     "jest": "^28.1.1",
+    "koa": "^2.13.4",
+    "koa-body": "^5.0.0",
+    "prettier": "2.6.2",
     "rollup": "^2.75.5",
     "rollup-plugin-dts": "^4.2.2",
     "rollup-plugin-license": "^2.8.1",
     "ts-jest": "^28.0.5",
+    "ts-node": "^10.8.1",
     "tsconfig-paths": "^4.0.0",
     "tslib": "^2.4.0",
-    "ts-node": "^10.8.1",
     "typescript": "^4.7.3"
   },
   "publishConfig": {

package/types/index.d.ts

@@ -39443,18 +39443,23 @@ declare class CardActionHandler {
     invoke(data: any): Promise<any>;
 }
 
-declare const adaptDefault: (path: string, dispatcher: EventDispatcher | CardActionHandler) => (req: any, res: any) => Promise<void>;
+declare const adaptDefault: (path: string, dispatcher: EventDispatcher | CardActionHandler, options?: {
+    autoChallenge?: boolean;
+}) => (req: any, res: any) => Promise<void>;
 
 declare const adaptExpress: (dispatcher: EventDispatcher | CardActionHandler, options?: {
     logger?: Logger;
+    autoChallenge?: boolean;
 }) => (req: any, res: any) => Promise<void>;
 
 declare const adaptKoa: (path: string, dispatcher: EventDispatcher | CardActionHandler, options?: {
     logger?: Logger;
+    autoChallenge?: boolean;
 }) => (ctx: any, next: any) => Promise<void>;
 
 declare const adaptKoaRouter: (dispatcher: EventDispatcher | CardActionHandler, options?: {
     logger?: Logger;
+    autoChallenge?: boolean;
 }) => (ctx: any, next: any) => Promise<void>;
 
 export { AESCipher, AppType, CAppTicket, CardActionHandler, Client, Domain, EventDispatcher, IHandles as EventHandles, LoggerLevel, adaptDefault, adaptExpress, adaptKoa, adaptKoaRouter, withAll, withHelpDeskCredential, withTenantKey, withTenantToken, withUserAccessToken };