meta-cloud-api 1.7.3 → 2.0.1

package/README.md

@@ -13,16 +13,48 @@
 
 ## Resources
 
-- [Documentation](https://www.meta-cloud-api.xyz/)
+- **[📚 Documentation](https://www.meta-cloud-api.xyz/)** - Complete documentation with guides and examples
+- **[🚀 Getting Started](https://www.meta-cloud-api.xyz/getting-started/installation)** - Quick start guide
+- **[📖 API Reference](https://www.meta-cloud-api.xyz/api/messages)** - Comprehensive API documentation
+- **[🔧 Examples](./examples/)** - Production-ready code examples
+
+## Examples
+
+- **[express-simple](./examples/express-simple/)** - Basic Express.js integration
+- **[express-production](./examples/express-production/)** - Production-ready example with conversation flows, database, and queue processing
+- **[nextjs-app-router-example](./examples/nextjs-app-router-example/)** - Next.js App Router integration
+- **[nextjs-page-router-example](./examples/nextjs-page-router-example/)** - Next.js Pages Router integration
+
+## Local API Docs
+
+- [Messages](./docs/messages.md)
+- [Media](./docs/media.md)
+- [Templates](./docs/templates.md)
+- [Flows](./docs/flows.md)
+- [Phone Numbers](./docs/phone-numbers.md)
+- [Business Profile](./docs/business-profile.md)
+- [Registration](./docs/registration.md)
+- [Two-Step Verification](./docs/two-step-verification.md)
+- [Encryption](./docs/encryption.md)
+- [QR Codes](./docs/qr-codes.md)
+- [WABA](./docs/waba.md)
+- [Block Users](./docs/block-users.md)
+- [Calling](./docs/calling.md)
+- [Groups](./docs/groups.md)
+- [Marketing Messages](./docs/marketing-messages.md)
+- [Commerce Settings](./docs/commerce-settings.md)
+- [Payments](./docs/payments.md)
 
 ## Features
 
-- **Type-Safe Development** - Built with TypeScript to provide code completion and catch errors during development
-- **Comprehensive Coverage** - Full support for WhatsApp Business Platform APIs including Messages, Media, Templates, Flows, and more
-- **Modular Architecture** - Clean separation of concerns with dedicated API classes for each domain
-- **Framework-Specific Webhooks** - Built-in support for Express.js and Next.js webhook handling
-- **Advanced Features** - Support for Flows, Encryption, QR Codes, Two-Step Verification, and WABA management
-- **Error Handling** - Standardized error handling with detailed Meta API error information
+- **🔒 Type-Safe Development** - Built with TypeScript strict mode for complete type safety and excellent IntelliSense
+- **📦 Comprehensive Coverage** - Full support for 17+ WhatsApp Business Platform APIs including Messages, Media, Templates, Flows, and more
+- **🏗️ Modular Architecture** - Clean separation with dedicated API classes, tree-shakeable imports, and minimal bundle size
+- **🔌 Framework-Specific Webhooks** - Built-in adapters for Express.js and Next.js (App Router & Pages Router)
+- **⚡ Production Ready** - Battle-tested with error handling, retry logic, rate limiting, and comprehensive logging
+- **🎯 Advanced Features** - Support for Flows, End-to-End Encryption, QR Codes, Two-Step Verification, Groups, and WABA management
+- **📚 Excellent Documentation** - Complete documentation site with guides, API reference, and working examples
+- **🧪 Well Tested** - Comprehensive test coverage with unit, integration, and E2E tests
 
 ## Installation
 
@@ -34,525 +66,6 @@ yarn add meta-cloud-api
 pnpm add meta-cloud-api
 ```
 
-## Quick Start
-
-```typescript
-import WhatsApp, { MessageTypesEnum } from 'meta-cloud-api';
-
-// Initialize the client
-const client = new WhatsApp({
-  accessToken: process.env.CLOUD_API_ACCESS_TOKEN,
-  phoneNumberId: Number(process.env.WA_PHONE_NUMBER_ID),
-  businessAcctId: process.env.WA_BUSINESS_ACCOUNT_ID
-});
-
-// Send a WhatsApp text message
-const response = await client.messages.text({
-  to: '+1234567890',
-  body: 'Hello from Meta Cloud API!'
-});
-
-console.log(`Message ID: ${response.messages[0].id}`);
-```
-
-## Usage Examples
-
-### Messaging
-
-#### Text Message
-
-```typescript
-const result = await client.messages.text({
-  to: "15551234567",
-  body: "Hello from Meta Cloud API!"
-});
-```
-
-#### Template Message
-
-```typescript
-import { ComponentTypesEnum, LanguagesEnum, ParametersTypesEnum } from 'meta-cloud-api';
-
-const result = await client.messages.template({
-  to: "15551234567",
-  body: {
-    name: "shipping_confirmation",
-    language: {
-      code: LanguagesEnum.English_US,
-      policy: "deterministic"
-    },
-    components: [
-      {
-        type: ComponentTypesEnum.Body,
-        parameters: [
-          {
-            type: ParametersTypesEnum.Text,
-            text: "John Doe"
-          },
-          {
-            type: ParametersTypesEnum.Text,
-            text: "12345"
-          }
-        ]
-      }
-    ]
-  }
-});
-```
-
-#### Media Message
-
-```typescript
-const result = await client.messages.image({
-  to: "15551234567",
-  body: {
-    link: "https://example.com/image.jpg"
-  }
-});
-```
-
-#### Interactive Message
-
-```typescript
-import { InteractiveTypesEnum } from 'meta-cloud-api';
-
-const result = await client.messages.interactive({
-  to: "15551234567",
-  body: {
-    type: InteractiveTypesEnum.Button,
-    body: {
-      text: "What would you like to do?"
-    },
-    action: {
-      buttons: [
-        {
-          type: "reply",
-          reply: {
-            id: "help_button",
-            title: "Get Help"
-          }
-        },
-        {
-          type: "reply",
-          reply: {
-            id: "info_button",
-            title: "Account Info"
-          }
-        }
-      ]
-    }
-  }
-});
-```
-
-### Webhook Integration
-
-#### Express.js Webhook
-
-```typescript
-import express from 'express';
-import { MessageTypesEnum } from 'meta-cloud-api';
-import { webhookHandler } from 'meta-cloud-api/webhook/express';
-
-const app = express();
-
-// Create webhook handler
-const bot = webhookHandler({
-  accessToken: process.env.CLOUD_API_ACCESS_TOKEN!,
-  phoneNumberId: parseInt(process.env.WA_PHONE_NUMBER_ID!),
-  webhookVerificationToken: process.env.WEBHOOK_VERIFICATION_TOKEN!,
-});
-
-// Handle text messages
-bot.processor.onMessage(MessageTypesEnum.Text, async (whatsapp, message) => {
-  await whatsapp.messages.text({
-    to: message.from,
-    body: `Echo: ${message.text?.body}`,
-  });
-});
-
-// Setup webhook endpoints
-app.get('/webhook', bot.webhook);
-app.post('/webhook', express.json(), bot.webhook);
-
-app.listen(3000);
-```
-
-#### Next.js Webhook
-
-```typescript
-// pages/api/webhook.ts
-import { NextApiRequest, NextApiResponse } from 'next';
-import { MessageTypesEnum } from 'meta-cloud-api';
-import { webhookHandler } from 'meta-cloud-api/webhook/nextjs';
-
-const bot = webhookHandler({
-  accessToken: process.env.CLOUD_API_ACCESS_TOKEN!,
-  phoneNumberId: parseInt(process.env.WA_PHONE_NUMBER_ID!),
-  webhookVerificationToken: process.env.WEBHOOK_VERIFICATION_TOKEN!,
-});
-
-// Handle text messages
-bot.processor.onMessage(MessageTypesEnum.Text, async (whatsapp, message) => {
-  await whatsapp.messages.text({
-    to: message.from,
-    body: `Echo: ${message.text?.body}`,
-  });
-});
-
-export default async function handler(req: NextApiRequest, res: NextApiResponse) {
-  return bot.webhook(req, res);
-}
-```
-
-### Advanced Message Handling
-
-```typescript
-import { MessageTypesEnum } from 'meta-cloud-api';
-
-// Pre-process all messages (e.g., mark as read)
-// ✨ Use processed.messageId for consistent ID access across all message types
-bot.processor.onMessagePreProcess(async (whatsapp, processed) => {
-  // messageId is automatically extracted from the correct location
-  // (message.id for most types, message.context.id for nfm_reply)
-  await whatsapp.messages.markAsRead({ messageId: processed.messageId });
-});
-
-// ✨ Type-safe specialized handlers (recommended)
-// These methods provide better type safety - no need for optional chaining!
-
-bot.processor.onText(async (whatsapp, processed) => {
-  const { message, messageId } = processed;
-  // message.text is guaranteed to exist - no need for message.text?.body
-  console.log('Received:', message.text.body);
-  await whatsapp.messages.text({
-    to: message.from,
-    text: { body: `Echo: ${message.text.body}` }
-  });
-
-  // Mark as read using the extracted messageId
-  await whatsapp.messages.markAsRead({ messageId });
-});
-
-bot.processor.onImage(async (whatsapp, processed) => {
-  const { message } = processed;
-  // message.image is guaranteed to exist
-  console.log('Image ID:', message.image.id);
-  console.log('Caption:', message.image.caption);
-});
-
-bot.processor.onInteractive(async (whatsapp, processed) => {
-  const { message, messageId } = processed;
-  // message.interactive is guaranteed to exist
-  if (message.interactive.type === 'nfm_reply') {
-    const flowResponse = JSON.parse(message.interactive.nfm_reply.response_json);
-    console.log('Flow response:', flowResponse);
-
-    // messageId works correctly for nfm_reply (uses context.id automatically)
-    await whatsapp.messages.markAsRead({ messageId });
-  } else if (message.interactive.type === 'button_reply') {
-    console.log('Button clicked:', message.interactive.button_reply.id);
-  } else if (message.interactive.type === 'list_reply') {
-    console.log('List item selected:', message.interactive.list_reply.id);
-  }
-});
-
-// Other specialized handlers available:
-// onVideo, onAudio, onDocument, onSticker, onButton,
-// onLocation, onContacts, onReaction, onOrder, onSystem
-
-// 📝 Legacy generic handler (still supported)
-bot.processor.onMessage(MessageTypesEnum.Text, async (whatsapp, processed) => {
-  // With generic handler, you need optional chaining
-  console.log(processed.message.text?.body); // ⚠️ Need ? because text might be undefined
-
-  // But messageId is always available regardless of message type!
-  await whatsapp.messages.markAsRead({ messageId: processed.messageId });
-});
-
-// 🔍 TypeScript Discriminated Union for Manual Type Narrowing
-// Use this when you need to check message types dynamically in pre/post-process handlers
-bot.processor.onMessagePreProcess(async (whatsapp, processed) => {
-  const { message, messageId } = processed;
-
-  // TypeScript automatically narrows the type based on the type property!
-  if (message.type === MessageTypesEnum.Text) {
-    console.log(message.text.body); // ✅ No optional chaining needed!
-  } else if (message.type === MessageTypesEnum.Image) {
-    console.log(message.image.id); // ✅ Type-safe!
-  } else if (message.type === MessageTypesEnum.Interactive) {
-    console.log(message.interactive.type); // ✅ Guaranteed to exist!
-  }
-
-  // messageId works for all types - automatically extracted from the correct location
-  await whatsapp.messages.markAsRead({ messageId });
-});
-
-// Handle message status updates
-bot.processor.onMessageStatus(async (whatsapp, status) => {
-  console.log(`Message ${status.id} status: ${status.status}`);
-});
-```
-
-### Templates Management
-
-```typescript
-// List all templates
-const templates = await client.templates.list({
-  businessId: process.env.WA_BUSINESS_ACCOUNT_ID
-});
-
-// Create a new template
-const newTemplate = await client.templates.create({
-  businessId: process.env.WA_BUSINESS_ACCOUNT_ID,
-  name: "welcome_message",
-  category: "MARKETING",
-  components: [
-    {
-      type: "HEADER",
-      format: "TEXT",
-      text: "Welcome!"
-    },
-    {
-      type: "BODY",
-      text: "Hi {{1}}, welcome to our service!"
-    }
-  ],
-  language: "en_US"
-});
-```
-
-### Media Management
-
-```typescript
-import fs from 'fs';
-
-// Upload media
-const mediaUpload = await client.media.upload({
-  file: fs.createReadStream("./path/to/image.jpg"),
-  type: "image/jpeg"
-});
-
-// Get media URL
-const media = await client.media.get({
-  mediaId: mediaUpload.id
-});
-
-// Download media
-const mediaBuffer = await client.media.download({
-  mediaId: mediaUpload.id
-});
-```
-
-### Business Profile Management
-
-```typescript
-// Update business profile
-const profile = await client.businessProfile.update({
-  about: "We provide the best service!",
-  address: "123 Business St, City",
-  description: "Premium products and services",
-  email: "contact@business.com",
-  websites: ["https://www.business.com"]
-});
-
-// Get current profile
-const currentProfile = await client.businessProfile.get();
-```
-
-### Phone Number Management
-
-#### Conversational Automation
-
-Configure conversational components like Welcome Messages, Ice Breakers, and Commands to enhance user interactions:
-
-```typescript
-// Enable welcome message
-await client.phoneNumber.setConversationalAutomation({
-  enable_welcome_message: true
-});
-
-// Configure ice breakers (prompts) - up to 4, each max 80 characters
-await client.phoneNumber.setConversationalAutomation({
-  prompts: ['Book a flight', 'Plan a vacation', 'Find hotels', 'Get travel tips']
-});
-
-// Configure commands - up to 30, each command max 32 chars, description max 256 chars
-await client.phoneNumber.setConversationalAutomation({
-  commands: [
-    { command_name: 'tickets', command_description: 'Book flight tickets' },
-    { command_name: 'hotel', command_description: 'Book hotel rooms' },
-    { command_name: 'imagine', command_description: 'Create images using a text prompt' }
-  ]
-});
-
-// Configure all features at once
-await client.phoneNumber.setConversationalAutomation({
-  enable_welcome_message: true,
-  commands: [
-    { command_name: 'tickets', command_description: 'Book flight tickets' }
-  ],
-  prompts: ['Book a flight', 'Plan a vacation']
-});
-
-// Get current configuration
-const config = await client.phoneNumber.getConversationalAutomation();
-console.log('Welcome message enabled:', config.enable_welcome_message);
-console.log('Commands:', config.commands);
-console.log('Ice breakers:', config.prompts);
-```
-
-#### Phone Number Information
-
-```typescript
-// Get phone number details
-const phoneInfo = await client.phoneNumber.getPhoneNumberById();
-console.log('Display number:', phoneInfo.display_phone_number);
-console.log('Quality rating:', phoneInfo.quality_rating);
-console.log('Verified name:', phoneInfo.verified_name);
-
-// Get specific fields only
-const phoneDetails = await client.phoneNumber.getPhoneNumberById(
-  'display_phone_number,verified_name,code_verification_status'
-);
-```
-
-### Block Users Management
-
-```typescript
-// Block a user (only works for users who messaged you in last 24 hours)
-const blockResult = await client.blockUsers.block(['1234567890']);
-console.log('Blocked users:', blockResult.block_users.added_users);
-console.log('Failed to block:', blockResult.block_users.failed_users);
-
-// Block multiple users at once
-const multiBlockResult = await client.blockUsers.block([
-  '1234567890',
-  '0987654321',
-  '1122334455'
-]);
-
-// Unblock users
-const unblockResult = await client.blockUsers.unblock(['1234567890']);
-
-// Get list of blocked users with pagination
-const blockedUsers = await client.blockUsers.listBlockedUsers({
-  limit: 10
-});
-
-// Iterate through all blocked users
-let cursor: string | undefined;
-const allBlockedUsers = [];
-
-do {
-  const page = await client.blockUsers.listBlockedUsers({
-    limit: 100,
-    after: cursor
-  });
-
-  page.data.forEach(item => {
-    if (item.block_users) {
-      allBlockedUsers.push(...item.block_users);
-    }
-  });
-
-  cursor = page.paging?.cursors?.after;
-} while (cursor);
-
-console.log(`Total blocked users: ${allBlockedUsers.length}`);
-```
-
-### WhatsApp Flows
-
-```typescript
-// Create a flow
-const flow = await client.flows.create({
-  name: "Customer Survey",
-  categories: ["SURVEY"],
-  clone_flow_id: "existing_flow_id" // Optional
-});
-
-// Update flow
-const updatedFlow = await client.flows.update({
-  flowId: flow.id,
-  name: "Updated Survey",
-  categories: ["SURVEY", "FEEDBACK"]
-});
-```
-
-## Example Projects
-
-We provide ready-to-use example projects demonstrating integration with different frameworks:
-
-### [Express.js Echo Bot](./examples/express-example)
-A simple echo bot that responds to any text message. Perfect for getting started!
-
-```bash
-cd examples/express-example
-npm install
-cp env.example .env  # Configure your credentials
-npm run dev
-```
-
-### [Next.js Echo Bot](./examples/nextjs-page-router-example)
-Next.js implementation with API routes for webhook handling.
-
-```bash
-cd examples/nextjs-page-router-example
-npm install
-cp env.example .env.local  # Configure your credentials
-npm run dev
-```
-
-## Modular Imports
-
-Use specific imports for better tree-shaking:
-
-```typescript
-// Import specific API classes
-import { MessagesApi } from 'meta-cloud-api/messages';
-import { MediaApi } from 'meta-cloud-api/media';
-import { TemplateApi } from 'meta-cloud-api/template';
-
-// Import specific webhook handlers
-import { webhookHandler } from 'meta-cloud-api/webhook/express';
-import { webhookHandler } from 'meta-cloud-api/webhook/nextjs';
-
-// Import types and enums
-import { MessageTypesEnum, InteractiveTypesEnum } from 'meta-cloud-api/types/enums';
-import type { WhatsAppConfig } from 'meta-cloud-api/types/config';
-```
-
-## Configuration
-
-```typescript
-interface WhatsAppConfig {
-  accessToken: string;           // Required: Meta Cloud API access token
-  phoneNumberId: number;         // Required: WhatsApp phone number ID
-  businessAcctId?: string;       // Optional: Business account ID
-  apiVersion?: string;           // Optional: API version (default: v21.0)
-  webhookVerificationToken?: string; // Optional: For webhook verification
-  requestTimeout?: number;       // Optional: Request timeout in ms
-}
-```
-
-## Error Handling
-
-```typescript
-try {
-  const result = await client.messages.text({
-    to: "15551234567",
-    body: "Hello World"
-  });
-} catch (error) {
-  if (error.response?.data?.error) {
-    console.error('Meta API Error:', error.response.data.error);
-  } else {
-    console.error('Network Error:', error.message);
-  }
-}
-```
-
 ## Requirements
 
 - **Node.js** 18 LTS or later

package/dist/chunk.js

@@ -0,0 +1 @@
+var e=Object.defineProperty,t=(t,n)=>{let r={};for(var i in t)e(r,i,{get:t[i],enumerable:!0});return n||e(r,Symbol.toStringTag,{value:`Module`}),r};export{t};