whatsapp-cloud 0.0.4 → 0.0.5

package/src/schemas/templates/response.ts

@@ -0,0 +1,64 @@
+import { z } from "zod";
+import { componentSchema } from "./component";
+
+/**
+ * Schema for template response (single template)
+ */
+export const templateResponseSchema = z.object({
+  id: z.string(),
+  name: z.string(),
+  language: z.string(),
+  status: z.string(),
+  category: z.string(),
+  components: z.array(componentSchema),
+});
+
+/**
+ * Schema for create template response
+ */
+export const createTemplateResponseSchema = z.object({
+  id: z.string(),
+  status: z.string(),
+  category: z.string(),
+});
+
+/**
+ * Schema for list templates response
+ */
+export const templateListItemSchema = z.object({
+  id: z.string(),
+  name: z.string(),
+  language: z.string(),
+  status: z.string(),
+  category: z.string(),
+  components: z.array(componentSchema),
+});
+
+export const listTemplatesResponseSchema = z.object({
+  data: z.array(templateListItemSchema),
+  paging: z
+    .object({
+      cursors: z
+        .object({
+          before: z.string().optional(),
+          after: z.string().optional(),
+        })
+        .optional(),
+    })
+    .optional(),
+});
+
+/**
+ * Schema for update template response
+ */
+export const updateTemplateResponseSchema = z.object({
+  success: z.boolean(),
+});
+
+/**
+ * Schema for delete template response
+ */
+export const deleteTemplateResponseSchema = z.object({
+  success: z.boolean(),
+});
+

package/src/services/accounts/AccountsClient.ts

@@ -1,42 +1,34 @@
 import type { HttpClient } from "../../client/HttpClient";
 
 /**
- * Accounts client - wraps HttpClient with WABA ID (WhatsApp Business Account ID) as base endpoint
+ * Accounts client - wraps HttpClient with WABA ID as base endpoint
  *
- * This client automatically prepends `/${wabaId}` to all request paths,
- * so methods can use relative paths like `/phone_numbers` instead of `/${wabaId}/phone_numbers`.
- *
- * Note: The wabaId is the WhatsApp Business Account ID (not the Business Portfolio ID).
- * This is used in endpoints like GET /<WABA_ID>/phone_numbers.
- *
- * This treats wabaId as a "client" for the accounts namespace - different
- * wabaIds represent different WhatsApp Business Account endpoints.
+ * This client automatically prepends `/${businessAccountId}` to all request paths.
  */
 export class AccountsClient {
   constructor(
     private readonly httpClient: HttpClient,
-    private readonly wabaId: string
+    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.wabaId}${path}`);
+    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.wabaId}${path}`, body);
+    return this.httpClient.post<T>(`/${this.businessAccountId}${path}`, body);
   }
 
   /**
    * Make a PATCH request with WABA ID prefix
    */
   async patch<T>(path: string, body: unknown): Promise<T> {
-    return this.httpClient.patch<T>(`/${this.wabaId}${path}`, body);
+    return this.httpClient.patch<T>(`/${this.businessAccountId}${path}`, body);
   }
 }
-

package/src/services/accounts/AccountsService.ts

