@juzi/wechaty 1.0.0

package/src/mods/impls.ts

@@ -0,0 +1,115 @@
+/**
+ *   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.
+ *
+ */
+
+/**
+ * Huan(202111): We export all names with specific postfix to make it easier to be recongnized
+ *  with less misunderstandings.
+ *
+ * Postfixes:
+ *  - Interface:    type, the `interface
+ *  - Constructor:  type, the `Constructor<interface>`
+ *  - Impl:         value, the `class`
+ *
+ *  - no postfix:  value, the `class`
+ */
+
+export {
+  ContactImpl,
+  ContactSelfImpl,
+  FavoriteImpl,
+  FriendshipImpl,
+  ImageImpl,
+  LocationImpl,
+  MessageImpl,
+  MiniProgramImpl,
+  MomentImpl,
+  MoneyImpl,
+  PostImpl,
+  RoomImpl,
+  RoomInvitationImpl,
+  DelayImpl,
+  TagImpl,
+  UrlLinkImpl,
+}                             from '../user-modules/mod.js'
+
+// export {
+//   ContactImpl         as Contact,
+//   ContactSelfImpl     as ContactSelf,
+//   FavoriteImpl        as Favorite,
+//   FriendshipImpl      as Friendship,
+//   ImageImpl           as Image,
+//   LocationImpl        as Location,
+//   MessageImpl         as Message,
+//   MiniProgramImpl     as MiniProgram,
+//   MomentImpl          as Moment,
+//   MoneyImpl           as Money,
+//   PostImpl            as Post,
+//   RoomImpl            as Room,
+//   RoomInvitationImpl  as RoomInvitation,
+//   DelayImpl           as Delay,
+//   TagImpl             as Tag,
+//   UrlLinkImpl         as UrlLink,
+// }                                         from '../user-modules/mod.js'
+
+export type {
+  ContactInterface,
+  ContactSelfInterface,
+  DelayInterface,
+  FavoriteInterface,
+  FriendshipInterface,
+  ImageInterface,
+  LocationInterface,
+  MessageInterface,
+  MiniProgramInterface,
+  MomentInterface,
+  MoneyInterface,
+  PostInterface,
+  RoomInterface,
+  RoomInvitationInterface,
+  TagInterface,
+  UrlLinkInterface,
+}                               from '../user-modules/mod.js'
+
+export type {
+  ContactConstructor,
+  ContactSelfConstructor,
+  DelayConstructor,
+  FavoriteConstructor,
+  FriendshipConstructor,
+  ImageConstructor,
+  LocationConstructor,
+  MessageConstructor,
+  MiniProgramConstructor,
+  MomentConstructor,
+  MoneyConstructor,
+  PostConstructor,
+  RoomConstructor,
+  RoomInvitationConstructor,
+  TagConstructor,
+  UrlLinkConstructor,
+}                               from '../user-modules/mod.js'
+
+export {
+  WechatyImpl,
+}                         from '../wechaty/mod.js'
+export type {
+  WechatyInterface,
+  WechatyConstructor,
+}                         from '../wechaty/mod.js'

package/src/mods/mod.spec.ts

@@ -0,0 +1,17 @@
+#!/usr/bin/env -S node --no-warnings --loader ts-node/esm
+
+import { test } from 'tstest'
+
+import * as WECHATY from './mod.js'
+
+test('Export of the Framework', async t => {
+  t.ok(WECHATY.impls,     'should export impls.*')
+  t.ok(WECHATY.types,     'should export types.*')
+  t.ok(WECHATY.IoClient,  'should export IoClient')
+  t.ok(WECHATY.log,       'should export log')
+})
+
+test('Config setting', async t => {
+  t.ok(WECHATY.config, 'should export Config')
+  // t.ok(config.default.DEFAULT_PUPPET  , 'should has DEFAULT_PUPPET')
+})

package/src/mods/mod.ts

