@juzi/wechaty 1.0.0

package/src/wechaty/wechaty-impl.spec.ts

@@ -0,0 +1,118 @@
+#!/usr/bin/env -S node --no-warnings --loader ts-node/esm
+import { test } from 'tstest'
+import PuppetMock from 'wechaty-puppet-mock'
+
+import { WechatyEventEmitter } from '../schemas/wechaty-events.js'
+
+import type {
+  ContactSelfConstructor,
+  ContactConstructor,
+  FriendshipConstructor,
+  ImageConstructor,
+  LocationConstructor,
+  MessageConstructor,
+  MiniProgramConstructor,
+  PostConstructor,
+  RoomInvitationConstructor,
+  RoomConstructor,
+  DelayConstructor,
+  TagConstructor,
+  UrlLinkConstructor,
+  MessageInterface,
+}                             from '../user-modules/mod.js'
+
+import {
+  type WechatyConstructor,
+  type WechatyInterface,
+  type AllProtectedProperty,
+  WechatyImpl,
+  // WechatyConstructor,
+}                       from './wechaty-impl.js'
+
+test('Wechaty interface', async t => {
+  abstract class WechatyImplementation extends WechatyEventEmitter implements WechatyInterface {
+
+    Contact        : ContactConstructor
+    ContactSelf    : ContactSelfConstructor
+    Delay          : DelayConstructor
+    Friendship     : FriendshipConstructor
+    Image          : ImageConstructor
+    Location       : LocationConstructor
+    Message        : MessageConstructor
+    MiniProgram    : MiniProgramConstructor
+    Post           : PostConstructor
+    Room           : RoomConstructor
+    RoomInvitation : RoomInvitationConstructor
+    Tag            : TagConstructor
+    UrlLink        : UrlLinkConstructor
+
+    constructor () {
+      super()
+      // this.puppet
+      this.Contact
+        = this.ContactSelf
+        = this.Delay
+        = this.Friendship
+        = this.Image
+        = this.Location
+        = this.Message
+        = this.MiniProgram
+        = this.Post
+        = this.Room
+        = this.RoomInvitation
+        = this.Tag
+        = this.UrlLink
+        = {} as any
+    }
+
+    abstract authQrCode  : WechatyInterface['authQrCode']
+    abstract currentUser : WechatyInterface['currentUser']
+    abstract ding        : WechatyInterface['ding']
+    abstract emitError   : WechatyInterface['emitError']
+    abstract id          : WechatyInterface['id']
+    abstract init        : WechatyInterface['init']
+    abstract isLoggedIn  : WechatyInterface['isLoggedIn']
+    abstract log         : WechatyInterface['log']
+    abstract logout      : WechatyInterface['logout']
+    abstract name        : WechatyInterface['name']
+    abstract publish     : WechatyInterface['publish']
+    abstract puppet      : WechatyInterface['puppet']
+    abstract ready       : WechatyInterface['ready']
+    abstract reset       : WechatyInterface['reset']
+    abstract say         : WechatyInterface['say']
+    abstract sleep       : WechatyInterface['sleep']
+    abstract start       : WechatyInterface['start']
+    abstract state       : WechatyInterface['state']
+    abstract stop        : WechatyInterface['stop']
+    abstract use         : WechatyInterface['use']
+    abstract version     : WechatyInterface['version']
+    abstract wrapAsync   : WechatyInterface['wrapAsync']
+
+  }
+
+  const WechatyTest = WechatyImplementation as unknown as WechatyConstructor
+  const w: WechatyInterface = new WechatyTest()
+  w.on('message', (msg: MessageInterface) => {
+    msg.say('ok').catch(console.error)
+  })
+
+  t.ok(typeof WechatyImplementation, 'should no typing error')
+})
+
+test('ProtectedProperties', async t => {
+  type NotExistInWechaty = Exclude<AllProtectedProperty, keyof WechatyImpl | `_${string}`>
+  type NotExistTest = NotExistInWechaty extends never ? true : false
+
+  const noOneLeft: NotExistTest = true
+  t.ok(noOneLeft, 'should match Wechaty properties for every protected property')
+})
+
+test('options.puppet initialization', async t => {
+  const puppet  = new PuppetMock()
+  const wechaty = new WechatyImpl({ puppet })
+  t.throws(() => wechaty.puppet, 'should throw when access puppet getter before init()')
+
+  await wechaty.init()
+  t.doesNotThrow(() => wechaty.puppet, 'should not throw when access puppet getter after init()')
+  t.ok(wechaty.puppet, 'should exist puppet instance by setting the options.puppet')
+})

