@juzi/wechaty-puppet-service 1.0.127 → 1.0.129

package/dist/esm/src/server/puppet-implementation.spec.js

@@ -0,0 +1,77 @@
+#!/usr/bin/env -S node --no-warnings --loader ts-node/esm
+import { sinon, test, } from 'tstest';
+import { FileBox } from 'file-box';
+import { puppet as grpcPuppet } from '@juzi/wechaty-grpc';
+import { PuppetMock } from '@juzi/wechaty-puppet-mock';
+import { puppetImplementation } from './puppet-implementation.js';
+function buildRequest(options) {
+    const request = new grpcPuppet.CallInviteWithMediaRequest();
+    request.setContactIdsList(options.contactIds);
+    request.setFileBox(options.fileBox ?? '');
+    request.setHangupOnFinish(options.hangupOnFinish ?? false);
+    request.setHangupDelayMs(options.hangupDelayMs ?? 0);
+    return request;
+}
+async function invokeCallInviteWithMedia(puppet, request) {
+    const impl = puppetImplementation(puppet, FileBox);
+    return new Promise(resolve => {
+        void impl.callInviteWithMedia({ request }, ((error, response) => resolve({ error, response })));
+    });
+}
+test('callInviteWithMedia rejects an empty contact_ids list', async (t) => {
+    const puppet = new PuppetMock();
+    const stub = sinon.stub().resolves('call-id');
+    puppet.callInviteWithMedia = stub;
+    const { error } = await invokeCallInviteWithMedia(puppet, buildRequest({
+        contactIds: [],
+        hangupOnFinish: true,
+    }));
+    t.match(error?.message, /contact_ids is required/, 'reports the missing contact_ids');
+    t.equal(stub.callCount, 0, 'never reaches the puppet');
+});
+test('callInviteWithMedia rejects an empty file_box combined with hangup_on_finish false', async (t) => {
+    const puppet = new PuppetMock();
+    const stub = sinon.stub().resolves('call-id');
+    puppet.callInviteWithMedia = stub;
+    const { error } = await invokeCallInviteWithMedia(puppet, buildRequest({
+        contactIds: ['contact-1'],
+        hangupOnFinish: false,
+    }));
+    t.match(error?.message, /use CallInvite directly/, 'points the caller at the equivalent CallInvite');
+    t.equal(stub.callCount, 0, 'never reaches the puppet');
+});
+test('callInviteWithMedia forwards a file-less invite as an undefined file', async (t) => {
+    const puppet = new PuppetMock();
+    const stub = sinon.stub().resolves('call-id-no-file');
+    puppet.callInviteWithMedia = stub;
+    const { error, response } = await invokeCallInviteWithMedia(puppet, buildRequest({
+        contactIds: ['contact-1'],
+        hangupDelayMs: 1500,
+        hangupOnFinish: true,
+    }));
+    t.equal(error, null, 'accepts the file-less invite');
+    t.equal(response?.getCallId(), 'call-id-no-file', 'returns the callId from the puppet');
+    t.same(stub.args[0], [['contact-1'], undefined, { hangupDelayMs: 1500, hangupOnFinish: true }], 'forwards contactIds, an undefined file and the orchestration options');
+});
+test('callInviteWithMedia deserializes a non-empty file_box into a FileBox', async (t) => {
+    const puppet = new PuppetMock();
+    const stub = sinon.stub().resolves('call-id-with-file');
+    puppet.callInviteWithMedia = stub;
+    const file = FileBox.fromUrl('https://example.com/notice.mp3', { name: 'notice.mp3' });
+    const { error } = await invokeCallInviteWithMedia(puppet, buildRequest({
+        contactIds: ['contact-1'],
+        fileBox: JSON.stringify(file),
+    }));
+    t.equal(error, null, 'accepts the invite carrying a file');
+    t.equal(stub.args[0]?.[1]?.name, 'notice.mp3', 'hands the puppet a FileBox rebuilt from file_box');
+});
+test('callInviteWithMedia rejects an empty callId returned by the puppet', async (t) => {
+    const puppet = new PuppetMock();
+    puppet.callInviteWithMedia = sinon.stub().resolves('');
+    const { error } = await invokeCallInviteWithMedia(puppet, buildRequest({
+        contactIds: ['contact-1'],
+        hangupOnFinish: true,
+    }));
+    t.match(error?.message, /empty callId/, 'does not pass an unusable empty callId back on the wire');
+});
+//# sourceMappingURL=puppet-implementation.spec.js.map