@@ -0,0 +1,74 @@
+/**
+ *   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.
+ *
+ */
+
+/**
+ * We need to put `Wechaty` at the beginning of this file for import
+ * because we have circular dependencies between `Puppet` & `Wechaty`
+ */
+export type {
+  WechatyOptions,
+  WechatyInterface as Wechaty,
+}                               from '../wechaty/mod.js'
+export {
+  WechatyBuilder,
+  type BuilderInterface,
+}                               from '../wechaty-builder.js'
+
+export {
+  type SayableSayer,
+  type Sayable,
+}                       from '../sayable/mod.js'
+
+export * as types       from 'wechaty-puppet/types'
+export * as payloads    from 'wechaty-puppet/payloads'
+
+export *                from './users.js'
+export * as users       from './users.js'
+export * as impls       from './impls.js'
+export * as helpers     from './helpers.js'
+export {
+  ScanStatus,
+}                       from 'wechaty-puppet/types'
+
+export {
+  log,
+  config,
+  qrcodeValueToImageUrl,
+  VERSION,
+}                         from '../config.js'
+
+export type {
+  WechatyEventName,
+}                             from '../schemas/mod.js'
+
+export type {
+  OfficialPuppetNpmName,
+  PuppetModuleName, // DEPRECATED
+}                             from '../puppet-config.js'
+export type {
+  WechatyPlugin,
+  WechatyPluginUninstaller,
+}                             from '../plugin.js'
+export type {
+  IoClientOptions,
+}                             from '../io-client.js'
+export {
+  IoClient,
+}                             from '../io-client.js'

package/src/mods/users.ts

@@ -0,0 +1,44 @@
+/**
+ *   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.
+ *
+ */
+
+/**
+ * Huan(202111): we export all `interface` from this file, as the most convenience class name.
+ *
+ *  since they are `interface`s, so they are `type`-only.
+ */
+
+export type {
+  ContactInterface        as Contact,
+  ContactSelfInterface    as ContactSelf,
+  DelayInterface          as Delay,
+  FavoriteInterface       as Favorite,
+  FriendshipInterface     as Friendship,
+  ImageInterface          as Image,
+  LocationInterface       as Location,
+  MessageInterface        as Message,
+  MiniProgramInterface    as MiniProgram,
+  MomentInterface         as Moment,
+  MoneyInterface          as Money,
+  PostInterface           as Post,
+  RoomInterface           as Room,
+  RoomInvitationInterface as RoomInvitation,
+  TagInterface            as Tag,
+  UrlLinkInterface        as UrlLink,
+}                                               from '../user-modules/mod.js'

package/src/package-json.spec.ts

@@ -0,0 +1,18 @@
+#!/usr/bin/env -S node --no-warnings --loader ts-node/esm
+
+import { test } from 'tstest'
+
+import { packageJson } from './package-json.js'
+
+test('Make sure the packageJson is fresh in source code', async t => {
+  const json = JSON.parse(JSON.stringify(packageJson))
+  /**
+   * Delete test data (keys), which will
+   *  be overwrite
+   *    by the real data before deploy
+   */
+  delete json['wechaty']
+
+  const keyNum = Object.keys(json).length
+  t.equal(keyNum, 0, 'packageJson should be empty in source code, only updated before publish to NPM')
+})

package/src/package-json.ts

