@weaccelerateinc/agent-sdk 0.10.3 → 0.12.0

package/whatsapp-messaging.js

@@ -0,0 +1,182 @@
+import { createHash } from 'node:crypto';
+import { AccelerateError } from './index.js';
+import { authenticatedCheckoutContext } from './host-adapter.js';
+
+const id = /^[A-Za-z0-9][A-Za-z0-9_.:+/=-]{0,499}$/;
+const safeId = value => `wa:${hash(value)}`;
+const digits = /^[1-9]\d{5,19}$/;
+const keyPattern = /^[A-Za-z0-9_.:-]{1,200}$/;
+const fail = () => { throw new AccelerateError('request_failed'); };
+const check = value => { if (!value) fail(); };
+const hash = value => createHash('sha256').update(JSON.stringify(value)).digest('hex');
+const validTime = value => typeof value === 'string' && /^\d{4}-\d\d-\d\dT\d\d:\d\d:\d\d\.\d{3}Z$/.test(value) && Number.isFinite(Date.parse(value)) && Date.parse(value) <= Date.now();
+const fromEpoch = value => {
+  check(typeof value === 'string' && /^\d{10}$/.test(value));
+  const ms = Number(value) * 1000; check(Number.isSafeInteger(ms) && ms <= Date.now());
+  return new Date(ms).toISOString();
+};
+const phoneDigits = value => { check(typeof value === 'string' && /^\+[1-9]\d{6,14}$/.test(value)); return value.slice(1); };
+function bounded(signal, deadline) {
+  const ms = deadline === undefined ? 45000 : Date.parse(deadline) - Date.now();
+  check(Number.isFinite(ms) && ms > 0);
+  return AbortSignal.any([AbortSignal.timeout(Math.min(ms, 45000)), ...(signal ? [signal] : [])]);
+}
+async function run(signal, task) {
+  signal.throwIfAborted();
+  return new Promise((resolve, reject) => {
+    const abort = () => reject(new AccelerateError('request_failed'));
+    signal.addEventListener('abort', abort, { once: true });
+    Promise.resolve().then(task).then(resolve, reject).finally(() => signal.removeEventListener('abort', abort));
+    if (signal.aborted) abort();
+  });
+}
+const wait = signal => run(signal, () => new Promise(resolve => setTimeout(resolve, 250)));
+function validateJournal(journal) { check(['reserve', 'bind', 'recordStatus', 'get'].every(k => typeof journal?.[k] === 'function')); }
+
+/** The injected journal MUST be durable, atomic, and linearizable across all
+ * workers. No image, caption, reply or raw provider envelope may be stored. */
+export function createWhatsAppMessagingAdapter({ client, journal, sendingPhoneId, resolveDestination } = {}) {
+  check(typeof client?.uploadImage === 'function' && typeof client?.sendImage === 'function' && typeof client?.sendText === 'function' && digits.test(sendingPhoneId) && typeof resolveDestination === 'function');
+  validateJournal(journal);
+  async function deliver(input, message, review, options = {}) {
+    let bytes;
+    try {
+      const context = authenticatedCheckoutContext(input);
+      check(message && typeof message.text === 'string' && message.text.length > 0 && message.text.length <= (review ? 1024 : 4096) && keyPattern.test(message.idempotency_key));
+      if (review) check(Buffer.isBuffer(message.bytes) && message.bytes.length > 8 && message.bytes.length <= 2 * 1024 * 1024 && message.bytes.subarray(0, 8).equals(Buffer.from([137,80,78,71,13,10,26,10])) && message.contentType === 'image/png' && message.signal instanceof AbortSignal);
+      const signal = bounded(review ? message.signal : options.signal, review ? message.delivery_expires_at : undefined);
+      const destination = await run(signal, () => resolveDestination(context));
+      check(destination && destination.phone_number_id === sendingPhoneId && (destination.recipient_id === phoneDigits(context.phone_number) || digits.test(destination.recipient_id) && destination.verified_wa_id === destination.recipient_id));
+      const scope = { key: hash([context.customer_id, context.workspace_id, context.conversation_id, message.idempotency_key]),
+        sender: hash(sendingPhoneId), recipient: hash(destination.recipient_id) };
+      const reserved = await run(signal, () => journal.reserve(scope));
+      check(reserved && typeof reserved.created === 'boolean');
+      if (reserved.created) {
+        let accepted;
+        if (review) {
+          bytes = Buffer.from(message.bytes);
+          const uploaded = await run(signal, () => client.uploadImage({ bytes, contentType: 'image/png', signal }));
+          check(typeof uploaded?.media_id === 'string' && id.test(uploaded.media_id));
+          accepted = await run(signal, () => client.sendImage({ phone_number_id: sendingPhoneId, recipient_id: destination.recipient_id, media_id: uploaded.media_id, caption: message.text, signal }));
+        } else accepted = await run(signal, () => client.sendText({ phone_number_id: sendingPhoneId, recipient_id: destination.recipient_id, text: message.text, signal }));
+        check(typeof accepted?.message_id === 'string' && id.test(accepted.message_id));
+        await run(signal, () => journal.bind({ ...scope, message_id: safeId(accepted.message_id) }));
+      }
+      for (;;) {
+        const value = await run(signal, () => journal.get(scope));
+        check(value && value.sender === scope.sender && value.recipient === scope.recipient);
+        // A reservation without an ID has an ambiguous provider outcome. Never send again.
+        check(typeof value.message_id === 'string' && id.test(value.message_id));
+        if (value.status === 'failed') fail();
+        if (value.status === 'sent') {
+          check(validTime(value.sent_at) && (!review || Date.parse(value.sent_at) < Date.parse(message.delivery_expires_at)));
+          return Object.freeze({ message_id: value.message_id, sent_at: value.sent_at });
+        }
+        check(value.status === 'pending');
+        await wait(signal);
+      }
+    } catch { throw new AccelerateError('request_failed'); }
+    finally { bytes?.fill(0); }
+  }
+  async function findReviewReceipt(input, idempotencyKey, options = {}) {
+    try {
+      const context = authenticatedCheckoutContext(input);
+      check(typeof idempotencyKey === 'string' && /^accelerate-chat:[a-f0-9]{64}$/.test(idempotencyKey));
+      const signal = bounded(options.signal);
+      const destination = await run(signal, () => resolveDestination(context));
+      check(destination && destination.phone_number_id === sendingPhoneId && (destination.recipient_id === phoneDigits(context.phone_number) || digits.test(destination.recipient_id) && destination.verified_wa_id === destination.recipient_id));
+      const scope = { key: hash([context.customer_id, context.workspace_id, context.conversation_id, idempotencyKey]), sender: hash(sendingPhoneId), recipient: hash(destination.recipient_id) };
+      const value = await run(signal, () => journal.get(scope));
+      check(value && value.sender === scope.sender && value.recipient === scope.recipient && value.status === 'sent' && typeof value.message_id === 'string' && id.test(value.message_id) && validTime(value.sent_at));
+      return Object.freeze({ message_id: value.message_id, sent_at: value.sent_at });
+    } catch { throw new AccelerateError('request_failed'); }
+  }
+  return Object.freeze({ sendText: (context, message, options) => deliver(context, message, false, options), sendReview: (context, message) => deliver(context, message, true), findReviewReceipt });
+}
+
+/** A batch handler verifies the original bytes once and invokes onMessage in
+ * provider array order. Callback processing must run before history or AI and
+ * must deduplicate provider message IDs across whole-webhook retries. */
+export function createWhatsAppWebhookBatchHandler({ verifyWebhook, resolveIdentity, sendingPhoneId, journal, onMessage } = {}) {
+  check(typeof verifyWebhook === 'function' && typeof resolveIdentity === 'function' && digits.test(sendingPhoneId) && typeof onMessage === 'function'); validateJournal(journal);
+  return async (request, rawBody) => {
+    let body;
+    try {
+      check(rawBody instanceof Uint8Array && rawBody.byteLength <= 262144 && await verifyWebhook(request, rawBody) === true);
+      body = JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(rawBody));
+      check(body?.object === 'whatsapp_business_account' && Array.isArray(body.entry) && body.entry.length > 0);
+      let retry = false;
+      for (const entry of body.entry) {
+        if (!Array.isArray(entry?.changes)) { retry = true; continue; }
+        for (const change of entry.changes) {
+          if (change?.field !== 'messages') continue;
+          const value = change.value;
+          if (value?.messaging_product !== 'whatsapp' || value.metadata?.phone_number_id !== sendingPhoneId) { retry = true; continue; }
+          if ((value.statuses !== undefined && !Array.isArray(value.statuses)) || (value.messages !== undefined && !Array.isArray(value.messages))) { retry = true; continue; }
+          const statuses = value.statuses ?? [], messages = value.messages ?? [];
+          // Separate arrays have no shared provider ordering. Keep each array's order.
+          for (const status of statuses) {
+            try {
+              if (!['sent', 'failed'].includes(status?.status)) continue;
+              check(id.test(status.id) && digits.test(status.recipient_id));
+              const time = fromEpoch(status.timestamp);
+              await journal.recordStatus({ sender: hash(sendingPhoneId), recipient: hash(status.recipient_id), message_id: safeId(status.id), status: status.status, timestamp: time });
+            } catch { retry = true; }
+          }
+          for (const message of messages) {
+            let result;
+            try {
+              if (message?.type !== 'text') continue;
+              // Never treat explicitly shared/group traffic as direct.
+              if (value.group_id != null || value.is_group === true || message.group_id != null || message.groupId != null || message.group != null || message.is_group === true || message.isGroup === true || message.context?.group_id != null) continue;
+              check(message && id.test(message.id) && digits.test(message.from) && typeof message.text?.body === 'string' && message.text.body.length <= 2000);
+              const sent_at = fromEpoch(message.timestamp), phone_number = `+${message.from}`;
+              const resolved = await resolveIdentity({ phone_number, wa_id: message.from, phone_number_id: sendingPhoneId });
+              if (resolved === null) continue;
+              const mapped = resolved && Object.hasOwn(resolved, 'context') ? resolved : undefined;
+              const context = authenticatedCheckoutContext(mapped ? mapped.context : resolved);
+              check(context.phone_number === phone_number || mapped?.verified_wa_id === message.from);
+              result = { authenticated: true, direct: true, context, message_id: safeId(message.id), text: message.text.body, sent_at };
+              if (message.context?.id !== undefined) { check(id.test(message.context.id)); result.reply_to_message_id = safeId(message.context.id); }
+              const handled = await onMessage(result);
+              if (handled?.retry === true) retry = true;
+            } catch { retry = true; }
+            finally { if (result) result.text = ''; if (message?.text && typeof message.text === 'object') message.text.body = ''; }
+          }
+        }
+      }
+      check(!retry);
+      return Object.freeze({ handled: true });
+    } catch { throw new AccelerateError('permission_denied'); }
+    finally {
+      if (Array.isArray(body?.entry)) for (const entry of body.entry) if (Array.isArray(entry?.changes)) for (const change of entry.changes) if (Array.isArray(change?.value?.messages)) for (const message of change.value.messages) if (message?.text && typeof message.text === 'object') message.text.body = '';
+      if (rawBody instanceof Uint8Array) rawBody.fill(0);
+      body = undefined;
+    }
+  };
+}
+
+/** Compatibility authenticator accepts exactly one message or status event.
+ * Use the batch handler for provider endpoints that can deliver batches. */
+export function createWhatsAppWebhookAuthenticator(options = {}) {
+  return async (request, rawBody) => {
+    let message, count = 0;
+    // Batch compatibility cannot safely return multiple messages to a caller
+    // that only consumes one; reject before any journal or callback side effect.
+    let parsed;
+    try {
+      check(rawBody instanceof Uint8Array && rawBody.byteLength <= 262144 && await options.verifyWebhook(request, rawBody) === true);
+      parsed = JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(rawBody));
+      check(Array.isArray(parsed?.entry) && parsed.entry.length === 1 && Array.isArray(parsed.entry[0]?.changes) && parsed.entry[0].changes.length === 1);
+      const value = parsed.entry[0].changes[0]?.value;
+      check((value?.messages?.length ?? 0) + (value?.statuses?.length ?? 0) === 1);
+      const handler = createWhatsAppWebhookBatchHandler({ ...options, verifyWebhook: () => true, onMessage: event => { count++; message = { ...event }; } });
+      await handler(request, rawBody);
+      return count ? message : { kind: 'ignore' };
+    } catch { throw new AccelerateError('permission_denied'); }
+    finally {
+      if (Array.isArray(parsed?.entry)) for (const entry of parsed.entry) if (Array.isArray(entry?.changes)) for (const change of entry.changes) if (Array.isArray(change?.value?.messages)) for (const item of change.value.messages) if (item?.text && typeof item.text === 'object') item.text.body = '';
+      if (rawBody instanceof Uint8Array) rawBody.fill(0); parsed = undefined;
+    }
+  };
+}