@juzi/wechaty 1.0.149 → 1.0.155

package/src/user-modules/voice.spec.ts

@@ -0,0 +1,187 @@
+#!/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 { FileBox }        from 'file-box'
+import type * as PUPPET   from '@juzi/wechaty-puppet'
+import { PuppetMock }     from '@juzi/wechaty-puppet-mock'
+import { WechatyBuilder } from '../wechaty-builder.js'
+
+const MESSAGE_ID = 'message-id-voice'
+
+/**
+ * The fallback must trigger ONLY when the puppet does not implement the new
+ * RPC, never on transient failures: otherwise `text()` silently drops the
+ * `noSpeech` discriminator and makes the bot re-run its own paid ASR.
+ *
+ * The puppet is built & started once and reused across cases (`wechaty.Voice`
+ * is unavailable before `start()`). `messageVoice` / `messageVoiceText` are
+ * assigned directly (rather than via `sinon.stub(puppet, ...)`) because the
+ * installed wechaty-puppet-mock predates those methods, so stubbing a
+ * non-existent property would throw.
+ */
+const puppet  = new PuppetMock() as any
+const wechaty = WechatyBuilder.build({ puppet })
+
+let started = false
+async function ensureStarted () {
+  if (!started) {
+    await wechaty.start()
+    started = true
+  }
+}
+
+const voice = () => wechaty.Voice.create(MESSAGE_ID)
+
+const UNSUPPORTED = new Error('Wechaty Puppet Unsupported API Error.')
+
+test('Voice.file() returns the dedicated messageVoice result when supported', async t => {
+  await ensureStarted()
+  puppet.messageVoice = sinon.stub().resolves(FileBox.fromBuffer(Buffer.from('voice'), 'voice.silk'))
+  puppet.messageFile  = sinon.stub().resolves(FileBox.fromBuffer(Buffer.from('file'), 'file.bin'))
+
+  const fileBox = await voice().file()
+  t.equal(fileBox.name, 'voice.silk', 'should return the messageVoice FileBox')
+  t.ok(puppet.messageVoice.calledOnceWith(MESSAGE_ID), 'should call messageVoice')
+  t.notOk(puppet.messageFile.called, 'should NOT fall back to messageFile when supported')
+})
+
+test('Voice.file() falls back to messageFile on unsupported error', async t => {
+  await ensureStarted()
+  puppet.messageVoice = sinon.stub().rejects(UNSUPPORTED)
+  puppet.messageFile  = sinon.stub().resolves(FileBox.fromBuffer(Buffer.from('file'), 'file.bin'))
+
+  const fileBox = await voice().file()
+  t.equal(fileBox.name, 'file.bin', 'should fall back to messageFile')
+  t.ok(puppet.messageFile.calledOnceWith(MESSAGE_ID), 'should call messageFile on fallback')
+})
+
+test('Voice.file() falls back to messageFile when messageVoice is absent (old puppet)', async t => {
+  await ensureStarted()
+  puppet.messageVoice = undefined // old puppet built without the method at all
+  puppet.messageFile  = sinon.stub().resolves(FileBox.fromBuffer(Buffer.from('file'), 'file.bin'))
+
+  const fileBox = await voice().file()
+  t.equal(fileBox.name, 'file.bin', 'should fall back to messageFile via the typeof guard')
+  t.ok(puppet.messageFile.calledOnceWith(MESSAGE_ID), 'should call messageFile on fallback')
+})
+
+test('Voice.file() rethrows a transient error instead of falling back', async t => {
+  await ensureStarted()
+  puppet.messageVoice = sinon.stub().rejects(new Error('socket hang up'))
+  puppet.messageFile  = sinon.stub().resolves(FileBox.fromBuffer(Buffer.from('file'), 'file.bin'))
+
+  await t.rejects(() => voice().file(), /socket hang up/, 'should rethrow the transient error')
+  t.notOk(puppet.messageFile.called, 'should NOT fall back on a transient error')
+})
+
+test('Voice.file() rethrows a genuine "is not a function" TypeError from a working messageVoice', async t => {
+  await ensureStarted()
+  // method exists but its implementation throws internally — must NOT be
+  // misclassified as unsupported just because the message says "is not a function"
+  puppet.messageVoice = sinon.stub().rejects(new TypeError('innerHelper.process is not a function'))
+  puppet.messageFile  = sinon.stub().resolves(FileBox.fromBuffer(Buffer.from('file'), 'file.bin'))
+
+  await t.rejects(() => voice().file(), /is not a function/, 'should rethrow the internal TypeError')
+  t.notOk(puppet.messageFile.called, 'should NOT mask a real implementation bug')
+})
+
+test('Voice.text() returns the dedicated messageVoiceText payload when supported', async t => {
+  await ensureStarted()
+  puppet.messageVoiceText = sinon.stub().resolves({ text: 'hello', noSpeech: false })
+  puppet.messagePayload   = sinon.stub().resolves({ text: 'legacy' } as PUPPET.payloads.Message)
+
+  const result = await voice().text()
+  t.same(result, { text: 'hello', noSpeech: false }, 'should return the messageVoiceText payload')
+  t.ok(puppet.messageVoiceText.calledOnceWith(MESSAGE_ID), 'should call messageVoiceText')
+  t.notOk(puppet.messagePayload.called, 'should NOT fall back to messagePayload when supported')
+})
+
+test('Voice.text() preserves noSpeech=true from the puppet (skip paid ASR)', async t => {
+  await ensureStarted()
+  puppet.messageVoiceText = sinon.stub().resolves({ text: '', noSpeech: true })
+  puppet.messagePayload   = sinon.stub().resolves({ text: '' } as PUPPET.payloads.Message)
+
+  const result = await voice().text()
+  t.same(result, { text: '', noSpeech: true }, 'should return the puppet payload verbatim')
+  t.equal(result.noSpeech, true, 'should preserve noSpeech=true so the bot can skip its own ASR')
+  t.ok(puppet.messageVoiceText.calledOnceWith(MESSAGE_ID), 'should call messageVoiceText')
+  t.notOk(puppet.messagePayload.called, 'should NOT fall back when supported')
+})
+
+test('Voice.text() falls back to messagePayload().text on unsupported error', async t => {
+  await ensureStarted()
+  puppet.messageVoiceText = sinon.stub().rejects(UNSUPPORTED)
+  puppet.messagePayload   = sinon.stub().resolves({ text: 'legacy asr' } as PUPPET.payloads.Message)
+
+  const result = await voice().text()
+  t.same(result, { text: 'legacy asr', noSpeech: false }, 'should fall back to legacy payload.text with noSpeech=false')
+  t.ok(puppet.messagePayload.calledOnceWith(MESSAGE_ID), 'should call messagePayload on fallback')
+})
+
+test('Voice.text() falls back on gRPC UNIMPLEMENTED (code 12)', async t => {
+  await ensureStarted()
+  const unimplemented = Object.assign(new Error('12 UNIMPLEMENTED'), { code: 12 })
+  puppet.messageVoiceText = sinon.stub().rejects(unimplemented)
+  puppet.messagePayload   = sinon.stub().resolves({ text: 'legacy asr' } as PUPPET.payloads.Message)
+
+  const result = await voice().text()
+  t.same(result, { text: 'legacy asr', noSpeech: false }, 'should fall back when the server returns UNIMPLEMENTED')
+  t.ok(puppet.messagePayload.calledOnceWith(MESSAGE_ID), 'should call messagePayload on fallback')
+})
+
+test('Voice.text() falls back to messagePayload when messageVoiceText is absent (old puppet)', async t => {
+  await ensureStarted()
+  puppet.messageVoiceText = undefined // old puppet built without the method at all
+  puppet.messagePayload   = sinon.stub().resolves({ text: 'legacy asr' } as PUPPET.payloads.Message)
+
+  const result = await voice().text()
+  t.same(result, { text: 'legacy asr', noSpeech: false }, 'should fall back via the typeof guard with noSpeech=false')
+  t.ok(puppet.messagePayload.calledOnceWith(MESSAGE_ID), 'should call messagePayload on fallback')
+})
+
+test('Voice.text() rethrows a transient error instead of falling back', async t => {
+  await ensureStarted()
+  puppet.messageVoiceText = sinon.stub().rejects(new Error('ETIMEDOUT'))
+  puppet.messagePayload   = sinon.stub().resolves({ text: 'legacy asr' } as PUPPET.payloads.Message)
+
+  await t.rejects(() => voice().text(), /ETIMEDOUT/, 'should rethrow the transient error')
+  t.notOk(puppet.messagePayload.called, 'should NOT fall back on a transient error (would drop noSpeech)')
+})
+
+test('Voice.text() rethrows a genuine "is not a function" TypeError from a working messageVoiceText', async t => {
+  await ensureStarted()
+  // regression: a real internal TypeError must NOT be downgraded — that would
+  // drop noSpeech and make the bot re-run its own paid ASR
+  puppet.messageVoiceText = sinon.stub().rejects(new TypeError('innerHelper.process is not a function'))
+  puppet.messagePayload   = sinon.stub().resolves({ text: 'legacy asr' } as PUPPET.payloads.Message)
+
+  await t.rejects(() => voice().text(), /is not a function/, 'should rethrow the internal TypeError')
+  t.notOk(puppet.messagePayload.called, 'should NOT mask a real implementation bug')
+})
+
+test('teardown: stop the shared wechaty', async t => {
+  await wechaty.stop()
+  t.pass('stopped')
+})