package/src/wechaty/wechaty-impl.ts

@@ -0,0 +1,65 @@
+import type { EventEmitter }  from 'events'
+
+import type { Constructor }           from 'clone-class'
+import type {
+  WechatyMixinProtectedProperty,
+}                                     from '../wechaty-mixins/mod.js'
+import type { WechatyEventListeners } from '../schemas/mod.js'
+import { validationMixin }            from '../user-mixins/mod.js'
+
+import type {
+  WechatySkeletonProtectedProperty,
+}                                     from './wechaty-skeleton.js'
+import {
+  WechatyBase,
+  WechatyBaseProtectedProperty,
+}                                     from './wechaty-base.js'
+
+/**
+ * Huan(202111): this is for solving the circyle dependency problem
+ *
+ *  Construct a `WechatyImpl` based the `WechatyImplBase` with `validationMixin`
+ *
+ */
+class WechatyImplBase extends validationMixin(WechatyBase)<WechatyImplInterface>() {}
+interface WechatyImplInterface extends WechatyImplBase {}
+
+class WechatyImpl extends validationMixin(WechatyImplBase)<WechatyInterface>() {}
+
+/**
+ * ^ The above code will make a ready-to-use class: `WechatyImpl`
+ *  without any cyclic dependency problem.
+ */
+
+type AllProtectedProperty =
+  | keyof EventEmitter  // Huan(202110): remove all EventEmitter first, and added typed event emitter later: or will get error
+  | WechatyMixinProtectedProperty
+  | WechatyBaseProtectedProperty
+  | WechatySkeletonProtectedProperty
+  | `_${string}`// remove all property from interface which is start with `_`
+
+/**
+ * Huan(202111):
+ * `on`/`off`/`once` must use TypedEventEmitter<WechatyEventListeners> instead of WechatyImpl
+ *    or will run into error: cyclic dependency?
+ */
+interface WechatyEventEmitter {
+  on:   <E extends keyof WechatyEventListeners>(event: E, listener: WechatyEventListeners[E]) => WechatyInterface
+  off:  <E extends keyof WechatyEventListeners>(event: E, listener: WechatyEventListeners[E]) => WechatyInterface
+  once: <E extends keyof WechatyEventListeners>(event: E, listener: WechatyEventListeners[E]) => WechatyInterface
+}
+
+type WechatyInterface = Omit<WechatyImplInterface, AllProtectedProperty>
+  & WechatyEventEmitter
+
+type WechatyConstructor = Constructor<
+  WechatyInterface,
+  typeof WechatyImpl
+>
+
+export  {
+  type WechatyInterface,
+  type WechatyConstructor,
+  type AllProtectedProperty,
+  WechatyImpl,
+}

package/src/wechaty/wechaty-skeleton.ts

