@juzi/wechaty 1.0.150 → 1.0.156

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

@@ -21,6 +21,7 @@ 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'
 
@@ -28,6 +29,36 @@ 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 {
@@ -48,17 +79,28 @@ class VoiceMixin extends wechatifyMixinBase() {
    * 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` (old puppet without the new RPC → rejection), keeping the
-   * behaviour compatible with the legacy "voice file via messageFile" path.
+   * `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 this.wechaty.puppet.messageVoice(this.id)
+      const fileBox = await puppet.messageVoice(this.id)
       return fileBox
     } catch (e) {
-      log.verbose('Voice', 'file() messageVoice() failed, fallback to messageFile(): %s', (e as Error).message)
-      const fileBox = await this.wechaty.puppet.messageFile(this.id)
+      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
     }
   }
@@ -69,18 +111,31 @@ class VoiceMixin extends wechatifyMixinBase() {
    * "confirmed no speech" (`noSpeech=true`) from "normal transcription".
    *
    * Falls back to reading the legacy `messagePayload().text` when the puppet
-   * does not implement `messageVoiceText` (old puppet without the new RPC →
-   * rejection). Old puppets put the ASR result into `payload.text`, so this
-   * keeps the behaviour compatible; `noSpeech` is `false` in the fallback.
+   * 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<{ text: string; noSpeech: boolean }> {
+  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 this.wechaty.puppet.messageVoiceText(this.id)
+      const payload = await puppet.messageVoiceText(this.id)
       return payload
     } catch (e) {
-      log.verbose('Voice', 'text() messageVoiceText() failed, fallback to messagePayload().text: %s', (e as Error).message)
-      const payload = await this.wechaty.puppet.messagePayload(this.id)
+      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 }
     }
   }

package/src/wechaty-mixins/puppet-mixin-dirty-call.spec.ts

@@ -0,0 +1,55 @@
+#!/usr/bin/env -S node --no-warnings --loader ts-node/esm
+
+import { test }        from 'tstest'
+import * as PUPPET     from '@juzi/wechaty-puppet'
+import { PuppetMock }  from '@juzi/wechaty-puppet-mock'
+
+import { WechatyBuilder } from '../wechaty-builder.js'
+
+/**
+ * Regression: the dirty event listener for `Payload.Call` in `puppet-mixin`
+ * used to do `await this.puppet.callPayloadDirty(payloadId)` inside the
+ * handler itself.
+ *
+ * Under wechaty-puppet-service, `callPayloadDirty` fires a gRPC
+ * `DirtyPayload` to the server, which then re-emits `dirty` back to the
+ * client through the event stream. That re-emit triggers the handler
+ * again, forming an infinite client⇄server feedback loop.
+ *
+ * All other dirty branches (Contact / Room / Message / Wxxd*) only call
+ * `find(...).ready(true)`; the Call branch was the outlier.
+ *
+ * The fix removes the in-handler `callPayloadDirty` call so the branch
+ * matches the rest of the template. This test pins that contract:
+ * emitting a Call-typed dirty event must NOT cause the handler to call
+ * `puppet.callPayloadDirty` again.
+ */
+test('dirty(Call) handler must NOT call callPayloadDirty (would form a gRPC loop)', async t => {
+  const puppet = new PuppetMock() as any
+  const wechaty = WechatyBuilder.build({ puppet })
+
+  await wechaty.start()
+
+  let dirtyCallCount = 0
+  const originalCallPayloadDirty = puppet.callPayloadDirty.bind(puppet)
+  puppet.callPayloadDirty = async (id: string) => {
+    dirtyCallCount++
+    return originalCallPayloadDirty(id)
+  }
+
+  puppet.emit('dirty', {
+    payloadType: PUPPET.types.Payload.Call,
+    payloadId:   'call-id-x',
+  })
+
+  // Allow the async handler to run.
+  await new Promise(resolve => setTimeout(resolve, 50))
+
+  t.equal(
+    dirtyCallCount,
+    0,
+    `dirty(Call) handler must not re-invoke callPayloadDirty; got ${dirtyCallCount} call(s)`,
+  )
+
+  await wechaty.stop()
+})

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

@@ -753,16 +753,21 @@ const puppetMixin = <MixinBase extends WechatifyUserModuleMixin & GErrorMixin &
                   }
                   case PUPPET.types.Payload.Call: {
                     /**
-                     * Invalidate the puppet-side cache so the next callPayload()
-                     * pull reflects the latest server state, then refresh the
-                     * user-layer Call payload so getters (media / participants /
-                     * endTime) reflect the new view immediately. Whether the
-                     * call is still alive is still decided by the call-event
-                     * handler via __finalizeIfEnded; we do not touch the pool
-                     * here, and we do not emit a synthetic user event — the
-                     * UI is expected to read getters when it needs the value.
+                     * Refresh the user-layer Call payload so getters (media /
+                     * participants / endTime) reflect the new view. Whether
+                     * the call is still alive is still decided by the
+                     * call-event handler via __finalizeIfEnded; we do not
+                     * touch the pool here, and we do not emit a synthetic
+                     * user event — the UI is expected to read getters when
+                     * it needs the value.
+                     *
+                     * IMPORTANT: do NOT call puppet.callPayloadDirty here.
+                     * Under puppet-service that fires a gRPC DirtyPayload
+                     * which the server bounces back as another `dirty`
+                     * event, forming an infinite client⇄server feedback
+                     * loop. Cache invalidation is already handled by the
+                     * cache-mixin onDirty listener registered alongside.
                      */
-                    await this.puppet.callPayloadDirty(payloadId)
                     const call = this.__callPool.get(payloadId)
                     if (call) {
                       try {