@@ -7,41 +7,39 @@ import type { PhoneNumberListResponse } from "../../types/accounts/phone-number"
 /**
  * Accounts service for managing WhatsApp Business Accounts
  *
- * The service validates that businessAccountId (WABA ID - WhatsApp Business Account ID) is set
- * at the client level and creates an AccountsClient instance.
- *
- * Note: businessAccountId in the client config represents the WABA ID, not the Business Portfolio ID.
- * The WABA ID is used in endpoints like GET /<WABA_ID>/phone_numbers.
- *
- * AccountsClient treats wabaId as a "client" for the accounts namespace - different
- * wabaIds represent different WhatsApp Business Account endpoints.
+ * This service handles WABA operations like listing phone numbers.
+ * It supports both a globally configured businessAccountId (in WhatsAppClient)
+ * and per-request businessAccountId overrides.
  */
 export class AccountsService {
-  private readonly accountsClient: AccountsClient;
+  constructor(private readonly httpClient: HttpClient) {}
 
-  constructor(httpClient: HttpClient) {
-    // Validate that businessAccountId (WABA ID) is set at client level
-    // This is the WhatsApp Business Account ID, not the Business Portfolio ID
-    if (!httpClient.businessAccountId) {
+  /**
+   * Helper to create a Scoped Client (prefer override, fallback to config)
+   */
+  private getClient(overrideId?: string): AccountsClient {
+    const id = overrideId || this.httpClient.businessAccountId;
+    if (!id) {
       throw new WhatsAppValidationError(
-        "businessAccountId (WABA ID - WhatsApp Business Account ID) is required for AccountsService. Provide it in WhatsAppClient config.",
+        "businessAccountId (WABA ID) is required. Provide it in WhatsAppClient config or as a parameter.",
         "businessAccountId"
       );
     }
 
-    // Create accounts client with WABA ID baked in
-    this.accountsClient = new AccountsClient(
-      httpClient,
-      httpClient.businessAccountId
-    );
+    // Just wrap the existing httpClient
+    return new AccountsClient(this.httpClient, id);
   }
 
   /**
    * List phone numbers for a WhatsApp Business Account
    *
+   * @param businessAccountId - Optional WABA ID (overrides client config)
    * @returns List of phone numbers associated with the WABA
    */
-  async listPhoneNumbers(): Promise<PhoneNumberListResponse> {
-    return listPhoneNumbers(this.accountsClient);
+  async listPhoneNumbers(
+    businessAccountId?: string
+  ): Promise<PhoneNumberListResponse> {
+    const client = this.getClient(businessAccountId);
+    return listPhoneNumbers(client);
   }
 }

package/src/services/accounts/methods/list-phone-numbers.ts

@@ -4,7 +4,7 @@ import type { PhoneNumberListResponse } from "../../../types/accounts/phone-numb
 /**
  * List phone numbers for a WhatsApp Business Account
  *
- * @param accountsClient - Accounts client with WABA ID baked in
+ * @param accountsClient - Scoped accounts client
  * @returns List of phone numbers associated with the WABA
  */
 export async function listPhoneNumbers(
@@ -13,4 +13,3 @@ export async function listPhoneNumbers(
   // Make API request - accountsClient handles the WABA ID prefix automatically
   return accountsClient.get<PhoneNumberListResponse>("/phone_numbers");
 }
-

package/src/services/business/BusinessClient.ts

@@ -3,14 +3,7 @@ import type { HttpClient } from "../../client/HttpClient";
 /**
  * Business client - wraps HttpClient with Business Portfolio ID as base endpoint
  *
- * This client automatically prepends `/${businessId}` to all request paths,
- * so methods can use relative paths like `/whatsapp_business_accounts` instead of `/${businessId}/whatsapp_business_accounts`.
- *
- * Note: The businessId is the Business Portfolio ID (not the WABA ID).
- * This is used in endpoints like GET /<Business-ID>/whatsapp_business_accounts.
- *
- * This treats businessId as a "client" for the business namespace - different
- * businessIds represent different Business Portfolio endpoints.
+ * This client automatically prepends `/${businessId}` to all request paths.
  */
 export class BusinessClient {
   constructor(
@@ -39,4 +32,3 @@ export class BusinessClient {
     return this.httpClient.patch<T>(`/${this.businessId}${path}`, body);
   }
 }
-

package/src/services/business/BusinessService.ts

@@ -7,41 +7,39 @@ import type { BusinessAccountsListResponse } from "../../types/business/account"
 /**
  * Business service for managing Business Portfolios
  *
- * The service validates that businessId (Business Portfolio ID) is set at the client level
- * and creates a BusinessClient instance.
- *
- * Note: businessId in the client config represents the Business Portfolio ID.
- * The Business Portfolio ID is used in endpoints like GET /<Business-ID>/whatsapp_business_accounts.
- *
- * BusinessClient treats businessId as a "client" for the business namespace - different
- * businessIds represent different Business Portfolio endpoints.
+ * This service handles Business Portfolio operations like listing WABAs.
+ * It supports both a globally configured businessId (in WhatsAppClient)
+ * and per-request businessId overrides.
  */
 export class BusinessService {
-  private readonly businessClient: BusinessClient;
+  constructor(private readonly httpClient: HttpClient) {}
 
-  constructor(httpClient: HttpClient) {
-    // Validate that businessId (Business Portfolio ID) is set at client level
-    if (!httpClient.businessId) {
+  /**
+   * Helper to create a Scoped Client (prefer override, fallback to config)
+   */
+  private getClient(overrideId?: string): BusinessClient {
+    const id = overrideId || this.httpClient.businessId;
+    if (!id) {
       throw new WhatsAppValidationError(
-        "businessId (Business Portfolio ID) is required for BusinessService. Provide it in WhatsAppClient config.",
+        "businessId (Business Portfolio ID) is required. Provide it in WhatsAppClient config or as a parameter.",
         "businessId"
       );
     }
 
-    // Create business client with Business Portfolio ID baked in
-    this.businessClient = new BusinessClient(
-      httpClient,
-      httpClient.businessId
-    );
+    // Just wrap the existing httpClient
+    return new BusinessClient(this.httpClient, id);
   }
 
   /**
    * List WhatsApp Business Accounts (WABAs) for a Business Portfolio
    *
+   * @param businessId - Optional Business Portfolio ID (overrides client config)
    * @returns List of WABAs associated with the Business Portfolio
    */
-  async listAccounts(): Promise<BusinessAccountsListResponse> {
-    return listAccounts(this.businessClient);
+  async listAccounts(
+    businessId?: string
+  ): Promise<BusinessAccountsListResponse> {
+    const client = this.getClient(businessId);
+    return listAccounts(client);
   }
 }
-

package/src/services/business/methods/list-accounts.ts

@@ -4,7 +4,7 @@ import type { BusinessAccountsListResponse } from "../../../types/business/accou
 /**
  * List WhatsApp Business Accounts (WABAs) for a Business Portfolio
  *
- * @param businessClient - Business client with Business Portfolio ID baked in
+ * @param businessClient - Scoped business client
  * @returns List of WABAs associated with the Business Portfolio
  */
 export async function listAccounts(
@@ -15,4 +15,3 @@ export async function listAccounts(
     "/whatsapp_business_accounts"
   );
 }
-

package/src/services/messages/MessagesClient.ts

@@ -2,12 +2,8 @@ import type { HttpClient } from "../../client/HttpClient";
 
 /**
  * Messages client - wraps HttpClient with phone number ID as base endpoint
- *
- * This client automatically prepends `/${phoneNumberId}` to all request paths,
- * so methods can use relative paths like `/messages` instead of `/${phoneNumberId}/messages`.
- *
- * This treats phoneNumberId as a "client" for the messaging namespace - different
- * phoneNumberIds represent different messaging endpoints.
+ * 
+ * This client automatically prepends `/${phoneNumberId}` to all request paths.
  */
 export class MessagesClient {
   constructor(

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}`);
+}
+