@@ -0,0 +1,129 @@
+/**
+ *   Wechaty Chatbot SDK - https://github.com/wechaty/wechaty
+ *
+ *   @copyright 2016 Huan LI (李卓桓) <https://github.com/huan>, and
+ *                   Wechaty Contributors <https://github.com/wechaty>.
+ *
+ *   Licensed under the Apache License, Version 2.0 (the "License");
+ *   you may not use this file except in compliance with the License.
+ *   You may obtain a copy of the License at
+ *
+ *       http://www.apache.org/licenses/LICENSE-2.0
+ *
+ *   Unless required by applicable law or agreed to in writing, software
+ *   distributed under the License is distributed on an "AS IS" BASIS,
+ *   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *   See the License for the specific language governing permissions and
+ *   limitations under the License.
+ *
+ */
+import { MemoryCard }     from 'memory-card'
+import { log }            from 'wechaty-puppet'
+import * as UUID          from 'uuid'
+import type { Loggable }  from 'brolog'
+
+import {
+  WechatyEventEmitter,
+  WechatyEventName,
+}                               from '../schemas/mod.js'
+
+import type { WechatyOptions }  from '../schemas/wechaty-options.js'
+
+abstract class WechatySkeleton extends WechatyEventEmitter {
+
+  static readonly log: Loggable = log
+  readonly log: Loggable = log
+
+  /**
+   * the UUID of the Wechaty
+   * @ignore
+   */
+  readonly id: string
+
+  __memory?: MemoryCard
+  get memory (): MemoryCard {
+    if (!this.__memory) {
+      throw new Error('NOMEMORY')
+    }
+    return this.__memory
+  }
+
+  __options: WechatyOptions
+
+  constructor (...args: any[]) {
+    log.verbose('WechatySkeleton', 'constructor()')
+    super()
+
+    this.id = UUID.v4()
+    this.__options = args[0] || {} as WechatyOptions
+
+    /**
+     * Huan(202008):
+     *
+     * Set max listeners to 1K, so that we can add lots of listeners without the warning message.
+     * The listeners might be one of the following functionilities:
+     *  1. Plugins
+     *  2. Redux Observables
+     *  3. etc...
+     */
+    super.setMaxListeners(1024)
+  }
+
+  /**
+   * Initialize the Wechaty instance for ready to be started.
+   *
+   *  1. It will be called automatically by the start()
+   *  2. It should be allowed for being called multiple times in the same instance,
+   *    by skipping the second time initialization.
+   */
+  async init (): Promise<void> {
+    log.verbose('WechatySkeleton', 'init()')
+
+    if (!this.__memory) {
+      this.__memory = new MemoryCard(this.__options.name)
+      try {
+        await this.__memory.load()
+      } catch (_) {
+        log.silly('WechatySkeleton', 'onStart() memory.load() had already loaded')
+      }
+    }
+  }
+
+  async start (): Promise<void> {
+    log.verbose('WechatySkeleton', 'start()')
+    // no super.start()
+
+    /**
+     * Huan(202203): Call the init() functions (with super.init() inside them for chaining)
+     */
+    await this.init()
+  }
+
+  async stop  (): Promise<void> {
+    log.verbose('WechatySkeleton', 'stop()')
+    // no super.stop()
+  }
+
+  override on (event: WechatyEventName, listener: (...args: any[]) => any): this {
+    log.verbose('WechatySkeleton', 'on(%s, listener) registering... listenerCount: %s',
+      event,
+      this.listenerCount(event),
+    )
+
+    return super.on(event, listener)
+  }
+
+}
+
+type WechatySkeletonProtectedProperty =
+  | '__events'
+  | '__memory'
+  | '__options'
+  | 'memory'
+
+export type {
+  WechatySkeletonProtectedProperty,
+}
+export {
+  WechatySkeleton,
+}

package/src/wechaty/wechaty-skelton.spec.ts

@@ -0,0 +1,18 @@
+#!/usr/bin/env -S node --no-warnings --loader ts-node/esm
+
+import {
+  test,
+}           from 'tstest'
+
+import type {
+  WechatySkeleton,
+  WechatySkeletonProtectedProperty,
+}                                         from './wechaty-skeleton.js'
+
+test('ProtectedPropertyWechatySkeleton', async t => {
+  type NotExistInMixin = Exclude<WechatySkeletonProtectedProperty, keyof WechatySkeleton>
+  type NotExistTest = NotExistInMixin extends never ? true : false
+
+  const noOneLeft: NotExistTest = true
+  t.ok(noOneLeft, 'should match Mixin properties for every protected property')
+})

package/src/wechaty-builder.spec.ts

