@andreprado/agentkit 0.1.0-alpha.10 → 0.1.0-alpha.12

package/docs/guides/channel-security.md

@@ -27,7 +27,7 @@ AGENTKIT_RUN_ZAPSTER_CHANNEL_TESTS=1 bun test
 
 Telegram smoke also requires `TELEGRAM_BOT_TOKEN`, `TELEGRAM_WEBHOOK_SECRET`, and `AGENTKIT_TELEGRAM_WEBHOOK_URL`.
 
-Zapster smoke also requires `ZAPSTER_API_KEY`, `AGENTKIT_ZAPSTER_SEND_URL`, and `AGENTKIT_ZAPSTER_TO`.
+Zapster smoke also requires `ZAPSTER_API_KEY`, `ZAPSTER_INSTANCE_ID`, and `AGENTKIT_ZAPSTER_TO`. `AGENTKIT_ZAPSTER_SEND_URL` is optional and defaults to `https://api.zapsterapi.com/v1/wa/messages`.
 
 ## Files Created Or Edited
 

package/docs/guides/channels-production-handoff.md

@@ -74,7 +74,7 @@ AGENTKIT_RUN_ZAPSTER_CHANNEL_TESTS=1 bun test
 
 Telegram smoke requires `TELEGRAM_BOT_TOKEN`, `TELEGRAM_WEBHOOK_SECRET`, and `AGENTKIT_TELEGRAM_WEBHOOK_URL`.
 
-Zapster smoke requires `ZAPSTER_API_KEY`, `AGENTKIT_ZAPSTER_SEND_URL`, and `AGENTKIT_ZAPSTER_TO`.
+Zapster smoke requires `ZAPSTER_API_KEY`, `ZAPSTER_INSTANCE_ID`, and `AGENTKIT_ZAPSTER_TO`. `AGENTKIT_ZAPSTER_SEND_URL` is optional and defaults to `https://api.zapsterapi.com/v1/wa/messages`.
 
 ## Smoke Checks
 

package/docs/guides/connect-whatsapp-zapster.md

@@ -97,6 +97,8 @@ https://<deploy-host>/channels/chn_<id>/whatsapp/zapster/webhook?token=<ZAPSTER_
 - Zapster webhook headers are origin validation, not a cryptographic body signature.
 - Use optional `ZAPSTER_WEBHOOK_TOKEN` in the webhook URL when the endpoint should require an extra secret known only to AgentKit and Zapster.
 - Unsupported media should be logged as skipped/unsupported without creating an agent run.
