@andreprado/agentkit 0.1.0-alpha.9 → 0.1.1

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

@@ -1,28 +1,78 @@
-import type { ChannelAdapter, ChannelSendInput, RawWebhookEvent } from "../channels";
+import type {
+  ChannelAdapter,
+  ChannelMediaDownloadInput,
+  ChannelMediaDownloadResult,
+  ChannelSendInput,
+  ChannelSendResult,
+  RawWebhookEvent,
+  WebhookVerificationInput,
+  WebhookVerificationResult,
+} from "../channels";
 import { AgentKitError } from "../errors";
+import {
+  CHANNEL_DOWNLOAD_TIMEOUT_MS,
+  CHANNEL_SEND_TIMEOUT_MS,
+  classifySendRequestError,
+  isRetryableReadRequestError,
+} from "./provider-fetch";
 
 export const zapsterWhatsappChannelAdapter: ChannelAdapter = {
   type: "whatsapp",
   provider: "zapster",
-  requiredSecrets: ["ZAPSTER_API_KEY", "ZAPSTER_WEBHOOK_SECRET"],
+  requiredSecrets: ["ZAPSTER_API_KEY", "ZAPSTER_INSTANCE_ID", "ZAPSTER_WEBHOOK_ID", "ZAPSTER_WEBHOOK_TOKEN"],
   verifyWebhook(input) {
-    const expected = input.secrets.ZAPSTER_WEBHOOK_SECRET;
+    const expectedInstanceId = input.secrets.ZAPSTER_INSTANCE_ID;
+    const expectedWebhookId = input.secrets.ZAPSTER_WEBHOOK_ID;
 
-    if (!expected) {
+    if (!expectedInstanceId) {
       return {
         ok: false,
         code: "channel_secret_missing",
-        message: "Secret ZAPSTER_WEBHOOK_SECRET is not set for this channel.",
+        message: "Secret ZAPSTER_INSTANCE_ID is not set for this channel.",
       };
     }
 
-    const actual = input.headers.get("x-zapster-webhook-secret");
+    if (!expectedWebhookId) {
+      return {
+        ok: false,
+        code: "channel_secret_missing",
+        message: "Secret ZAPSTER_WEBHOOK_ID is not set for this channel.",
+      };
+    }
+
+    const tokenResult = verifyWebhookToken(input);
+
+    if (!tokenResult.ok) {
+      return tokenResult;
+    }
+
+    const instanceId = input.headers.get("x-instance-id");
+    const webhookId = input.headers.get("x-webhook-id");
+    const messageId = input.headers.get("x-message-id");
+    const attemptCount = input.headers.get("x-attempt-count");
+    const userAgent = input.headers.get("user-agent");
 
-    if (actual !== expected) {
+    if (instanceId !== expectedInstanceId) {
       return {
         ok: false,
         code: "channel_signature_invalid",
-        message: "Zapster webhook secret did not match.",
+        message: "Zapster instance id did not match.",
+      };
+    }
+
+    if (webhookId !== expectedWebhookId) {
+      return {
+        ok: false,
+        code: "channel_signature_invalid",
+        message: "Zapster webhook id did not match.",
+      };
+    }
+
+    if (!messageId || !isPositiveIntegerHeader(attemptCount) || !userAgent?.toLowerCase().startsWith("zapsterapi/")) {
+      return {
+        ok: false,
+        code: "channel_payload_invalid",
+        message: "Missing Zapster webhook headers.",
       };
     }
 
@@ -30,16 +80,21 @@ export const zapsterWhatsappChannelAdapter: ChannelAdapter = {
   },
   normalizeInbound(input) {
     const body = parseJsonObject(input);
-    const message = readRecord(body, "message");
-    const instanceId = readString(body, "instance_id") ?? "default";
-    const providerEventId = readString(body, "event_id") ?? readString(message, "id");
+    const officialMessage = normalizeZapsterOfficialMessage(body);
+    const message = officialMessage ?? normalizeZapsterLegacyMessage(body);
+    const instanceId = input.headers.get("x-instance-id") ?? readString(body, "instance_id") ?? "default";
+    const providerEventId =
+      readString(body, "id") ??
+      readString(body, "event_id") ??
+      input.headers.get("x-message-id") ??
+      message.id;
 
     if (!providerEventId) {
-      throw new AgentKitError("channel_payload_invalid", "Zapster payload is missing event_id or message.id.");
+      throw new AgentKitError("channel_payload_invalid", "Zapster payload is missing id, event_id, X-Message-ID, or message.id.");
     }
 
-    const contactId = readString(message, "from") ?? "unknown";
-    const messageType = readString(message, "type") ?? "unknown";
+    const contactId = message.contactId ?? "unknown";
+    const messageType = message.type ?? "unknown";
     const base = {
       type: "whatsapp" as const,
       provider: "zapster" as const,
@@ -54,9 +109,26 @@ export const zapsterWhatsappChannelAdapter: ChannelAdapter = {
       providerMetadata: {
         instanceId,
         messageType,
+        ...(readString(body, "type") ? { eventType: readString(body, "type") } : {}),
       },
     };
 
+    if (messageType === "audio" && message.audio) {
+      return [
+        {
+          ...base,
+          kind: "message",
+          message: {
+            role: "user",
+            contentType: "audio",
+            content: "",
+            providerMessageId: message.id,
+            audio: message.audio,
+          },
+        },
+      ];
+    }
+
     if (messageType !== "text") {
       return [
         {
@@ -67,7 +139,7 @@ export const zapsterWhatsappChannelAdapter: ChannelAdapter = {
       ];
     }
 
-    const text = readString(readRecord(message, "text"), "body");
+    const text = message.text;
 
     if (!text) {
       return [
@@ -87,30 +159,30 @@ export const zapsterWhatsappChannelAdapter: ChannelAdapter = {
           role: "user",
           contentType: "text",
           content: text,
-          providerMessageId: readString(message, "id"),
+          providerMessageId: message.id,
         },
       },
     ];
   },
+  async downloadMedia(input) {
+    return downloadZapsterMedia(input);
+  },
   async sendMessage(input) {
-    const request = buildZapsterSendMessageRequest(input);
-
-    return {
-      ok: true,
-      status: "sent",
-      providerRequestId: request.idempotencyKey,
-      providerMetadata: {
-        method: request.method,
-        url: request.url,
-      },
-    };
+    return sendZapsterMessage(input);
   },
   getStatus(input) {
-    if (!input.secrets.ZAPSTER_API_KEY) {
+    const missingSecrets = [
+      "ZAPSTER_API_KEY",
+      "ZAPSTER_INSTANCE_ID",
+      "ZAPSTER_WEBHOOK_ID",
+      "ZAPSTER_WEBHOOK_TOKEN",
+    ].filter((secret) => !input.secrets[secret]);
+
+    if (missingSecrets.length > 0) {
       return {
         status: "needs_setup",
         checkedAt: new Date().toISOString(),
-        message: "Secret ZAPSTER_API_KEY is missing.",
+        message: `Zapster channel secrets are missing: ${missingSecrets.join(", ")}.`,
       };
     }
 
@@ -122,20 +194,518 @@ export const zapsterWhatsappChannelAdapter: ChannelAdapter = {
   },
 };
 
+type NormalizedZapsterWebhookMessage = {
+  id?: string;
+  contactId?: string;
+  type?: string;
+  text?: string;
+  audio?: {
+    providerMediaId: string;
+    kind: "voice" | "audio";
+    mimeType?: string;
+    filename?: string;
+    durationSeconds?: number;
+    sizeBytes?: number;
+    downloadUrl?: string;
+  };
+};
+
+function normalizeZapsterOfficialMessage(body: Record<string, unknown>): NormalizedZapsterWebhookMessage | null {
+  if (readString(body, "type") !== "message.received") {
+    return null;
+  }
+
+  const data = readRecord(body, "data");
+  const content = readRecord(data, "content");
+  const sender = readRecord(data, "sender");
+
+  return {
+    id: readString(data, "id"),
+    contactId: readString(sender, "id"),
+    type: readString(data, "type"),
+    text: readString(content, "text"),
+    audio: normalizeZapsterAudio(content),
+  };
+}
+
+function normalizeZapsterLegacyMessage(body: Record<string, unknown>): NormalizedZapsterWebhookMessage {
+  const message = readRecord(body, "message");
+  const audio = readRecord(message, "audio");
+
+  return {
+    id: readString(message, "id"),
+    contactId: readString(message, "from"),
+    type: readString(message, "type"),
+    text: readString(readRecord(message, "text"), "body"),
+    audio: normalizeZapsterAudio(audio),
+  };
+}
+
+function normalizeZapsterAudio(value: Record<string, unknown>): NormalizedZapsterWebhookMessage["audio"] {
+  const mediaId = readString(value, "id") ?? readString(value, "media_id") ?? readString(value, "mediaId");
+  const downloadUrl =
+    readString(value, "url") ??
+    readString(value, "download_url") ??
+    readString(value, "downloadUrl") ??
+    readString(value, "media_url") ??
+    readString(value, "mediaUrl");
+
+  if (!mediaId && !downloadUrl) {
+    return undefined;
+  }
+
+  return {
+    providerMediaId: mediaId ?? downloadUrl ?? "unknown",
+    kind: readString(value, "ptt") === "true" ? "voice" : "audio",
+    ...(readString(value, "mime_type") ?? readString(value, "mimeType")
+      ? { mimeType: readString(value, "mime_type") ?? readString(value, "mimeType") }
+      : {}),
+    filename: readString(value, "filename") ?? readString(value, "file_name") ?? defaultZapsterAudioFilename(value),
+    ...(readNumber(value, "duration") !== undefined ? { durationSeconds: readNumber(value, "duration") } : {}),
+    ...(readNumber(value, "file_size") ?? readNumber(value, "size")
+      ? { sizeBytes: readNumber(value, "file_size") ?? readNumber(value, "size") }
+      : {}),
+    ...(downloadUrl ? { downloadUrl } : {}),
+  };
+}
+
+function verifyWebhookToken(input: WebhookVerificationInput): WebhookVerificationResult {
+  const expectedToken = input.secrets.ZAPSTER_WEBHOOK_TOKEN;
+
+  if (!expectedToken) {
+    return {
+      ok: false,
+      code: "channel_secret_missing",
+      message: "Secret ZAPSTER_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: "Zapster webhook token did not match.",
+    };
+  }
+
+  return { ok: true };
+}
+
 export type ZapsterSendMessageRequest = {
   method: "POST";
   url: string;
   body: {
-    to: string;
-    type: "text";
-    text: {
-      body: string;
-    };
+    recipient: string;
+    text: string;
+    instance_id: string;
   };
   idempotencyKey: string;
 };
 
+type ZapsterFetch = (url: string, init: RequestInit) => Promise<Response>;
+
+const ZAPSTER_SEND_MESSAGE_URL = "https://api.zapsterapi.com/v1/wa/messages";
+const ZAPSTER_DEFAULT_MEDIA_HOSTS = ["api.zapsterapi.com"];
+const ZAPSTER_MAX_DOWNLOAD_BYTES = 25_000_000;
+
 export function buildZapsterSendMessageRequest(input: ChannelSendInput): ZapsterSendMessageRequest {
+  return buildZapsterSendMessageRequestInternal(input, "<redacted>");
+}
+
+export async function sendZapsterMessage(
+  input: ChannelSendInput,
+  fetcher: ZapsterFetch = fetch,
+): Promise<ChannelSendResult> {
+  if (input.secrets.AGENTKIT_CHANNEL_SEND_DRY_RUN === "1") {
+    const request = buildZapsterSendMessageRequest(input);
+
+    return {
+      ok: true,
+      status: "stubbed",
+      providerRequestId: request.idempotencyKey,
+      providerMetadata: {
+        method: request.method,
+        url: request.url,
+        body: request.body,
+      },
+    };
+  }
+
+  const apiKey = input.secrets.ZAPSTER_API_KEY;
+  const instanceId = input.secrets.ZAPSTER_INSTANCE_ID;
+
+  if (!apiKey || !instanceId) {
+    return {
+      ok: false,
+      retryable: false,
+      code: "channel_secret_missing",
+      message: "Secret ZAPSTER_API_KEY or ZAPSTER_INSTANCE_ID is missing.",
+    };
+  }
+
+  let request: ZapsterSendMessageRequest;
+  let actualRequest: ZapsterSendMessageRequest;
+
+  try {
+    request = buildZapsterSendMessageRequest(input);
+    actualRequest = buildZapsterSendMessageRequestInternal(input, instanceId);
+  } 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: {
+        Authorization: `Bearer ${apiKey}`,
+        "Content-Type": "application/json",
+        Accept: "application/json",
+      },
+      body: JSON.stringify(actualRequest.body),
+    });
+  } catch (error) {
+    const failure = classifySendRequestError(error);
+    const errorMessage = redactString(error instanceof Error ? error.message : String(error), [apiKey, instanceId]);
+
+    return {
+      ok: false,
+      retryable: failure.retryable,
+      code: failure.code,
+      message: `Zapster sendMessage request ${failure.reason}: ${errorMessage}`,
+      providerRequestId: request.idempotencyKey,
+      providerMetadata: {
+        method: request.method,
+        url: request.url,
+        body: request.body,
+      },
+    };
+  }
+
+  const payload = await readZapsterResponseBody(response);
+  const redactedPayload = redactValue(payload, [apiKey, instanceId]);
+  const messageId = isRecord(payload)
+    ? readString(payload, "message_id") ?? readString(payload, "id")
+    : undefined;
+
+  if (!response.ok) {
+    return {
+      ok: false,
+      retryable: response.status === 429 || response.status >= 500,
+      code: "channel_send_failed",
+      message: redactString(readZapsterErrorMessage(payload, response.status), [apiKey, instanceId]),
+      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: "Zapster sendMessage did not return message_id 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 downloadZapsterMedia(
+  input: ChannelMediaDownloadInput,
+  fetcher: ZapsterFetch = fetch,
+): Promise<ChannelMediaDownloadResult> {
+  const apiKey = input.secrets.ZAPSTER_API_KEY;
+  const audio = input.message.audio;
+
+  if (!apiKey) {
+    return {
+      ok: false,
+      retryable: false,
+      code: "channel_secret_missing",
+      message: "Secret ZAPSTER_API_KEY is missing.",
+    };
+  }
+
+  if (!audio?.downloadUrl) {
+    return {
+      ok: false,
+      retryable: false,
+      code: "channel_audio_download_unavailable",
+      message: "Zapster audio payload did not include a media download URL.",
+    };
+  }
+
+  const mediaUrl = validateZapsterMediaDownloadUrl(audio.downloadUrl);
+
+  if (!mediaUrl.ok) {
+    return mediaUrl;
+  }
+
+  let response: Response;
+
+  try {
+    response = await fetcher(mediaUrl.url, {
+      signal: AbortSignal.timeout(CHANNEL_DOWNLOAD_TIMEOUT_MS),
+      method: "GET",
+      headers: {
+        Authorization: `Bearer ${apiKey}`,
+      },
+    });
+  } catch (error) {
+    return {
+      ok: false,
+      retryable: isRetryableReadRequestError(error),
+      code: "channel_provider_unavailable",
+      message: `Zapster media download failed before a response: ${redactString(
+        error instanceof Error ? error.message : String(error),
+        [apiKey, mediaUrl.url],
+      )}`,
+    };
+  }
+
+  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: `Zapster media download returned HTTP ${response.status}.`,
+      providerMetadata: {
+        status: response.status,
+      },
+    };
+  }
+
+  const maxDownloadBytes = input.maxBytes ?? ZAPSTER_MAX_DOWNLOAD_BYTES;
+  const bytes = await readResponseBytesWithLimit(response, maxDownloadBytes);
+
+  if (!bytes.ok) {
+    return bytes;
+  }
+
+  return {
+    ok: true,
+    audio: bytes.audio,
+    filename: audio.filename ?? `${audio.providerMediaId}.ogg`,
+    ...(audio.mimeType ? { mimeType: audio.mimeType } : {}),
+    ...(audio.durationSeconds !== undefined ? { durationSeconds: audio.durationSeconds } : {}),
+    sizeBytes: bytes.audio.byteLength,
+    providerMetadata: {
+      status: response.status,
+    },
+  };
+}
+
+function validateZapsterMediaDownloadUrl(rawUrl: string):
+  | {
+      ok: true;
+      url: string;
+    }
+  | {
+      ok: false;
+      retryable: false;
+      code: "channel_audio_download_unavailable";
+      message: string;
+    } {
+  let url: URL;
+
+  try {
+    url = new URL(rawUrl);
+  } catch {
+    return {
+      ok: false,
+      retryable: false,
+      code: "channel_audio_download_unavailable",
+      message: "Zapster audio download URL is not a valid URL.",
+    };
+  }
+
+  if (url.protocol !== "https:") {
+    return {
+      ok: false,
+      retryable: false,
+      code: "channel_audio_download_unavailable",
+      message: "Zapster audio download URL must use HTTPS.",
+    };
+  }
+
+  const hostname = url.hostname.toLowerCase();
+  const allowed = ZAPSTER_DEFAULT_MEDIA_HOSTS.some((host) => hostname === host || hostname.endsWith(`.${host}`));
+
+  if (!allowed) {
+    return {
+      ok: false,
+      retryable: false,
+      code: "channel_audio_download_unavailable",
+      message: "Zapster audio download URL host is not allowed.",
+    };
+  }
+
+  url.username = "";
+  url.password = "";
+
+  return {
+    ok: true,
+    url: url.href,
+  };
+}
+
+async function readResponseBytesWithLimit(
+  response: Response,
+  maxBytes: number,
+): Promise<
+  | {
+      ok: true;
+      audio: Uint8Array;
+    }
+  | {
+      ok: false;
+      retryable: boolean;
+      code: "channel_audio_too_large" | "channel_provider_unavailable";
+      message: string;
+      providerMetadata?: Record<string, unknown>;
+    }
+> {
+  const contentLength = response.headers.get("content-length");
+  const declaredBytes = contentLength ? Number(contentLength) : undefined;
+
+  if (declaredBytes !== undefined && Number.isFinite(declaredBytes) && declaredBytes > maxBytes) {
+    return {
+      ok: false,
+      retryable: false,
+      code: "channel_audio_too_large",
+      message: `Audio response declares ${declaredBytes} bytes, which exceeds the configured ${maxBytes} byte limit.`,
+      providerMetadata: {
+        sizeBytes: declaredBytes,
+      },
+    };
+  }
+
+  if (!response.body) {
+    let audio: Uint8Array;
+
+    try {
+      audio = new Uint8Array(await response.arrayBuffer());
+    } catch (error) {
+      return {
+        ok: false,
+        retryable: true,
+        code: "channel_provider_unavailable",
+        message: `Media download response could not be read: ${error instanceof Error ? error.message : String(error)}`,
+      };
+    }
+
+    if (audio.byteLength > maxBytes) {
+      return {
+        ok: false,
+        retryable: false,
+        code: "channel_audio_too_large",
+        message: `Audio response is ${audio.byteLength} bytes, which exceeds the configured ${maxBytes} byte limit.`,
+        providerMetadata: {
+          sizeBytes: audio.byteLength,
+        },
+      };
+    }
+
+    return { ok: true, audio };
+  }
+
+  const reader = response.body.getReader();
+  const chunks: Uint8Array[] = [];
+  let totalBytes = 0;
+
+  try {
+    while (true) {
+      const chunk = await reader.read();
+
+      if (chunk.done) {
+        break;
+      }
+
+      totalBytes += chunk.value.byteLength;
+
+      if (totalBytes > maxBytes) {
+        await reader.cancel().catch(() => undefined);
+        return {
+          ok: false,
+          retryable: false,
+          code: "channel_audio_too_large",
+          message: `Audio response exceeded the configured ${maxBytes} byte limit while downloading.`,
+          providerMetadata: {
+            sizeBytes: totalBytes,
+          },
+        };
+      }
+
+      chunks.push(chunk.value);
+    }
+  } catch (error) {
+    await reader.cancel().catch(() => undefined);
+    return {
+      ok: false,
+      retryable: true,
+      code: "channel_provider_unavailable",
+      message: `Media download response could not be read: ${error instanceof Error ? error.message : String(error)}`,
+    };
+  } finally {
+    reader.releaseLock();
+  }
+
+  const audio = new Uint8Array(totalBytes);
+  let offset = 0;
+
+  for (const chunk of chunks) {
+    audio.set(chunk, offset);
+    offset += chunk.byteLength;
+  }
+
+  return { ok: true, audio };
+}
+
+function buildZapsterSendMessageRequestInternal(
+  input: ChannelSendInput,
+  instanceId: string,
+): ZapsterSendMessageRequest {
   const to = input.externalIdentity.key.match(/contact:([^:]+)$/)?.[1];
 
   if (!to) {
@@ -144,18 +714,83 @@ export function buildZapsterSendMessageRequest(input: ChannelSendInput): Zapster
 
   return {
     method: "POST",
-    url: "https://api.zapster.example/messages",
+    url: ZAPSTER_SEND_MESSAGE_URL,
     body: {
-      to,
-      type: "text",
-      text: {
-        body: input.message.content,
-      },
+      recipient: to,
+      text: input.message.content,
+      instance_id: instanceId,
     },
     idempotencyKey: `whatsapp:zapster:${input.channelId}:${input.conversationId}:${redactPhone(to)}`,
   };
 }
 
+async function readZapsterResponseBody(response: Response): Promise<unknown> {
+  const text = await response.text().catch(() => "");
+
+  if (!text) {
+    return null;
+  }
+
+  try {
+    return JSON.parse(text) as unknown;
+  } catch {
+    return text;
+  }
+}
+
+function readZapsterErrorMessage(payload: unknown, status: number): string {
+  if (typeof payload === "string" && payload.length > 0) {
+    return payload;
+  }
+
+  if (isRecord(payload)) {
+    const message = readString(payload, "message") ?? readString(payload, "error") ?? readString(payload, "detail");
+
+    if (message) {
+      return message;
+    }
+
+    const error = readRecord(payload, "error");
+    const nestedMessage = readString(error, "message") ?? readString(error, "detail");
+
+    if (nestedMessage) {
+      return nestedMessage;
+    }
+  }
+
+  return `Zapster sendMessage returned HTTP ${status}.`;
+}
+
+function redactValue(value: unknown, secrets: string[]): unknown {
+  if (typeof value === "string") {
+    return redactString(value, secrets);
+  }
+
+  if (!isRecord(value) && !Array.isArray(value)) {
+    return value;
+  }
+
+  const serialized = redactString(JSON.stringify(value), secrets);
+
+  try {
+    return JSON.parse(serialized) as unknown;
+  } catch {
+    return serialized;
+  }
+}
+
+function redactString(value: string, secrets: string[]): string {
+  let redacted = value;
+
+  for (const secret of secrets) {
+    if (secret) {
+      redacted = redacted.split(secret).join("<redacted>");
+    }
+  }
+
+  return redacted;
+}
+
 function parseJsonObject(input: RawWebhookEvent): Record<string, unknown> {
   try {
     const parsed = JSON.parse(input.rawBody) as unknown;
@@ -180,6 +815,33 @@ function readString(value: Record<string, unknown>, key: string): string | undef
   return typeof field === "string" && field.length > 0 ? field : undefined;
 }
 
+function readNumber(value: Record<string, unknown>, key: string): number | undefined {
+  const field = value[key];
+  return typeof field === "number" && Number.isFinite(field) ? field : undefined;
+}
+
+function defaultZapsterAudioFilename(value: Record<string, unknown>): string {
+  const mimeType = readString(value, "mime_type") ?? readString(value, "mimeType");
+
+  if (mimeType?.includes("ogg")) {
+    return "audio.ogg";
+  }
+
+  if (mimeType?.includes("mpeg") || mimeType?.includes("mp3")) {
+    return "audio.mp3";
+  }
+
+  if (mimeType?.includes("wav")) {
+    return "audio.wav";
+  }
+
+  return "audio.ogg";
+}
+
+function isPositiveIntegerHeader(value: string | null): value is string {
+  return typeof value === "string" && /^[1-9]\d*$/.test(value);
+}
+
 function redactPhone(value: string): string {
   if (value.length <= 6) {
     return "*".repeat(value.length);