@@ -0,0 +1,180 @@
+/* eslint-disable */
+/**
+ * This file was auto generated from scripts/generate-version.sh
+ */
+import type { PackageJsonWechaty } from './config'
+
+export const GIT_COMMIT_HASH: string = '8302b201b9d77f9e190fe696b3170b7bb3b5e328'
+export const packageJson: PackageJsonWechaty = {
+  "name": "@juzi/wechaty",
+  "version": "1.0.0",
+  "description": "Wechaty is a RPA SDK for Chatbot Makers.",
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": "./dist/esm/src/mods/mod.js",
+      "require": "./dist/cjs/src/mods/mod.js"
+    },
+    "./impls": {
+      "import": "./dist/esm/src/mods/impls.js",
+      "require": "./dist/cjs/src/mods/impls.js"
+    },
+    "./users": {
+      "import": "./dist/esm/src/mods/users.js",
+      "require": "./dist/cjs/src/mods/users.js"
+    }
+  },
+  "typesVersions": {
+    "*": {
+      "users": [
+        "./dist/esm/src/mods/users.d.ts"
+      ],
+      "impls": [
+        "./dist/esm/src/mods/impls.d.ts"
+      ]
+    }
+  },
+  "types": "./dist/esm/src/mods/mod.d.ts",
+  "engines": {
+    "node": ">=16",
+    "npm": ">=7"
+  },
+  "wechaty": {
+    "DEFAULT_PORT": 8080,
+    "DEFAULT_PROTOCOL": "io|0.0.1",
+    "DEFAULT_APIHOST": "api.chatie.io"
+  },
+  "scripts": {
+    "build": "tsc && tsc -p tsconfig.cjs.json",
+    "changelog": "docker run -it --rm -e CHANGELOG_GITHUB_TOKEN -v \"$(pwd)\":/usr/local/src/your-app ferrarimarco/github-changelog-generator -u wechaty -p wechaty && sed -i'.bak' /greenkeeper/d CHANGELOG.md && sed -i'.bak' /Snyk/d CHANGELOG.md && sed -i'.bak' '/An in-range update of/d' CHANGELOG.md && node --no-warnings --loader=ts-node/esm scripts/sort-contributiveness.ts < CHANGELOG.md > CHANGELOG.new.md 2>/dev/null && cat CHANGELOG.md >> CHANGELOG.new.md && mv CHANGELOG.new.md CHANGELOG.md",
+    "clean": "shx rm -fr dist/*",
+    "coverage": "nyc report --reporter=lcov",
+    "cli": "node --no-warnings --loader ts-node/esm bin/cli.ts",
+    "demo": "cross-env NODE_OPTIONS=\"--no-warnings --loader=ts-node/esm\" node examples/ding-dong-bot.ts",
+    "dist": "npm-run-all clean build dist:commonjs",
+    "dist:commonjs": "jq -n \"{ type: \\\"commonjs\\\" }\" > dist/cjs/package.json",
+    "docs": "bash -x scripts/generate-docs.sh",
+    "doctor": "node --no-warnings --loader=ts-node/esm bin/doctor.ts",
+    "io-client": "node --no-warnings --loader=ts-node/esm bin/io-client.ts",
+    "lint:es": "eslint --ignore-pattern node_modules/ --ignore-pattern fixtures/ \"{bin,examples,src,scripts,tests}/**/*.ts\"",
+    "lint:md": "markdownlint README.md",
+    "lint:sh": "bash -n bin/*.sh",
+    "lint:ts": "tsc --isolatedModules --noEmit",
+    "lint": "npm-run-all lint:es lint:ts lint:sh lint:md",
+    "puppet-install": "node --no-warnings --loader=ts-node/esm bin/puppet-install.ts",
+    "sloc": "sloc bin examples scripts src tests --details --format cli-table --keys total,source,comment && sloc bin examples scripts src tests",
+    "start": "npm run demo",
+    "test:pack": "bash -x scripts/npm-pack-testing.sh",
+    "test:shell": "shellcheck bin/*.sh scripts/*.sh",
+    "test:unit": "cross-env NODE_OPTIONS=\"--no-warnings --loader=ts-node/esm\" TAP_TIMEOUT=600 tap \"src/**/*.spec.ts\" \"tests/**/*.spec.ts\"",
+    "test": "npm run lint && nyc npm run test:unit",
+    "typedoc": "bash scripts/typedoc.sh"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/juzibot/wechaty.git"
+  },
+  "bin": {
+    "wechaty": "dist/esm/bin/cli.js",
+    "wechaty-doctor": "dist/esm/bin/doctor.js",
+    "wechaty-io-client": "dist/esm/bin/io-client.js",
+    "wechaty-puppet-install": "dist/esm/bin/puppet-install.js",
+    "wechaty-version": "dist/esm/bin/version.js"
+  },
+  "keywords": [
+    "ai",
+    "bot",
+    "chatbot",
+    "chatie",
+    "conversational",
+    "framework",
+    "robotics",
+    "robot",
+    "rpa",
+    "sdk",
+    "wechat",
+    "wecom",
+    "wxwork",
+    "lark",
+    "TikTok",
+    "weixin",
+    "whatsapp",
+    "微信"
+  ],
+  "author": {
+    "name": "Huan LI (李卓桓)",
+    "email": "zixia@zixia.net",
+    "url": "https://linkedin.com/in/zixia/"
+  },
+  "license": "Apache-2.0",
+  "bugs": {
+    "url": "https://github.com/wechaty/wechaty/issues"
+  },
+  "funding": {
+    "type": "opencollective",
+    "url": "https://opencollective.com/wechaty"
+  },
+  "homepage": "https://github.com/wechaty/",
+  "dependencies": {
+    "clone-class": "^1.1.1",
+    "cmd-ts": "^0.10.0",
+    "cockatiel": "^2.0.2",
+    "cross-spawn": "^7.0.3",
+    "dotenv": "^16.0.0",
+    "file-box": "^1.4.15",
+    "fp-ts": "^2.11.9",
+    "gerror": "^1.0.16",
+    "get-port": "^6.1.2",
+    "json-rpc-peer": "^0.17.0",
+    "memory-card": "^1.1.2",
+    "open-graph": "^0.2.6",
+    "rx-queue": "^1.0.5",
+    "state-switch": "^1.6.3",
+    "uuid": "^8.3.2",
+    "@juzi/wechaty-puppet": "1.0.0",
+    "@juzi/wechaty-puppet-service": "1.0.0",
+    "wechaty-puppet-wechat4u": "^1.11.1",
+    "wechaty-token": "^1.1.1",
+    "ws": "^8.5.0"
+  },
+  "devDependencies": {
+    "@chatie/eslint-config": "^1.0.4",
+    "@chatie/semver": "^0.4.7",
+    "@chatie/tsconfig": "^4.6.3",
+    "@swc/core": "^1.2.155",
+    "@swc/helpers": "^0.3.6",
+    "@types/cross-spawn": "^6.0.2",
+    "@types/dotenv": "^8.2.0",
+    "@types/glob": "^7.2.0",
+    "@types/open-graph": "^0.2.2",
+    "@types/qrcode-terminal": "^0.12.0",
+    "@types/raven": "^2.5.4",
+    "@types/uuid": "^8.3.4",
+    "@types/ws": "^8.5.3",
+    "coveralls": "^3.1.1",
+    "glob": "^7.2.0",
+    "jsdoc-to-markdown": "^7.1.1",
+    "nyc": "^15.1.0",
+    "qrcode-terminal": "^0.12.0",
+    "raven": "^2.6.4",
+    "regenerator-runtime": "^0.13.9",
+    "sloc": "^0.2.1",
+    "typed-emitter": "^1.5.0-from-event",
+    "typedoc": "^1.0.0-dev.4 ",
+    "wechaty-puppet-mock": "^1.18.2",
+    "wechaty-puppet-padlocal": "^1.11.13"
+  },
+  "files": [
+    "bin/",
+    "dist/",
+    "src/"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "tag": "next"
+  },
+  "collective": {
+    "type": "opencollective",
+    "url": "https://opencollective.com/wechaty"
+  }
+} as any