package/dist/esm/src/server/puppet-implementation.spec.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"puppet-implementation.spec.js","sourceRoot":"","sources":["../../../../src/server/puppet-implementation.spec.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@juzi/wechaty-puppet-service",
-  "version": "1.0.127",
+  "version": "1.0.129",
   "description": "Puppet Service for Wechaty",
   "type": "module",
   "exports": {
@@ -51,7 +51,7 @@
     "@chatie/eslint-config": "^1.0.4",
     "@chatie/semver": "^0.4.7",
     "@chatie/tsconfig": "^4.6.3",
-    "@juzi/wechaty-puppet": "^1.0.151",
+    "@juzi/wechaty-puppet": "^1.0.156",
     "@juzi/wechaty-puppet-mock": "^1.0.1",
     "@swc/core": "1.3.39",
     "@types/google-protobuf": "^3.15.5",
@@ -71,10 +71,10 @@
     "why-is-node-running": "^2.2.1"
   },
   "peerDependencies": {
-    "@juzi/wechaty-puppet": "^1.0.151"
+    "@juzi/wechaty-puppet": "^1.0.156"
   },
   "dependencies": {
-    "@juzi/wechaty-grpc": "^1.0.106",
+    "@juzi/wechaty-grpc": "^1.0.108",
     "clone-class": "^1.1.1",
     "ducks": "^1.0.2",
     "file-box": "^1.5.5",

package/src/client/puppet-service.spec.ts

@@ -6,6 +6,9 @@ import {
 }  from 'tstest'
 import getPort from 'get-port'
 
+import { FileBox } from 'file-box'
+import { puppet as grpcPuppet } from '@juzi/wechaty-grpc'
+
 import { PuppetMock } from '@juzi/wechaty-puppet-mock'
 
 import { PuppetService } from './puppet-service.js'
@@ -74,6 +77,83 @@ test('batchRoomRawPayload still rejects when every per-room fallback fails', asy
   )
 })
 
