tmc.js 0.3.2 → 0.3.4

package/README.md

@@ -9,6 +9,12 @@ Events driven and chained Taobao Message Channel(TMC) for NodeJS
 [![downloads](https://img.shields.io/npm/dm/tmc.js)](https://www.npmjs.com/package/tmc.js)
 [![license](https://img.shields.io/npm/l/tmc.js)](https://www.npmjs.com/package/tmc.js)
 
+## 设计
+
+核心包以事件作为驱动，通过注册`TOPIC`回调处理函数，实现了TMC产品服务的消息消费处理能力，同时通过`Proxy`代理，以`TOPIC`作为键值，平序注册消息消费处理函数，序图如下：
+
+[![SDK Sequence](./.github/sdk-sequence.svg)](./.github/sdk-sequence.mmd)
+
 ## 使用
 
 `npm i tmc.js`
@@ -54,6 +60,24 @@ new Tmc('your_app_key', 'your_app_secret')
 
 消费端发起建立连接 `onopen` 事件，`address` 默认为 `ws://mc.api.taobao.com/`。
 
+**`tmc.send(msg: Message, options?: { mask?: true, binary?: true }, cb?: (err: Error) => void) => void`**
+
+实例化后，当自动应答确认消息无法满足需求的时候，比如消息处理失败，需要`Publisher`再次重推消息，在实例初始化时置`options.autoReplyConfirmation=false`，则在消息处理函数内，可以通过 `this.send()` 函数回复`确认`或者`失败`消息。例如：
+
+```js
+new Tmc('your_app_key', 'your_app_secret', { autoReplyConfirmation: false })
+.taobao_trade_TradeDelayConfirmPay(function needDoubleReriesThenConfirm(msg) {
+  if (msg instanceof Message && msg.content?.reried === 0) {
+    this.send(
+      new Message(MessageType.SENDACK, MessageKind.Failed)
+      .with(MessageFields.ID, msg.content?.id)
+      .with(MessageFields.MSG, 'Something went wrong, please retries this ID.')
+    );
+  }
+})
+.connect();
+```
+
 <details><summary>可选设置的 NODE_DEBUG=< label > 环境变量</summary>
 
 | label | 说明 |
@@ -63,7 +87,7 @@ new Tmc('your_app_key', 'your_app_secret')
 | `tmc:onpull` | 开启 `onpull` 时的日志
 | `tmc:onerror` | 开启 `onerror` 时的日志
 | `tmc:onclose` | 开启 `onclose` 时的日志
-| `tmc:onmessage` | 开启全部 `onmessage` 时的日志(即`From`淘宝消息)
+| `tmc:onmessage*` | 开启全部 `onmessage` 时的日志(即`From`淘宝消息)
 | `tmc:onmessage:connect` | 开启消费端发起连接 `connect` 时的日志
 | `tmc:onmessage:connectack` | 开启消费端回复连接 `connectack` 时的日志
 | `tmc:onmessage:send` | 开启消费端接收到(即`From`淘宝) `send` 的消息时的日志

package/lib/consumer.js

@@ -92,6 +92,11 @@ class TaoMessageConsumer extends EventEmitter {
     ).update(sk).digest('hex').toUpperCase();
   }
 
+  /** @since v0.3.4 */
+  send(data, options = { mask: true, binary: true }, cb = undefined) {
+    if (data instanceof Message) { this[kWebSocket]?.send(data.with(TOKEN, this[kToken]).buffer, options, cb); }
+  }
+
   onopen() {
     const now = `${Date.now()}`;
     const msg = new Message(CONNECT)
@@ -104,7 +109,7 @@ class TaoMessageConsumer extends EventEmitter {
 
     logger.onopen(JSONB.stringify(msg));
 
-    this[kWebSocket]?.send(msg.buffer, { mask: true, binary: true });
+    this.send(msg);
 
     if (this[kOptions].intervalId) { clearInterval(this[kOptions].intervalId); }
 
@@ -114,7 +119,7 @@ class TaoMessageConsumer extends EventEmitter {
   onpull() {
     const msg = new Message(SEND, PullRequest).with(TOKEN, this[kToken]);
     logger.onpull(JSONB.stringify(msg));
-    this[kWebSocket]?.send(msg.buffer, { mask: true, binary: true });
+    this.send(msg);
   }
 
   onping(data) {
@@ -142,7 +147,7 @@ class TaoMessageConsumer extends EventEmitter {
     if (this[kOptions].autoReplyConfirmation && msg && msg[CONTENT] && msg[CONTENT][ID]) {
       const reply = new Message(SEND, Confirm).with(TOKEN, this[kToken]).with(ID, msg[CONTENT][ID]);
       logger.onmessage[SEND][Confirm](JSONB.stringify(reply));
-      this[kWebSocket]?.send(reply.buffer, { mask: true, binary: true });
+      this.send(reply);
     }
   }
 
@@ -178,6 +183,7 @@ class TaoMessageConsumer extends EventEmitter {
     if (this[kOptions].intervalId) { this[kOptions].intervalId = clearInterval(this[kOptions].intervalId); }
     if (this[kOptions].timeoutId) { this[kOptions].timeoutId = clearTimeout(this[kOptions].timeoutId); }
 
+    this[kToken] = undefined;
     this[kWebSocket] = undefined;
     this[kOptions].timeoutId = setTimeout(() => this.connect(), ms);
 
@@ -187,16 +193,12 @@ class TaoMessageConsumer extends EventEmitter {
   connect(address) {
     if (address) { this[kAddress] = address; }
 
-    this[kWebSocket]?.close();
-
-    const ws = new WebSocket(this[kAddress]);
-    Reflect.set(this, kWebSocket, ws);
-
-    ws.on('open', () => this.onopen());
-    ws.on('ping', (...arg) => this.onping(...arg));
-    ws.on('error', (err) => this.onerror(err));
-    ws.on('close', (...arg) => this.onclose(...arg));
-    ws.on('message', (...arg) => this.onmessage(...arg));
+    this[kWebSocket] = new WebSocket(this[kAddress])
+      .on('message', (data, isBinary) => this.onmessage(data, isBinary))
+      .on('close', (code, reason) => this.onclose(code, reason))
+      .on('error', (err) => this.onerror(err))
+      .on('ping', (data) => this.onping(data))
+      .on('open', () => this.onopen());
 
     return this;
   }

package/lib/message-fields.js

@@ -12,6 +12,11 @@ const SDK = 'sdk';
 const INTRANET_IP = 'intranet_ip';
 const ID = 'id';
 const TOPIC = 'topic';
+const MSG = 'msg';
+const DATAID = 'dataid';
+const USERID = 'userid';
+const OUTTIME = 'outtime';
+const PUBLISHER = 'publisher';
 
 class MessageFields {
   static TYPE = TYPE;
@@ -41,6 +46,16 @@ class MessageFields {
   static ID = ID;
 
   static TOPIC = TOPIC;
+
+  static MSG = MSG;
+
+  static DATAID = DATAID;
+
+  static USERID = USERID;
+
+  static OUTTIME = OUTTIME;
+
+  static PUBLISHER = PUBLISHER;
 }
 
 module.exports = MessageFields;
@@ -59,3 +74,8 @@ module.exports.SDK = SDK;
 module.exports.INTRANET_IP = INTRANET_IP;
 module.exports.ID = ID;
 module.exports.TOPIC = TOPIC;
+module.exports.MSG = MSG;
+module.exports.DATAID = DATAID;
+module.exports.USERID = USERID;
+module.exports.OUTTIME = OUTTIME;
+module.exports.PUBLISHER = PUBLISHER;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tmc.js",
-  "version": "0.3.2",
+  "version": "0.3.4",
   "description": "Events driven and chained Taobao Message Channel(TMC) for NodeJS",
   "author": "James ZHANG",
   "license": "MIT",

package/types/index.d.ts

@@ -26,6 +26,10 @@ declare interface ConsumerOptions {
 declare interface TaoMessageConstractor extends EventEmitter {
   new (appKey: string, appSecret: BinaryLike, groupName?: string | ConsumerOptions, options?: ConsumerOptions): TaoMessageConsumer;
   sign(timestamp: string): string;
+  /** @since v0.3.4 */
+  send(data: Message, cb?: (err?: Error) => void): void;
+  /** @since v0.3.4 */
+  send(data: Message, options?: { mask?: true, binary?: true, compress?: boolean, fin?: boolean }, cb?: (err: Error) => void): void;
   onopen(): void;
   onpull(): void;
   onping(data: Buffer): void;
@@ -784,6 +788,10 @@ declare interface TaoTopicsDescriptor {
   tmall_auto_TradeModify(fn: (this: TaoMessageConsumer, message: IncomingMessage.TmallAutoTradeModify) => void): TaoMessageConsumer;
   /** {@link IncomingMessage.TmallAutoTwoWheelsReceiptCreate 天猫汽车 > 天猫二轮车服务工单创建开放} */
   tmall_auto_TwoWheelsReceiptCreate(fn: (this: TaoMessageConsumer, message: IncomingMessage.TmallAutoTwoWheelsReceiptCreate) => void): TaoMessageConsumer;
+  /** {@link IncomingMessage.TmallCarContractSign 天猫汽车 > 合同签署消息} */
+  tmall_car_ContractSign(fn: (this: TaoMessageConsumer, message: IncomingMessage.TmallCarContractSign) => void): TaoMessageConsumer;
+  /** {@link IncomingMessage.TmallCarFinanceMsg 天猫汽车 > 汽车金融消息} */
+  tmall_car_FinanceMsg(fn: (this: TaoMessageConsumer, message: IncomingMessage.TmallCarFinanceMsg) => void): TaoMessageConsumer;
   /** {@link IncomingMessage.TmallChannelApplyOrderChange 渠道中心API > 申请单变更消息} */
   tmall_channel_ApplyOrderChange(fn: (this: TaoMessageConsumer, message: IncomingMessage.TmallChannelApplyOrderChange) => void): TaoMessageConsumer;
   /** {@link IncomingMessage.TmallChannelDeliverOrderChange 渠道中心API > 发货单消息变更} */
@@ -1609,6 +1617,10 @@ declare interface TaoEventsListener {
   on(topic: 'tmall_auto_TradeModify', listener: (this: TaoMessageConsumer, message: IncomingMessage.TmallAutoTradeModify) => void): TaoMessageConsumer;
   /** {@link IncomingMessage.TmallAutoTwoWheelsReceiptCreate 天猫汽车 > 天猫二轮车服务工单创建开放} */
   on(topic: 'tmall_auto_TwoWheelsReceiptCreate', listener: (this: TaoMessageConsumer, message: IncomingMessage.TmallAutoTwoWheelsReceiptCreate) => void): TaoMessageConsumer;
+  /** {@link IncomingMessage.TmallCarContractSign 天猫汽车 > 合同签署消息} */
+  on(topic: 'tmall_car_ContractSign', listener: (this: TaoMessageConsumer, message: IncomingMessage.TmallCarContractSign) => void): TaoMessageConsumer;
+  /** {@link IncomingMessage.TmallCarFinanceMsg 天猫汽车 > 汽车金融消息} */
+  on(topic: 'tmall_car_FinanceMsg', listener: (this: TaoMessageConsumer, message: IncomingMessage.TmallCarFinanceMsg) => void): TaoMessageConsumer;
   /** {@link IncomingMessage.TmallChannelApplyOrderChange 渠道中心API > 申请单变更消息} */
   on(topic: 'tmall_channel_ApplyOrderChange', listener: (this: TaoMessageConsumer, message: IncomingMessage.TmallChannelApplyOrderChange) => void): TaoMessageConsumer;
   /** {@link IncomingMessage.TmallChannelDeliverOrderChange 渠道中心API > 发货单消息变更} */

package/types/message-fields.d.ts

@@ -13,6 +13,11 @@ declare namespace MessageFields {
   type INTRANET_IP = 'intranet_ip';
   type ID = 'id';
   type TOPIC = 'topic';
+  type MSG = 'msg';
+  type DATAID = 'dataid';
+  type USERID = 'userid';
+  type OUTTIME = 'outtime';
+  type PUBLISHER = 'publisher';
 }
 
 declare class MessageFields {
@@ -30,4 +35,9 @@ declare class MessageFields {
   static INTRANET_IP: MessageFields.INTRANET_IP;
   static ID: MessageFields.ID;
   static TOPIC: MessageFields.TOPIC;
+  static MSG: MessageFields.MSG;
+  static DATAID: MessageFields.DATAID;
+  static USERID: MessageFields.USERID;
+  static OUTTIME: MessageFields.OUTTIME;
+  static PUBLISHER: MessageFields.PUBLISHER;
 }

package/types/message.d.ts

@@ -1,5 +1,5 @@
 /// <reference types="node" />
-/// <reference path="header-type.d.ts" />
+/// <reference path="message-type.d.ts" />
 /// <reference path="message-kind.d.ts" />
 
 declare class Message {
@@ -7,14 +7,14 @@ declare class Message {
     type?: MessageType.CONNECT | MessageType.CONNECTACK | MessageType.SEND | MessageType.SENDACK,
     kind?: MessageKind.None | MessageKind.PullRequest | MessageKind.Confirm | MessageKind.Data | MessageKind.Failed
   );
-  protocolVersion: number;
-  messageType: number;
+  protocolVersion: 2;
+  messageType: MessageType.CONNECT | MessageType.CONNECTACK | MessageType.SEND | MessageType.SENDACK;
   statusCode?: number;
   statusPhrase?: string;
   flag?: number;
   token?: string;
   content?: MessageContent;
-  with(key: string, value?: number | bigint | string | Buffer | Date): this;
+  with(key: string | MessageKind, value?: number | bigint | string | Buffer | Date): this;
   get buffer(): Buffer;
   static from(buf: Buffer): Message;
 }

package/types/message.in.d.ts

@@ -751,6 +751,10 @@ declare namespace IncomingMessage {
   type TmallAutoTradeModify = Message & { content?: MessageContent & { content?: string | Tmall.Auto.TradeModify } };
   /** {@link Tmall.Auto.TwoWheelsReceiptCreate 天猫汽车 > 天猫二轮车服务工单创建开放} */
   type TmallAutoTwoWheelsReceiptCreate = Message & { content?: MessageContent & { content?: string | Tmall.Auto.TwoWheelsReceiptCreate } };
+  /** {@link Tmall.Car.ContractSign 天猫汽车 > 合同签署消息} */
+  type TmallCarContractSign = Message & { content?: MessageContent & { content?: string | Tmall.Car.ContractSign } };
+  /** {@link Tmall.Car.FinanceMsg 天猫汽车 > 汽车金融消息} */
+  type TmallCarFinanceMsg = Message & { content?: MessageContent & { content?: string | Tmall.Car.FinanceMsg } };
   /** {@link Tmall.Channel.ApplyOrderChange 渠道中心API > 申请单变更消息} */
   type TmallChannelApplyOrderChange = Message & { content?: MessageContent & { content?: string | Tmall.Channel.ApplyOrderChange } };
   /** {@link Tmall.Channel.DeliverOrderChange 渠道中心API > 发货单消息变更} */

package/types/tmall.d.ts

@@ -28,6 +28,25 @@ declare namespace Tmall.Auto {
   }
 }
 
+/** 天猫汽车 */
+declare namespace Tmall.Car {
+  /** 合同签署消息 */
+  interface ContractSign {
+    /** 合同下载地址，有效期10分钟 */
+    contract_url: string;
+    /** 订单id */
+    order_id: number;
+  }
+
+  /** 汽车金融消息 */
+  interface FinanceMsg {
+    /** 订单id */
+    order_id: number;
+    /** 消息类型： FULL_PURCHASE_FINANCE_CANCEL_MSG_TYPE?，因全款购车导致金融取消 REFUND_FINANCE_CANCEL，因退款导致的金融单关闭 */
+    type: string;
+  }
+}
+
 /** 渠道中心API */
 declare namespace Tmall.Channel {
   /** 申请单变更消息 */