package/src/plugin.spec.ts

@@ -0,0 +1,87 @@
+#!/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,
+  sinon,
+}           from 'tstest'
+
+import { PuppetMock } from 'wechaty-puppet-mock'
+
+import type { Wechaty } from './mods/mod.js'
+import { WechatyBuilder } from './wechaty-builder.js'
+
+import {
+  WechatyPlugin,
+  isWechatyPluginUninstaller,
+}                               from './plugin.js'
+
+/**
+ *
+ * Huan(202111): we are not remove plugins in the `stop()` method.
+ *  @see https://github.com/wechaty/wechaty/issues/2282#issuecomment-966008175
+ *
+ * TODO: make sure to not remove or remote, then remove this comment
+ *
+ */
+test('Wechaty Plugin uninstaller should be called after wechaty.stop()', async t => {
+  const spyPluginInstall    = sinon.spy()
+  const spyPluginUninstall  = sinon.spy()
+
+  const bot = WechatyBuilder.build({ puppet: new PuppetMock() })
+
+  const plugin: WechatyPlugin = (_bot: Wechaty) => {
+    spyPluginInstall()
+    return () => {
+      spyPluginUninstall()
+    }
+  }
+
+  t.ok(spyPluginInstall.notCalled, 'should be clean for install spy')
+  t.ok(spyPluginUninstall.notCalled, 'should be clean for uninstall spy')
+
+  const uninstaller = bot.use(plugin)
+  t.ok(spyPluginInstall.calledOnce, 'should called install spy right after use() before start()')
+  t.ok(spyPluginUninstall.notCalled, 'should not call uninstall spy after use()')
+
+  await bot.start()
+  t.ok(spyPluginInstall.calledOnce, 'should called install spy after start()')
+  t.ok(spyPluginUninstall.notCalled, 'should not call uninstall spy after start()')
+
+  spyPluginInstall.resetHistory()
+  await bot.stop()
+  t.ok(spyPluginInstall.notCalled, 'should not called with stop()')
+  await new Promise(setImmediate) // clean the event loop
+  t.ok(spyPluginUninstall.notCalled, 'should not call uninstall spy after stop()')
+
+  uninstaller()
+  t.ok(spyPluginUninstall.calledOnce, 'should called uninstall spy after call uninstaller()')
+})
+
+test('isWechatyPluginUninstaller()', async t => {
+  const FIXTURES = [
+    [undefined, false],
+    [() => {}, true],
+  ] as const
+
+  for (const [uninstaller, expected] of FIXTURES) {
+    t.equal(isWechatyPluginUninstaller(uninstaller), expected, `isWechatyPluginUninstaller(${uninstaller}) === ${expected}`)
+  }
+})

