whatsapp-cloud 0.0.3 → 0.0.5

package/src/client/HttpClient.ts

@@ -0,0 +1,159 @@
+import type { ClientConfig } from "../types/client";
+
+interface APIErrorResponse {
+  error?: {
+    message?: string;
+    code?: number;
+  };
+}
+
+/**
+ * HTTP client for making requests to the WhatsApp Cloud API
+ */
+export class HttpClient {
+  private readonly baseURL: string;
+  public readonly accessToken: string;
+  public readonly phoneNumberId?: string;
+  public readonly businessAccountId?: string;
+  public readonly businessId?: string;
+  public readonly apiVersion: string;
+
+  constructor(config: ClientConfig) {
+    this.accessToken = config.accessToken;
+    if (config.phoneNumberId !== undefined) {
+      this.phoneNumberId = config.phoneNumberId;
+    }
+    if (config.businessAccountId !== undefined) {
+      this.businessAccountId = config.businessAccountId;
+    }
+    if (config.businessId !== undefined) {
+      this.businessId = config.businessId;
+    }
+    this.apiVersion = config.apiVersion ?? "v18.0";
+    this.baseURL = config.baseURL ?? "https://graph.facebook.com";
+  }
+
+  /**
+   * Make a POST request
+   */
+  async post<T>(path: string, body: unknown): Promise<T> {
+    const url = `${this.baseURL}/${this.apiVersion}${path}`;
+
+    const response = await fetch(url, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${this.accessToken}`,
+      },
+      body: JSON.stringify(body),
+    });
+
+    if (!response.ok) {
+      const error = (await response.json().catch(() => ({
+        error: {
+          message: response.statusText,
+          code: response.status,
+        },
+      }))) as APIErrorResponse;
+      throw new Error(
+        `API Error: ${error.error?.message || response.statusText} (${
+          error.error?.code || response.status
+        })`
+      );
+    }
+
+    return response.json() as Promise<T>;
+  }
+
+  /**
+   * Make a GET request
+   */
+  async get<T>(path: string): Promise<T> {
+    const url = `${this.baseURL}/${this.apiVersion}${path}`;
+
+    const response = await fetch(url, {
+      method: "GET",
+      headers: {
+        Authorization: `Bearer ${this.accessToken}`,
+      },
+    });
+
+    if (!response.ok) {
+      const error = (await response.json().catch(() => ({
+        error: {
+          message: response.statusText,
+          code: response.status,
+        },
+      }))) as APIErrorResponse;
+      throw new Error(
+        `API Error: ${error.error?.message || response.statusText} (${
+          error.error?.code || response.status
+        })`
+      );
+    }
+
+    return response.json() as Promise<T>;
+  }
+
+  /**
+   * Make a PATCH request
+   */
+  async patch<T>(path: string, body: unknown): Promise<T> {
+    const url = `${this.baseURL}/${this.apiVersion}${path}`;
+
+    const response = await fetch(url, {
+      method: "PATCH",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${this.accessToken}`,
+      },
+      body: JSON.stringify(body),
+    });
+
+    if (!response.ok) {
+      const error = (await response.json().catch(() => ({
+        error: {
+          message: response.statusText,
+          code: response.status,
+        },
+      }))) as APIErrorResponse;
+      throw new Error(
+        `API Error: ${error.error?.message || response.statusText} (${
+          error.error?.code || response.status
+        })`
+      );
+    }
+
+    return response.json() as Promise<T>;
+  }
+
+  /**
+   * Make a DELETE request
+   */
+  async delete<T>(path: string): Promise<T> {
+    const url = `${this.baseURL}/${this.apiVersion}${path}`;
+
+    const response = await fetch(url, {
+      method: "DELETE",
+      headers: {
+        Authorization: `Bearer ${this.accessToken}`,
+      },
+    });
+
+    if (!response.ok) {
+      const error = (await response.json().catch(() => ({
+        error: {
+          message: response.statusText,
+          code: response.status,
+        },
+      }))) as APIErrorResponse;
+      throw new Error(
+        `API Error: ${error.error?.message || response.statusText} (${
+          error.error?.code || response.status
+        })`
+      );
+    }
+
+    return response.json() as Promise<T>;
+  }
+}

