@andreprado/agentkit 0.1.0-alpha.2 → 0.1.0-alpha.21

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

@@ -0,0 +1,1327 @@
+import type {
+  ChannelAdapter,
+  ChannelMediaDownloadInput,
+  ChannelMediaDownloadResult,
+  ChannelSendInput,
+  ChannelSendResult,
+  ChannelStatusInput,
+  ChannelStatusResult,
+  NormalizedChannelEvent,
+  RawWebhookEvent,
+  WebhookVerificationInput,
+  WebhookVerificationResult,
+} from "../channels";
+import { AgentKitError } from "../errors";
+
+type UazapiFetch = (url: string, init?: RequestInit) => Promise<Response>;
+
+type UazapiSendTextRequest = {
+  method: "POST";
+  url: string;
+  body: {
+    number: string;
+    text: string;
+    readchat: boolean;
+    async: boolean;
+    track_source: "agentkit";
+    track_id: string;
+  };
+  idempotencyKey: string;
+};
+
+type UazapiMessage = {
+  id?: string;
+  messageId?: string;
+  chatId?: string;
+  sender?: string;
+  senderName?: string;
+  fromMe?: boolean;
+  wasSentByApi?: boolean;
+  messageType?: string;
+  timestamp?: number;
+  text?: string;
+  fileUrl?: string;
+  mimeType?: string;
+  durationSeconds?: number;
+  sizeBytes?: number;
+};
+
+const UAZAPI_MAX_DOWNLOAD_BYTES = 25_000_000;
+const UAZAPI_MEDIA_DOWNLOAD_BODY_OVERHEAD_BYTES = 64_000;
+const UAZAPI_MESSAGE_EVENTS = new Set(["messages", "message", "message.received", "newsletter_messages"]);
+const UAZAPI_UPDATE_EVENTS = new Set(["messages_update", "message.status", "message.update"]);
+const UAZAPI_IGNORED_EVENTS = new Set(["connection", "presence", "history"]);
+
+export const uazapiWhatsappChannelAdapter: ChannelAdapter = {
+  type: "whatsapp",
+  provider: "uazapi",
+  requiredSecrets: ["UAZAPI_BASE_URL", "UAZAPI_TOKEN"],
+  verifyWebhook(input) {
+    const optionalTokenResult = verifyOptionalWebhookToken(input);
+
+    if (!optionalTokenResult.ok) {
+      return optionalTokenResult;
+    }
+
+    try {
+      parseJsonObject(input);
+    } catch (error) {
+      return {
+        ok: false,
+        code: "channel_payload_invalid",
+        message: error instanceof Error ? error.message : String(error),
+      };
+    }
+
+    return { ok: true };
+  },
+  normalizeInbound(input) {
+    const body = parseJsonObject(input);
+    const eventType = readEventType(body);
+
+    if (UAZAPI_IGNORED_EVENTS.has(eventType)) {
+      return [unsupportedUazapiEvent(input, body, eventType, "unsupported_event_type")];
+    }
+
+    if (UAZAPI_UPDATE_EVENTS.has(eventType)) {
+      return [normalizeUazapiStatusEvent(input, body, eventType)];
+    }
+
+    if (!UAZAPI_MESSAGE_EVENTS.has(eventType)) {
+      return [unsupportedUazapiEvent(input, body, eventType, "unsupported_event_type")];
+    }
+
+    const message = normalizeUazapiMessage(body);
+    const providerEventId = providerEventIdFor(body, message);
+
+    if (!providerEventId) {
+      throw new AgentKitError("channel_payload_invalid", "UAZAPI payload is missing messageid, event id, or chat timestamp.");
+    }
+
+    const contactId = stripWhatsappJid(message.sender ?? message.chatId ?? "unknown");
+    const instanceId = readString(body, "instance") ?? readString(body, "instance_id") ?? "default";
+    const messageType = (message.messageType ?? (message.text ? "text" : "unknown")).toLowerCase();
+    const base = baseUazapiEvent(input, {
+      providerEventId,
+      instanceId,
+      contactId,
+      eventType,
+      messageType,
+      senderName: message.senderName,
+    });
+
+    if (message.fromMe || message.wasSentByApi) {
+      return [
+        {
+          ...base,
+          kind: "unsupported",
+          unsupportedReason: message.wasSentByApi ? "ignored_message:was_sent_by_api" : "ignored_message:from_me",
+        },
+      ];
+    }
+
+    if (isUazapiAudioMessage(messageType, message)) {
+      return [
+        {
+          ...base,
+          kind: "message",
+          message: {
+            role: "user",
+            contentType: "audio",
+            content: "",
+            providerMessageId: message.messageId ?? message.id,
+            audio: {
+              providerMediaId: message.messageId ?? message.id ?? providerEventId,
+              kind: messageType === "ptt" || messageType === "myaudio" ? "voice" : "audio",
+              ...(message.mimeType ? { mimeType: message.mimeType } : {}),
+              filename: defaultUazapiAudioFilename(message),
+              ...(message.durationSeconds !== undefined ? { durationSeconds: message.durationSeconds } : {}),
+              ...(message.sizeBytes !== undefined ? { sizeBytes: message.sizeBytes } : {}),
+            },
+          },
+        },
+      ];
+    }
+
+    if (!isUazapiTextMessage(messageType, message)) {
+      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.messageId ?? message.id,
+        },
+      },
+    ];
+  },
+  async downloadMedia(input) {
+    return downloadUazapiMedia(input);
+  },
+  async sendMessage(input) {
+    return sendUazapiMessage(input);
+  },
+  async getStatus(input) {
+    return getUazapiStatus(input);
+  },
+};
+
+export function buildUazapiSendTextRequest(input: ChannelSendInput): UazapiSendTextRequest {
+  return buildUazapiSendTextRequestInternal(input, "<redacted>", "<redacted>");
+}
+
+export async function sendUazapiMessage(
+  input: ChannelSendInput,
+  fetcher: UazapiFetch = fetch,
+): Promise<ChannelSendResult> {
+  if (input.secrets.AGENTKIT_CHANNEL_SEND_DRY_RUN === "1") {
+    const request = buildUazapiSendTextRequest(input);
+
+    return {
+      ok: true,
+      status: "stubbed",
+      providerRequestId: request.idempotencyKey,
+      providerMetadata: {
+        method: request.method,
+        url: request.url,
+        body: request.body,
+      },
+    };
+  }
+
+  const token = input.secrets.UAZAPI_TOKEN;
+  const baseUrl = input.secrets.UAZAPI_BASE_URL;
+
+  if (!token || !baseUrl) {
+    return {
+      ok: false,
+      retryable: false,
+      code: "channel_secret_missing",
+      message: "Secret UAZAPI_BASE_URL or UAZAPI_TOKEN is missing.",
+    };
+  }
+
+  let request: UazapiSendTextRequest;
+  let actualRequest: UazapiSendTextRequest;
+
+  try {
+    request = buildUazapiSendTextRequest(input);
+    actualRequest = buildUazapiSendTextRequestInternal(input, baseUrl, "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, {
+      method: actualRequest.method,
+      headers: {
+        token,
+        "Content-Type": "application/json",
+        Accept: "application/json",
+      },
+      body: JSON.stringify(actualRequest.body),
+    });
+  } catch (error) {
+    const message = redactString(error instanceof Error ? error.message : String(error), [token, baseUrl]);
+
+    return {
+      ok: false,
+      retryable: true,
+      code: "channel_provider_unavailable",
+      message: `UAZAPI sendText request failed before a response: ${message}`,
+      providerRequestId: request.idempotencyKey,
+      providerMetadata: {
+        method: request.method,
+        url: request.url,
+        body: request.body,
+      },
+    };
+  }
+
+  const payload = await readUazapiResponseBody(response);
+  const redactedPayload = redactValue(payload, [token, baseUrl]);
+  const messageId = readUazapiProviderMessageId(payload);
+
+  if (!response.ok) {
+    return {
+      ok: false,
+      retryable: isRetryableUazapiSendFailure(response.status, payload),
+      code: "channel_send_failed",
+      message: redactString(readUazapiErrorMessage(payload, response.status), [token, baseUrl]),
+      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: "UAZAPI sendText did not return messageid or 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 downloadUazapiMedia(
+  input: ChannelMediaDownloadInput,
+  fetcher: UazapiFetch = fetch,
+): Promise<ChannelMediaDownloadResult> {
+  const token = input.secrets.UAZAPI_TOKEN;
+  const baseUrl = input.secrets.UAZAPI_BASE_URL;
+
+  if (!token || !baseUrl) {
+    return {
+      ok: false,
+      retryable: false,
+      code: "channel_secret_missing",
+      message: "Secret UAZAPI_BASE_URL or UAZAPI_TOKEN is missing.",
+    };
+  }
+
+  const providerMessageId = input.message.providerMessageId ?? input.message.audio?.providerMediaId;
+
+  if (!providerMessageId) {
+    return {
+      ok: false,
+      retryable: false,
+      code: "channel_audio_download_unavailable",
+      message: "UAZAPI audio payload did not include a provider message id.",
+    };
+  }
+
+  let url: string;
+
+  try {
+    url = uazapiApiUrl(baseUrl, "/message/download");
+  } 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, {
+      method: "POST",
+      headers: {
+        token,
+        "Content-Type": "application/json",
+        Accept: "application/json",
+      },
+      body: JSON.stringify({
+        id: providerMessageId,
+        return_base64: true,
+        return_link: false,
+        generate_mp3: false,
+        transcribe: false,
+      }),
+    });
+  } catch (error) {
+    return {
+      ok: false,
+      retryable: true,
+      code: "channel_provider_unavailable",
+      message: `UAZAPI media download failed before a response: ${redactString(
+        error instanceof Error ? error.message : String(error),
+        [token, baseUrl],
+      )}`,
+    };
+  }
+
+  const maxBytes = input.maxBytes ?? UAZAPI_MAX_DOWNLOAD_BYTES;
+  let payload: unknown;
+
+  try {
+    payload = await readUazapiResponseBody(response, {
+      maxBytes: maxUazapiMediaResponseBytes(maxBytes),
+    });
+  } catch (error) {
+    if (error instanceof UazapiResponseBodyTooLargeError) {
+      return {
+        ok: false,
+        retryable: false,
+        code: "channel_audio_too_large",
+        message: `UAZAPI media download response exceeds the configured ${maxBytes} byte audio limit before decode.`,
+        providerMetadata: {
+          status: response.status,
+        },
+      };
+    }
+
+    throw error;
+  }
+
+  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: `UAZAPI media download returned HTTP ${response.status}.`,
+      providerMetadata: {
+        status: response.status,
+        body: redactValue(payload, [token, baseUrl]),
+      },
+    };
+  }
+
+  if (!isRecord(payload) || typeof payload.base64Data !== "string") {
+    return {
+      ok: false,
+      retryable: false,
+      code: "channel_audio_download_unavailable",
+      message: "UAZAPI media download did not return base64Data.",
+      providerMetadata: {
+        status: response.status,
+        body: redactValue(payload, [token, baseUrl]),
+      },
+    };
+  }
+
+  const base64Data = normalizeBase64(payload.base64Data);
+  const estimatedBytes = estimateBase64DecodedBytes(base64Data);
+
+  if (estimatedBytes === undefined) {
+    return {
+      ok: false,
+      retryable: false,
+      code: "channel_media_download_failed",
+      message: "UAZAPI media download returned invalid base64Data.",
+      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(base64Data);
+  } catch {
+    return {
+      ok: false,
+      retryable: false,
+      code: "channel_media_download_failed",
+      message: "UAZAPI media download returned invalid base64Data.",
+      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`,
+    ...(typeof payload.mimetype === "string" ? { mimeType: payload.mimetype } : 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 getUazapiStatus(
+  input: ChannelStatusInput,
+  fetcher: UazapiFetch = fetch,
+): Promise<ChannelStatusResult> {
+  const missingSecrets = ["UAZAPI_BASE_URL", "UAZAPI_TOKEN"].filter((secret) => !input.secrets[secret]);
+
+  if (missingSecrets.length > 0) {
+    return {
+      status: "needs_setup",
+      checkedAt: new Date().toISOString(),
+      message: `UAZAPI channel secrets are missing: ${missingSecrets.join(", ")}.`,
+    };
+  }
+
+  let url: string;
+
+  try {
+    url = uazapiApiUrl(input.secrets.UAZAPI_BASE_URL, "/instance/status");
+  } 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, {
+      method: "GET",
+      headers: {
+        token: input.secrets.UAZAPI_TOKEN,
+        Accept: "application/json",
+      },
+    });
+  } catch (error) {
+    return {
+      status: "failed",
+      checkedAt: new Date().toISOString(),
+      message: `UAZAPI instance status failed before a response: ${redactString(
+        error instanceof Error ? error.message : String(error),
+        [input.secrets.UAZAPI_TOKEN, input.secrets.UAZAPI_BASE_URL],
+      )}`,
+    };
+  }
+
+  const payload = await readUazapiResponseBody(response);
+
+  if (!response.ok) {
+    return {
+      status: "failed",
+      checkedAt: new Date().toISOString(),
+      message: redactString(
+        readUazapiErrorMessage(payload, response.status),
+        [input.secrets.UAZAPI_TOKEN, input.secrets.UAZAPI_BASE_URL],
+      ),
+      providerMetadata: {
+        status: response.status,
+        body: redactValue(payload, [input.secrets.UAZAPI_TOKEN, input.secrets.UAZAPI_BASE_URL]),
+      },
+    };
+  }
+
+  const instance = isRecord(payload) ? readRecord(payload, "instance") : {};
+  const status = isRecord(payload) ? readRecord(payload, "status") : {};
+  const instanceStatus = readString(instance, "status");
+  const connected = readBoolean(status, "connected") === true || instanceStatus === "connected";
+
+  if (connected) {
+    return {
+      status: "connected",
+      checkedAt: new Date().toISOString(),
+      message: "UAZAPI instance is connected.",
+      providerMetadata: {
+        instanceStatus: instanceStatus ?? "connected",
+        ...(readString(instance, "name") ? { instanceName: readString(instance, "name") } : {}),
+      },
+    };
+  }
+
+  return {
+    status: "needs_setup",
+    checkedAt: new Date().toISOString(),
+    message: `UAZAPI instance is ${instanceStatus ?? "not connected"}. Connect it with QR code or pairing code in UAZAPI.`,
+    providerMetadata: {
+      ...(instanceStatus ? { instanceStatus } : {}),
+    },
+  };
+}
+
+export function buildUazapiWebhookSetupPayload(webhookUrl: string): Record<string, unknown> {
+  return {
+    enabled: true,
+    url: webhookUrl,
+    events: ["messages", "messages_update", "connection"],
+    excludeMessages: ["wasSentByApi"],
+    addUrlEvents: false,
+    addUrlTypesMessages: false,
+  };
+}
+
+export function uazapiApiUrl(baseUrl: string, path: string): string {
+  const base = validateUazapiBaseUrl(baseUrl);
+  const normalizedPath = path.startsWith("/") ? path : `/${path}`;
+  return new URL(normalizedPath, `${base}/`).href;
+}
+
+function verifyOptionalWebhookToken(input: WebhookVerificationInput): WebhookVerificationResult {
+  const expectsToken = input.channel.secrets.includes("UAZAPI_WEBHOOK_TOKEN");
+
+  if (!expectsToken) {
+    return { ok: true };
+  }
+
+  const expectedToken = input.secrets.UAZAPI_WEBHOOK_TOKEN;
+
+  if (!expectedToken) {
+    return {
+      ok: false,
+      code: "channel_secret_missing",
+      message: "Secret UAZAPI_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: "UAZAPI webhook token did not match.",
+    };
+  }
+
+  return { ok: true };
+}
+
+function normalizeUazapiStatusEvent(
+  input: RawWebhookEvent,
+  body: Record<string, unknown>,
+  eventType: string,
+): NormalizedChannelEvent {
+  const message = normalizeUazapiMessage(body);
+  const providerEventId = providerEventIdFor(body, message) ?? `status:${Date.now()}`;
+  const status = (message.messageType ?? readString(body, "status") ?? "sent").toLowerCase();
+  const deliveryStatus = status.includes("read")
+    ? "delivered"
+    : status.includes("deliver")
+      ? "delivered"
+      : status.includes("fail")
+        ? "failed"
+        : "sent";
+
+  return {
+    ...baseUazapiEvent(input, {
+      providerEventId,
+      instanceId: readString(body, "instance") ?? readString(body, "instance_id") ?? "default",
+      contactId: stripWhatsappJid(message.sender ?? message.chatId ?? "unknown"),
+      eventType,
+      messageType: status,
+      senderName: message.senderName,
+    }),
+    kind: "delivery_status",
+    deliveryStatus,
+  };
+}
+
+function unsupportedUazapiEvent(
+  input: RawWebhookEvent,
+  body: Record<string, unknown>,
+  eventType: string,
+  reason: string,
+): NormalizedChannelEvent {
+  const message = normalizeUazapiMessage(body);
+  const providerEventId = providerEventIdFor(body, message) ?? `${eventType}:${Date.now()}`;
+
+  return {
+    ...baseUazapiEvent(input, {
+      providerEventId,
+      instanceId: readString(body, "instance") ?? readString(body, "instance_id") ?? "default",
+      contactId: stripWhatsappJid(message.sender ?? message.chatId ?? "unknown"),
+      eventType,
+      messageType: message.messageType ?? "unknown",
+      senderName: message.senderName,
+    }),
+    kind: "unsupported",
+    unsupportedReason: `${reason}:${eventType}`,
+  };
+}
+
+function baseUazapiEvent(
+  input: RawWebhookEvent,
+  values: {
+    providerEventId: string;
+    instanceId: string;
+    contactId: string;
+    eventType: string;
+    messageType: string;
+    senderName?: string;
+  },
+): Omit<NormalizedChannelEvent, "kind"> {
+  return {
+    type: "whatsapp",
+    provider: "uazapi",
+    providerEventId: values.providerEventId,
+    dedupeKey: `whatsapp:uazapi:${values.instanceId}:${values.providerEventId}`,
+    externalIdentity: {
+      key: `whatsapp:uazapi:contact:${values.contactId}`,
+      display: values.senderName ?? values.contactId,
+      redactedDisplay: values.senderName
+        ? `${values.senderName} (${redactPhone(values.contactId)})`
+        : `whatsapp:uazapi:contact:${redactPhone(values.contactId)}`,
+    },
+    receivedAt: input.receivedAt,
+    providerMetadata: {
+      instanceId: values.instanceId,
+      eventType: values.eventType,
+      messageType: values.messageType,
+    },
+  };
+}
+
+function normalizeUazapiMessage(body: Record<string, unknown>): UazapiMessage {
+  const data = readRecord(body, "data");
+  const nestedMessage = readRecord(body, "message");
+  const dataMessage = readRecord(data, "message");
+  const message = Object.keys(nestedMessage).length > 0
+    ? nestedMessage
+    : Object.keys(dataMessage).length > 0
+      ? dataMessage
+      : Object.keys(data).length > 0
+        ? data
+        : body;
+  const content = readRecord(message, "content");
+  const textRecord = readRecord(message, "text");
+
+  return {
+    id: readString(message, "id"),
+    messageId: readString(message, "messageid") ?? readString(message, "messageId") ?? readString(message, "message_id"),
+    chatId: readString(message, "chatid") ?? readString(message, "chatId") ?? readString(message, "chat_id") ?? readString(message, "from"),
+    sender:
+      readString(message, "sender") ??
+      readString(message, "from") ??
+      readString(data, "from") ??
+      readString(message, "chatid") ??
+      readString(message, "chatId"),
+    senderName: readString(message, "senderName") ?? readString(message, "pushName") ?? readString(message, "name"),
+    fromMe: readBoolean(message, "fromMe"),
+    wasSentByApi: readBoolean(message, "wasSentByApi"),
+    messageType:
+      readString(message, "messageType") ??
+      readString(message, "type") ??
+      readString(message, "message_type") ??
+      readString(content, "type"),
+    timestamp: readNumber(message, "messageTimestamp") ?? readNumber(message, "timestamp") ?? readNumber(data, "timestamp"),
+    text:
+      readString(message, "text") ??
+      readString(textRecord, "body") ??
+      readString(content, "text") ??
+      readString(content, "conversation") ??
+      readString(data, "body"),
+    fileUrl: readString(message, "fileURL") ?? readString(message, "fileUrl") ?? readString(message, "url"),
+    mimeType: readString(message, "mimetype") ?? readString(message, "mimeType"),
+    durationSeconds: readNumber(message, "duration") ?? readNumber(content, "duration"),
+    sizeBytes: readNumber(message, "file_size") ?? readNumber(message, "size") ?? readNumber(content, "size"),
+  };
+}
+
+function providerEventIdFor(body: Record<string, unknown>, message: UazapiMessage): string | undefined {
+  return (
+    message.messageId ??
+    readString(body, "event_id") ??
+    readString(body, "eventId") ??
+    readString(body, "id") ??
+    message.id ??
+    fallbackEventId(message)
+  );
+}
+
+function fallbackEventId(message: UazapiMessage): string | undefined {
+  if (!message.chatId || message.timestamp === undefined) {
+    return undefined;
+  }
+
+  return `fallback:${stripWhatsappJid(message.chatId)}:${message.timestamp}`;
+}
+
+function readEventType(body: Record<string, unknown>): string {
+  const value =
+    readString(body, "EventType") ??
+    readString(body, "eventType") ??
+    readString(body, "event") ??
+    readString(body, "type") ??
+    "messages";
+  return value.toLowerCase();
+}
+
+function isUazapiTextMessage(messageType: string, message: UazapiMessage): boolean {
+  return messageType === "text" || messageType === "conversation" || Boolean(message.text);
+}
+
+function isUazapiAudioMessage(messageType: string, message: UazapiMessage): boolean {
+  return (
+    messageType === "audio" ||
+    messageType === "ptt" ||
+    messageType === "myaudio" ||
+    Boolean(message.mimeType?.toLowerCase().startsWith("audio/"))
+  );
+}
+
+function defaultUazapiAudioFilename(message: UazapiMessage): string {
+  const id = message.messageId ?? message.id ?? "uazapi-audio";
+  const extension = message.mimeType?.includes("mpeg") ? "mp3" : "ogg";
+  return `${id}.${extension}`;
+}
+
+function buildUazapiSendTextRequestInternal(
+  input: ChannelSendInput,
+  baseUrl: string,
+  mode: "actual" | "<redacted>",
+): UazapiSendTextRequest {
+  if (input.message.contentType !== "text") {
+    throw new Error("UAZAPI sendText supports only text channel messages.");
+  }
+
+  const to = contactFromExternalIdentity(input.externalIdentity.key);
+  const redactedTo = redactPhone(to);
+  const trackId = `${input.channelId}:${input.conversationId}`;
+
+  return {
+    method: "POST",
+    url: mode === "actual" ? uazapiApiUrl(baseUrl, "/send/text") : "https://<redacted>/send/text",
+    body: {
+      number: mode === "actual" ? to : redactedTo,
+      text: input.message.content,
+      readchat: true,
+      async: false,
+      track_source: "agentkit",
+      track_id: trackId,
+    },
+    idempotencyKey: `whatsapp:uazapi:${input.channelId}:${input.conversationId}:${redactedTo}`,
+  };
+}
+
+function contactFromExternalIdentity(identityKey: string): string {
+  const prefix = "whatsapp:uazapi:contact:";
+
+  if (!identityKey.startsWith(prefix)) {
+    throw new Error("UAZAPI WhatsApp external identity must start with whatsapp:uazapi:contact:.");
+  }
+
+  const contact = identityKey.slice(prefix.length);
+
+  if (!contact) {
+    throw new Error("UAZAPI WhatsApp external identity is missing a contact id.");
+  }
+
+  return contact;
+}
+
+function readUazapiProviderMessageId(payload: unknown): string | undefined {
+  if (!isRecord(payload)) {
+    return undefined;
+  }
+
+  const response = readRecord(payload, "response");
+  const message = readRecord(payload, "message");
+
+  return (
+    readString(payload, "messageid") ??
+    readString(payload, "messageId") ??
+    readString(payload, "id") ??
+    readString(message, "messageid") ??
+    readString(message, "id") ??
+    readString(response, "messageid") ??
+    readString(response, "id")
+  );
+}
+
+function isRetryableUazapiSendFailure(status: number, payload: unknown): boolean {
+  if (status === 429 || status >= 500) {
+    const errorKey = isRecord(payload) ? readString(payload, "error_key") : undefined;
+
+    if (errorKey === "WHATSAPP_REACHOUT_TIMELOCK") {
+      return false;
+    }
+
+    return true;
+  }
+
+  return false;
+}
+
+class UazapiResponseBodyTooLargeError extends Error {
+  constructor() {
+    super("UAZAPI response body exceeded the configured limit.");
+  }
+}
+
+async function readUazapiResponseBody(response: Response, options: { maxBytes?: number } = {}): Promise<unknown> {
+  const text = await readUazapiResponseText(response, options.maxBytes);
+
+  if (!text) {
+    return null;
+  }
+
+  try {
+    return JSON.parse(text);
+  } catch {
+    return text;
+  }
+}
+
+async function readUazapiResponseText(response: Response, maxBytes?: number): Promise<string> {
+  if (maxBytes !== undefined) {
+    const contentLength = readContentLength(response.headers);
+
+    if (contentLength !== undefined && contentLength > maxBytes) {
+      throw new UazapiResponseBodyTooLargeError();
+    }
+  }
+
+  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 UazapiResponseBodyTooLargeError();
+        }
+
+        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 UazapiResponseBodyTooLargeError();
+  }
+
+  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 maxUazapiMediaResponseBytes(maxAudioBytes: number): number {
+  return Math.ceil(maxAudioBytes / 3) * 4 + UAZAPI_MEDIA_DOWNLOAD_BODY_OVERHEAD_BYTES;
+}
+
+function readUazapiErrorMessage(payload: unknown, status: number): string {
+  if (isRecord(payload)) {
+    return (
+      readString(payload, "message") ??
+      readString(payload, "error") ??
+      readString(payload, "provider_message") ??
+      `UAZAPI request returned HTTP ${status}.`
+    );
+  }
+
+  return typeof payload === "string" && payload ? payload : `UAZAPI 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", "UAZAPI payload must be valid JSON.");
+  }
+
+  if (!isRecord(parsed)) {
+    throw new AgentKitError("channel_payload_invalid", "UAZAPI payload must be a JSON object.");
+  }
+
+  return parsed;
+}
+
+function validateUazapiBaseUrl(rawBaseUrl: string): string {
+  let url: URL;
+
+  try {
+    url = new URL(rawBaseUrl);
+  } catch {
+    throw new Error("UAZAPI_BASE_URL must be a valid HTTPS URL.");
+  }
+
+  if (url.protocol !== "https:") {
+    throw new Error("UAZAPI_BASE_URL must use HTTPS.");
+  }
+
+  if (url.username || url.password) {
+    throw new Error("UAZAPI_BASE_URL must not include credentials.");
+  }
+
+  if (isBlockedHostname(url.hostname)) {
+    throw new Error("UAZAPI_BASE_URL host is not allowed.");
+  }
+
+  url.pathname = url.pathname.replace(/\/+$/, "");
+  url.search = "";
+  url.hash = "";
+
+  return url.href.replace(/\/$/, "");
+}
+
+function isBlockedHostname(hostname: string): boolean {
+  const host = normalizeUrlHostname(hostname);
+
+  if (
+    host === "localhost" ||
+    host.endsWith(".localhost") ||
+    host === "metadata.google.internal" ||
+    host === "169.254.169.254"
+  ) {
+    return true;
+  }
+
+  const ipv4 = parseIpv4Octets(host);
+
+  if (ipv4) {
+    return isBlockedIpv4Octets(ipv4);
+  }
+
+  if (host.includes(":")) {
+    return isBlockedIpv6Hostname(host);
+  }
+
+  return false;
+}
+
+function normalizeUrlHostname(hostname: string): string {
+  const host = hostname.toLowerCase().replace(/\.$/, "");
+  return host.startsWith("[") && host.endsWith("]") ? host.slice(1, -1) : host;
+}
+
+function isBlockedIpv4Octets(parts: number[]): boolean {
+  const [a, b] = parts;
+
+  return (
+    a === 10 ||
+    a === 127 ||
+    (a === 169 && b === 254) ||
+    (a === 172 && b !== undefined && b >= 16 && b <= 31) ||
+    (a === 192 && b === 168) ||
+    a === 0
+  );
+}
+
+function isBlockedIpv6Hostname(host: string): boolean {
+  if (host.includes("%")) {
+    return true;
+  }
+
+  const segments = parseIpv6Segments(host);
+
+  if (!segments) {
+    return false;
+  }
+
+  const first = segments[0] ?? 0;
+  const isUnspecified = segments.every((segment) => segment === 0);
+  const isLoopback = segments.slice(0, 7).every((segment) => segment === 0) && segments[7] === 1;
+  const isUniqueLocal = (first & 0xfe00) === 0xfc00;
+  const isLinkLocal = (first & 0xffc0) === 0xfe80;
+  const isIpv4Mapped = segments.slice(0, 5).every((segment) => segment === 0) && segments[5] === 0xffff;
+  const isIpv4Compatible = segments.slice(0, 6).every((segment) => segment === 0) && (segments[6] !== 0 || segments[7] !== 0);
+
+  if (isUnspecified || isLoopback || isUniqueLocal || isLinkLocal) {
+    return true;
+  }
+
+  if (isIpv4Mapped || isIpv4Compatible) {
+    return isBlockedIpv4Octets([
+      (segments[6] >> 8) & 255,
+      segments[6] & 255,
+      (segments[7] >> 8) & 255,
+      segments[7] & 255,
+    ]);
+  }
+
+  return false;
+}
+
+function parseIpv6Segments(host: string): number[] | undefined {
+  if (!host.includes(":")) {
+    return undefined;
+  }
+
+  if ((host.match(/::/g) ?? []).length > 1) {
+    return undefined;
+  }
+
+  const [left = "", right = ""] = host.split("::");
+  const leftSegments = parseIpv6SegmentSide(left);
+  const rightSegments = parseIpv6SegmentSide(right);
+
+  if (!leftSegments || !rightSegments) {
+    return undefined;
+  }
+
+  if (!host.includes("::")) {
+    return leftSegments.length === 8 ? leftSegments : undefined;
+  }
+
+  const missing = 8 - leftSegments.length - rightSegments.length;
+
+  if (missing < 1) {
+    return undefined;
+  }
+
+  return [...leftSegments, ...Array.from({ length: missing }, () => 0), ...rightSegments];
+}
+
+function parseIpv6SegmentSide(value: string): number[] | undefined {
+  if (!value) {
+    return [];
+  }
+
+  const parts = value.split(":");
+  const segments: number[] = [];
+
+  for (const [index, part] of parts.entries()) {
+    if (!part) {
+      return undefined;
+    }
+
+    if (part.includes(".")) {
+      if (index !== parts.length - 1) {
+        return undefined;
+      }
+
+      const ipv4 = parseIpv4Octets(part);
+
+      if (!ipv4) {
+        return undefined;
+      }
+
+      segments.push((ipv4[0] << 8) | ipv4[1], (ipv4[2] << 8) | ipv4[3]);
+      continue;
+    }
+
+    if (!/^[0-9a-f]{1,4}$/i.test(part)) {
+      return undefined;
+    }
+
+    segments.push(Number.parseInt(part, 16));
+  }
+
+  return segments;
+}
+
+function parseIpv4Octets(host: string): number[] | undefined {
+  if (!/^\d+\.\d+\.\d+\.\d+$/.test(host)) {
+    return undefined;
+  }
+
+  const parts = host.split(".").map(Number);
+
+  if (parts.some((part) => !Number.isInteger(part) || part < 0 || part > 255)) {
+    return undefined;
+  }
+
+  return parts;
+}
+
+function stripWhatsappJid(value: string): string {
+  return value
+    .replace(/^whatsapp:/, "")
+    .replace(/@s\.whatsapp\.net$/i, "")
+    .replace(/@c\.us$/i, "")
+    .replace(/@lid$/i, "")
+    .replace(/@g\.us$/i, "");
+}
+
+function redactPhone(value: string): string {
+  const digits = value.replace(/\D/g, "");
+
+  if (digits.length < 8) {
+    return value;
+  }
+
+  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;
+}
+
+function redactValue(value: unknown, secrets: Array<string | undefined>): unknown {
+  if (typeof value === "string") {
+    return redactString(value, secrets);
+  }
+
+  if (Array.isArray(value)) {
+    return value.map((entry) => redactValue(entry, secrets));
+  }
+
+  if (isRecord(value)) {
+    const redacted: Record<string, unknown> = {};
+
+    for (const [key, entry] of Object.entries(value)) {
+      redacted[key] = redactValue(entry, secrets);
+    }
+
+    return redacted;
+  }
+
+  return value;
+}
+
+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 normalizeBase64(value: string): string {
+  return value.replace(/\s/g, "");
+}
+
+function estimateBase64DecodedBytes(value: string): number | undefined {
+  if (!/^[A-Za-z0-9+/]*={0,2}$/.test(value) || value.length % 4 === 1) {
+    return undefined;
+  }
+
+  if (value.includes("=") && !/={1,2}$/.test(value)) {
+    return undefined;
+  }
+
+  const padding = value.endsWith("==") ? 2 : value.endsWith("=") ? 1 : 0;
+  return Math.floor((value.length * 3) / 4) - padding;
+}
+
+function utf8ByteLength(value: string): number {
+  if (typeof Buffer !== "undefined") {
+    return Buffer.byteLength(value);
+  }
+
+  return new TextEncoder().encode(value).byteLength;
+}
+
+function readRecord(value: Record<string, unknown>, key: string): Record<string, unknown> {
+  const entry = value[key];
+  return isRecord(entry) ? entry : {};
+}
+
+function readString(value: Record<string, unknown>, key: string): string | undefined {
+  const entry = value[key];
+  return typeof entry === "string" && entry.length > 0 ? entry : undefined;
+}
+
+function readBoolean(value: Record<string, unknown>, key: string): boolean | undefined {
+  const entry = value[key];
+  return typeof entry === "boolean" ? entry : undefined;
+}
+
+function readNumber(value: Record<string, unknown>, key: string): number | undefined {
+  const entry = value[key];
+  return typeof entry === "number" && Number.isFinite(entry) ? entry : undefined;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return Boolean(value && typeof value === "object" && !Array.isArray(value));
+}