package/src/user-modules/voice.ts

@@ -0,0 +1,159 @@
+/**
+ *   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 type {
+  FileBoxInterface,
+}                   from 'file-box'
+import type { Constructor } from 'clone-class'
+import type * as PUPPET from '@juzi/wechaty-puppet'
+import { validationMixin } from '../user-mixins/validation.js'
+import { log } from '../config.js'
+
+import {
+  wechatifyMixinBase,
+}                       from '../user-mixins/wechatify.js'
+
+/**
+ * gRPC status code for an RPC the server does not implement.
+ * @see https://grpc.github.io/grpc/core/md_doc_statuscodes.html
+ */
+const GRPC_STATUS_UNIMPLEMENTED = 12
+
+/**
+ * Whether `e` means the puppet / server does not implement the new voice RPC,
+ * i.e. it is safe to fall back to the legacy path.
+ *
+ * Transient errors (network / timeout / file expired / other gRPC codes) must
+ * NOT match here: otherwise the fallback silently masks real failures and — for
+ * `text()` — discards the `noSpeech` discriminator, making the bot re-run its
+ * own paid ASR on voices the puppet already confirmed as empty.
+ *
+ * Note: the "method does not exist at all" case (an old puppet built against a
+ * wechaty-puppet without the method) is detected up-front via a `typeof` guard
+ * at the call site, NOT here — matching the `'is not a function'` text would
+ * also swallow a genuine `TypeError` raised inside a working implementation.
+ */
+function isUnsupportedError (e: unknown): boolean {
+  const err = e as { code?: number | string; message?: string } | undefined
+  // old wechaty-puppet-service server without the new RPC → gRPC UNIMPLEMENTED
+  if (err?.code === GRPC_STATUS_UNIMPLEMENTED) {
+    return true
+  }
+  // puppet implements the abstract method via throwUnsupportedError()
+  return (err?.message || '').includes('Unsupported API')
+}
+
+class VoiceMixin extends wechatifyMixinBase() {
+
+  static create (id: string): VoiceInterface {
+    log.verbose('Voice', 'static create(%s)', id)
+
+    const voice = new this(id)
+    return voice
+  }
+
+  constructor (
+    public id: string,
+  ) {
+    super()
+    log.verbose('Voice', 'constructor(%s)', id)
+  }
+
+  /**
+   * Get the voice file (FileBox) via the puppet's dedicated `messageVoice` RPC.
+   *
+   * Falls back to the generic `messageFile` when the puppet does not implement
+   * `messageVoice` — either the method is absent (old puppet built without it,
+   * caught by the `typeof` guard) or it rejects with an unsupported-API error.
+   * Keeps the behaviour compatible with the legacy "voice file via messageFile"
+   * path. A genuine runtime error from a working `messageVoice` is rethrown.
+   */
+  async file (): Promise<FileBoxInterface> {
+    log.verbose('Voice', 'file() for id: "%s"', this.id)
+    const puppet = this.wechaty.puppet
+    // puppet built against an old wechaty-puppet without the method at all
+    if (typeof (puppet as { messageVoice?: unknown }).messageVoice !== 'function') {
+      log.verbose('Voice', 'file() messageVoice() absent, fallback to messageFile()')
+      return puppet.messageFile(this.id)
+    }
+    try {
+      const fileBox = await puppet.messageVoice(this.id)
+      return fileBox
+    } catch (e) {
+      if (!isUnsupportedError(e)) {
+        throw e
+      }
+      log.verbose('Voice', 'file() messageVoice() unsupported, fallback to messageFile(): %s', (e as Error).message)
+      const fileBox = await puppet.messageFile(this.id)
+      return fileBox
+    }
+  }
+
+  /**
+   * Get the voice-to-text (ASR) result via the puppet's dedicated
+   * `messageVoiceText` RPC. Returns a discriminated result so the bot can tell
+   * "confirmed no speech" (`noSpeech=true`) from "normal transcription".
+   *
+   * Falls back to reading the legacy `messagePayload().text` when the puppet
+   * does not implement `messageVoiceText` — either the method is absent (old
+   * puppet built without it, caught by the `typeof` guard) or it rejects with
+   * an unsupported-API error. Old puppets put the ASR result into
+   * `payload.text`, so this keeps the behaviour compatible; `noSpeech` is
+   * `false` in the fallback. A genuine runtime error is rethrown (so the bot
+   * does not silently drop `noSpeech` and re-run its own paid ASR).
+   */
+  async text (): Promise<PUPPET.payloads.VoiceText> {
+    log.verbose('Voice', 'text() for id: "%s"', this.id)
+    const puppet = this.wechaty.puppet
+    // puppet built against an old wechaty-puppet without the method at all
+    if (typeof (puppet as { messageVoiceText?: unknown }).messageVoiceText !== 'function') {
+      log.verbose('Voice', 'text() messageVoiceText() absent, fallback to messagePayload().text')
+      const payload = await puppet.messagePayload(this.id)
+      return { text: payload.text || '', noSpeech: false }
+    }
+    try {
+      const payload = await puppet.messageVoiceText(this.id)
+      return payload
+    } catch (e) {
+      if (!isUnsupportedError(e)) {
+        throw e
+      }
+      log.verbose('Voice', 'text() messageVoiceText() unsupported, fallback to messagePayload().text: %s', (e as Error).message)
+      const payload = await puppet.messagePayload(this.id)
+      return { text: payload.text || '', noSpeech: false }
+    }
+  }
+
+}
+
+class VoiceImpl extends validationMixin(VoiceMixin)<VoiceInterface>() {}
+interface VoiceInterface extends VoiceImpl { }
+
+type VoiceConstructor = Constructor<
+  VoiceInterface,
+  typeof VoiceImpl
+>
+
+export type {
+  VoiceConstructor,
+  VoiceInterface,
+}
+export {
+  VoiceImpl,
+}

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