package/src/client/WhatsAppClient.ts

@@ -0,0 +1,58 @@
+import { clientConfigSchema } from "../schemas/client";
+import type { ClientConfig } from "../types/client";
+import { HttpClient } from "./HttpClient";
+import { MessagesService } from "../services/messages/index";
+import { AccountsService } from "../services/accounts/index";
+import { BusinessService } from "../services/business/index";
+import { TemplatesService } from "../services/templates/index";
+import { ZodError } from "zod";
+import { transformZodError } from "../utils/zod-error";
+import type { DebugTokenResponse } from "../types/debug";
+
+/**
+ * WhatsApp Cloud API client
+ */
+export class WhatsAppClient {
+  public readonly messages: MessagesService;
+  public readonly accounts: AccountsService;
+  public readonly business: BusinessService;
+  public readonly templates: TemplatesService;
+
+  private readonly httpClient: HttpClient;
+
+  constructor(config: ClientConfig) {
+    // Validate config with schema - Zod provides detailed error messages
+    let validated: ClientConfig;
+    try {
+      validated = clientConfigSchema.parse(config);
+    } catch (error) {
+      if (error instanceof ZodError) {
+        throw transformZodError(error);
+      }
+      throw error;
+    }
+
+    // Initialize HTTP client
+    this.httpClient = new HttpClient(validated);
+
+    // Initialize services (namespaces)
+    this.messages = new MessagesService(this.httpClient);
+    this.accounts = new AccountsService(this.httpClient);
+    this.business = new BusinessService(this.httpClient);
+    this.templates = new TemplatesService(this.httpClient);
+  }
+
+  /**
+   * Debug the current access token
+   *
+   * This method calls the Graph API debug_token endpoint to inspect the access token
+   * used by this client. Useful for understanding token permissions, expiration, and validity.
+   *
+   * @returns Debug information about the access token
+   */
+  async debugToken(): Promise<DebugTokenResponse> {
+    return this.httpClient.get<DebugTokenResponse>(
+      `/debug_token?input_token=${this.httpClient.accessToken}`
+    );
+  }
+}

package/src/client/index.ts

@@ -0,0 +1,2 @@
+export { WhatsAppClient } from "./WhatsAppClient";
+export { HttpClient } from "./HttpClient";

package/src/errors.ts

@@ -0,0 +1,58 @@
+/**
+ * Base error class for WhatsApp API errors
+ */
+export class WhatsAppError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = this.constructor.name;
+    // Maintains proper stack trace for where our error was thrown (only available on V8)
+    const captureStackTrace = (Error as any).captureStackTrace;
+    if (typeof captureStackTrace === "function") {
+      captureStackTrace(this, this.constructor);
+    }
+  }
+}
+
+/**
+ * Error thrown when validation fails (configuration, requests, etc.)
+ * Can be used for any Zod validation error
+ */
+export class WhatsAppValidationError extends WhatsAppError {
+  constructor(
+    message: string,
+    public readonly field?: string,
+    public readonly issues?: Array<{
+      path: readonly (string | number)[];
+      message: string;
+    }>
+  ) {
+    super(message);
+    this.name = "WhatsAppValidationError";
+  }
+}
+
+/**
+ * Error thrown when an API request fails
+ */
+export class WhatsAppAPIError extends WhatsAppError {
+  constructor(
+    public readonly code: number,
+    public readonly type: string,
+    message: string,
+    public readonly statusCode?: number,
+    public readonly details?: unknown
+  ) {
+    super(message);
+    this.name = "WhatsAppAPIError";
+  }
+}
+
+/**
+ * Error thrown when rate limit is exceeded
+ */
+export class WhatsAppRateLimitError extends WhatsAppAPIError {
+  constructor(message: string, public readonly retryAfter?: number) {
+    super(131056, "rate_limit", message, 429, { retryAfter });
+    this.name = "WhatsAppRateLimitError";
+  }
+}

