@andreprado/agentkit 0.1.0-alpha.11 → 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

@@ -98,6 +98,7 @@ https://<deploy-host>/channels/chn_<id>/whatsapp/zapster/webhook?token=<ZAPSTER_
 - 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.11",
+  "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,
@@ -140,17 +141,7 @@ export const zapsterWhatsappChannelAdapter: ChannelAdapter = {
     ];
   },
   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(
@@ -248,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) {
@@ -266,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

@@ -29,6 +29,8 @@ Paste the stable AgentKit webhook URL into Zapster settings. If the channel decl
 
 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