whatsapp-cloud 0.0.3 → 0.0.5

package/src/schemas/messages/response.ts

@@ -0,0 +1,19 @@
+import { z } from "zod";
+
+/**
+ * Schema for message response
+ */
+export const messageResponseSchema = z.object({
+  messaging_product: z.literal("whatsapp"),
+  contacts: z.array(
+    z.object({
+      input: z.string(),
+      wa_id: z.string(),
+    })
+  ),
+  messages: z.array(
+    z.object({
+      id: z.string(),
+    })
+  ),
+});

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/services/accounts/AccountsClient.ts

@@ -0,0 +1,34 @@
+import type { HttpClient } from "../../client/HttpClient";
+
+/**
+ * Accounts client - wraps HttpClient with WABA ID as base endpoint
+ *
+ * This client automatically prepends `/${businessAccountId}` to all request paths.
+ */
+export class AccountsClient {
+  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 PATCH request with WABA ID prefix
+   */
+  async patch<T>(path: string, body: unknown): Promise<T> {
+    return this.httpClient.patch<T>(`/${this.businessAccountId}${path}`, body);
+  }
+}

package/src/services/accounts/AccountsService.ts

@@ -0,0 +1,45 @@
+import type { HttpClient } from "../../client/HttpClient";
+import { AccountsClient } from "./AccountsClient";
+import { listPhoneNumbers } from "./methods/list-phone-numbers";
+import { WhatsAppValidationError } from "../../errors";
+import type { PhoneNumberListResponse } from "../../types/accounts/phone-number";
+
+/**
+ * Accounts service for managing WhatsApp Business Accounts
+ *
+ * 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 {
+  constructor(private readonly httpClient: HttpClient) {}
+
+  /**
+   * 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) is required. Provide it in WhatsAppClient config or as a parameter.",
+        "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(
+    businessAccountId?: string
+  ): Promise<PhoneNumberListResponse> {
+    const client = this.getClient(businessAccountId);
+    return listPhoneNumbers(client);
+  }
+}

package/src/services/accounts/index.ts

@@ -0,0 +1,2 @@
+export { AccountsService } from "./AccountsService";
+export type { PhoneNumberListResponse } from "../../types/accounts/phone-number";

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

@@ -0,0 +1,15 @@
+import type { AccountsClient } from "../AccountsClient";
+import type { PhoneNumberListResponse } from "../../../types/accounts/phone-number";
+
+/**
+ * List phone numbers for a WhatsApp Business Account
+ *
+ * @param accountsClient - Scoped accounts client
+ * @returns List of phone numbers associated with the WABA
+ */
+export async function listPhoneNumbers(
+  accountsClient: AccountsClient
+): Promise<PhoneNumberListResponse> {
+  // Make API request - accountsClient handles the WABA ID prefix automatically
+  return accountsClient.get<PhoneNumberListResponse>("/phone_numbers");
+}

package/src/services/business/BusinessClient.ts

@@ -0,0 +1,34 @@
+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.
+ */
+export class BusinessClient {
+  constructor(
+    private readonly httpClient: HttpClient,
+    private readonly businessId: string
+  ) {}
+
+  /**
+   * Make a GET request with Business Portfolio ID prefix
+   */
+  async get<T>(path: string): Promise<T> {
+    return this.httpClient.get<T>(`/${this.businessId}${path}`);
+  }
+
+  /**
+   * Make a POST request with Business Portfolio ID prefix
+   */
+  async post<T>(path: string, body: unknown): Promise<T> {
+    return this.httpClient.post<T>(`/${this.businessId}${path}`, body);
+  }
+
+  /**
+   * Make a PATCH request with Business Portfolio ID prefix
+   */
+  async patch<T>(path: string, body: unknown): Promise<T> {
+    return this.httpClient.patch<T>(`/${this.businessId}${path}`, body);
+  }
+}

package/src/services/business/BusinessService.ts

