whatsapp-cloud 0.0.4 → 0.0.6

package/src/services/messages/MessagesService.ts

@@ -1,4 +1,4 @@
-import type { HttpClient } from "../../client/HttpClient";
+import { HttpClient } from "../../client/HttpClient";
 import { sendText } from "./methods/send-text";
 import { sendImage } from "./methods/send-image";
 import { sendLocation } from "./methods/send-location";
@@ -16,62 +16,82 @@ import type { MessageResponse } from "../../types/messages/response";
 /**
  * Messages service for sending WhatsApp messages
  *
- * The service validates that phoneNumberId is set at the client level and creates
- * a MessagesClient instance. MessagesClient treats phoneNumberId as a "client" for
- * the messaging namespace - different phoneNumberIds represent different endpoints.
+ * This service handles message operations.
+ * It supports both a globally configured phoneNumberId (in WhatsAppClient)
+ * and per-request phoneNumberId overrides.
  */
 export class MessagesService {
-  private readonly messagesClient: MessagesClient;
+  constructor(private readonly httpClient: HttpClient) {}
 
-  constructor(httpClient: HttpClient) {
-    // Validate that phoneNumberId is set at client level
-    if (!httpClient.phoneNumberId) {
+  /**
+   * Helper to create a Scoped Client (prefer override, fallback to config)
+   */
+  private getClient(overrideId?: string): MessagesClient {
+    const id = overrideId || this.httpClient.phoneNumberId;
+    if (!id) {
       throw new WhatsAppValidationError(
-        "phoneNumberId is required for MessagesService. Provide it in WhatsAppClient config.",
+        "phoneNumberId is required. Provide it in WhatsAppClient config or as a parameter.",
         "phoneNumberId"
       );
     }
 
-    // Create messages client with phone number ID baked in
-    this.messagesClient = new MessagesClient(
-      httpClient,
-      httpClient.phoneNumberId
-    );
+    // Just wrap the existing httpClient
+    return new MessagesClient(this.httpClient, id);
   }
 
   /**
    * Send a text message
    *
    * @param request - Text message request (to, text)
+   * @param phoneNumberId - Optional phone number ID (overrides client config)
    */
-  async sendText(request: SendTextRequest): Promise<MessageResponse> {
-    return sendText(this.messagesClient, request);
+  async sendText(
+    request: SendTextRequest,
+    phoneNumberId?: string
+  ): Promise<MessageResponse> {
+    const client = this.getClient(phoneNumberId);
+    return sendText(client, request);
   }
 
   /**
    * Send an image message
    *
    * @param request - Image message request (to, image)
+   * @param phoneNumberId - Optional phone number ID (overrides client config)
    */
-  async sendImage(request: SendImageRequest): Promise<MessageResponse> {
-    return sendImage(this.messagesClient, request);
+  async sendImage(
+    request: SendImageRequest,
+    phoneNumberId?: string
+  ): Promise<MessageResponse> {
+    const client = this.getClient(phoneNumberId);
+    return sendImage(client, request);
   }
 
   /**
    * Send a location message
    *
    * @param request - Location message request (to, location)
+   * @param phoneNumberId - Optional phone number ID (overrides client config)
    */
-  async sendLocation(request: SendLocationRequest): Promise<MessageResponse> {
-    return sendLocation(this.messagesClient, request);
+  async sendLocation(
+    request: SendLocationRequest,
+    phoneNumberId?: string
+  ): Promise<MessageResponse> {
+    const client = this.getClient(phoneNumberId);
+    return sendLocation(client, request);
   }
 
   /**
    * Send a reaction message
    *
    * @param request - Reaction message request (to, reaction)
+   * @param phoneNumberId - Optional phone number ID (overrides client config)
    */
-  async sendReaction(request: SendReactionRequest): Promise<MessageResponse> {
-    return sendReaction(this.messagesClient, request);
+  async sendReaction(
+    request: SendReactionRequest,
+    phoneNumberId?: string
+  ): Promise<MessageResponse> {
+    const client = this.getClient(phoneNumberId);
+    return sendReaction(client, request);
   }
 }

package/src/services/templates/TemplatesClient.ts

@@ -0,0 +1,35 @@
+import type { HttpClient } from "../../client/HttpClient";
+
+/**
+ * Templates client - wraps HttpClient with WABA ID as base endpoint
+ *
+ * This client automatically prepends `/${businessAccountId}` to all request paths.
+ * Similar to AccountsClient, since templates are scoped to WABA.
+ */
+export class TemplatesClient {
+  constructor(
+    private readonly httpClient: HttpClient,
+    private readonly businessAccountId: string
+  ) {}
+
+  /**
+   * Make a GET request with WABA ID prefix
+   */
+  async get<T>(path: string): Promise<T> {
+    return this.httpClient.get<T>(`/${this.businessAccountId}${path}`);
+  }
+
+  /**
+   * Make a POST request with WABA ID prefix
+   */
+  async post<T>(path: string, body: unknown): Promise<T> {
+    return this.httpClient.post<T>(`/${this.businessAccountId}${path}`, body);
+  }
+
+  /**
+   * Make a DELETE request with WABA ID prefix
+   */
+  async delete<T>(path: string): Promise<T> {
+    return this.httpClient.delete<T>(`/${this.businessAccountId}${path}`);
+  }
+}

package/src/services/templates/TemplatesService.ts

@@ -0,0 +1,117 @@
+import type { HttpClient } from "../../client/HttpClient";
+import { TemplatesClient } from "./TemplatesClient";
+import { createTemplate } from "./methods/create";
+import { listTemplates } from "./methods/list";
+import { getTemplate } from "./methods/get";
+import { updateTemplate } from "./methods/update";
+import { deleteTemplate } from "./methods/delete";
+import { WhatsAppValidationError } from "../../errors";
+import type {
+  CreateTemplateRequest,
+  UpdateTemplateRequest,
+  ListTemplatesRequest,
+  DeleteTemplateRequest,
+} from "../../types/templates/request";
+import type {
+  CreateTemplateResponse,
+  ListTemplatesResponse,
+  TemplateResponse,
+  UpdateTemplateResponse,
+  DeleteTemplateResponse,
+} from "../../types/templates/response";
+
+/**
+ * Templates service for managing message templates
+ *
+ * This service handles template operations like creating, listing, and deleting templates.
+ * It supports both a globally configured businessAccountId (in WhatsAppClient)
+ * and per-request businessAccountId overrides.
+ *
+ * Note: Get and Update operations use template ID directly (no WABA prefix needed).
+ */
+export class TemplatesService {
+  constructor(private readonly httpClient: HttpClient) {}
+
+  /**
+   * Helper to create a Scoped Client (prefer override, fallback to config)
+   */
+  private getClient(overrideId?: string): TemplatesClient {
+    const id = overrideId || this.httpClient.businessAccountId;
+    if (!id) {
+      throw new WhatsAppValidationError(
+        "businessAccountId (WABA ID) is required for templates. Provide it in WhatsAppClient config or as a parameter.",
+        "businessAccountId"
+      );
+    }
+
+    return new TemplatesClient(this.httpClient, id);
+  }
+
+  /**
+   * Create a message template
+   *
+   * @param request - Template creation request
+   * @param businessAccountId - Optional WABA ID (overrides client config)
+   */
+  async create(
+    request: CreateTemplateRequest,
+    businessAccountId?: string
+  ): Promise<CreateTemplateResponse> {
+    const client = this.getClient(businessAccountId);
+    return createTemplate(client, request);
+  }
+
+  /**
+   * List message templates
+   *
+   * @param options - Optional filter options (name)
+   * @param businessAccountId - Optional WABA ID (overrides client config)
+   */
+  async list(
+    options?: ListTemplatesRequest,
+    businessAccountId?: string
+  ): Promise<ListTemplatesResponse> {
+    const client = this.getClient(businessAccountId);
+    return listTemplates(client, options);
+  }
+
+  /**
+   * Get a template by ID
+   *
+   * Note: This uses the template ID directly (no WABA prefix needed)
+   *
+   * @param templateId - Template ID
+   */
+  async get(templateId: string): Promise<TemplateResponse> {
+    return getTemplate(this.httpClient, templateId);
+  }
+
+  /**
+   * Update a template
+   *
+   * Note: This uses the template ID directly (no WABA prefix needed)
+   *
+   * @param templateId - Template ID
+   * @param request - Template update request
+   */
+  async update(
+    templateId: string,
+    request: UpdateTemplateRequest
+  ): Promise<UpdateTemplateResponse> {
+    return updateTemplate(this.httpClient, templateId, request);
+  }
+
+  /**
+   * Delete a template
+   *
+   * @param options - Delete options (name or hsm_id)
+   * @param businessAccountId - Optional WABA ID (overrides client config)
+   */
+  async delete(
+    options: DeleteTemplateRequest,
+    businessAccountId?: string
+  ): Promise<DeleteTemplateResponse> {
+    const client = this.getClient(businessAccountId);
+    return deleteTemplate(client, options);
+  }
+}

package/src/services/templates/index.ts

@@ -0,0 +1,3 @@
+export * from "./TemplatesService";
+export * from "./TemplatesClient";
+

package/src/services/templates/methods/create.ts

@@ -0,0 +1,27 @@
+import type { TemplatesClient } from "../TemplatesClient";
+import { createTemplateRequestSchema } from "../../../schemas/templates/request";
+import type { CreateTemplateRequest } from "../../../types/templates/request";
+import type { CreateTemplateResponse } from "../../../types/templates/response";
+import { transformZodError } from "../../../utils/zod-error";
+
+/**
+ * Create a message template
+ *
+ * @param templatesClient - Templates client with WABA ID baked in
+ * @param request - Template creation request
+ */
+export async function createTemplate(
+  templatesClient: TemplatesClient,
+  request: CreateTemplateRequest
+): Promise<CreateTemplateResponse> {
+  // Validate request with schema - throws WhatsAppValidationError if invalid
+  const result = createTemplateRequestSchema.safeParse(request);
+  if (!result.success) {
+    throw transformZodError(result.error);
+  }
+  const data = result.data;
+
+  // Make API request - templatesClient handles the WABA ID prefix automatically
+  return templatesClient.post<CreateTemplateResponse>("/message_templates", data);
+}
+

package/src/services/templates/methods/delete.ts

@@ -0,0 +1,38 @@
+import type { TemplatesClient } from "../TemplatesClient";
+import { deleteTemplateRequestSchema } from "../../../schemas/templates/request";
+import type { DeleteTemplateRequest } from "../../../types/templates/request";
+import type { DeleteTemplateResponse } from "../../../types/templates/response";
+import { transformZodError } from "../../../utils/zod-error";
+
+/**
+ * Delete a template
+ *
+ * @param templatesClient - Templates client with WABA ID baked in
+ * @param options - Delete options (name or hsm_id)
+ */
+export async function deleteTemplate(
+  templatesClient: TemplatesClient,
+  options: DeleteTemplateRequest
+): Promise<DeleteTemplateResponse> {
+  // Validate request with schema - throws WhatsAppValidationError if invalid
+  const result = deleteTemplateRequestSchema.safeParse(options);
+  if (!result.success) {
+    throw transformZodError(result.error);
+  }
+  const data = result.data;
+
+  // Build query string
+  const params = new URLSearchParams();
+  if (data.name) {
+    params.append("name", data.name);
+  }
+  if (data.hsm_id) {
+    params.append("hsm_id", data.hsm_id);
+  }
+  const queryString = params.toString();
+  const path = `/message_templates?${queryString}`;
+
+  // Make API request - templatesClient handles the WABA ID prefix automatically
+  return templatesClient.delete<DeleteTemplateResponse>(path);
+}
+

package/src/services/templates/methods/get.ts

@@ -0,0 +1,23 @@
+import type { HttpClient } from "../../../client/HttpClient";
+import type { TemplateResponse } from "../../../types/templates/response";
+
+/**
+ * Get a template by ID
+ *
+ * Note: This uses the template ID directly (no WABA prefix needed)
+ *
+ * @param httpClient - HTTP client
+ * @param templateId - Template ID
+ */
+export async function getTemplate(
+  httpClient: HttpClient,
+  templateId: string
+): Promise<TemplateResponse> {
+  if (!templateId || templateId.trim().length === 0) {
+    throw new Error("Template ID is required");
+  }
+
+  // Make API request - template ID is used directly, no WABA prefix
+  return httpClient.get<TemplateResponse>(`/${templateId}`);
+}
+

package/src/services/templates/methods/list.ts

@@ -0,0 +1,36 @@
+import type { TemplatesClient } from "../TemplatesClient";
+import { listTemplatesRequestSchema } from "../../../schemas/templates/request";
+import type { ListTemplatesRequest } from "../../../types/templates/request";
+import type { ListTemplatesResponse } from "../../../types/templates/response";
+import { transformZodError } from "../../../utils/zod-error";
+
+/**
+ * List message templates
+ *
+ * @param templatesClient - Templates client with WABA ID baked in
+ * @param options - Optional filter options (name)
+ */
+export async function listTemplates(
+  templatesClient: TemplatesClient,
+  options?: ListTemplatesRequest
+): Promise<ListTemplatesResponse> {
+  // Validate options if provided
+  if (options) {
+    const result = listTemplatesRequestSchema.safeParse(options);
+    if (!result.success) {
+      throw transformZodError(result.error);
+    }
+  }
+
+  // Build query string
+  const params = new URLSearchParams();
+  if (options?.name) {
+    params.append("name", options.name);
+  }
+  const queryString = params.toString();
+  const path = queryString ? `/message_templates?${queryString}` : "/message_templates";
+
+  // Make API request - templatesClient handles the WABA ID prefix automatically
+  return templatesClient.get<ListTemplatesResponse>(path);
+}
+

package/src/services/templates/methods/update.ts

@@ -0,0 +1,35 @@
+import type { HttpClient } from "../../../client/HttpClient";
+import { updateTemplateRequestSchema } from "../../../schemas/templates/request";
+import type { UpdateTemplateRequest } from "../../../types/templates/request";
+import type { UpdateTemplateResponse } from "../../../types/templates/response";
+import { transformZodError } from "../../../utils/zod-error";
+
+/**
+ * Update a template
+ *
+ * Note: This uses the template ID directly (no WABA prefix needed)
+ *
+ * @param httpClient - HTTP client
+ * @param templateId - Template ID
+ * @param request - Template update request
+ */
+export async function updateTemplate(
+  httpClient: HttpClient,
+  templateId: string,
+  request: UpdateTemplateRequest
+): Promise<UpdateTemplateResponse> {
+  if (!templateId || templateId.trim().length === 0) {
+    throw new Error("Template ID is required");
+  }
+
+  // Validate request with schema - throws WhatsAppValidationError if invalid
+  const result = updateTemplateRequestSchema.safeParse(request);
+  if (!result.success) {
+    throw transformZodError(result.error);
+  }
+  const data = result.data;
+
+  // Make API request - template ID is used directly, no WABA prefix
+  return httpClient.post<UpdateTemplateResponse>(`/${templateId}`, data);
+}
+

package/src/services/webhooks/WebhooksService.ts

@@ -0,0 +1,214 @@
+import type { HttpClient } from "../../client/HttpClient";
+import { extractMessages } from "./utils/extract-messages";
+import { extractStatuses } from "./utils/extract-statuses";
+import { verifyWebhook } from "./utils/verify";
+import { webhookPayloadSchema } from "../../schemas/webhooks/payload";
+import type {
+  WebhookPayload,
+  IncomingTextMessage,
+  IncomingMessage,
+} from "../../types/webhooks";
+
+/**
+ * Context provided to message handlers
+ * Contains metadata and contact info (message is passed separately)
+ */
+export type MessageContext = {
+  metadata: {
+    phoneNumberId: string;
+    displayPhoneNumber: string;
+    wabaId: string;
+  };
+  contact?: {
+    name: string;
+    waId: string;
+  };
+};
+
+/**
+ * Handler functions for different message types
+ * Receives message and context separately - message is the focus, context is optional metadata
+ */
+export type MessageHandlers = {
+  text?: (
+    message: IncomingTextMessage,
+    context: MessageContext
+  ) => Promise<void> | void;
+  // Future: image, audio, video, etc.
+};
+
+/**
+ * Options for handle() method
+ */
+export type HandleOptions = {
+  /**
+   * Error handler called when a message handler throws an error
+   * If not provided, errors are logged and processing continues
+   */
+  onError?: (error: Error, message: IncomingMessage) => void;
+};
+
+/**
+ * Webhooks service for handling incoming webhook payloads
+ *
+ * Provides utilities for extracting messages and a convenience handler
+ * for type-safe message processing.
+ */
+export class WebhooksService {
+  constructor(private readonly httpClient: HttpClient) {}
+
+  /**
+   * Verify webhook GET request from Meta
+   *
+   * Meta sends GET requests to verify webhook endpoints during setup.
+   * Returns the challenge string if valid, null if invalid.
+   *
+   * @param query - Query parameters from GET request
+   * @param verifyToken - Your verification token (stored on your server)
+   * @returns Challenge string if valid, null if invalid
+   */
+  verify(
+    query: {
+      "hub.mode"?: string;
+      "hub.verify_token"?: string;
+      "hub.challenge"?: string;
+    },
+    verifyToken: string
+  ): string | null {
+    return verifyWebhook(query, verifyToken);
+  }
+
+  /**
+   * Extract all incoming messages from webhook payload
+   *
+   * Low-level utility that flattens the nested webhook structure
+   * and returns messages directly.
+   *
+   * @param payload - Webhook payload from Meta
+   * @returns Flat array of incoming messages
+   */
+  extractMessages(payload: WebhookPayload): IncomingMessage[] {
+    return extractMessages(payload);
+  }
+
+  /**
+   * Extract status updates from webhook payload
+   *
+   * Low-level utility for extracting status updates for outgoing messages.
+   *
+   * @param payload - Webhook payload from Meta
+   * @returns Flat array of status updates
+   */
+  extractStatuses(payload: WebhookPayload): unknown[] {
+    return extractStatuses(payload);
+  }
+
+  /**
+   * Validate webhook payload structure
+   *
+   * Validates the payload against the schema. Logs errors if malformed
+   * but doesn't throw, allowing processing to continue.
+   *
+   * @param payload - Raw payload to validate
+   * @returns Validated payload if valid, original payload if invalid (with logged error)
+   */
+  private validatePayload(payload: unknown): WebhookPayload {
+    const result = webhookPayloadSchema.safeParse(payload);
+    if (!result.success) {
+      console.error(
+        "Webhook payload validation failed:",
+        result.error.format()
+      );
+      // Return as-is (TypeScript will treat it as WebhookPayload, but it's actually invalid)
+      // This allows processing to continue, but handlers should be defensive
+      return payload as WebhookPayload;
+    }
+    return result.data;
+  }
+
+  /**
+   * Handle webhook payload with type-safe callbacks
+   *
+   * High-level convenience method that extracts messages and dispatches
+   * them to appropriate handlers based on message type.
+   *
+   * **Important**: This method returns quickly to allow fast webhook responses.
+   * Handlers are processed asynchronously. If you need to await handler completion,
+   * use the low-level `extractMessages()` method instead.
+   *
+   * @param payload - Webhook payload from Meta (will be validated)
+   * @param handlers - Object with handler functions for each message type
+   * @param options - Optional error handling configuration
+   */
+  handle(
+    payload: unknown,
+    handlers: MessageHandlers,
+    options?: HandleOptions
+  ): void {
+    // Validate payload (logs error if malformed, but continues)
+    const validatedPayload = this.validatePayload(payload);
+
+    // Extract metadata and contacts from payload for context
+    for (const entry of validatedPayload.entry) {
+      for (const change of entry.changes) {
+        if (change.field === "messages" && change.value.messages) {
+          const metadata = {
+            phoneNumberId: change.value.metadata.phone_number_id,
+            displayPhoneNumber: change.value.metadata.display_phone_number,
+            wabaId: entry.id,
+          };
+
+          const contacts = change.value.contacts || [];
+
+          // Process each message with its context
+          for (const message of change.value.messages) {
+            // Find contact for this message (match by wa_id)
+            const contact = contacts.find((c) => c.wa_id === message.from);
+
+            // Build context (metadata + contact, no message duplication)
+            const context: MessageContext = {
+              metadata,
+              ...(contact && {
+                contact: {
+                  name: contact.profile.name,
+                  waId: contact.wa_id,
+                },
+              }),
+            };
+
+            // Process handler asynchronously (don't await)
+            // This allows long-running handlers without blocking webhook response
+            Promise.resolve()
+              .then(async () => {
+                // Type-safe dispatch based on message type
+                switch (message.type) {
+                  case "text":
+                    if (handlers.text) {
+                      await handlers.text(message, context);
+                    }
+                    break;
+
+                  // Future: image, audio, video, etc.
+                  default:
+                    // Unhandled message type - silently continue
+                    break;
+                }
+              })
+              .catch((error) => {
+                // Handle errors in handler execution
+                if (options?.onError) {
+                  options.onError(error as Error, message);
+                } else {
+                  // Default: log and continue (don't break webhook response)
+                  console.error(
+                    `Error handling ${message.type} message ${message.id}:`,
+                    error
+                  );
+                }
+              });
+          }
+        }
+      }
+    }
+  }
+}

package/src/services/webhooks/index.ts

@@ -0,0 +1,3 @@
+export * from "./WebhooksService";
+export type { MessageContext, MessageHandlers, HandleOptions } from "./WebhooksService";
+

package/src/services/webhooks/utils/extract-messages.ts

@@ -0,0 +1,25 @@
+import type { WebhookPayload } from "../../../types/webhooks";
+import type { IncomingMessage } from "../../../types/webhooks/incoming-message";
+
+/**
+ * Extract all incoming messages from webhook payload
+ *
+ * Flattens the nested structure: entry[].changes[].value.messages[]
+ * Returns a flat array of messages directly
+ *
+ * @param payload - Webhook payload from Meta
+ * @returns Flat array of incoming messages
+ */
+export function extractMessages(payload: WebhookPayload): IncomingMessage[] {
+  const messages: IncomingMessage[] = [];
+
+  for (const entry of payload.entry) {
+    for (const change of entry.changes) {
+      if (change.field === "messages" && change.value.messages) {
+        messages.push(...change.value.messages);
+      }
+    }
+  }
+
+  return messages;
+}