whatsapp-cloud 0.0.3 → 0.0.4

package/agent_docs/messages-namespace-design.md

@@ -0,0 +1,357 @@
+# Messages Namespace Design
+
+This document describes the design patterns and architectural decisions for the Messages namespace. This serves as a blueprint for implementing other namespaces in the WhatsApp Cloud API SDK.
+
+## Core Design Principles
+
+### 1. **Namespace Client Pattern**
+
+Each namespace that requires a base path identifier (like `phoneNumberId` for messages) gets its own client wrapper that handles the base path automatically.
+
+**Pattern:**
+- Create a `{Namespace}Client` class that wraps `HttpClient`
+- The client automatically prepends the namespace identifier to all paths
+- Methods use simple relative paths (e.g., `/messages`) instead of full paths (e.g., `/${phoneNumberId}/messages`)
+
+**Example:**
+```typescript
+// MessagesClient wraps HttpClient with phoneNumberId as base endpoint
+export class MessagesClient {
+  constructor(
+    private readonly httpClient: HttpClient,
+    private readonly phoneNumberId: string
+  ) {}
+
+  async post<T>(path: string, body: unknown): Promise<T> {
+    return this.httpClient.post<T>(`/${this.phoneNumberId}${path}`, body);
+  }
+}
+```
+
+**Why:** Treats the namespace identifier (phoneNumberId) as a "client" for that namespace. Different identifiers represent different endpoints, making the abstraction clean and intuitive.
+
+### 2. **Request Structure Matches API**
+
+Request schemas match the WhatsApp API structure exactly, minus fields that are handled internally.
+
+**Pattern:**
+- Request schemas mirror the API payload structure
+- Exclude: `messaging_product`, `recipient_type`, `type` (added by `buildMessagePayload`)
+- Exclude: `phoneNumberId` (handled at client level)
+- Include: All user-provided fields matching API structure
+
+**Example:**
+```typescript
+// API expects: { to, image: { id?, link?, caption? } }
+// Schema matches: { to, image: { id?, link?, caption? } }
+export const sendImageRequestSchema = baseMessageRequestSchema.extend({
+  image: imageSchema, // Matches API structure
+});
+```
+
+**Why:** 
+- Reduces transformation logic
+- Makes API documentation directly applicable
+- Clear mapping between user input and API payload
+
+### 3. **Client-Level Configuration**
+
+Namespace-specific identifiers (like `phoneNumberId`) are handled at the service construction level, not in individual requests.
+
+**Pattern:**
+- Service validates required identifier exists in `HttpClient` at construction
+- Service creates namespace client once with the identifier
+- Methods receive the namespace client, not the raw `HttpClient`
+- No per-request identifier resolution needed
+
+**Example:**
+```typescript
+export class MessagesService {
+  private readonly messagesClient: MessagesClient;
+
+  constructor(httpClient: HttpClient) {
+    // Validate identifier at construction
+    if (!httpClient.phoneNumberId) {
+      throw new WhatsAppValidationError(...);
+    }
+    
+    // Create namespace client once
+    this.messagesClient = new MessagesClient(httpClient, httpClient.phoneNumberId);
+  }
+
+  async sendImage(request: SendImageRequest) {
+    // Method receives namespace client, not HttpClient
+    return sendImage(this.messagesClient, request);
+  }
+}
+```
+
+**Why:**
+- Identifier is required, so validate early (fail fast)
+- Single source of truth for namespace identifier
+- Methods don't need to handle optional overrides
+- Cleaner method signatures
+
+### 4. **Clean Method Pattern**
+
+All methods follow a consistent pattern: validate → extract → build → request.
+
+**Pattern:**
+```typescript
+export async function sendImage(
+  messagesClient: MessagesClient,
+  request: SendImageRequest
+): Promise<MessageResponse> {
+  // 1. Validate request with schema
+  const result = sendImageRequestSchema.safeParse(request);
+  if (!result.success) {
+    throw transformZodError(result.error);
+  }
+  
+  // 2. Extract validated data
+  const data = result.data;
+  
+  // 3. Build payload (request structure already matches API)
+  const payload = buildMessagePayload(data.to, "image", {
+    image: data.image,
+  });
+  
+  // 4. Make API request (namespace client handles base path)
+  return messagesClient.post<MessageResponse>("/messages", payload);
+}
+```
+
+**Why:**
+- Consistent, predictable flow
+- Easy to understand and maintain
+- Clear separation of concerns
+- Request → result → data trajectory
+
+### 5. **Request → Result → Data Trajectory**
+
+The validation flow follows a clear trajectory: request → validation result → validated data.
+
+**Pattern:**
+```typescript
+// Request comes in
+const result = schema.safeParse(request);
+
+// Extract validated data
+const data = result.data;
+
+// Use data directly (structure matches API)
+const payload = buildMessagePayload(data.to, "image", {
+  image: data.image,
+});
+```
+
+**Why:**
+- Clear path from user input to safe API request
+- No intermediate transformations needed
+- Type-safe throughout the flow
+
+### 6. **No Manual Undefined Filtering**
+
+Let `JSON.stringify` handle undefined values automatically.
+
+**Pattern:**
+```typescript
+// Don't filter undefined manually
+export function buildMessagePayload(to: string, type: string, content: T) {
+  return {
+    messaging_product: "whatsapp" as const,
+    recipient_type: "individual" as const,
+    to,
+    type,
+    ...content, // undefined values automatically omitted by JSON.stringify
+  };
+}
+```
+
+**Why:**
+- `JSON.stringify` automatically omits undefined values
+- Less code, simpler logic
+- No need for `omitUndefined` utilities
+
+## Architecture Layers
+
+### Layer 1: Service (MessagesService)
+- **Responsibility:** Validate namespace requirements, create namespace client
+- **Input:** `HttpClient` (with namespace identifier)
+- **Output:** Namespace client instance
+- **Pattern:** Constructor validation + client creation
+
+### Layer 2: Namespace Client (MessagesClient)
+- **Responsibility:** Handle namespace-specific base path
+- **Input:** `HttpClient` + namespace identifier
+- **Output:** Wrapped client with base path handling
+- **Pattern:** Proxy pattern - wraps HttpClient with path prefix
+
+### Layer 3: Methods (sendImage, sendText, etc.)
+- **Responsibility:** Validate request, build payload, make API call
+- **Input:** Namespace client + request object
+- **Output:** API response
+- **Pattern:** Validate → extract → build → request
+
+### Layer 4: Utilities (buildMessagePayload)
+- **Responsibility:** Add common API fields
+- **Input:** User data
+- **Output:** Complete API payload
+- **Pattern:** Simple object construction
+
+## File Structure
+
+```
+services/messages/
+├── MessagesService.ts      # Service layer - validates & creates client
+├── MessagesClient.ts        # Namespace client - handles base path
+├── methods/
+│   ├── send-image.ts       # Method implementations
+│   ├── send-text.ts
+│   ├── send-location.ts
+│   └── send-reaction.ts
+├── utils/
+│   └── build-message-payload.ts  # Common payload builder
+└── index.ts                # Exports
+```
+
+## Schema Structure
+
+```
+schemas/messages/
+├── request.ts              # Request schemas matching API structure
+└── response.ts             # Response schemas
+```
+
+**Request Schema Pattern:**
+```typescript
+// Base schema (common fields)
+const baseMessageRequestSchema = z.object({
+  to: z.string().regex(...),
+});
+
+// Type-specific schema (matches API structure)
+const imageSchema = z.object({
+  id: z.string().optional(),
+  link: z.string().url().optional(),
+  caption: z.string().max(1024).optional(),
+}).refine(...);
+
+// Combined schema
+export const sendImageRequestSchema = baseMessageRequestSchema.extend({
+  image: imageSchema,
+});
+```
+
+## Type Structure
+
+```
+types/messages/
+├── request.ts              # Request types (inferred from schemas)
+└── response.ts             # Response types
+```
+
+**Type Pattern:**
+```typescript
+// Types are inferred from schemas
+export type SendImageRequest = z.infer<typeof sendImageRequestSchema>;
+```
+
+## Key Design Decisions
+
+### ✅ Do's
+
+1. **Match API structure in requests** - Makes documentation directly applicable
+2. **Validate at service construction** - Fail fast, clear errors
+3. **Use namespace clients** - Clean abstraction for namespace-specific paths
+4. **Follow consistent method pattern** - Easy to understand and maintain
+5. **Let JSON.stringify handle undefined** - Simpler code
+
+### ❌ Don'ts
+
+1. **Don't include namespace identifiers in requests** - Handle at client level
+2. **Don't manually filter undefined** - Let JSON.stringify do it
+3. **Don't transform request structure unnecessarily** - Match API directly
+4. **Don't resolve identifiers in methods** - Do it at service level
+5. **Don't create namespace client per request** - Create once in constructor
+
+## Applying to Other Namespaces
+
+When creating a new namespace (e.g., `BusinessAccounts`):
+
+1. **Create namespace client** (`BusinessAccountsClient`)
+   - Wrap `HttpClient` with namespace-specific base path
+   - Handle namespace identifier (e.g., `businessAccountId`)
+
+2. **Create service** (`BusinessAccountsService`)
+   - Validate namespace identifier exists in constructor
+   - Create namespace client once
+   - Pass client to methods
+
+3. **Create methods** (`getProfile`, `updateProfile`, etc.)
+   - Follow validate → extract → build → request pattern
+   - Use namespace client, not raw `HttpClient`
+   - Match API structure in requests
+
+4. **Create schemas** (`schemas/business-accounts/`)
+   - Match API structure exactly
+   - Exclude internal fields (handled by utilities)
+   - Exclude namespace identifier (handled at client level)
+
+5. **Create types** (`types/business-accounts/`)
+   - Infer from schemas using `z.infer`
+
+## Example: Applying Pattern to Business Accounts
+
+```typescript
+// 1. Namespace Client
+export class BusinessAccountsClient {
+  constructor(
+    private readonly httpClient: HttpClient,
+    private readonly businessAccountId: string
+  ) {}
+
+  async get<T>(path: string): Promise<T> {
+    return this.httpClient.get<T>(`/${this.businessAccountId}${path}`);
+  }
+}
+
+// 2. Service
+export class BusinessAccountsService {
+  private readonly accountsClient: BusinessAccountsClient;
+
+  constructor(httpClient: HttpClient) {
+    if (!httpClient.businessAccountId) {
+      throw new WhatsAppValidationError(...);
+    }
+    this.accountsClient = new BusinessAccountsClient(
+      httpClient,
+      httpClient.businessAccountId
+    );
+  }
+
+  async getProfile() {
+    return getProfile(this.accountsClient);
+  }
+}
+
+// 3. Method
+export async function getProfile(
+  accountsClient: BusinessAccountsClient
+): Promise<ProfileResponse> {
+  return accountsClient.get<ProfileResponse>("/profile");
+}
+```
+
+## Summary
+
+The Messages namespace design provides a clean, consistent pattern for implementing API namespaces:
+
+- **Namespace clients** handle base paths automatically
+- **Request structures** match API directly
+- **Service layer** validates and creates clients
+- **Methods** follow a consistent pattern
+- **No manual filtering** - let JSON.stringify handle it
+
+This pattern ensures consistency, maintainability, and clarity across all namespaces in the SDK.
+

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "whatsapp-cloud",
-  "version": "0.0.3",
-  "description": "",
+  "version": "0.0.4",
+  "description": "Work in progress. A WhatsApp client tailored for LLMs—built to actually work.",
   "type": "module",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
@@ -14,6 +14,9 @@
     "tsup": "^8.5.1",
     "typescript": "^5.9.3"
   },
+  "dependencies": {
+    "zod": "^4.2.1"
+  },
   "scripts": {
     "build": "tsup src/index.ts --format cjs,esm --dts",
     "lint": "tsc"

package/src/client/HttpClient.ts

@@ -0,0 +1,122 @@
+import type { ClientConfig } from "../types/client";
+
+/**
+ * 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,
+        },
+      }));
+      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,
+        },
+      }));
+      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,
+        },
+      }));
+      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,55 @@
+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 { 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;
+
+  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);
+  }
+
+  /**
+   * 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/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(),
+});
+