@andreprado/agentkit 0.1.0-alpha.9 → 0.1.1

package/src/runtime/channels/whatsapp-evolution.ts

@@ -0,0 +1,1330 @@
+import type {
+  ChannelAdapter,
+  ChannelMediaDownloadInput,
+  ChannelMediaDownloadResult,
+  ChannelSendInput,
+  ChannelSendResult,
+  ChannelStatusInput,
+  ChannelStatusResult,
+  NormalizedChannelEvent,
+  RawWebhookEvent,
+  WebhookVerificationInput,
+  WebhookVerificationResult,
+} from "../channels";
+import { AgentKitError } from "../errors";
+import {
+  CHANNEL_DOWNLOAD_TIMEOUT_MS,
+  CHANNEL_SEND_TIMEOUT_MS,
+  CHANNEL_STATUS_TIMEOUT_MS,
+  classifySendRequestError,
+  isRetryableReadRequestError,
+} from "./provider-fetch";
+import { createPublicHttpsFetch, isBlockedOutboundHost } from "./net-guard";
+
+type EvolutionFetch = (url: string, init?: RequestInit) => Promise<Response>;
+
+const evolutionFetch: EvolutionFetch = createPublicHttpsFetch("EVOLUTION_API_BASE_URL");
+
+type EvolutionSendTextRequest = {
+  method: "POST";
+  url: string;
+  body: {
+    number: string;
+    text: string;
+  };
+  idempotencyKey: string;
+};
+
+type EvolutionMessage = {
+  id?: string;
+  remoteJid?: string;
+  sender?: string;
+  senderName?: string;
+  fromMe?: boolean;
+  messageType?: string;
+  timestamp?: number;
+  text?: string;
+  ptt?: boolean;
+  mimeType?: string;
+  durationSeconds?: number;
+  sizeBytes?: number;
+};
+
+const EVOLUTION_MAX_DOWNLOAD_BYTES = 25_000_000;
+const EVOLUTION_MEDIA_DOWNLOAD_BODY_OVERHEAD_BYTES = 64_000;
+const EVOLUTION_MESSAGE_EVENTS = new Set(["messages_upsert", "messages.upsert", "messages", "message"]);
+const EVOLUTION_UPDATE_EVENTS = new Set(["messages_update", "messages.update", "send_message", "send.message"]);
+const EVOLUTION_IGNORED_EVENTS = new Set([
+  "application_startup",
+  "qrcode_updated",
+  "connection_update",
+  "contacts_set",
+  "contacts_upsert",
+  "contacts_update",
+  "presence_update",
+  "chats_set",
+  "chats_upsert",
+  "chats_update",
+  "chats_delete",
+  "groups_upsert",
+  "groups_update",
+  "group_update",
+  "group_participants_update",
+  "call",
+  "new_jwt_token",
+  "new_token",
+  "typebot_start",
+  "typebot_change_status",
+]);
+
+export const evolutionWhatsappChannelAdapter: ChannelAdapter = {
+  type: "whatsapp",
+  provider: "evolution",
+  requiredSecrets: ["EVOLUTION_API_BASE_URL", "EVOLUTION_API_KEY", "EVOLUTION_INSTANCE_NAME", "EVOLUTION_WEBHOOK_TOKEN"],
+  verifyWebhook(input) {
+    const tokenResult = verifyWebhookToken(input);
+
+    if (!tokenResult.ok) {
+      return tokenResult;
+    }
+
+    let body: Record<string, unknown>;
+
+    try {
+      body = parseJsonObject(input);
+    } catch (error) {
+      return {
+        ok: false,
+        code: "channel_payload_invalid",
+        message: error instanceof Error ? error.message : String(error),
+      };
+    }
+
+    const instanceResult = verifyEvolutionInstance(input, body);
+
+    if (!instanceResult.ok) {
+      return instanceResult;
+    }
+
+    return { ok: true };
+  },
+  normalizeInbound(input) {
+    const body = parseJsonObject(input);
+    const eventType = readEventType(body);
+
+    if (EVOLUTION_IGNORED_EVENTS.has(eventType)) {
+      return [unsupportedEvolutionEvent(input, body, eventType, "unsupported_event_type")];
+    }
+
+    if (EVOLUTION_UPDATE_EVENTS.has(eventType)) {
+      return [normalizeEvolutionStatusEvent(input, body, eventType)];
+    }
+
+    if (!EVOLUTION_MESSAGE_EVENTS.has(eventType)) {
+      return [unsupportedEvolutionEvent(input, body, eventType, "unsupported_event_type")];
+    }
+
+    const message = normalizeEvolutionMessage(body);
+    const providerEventId = providerEventIdFor(body, message);
+
+    if (!providerEventId) {
+      throw new AgentKitError("channel_payload_invalid", "Evolution payload is missing a message key id or event id.");
+    }
+
+    const contactId = stripWhatsappJid(message.sender ?? message.remoteJid ?? "unknown");
+    const instanceId = readEvolutionInstanceName(body) ?? "default";
+    const messageType = (message.messageType ?? (message.text ? "conversation" : "unknown")).toLowerCase();
+    const base = baseEvolutionEvent(input, {
+      providerEventId,
+      instanceId,
+      contactId,
+      eventType,
+      messageType,
+      senderName: message.senderName,
+    });
+
+    if (message.fromMe) {
+      return [
+        {
+          ...base,
+          kind: "unsupported",
+          unsupportedReason: "ignored_message:from_me",
+        },
+      ];
+    }
+
+    if (isEvolutionAudioMessage(messageType, message)) {
+      return [
+        {
+          ...base,
+          kind: "message",
+          message: {
+            role: "user",
+            contentType: "audio",
+            content: "",
+            providerMessageId: message.id,
+            audio: {
+              providerMediaId: message.id ?? providerEventId,
+              kind: messageType.includes("ptt") || message.ptt ? "voice" : "audio",
+              ...(message.mimeType ? { mimeType: message.mimeType } : {}),
+              filename: defaultEvolutionAudioFilename(message),
+              ...(message.durationSeconds !== undefined ? { durationSeconds: message.durationSeconds } : {}),
+              ...(message.sizeBytes !== undefined ? { sizeBytes: message.sizeBytes } : {}),
+            },
+          },
+        },
+      ];
+    }
+
+    if (!isEvolutionTextMessage(messageType)) {
+      return [
+        {
+          ...base,
+          kind: "unsupported",
+          unsupportedReason: `unsupported_message_type:${messageType}`,
+        },
+      ];
+    }
+
+    const text = message.text?.trim();
+
+    if (!text) {
+      return [
+        {
+          ...base,
+          kind: "unsupported",
+          unsupportedReason: "unsupported_message_type:empty_text",
+        },
+      ];
+    }
+
+    return [
+      {
+        ...base,
+        kind: "message",
+        message: {
+          role: "user",
+          contentType: "text",
+          content: text,
+          providerMessageId: message.id,
+        },
+      },
+    ];
+  },
+  async downloadMedia(input) {
+    return downloadEvolutionMedia(input);
+  },
+  async sendMessage(input) {
+    return sendEvolutionMessage(input);
+  },
+  async getStatus(input) {
+    return getEvolutionStatus(input);
+  },
+};
+
+export function buildEvolutionSendTextRequest(input: ChannelSendInput): EvolutionSendTextRequest {
+  return buildEvolutionSendTextRequestInternal(input, "<redacted>", "<redacted>", "<redacted>");
+}
+
+export async function sendEvolutionMessage(
+  input: ChannelSendInput,
+  fetcher: EvolutionFetch = evolutionFetch,
+): Promise<ChannelSendResult> {
+  if (input.secrets.AGENTKIT_CHANNEL_SEND_DRY_RUN === "1") {
+    const request = buildEvolutionSendTextRequest(input);
+
+    return {
+      ok: true,
+      status: "stubbed",
+      providerRequestId: request.idempotencyKey,
+      providerMetadata: {
+        method: request.method,
+        url: request.url,
+        body: request.body,
+      },
+    };
+  }
+
+  const baseUrl = input.secrets.EVOLUTION_API_BASE_URL;
+  const apiKey = input.secrets.EVOLUTION_API_KEY;
+  const instanceName = input.secrets.EVOLUTION_INSTANCE_NAME;
+
+  if (!baseUrl || !apiKey || !instanceName) {
+    return {
+      ok: false,
+      retryable: false,
+      code: "channel_secret_missing",
+      message: "Secret EVOLUTION_API_BASE_URL, EVOLUTION_API_KEY, or EVOLUTION_INSTANCE_NAME is missing.",
+    };
+  }
+
+  let request: EvolutionSendTextRequest;
+  let actualRequest: EvolutionSendTextRequest;
+
+  try {
+    request = buildEvolutionSendTextRequest(input);
+    actualRequest = buildEvolutionSendTextRequestInternal(input, baseUrl, instanceName, "actual");
+  } catch (error) {
+    return {
+      ok: false,
+      retryable: false,
+      code: "channel_send_failed",
+      message: error instanceof Error ? error.message : String(error),
+    };
+  }
+
+  let response: Response;
+
+  try {
+    response = await fetcher(actualRequest.url, {
+      signal: AbortSignal.timeout(CHANNEL_SEND_TIMEOUT_MS),
+      method: actualRequest.method,
+      headers: {
+        apikey: apiKey,
+        "Content-Type": "application/json",
+        Accept: "application/json",
+      },
+      body: JSON.stringify(actualRequest.body),
+    });
+  } catch (error) {
+    const failure = classifySendRequestError(error);
+    return {
+      ok: false,
+      retryable: failure.retryable,
+      code: failure.code,
+      message: `Evolution sendText request ${failure.reason}: ${redactString(
+        error instanceof Error ? error.message : String(error),
+        [apiKey, baseUrl, instanceName],
+      )}`,
+      providerRequestId: request.idempotencyKey,
+      providerMetadata: {
+        method: request.method,
+        url: request.url,
+        body: request.body,
+      },
+    };
+  }
+
+  const payload = await readEvolutionResponseBody(response).catch(() => null);
+  const redactedPayload = redactValue(payload, [apiKey, baseUrl, instanceName]);
+  const messageId = readEvolutionProviderMessageId(payload);
+
+  if (!response.ok) {
+    return {
+      ok: false,
+      retryable: response.status === 429 || response.status >= 500,
+      code: "channel_send_failed",
+      message: redactString(readEvolutionErrorMessage(payload, response.status), [apiKey, baseUrl, instanceName]),
+      providerRequestId: request.idempotencyKey,
+      providerMetadata: {
+        method: request.method,
+        url: request.url,
+        status: response.status,
+        body: redactedPayload,
+      },
+    };
+  }
+
+  if (!messageId) {
+    return {
+      ok: false,
+      retryable: false,
+      code: "channel_send_failed",
+      message: "Evolution sendText did not return a provider message id.",
+      providerRequestId: request.idempotencyKey,
+      providerMetadata: {
+        method: request.method,
+        url: request.url,
+        status: response.status,
+        body: redactedPayload,
+      },
+    };
+  }
+
+  return {
+    ok: true,
+    status: "sent",
+    providerRequestId: request.idempotencyKey,
+    providerMessageId: messageId,
+    providerMetadata: {
+      method: request.method,
+      url: request.url,
+      status: response.status,
+      body: redactedPayload,
+    },
+  };
+}
+
+export async function downloadEvolutionMedia(
+  input: ChannelMediaDownloadInput,
+  fetcher: EvolutionFetch = evolutionFetch,
+): Promise<ChannelMediaDownloadResult> {
+  const baseUrl = input.secrets.EVOLUTION_API_BASE_URL;
+  const apiKey = input.secrets.EVOLUTION_API_KEY;
+  const instanceName = input.secrets.EVOLUTION_INSTANCE_NAME;
+
+  if (!baseUrl || !apiKey || !instanceName) {
+    return {
+      ok: false,
+      retryable: false,
+      code: "channel_secret_missing",
+      message: "Secret EVOLUTION_API_BASE_URL, EVOLUTION_API_KEY, or EVOLUTION_INSTANCE_NAME is missing.",
+    };
+  }
+
+  const providerMessageId = input.message.providerMessageId ?? input.message.audio?.providerMediaId;
+
+  if (!providerMessageId) {
+    return {
+      ok: false,
+      retryable: false,
+      code: "channel_audio_download_unavailable",
+      message: "Evolution audio payload did not include a provider message id.",
+    };
+  }
+
+  let url: string;
+
+  try {
+    url = evolutionApiUrl(baseUrl, `/chat/getBase64FromMediaMessage/${encodeURIComponent(instanceName)}`);
+  } catch (error) {
+    return {
+      ok: false,
+      retryable: false,
+      code: "channel_audio_download_unavailable",
+      message: error instanceof Error ? error.message : String(error),
+    };
+  }
+
+  let response: Response;
+
+  try {
+    response = await fetcher(url, {
+      signal: AbortSignal.timeout(CHANNEL_DOWNLOAD_TIMEOUT_MS),
+      method: "POST",
+      headers: {
+        apikey: apiKey,
+        "Content-Type": "application/json",
+        Accept: "application/json",
+      },
+      body: JSON.stringify({
+        message: {
+          key: {
+            id: providerMessageId,
+          },
+        },
+        convertToMp4: false,
+      }),
+    });
+  } catch (error) {
+    return {
+      ok: false,
+      retryable: isRetryableReadRequestError(error),
+      code: "channel_provider_unavailable",
+      message: `Evolution media download failed before a response: ${redactString(
+        error instanceof Error ? error.message : String(error),
+        [apiKey, baseUrl, instanceName],
+      )}`,
+    };
+  }
+
+  const maxBytes = input.maxBytes ?? EVOLUTION_MAX_DOWNLOAD_BYTES;
+  let payload: unknown;
+
+  try {
+    payload = await readEvolutionResponseBody(response, {
+      maxBytes: maxEvolutionMediaResponseBytes(maxBytes),
+    });
+  } catch (error) {
+    if (error instanceof EvolutionResponseBodyTooLargeError) {
+      return {
+        ok: false,
+        retryable: false,
+        code: "channel_audio_too_large",
+        message: `Evolution media download response exceeds the configured ${maxBytes} byte audio limit before decode.`,
+        providerMetadata: {
+          status: response.status,
+        },
+      };
+    }
+
+    return {
+      ok: false,
+      retryable: true,
+      code: "channel_provider_unavailable",
+      message: `Evolution media download response could not be read: ${error instanceof Error ? error.message : String(error)}`,
+      providerMetadata: {
+        status: response.status,
+      },
+    };
+  }
+
+  if (!response.ok) {
+    return {
+      ok: false,
+      retryable: response.status === 429 || response.status >= 500,
+      code: response.status === 429 || response.status >= 500
+        ? "channel_provider_unavailable"
+        : "channel_media_download_failed",
+      message: `Evolution media download returned HTTP ${response.status}.`,
+      providerMetadata: {
+        status: response.status,
+        body: redactValue(payload, [apiKey, baseUrl, instanceName]),
+      },
+    };
+  }
+
+  const base64Data = readEvolutionBase64Data(payload);
+
+  if (!base64Data) {
+    return {
+      ok: false,
+      retryable: false,
+      code: "channel_audio_download_unavailable",
+      message: "Evolution media download did not return base64 data.",
+      providerMetadata: {
+        status: response.status,
+        body: redactValue(payload, [apiKey, baseUrl, instanceName]),
+      },
+    };
+  }
+
+  const normalizedBase64 = normalizeBase64(base64Data);
+  const estimatedBytes = estimateBase64DecodedBytes(normalizedBase64);
+
+  if (estimatedBytes === undefined) {
+    return {
+      ok: false,
+      retryable: false,
+      code: "channel_media_download_failed",
+      message: "Evolution media download returned invalid base64 data.",
+      providerMetadata: {
+        status: response.status,
+      },
+    };
+  }
+
+  if (estimatedBytes > maxBytes) {
+    return {
+      ok: false,
+      retryable: false,
+      code: "channel_audio_too_large",
+      message: `Audio response contains approximately ${estimatedBytes} bytes, which exceeds the configured ${maxBytes} byte limit.`,
+      providerMetadata: {
+        status: response.status,
+        sizeBytes: estimatedBytes,
+      },
+    };
+  }
+
+  let audio: Uint8Array;
+
+  try {
+    audio = decodeBase64(normalizedBase64);
+  } catch {
+    return {
+      ok: false,
+      retryable: false,
+      code: "channel_media_download_failed",
+      message: "Evolution media download returned invalid base64 data.",
+      providerMetadata: {
+        status: response.status,
+      },
+    };
+  }
+
+  if (audio.byteLength > maxBytes) {
+    return {
+      ok: false,
+      retryable: false,
+      code: "channel_audio_too_large",
+      message: `Audio response contains ${audio.byteLength} bytes, which exceeds the configured ${maxBytes} byte limit.`,
+      providerMetadata: {
+        status: response.status,
+        sizeBytes: audio.byteLength,
+      },
+    };
+  }
+
+  return {
+    ok: true,
+    audio,
+    filename: input.message.audio?.filename ?? `${providerMessageId}.ogg`,
+    ...(readEvolutionMimeType(payload) ? { mimeType: readEvolutionMimeType(payload) } : input.message.audio?.mimeType ? { mimeType: input.message.audio.mimeType } : {}),
+    ...(input.message.audio?.durationSeconds !== undefined ? { durationSeconds: input.message.audio.durationSeconds } : {}),
+    sizeBytes: audio.byteLength,
+    providerMetadata: {
+      status: response.status,
+    },
+  };
+}
+
+export async function getEvolutionStatus(
+  input: ChannelStatusInput,
+  fetcher: EvolutionFetch = evolutionFetch,
+): Promise<ChannelStatusResult> {
+  const missingSecrets = ["EVOLUTION_API_BASE_URL", "EVOLUTION_API_KEY", "EVOLUTION_INSTANCE_NAME"].filter(
+    (secret) => !input.secrets[secret],
+  );
+
+  if (missingSecrets.length > 0) {
+    return {
+      status: "needs_setup",
+      checkedAt: new Date().toISOString(),
+      message: `Evolution channel secrets are missing: ${missingSecrets.join(", ")}.`,
+    };
+  }
+
+  let url: string;
+
+  try {
+    url = evolutionApiUrl(
+      input.secrets.EVOLUTION_API_BASE_URL,
+      `/instance/connectionState/${encodeURIComponent(input.secrets.EVOLUTION_INSTANCE_NAME)}`,
+    );
+  } catch (error) {
+    return {
+      status: "failed",
+      checkedAt: new Date().toISOString(),
+      message: error instanceof Error ? error.message : String(error),
+    };
+  }
+
+  let response: Response;
+
+  try {
+    response = await fetcher(url, {
+      signal: AbortSignal.timeout(CHANNEL_STATUS_TIMEOUT_MS),
+      method: "GET",
+      headers: {
+        apikey: input.secrets.EVOLUTION_API_KEY,
+        Accept: "application/json",
+      },
+    });
+  } catch (error) {
+    return {
+      status: "failed",
+      checkedAt: new Date().toISOString(),
+      message: `Evolution connection state failed before a response: ${redactString(
+        error instanceof Error ? error.message : String(error),
+        [input.secrets.EVOLUTION_API_KEY, input.secrets.EVOLUTION_API_BASE_URL, input.secrets.EVOLUTION_INSTANCE_NAME],
+      )}`,
+    };
+  }
+
+  const payload = await readEvolutionResponseBody(response).catch(() => null);
+
+  if (!response.ok) {
+    return {
+      status: "failed",
+      checkedAt: new Date().toISOString(),
+      message: redactString(
+        readEvolutionErrorMessage(payload, response.status),
+        [input.secrets.EVOLUTION_API_KEY, input.secrets.EVOLUTION_API_BASE_URL, input.secrets.EVOLUTION_INSTANCE_NAME],
+      ),
+      providerMetadata: {
+        status: response.status,
+        body: redactValue(payload, [
+          input.secrets.EVOLUTION_API_KEY,
+          input.secrets.EVOLUTION_API_BASE_URL,
+          input.secrets.EVOLUTION_INSTANCE_NAME,
+        ]),
+      },
+    };
+  }
+
+  const instance = isRecord(payload) ? readRecord(payload, "instance") : {};
+  const state = readString(instance, "state") ?? readString(payload, "state") ?? "unknown";
+
+  if (state === "open") {
+    return {
+      status: "connected",
+      checkedAt: new Date().toISOString(),
+      message: "Evolution instance is connected.",
+      providerMetadata: {
+        instanceState: state,
+      },
+    };
+  }
+
+  return {
+    status: "needs_setup",
+    checkedAt: new Date().toISOString(),
+    message: `Evolution instance is ${state}. Connect it with QR code or pairing code in Evolution API.`,
+    providerMetadata: {
+      instanceState: state,
+    },
+  };
+}
+
+export function buildEvolutionWebhookSetupPayload(webhookUrl: string): Record<string, unknown> {
+  return {
+    enabled: true,
+    url: webhookUrl,
+    webhookByEvents: false,
+    webhookBase64: false,
+    events: ["MESSAGES_UPSERT", "MESSAGES_UPDATE", "CONNECTION_UPDATE"],
+  };
+}
+
+export function evolutionApiUrl(baseUrl: string, path: string): string {
+  const base = validateEvolutionBaseUrl(baseUrl);
+  const normalizedPath = path.startsWith("/") ? path : `/${path}`;
+  return new URL(normalizedPath, `${base}/`).href;
+}
+
+function verifyWebhookToken(input: WebhookVerificationInput): WebhookVerificationResult {
+  const expectedToken = input.secrets.EVOLUTION_WEBHOOK_TOKEN;
+
+  if (!expectedToken) {
+    return {
+      ok: false,
+      code: "channel_secret_missing",
+      message: "Secret EVOLUTION_WEBHOOK_TOKEN is not set for this channel.",
+    };
+  }
+
+  let actualToken: string | null = null;
+
+  try {
+    actualToken = new URL(input.url).searchParams.get("token");
+  } catch {
+    actualToken = null;
+  }
+
+  if (actualToken !== expectedToken) {
+    return {
+      ok: false,
+      code: "channel_signature_invalid",
+      message: "Evolution webhook token did not match.",
+    };
+  }
+
+  return { ok: true };
+}
+
+function verifyEvolutionInstance(
+  input: WebhookVerificationInput,
+  body: Record<string, unknown>,
+): WebhookVerificationResult {
+  const expectedInstance = input.secrets.EVOLUTION_INSTANCE_NAME;
+
+  if (!expectedInstance) {
+    return {
+      ok: false,
+      code: "channel_secret_missing",
+      message: "Secret EVOLUTION_INSTANCE_NAME is not set for this channel.",
+    };
+  }
+
+  const actualInstance = readEvolutionInstanceName(body);
+
+  if (!actualInstance) {
+    return {
+      ok: false,
+      code: "channel_payload_invalid",
+      message: "Evolution webhook payload is missing an instance name.",
+    };
+  }
+
+  if (actualInstance !== expectedInstance) {
+    return {
+      ok: false,
+      code: "channel_signature_invalid",
+      message: "Evolution webhook instance did not match.",
+    };
+  }
+
+  return { ok: true };
+}
+
+function normalizeEvolutionStatusEvent(
+  input: RawWebhookEvent,
+  body: Record<string, unknown>,
+  eventType: string,
+): NormalizedChannelEvent {
+  const message = normalizeEvolutionMessage(body);
+  const providerEventId = providerEventIdFor(body, message) ?? `status:${Date.now()}`;
+  const data = readRecord(body, "data");
+  const status =
+    readString(data, "status") ??
+    readString(data, "messageStatus") ??
+    readString(body, "status") ??
+    message.messageType ??
+    "sent";
+  const normalizedStatus = status.toLowerCase();
+  const deliveryStatus = normalizedStatus.includes("read")
+    ? "delivered"
+    : normalizedStatus.includes("deliver")
+      ? "delivered"
+      : normalizedStatus.includes("fail")
+        ? "failed"
+        : "sent";
+
+  return {
+    ...baseEvolutionEvent(input, {
+      providerEventId,
+      instanceId: readEvolutionInstanceName(body) ?? "default",
+      contactId: stripWhatsappJid(message.sender ?? message.remoteJid ?? "unknown"),
+      eventType,
+      messageType: normalizedStatus,
+      senderName: message.senderName,
+    }),
+    kind: "delivery_status",
+    deliveryStatus,
+  };
+}
+
+function unsupportedEvolutionEvent(
+  input: RawWebhookEvent,
+  body: Record<string, unknown>,
+  eventType: string,
+  reason: string,
+): NormalizedChannelEvent {
+  const message = normalizeEvolutionMessage(body);
+  const providerEventId = providerEventIdFor(body, message) ?? `${eventType}:${Date.now()}`;
+
+  return {
+    ...baseEvolutionEvent(input, {
+      providerEventId,
+      instanceId: readEvolutionInstanceName(body) ?? "default",
+      contactId: stripWhatsappJid(message.sender ?? message.remoteJid ?? "unknown"),
+      eventType,
+      messageType: message.messageType ?? "unknown",
+      senderName: message.senderName,
+    }),
+    kind: "unsupported",
+    unsupportedReason: `${reason}:${eventType}`,
+  };
+}
+
+function baseEvolutionEvent(
+  input: RawWebhookEvent,
+  values: {
+    providerEventId: string;
+    instanceId: string;
+    contactId: string;
+    eventType: string;
+    messageType: string;
+    senderName?: string;
+  },
+): Omit<NormalizedChannelEvent, "kind"> {
+  return {
+    type: "whatsapp",
+    provider: "evolution",
+    providerEventId: values.providerEventId,
+    dedupeKey: `whatsapp:evolution:${input.channelId}:${values.providerEventId}`,
+    externalIdentity: {
+      key: `whatsapp:evolution:contact:${values.contactId}`,
+      display: values.senderName ?? values.contactId,
+      redactedDisplay: values.senderName
+        ? `${values.senderName} (${redactPhone(values.contactId)})`
+        : `whatsapp:evolution:contact:${redactPhone(values.contactId)}`,
+    },
+    receivedAt: input.receivedAt,
+    providerMetadata: {
+      eventType: values.eventType,
+      messageType: values.messageType,
+    },
+  };
+}
+
+function normalizeEvolutionMessage(body: Record<string, unknown>): EvolutionMessage {
+  const data = readRecord(body, "data");
+  const payload = Object.keys(data).length > 0 ? data : body;
+  const key = readRecord(payload, "key");
+  const message = readRecord(payload, "message");
+  const extendedText = readRecord(message, "extendedTextMessage");
+  const image = readRecord(message, "imageMessage");
+  const video = readRecord(message, "videoMessage");
+  const audio = readRecord(message, "audioMessage");
+  const document = readRecord(message, "documentMessage");
+  const messageType =
+    readString(payload, "messageType") ??
+    readString(payload, "type") ??
+    firstPresentMessageType(message);
+
+  return {
+    id: readString(key, "id") ?? readString(payload, "id") ?? readString(body, "id"),
+    remoteJid: readString(key, "remoteJid") ?? readString(payload, "remoteJid") ?? readString(payload, "chatId"),
+    sender:
+      readString(key, "participant") ??
+      readString(payload, "sender") ??
+      readString(payload, "remoteJid") ??
+      readString(key, "remoteJid"),
+    senderName: readString(payload, "pushName") ?? readString(payload, "senderName") ?? readString(payload, "name"),
+    fromMe: readBoolean(key, "fromMe") ?? readBoolean(payload, "fromMe"),
+    messageType,
+    timestamp: readNumber(payload, "messageTimestamp") ?? readNumber(payload, "timestamp") ?? readNumber(body, "date_time"),
+    text:
+      readString(message, "conversation") ??
+      readString(extendedText, "text") ??
+      readString(payload, "text") ??
+      readString(payload, "body"),
+    ptt: readBoolean(audio, "ptt"),
+    mimeType:
+      readString(audio, "mimetype") ??
+      readString(image, "mimetype") ??
+      readString(video, "mimetype") ??
+      readString(document, "mimetype") ??
+      readString(payload, "mimetype"),
+    durationSeconds: readNumber(audio, "seconds") ?? readNumber(audio, "duration"),
+    sizeBytes:
+      readNumber(audio, "fileLength") ??
+      readNumber(image, "fileLength") ??
+      readNumber(video, "fileLength") ??
+      readNumber(document, "fileLength"),
+  };
+}
+
+function providerEventIdFor(body: Record<string, unknown>, message: EvolutionMessage): string | undefined {
+  return (
+    message.id ??
+    readString(body, "event_id") ??
+    readString(body, "eventId") ??
+    readString(body, "id") ??
+    fallbackEventId(message)
+  );
+}
+
+function fallbackEventId(message: EvolutionMessage): string | undefined {
+  if (!message.remoteJid || message.timestamp === undefined) {
+    return undefined;
+  }
+
+  return `fallback:${stripWhatsappJid(message.remoteJid)}:${message.timestamp}`;
+}
+
+function readEventType(body: Record<string, unknown>): string {
+  const value =
+    readString(body, "EventType") ??
+    readString(body, "eventType") ??
+    readString(body, "event") ??
+    readString(body, "type") ??
+    "messages_upsert";
+  return value.toLowerCase().replace(/\./g, "_");
+}
+
+function readEvolutionInstanceName(body: Record<string, unknown>): string | undefined {
+  const data = readRecord(body, "data");
+
+  return (
+    readString(body, "instance") ??
+    readString(body, "instanceName") ??
+    readString(body, "instance_name") ??
+    readString(data, "instance") ??
+    readString(data, "instanceName") ??
+    readString(data, "instance_name")
+  );
+}
+
+function firstPresentMessageType(message: Record<string, unknown>): string | undefined {
+  for (const key of [
+    "conversation",
+    "extendedTextMessage",
+    "audioMessage",
+    "imageMessage",
+    "videoMessage",
+    "documentMessage",
+    "stickerMessage",
+  ]) {
+    if (message[key] !== undefined) {
+      return key;
+    }
+  }
+
+  return undefined;
+}
+
+function isEvolutionTextMessage(messageType: string): boolean {
+  return messageType === "conversation" || messageType === "extendedtextmessage" || messageType === "text";
+}
+
+function isEvolutionAudioMessage(messageType: string, message: EvolutionMessage): boolean {
+  return messageType === "audiomessage" || messageType === "audio" || Boolean(message.mimeType?.toLowerCase().startsWith("audio/"));
+}
+
+function defaultEvolutionAudioFilename(message: EvolutionMessage): string {
+  const id = message.id ?? "evolution-audio";
+  const extension = message.mimeType?.includes("mpeg") ? "mp3" : "ogg";
+  return `${id}.${extension}`;
+}
+
+function buildEvolutionSendTextRequestInternal(
+  input: ChannelSendInput,
+  baseUrl: string,
+  instanceName: string,
+  mode: "actual" | "<redacted>",
+): EvolutionSendTextRequest {
+  if (input.message.contentType !== "text") {
+    throw new Error("Evolution sendText supports only text channel messages.");
+  }
+
+  const to = contactFromExternalIdentity(input.externalIdentity.key);
+  const redactedTo = redactPhone(to);
+
+  return {
+    method: "POST",
+    url: mode === "actual"
+      ? evolutionApiUrl(baseUrl, `/message/sendText/${encodeURIComponent(instanceName)}`)
+      : "https://<redacted>/message/sendText/<redacted>",
+    body: {
+      number: mode === "actual" ? to : redactedTo,
+      text: input.message.content,
+    },
+    idempotencyKey: `whatsapp:evolution:${input.channelId}:${input.conversationId}:${redactedTo}`,
+  };
+}
+
+function contactFromExternalIdentity(identityKey: string): string {
+  const prefix = "whatsapp:evolution:contact:";
+
+  if (!identityKey.startsWith(prefix)) {
+    throw new Error("Evolution WhatsApp external identity must start with whatsapp:evolution:contact:.");
+  }
+
+  const contact = identityKey.slice(prefix.length);
+
+  if (!contact) {
+    throw new Error("Evolution WhatsApp external identity is missing a contact id.");
+  }
+
+  return contact;
+}
+
+function readEvolutionProviderMessageId(payload: unknown): string | undefined {
+  if (!isRecord(payload)) {
+    return undefined;
+  }
+
+  const key = readRecord(payload, "key");
+  const response = readRecord(payload, "response");
+  const responseKey = readRecord(response, "key");
+
+  return (
+    readString(key, "id") ??
+    readString(payload, "messageId") ??
+    readString(payload, "messageid") ??
+    readString(payload, "id") ??
+    readString(responseKey, "id") ??
+    readString(response, "messageId") ??
+    readString(response, "id")
+  );
+}
+
+class EvolutionResponseBodyTooLargeError extends Error {
+  constructor() {
+    super("Evolution response body exceeded the configured limit.");
+  }
+}
+
+async function readEvolutionResponseBody(response: Response, options: { maxBytes?: number } = {}): Promise<unknown> {
+  const text = await readEvolutionResponseText(response, options.maxBytes);
+
+  if (!text) {
+    return null;
+  }
+
+  try {
+    return JSON.parse(text);
+  } catch {
+    return text;
+  }
+}
+
+async function readEvolutionResponseText(response: Response, maxBytes?: number): Promise<string> {
+  if (maxBytes !== undefined) {
+    const contentLength = readContentLength(response.headers);
+
+    if (contentLength !== undefined && contentLength > maxBytes) {
+      throw new EvolutionResponseBodyTooLargeError();
+    }
+  }
+
+  if (maxBytes !== undefined && response.body) {
+    const reader = response.body.getReader();
+    const decoder = new TextDecoder();
+    let text = "";
+    let bytesRead = 0;
+
+    try {
+      while (true) {
+        const chunk = await reader.read();
+
+        if (chunk.done) {
+          break;
+        }
+
+        bytesRead += chunk.value.byteLength;
+
+        if (bytesRead > maxBytes) {
+          throw new EvolutionResponseBodyTooLargeError();
+        }
+
+        text += decoder.decode(chunk.value, { stream: true });
+      }
+
+      text += decoder.decode();
+      return text;
+    } finally {
+      reader.releaseLock();
+    }
+  }
+
+  const text = await response.text();
+
+  if (maxBytes !== undefined && utf8ByteLength(text) > maxBytes) {
+    throw new EvolutionResponseBodyTooLargeError();
+  }
+
+  return text;
+}
+
+function readContentLength(headers: Headers): number | undefined {
+  const value = headers.get("content-length");
+
+  if (!value) {
+    return undefined;
+  }
+
+  const parsed = Number(value);
+  return Number.isFinite(parsed) && parsed >= 0 ? parsed : undefined;
+}
+
+function maxEvolutionMediaResponseBytes(maxAudioBytes: number): number {
+  return Math.ceil(maxAudioBytes / 3) * 4 + EVOLUTION_MEDIA_DOWNLOAD_BODY_OVERHEAD_BYTES;
+}
+
+function readEvolutionBase64Data(payload: unknown): string | undefined {
+  if (typeof payload === "string") {
+    return payload;
+  }
+
+  if (!isRecord(payload)) {
+    return undefined;
+  }
+
+  const media = readRecord(payload, "media");
+
+  return (
+    readString(payload, "base64") ??
+    readString(payload, "base64Data") ??
+    readString(payload, "data") ??
+    readString(media, "base64") ??
+    readString(media, "base64Data")
+  );
+}
+
+function readEvolutionMimeType(payload: unknown): string | undefined {
+  if (!isRecord(payload)) {
+    return undefined;
+  }
+
+  const media = readRecord(payload, "media");
+
+  return (
+    readString(payload, "mimetype") ??
+    readString(payload, "mimeType") ??
+    readString(media, "mimetype") ??
+    readString(media, "mimeType")
+  );
+}
+
+function readEvolutionErrorMessage(payload: unknown, status: number): string {
+  if (isRecord(payload)) {
+    return (
+      readString(payload, "message") ??
+      readString(payload, "error") ??
+      readString(payload, "provider_message") ??
+      `Evolution request returned HTTP ${status}.`
+    );
+  }
+
+  return typeof payload === "string" && payload ? payload : `Evolution request returned HTTP ${status}.`;
+}
+
+function parseJsonObject(input: RawWebhookEvent): Record<string, unknown> {
+  let parsed: unknown;
+
+  try {
+    parsed = JSON.parse(input.rawBody);
+  } catch {
+    throw new AgentKitError("channel_payload_invalid", "Evolution webhook payload must be valid JSON.");
+  }
+
+  if (!isRecord(parsed)) {
+    throw new AgentKitError("channel_payload_invalid", "Evolution webhook payload must be a JSON object.");
+  }
+
+  return parsed;
+}
+
+function validateEvolutionBaseUrl(baseUrl: string): string {
+  let parsed: URL;
+
+  try {
+    parsed = new URL(baseUrl);
+  } catch {
+    throw new Error("EVOLUTION_API_BASE_URL must be a valid HTTPS URL.");
+  }
+
+  if (parsed.protocol !== "https:") {
+    throw new Error("EVOLUTION_API_BASE_URL must use HTTPS.");
+  }
+
+  if (parsed.username || parsed.password) {
+    throw new Error("EVOLUTION_API_BASE_URL must not include embedded credentials.");
+  }
+
+  if (parsed.pathname !== "/" || parsed.search || parsed.hash) {
+    throw new Error("EVOLUTION_API_BASE_URL must be an origin URL without a path, query, or hash.");
+  }
+
+  const host = parsed.hostname.toLowerCase();
+
+  if (isBlockedOutboundHost(host)) {
+    throw new Error("EVOLUTION_API_BASE_URL must be a public HTTPS origin.");
+  }
+
+  return parsed.origin;
+}
+
+
+
+
+function readRecord(record: Record<string, unknown>, key: string): Record<string, unknown> {
+  const value = record[key];
+  return isRecord(value) ? value : {};
+}
+
+function readString(record: unknown, key: string): string | undefined {
+  if (!isRecord(record)) {
+    return undefined;
+  }
+
+  const value = record[key];
+  return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+
+function readBoolean(record: unknown, key: string): boolean | undefined {
+  if (!isRecord(record)) {
+    return undefined;
+  }
+
+  const value = record[key];
+  return typeof value === "boolean" ? value : undefined;
+}
+
+function readNumber(record: unknown, key: string): number | undefined {
+  if (!isRecord(record)) {
+    return undefined;
+  }
+
+  const value = record[key];
+
+  if (typeof value === "number" && Number.isFinite(value)) {
+    return value;
+  }
+
+  if (typeof value === "string" && value.trim() && Number.isFinite(Number(value))) {
+    return Number(value);
+  }
+
+  return undefined;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function normalizeBase64(value: string): string {
+  const commaIndex = value.indexOf(",");
+  const raw = commaIndex >= 0 ? value.slice(commaIndex + 1) : value;
+  return raw.replace(/\s+/g, "");
+}
+
+function estimateBase64DecodedBytes(value: string): number | undefined {
+  if (!/^[A-Za-z0-9+/]*={0,2}$/.test(value) || value.length % 4 === 1) {
+    return undefined;
+  }
+
+  const padding = value.endsWith("==") ? 2 : value.endsWith("=") ? 1 : 0;
+  return Math.floor((value.length * 3) / 4) - padding;
+}
+
+function decodeBase64(value: string): Uint8Array {
+  if (typeof Buffer !== "undefined") {
+    return new Uint8Array(Buffer.from(value, "base64"));
+  }
+
+  const binary = atob(value);
+  const bytes = new Uint8Array(binary.length);
+
+  for (let index = 0; index < binary.length; index += 1) {
+    bytes[index] = binary.charCodeAt(index);
+  }
+
+  return bytes;
+}
+
+function utf8ByteLength(value: string): number {
+  return new TextEncoder().encode(value).byteLength;
+}
+
+function stripWhatsappJid(value: string): string {
+  return value
+    .replace(/^whatsapp:/, "")
+    .replace(/@s\.whatsapp\.net$/i, "")
+    .replace(/@c\.us$/i, "")
+    .replace(/@g\.us$/i, "")
+    .replace(/[^0-9+]/g, "");
+}
+
+function redactPhone(value: string): string {
+  const digits = value.replace(/\D/g, "");
+
+  if (digits.length <= 8) {
+    return digits ? `${digits.slice(0, 2)}******` : "unknown";
+  }
+
+  return `${digits.slice(0, 4)}******${digits.slice(-4)}`;
+}
+
+function redactString(value: string, secrets: Array<string | undefined>): string {
+  let redacted = value;
+
+  for (const secret of secrets) {
+    if (secret) {
+      redacted = redacted.split(secret).join("<redacted>");
+    }
+  }
+
+  return redacted.replace(/\b\+?\d[\d\s().-]{8,}\d\b/g, (match) => redactPhone(match));
+}
+
+function redactValue(value: unknown, secrets: Array<string | undefined>): unknown {
+  if (typeof value === "string") {
+    return redactString(value, secrets);
+  }
+
+  if (Array.isArray(value)) {
+    return value.map((item) => redactValue(item, secrets));
+  }
+
+  if (isRecord(value)) {
+    const redacted: Record<string, unknown> = {};
+
+    for (const [key, item] of Object.entries(value)) {
+      if (/secret|token|apikey|api_key|authorization|password/i.test(key)) {
+        redacted[key] = "<redacted>";
+        continue;
+      }
+
+      redacted[key] = redactValue(item, secrets);
+    }
+
+    return redacted;
+  }
+
+  return value;
+}