+let callInviteWithMediaTestId = 0
+
+function createCallInviteWithMediaPuppet (
+  callId: string,
+): { puppet: PuppetService, requestList: grpcPuppet.CallInviteWithMediaRequest[] } {
+  const puppet = new PuppetService({
+    token: `call-invite-with-media-test-${callInviteWithMediaTestId++}`,
+  })
+
+  const requestList: grpcPuppet.CallInviteWithMediaRequest[] = []
+
+  ;(puppet as any)._grpcManager = {
+    client: {
+      callInviteWithMedia: (
+        request  : grpcPuppet.CallInviteWithMediaRequest,
+        callback : (error: null | Error, response: grpcPuppet.CallInviteWithMediaResponse) => void,
+      ) => {
+        requestList.push(request)
+
+        const response = new grpcPuppet.CallInviteWithMediaResponse()
+        response.setCallId(callId)
+        callback(null, response)
+      },
+    },
+  }
+
+  return { puppet, requestList }
+}
+
+test('callInviteWithMedia maps the file and the orchestration options onto the request', async t => {
+  const { puppet, requestList } = createCallInviteWithMediaPuppet('call-id-with-file')
+
+  const file = FileBox.fromUrl('https://example.com/notice.mp3', { name: 'notice.mp3' })
+
+  const callId = await puppet.callInviteWithMedia(
+    [ 'contact-1', 'contact-2' ],
+    file,
+    { hangupDelayMs: 800, hangupOnFinish: true },
+  )
+
+  t.equal(callId, 'call-id-with-file', 'returns the call_id from the server response')
+  t.equal(requestList.length, 1, 'sends exactly one request')
+
+  const request = requestList[0]!
+  t.same(request.getContactIdsList(), [ 'contact-1', 'contact-2' ], 'maps contactIds onto contact_ids')
+  t.equal(request.getHangupOnFinish(), true, 'maps hangupOnFinish onto hangup_on_finish')
+  t.equal(request.getHangupDelayMs(), 800, 'maps hangupDelayMs onto hangup_delay_ms')
+  t.equal(
+    JSON.parse(request.getFileBox()).name,
+    'notice.mp3',
+    'serializes the FileBox onto file_box',
+  )
+})
+
+test('callInviteWithMedia leaves file_box empty and defaults the options when they are omitted', async t => {
+  const { puppet, requestList } = createCallInviteWithMediaPuppet('call-id-no-file')
+
+  const callId = await puppet.callInviteWithMedia([ 'contact-1' ])
+
+  t.equal(callId, 'call-id-no-file', 'returns the call_id from the server response')
+
+  const request = requestList[0]!
+  t.equal(request.getFileBox(), '', 'leaves file_box empty when no file is given')
+  t.equal(request.getHangupOnFinish(), false, 'defaults hangup_on_finish to false')
+  t.equal(request.getHangupDelayMs(), 0, 'defaults hangup_delay_ms to 0')
+})
+
+test('callInviteWithMedia rejects when the server returns an empty call_id', async t => {
+  const { puppet } = createCallInviteWithMediaPuppet('')
+
+  await t.rejects(
+    puppet.callInviteWithMedia([ 'contact-1' ], undefined, { hangupOnFinish: true }),
+    /empty call_id/,
+    'does not hand back an unusable empty call_id',
+  )
+})
+
 test('version()', async t => {
   const puppet = new PuppetService({
     token: 'test',

package/src/client/puppet-service.ts

@@ -56,6 +56,7 @@ import { PayloadStore } from './payload-store.js'
 import { OptionalBooleanUnwrapper, OptionalBooleanWrapper, callRecordPbToPayload, channelPayloadToPb, channelPbToPayload, chatHistoryPbToPayload, contactPbToPayload, postPayloadToPb, roomMemberPbToPayload, urlLinkPbToPayload, channelCardPayloadToPb, channelCardPbToPayload, miniProgramPayloadToPb, urlLinkPayloadToPb, locationPayloadToPb } from '../utils/pb-payload-helper.js'
 import { puppetCallMediaTypeToGrpc, grpcCallTypeToPuppetMedia } from '../utils/call-media-mapping.js'
 import type { MessageBroadcastTargets } from '@juzi/wechaty-puppet/dist/esm/src/schemas/message.js'
+import type { CallInviteWithMediaOptions } from '@juzi/wechaty-puppet/dist/esm/src/schemas/call.js'
 import { timeoutPromise } from 'gerror'
 import { BooleanIndicator } from 'state-switch'
 import type { Contact } from '@juzi/wechaty-puppet/types'
@@ -428,6 +429,9 @@ class PuppetService extends PUPPET.Puppet {
       case grpcPuppet.EventType.EVENT_TYPE_VERIFY_SLIDE:
         this.emit('verify-slide', JSON.parse(payload) as PUPPET.payloads.EventVerifySlide)
         break
+      case grpcPuppet.EventType.EVENT_TYPE_SAME_NET_VERIFY:
+        this.emit('same-net-verify', JSON.parse(payload) as PUPPET.payloads.EventSameNetVerify)
+        break
       case grpcPuppet.EventType.EVENT_TYPE_CALL:
         this.emit('call', JSON.parse(payload) as PUPPET.payloads.EventCall)
         break
@@ -1184,6 +1188,38 @@ class PuppetService extends PUPPET.Puppet {
     return callId
   }
 
+  override async callInviteWithMedia (
+    contactIds : string[],
+    file?      : FileBoxInterface,
+    options?   : CallInviteWithMediaOptions,
+  ): Promise<string> {
+    this.log.verbose('PuppetService', 'callInviteWithMedia(%s, %s, %s)',
+      contactIds,
+      file?.name,
+      JSON.stringify(options),
+    )
+
+    const request = new grpcPuppet.CallInviteWithMediaRequest()
+    request.setContactIdsList(contactIds)
+    if (file) {
+      request.setFileBox(await this.serializeFileBox(file))
+    }
+    request.setHangupOnFinish(options?.hangupOnFinish ?? false)
+    request.setHangupDelayMs(options?.hangupDelayMs ?? 0)
+
+    const response = await util.promisify(
+      this.grpcManager.client.callInviteWithMedia
+        .bind(this.grpcManager.client),
+    )(request)
+
+    const callId = response.getCallId()
+    if (!callId) {
+      throw new Error('callInviteWithMedia: puppet server returned empty call_id')
+    }
+
+    return callId
+  }
+
   override async callAdd (
     callId: string,
     contactIds: string[],

package/src/package-json.ts

@@ -4,7 +4,7 @@
 import type { PackageJson } from 'type-fest'
 export const packageJson: PackageJson = {
   "name": "@juzi/wechaty-puppet-service",
-  "version": "1.0.127",
+  "version": "1.0.129",
   "description": "Puppet Service for Wechaty",
   "type": "module",
   "exports": {
@@ -55,7 +55,7 @@ export const packageJson: PackageJson = {
     "@chatie/eslint-config": "^1.0.4",
     "@chatie/semver": "^0.4.7",
     "@chatie/tsconfig": "^4.6.3",
-    "@juzi/wechaty-puppet": "^1.0.151",
+    "@juzi/wechaty-puppet": "^1.0.156",
     "@juzi/wechaty-puppet-mock": "^1.0.1",
     "@swc/core": "1.3.39",
     "@types/google-protobuf": "^3.15.5",
@@ -75,10 +75,10 @@ export const packageJson: PackageJson = {
     "why-is-node-running": "^2.2.1"
   },
   "peerDependencies": {
-    "@juzi/wechaty-puppet": "^1.0.151"
+    "@juzi/wechaty-puppet": "^1.0.156"
   },
   "dependencies": {
-    "@juzi/wechaty-grpc": "^1.0.106",
+    "@juzi/wechaty-grpc": "^1.0.108",
     "clone-class": "^1.1.1",
     "ducks": "^1.0.2",
     "file-box": "^1.5.5",

package/src/server/event-stream-manager.ts

@@ -322,6 +322,13 @@ class EventStreamManager {
           this.offCallbackList.push(off)
           break
         }
+        case 'same-net-verify': {
+          const listener = (payload: PUPPET.payloads.EventSameNetVerify) => this.grpcEmit(grpcPuppet.EventType.EVENT_TYPE_SAME_NET_VERIFY, payload)
+          this.puppet.on('same-net-verify', listener)
+          const off = () => this.puppet.off('same-net-verify', listener)
+          this.offCallbackList.push(off)
+          break
+        }
         case 'call': {
           const listener = (payload: PUPPET.payloads.EventCall) => this.grpcEmit(grpcPuppet.EventType.EVENT_TYPE_CALL, payload)
           this.puppet.on('call', listener)

package/src/server/puppet-implementation.spec.ts

@@ -0,0 +1,121 @@
+#!/usr/bin/env -S node --no-warnings --loader ts-node/esm
+
+import {
+  sinon,
+  test,
+}  from 'tstest'
+
+import { FileBox } from 'file-box'
+import { puppet as grpcPuppet } from '@juzi/wechaty-grpc'
+
+import { PuppetMock } from '@juzi/wechaty-puppet-mock'
+
+import { puppetImplementation } from './puppet-implementation.js'
+
+interface CallInviteWithMediaCase {
+  contactIds      : string[]
+  fileBox?        : string
+  hangupOnFinish? : boolean
+  hangupDelayMs?  : number
+}
+
+function buildRequest (
+  options: CallInviteWithMediaCase,
+): grpcPuppet.CallInviteWithMediaRequest {
+  const request = new grpcPuppet.CallInviteWithMediaRequest()
+  request.setContactIdsList(options.contactIds)
+  request.setFileBox(options.fileBox ?? '')
+  request.setHangupOnFinish(options.hangupOnFinish ?? false)
+  request.setHangupDelayMs(options.hangupDelayMs ?? 0)
+  return request
+}
+
+async function invokeCallInviteWithMedia (
+  puppet  : any,
+  request : grpcPuppet.CallInviteWithMediaRequest,
+): Promise<{ error: null | Error, response: null | grpcPuppet.CallInviteWithMediaResponse }> {
+  const impl = puppetImplementation(puppet, FileBox)
+
+  return new Promise(resolve => {
+    void impl.callInviteWithMedia(
+      { request } as any,
+      ((error: any, response: any) => resolve({ error, response })) as any,
+    )
+  })
+}
+
+test('callInviteWithMedia rejects an empty contact_ids list', async t => {
+  const puppet = new PuppetMock() as any
+  const stub   = sinon.stub().resolves('call-id')
+  puppet.callInviteWithMedia = stub
+
+  const { error } = await invokeCallInviteWithMedia(puppet, buildRequest({
+    contactIds     : [],
+    hangupOnFinish : true,
+  }))
+
+  t.match(error?.message, /contact_ids is required/, 'reports the missing contact_ids')
+  t.equal(stub.callCount, 0, 'never reaches the puppet')
+})
+
+test('callInviteWithMedia rejects an empty file_box combined with hangup_on_finish false', async t => {
+  const puppet = new PuppetMock() as any
+  const stub   = sinon.stub().resolves('call-id')
+  puppet.callInviteWithMedia = stub
+
+  const { error } = await invokeCallInviteWithMedia(puppet, buildRequest({
+    contactIds     : [ 'contact-1' ],
+    hangupOnFinish : false,
+  }))
+
+  t.match(error?.message, /use CallInvite directly/, 'points the caller at the equivalent CallInvite')
+  t.equal(stub.callCount, 0, 'never reaches the puppet')
+})
+
+test('callInviteWithMedia forwards a file-less invite as an undefined file', async t => {
+  const puppet = new PuppetMock() as any
+  const stub   = sinon.stub().resolves('call-id-no-file')
+  puppet.callInviteWithMedia = stub
+
+  const { error, response } = await invokeCallInviteWithMedia(puppet, buildRequest({
+    contactIds     : [ 'contact-1' ],
+    hangupDelayMs  : 1500,
+    hangupOnFinish : true,
+  }))
+
+  t.equal(error, null, 'accepts the file-less invite')
+  t.equal(response?.getCallId(), 'call-id-no-file', 'returns the callId from the puppet')
+  t.same(
+    stub.args[0],
+    [ [ 'contact-1' ], undefined, { hangupDelayMs: 1500, hangupOnFinish: true } ],
+    'forwards contactIds, an undefined file and the orchestration options',
+  )
+})
+
+test('callInviteWithMedia deserializes a non-empty file_box into a FileBox', async t => {
+  const puppet = new PuppetMock() as any
+  const stub   = sinon.stub().resolves('call-id-with-file')
+  puppet.callInviteWithMedia = stub
+
+  const file = FileBox.fromUrl('https://example.com/notice.mp3', { name: 'notice.mp3' })
+
+  const { error } = await invokeCallInviteWithMedia(puppet, buildRequest({
+    contactIds : [ 'contact-1' ],
+    fileBox    : JSON.stringify(file),
+  }))
+
+  t.equal(error, null, 'accepts the invite carrying a file')
+  t.equal(stub.args[0]?.[1]?.name, 'notice.mp3', 'hands the puppet a FileBox rebuilt from file_box')
+})
+
+test('callInviteWithMedia rejects an empty callId returned by the puppet', async t => {
+  const puppet = new PuppetMock() as any
+  puppet.callInviteWithMedia = sinon.stub().resolves('')
+
+  const { error } = await invokeCallInviteWithMedia(puppet, buildRequest({
+    contactIds     : [ 'contact-1' ],
+    hangupOnFinish : true,
+  }))
+
+  t.match(error?.message, /empty callId/, 'does not pass an unusable empty callId back on the wire')
+})

package/src/server/puppet-implementation.ts

@@ -3060,6 +3060,41 @@ function puppetImplementation (
       }
     },
 
+    callInviteWithMedia: async (call, callback) => {
+      log.verbose('PuppetServiceImpl', 'callInviteWithMedia()')
+
+      try {
+        const contactIds = call.request.getContactIdsList()
+        if (contactIds.length === 0) {
+          throw new Error('callInviteWithMedia: contact_ids is required')
+        }
+
+        const jsonText       = call.request.getFileBox()
+        const file           = jsonText ? FileBoxUuid.fromJSON(jsonText) : undefined
+        const hangupOnFinish = call.request.getHangupOnFinish()
+        const hangupDelayMs  = call.request.getHangupDelayMs()
+
+        if (!file && !hangupOnFinish) {
+          throw new Error('callInviteWithMedia: hangup_on_finish must be true when file_box is empty, otherwise it is equivalent to CallInvite — use CallInvite directly')
+        }
+
+        const callId = await puppet.callInviteWithMedia(contactIds, file, {
+          hangupDelayMs,
+          hangupOnFinish,
+        })
+        if (!callId) {
+          throw new Error('callInviteWithMedia: puppet returned empty callId')
+        }
+
+        const response = new grpcPuppet.CallInviteWithMediaResponse()
+        response.setCallId(callId)
+
+        return callback(null, response)
+      } catch (e) {
+        return grpcError('callInviteWithMedia', e, callback)
+      }
+    },
+
     callAdd: async (call, callback) => {
       log.verbose('PuppetServiceImpl', 'callAdd()')