whatsapp-cloud 0.0.5 → 0.0.6

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # whatzapp
 
+## 0.0.6
+
+### Patch Changes
+
+- a46c084: export types
+- 175d774: add webhooks namespace
+
 ## 0.0.5
 
 ### Patch Changes

package/docs/DEVELOPMENT.md

@@ -0,0 +1,154 @@
+# Development Guide
+
+## Local Development with npm/pnpm link
+
+To test the SDK in your own project without publishing to npm:
+
+### Step 1: Link the package (in whatsapp-cloud directory)
+
+```bash
+cd /Users/lukas/Developer/whatsapp-cloud
+pnpm build  # Build the package first
+pnpm link --global  # Creates a global symlink
+```
+
+Or with npm:
+
+```bash
+npm link
+```
+
+### Step 2: Link in your project
+
+```bash
+cd /path/to/your/project
+pnpm link whatsapp-cloud
+```
+
+Or with npm:
+
+```bash
+npm link whatsapp-cloud
+```
+
+**What this does:** Creates a symlink in your project's `node_modules` pointing to your local package. You don't need to:
+
+- Add it to `package.json` (link handles it)
+- Run `pnpm install` (link is enough)
+- Publish to npm
+
+### Step 3: Use it in your project
+
+```typescript
+import { WhatsAppClient, type IncomingTextMessage } from "whatsapp-cloud";
+
+const client = new WhatsAppClient({
+  accessToken: "...",
+});
+```
+
+### Important Notes
+
+- **Rebuild after changes**: After making changes to whatsapp-cloud, run `pnpm build` in the whatsapp-cloud directory
+- **Hot reload**: Some bundlers (like Next.js) may need a restart to pick up changes
+- **Unlink**: When done, unlink with `pnpm unlink whatsapp-cloud` in your project
+
+## Production / CI/CD
+
+For production builds and CI/CD, you have a few options:
+
+### Option 1: Publish to npm (Recommended)
+
+Once ready, publish the package:
+
+```bash
+cd /Users/lukas/Developer/whatsapp-cloud
+pnpm publish
+```
+
+Then in your project's `package.json`:
+
+```json
+{
+  "dependencies": {
+    "whatsapp-cloud": "^0.0.5"
+  }
+}
+```
+
+### Option 2: Git dependency (For private repos)
+
+If your repo is private, use git dependency:
+
+```json
+{
+  "dependencies": {
+    "whatsapp-cloud": "git+https://github.com/your-username/whatsapp-cloud.git"
+  }
+}
+```
+
+### Option 3: Local file path (For monorepos)
+
+If both projects are in the same repo/monorepo:
+
+```json
+{
+  "dependencies": {
+    "whatsapp-cloud": "file:../whatsapp-cloud"
+  }
+}
+```
+
+### Option 4: Conditional linking (Dev vs Prod)
+
+Use environment detection:
+
+```json
+{
+  "dependencies": {
+    "whatsapp-cloud": process.env.NODE_ENV === "development"
+      ? "link:../whatsapp-cloud"
+      : "^0.0.5"
+  }
+}
+```
+
+**Note:** For CI/CD, you'll need Option 1 (npm publish) or Option 2 (git dependency). `pnpm link` only works locally.
+
+## Type Exports
+
+All types are properly exported and can be imported in React/Next.js projects:
+
+```typescript
+// Import client
+import { WhatsAppClient } from "whatsapp-cloud";
+
+// Import types
+import type {
+  IncomingTextMessage,
+  IncomingMessage,
+  WebhookPayload,
+  MessageContext,
+  CreateTemplateRequest,
+  // ... all other types
+} from "whatsapp-cloud";
+
+// Import schemas (for validation)
+import {
+  incomingTextMessageSchema,
+  webhookPayloadSchema,
+  // ... all other schemas
+} from "whatsapp-cloud";
+```
+
+## Verifying Exports
+
+To verify all types are exported correctly:
+
+```bash
+# In your project
+pnpm exec tsc --noEmit --skipLibCheck
+```
+
+This will check that all imported types are available.

package/docs/webhooks.md

