whatsapp-cloud 0.0.3 → 0.0.4

package/src/schemas/business/index.ts

@@ -0,0 +1,2 @@
+export * from "./account";
+

package/src/schemas/client.ts

@@ -0,0 +1,50 @@
+import { z } from "zod";
+
+/**
+ * Helper message for access token errors
+ */
+const ACCESS_TOKEN_HELP_MESSAGE =
+  "Get your access token from Meta for Developers: https://developers.facebook.com/docs/whatsapp/cloud-api/get-started";
+
+/**
+ * Schema for access token with validation and helpful error messages
+ */
+const accessTokenSchema = z
+  .string({
+    message: `accessToken is required. ${ACCESS_TOKEN_HELP_MESSAGE}`,
+  })
+  .min(1, {
+    message: `accessToken cannot be empty. ${ACCESS_TOKEN_HELP_MESSAGE}`,
+  })
+  .trim()
+  .refine((val) => val.length > 0, {
+    message: `accessToken cannot be whitespace only. ${ACCESS_TOKEN_HELP_MESSAGE}`,
+  });
+
+/**
+ * Client configuration schema
+ */
+export const clientConfigSchema = z.object({
+  accessToken: accessTokenSchema,
+  phoneNumberId: z
+    .string()
+    .optional()
+    .refine((val) => val === undefined || val.trim().length > 0, {
+      message: "phoneNumberId cannot be empty or whitespace only",
+    }),
+  businessAccountId: z
+    .string()
+    .optional()
+    .refine((val) => val === undefined || val.trim().length > 0, {
+      message: "businessAccountId cannot be empty or whitespace only",
+    }),
+  businessId: z
+    .string()
+    .optional()
+    .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"),
+  timeout: z.number().positive().optional(),
+});

package/src/schemas/debug.ts

@@ -0,0 +1,25 @@
+import { z } from "zod";
+
+/**
+ * Schema for debug token response
+ * Matches Graph API debug_token endpoint response structure
+ */
+export const debugTokenResponseSchema = z.object({
+  data: z.object({
+    app_id: z.string().optional(),
+    type: z.string().optional(),
+    application: z.string().optional(),
+    data_access_expires_at: z.number().optional(),
+    expires_at: z.number().optional(),
+    is_valid: z.boolean().optional(),
+    issued_at: z.number().optional(),
+    metadata: z
+      .object({
+        auth_type: z.string().optional(),
+        sso: z.string().optional(),
+      })
+      .optional(),
+    scopes: z.array(z.string()).optional(),
+    user_id: z.string().optional(),
+  }),
+});

package/src/schemas/index.ts

@@ -0,0 +1,5 @@
+export * from "./client";
+export * from "./messages/index";
+export * from "./accounts/index";
+export * from "./business/index";
+export * from "./debug";

package/src/schemas/messages/index.ts

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

package/src/schemas/messages/request.ts

@@ -0,0 +1,82 @@
+import { z } from "zod";
+
+/**
+ * Base schema for all message requests
+ * phoneNumberId is handled at the client level, not in the request object
+ */
+const baseMessageRequestSchema = z.object({
+  to: z.string().regex(/^\+[1-9]\d{1,14}$/, "Invalid phone number format"),
+});
+
+/**
+ * Schema for image object in image messages
+ * Matches WhatsApp API structure
+ */
+const imageSchema = z
+  .object({
+    id: z.string().optional(),
+    link: z.string().url().optional(),
+    caption: z.string().max(1024).optional(),
+  })
+  .refine((data) => data.link || data.id, "Either link or id must be provided");
+
+/**
+ * Schema for sending an image message
+ * Matches the structure expected by WhatsApp API (minus messaging_product, recipient_type, type, and phoneNumberId)
+ */
+export const sendImageRequestSchema = baseMessageRequestSchema.extend({
+  image: imageSchema,
+});
+
+/**
+ * Schema for text object in text messages
+ * Matches WhatsApp API structure
+ */
+const textSchema = z.object({
+  body: z.string().min(1).max(4096),
+  preview_url: z.boolean().optional(),
+});
+
+/**
+ * Schema for sending a text message
+ * Matches the structure expected by WhatsApp API (minus messaging_product, recipient_type, type, and phoneNumberId)
+ */
+export const sendTextRequestSchema = baseMessageRequestSchema.extend({
+  text: textSchema,
+});
+
+/**
+ * Schema for location object in location messages
+ * Matches WhatsApp API structure
+ */
+const locationSchema = z.object({
+  longitude: z.number().min(-180).max(180),
+  latitude: z.number().min(-90).max(90),
+  name: z.string().optional(),
+  address: z.string().optional(),
+});
+
+/**
+ * Schema for sending a location message
+ * Matches the structure expected by WhatsApp API (minus messaging_product, recipient_type, type, and phoneNumberId)
+ */
+export const sendLocationRequestSchema = baseMessageRequestSchema.extend({
+  location: locationSchema,
+});
+
+/**
+ * Schema for reaction object in reaction messages
+ * Matches WhatsApp API structure
+ */
+const reactionSchema = z.object({
+  message_id: z.string().min(1),
+  emoji: z.string().min(1).max(1), // Single emoji character
+});
+
+/**
+ * Schema for sending a reaction message
+ * Matches the structure expected by WhatsApp API (minus messaging_product, recipient_type, type, and phoneNumberId)
+ */
+export const sendReactionRequestSchema = baseMessageRequestSchema.extend({
+  reaction: reactionSchema,
+});

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