@@ -0,0 +1,45 @@
+import type { HttpClient } from "../../client/HttpClient";
+import { BusinessClient } from "./BusinessClient";
+import { listAccounts } from "./methods/list-accounts";
+import { WhatsAppValidationError } from "../../errors";
+import type { BusinessAccountsListResponse } from "../../types/business/account";
+
+/**
+ * Business service for managing Business Portfolios
+ *
+ * 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 {
+  constructor(private readonly httpClient: HttpClient) {}
+
+  /**
+   * 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. Provide it in WhatsAppClient config or as a parameter.",
+        "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(
+    businessId?: string
+  ): Promise<BusinessAccountsListResponse> {
+    const client = this.getClient(businessId);
+    return listAccounts(client);
+  }
+}

package/src/services/business/index.ts

@@ -0,0 +1,3 @@
+export { BusinessService } from "./BusinessService";
+export type { BusinessAccountsListResponse } from "../../types/business/account";
+

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

@@ -0,0 +1,17 @@
+import type { BusinessClient } from "../BusinessClient";
+import type { BusinessAccountsListResponse } from "../../../types/business/account";
+
+/**
+ * List WhatsApp Business Accounts (WABAs) for a Business Portfolio
+ *
+ * @param businessClient - Scoped business client
+ * @returns List of WABAs associated with the Business Portfolio
+ */
+export async function listAccounts(
+  businessClient: BusinessClient
+): Promise<BusinessAccountsListResponse> {
+  // Make API request - businessClient handles the Business Portfolio ID prefix automatically
+  return businessClient.get<BusinessAccountsListResponse>(
+    "/whatsapp_business_accounts"
+  );
+}

package/src/services/index.ts

@@ -0,0 +1,2 @@
+export * from "./messages/index";
+export * from "./accounts/index";

package/src/services/messages/MessagesClient.ts

@@ -0,0 +1,34 @@
+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.
+ */
+export class MessagesClient {
+  constructor(
+    private readonly httpClient: HttpClient,
+    private readonly phoneNumberId: string
+  ) {}
+
+  /**
+   * Make a POST request with phone number ID prefix
+   */
+  async post<T>(path: string, body: unknown): Promise<T> {
+    return this.httpClient.post<T>(`/${this.phoneNumberId}${path}`, body);
+  }
+
+  /**
+   * Make a GET request with phone number ID prefix
+   */
+  async get<T>(path: string): Promise<T> {
+    return this.httpClient.get<T>(`/${this.phoneNumberId}${path}`);
+  }
+
+  /**
+   * Make a PATCH request with phone number ID prefix
+   */
+  async patch<T>(path: string, body: unknown): Promise<T> {
+    return this.httpClient.patch<T>(`/${this.phoneNumberId}${path}`, body);
+  }
+}

package/src/services/messages/MessagesService.ts

@@ -0,0 +1,97 @@
+import { HttpClient } from "../../client/HttpClient";
+import { sendText } from "./methods/send-text";
+import { sendImage } from "./methods/send-image";
+import { sendLocation } from "./methods/send-location";
+import { sendReaction } from "./methods/send-reaction";
+import { MessagesClient } from "./MessagesClient";
+import { WhatsAppValidationError } from "../../errors";
+import type {
+  SendTextRequest,
+  SendImageRequest,
+  SendLocationRequest,
+  SendReactionRequest,
+} from "../../types/messages/request";
+import type { MessageResponse } from "../../types/messages/response";
+
+/**
+ * Messages service for sending WhatsApp messages
+ *
+ * This service handles message operations.
+ * It supports both a globally configured phoneNumberId (in WhatsAppClient)
+ * and per-request phoneNumberId overrides.
+ */
+export class MessagesService {
+  constructor(private readonly httpClient: HttpClient) {}
+
+  /**
+   * 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. Provide it in WhatsAppClient config or as a parameter.",
+        "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,
+    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,
+    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,
+    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,
+    phoneNumberId?: string
+  ): Promise<MessageResponse> {
+    const client = this.getClient(phoneNumberId);
+    return sendReaction(client, request);
+  }
+}

package/src/services/messages/index.ts

@@ -0,0 +1,8 @@
+export { MessagesService } from "./MessagesService";
+export type {
+  SendTextRequest,
+  SendImageRequest,
+  SendLocationRequest,
+  SendReactionRequest,
+} from "../../types/messages/request";
+export type { MessageResponse } from "../../types/messages/response";