@@ -0,0 +1,76 @@
+# Webhooks
+
+Handle incoming WhatsApp messages and status updates via webhooks.
+
+## Quick Start
+
+```typescript
+import { WhatsAppClient } from "@whatsapp-cloud/sdk";
+
+const client = new WhatsAppClient({
+  accessToken: process.env.WHATSAPP_ACCESS_TOKEN!,
+});
+
+// In your webhook endpoint
+app.post("/webhook", async (req, res) => {
+  // handle() returns IMMEDIATELY - handlers run in background
+  client.webhooks.handle(req.body, {
+    text: async (message, context) => {
+      // This can take as long as needed (20s, 1min, etc.)
+      // Webhook already returned 200, so Meta is happy
+
+      // Process text message
+      console.log(`Received: ${message.text.body} from ${message.from}`);
+
+      // Store in database
+      await db.messages.create({
+        id: message.id,
+        from: message.from,
+        body: message.text.body,
+        phoneNumberId: context.metadata.phoneNumberId,
+      });
+
+      // Send response
+      await client.messages.sendText({
+        to: `+${message.from}`,
+        text: { body: "Got it!" },
+      });
+    },
+  });
+
+  // Returns 200 IMMEDIATELY (handlers continue in background)
+  res.json({ success: true });
+});
+```
+
+## Webhook Verification
+
+Meta sends GET requests to verify your webhook endpoint:
+
+```typescript
+app.get("/webhook", (req, res) => {
+  const challenge = client.webhooks.verify(req.query, process.env.VERIFY_TOKEN);
+  if (challenge) {
+    return res.send(challenge);
+  }
+  return res.status(403).send("Forbidden");
+});
+```
+
+## Low-Level API
+
+For more control, extract messages manually:
+
+```typescript
+const messages = client.webhooks.extractMessages(payload);
+for (const message of messages) {
+  // Custom processing
+}
+```
+
+## API Reference
+
+- `client.webhooks.verify(query, token)` - Verify GET request, returns challenge or null
+- `client.webhooks.extractMessages(payload)` - Extract messages from payload
+- `client.webhooks.extractStatuses(payload)` - Extract status updates
+- `client.webhooks.handle(payload, handlers, options?)` - Handle with type-safe callbacks

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "whatsapp-cloud",
-  "version": "0.0.5",
+  "version": "0.0.6",
   "description": "Work in progress. A WhatsApp client tailored for LLMs—built to actually work.",
   "type": "module",
   "main": "dist/index.js",

package/src/client/WhatsAppClient.ts

@@ -5,6 +5,7 @@ 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 { WebhooksService } from "../services/webhooks/index";
 import { ZodError } from "zod";
 import { transformZodError } from "../utils/zod-error";
 import type { DebugTokenResponse } from "../types/debug";