@@ -0,0 +1,42 @@
+import type { HttpClient } from "../../client/HttpClient";
+
+/**
+ * Accounts client - wraps HttpClient with WABA ID (WhatsApp Business Account 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.
+ */
+export class AccountsClient {
+  constructor(
+    private readonly httpClient: HttpClient,
+    private readonly wabaId: string
+  ) {}
+
+  /**
+   * Make a GET request with WABA ID prefix
+   */
+  async get<T>(path: string): Promise<T> {
+    return this.httpClient.get<T>(`/${this.wabaId}${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);
+  }
+
+  /**
+   * 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);
+  }
+}
+

package/src/services/accounts/AccountsService.ts

@@ -0,0 +1,47 @@
+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
+ *
+ * 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.
+ */
+export class AccountsService {
+  private readonly accountsClient: AccountsClient;
+
+  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) {
+      throw new WhatsAppValidationError(
+        "businessAccountId (WABA ID - WhatsApp Business Account ID) is required for AccountsService. Provide it in WhatsAppClient config.",
+        "businessAccountId"
+      );
+    }
+
+    // Create accounts client with WABA ID baked in
+    this.accountsClient = new AccountsClient(
+      httpClient,
+      httpClient.businessAccountId
+    );
+  }
+
+  /**
+   * List phone numbers for a WhatsApp Business Account
+   *
+   * @returns List of phone numbers associated with the WABA
+   */
+  async listPhoneNumbers(): Promise<PhoneNumberListResponse> {
+    return listPhoneNumbers(this.accountsClient);
+  }
+}

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,16 @@
+import type { AccountsClient } from "../AccountsClient";
+import type { PhoneNumberListResponse } from "../../../types/accounts/phone-number";
+
+/**
+ * List phone numbers for a WhatsApp Business Account
+ *
+ * @param accountsClient - Accounts client with WABA ID baked in
+ * @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,42 @@
+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.
+ */
+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,47 @@
+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
+ *
+ * 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.
+ */
+export class BusinessService {
+  private readonly businessClient: BusinessClient;
+
+  constructor(httpClient: HttpClient) {
+    // Validate that businessId (Business Portfolio ID) is set at client level
+    if (!httpClient.businessId) {
+      throw new WhatsAppValidationError(
+        "businessId (Business Portfolio ID) is required for BusinessService. Provide it in WhatsAppClient config.",
+        "businessId"
+      );
+    }
+
+    // Create business client with Business Portfolio ID baked in
+    this.businessClient = new BusinessClient(
+      httpClient,
+      httpClient.businessId
+    );
+  }
+
+  /**
+   * List WhatsApp Business Accounts (WABAs) for a Business Portfolio
+   *
+   * @returns List of WABAs associated with the Business Portfolio
+   */
+  async listAccounts(): Promise<BusinessAccountsListResponse> {
+    return listAccounts(this.businessClient);
+  }
+}
+

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,18 @@
+import type { BusinessClient } from "../BusinessClient";
+import type { BusinessAccountsListResponse } from "../../../types/business/account";
+
+/**
+ * List WhatsApp Business Accounts (WABAs) for a Business Portfolio
+ *
+ * @param businessClient - Business client with Business Portfolio ID baked in
+ * @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,38 @@
+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.
+ */
+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,77 @@
+import type { 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
+ *
+ * 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.
+ */
+export class MessagesService {
+  private readonly messagesClient: MessagesClient;
+
+  constructor(httpClient: HttpClient) {
+    // Validate that phoneNumberId is set at client level
+    if (!httpClient.phoneNumberId) {
+      throw new WhatsAppValidationError(
+        "phoneNumberId is required for MessagesService. Provide it in WhatsAppClient config.",
+        "phoneNumberId"
+      );
+    }
+
+    // Create messages client with phone number ID baked in
+    this.messagesClient = new MessagesClient(
+      httpClient,
+      httpClient.phoneNumberId
+    );
+  }
+
+  /**
+   * Send a text message
+   *
+   * @param request - Text message request (to, text)
+   */
+  async sendText(request: SendTextRequest): Promise<MessageResponse> {
+    return sendText(this.messagesClient, request);
+  }
+
+  /**
+   * Send an image message
+   *
+   * @param request - Image message request (to, image)
+   */
+  async sendImage(request: SendImageRequest): Promise<MessageResponse> {
+    return sendImage(this.messagesClient, request);
+  }
+
+  /**
+   * Send a location message
+   *
+   * @param request - Location message request (to, location)
+   */
+  async sendLocation(request: SendLocationRequest): Promise<MessageResponse> {
+    return sendLocation(this.messagesClient, request);
+  }
+
+  /**
+   * Send a reaction message
+   *
+   * @param request - Reaction message request (to, reaction)
+   */
+  async sendReaction(request: SendReactionRequest): Promise<MessageResponse> {
+    return sendReaction(this.messagesClient, 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";

package/src/services/messages/methods/send-image.ts

@@ -0,0 +1,33 @@
+import type { MessagesClient } from "../MessagesClient";
+import { sendImageRequestSchema } from "../../../schemas/messages/request";
+import type { SendImageRequest } from "../../../types/messages/request";
+import type { MessageResponse } from "../../../types/messages/response";
+import { buildMessagePayload } from "../utils/build-message-payload";
+import { transformZodError } from "../../../utils/zod-error";
+
+/**
+ * Send an image message
+ *
+ * @param messagesClient - Messages client with phone number ID baked in
+ * @param request - Image message request (to, image)
+ */
+export async function sendImage(
+  messagesClient: MessagesClient,
+  request: SendImageRequest
+): Promise<MessageResponse> {
+  // Validate request with schema - throws WhatsAppValidationError if invalid
+  const result = sendImageRequestSchema.safeParse(request);
+  if (!result.success) {
+    throw transformZodError(result.error);
+  }
+  const data = result.data;
+
+  // Build message payload using common structure
+  // The request.image already matches the API structure, so we can pass it directly
+  const payload = buildMessagePayload(data.to, "image", {
+    image: data.image,
+  });
+
+  // Make API request - messagesClient handles the phoneNumberId prefix automatically
+  return messagesClient.post<MessageResponse>("/messages", payload);
+}

package/src/services/messages/methods/send-location.ts

@@ -0,0 +1,32 @@
+import type { MessagesClient } from "../MessagesClient";
+import { sendLocationRequestSchema } from "../../../schemas/messages/request";
+import type { SendLocationRequest } from "../../../types/messages/request";
+import type { MessageResponse } from "../../../types/messages/response";
+import { buildMessagePayload } from "../utils/build-message-payload";
+import { transformZodError } from "../../../utils/zod-error";
+
+/**
+ * Send a location message
+ * 
+ * @param messagesClient - Messages client with phone number ID baked in
+ * @param request - Location message request (to, location)
+ */
+export async function sendLocation(
+  messagesClient: MessagesClient,
+  request: SendLocationRequest
+): Promise<MessageResponse> {
+  // Validate request with schema - throws WhatsAppValidationError if invalid
+  const result = sendLocationRequestSchema.safeParse(request);
+  if (!result.success) {
+    throw transformZodError(result.error);
+  }
+  const data = result.data;
+
+  // Build message payload using common structure
+  const payload = buildMessagePayload(data.to, "location", {
+    location: data.location,
+  });
+
+  // Make API request - messagesClient handles the phoneNumberId prefix automatically
+  return messagesClient.post<MessageResponse>("/messages", payload);
+}

package/src/services/messages/methods/send-reaction.ts

@@ -0,0 +1,33 @@
+import type { MessagesClient } from "../MessagesClient";
+import { sendReactionRequestSchema } from "../../../schemas/messages/request";
+import type { SendReactionRequest } from "../../../types/messages/request";
+import type { MessageResponse } from "../../../types/messages/response";
+import { buildMessagePayload } from "../utils/build-message-payload";
+import { transformZodError } from "../../../utils/zod-error";
+
+/**
+ * Send a reaction message
+ * 
+ * @param messagesClient - Messages client with phone number ID baked in
+ * @param request - Reaction message request (to, reaction)
+ */
+export async function sendReaction(
+  messagesClient: MessagesClient,
+  request: SendReactionRequest
+): Promise<MessageResponse> {
+  // Validate request with schema - throws WhatsAppValidationError if invalid
+  const result = sendReactionRequestSchema.safeParse(request);
+  if (!result.success) {
+    throw transformZodError(result.error);
+  }
+  const data = result.data;
+
+  // Build message payload using common structure
+  const payload = buildMessagePayload(data.to, "reaction", {
+    reaction: data.reaction,
+  });
+
+  // Make API request - messagesClient handles the phoneNumberId prefix automatically
+  return messagesClient.post<MessageResponse>("/messages", payload);
+}
+