@@ -0,0 +1,79 @@
+#!/usr/bin/env -S node --no-warnings --loader ts-node/esm
+/**
+ *   Wechaty Chatbot SDK - https://github.com/wechaty/wechaty
+ *
+ *   @copyright 2016 Huan LI (李卓桓) <https://github.com/huan>, and
+ *                   Wechaty Contributors <https://github.com/wechaty>.
+ *
+ *   Licensed under the Apache License, Version 2.0 (the "License");
+ *   you may not use this file except in compliance with the License.
+ *   You may obtain a copy of the License at
+ *
+ *       http://www.apache.org/licenses/LICENSE-2.0
+ *
+ *   Unless required by applicable law or agreed to in writing, software
+ *   distributed under the License is distributed on an "AS IS" BASIS,
+ *   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *   See the License for the specific language governing permissions and
+ *   limitations under the License.
+ *
+ */
+
+import { test }  from 'tstest'
+
+import { PuppetMock } from 'wechaty-puppet-mock'
+
+import { WechatyBuilder } from './wechaty-builder.js'
+
+test('WechatyBuilder class', async t => {
+  const wechaty1 = WechatyBuilder.build()
+  const wechaty2 = WechatyBuilder.build()
+  t.not(wechaty1, wechaty2, 'should build two different Wechaty instance')
+
+  const singleton1 = WechatyBuilder.singleton()
+  const singleton2 = WechatyBuilder.singleton()
+  t.equal(singleton1, singleton2, 'should get the same singleton instance')
+
+  const wechaty = WechatyBuilder.build({ puppet: 'wechaty-puppet-mock' })
+  await wechaty.start()
+  t.ok(PuppetMock.validInstance(wechaty.puppet), 'should set options.puppet to mock')
+  await wechaty.stop()
+})
+
+test('throw when set options twice', async t => {
+  class WechatyBuilderTest extends WechatyBuilder {
+
+    constructor () { super() }
+
+    static override new () { return new this() }
+
+    override options (...args: any[]) {
+      super.options(...args)
+      return this
+    }
+
+  }
+
+  const builder = WechatyBuilderTest.new()
+  t.doesNotThrow(() => builder.options({}), 'should not throw for the first time')
+  t.doesNotThrow(() => builder.options({}), 'should not throw as long as the `options` is an empty object')
+
+  const options = { name: 'bot' }
+  t.doesNotThrow(() => builder.options(options), 'should not throw for setting non-empty `options` for the first time')
+  t.throws(() => builder.options(options), 'should throw for setting non-empty `options` again')
+})
+
+test('WechatyBuilder class static', async t => {
+  const wechaty1 = WechatyBuilder.build()
+  const wechaty2 = WechatyBuilder.build()
+  t.not(wechaty1, wechaty2, 'should build two different Wechaty instance')
+
+  const singleton1 = WechatyBuilder.singleton()
+  const singleton2 = WechatyBuilder.singleton()
+  t.equal(singleton1, singleton2, 'should get the same singleton instance')
+
+  const wechaty = WechatyBuilder.build({ puppet: 'wechaty-puppet-mock' })
+  await wechaty.start()
+  t.ok(PuppetMock.validInstance(wechaty.puppet), 'should set options.puppet to mock')
+  await wechaty.stop()
+})

package/src/wechaty-builder.ts

@@ -0,0 +1,123 @@
+/**
+ *   Wechaty Chatbot SDK - https://github.com/wechaty/wechaty
+ *
+ *   @copyright 2016 Huan LI (李卓桓) <https://github.com/huan>, and
+ *                   Wechaty Contributors <https://github.com/wechaty>.
+ *
+ *   Licensed under the Apache License, Version 2.0 (the "License");
+ *   you may not use this file except in compliance with the License.
+ *   You may obtain a copy of the License at
+ *
+ *       http://www.apache.org/licenses/LICENSE-2.0
+ *
+ *   Unless required by applicable law or agreed to in writing, software
+ *   distributed under the License is distributed on an "AS IS" BASIS,
+ *   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *   See the License for the specific language governing permissions and
+ *   limitations under the License.
+ *
+ */
+import { log } from 'wechaty-puppet'
+
+import {
+  WechatyInterface,
+  WechatyImpl,
+  type WechatyOptions,
+}                     from './wechaty/mod.js'
+
+interface BuilderInterface {
+  build (options?: WechatyOptions): WechatyInterface
+}
+
+class WechatyBuilder implements BuilderInterface {
+
+  private static _instance?: WechatyInterface
+
+  static valid (target: any): target is WechatyInterface {
+    return WechatyImpl.valid(target)
+  }
+
+  /**
+   * Create an instance of Wechaty
+   *
+   * @param {WechatyOptions} [options={}]
+   *
+   * @example <caption>The World's Shortest ChatBot Code: 6 lines of JavaScript</caption>
+   * import { WechatyBuilder } from 'wechaty'
+   *
+   * WechatyBuilder.build(options) // instance() for singleton mode
+   *  .on('scan', (url, status) => console.log(`Scan QR Code to login: ${status}\n${url}`))
+   *  .on('login',       user => console.log(`User ${user} logged in`))
+   *  .on('message',  message => console.log(`Message: ${message}`))
+   *  .start()
+   */
+  static build (options?: WechatyOptions): WechatyInterface {
+    return WechatyBuilder.new().options(options).build()
+  }
+
+  /**
+   * @param options is a `WechatyOptions` object, it can only be set once
+   */
+  static singleton (options?: WechatyOptions): WechatyInterface {
+    const builder = new WechatyBuilder()
+    if (options) {
+      builder.options(options)
+    }
+    return builder.singleton().build()
+  }
+
+  protected static new (): WechatyBuilder { return new this() }
+  protected constructor () {}
+
+  protected _singleton = false
+  protected _options: WechatyOptions = {}
+
+  protected singleton (): WechatyBuilder {
+    log.verbose('WechatyBuilder', 'singleton()')
+    this._singleton = true
+    return this
+  }
+
+  protected options (options?: WechatyOptions): WechatyBuilder {
+    log.verbose('WechatyBuilder', 'singleton()')
+    if (Object.keys(this._options).length > 0) {
+      throw new Error([
+        'WechatyBuilder options() can only be set once',
+        'Create a new WechatyBuilder if you need different options',
+      ].join('\n'))
+    }
+
+    if (options) {
+      this._options = options
+    }
+
+    return this
+  }
+
+  build (): WechatyInterface {
+    if (this._singleton) {
+      return this.singletonInstance()
+    }
+    return this.newInstance()
+  }
+
+  protected singletonInstance (): WechatyInterface {
+    log.verbose('WechatyBuilder', 'singletonInstance()')
+    if (!WechatyBuilder._instance) {
+      WechatyBuilder._instance = this.newInstance()
+    }
+    return WechatyBuilder._instance
+  }
+
+  protected newInstance (): WechatyInterface {
+    log.verbose('WechatyBuilder', 'newInstance()')
+    return new WechatyImpl(this._options)
+  }
+
+}
+
+export {
+  type WechatyOptions,
+  type BuilderInterface,
+  WechatyBuilder,
+}