package/src/plugin.ts

@@ -0,0 +1,19 @@
+import type { WechatyInterface } from './wechaty/mod.js'
+
+export type WechatyPluginUninstaller = () => void
+
+export type WechatyPluginReturn = void | WechatyPluginUninstaller
+
+export interface WechatyPlugin {
+  (bot: WechatyInterface): WechatyPluginReturn
+}
+
+function isWechatyPluginUninstaller (
+  pluginReturn: WechatyPluginReturn,
+): pluginReturn is WechatyPluginUninstaller {
+  return typeof pluginReturn === 'function'
+}
+
+export {
+  isWechatyPluginUninstaller,
+}

package/src/puppet-config.ts

@@ -0,0 +1,104 @@
+/* eslint-disable sort-keys */
+/**
+ *   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.
+ *
+ */
+const OFFICIAL_PUPPET_DEPENDENCIES = {
+  /**
+   * The following puppets were DEPRECATED before 2020
+   */
+  // 'wechaty-puppet-ioscat'    : '^0.5.22',   // https://www.npmjs.com/package/wechaty-puppet-ioscat
+  // 'wechaty-puppet-padchat'   : '^0.19.3',   // https://www.npmjs.com/package/wechaty-puppet-padchat
+  // 'wechaty-puppet-padpro'    : '^0.3.21',   // https://www.npmjs.com/package/wechaty-puppet-padpro
+
+  /**
+   * Deprecated History:
+   *  https://github.com/wechaty/puppet-service-providers/issues/11
+   */
+  // Dec 2020
+  //  - https://github.com/wechaty/puppet-services/issues/61
+  //    'wechaty-puppet-padplus'   : '^0.7.30',   // https://www.npmjs.com/package/wechaty-puppet-padplus
+  // Sep 2021:
+  //    'wechaty-puppet-hostie'    : '*',       // https://www.npmjs.com/package/wechaty-puppet-hostie
+
+  /**
+   * Wechaty Internal Puppets: dependency by package.json
+   *
+   *  Huan(202108): DO NOT REMOVE THE SPECIFIC VERSIONS BELOW
+   *    All the internal puppets which have already depended in package.json
+   *    MUST be listed below with their correct version number (ranges)
+   *    because the `bin/puppet-install.ts` will use those version
+   *    to install all them inside the Docker
+   */
+  'wechaty-puppet-service' : '>=1.19.8',  // https://www.npmjs.com/package/wechaty-puppet-service
+  'wechaty-puppet-mock'    : '>=1.10.2',  // https://www.npmjs.com/package/wechaty-puppet-mock
+
+  /**
+   * WeChat Puppets
+   */
+  'wechaty-puppet-wechat'           : '>=1.11.8', // https://www.npmjs.com/package/wechaty-puppet-wechat
+  'wechaty-puppet-wechat4u'         : '>=1.11.1', // https://www.npmjs.com/package/wechaty-puppet-wechat4u
+  'wechaty-puppet-padlocal'         : '>=1.11.13',  // https://www.npmjs.com/package/wechaty-puppet-padlocal
+  'wechaty-puppet-xp'               : '>=1.10.2',  // https://www.npmjs.com/package/wechaty-puppet-xp
+  'wechaty-puppet-oicq'             : '>=1.10.2',  // https://www.npmjs.com/package/wechaty-puppet-oicq
+  'wechaty-puppet-official-account' : '>=1.10.2',    // https://www.npmjs.com/package/wechaty-puppet-official-account
+
+  /**
+   * Non-WeChat External Puppets
+   */
+  'wechaty-puppet-gitter'   : '>=1.10.1',   // https://www.npmjs.com/package/wechaty-puppet-gitter
+  'wechaty-puppet-lark'     : '>=0.4.5',   // https://www.npmjs.com/package/wechaty-puppet-lark
+  'wechaty-puppet-whatsapp' : '>=1.10.4',   // https://www.npmjs.com/package/wechaty-puppet-whatsapp
+  'wechaty-puppet-walnut'   : '>=0.1.41',  // https://www.npmjs.com/package/wechaty-puppet-walnut
+
+  /**
+   * Scoped puppets (private)
+   */
+  '@juzibot/wechaty-puppet-donut'  : '*',   // https://www.npmjs.com/package/wechaty-puppet-donut (to be published)
+  '@juzibot/wechaty-puppet-wxwork' : '*',   // https://www.npmjs.com/package/wechaty-puppet-wxwork (to be published)
+}
+
+type OfficialPuppetNpmName = keyof typeof OFFICIAL_PUPPET_DEPENDENCIES
+
+const isPuppetModuleName = (name: string): name is OfficialPuppetNpmName => name in OFFICIAL_PUPPET_DEPENDENCIES
+
+/**
+ * Updates:
+ *  - Huan(202004): we change default puppet from puppet-service -> puppet-wechat (with UOS support)
+ *  - Huan(202009): use puppet service as default
+ *  - Huan(202201): use puppet-wechat4u as default
+ */
+const OFFICIAL_PUPPET_DEFAULT: OfficialPuppetNpmName = 'wechaty-puppet-wechat4u'
+
+// i.e. @juzibot/wechaty-puppet-donut
+type PuppetNpmScope = `@${string}/` | ''
+type PuppetNpmName  = `${PuppetNpmScope}wechaty-puppet-${string}`
+
+/**
+ * @deprecated: use `OfficialPuppetNpmName` instead. will be removed after Dec 31, 2022
+ */
+type PuppetModuleName = OfficialPuppetNpmName
+
+export {
+  type OfficialPuppetNpmName,
+  type PuppetNpmName,
+  type PuppetModuleName, // DEPRECATED
+  OFFICIAL_PUPPET_DEPENDENCIES,
+  OFFICIAL_PUPPET_DEFAULT,
+  isPuppetModuleName,
+}