@@ -9,6 +9,7 @@ import type {
   ContactConstructor,
   FriendshipConstructor,
   ImageConstructor,
+  VoiceConstructor,
   LocationConstructor,
   MessageConstructor,
   MiniProgramConstructor,
@@ -51,6 +52,7 @@ test('Wechaty interface', async t => {
     Delay                         : DelayConstructor
     Friendship                    : FriendshipConstructor
     Image                         : ImageConstructor
+    Voice                         : VoiceConstructor
     Location                      : LocationConstructor
     Message                       : MessageConstructor
     MiniProgram                   : MiniProgramConstructor
@@ -82,6 +84,7 @@ test('Wechaty interface', async t => {
         = this.Delay
         = this.Friendship
         = this.Image
+        = this.Voice
         = this.Location
         = this.Message
         = this.MiniProgram

package/src/wechaty-mixins/wechatify-user-module-mixin.ts

@@ -7,6 +7,7 @@ import {
   DelayImpl,
   FriendshipImpl,
   ImageImpl,
+  VoiceImpl,
   LocationImpl,
   MessageImpl,
   MiniProgramImpl,
@@ -35,6 +36,7 @@ import {
   DelayConstructor,
   FriendshipConstructor,
   ImageConstructor,
+  VoiceConstructor,
   LocationConstructor,
   MessageConstructor,
   MiniProgramConstructor,
@@ -79,6 +81,7 @@ const wechatifyUserModuleMixin = <MixinBase extends typeof WechatySkeleton> (mix
     __wechatifiedDelay?                         : DelayConstructor
     __wechatifiedFriendship?                    : FriendshipConstructor
     __wechatifiedImage?                         : ImageConstructor
+    __wechatifiedVoice?                         : VoiceConstructor
     __wechatifiedLocation?                      : LocationConstructor
     __wechatifiedMessage?                       : MessageConstructor
     __wechatifiedMiniProgram?                   : MiniProgramConstructor
@@ -107,6 +110,7 @@ const wechatifyUserModuleMixin = <MixinBase extends typeof WechatySkeleton> (mix
     get Delay ()                        : DelayConstructor                          { return guardWechatify(this.__wechatifiedDelay)          }
     get Friendship ()                   : FriendshipConstructor                     { return guardWechatify(this.__wechatifiedFriendship)     }
     get Image ()                        : ImageConstructor                          { return guardWechatify(this.__wechatifiedImage)          }
+    get Voice ()                        : VoiceConstructor                          { return guardWechatify(this.__wechatifiedVoice)          }
     get Location ()                     : LocationConstructor                       { return guardWechatify(this.__wechatifiedLocation)       }
     get Message ()                      : MessageConstructor                        { return guardWechatify(this.__wechatifiedMessage)        }
     get MiniProgram ()                  : MiniProgramConstructor                    { return guardWechatify(this.__wechatifiedMiniProgram)    }
@@ -155,6 +159,7 @@ const wechatifyUserModuleMixin = <MixinBase extends typeof WechatySkeleton> (mix
       this.__wechatifiedDelay                        = wechatifyUserModule(DelayImpl)(this as any)
       this.__wechatifiedFriendship                   = wechatifyUserModule(FriendshipImpl)(this as any)
       this.__wechatifiedImage                        = wechatifyUserModule(ImageImpl)(this as any)
+      this.__wechatifiedVoice                        = wechatifyUserModule(VoiceImpl)(this as any)
       this.__wechatifiedLocation                     = wechatifyUserModule(LocationImpl)(this as any)
       this.__wechatifiedMessage                      = wechatifyUserModule(MessageImpl)(this as any)
       this.__wechatifiedMiniProgram                  = wechatifyUserModule(MiniProgramImpl)(this as any)
@@ -204,6 +209,7 @@ type ProtectedPropertyWechatifyUserModuleMixin =
   | '__wechatifiedDelay'
   | '__wechatifiedFriendship'
   | '__wechatifiedImage'
+  | '__wechatifiedVoice'
   | '__wechatifiedLocation'
   | '__wechatifiedMessage'
   | '__wechatifiedMiniProgram'