+- AgentKit handles Zapster `message.received` envelopes with event id at `id`, message text at `data.content.text`, and contact identity at `data.sender.id`.
+- Outbound replies call `POST https://api.zapsterapi.com/v1/wa/messages` with bearer auth and a JSON body containing `recipient`, `text`, and `instance_id`. Only set `AGENTKIT_CHANNEL_SEND_DRY_RUN=1` in tests when Zapster should not receive a real message.
 
 ## Verification
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@andreprado/agentkit",
-  "version": "0.1.0-alpha.10",
+  "version": "0.1.0-alpha.12",
   "private": false,
   "type": "module",
   "repository": {

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

@@ -1,6 +1,7 @@
 import type {
   ChannelAdapter,
   ChannelSendInput,
+  ChannelSendResult,
   RawWebhookEvent,
   WebhookVerificationInput,
   WebhookVerificationResult,
@@ -71,16 +72,21 @@ export const zapsterWhatsappChannelAdapter: ChannelAdapter = {
   },
   normalizeInbound(input) {
     const body = parseJsonObject(input);
-    const message = readRecord(body, "message");
+    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, "event_id") ?? input.headers.get("x-message-id") ?? readString(message, "id");
+    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, X-Message-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,
@@ -95,6 +101,7 @@ export const zapsterWhatsappChannelAdapter: ChannelAdapter = {
       providerMetadata: {
         instanceId,
         messageType,
+        ...(readString(body, "type") ? { eventType: readString(body, "type") } : {}),
       },
     };
 
@@ -108,7 +115,7 @@ export const zapsterWhatsappChannelAdapter: ChannelAdapter = {
       ];
     }
 
-    const text = readString(readRecord(message, "text"), "body");
+    const text = message.text;
 
     if (!text) {
       return [
@@ -128,23 +135,13 @@ export const zapsterWhatsappChannelAdapter: ChannelAdapter = {
           role: "user",
           contentType: "text",
           content: text,
-          providerMessageId: readString(message, "id"),
+          providerMessageId: message.id,
         },
       },
     ];
   },
   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) {
     const missingSecrets = ["ZAPSTER_API_KEY", "ZAPSTER_INSTANCE_ID", "ZAPSTER_WEBHOOK_ID"].filter(
@@ -167,6 +164,41 @@ export const zapsterWhatsappChannelAdapter: ChannelAdapter = {
   },
 };
 
+type NormalizedZapsterWebhookMessage = {
+  id?: string;
+  contactId?: string;
+  type?: string;
+  text?: 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"),
+  };
+}
+
+function normalizeZapsterLegacyMessage(body: Record<string, unknown>): NormalizedZapsterWebhookMessage {
+  const message = readRecord(body, "message");
+
+  return {
+    id: readString(message, "id"),
+    contactId: readString(message, "from"),
+    type: readString(message, "type"),
+    text: readString(readRecord(message, "text"), "body"),
+  };
+}
+
 function verifyOptionalWebhookToken(input: WebhookVerificationInput): WebhookVerificationResult {
   const expectsToken = input.channel.secrets.includes("ZAPSTER_WEBHOOK_TOKEN");
 
@@ -207,16 +239,136 @@ 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";
+
 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: "sent",
+      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, {
+      method: actualRequest.method,
+      headers: {
+        Authorization: `Bearer ${apiKey}`,
+        "Content-Type": "application/json",
+        Accept: "application/json",
+      },
+      body: JSON.stringify(actualRequest.body),
+    });
+  } catch (error) {
+    const errorMessage = redactString(error instanceof Error ? error.message : String(error), [apiKey, instanceId]);
+
+    return {
+      ok: false,
+      retryable: true,
+      code: "channel_provider_unavailable",
+      message: `Zapster sendMessage request failed before a response: ${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,
+      },
+    };
+  }
+
+  return {
+    ok: true,
+    status: "sent",
+    providerRequestId: messageId ?? request.idempotencyKey,
+    ...(messageId ? { providerMessageId: messageId } : {}),
+    providerMetadata: {
+      method: request.method,
+      url: request.url,
+      status: response.status,
+      body: redactedPayload,
+    },
+  };
+}
+
+function buildZapsterSendMessageRequestInternal(
+  input: ChannelSendInput,
+  instanceId: string,
+): ZapsterSendMessageRequest {
   const to = input.externalIdentity.key.match(/contact:([^:]+)$/)?.[1];
 
   if (!to) {
@@ -225,18 +377,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;

package/src/templates/skills/agentkit-channels/references/whatsapp-zapster.md

@@ -27,6 +27,10 @@ agentkit channels deliveries list support-whatsapp
 
 Paste the stable AgentKit webhook URL into Zapster settings. If the channel declares `ZAPSTER_WEBHOOK_TOKEN`, append `?token=<ZAPSTER_WEBHOOK_TOKEN>` to the Zapster webhook URL. Keep phone numbers redacted in logs by default.
 
+AgentKit handles Zapster `message.received` envelopes with event id at `id`, message text at `data.content.text`, and contact identity at `data.sender.id`. Unsupported media should be logged as skipped/unsupported without creating an agent run.
+
+Outbound replies call `POST https://api.zapsterapi.com/v1/wa/messages` with bearer auth and a JSON body containing `recipient`, `text`, and `instance_id`. Only set `AGENTKIT_CHANNEL_SEND_DRY_RUN=1` in tests when Zapster should not receive a real message.
+
 Buffer rapid WhatsApp messages:
 
 ```ts