whatsapp-cloud 0.0.4 → 0.0.6

package/src/schemas/client.ts

@@ -44,7 +44,7 @@ export const clientConfigSchema = z.object({
     .refine((val) => val === undefined || val.trim().length > 0, {
       message: "businessId cannot be empty or whitespace only",
     }),
-  apiVersion: z.string().default("v18.0"),
-  baseURL: z.string().url().default("https://graph.facebook.com"),
+  apiVersion: z.string().default("v18.0").optional(),
+  baseURL: z.string().url().default("https://graph.facebook.com").optional(),
   timeout: z.number().positive().optional(),
 });

package/src/schemas/index.ts

@@ -2,4 +2,6 @@ export * from "./client";
 export * from "./messages/index";
 export * from "./accounts/index";
 export * from "./business/index";
+export * from "./templates/index";
+export * from "./webhooks/index";
 export * from "./debug";

package/src/schemas/templates/component.ts

@@ -0,0 +1,145 @@
+import { z } from "zod";
+
+/**
+ * Button schemas for template components
+ * Simplified version without variables for now
+ */
+
+/**
+ * Quick reply button schema
+ */
+export const quickReplyButtonSchema = z.object({
+  type: z.literal("QUICK_REPLY"),
+  text: z.string().min(1).max(25, "Button text must be 25 characters or less"),
+});
+
+/**
+ * URL button schema
+ * Note: example field will be added later when we support variables
+ */
+export const urlButtonSchema = z.object({
+  type: z.literal("URL"),
+  text: z.string().min(1).max(25, "Button text must be 25 characters or less"),
+  url: z.string().url().max(2000, "URL must be 2000 characters or less"),
+  // example: z.array(z.string()).optional(), // For later: when URL contains variables
+});
+
+/**
+ * Phone number button schema
+ */
+export const phoneNumberButtonSchema = z.object({
+  type: z.literal("PHONE_NUMBER"),
+  text: z.string().min(1).max(25, "Button text must be 25 characters or less"),
+  phone_number: z
+    .string()
+    .min(1)
+    .max(20, "Phone number must be 20 characters or less"),
+});
+
+/**
+ * Copy code button schema
+ * Note: example field will be added later
+ */
+export const copyCodeButtonSchema = z.object({
+  type: z.literal("COPY_CODE"),
+  // example: z.string().max(15).optional(), // For later: example value to copy
+});
+
+/**
+ * Flow button schema (for authentication templates)
+ * Note: Will be expanded later when we support flow templates
+ */
+export const flowButtonSchema = z.object({
+  type: z.literal("FLOW"),
+  text: z.string().min(1).max(25, "Button text must be 25 characters or less"),
+  flow_action: z.string().optional(),
+  flow_id: z.string().optional(),
+  navigate_screen: z.string().optional(),
+});
+
+/**
+ * Union of all button types
+ */
+export const buttonSchema = z.discriminatedUnion("type", [
+  quickReplyButtonSchema,
+  urlButtonSchema,
+  phoneNumberButtonSchema,
+  copyCodeButtonSchema,
+  flowButtonSchema,
+]);
+
+/**
+ * Header component schema
+ * Simplified - no variables/examples for now
+ *
+ * Note:
+ * - TEXT format requires text field
+ * - IMAGE/VIDEO/DOCUMENT formats require example.header_handle (for later)
+ * - LOCATION format requires neither text nor example
+ */
+export const headerComponentSchema = z
+  .object({
+    type: z.literal("HEADER"),
+    format: z.enum(["TEXT", "IMAGE", "VIDEO", "DOCUMENT", "LOCATION"]),
+    text: z
+      .string()
+      .max(60, "Header text must be 60 characters or less")
+      .optional(),
+    // example: z.object({...}).optional(), // For later: when using variables or media
+  })
+  .refine(
+    (data) => {
+      // TEXT format requires text
+      if (data.format === "TEXT" && !data.text) {
+        return false;
+      }
+      // LOCATION format doesn't need text
+      if (data.format === "LOCATION") {
+        return true;
+      }
+      // IMAGE/VIDEO/DOCUMENT will need example.header_handle (for later)
+      return true;
+    },
+    {
+      message: "TEXT format header requires text field",
+    }
+  );
+
+/**
+ * Body component schema
+ * Required component - no variables for now
+ */
+export const bodyComponentSchema = z.object({
+  type: z.literal("BODY"),
+  text: z
+    .string()
+    .min(1)
+    .max(1024, "Body text must be 1024 characters or less"),
+  // example: z.object({...}).optional(), // For later: when using variables
+});
+
+/**
+ * Footer component schema
+ */
+export const footerComponentSchema = z.object({
+  type: z.literal("FOOTER"),
+  text: z.string().min(1).max(60, "Footer text must be 60 characters or less"),
+});
+
+/**
+ * Buttons component schema
+ */
+export const buttonsComponentSchema = z.object({
+  type: z.literal("BUTTONS"),
+  buttons: z.array(buttonSchema).min(1).max(10, "Maximum 10 buttons allowed"),
+});
+
+/**
+ * Union of all component types
+ */
+export const componentSchema = z.discriminatedUnion("type", [
+  headerComponentSchema,
+  bodyComponentSchema,
+  footerComponentSchema,
+  buttonsComponentSchema,
+]);

package/src/schemas/templates/index.ts

@@ -0,0 +1,4 @@
+export * from "./component";
+export * from "./request";
+export * from "./response";
+

package/src/schemas/templates/request.ts

