dingtalk-stream 2.1.2 → 2.1.4

package/README.md

@@ -1,114 +1,39 @@
-# dingtalk-stream
-Nodejs SDK for DingTalk Stream Mode API, Compared with the webhook mode, it is easier to access the DingTalk chatbot
 钉钉支持 Stream 模式接入事件推送、机器人收消息以及卡片回调，该 SDK 实现了 Stream 模式。相比 Webhook 模式，Stream 模式可以更简单的接入各类事件和回调。
 
-## 快速开始
-npm ii
-npm start
-
-### 准备工作
-
-* Nodejs 开发环境，https://midwayjs.org/docs/how_to_install_nodejs
-* 需要Node version >= 18.17.1
-* 钉钉开发者账号，具备创建企业内部应用的权限，详见[成为钉钉开发者](https://open.dingtalk.com/document/orgapp/become-a-dingtalk-developer)
-
-### 快速开始指南
-
-1、创建企业内部应用
+## 开发教程
 
-进入[钉钉开发者后台](https://open-dev.dingtalk.com/)，创建企业内部应用，获取ClientID（即 AppKey）和ClientSecret（ 即AppSecret）。
+在 [教程文档](https://opensource.dingtalk.com/developerpedia/docs/explore/tutorials/stream/overview) 中，你可以找到钉钉 Stream 模式的教程文档和示例代码。
 
-发布应用：在开发者后台左侧导航中，点击“版本管理与发布”，点击“确认发布”，并在接下来的可见范围设置中，选择“全部员工”，或者按需选择部分员工。
+### 参考资料
 
+* [Stream 模式说明](https://opensource.dingtalk.com/developerpedia/docs/learn/stream/overview)
+* [教程文档](https://opensource.dingtalk.com/developerpedia/docs/explore/tutorials/stream/overview)
+* [常见问题](https://opensource.dingtalk.com/developerpedia/docs/learn/stream/faq)
+* [Stream 模式共创群](https://opensource.dingtalk.com/developerpedia/docs/explore/support/?via=moon-group)
 
-2、Stream 模式的机器人（可选）
+### 调试方法
 
-如果不需要使用机器人功能的话，可以不用创建。
-
-在应用管理的左侧导航中，选择“消息推送”，打开机器人能力，设置机器人基本信息。
+1、创建企业内部应用
 
-注意：消息接收模式中，选择 “Stream 模式”
+进入钉钉开发者后台，创建企业内部应用，获取ClientID（即 AppKey）和ClientSecret（ 即AppSecret）。
 
-![Stream 模式](https://img.alicdn.com/imgextra/i3/O1CN01XL4piO1lkYX2F6sW6_!!6000000004857-0-tps-896-522.jpg)
+2、开通Stream 模式的机器人
 
-点击“点击调试”按钮，可以创建测试群进行测试。
+进入开发者后台新建的应用，点击应用能力 - 添加应用能力 - 机器人，完善机器人信息，选择stream模式并发布。
 
 3、使用demo项目测试，启动服务：
 
-a、获取demo项目 
-```Shell
+a、获取demo项目
+
  git clone git@github.com:open-dingtalk/dingtalk-stream-sdk-nodejs.git
-```
 b、在example/config.json里配置应用信息。
 
 c、启动测试case
-```Shell
-cd dingtalk-stream
+
+cd dingtalk-stream-sdk-nodejs
 yarn
 npm run build
 npm start
-```
-
-4、在项目中引用sdk，安装 dingtalk-stream
-
-```Shell
-npm i dingtalk-stream
-```
-
-代码中使用
-```javascript
-const DWClient = require("dingtalk-stream");
-const config = require("./config.json");
-
-const client = new DWClient({
-  clientId: config.clientId,
-  clientSecret: config.clientSecret,
-  debug: true // 开启调试信息，默认关闭
-});
-client.registerCallbackListener('/v1.0/im/bot/messages/get', async (res) => {
-    // 注册机器人回调事件
-    console.log("收到消息");
-    const {messageId} = res.headers;
-    const { text, senderStaffId, sessionWebhook } = JSON.parse(res.data);
-  })
-  .registerCallbackListener(
-    '/v1.0/graph/api/invoke',
-    async (res: DWClientDownStream) => {
-      // 注册AI插件回调事件
-      console.log("收到ai消息");
-      const { messageId } = res.headers;
-
-      // 添加业务逻辑
-      console.log(res);
-      console.log(JSON.parse(res.data));
-
-      // 通过Stream返回数据
-      client.sendGraphAPIResponse(messageId, {
-        response: {
-          statusLine: {
-            code: 200,
-            reasonPhrase: "OK",
-          },
-          headers: {},
-          body: JSON.stringify({
-            text: "你好",
-          }),
-        },
-      });
-    }
-  )
-  .connect();
-```
-
-### 事件订阅切换到 Stream 模式（可选）
-
-进入钉钉开发者后台，选择企业内部应用，在应用管理的左侧导航中，选择“事件与回调”。
-“订阅管理”中，“推送方式”选项中，选择 “Stream 模式”，并保存
-
-### AI 应用 - 技能插件，Graph API 类型插件使用 （可选）
-
-配置好魔法棒应用，并在技能中使用了Graph API类型插件。
-
-### 技术支持
-
-[点击链接，加入Stream模式共创群交流](https://open-dingtalk.github.io/developerpedia/docs/explore/support/?via=moon-group)
+
+
+注意：ts-node-esm启动ts文件调试时，ts文件内import引用的文件后缀必须是js，ts会报找不到模块异常。

package/dist/client.cjs

@@ -85,46 +85,47 @@ class DWClient extends EventEmitter {
     this.on(eventId, callback);
     return this;
   }
-  async getEndpoint() {
-    this.printDebug("get connect endpoint by config");
-    this.printDebug(this.config);
+  async getAccessToken() {
     const result = await axios.get(
       `${constants.GET_TOKEN_URL}?appkey=${this.config.clientId}&appsecret=${this.config.clientSecret}`
     );
     if (result.status === 200 && result.data.access_token) {
       this.config.access_token = result.data.access_token;
-      const res = await axios({
-        url: constants.GATEWAY_URL,
-        method: "POST",
-        responseType: "json",
-        data: {
-          clientId: this.config.clientId,
-          clientSecret: this.config.clientSecret,
-          ua: this.config.ua,
-          subscriptions: this.config.subscriptions
-        },
-        headers: {
-          // 这个接口得加个，否则默认返回的会是xml
-          Accept: "application/json",
-          "access-token": result.data.access_token
-          // 'd136e657-5998-4cc4-a055-2b7ceab0f212'
-        }
-      });
-      this.printDebug("res.data " + JSON.stringify(res.data));
-      if (res.data) {
-        this.config.endpoint = res.data;
-        const { endpoint, ticket } = res.data;
-        if (!endpoint || !ticket) {
-          this.printDebug("endpoint or ticket is null");
-          throw new Error("endpoint or ticket is null");
-        }
-        this.dw_url = `${endpoint}?ticket=${ticket}`;
-        return this;
-      } else {
-        throw new Error("build: get endpoint failed");
+      return result.data.access_token;
+    } else {
+      throw new Error("getAccessToken: get access_token failed");
+    }
+  }
+  async getEndpoint() {
+    this.printDebug("get connect endpoint by config");
+    this.printDebug(this.config);
+    const res = await axios({
+      url: constants.GATEWAY_URL,
+      method: "POST",
+      responseType: "json",
+      data: {
+        clientId: this.config.clientId,
+        clientSecret: this.config.clientSecret,
+        ua: this.config.ua,
+        subscriptions: this.config.subscriptions
+      },
+      headers: {
+        // 这个接口得加个，否则默认返回的会是xml
+        Accept: "application/json"
+      }
+    });
+    this.printDebug("res.data " + JSON.stringify(res.data));
+    if (res.data) {
+      this.config.endpoint = res.data;
+      const { endpoint, ticket } = res.data;
+      if (!endpoint || !ticket) {
+        this.printDebug("endpoint or ticket is null");
+        throw new Error("endpoint or ticket is null");
       }
+      this.dw_url = `${endpoint}?ticket=${ticket}`;
+      return this;
     } else {
-      throw new Error("build: get access_token failed");
+      throw new Error("build: get endpoint failed");
     }
   }
   _connect() {
@@ -194,8 +195,8 @@ class DWClient extends EventEmitter {
   }
   onDownStream(data) {
     this.printDebug("Received message from dingtalk websocket server");
-    this.printDebug(data);
     const msg = JSON.parse(data);
+    this.printDebug(msg);
     switch (msg.type) {
       case "SYSTEM":
         this.onSystem(msg);
@@ -277,6 +278,21 @@ class DWClient extends EventEmitter {
     };
     (_a = this.socket) == null ? void 0 : _a.send(JSON.stringify(msg));
   }
+  /**
+   * 消息响应，避免服务端重试. 
+   * stream模式下，服务端推送消息到client后，会监听client响应，如果消息长时间未响应会在一定时间内(60s)重试推消息，可以通过此方法返回消息响应，避免多次接收服务端消息。
+   * @param messageId
+   * @param result
+   * @returns
+   * @memberof DWClient
+   * @example
+   * ```javascript
+   * client.socketResponse(res.headers.messageId, result.data);
+   * ```
+   */
+  socketCallBackResponse(messageId, result) {
+    this.send(messageId, { response: result });
+  }
   sendGraphAPIResponse(messageId, value) {
     var _a;
     if (!messageId) {

package/dist/client.d.ts

@@ -83,6 +83,7 @@ declare class DWClient extends EventEmitter {
     printDebug(msg: object | string): void;
     registerAllEventListener(onEventReceived: (v: DWClientDownStream) => EventAckData): this;
     registerCallbackListener(eventId: string, callback: (v: DWClientDownStream) => void): this;
+    getAccessToken(): Promise<any>;
     getEndpoint(): Promise<this>;
     _connect(): Promise<void>;
     connect(): Promise<void>;
@@ -93,6 +94,19 @@ declare class DWClient extends EventEmitter {
     onEvent(message: DWClientDownStream): void;
     onCallback(message: DWClientDownStream): void;
     send(messageId: string, value: any): void;
+    /**
+     * 消息响应，避免服务端重试.
+     * stream模式下，服务端推送消息到client后，会监听client响应，如果消息长时间未响应会在一定时间内(60s)重试推消息，可以通过此方法返回消息响应，避免多次接收服务端消息。
+     * @param messageId
+     * @param result
+     * @returns
+     * @memberof DWClient
+     * @example
+     * ```javascript
+     * client.socketResponse(res.headers.messageId, result.data);
+     * ```
+     */
+    socketCallBackResponse(messageId: string, result: any): void;
     sendGraphAPIResponse(messageId: string, value: GraphAPIResponse): void;
 }
 

package/dist/client.mjs

@@ -83,46 +83,47 @@ class DWClient extends EventEmitter {
     this.on(eventId, callback);
     return this;
   }
-  async getEndpoint() {
-    this.printDebug("get connect endpoint by config");
-    this.printDebug(this.config);
+  async getAccessToken() {
     const result = await axios.get(
       `${GET_TOKEN_URL}?appkey=${this.config.clientId}&appsecret=${this.config.clientSecret}`
     );
     if (result.status === 200 && result.data.access_token) {
       this.config.access_token = result.data.access_token;
-      const res = await axios({
-        url: GATEWAY_URL,
-        method: "POST",
-        responseType: "json",
-        data: {
-          clientId: this.config.clientId,
-          clientSecret: this.config.clientSecret,
-          ua: this.config.ua,
-          subscriptions: this.config.subscriptions
-        },
-        headers: {
-          // 这个接口得加个，否则默认返回的会是xml
-          Accept: "application/json",
-          "access-token": result.data.access_token
-          // 'd136e657-5998-4cc4-a055-2b7ceab0f212'
-        }
-      });
-      this.printDebug("res.data " + JSON.stringify(res.data));
-      if (res.data) {
-        this.config.endpoint = res.data;
-        const { endpoint, ticket } = res.data;
-        if (!endpoint || !ticket) {
-          this.printDebug("endpoint or ticket is null");
-          throw new Error("endpoint or ticket is null");
-        }
-        this.dw_url = `${endpoint}?ticket=${ticket}`;
-        return this;
-      } else {
-        throw new Error("build: get endpoint failed");
+      return result.data.access_token;
+    } else {
+      throw new Error("getAccessToken: get access_token failed");
+    }
+  }
+  async getEndpoint() {
+    this.printDebug("get connect endpoint by config");
+    this.printDebug(this.config);
+    const res = await axios({
+      url: GATEWAY_URL,
+      method: "POST",
+      responseType: "json",
+      data: {
+        clientId: this.config.clientId,
+        clientSecret: this.config.clientSecret,
+        ua: this.config.ua,
+        subscriptions: this.config.subscriptions
+      },
+      headers: {
+        // 这个接口得加个，否则默认返回的会是xml
+        Accept: "application/json"
+      }
+    });
+    this.printDebug("res.data " + JSON.stringify(res.data));
+    if (res.data) {
+      this.config.endpoint = res.data;
+      const { endpoint, ticket } = res.data;
+      if (!endpoint || !ticket) {
+        this.printDebug("endpoint or ticket is null");
+        throw new Error("endpoint or ticket is null");
       }
+      this.dw_url = `${endpoint}?ticket=${ticket}`;
+      return this;
     } else {
-      throw new Error("build: get access_token failed");
+      throw new Error("build: get endpoint failed");
     }
   }
   _connect() {
@@ -192,8 +193,8 @@ class DWClient extends EventEmitter {
   }
   onDownStream(data) {
     this.printDebug("Received message from dingtalk websocket server");
-    this.printDebug(data);
     const msg = JSON.parse(data);
+    this.printDebug(msg);
     switch (msg.type) {
       case "SYSTEM":
         this.onSystem(msg);
@@ -275,6 +276,21 @@ class DWClient extends EventEmitter {
     };
     (_a = this.socket) == null ? void 0 : _a.send(JSON.stringify(msg));
   }
+  /**
+   * 消息响应，避免服务端重试. 
+   * stream模式下，服务端推送消息到client后，会监听client响应，如果消息长时间未响应会在一定时间内(60s)重试推消息，可以通过此方法返回消息响应，避免多次接收服务端消息。
+   * @param messageId
+   * @param result
+   * @returns
+   * @memberof DWClient
+   * @example
+   * ```javascript
+   * client.socketResponse(res.headers.messageId, result.data);
+   * ```
+   */
+  socketCallBackResponse(messageId, result) {
+    this.send(messageId, { response: result });
+  }
   sendGraphAPIResponse(messageId, value) {
     var _a;
     if (!messageId) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dingtalk-stream",
-  "version": "2.1.2",
+  "version": "2.1.4",
   "description": "Nodejs SDK for DingTalk Stream Mode API, Compared with the webhook mode, it is easier to access the DingTalk",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",