package/src/examples/main.ts

@@ -0,0 +1,9 @@
+import "dotenv/config";
+import { WhatsAppClient } from "../client";
+
+const client = new WhatsAppClient({
+  accessToken: process.env.WHATSAPP_ACCESS_TOKEN!,
+});
+
+const debugInfo = await client.debugToken();
+console.log(debugInfo);

package/src/examples/template.ts

@@ -0,0 +1,134 @@
+import "dotenv/config";
+import { WhatsAppClient } from "../client";
+
+const client = new WhatsAppClient({
+  accessToken: process.env.WHATSAPP_ACCESS_TOKEN!,
+  businessAccountId: process.env.WHATSAPP_BUSINESS_ACCOUNT_ID!,
+});
+
+async function testTemplates() {
+  try {
+    console.log("🧪 Testing Templates API...\n");
+
+    // Test 1: Create a template
+    console.log("1️⃣ Creating template...");
+    const createResponse = await client.templates.create({
+      name: `test_template_${Date.now()}`, // Unique name to avoid conflicts
+      language: "en",
+      category: "UTILITY",
+      components: [
+        {
+          type: "BODY",
+          text: "Hello! This is a test template. Thank you for testing our WhatsApp Cloud API SDK.",
+        },
+        {
+          type: "FOOTER",
+          text: "This is a test footer",
+        },
+        {
+          type: "BUTTONS",
+          buttons: [
+            {
+              type: "QUICK_REPLY",
+              text: "Get Started",
+            },
+            {
+              type: "QUICK_REPLY",
+              text: "Learn More",
+            },
+          ],
+        },
+      ],
+    });
+
+    console.log("✅ Template created successfully!");
+    console.log("Response:", JSON.stringify(createResponse, null, 2));
+    console.log("\n");
+
+    // Verify create response structure
+    if (!createResponse.id) {
+      throw new Error("Create response missing 'id' field");
+    }
+    if (!createResponse.status) {
+      throw new Error("Create response missing 'status' field");
+    }
+    if (!createResponse.category) {
+      throw new Error("Create response missing 'category' field");
+    }
+    console.log("✅ Create response structure verified\n");
+
+    // Test 2: Get template by ID
+    console.log("2️⃣ Getting template by ID...");
+    const templateId = createResponse.id;
+    const getResponse = await client.templates.get(templateId);
+
+    console.log("✅ Template retrieved successfully!");
+    console.log("Response:", JSON.stringify(getResponse, null, 2));
+    console.log("\n");
+
+    // Verify get response structure
+    if (!getResponse.id) {
+      throw new Error("Get response missing 'id' field");
+    }
+    if (!getResponse.name) {
+      throw new Error("Get response missing 'name' field");
+    }
+    if (!getResponse.language) {
+      throw new Error("Get response missing 'language' field");
+    }
+    if (!getResponse.status) {
+      throw new Error("Get response missing 'status' field");
+    }
+    if (!getResponse.category) {
+      throw new Error("Get response missing 'category' field");
+    }
+    if (!Array.isArray(getResponse.components)) {
+      throw new Error("Get response missing 'components' array");
+    }
+    console.log("✅ Get response structure verified\n");
+
+    // Verify components
+    const bodyComponent = getResponse.components.find((c) => c.type === "BODY");
+    if (!bodyComponent) {
+      throw new Error("BODY component not found in response");
+    }
+    if (bodyComponent.type !== "BODY") {
+      throw new Error("BODY component type mismatch");
+    }
+    console.log("✅ Components verified\n");
+
+    // Test 3: List templates
+    console.log("3️⃣ Listing templates...");
+    const listResponse = await client.templates.list();
+    console.log(`✅ Found ${listResponse.data.length} template(s)`);
+    console.log("Response:", JSON.stringify(listResponse, null, 2));
+    console.log("\n");
+
+    // Verify list response structure
+    if (!Array.isArray(listResponse.data)) {
+      throw new Error("List response missing 'data' array");
+    }
+    console.log("✅ List response structure verified\n");
+
+    // Verify our created template is in the list
+    const foundTemplate = listResponse.data.find((t) => t.id === templateId);
+    if (!foundTemplate) {
+      console.log(
+        "⚠️  Note: Created template may not appear in list immediately (async processing)"
+      );
+    } else {
+      console.log("✅ Created template found in list\n");
+    }
+
+    console.log("🎉 All tests passed!");
+  } catch (error) {
+    console.error("❌ Test failed:", error);
+    if (error instanceof Error) {
+      console.error("Error message:", error.message);
+      console.error("Error stack:", error.stack);
+    }
+    process.exit(1);
+  }
+}
+
+testTemplates();