@@ -17,6 +18,7 @@ export class WhatsAppClient {
   public readonly accounts: AccountsService;
   public readonly business: BusinessService;
   public readonly templates: TemplatesService;
+  public readonly webhooks: WebhooksService;
 
   private readonly httpClient: HttpClient;
 
@@ -40,6 +42,7 @@ export class WhatsAppClient {
     this.accounts = new AccountsService(this.httpClient);
     this.business = new BusinessService(this.httpClient);
     this.templates = new TemplatesService(this.httpClient);
+    this.webhooks = new WebhooksService(this.httpClient);
   }
 
   /**

package/src/index.ts

@@ -7,6 +7,13 @@ export * from "./schemas/index";
 // Export types (primary export point)
 export type * from "./types/index";
 
+// Export webhook handler types (convenience exports)
+export type {
+  MessageContext,
+  MessageHandlers,
+  HandleOptions,
+} from "./services/webhooks/index";
+
 // Export errors for error handling
 export {
   WhatsAppError,

package/src/schemas/index.ts

@@ -3,4 +3,5 @@ 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/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/webhooks/WebhooksService.ts

@@ -0,0 +1,214 @@
+import type { HttpClient } from "../../client/HttpClient";
+import { extractMessages } from "./utils/extract-messages";
+import { extractStatuses } from "./utils/extract-statuses";
+import { verifyWebhook } from "./utils/verify";
+import { webhookPayloadSchema } from "../../schemas/webhooks/payload";
+import type {
+  WebhookPayload,
+  IncomingTextMessage,
+  IncomingMessage,
+} from "../../types/webhooks";
+
+/**
+ * Context provided to message handlers
+ * Contains metadata and contact info (message is passed separately)
+ */
+export type MessageContext = {
+  metadata: {
+    phoneNumberId: string;
+    displayPhoneNumber: string;
+    wabaId: string;
+  };
+  contact?: {
+    name: string;
+    waId: string;
+  };
+};
+
+/**
+ * Handler functions for different message types
+ * Receives message and context separately - message is the focus, context is optional metadata
+ */
+export type MessageHandlers = {
+  text?: (
+    message: IncomingTextMessage,
+    context: MessageContext
+  ) => Promise<void> | void;
+  // Future: image, audio, video, etc.
+};
+
+/**
+ * Options for handle() method
+ */
+export type HandleOptions = {
+  /**
+   * Error handler called when a message handler throws an error
+   * If not provided, errors are logged and processing continues
+   */
+  onError?: (error: Error, message: IncomingMessage) => void;
+};
+
+/**
+ * Webhooks service for handling incoming webhook payloads
+ *
+ * Provides utilities for extracting messages and a convenience handler
+ * for type-safe message processing.
+ */
+export class WebhooksService {
+  constructor(private readonly httpClient: HttpClient) {}
+
+  /**
+   * Verify webhook GET request from Meta
+   *
+   * Meta sends GET requests to verify webhook endpoints during setup.
+   * Returns the challenge string if valid, null if invalid.
+   *
+   * @param query - Query parameters from GET request
+   * @param verifyToken - Your verification token (stored on your server)
+   * @returns Challenge string if valid, null if invalid
+   */
+  verify(
+    query: {
+      "hub.mode"?: string;
+      "hub.verify_token"?: string;
+      "hub.challenge"?: string;
+    },
+    verifyToken: string
+  ): string | null {
+    return verifyWebhook(query, verifyToken);
+  }
+
+  /**
+   * Extract all incoming messages from webhook payload
+   *
+   * Low-level utility that flattens the nested webhook structure
+   * and returns messages directly.
+   *
+   * @param payload - Webhook payload from Meta
+   * @returns Flat array of incoming messages
+   */
+  extractMessages(payload: WebhookPayload): IncomingMessage[] {
+    return extractMessages(payload);
+  }
+
+  /**
+   * Extract status updates from webhook payload
+   *
+   * Low-level utility for extracting status updates for outgoing messages.
+   *
+   * @param payload - Webhook payload from Meta
+   * @returns Flat array of status updates
+   */
+  extractStatuses(payload: WebhookPayload): unknown[] {
+    return extractStatuses(payload);
+  }
+
+  /**
+   * Validate webhook payload structure
+   *
+   * Validates the payload against the schema. Logs errors if malformed
+   * but doesn't throw, allowing processing to continue.
+   *
+   * @param payload - Raw payload to validate
+   * @returns Validated payload if valid, original payload if invalid (with logged error)
+   */
+  private validatePayload(payload: unknown): WebhookPayload {
+    const result = webhookPayloadSchema.safeParse(payload);
+    if (!result.success) {
+      console.error(
+        "Webhook payload validation failed:",
+        result.error.format()
+      );
+      // Return as-is (TypeScript will treat it as WebhookPayload, but it's actually invalid)
+      // This allows processing to continue, but handlers should be defensive
+      return payload as WebhookPayload;
+    }
+    return result.data;
+  }
+
+  /**
+   * Handle webhook payload with type-safe callbacks
+   *
+   * High-level convenience method that extracts messages and dispatches
+   * them to appropriate handlers based on message type.
+   *
+   * **Important**: This method returns quickly to allow fast webhook responses.
+   * Handlers are processed asynchronously. If you need to await handler completion,
+   * use the low-level `extractMessages()` method instead.
+   *
+   * @param payload - Webhook payload from Meta (will be validated)
+   * @param handlers - Object with handler functions for each message type
+   * @param options - Optional error handling configuration
+   */
+  handle(
+    payload: unknown,
+    handlers: MessageHandlers,
+    options?: HandleOptions
+  ): void {
+    // Validate payload (logs error if malformed, but continues)
+    const validatedPayload = this.validatePayload(payload);
+
+    // Extract metadata and contacts from payload for context
+    for (const entry of validatedPayload.entry) {
+      for (const change of entry.changes) {
+        if (change.field === "messages" && change.value.messages) {
+          const metadata = {
+            phoneNumberId: change.value.metadata.phone_number_id,
+            displayPhoneNumber: change.value.metadata.display_phone_number,
+            wabaId: entry.id,
+          };
+
+          const contacts = change.value.contacts || [];
+
+          // Process each message with its context
+          for (const message of change.value.messages) {
+            // Find contact for this message (match by wa_id)
+            const contact = contacts.find((c) => c.wa_id === message.from);
+
+            // Build context (metadata + contact, no message duplication)
+            const context: MessageContext = {
+              metadata,
+              ...(contact && {
+                contact: {
+                  name: contact.profile.name,
+                  waId: contact.wa_id,
+                },
+              }),
+            };
+
+            // Process handler asynchronously (don't await)
+            // This allows long-running handlers without blocking webhook response
+            Promise.resolve()
+              .then(async () => {
+                // Type-safe dispatch based on message type
+                switch (message.type) {
+                  case "text":
+                    if (handlers.text) {
+                      await handlers.text(message, context);
+                    }
+                    break;
+
+                  // Future: image, audio, video, etc.
+                  default:
+                    // Unhandled message type - silently continue
+                    break;
+                }
+              })
+              .catch((error) => {
+                // Handle errors in handler execution
+                if (options?.onError) {
+                  options.onError(error as Error, message);
+                } else {
+                  // Default: log and continue (don't break webhook response)
+                  console.error(
+                    `Error handling ${message.type} message ${message.id}:`,
+                    error
+                  );
+                }
+              });
+          }
+        }
+      }
+    }
+  }
+}

package/src/services/webhooks/index.ts

@@ -0,0 +1,3 @@
+export * from "./WebhooksService";
+export type { MessageContext, MessageHandlers, HandleOptions } from "./WebhooksService";
+

package/src/services/webhooks/utils/extract-messages.ts

@@ -0,0 +1,25 @@
+import type { WebhookPayload } from "../../../types/webhooks";
+import type { IncomingMessage } from "../../../types/webhooks/incoming-message";
+
+/**
+ * Extract all incoming messages from webhook payload
+ *
+ * Flattens the nested structure: entry[].changes[].value.messages[]
+ * Returns a flat array of messages directly
+ *
+ * @param payload - Webhook payload from Meta
+ * @returns Flat array of incoming messages
+ */
+export function extractMessages(payload: WebhookPayload): IncomingMessage[] {
+  const messages: IncomingMessage[] = [];
+
+  for (const entry of payload.entry) {
+    for (const change of entry.changes) {
+      if (change.field === "messages" && change.value.messages) {
+        messages.push(...change.value.messages);
+      }
+    }
+  }
+
+  return messages;
+}

package/src/services/webhooks/utils/extract-statuses.ts

@@ -0,0 +1,25 @@
+import type { WebhookPayload } from "../../../types/webhooks";
+
+/**
+ * Extract status updates from webhook payload
+ *
+ * Flattens the nested structure: entry[].changes[].value.statuses[]
+ * Returns a flat array of status updates
+ *
+ * @param payload - Webhook payload from Meta
+ * @returns Flat array of status updates
+ */
+export function extractStatuses(payload: WebhookPayload): unknown[] {
+  const statuses: unknown[] = [];
+
+  for (const entry of payload.entry) {
+    for (const change of entry.changes) {
+      if (change.field === "messages" && change.value.statuses) {
+        statuses.push(...change.value.statuses);
+      }
+    }
+  }
+
+  return statuses;
+}
+

package/src/services/webhooks/utils/verify.ts

@@ -0,0 +1,29 @@
+/**
+ * Verify webhook GET request from Meta
+ *
+ * Meta sends GET requests to verify webhook endpoints:
+ * GET /webhook?hub.mode=subscribe&hub.challenge=<CHALLENGE>&hub.verify_token=<TOKEN>
+ *
+ * @param query - Query parameters from GET request
+ * @param verifyToken - Your verification token (stored on your server)
+ * @returns Challenge string if valid, null if invalid
+ */
+export function verifyWebhook(
+  query: {
+    "hub.mode"?: string;
+    "hub.verify_token"?: string;
+    "hub.challenge"?: string;
+  },
+  verifyToken: string
+): string | null {
+  const mode = query["hub.mode"];
+  const token = query["hub.verify_token"];
+  const challenge = query["hub.challenge"];
+
+  // Verify mode is "subscribe" and token matches
+  if (mode === "subscribe" && token === verifyToken && challenge) {
+    return challenge;
+  }
+
+  return null;
+}

package/src/types/index.ts

@@ -3,4 +3,5 @@ export type * from "./messages/index";
 export type * from "./accounts/index";
 export type * from "./business/index";
 export type * from "./templates/index";
+export type * from "./webhooks/index";
 export type * from "./debug";

package/src/types/webhooks/incoming-message.ts

@@ -0,0 +1,16 @@
+import { z } from "zod";
+import {
+  incomingTextMessageSchema,
+  incomingMessageSchema,
+} from "../../schemas/webhooks/incoming-message";
+
+/**
+ * Type for incoming text message
+ */
+export type IncomingTextMessage = z.infer<typeof incomingTextMessageSchema>;
+
+/**
+ * Union type for all incoming message types
+ */
+export type IncomingMessage = z.infer<typeof incomingMessageSchema>;
+

package/src/types/webhooks/index.ts

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

package/src/types/webhooks/payload.ts

@@ -0,0 +1,8 @@
+import { z } from "zod";
+import { webhookPayloadSchema } from "../../schemas/webhooks/payload";
+
+/**
+ * Type for webhook payload
+ */
+export type WebhookPayload = z.infer<typeof webhookPayloadSchema>;
+