meta-cloud-api 3.7.1 → 3.9.0

package/README.md

@@ -15,6 +15,17 @@
 
 ## Quick Start
 
+**New project?** Scaffold a working WhatsApp app in 30 seconds. No Meta account needed to start:
+
+```bash
+npm create whatsapp-app@latest my-bot
+cd my-bot && npm run dev
+```
+
+It opens in mock mode: you play the customer in the browser, your message runs through the SDK as a real webhook payload, and `lib/bot.ts` replies. Add credentials to `.env.local` and the same code talks to real WhatsApp. See [create-whatsapp-app](./packages/create-whatsapp-app).
+
+**Existing project?**
+
 ```bash
 pnpm add meta-cloud-api
 ```
@@ -51,11 +62,13 @@ await wa.messages.image({ to: '1234567890', link: 'https://example.com/image.png
 | Account ban risk | None | None | Yes — violates WhatsApp ToS |
 | Maintenance | Active (tracks OpenAPI v23) | **Archived since 2023** | Varies |
 | TypeScript | Strict, full request/response types | Partial | Varies |
-| API coverage | 20 modules (Messages, Flows, Calling, Payments, and more) | Messaging-focused | Personal-account features |
-| Webhook adapters | Built-in Express.js + Next.js | Manual | Custom event system |
+| API coverage | 22 modules (Messages, Flows, Calling, Payments, and more) | Messaging-focused | Personal-account features |
+| Webhook adapters | Built-in Express.js, Next.js, Hono, Fastify (NestJS via Express) | Manual | Custom event system |
 
 If you're building on the official Cloud API and don't want to bet on an unmaintained SDK, this is what the archived one would look like if Meta had kept shipping it.
 
+**Coming from the `whatsapp` package?** The [migration guide](https://meta-cloud-api.site/getting-started/migrate-from-whatsapp-nodejs-sdk) maps every API of the archived SDK (config, messages, templates, webhooks, errors) to meta-cloud-api, with a checklist.
+
 ## API Coverage
 
 ```
@@ -78,6 +91,9 @@ wa.blockUsers            // Block/unblock users
 wa.contactBook           // Delete a BSUID contact book entry
 wa.threadControl         // Conversation Routing: pass, release, take threads
 wa.waba                  // WhatsApp Business Account management
+wa.business              // Business portfolio, pre-verified phone numbers, owned/client WABAs, credit lines
+wa.messageHistory        // Message history and history events
+wa.solutions             // Multi-Partner Solutions management
 ```
 
 ## Webhooks
@@ -87,13 +103,17 @@ import express from 'express';
 import { expressWebhookHandler } from 'meta-cloud-api';
 
 const app = express();
-app.use(express.json());
+// Keep the raw body: signatures are computed over the exact bytes Meta sent
+app.use(express.json({ verify: (req, _res, buf) => { (req as any).rawBody = buf.toString(); } }));
 
 // Handler is automatically cached per phoneNumberId — safe against HMR re-evaluation
 const Whatsapp = expressWebhookHandler({
     accessToken: process.env.CLOUD_API_ACCESS_TOKEN,
     phoneNumberId: process.env.WA_PHONE_NUMBER_ID,
     webhookVerificationToken: process.env.WEBHOOK_VERIFICATION_TOKEN,
+    // Reject forged POSTs: require a valid X-Hub-Signature-256 from Meta
+    appSecret: process.env.APP_SECRET,
+    verifyWebhookSignature: true,
 });
 
 // Handle incoming text messages — echo back to sender
@@ -118,11 +138,22 @@ app.get('/webhook', Whatsapp.GET);
 app.post('/webhook', Whatsapp.POST);
 ```
 
+Other frameworks use the same handler object (`GET`, `POST`, `webhook`, `flow`, `processor`, `destroy`):
+
+| Framework | Adapter | Guide |
+|---|---|---|
+| Express.js | `expressWebhookHandler` | [Express](https://meta-cloud-api.site/guides/express/) |
+| Next.js App Router | `nextjsAppWebhookHandler` | [Next.js App Router](https://meta-cloud-api.site/guides/nextjs-app/) |
+| Next.js Pages Router | `nextjsPagesWebhookHandler` | [Next.js Pages Router](https://meta-cloud-api.site/guides/nextjs-pages/) |
+| Hono (Node.js, Bun, Deno, Workers, Edge) | `honoWebhookHandler` | [Hono](https://meta-cloud-api.site/guides/hono/) |
+| Fastify | `fastifyWebhookHandler` | [Fastify](https://meta-cloud-api.site/guides/fastify/) |
+| NestJS | `expressWebhookHandler` or `fastifyWebhookHandler` | [NestJS](https://meta-cloud-api.site/guides/nestjs/) |
+
 All 30+ webhook field types are supported — messages, statuses, templates, flows, groups, calls, and more. See the [Webhooks documentation](https://meta-cloud-api.site/) for the full list of handlers.
 
 ## Requirements
 
-- **Node.js** 18 LTS or later
+- **Node.js** 20.12+, **Bun**, **Deno**, **Cloudflare Workers** or **Vercel Edge** — no runtime dependencies, no `node:*` imports ([runtime guide](https://meta-cloud-api.site/guides/runtimes))
 - **TypeScript** 4.5+ (for TypeScript projects)
 
 ## Resources