package/src/index.ts

@@ -1 +1,16 @@
-export const add = (a: number, b: number) => a + b;
+// WhatsApp Cloud API SDK
+export { WhatsAppClient } from "./client/index";
+
+// Export schemas (AI-ready)
+export * from "./schemas/index";
+
+// Export types (primary export point)
+export type * from "./types/index";
+
+// Export errors for error handling
+export {
+  WhatsAppError,
+  WhatsAppValidationError,
+  WhatsAppAPIError,
+  WhatsAppRateLimitError,
+} from "./errors";

package/src/schemas/accounts/index.ts

@@ -0,0 +1 @@
+export * from "./phone-number";

package/src/schemas/accounts/phone-number.ts

@@ -0,0 +1,20 @@
+import { z } from "zod";
+
+/**
+ * Schema for phone number response
+ * Matches WhatsApp API structure for phone number objects
+ */
+export const phoneNumberResponseSchema = z.object({
+  verified_name: z.string(),
+  display_phone_number: z.string(),
+  id: z.string(),
+  quality_rating: z.string(),
+});
+
+/**
+ * Schema for phone number list response
+ * Matches WhatsApp API structure for GET /phone_numbers endpoint
+ */
+export const phoneNumberListResponseSchema = z.object({
+  data: z.array(phoneNumberResponseSchema),
+});

package/src/schemas/business/account.ts

@@ -0,0 +1,43 @@
+import { z } from "zod";
+
+/**
+ * Schema for WhatsApp Business Account (WABA) response
+ * Matches WhatsApp API structure for WABA objects
+ */
+export const businessAccountResponseSchema = z.object({
+  id: z.string(),
+  name: z.string().optional(),
+  account_review_status: z.string().optional(),
+  currency: z.string().optional(),
+  country: z.string().optional(),
+  timezone_id: z.string().optional(),
+  business_verification_status: z.string().optional(),
+  is_enabled_for_insights: z.boolean().optional(),
+  message_template_namespace: z.string().optional(),
+});
+
+/**
+ * Schema for WhatsApp Business Accounts list response
+ * Matches WhatsApp API structure for GET /whatsapp_business_accounts endpoint
+ *
+ * Note: The API returns data as an object with numeric string keys (e.g., "0", "1")
+ * or as an array, plus optional paging information
+ */
+export const businessAccountsListResponseSchema = z.object({
+  data: z.record(z.string(), businessAccountResponseSchema).or(
+    z.array(businessAccountResponseSchema)
+  ),
+  paging: z
+    .object({
+      cursors: z
+        .object({
+          before: z.string().optional(),
+          after: z.string().optional(),
+        })
+        .optional(),
+      next: z.string().url().optional(),
+      previous: z.string().url().optional(),
+    })
+    .optional(),
+});
+

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").optional(),
+  baseURL: z.string().url().default("https://graph.facebook.com").optional(),
+  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,6 @@
+export * from "./client";
+export * from "./messages/index";
+export * from "./accounts/index";
+export * from "./business/index";
+export * from "./templates/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,
+});