@@ -0,0 +1,78 @@
+import { z } from "zod";
+import { componentSchema } from "./component";
+
+/**
+ * Schema for creating a template
+ * Simplified - no variables/examples for now
+ */
+export const createTemplateRequestSchema = z.object({
+  name: z.string().min(1).max(512, "Template name must be 512 characters or less"),
+  language: z.string().min(2).max(5, "Language code must be 2-5 characters (e.g., 'en' or 'en_US')"),
+  category: z.enum(["AUTHENTICATION", "MARKETING", "UTILITY"]),
+  components: z
+    .array(componentSchema)
+    .min(1, "At least one component is required")
+    .refine(
+      (components) => {
+        // Body component is required
+        return components.some((c) => c.type === "BODY");
+      },
+      { message: "BODY component is required" }
+    )
+    .refine(
+      (components) => {
+        // Only one header allowed
+        const headers = components.filter((c) => c.type === "HEADER");
+        return headers.length <= 1;
+      },
+      { message: "Only one HEADER component is allowed" }
+    )
+    .refine(
+      (components) => {
+        // Only one footer allowed
+        const footers = components.filter((c) => c.type === "FOOTER");
+        return footers.length <= 1;
+      },
+      { message: "Only one FOOTER component is allowed" }
+    )
+    .refine(
+      (components) => {
+        // Only one buttons component allowed
+        const buttons = components.filter((c) => c.type === "BUTTONS");
+        return buttons.length <= 1;
+      },
+      { message: "Only one BUTTONS component is allowed" }
+    ),
+});
+
+/**
+ * Schema for updating a template
+ * All fields optional - only update what's provided
+ */
+export const updateTemplateRequestSchema = z.object({
+  category: z.enum(["AUTHENTICATION", "MARKETING", "UTILITY"]).optional(),
+  components: z.array(componentSchema).optional(),
+  language: z.string().min(2).max(5).optional(),
+  name: z.string().min(1).max(512).optional(),
+});
+
+/**
+ * Schema for listing templates
+ */
+export const listTemplatesRequestSchema = z.object({
+  name: z.string().optional(), // Filter by template name
+});
+
+/**
+ * Schema for deleting a template
+ * Either name or hsm_id must be provided
+ */
+export const deleteTemplateRequestSchema = z
+  .object({
+    name: z.string().optional(),
+    hsm_id: z.string().optional(),
+  })
+  .refine((data) => data.name || data.hsm_id, {
+    message: "Either name or hsm_id must be provided",
+  });
+

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/schemas/webhooks/incoming-message.ts

@@ -0,0 +1,38 @@
+import { z } from "zod";
+
+/**
+ * Base fields present in ALL incoming messages
+ */
+const baseIncomingMessageSchema = z.object({
+  from: z.string(), // WhatsApp ID (phone number without +)
+  id: z.string(), // Message ID (wamid.*)
+  timestamp: z.string(), // Unix timestamp as string
+  type: z.string(), // Message type discriminator
+});
+
+/**
+ * Text content in incoming text messages
+ * Note: Incoming messages don't have preview_url like outgoing
+ */
+const incomingTextContentSchema = z.object({
+  body: z.string(),
+});
+
+/**
+ * Incoming text message schema
+ * Uses discriminated union pattern (type: "text")
+ */
+export const incomingTextMessageSchema = baseIncomingMessageSchema.extend({
+  type: z.literal("text"),
+  text: incomingTextContentSchema,
+});
+
+/**
+ * Union of all incoming message types
+ * For now: just text. Others (image, audio, etc.) will be added later
+ */
+export const incomingMessageSchema = z.discriminatedUnion("type", [
+  incomingTextMessageSchema,
+  // Future: incomingImageMessageSchema, incomingAudioMessageSchema, etc.
+]);
+

package/src/schemas/webhooks/index.ts

@@ -0,0 +1,3 @@
+export * from "./incoming-message";
+export * from "./payload";
+

package/src/schemas/webhooks/payload.ts

@@ -0,0 +1,56 @@
+import { z } from "zod";
+import { incomingMessageSchema } from "./incoming-message";
+
+/**
+ * Contact information in webhook
+ */
+const contactSchema = z.object({
+  profile: z.object({
+    name: z.string(),
+  }),
+  wa_id: z.string(),
+});
+
+/**
+ * Metadata in webhook value
+ */
+const webhookMetadataSchema = z.object({
+  display_phone_number: z.string(),
+  phone_number_id: z.string(),
+});
+
+/**
+ * Webhook value (the actual data)
+ */
+const webhookValueSchema = z.object({
+  messaging_product: z.literal("whatsapp"),
+  metadata: webhookMetadataSchema,
+  contacts: z.array(contactSchema).optional(),
+  messages: z.array(incomingMessageSchema).optional(), // Incoming messages
+  statuses: z.array(z.any()).optional(), // Status updates (for later)
+});
+
+/**
+ * Webhook change entry
+ */
+const webhookChangeSchema = z.object({
+  value: webhookValueSchema,
+  field: z.literal("messages"), // For now: only messages field
+});
+
+/**
+ * Webhook entry
+ */
+const webhookEntrySchema = z.object({
+  id: z.string(), // WABA ID
+  changes: z.array(webhookChangeSchema),
+});
+
+/**
+ * Full webhook payload schema
+ */
+export const webhookPayloadSchema = z.object({
+  object: z.literal("whatsapp_business_account"),
+  entry: z.array(webhookEntrySchema),
+});
+

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(