package/src/wechaty-mixins/gerror-mixin.spec.ts

@@ -0,0 +1,15 @@
+#!/usr/bin/env -S node --no-warnings --loader ts-node/esm
+import { test } from 'tstest'
+
+import type {
+  GErrorMixin,
+  ProtectedPropertyGErrorMixin,
+}                                             from './gerror-mixin.js'
+
+test('ProtectedPropertyGErrorMixin', async t => {
+  type NotExistInMixin = Exclude<ProtectedPropertyGErrorMixin, keyof InstanceType<GErrorMixin>>
+  type NotExistTest = NotExistInMixin extends never ? true : false
+
+  const noOneLeft: NotExistTest = true
+  t.ok(noOneLeft, 'should match Mixin properties for every protected property')
+})

package/src/wechaty-mixins/gerror-mixin.ts

@@ -0,0 +1,78 @@
+import { log }        from 'wechaty-puppet'
+import {
+  GError,
+  WrapAsync,
+  wrapAsyncError,
+}                     from 'gerror'
+
+import { wechatyCaptureException }  from '../raven.js'
+
+import type { WechatySkeleton }      from '../wechaty/mod.js'
+
+const gErrorMixin = <MixinBase extends typeof WechatySkeleton> (mixinBase: MixinBase) => {
+  log.verbose('WechatyGErrorMixin', 'gErrorMixin(%s)', mixinBase.name)
+
+  abstract class GErrorMixin extends mixinBase {
+
+    constructor (...args: any[]) {
+      super(...args)
+    }
+
+    /**
+     * Wrap promise in sync way (catch error by emitting it)
+     *  1. convert a async callback function to be sync function
+     *    by catcing any errors and emit them to error event
+     *  2. wrap a Promise by catcing any errors and emit them to error event
+     */
+    wrapAsync: WrapAsync = wrapAsyncError((e: any) => this.emit('error', e))
+
+    /**
+     * Wechaty internally can use `emit('error' whatever)` to emit any error
+     * But the external call can only emit GError.
+     * That's the reason why we need the below `emitError(e: any)
+     */
+    emitError (e: any): void {
+      this.emit('error', e)
+    }
+
+    /**
+     * Convert any error to GError,
+     *  and emit `error` event with GError
+     */
+    override emit (event: any, ...args: any) {
+      if (event !== 'error') {
+        return super.emit(event, ...args)
+      }
+
+      /**
+       * Dealing with the `error` event
+       */
+      const arg0 = args[0]
+      let gerror: GError
+
+      if (arg0 instanceof GError) {
+        gerror = arg0
+      } else {
+        gerror = GError.from(arg0)
+      }
+
+      wechatyCaptureException(gerror)
+      return super.emit('error', gerror)
+    }
+
+  }
+
+  return GErrorMixin
+}
+
+type GErrorMixin = ReturnType<typeof gErrorMixin>
+
+type ProtectedPropertyGErrorMixin = never
+
+export type {
+  GErrorMixin,
+  ProtectedPropertyGErrorMixin,
+}
+export {
+  gErrorMixin,
+}