feat: add stable proactive delivery

src/channels/whatsapp/whatsapp-controller.mjs

@@ -224,6 +224,20 @@ export class WhatsappController {
     });
   }
 
+  async sendProactiveText(botId, target, text, options = {}) {
+    const config = this.#configStore.get(botId);
+    if (!config) throw new Error('Unknown WhatsApp bot');
+    return this.#withBotTransition(botId, async () => {
+      const runtime = this.#runtimes.get(botId);
+      if (!runtime?.status?.ready || typeof runtime.sendProactiveText !== 'function') {
+        const error = new Error(t('WhatsApp机器人尚未连接'));
+        error.code = 'bot-not-connected';
+        throw error;
+      }
+      return runtime.sendProactiveText(target, text, options);
+    });
+  }
+
   async setAccessPolicy(botId, value) {
     if (this.#closed) throw new Error('WhatsApp controller is closed');
     const accessPolicy = normalizeWhatsappAccessPolicy(value);

src/channels/whatsapp/whatsapp-runtime.mjs

@@ -719,6 +719,25 @@ export class WhatsappRuntime {
     return { sent: true };
   }
 
+  async sendProactiveText(target, text, { signal } = {}) {
+    const jid = typeof target?.route?.jid === 'string' ? target.route.jid.trim() : '';
+    const validUser = target?.kind === 'user'
+      && /^[^@\s]+@(s\.whatsapp\.net|lid)$/.test(jid);
+    const validGroup = target?.kind === 'group' && /^[^@\s]+@g\.us$/.test(jid);
+    if (!validUser && !validGroup) {
+      const error = new TypeError('Invalid WhatsApp proactive delivery target');
+      error.code = 'invalid-target';
+      throw error;
+    }
+    if (!this.#status.ready || !this.#client) {
+      const error = new Error(t('WhatsApp机器人尚未连接'));
+      error.code = 'bot-not-connected';
+      throw error;
+    }
+    signal?.throwIfAborted();
+    return this.#client.sendText({ jid }, text);
+  }
+
   async stop() {
     const session = this.#session;
     const client = this.#client;