meta-cloud-api 0.0.3 → 0.0.4

package/README.md

@@ -0,0 +1,216 @@
+# Meta Cloud API
+
+A TypeScript SDK for the Meta Cloud API that provides a clean, strongly-typed interface for interacting with WhatsApp's Cloud API and other Meta platform services.
+
+[![npm version](https://img.shields.io/npm/v/meta-cloud-api.svg)](https://www.npmjs.com/package/meta-cloud-api)
+[![npm downloads](https://img.shields.io/npm/dm/meta-cloud-api.svg)](https://www.npmjs.com/package/meta-cloud-api)
+[![GitHub license](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/froggy1014/meta-cloud-api/blob/main/LICENSE)
+
+## Features
+
+- **Strongly Typed**: Full TypeScript support with comprehensive type definitions
+- **Modular Design**: API components are organized logically for ease of use
+- **Error Handling**: Standardized error handling for Meta API responses
+- **Complete API Coverage**: Support for all WhatsApp Cloud API functionality
+  - Messages API (text, templates, media, interactive, etc.)
+  - Templates API
+  - Media API
+  - Phone Number API
+  - Flow API
+  - QR Code API
+  - Registration API
+  - WABA (WhatsApp Business Account) API
+  - Two-Step Verification API
+  - Encryption API
+
+## Installation
+
+```bash
+npm install meta-cloud-api
+# or
+yarn add meta-cloud-api
+# or
+pnpm add meta-cloud-api
+```
+
+## Quick Start
+
+```typescript
+import WhatsApp from 'meta-cloud-api';
+
+// Initialize with configuration object
+const whatsapp = new WhatsApp({
+  phoneNumberId: YOUR_PHONE_NUMBER_ID,
+  accessToken: 'YOUR_ACCESS_TOKEN'
+});
+
+// You can also use environment variables (.env file)
+// const whatsapp = new WhatsApp();
+
+// Send a text message
+async function sendMessage() {
+  try {
+    const response = await whatsapp.messages.text(
+      { body: "Hello from Meta Cloud API!" },
+      15551234567
+    );
+    console.log(`Message sent successfully with ID: ${response.messages[0].id}`);
+  } catch (error) {
+    console.error('Error sending message:', error);
+  }
+}
+```
+
+## Environment Variables
+
+Create a `.env` file with your WhatsApp Cloud API credentials:
+
+```
+WA_BASE_URL=graph.facebook.com
+M4D_APP_ID=your_app_id
+M4D_APP_SECRET=your_app_secret
+WA_PHONE_NUMBER_ID=your_phone_number_id
+WA_BUSINESS_ACCOUNT_ID=your_business_account_id
+CLOUD_API_ACCESS_TOKEN=your_access_token
+CLOUD_API_VERSION=17.0
+```
+
+## API Documentation
+
+### Messages API
+
+Send various types of WhatsApp messages:
+
+```typescript
+// Text message
+await whatsapp.messages.text(
+  { body: "Hello world!" },
+  15551234567
+);
+
+// Image message
+await whatsapp.messages.image(
+  { link: "https://example.com/image.jpg" },
+  15551234567
+);
+
+// Document message
+await whatsapp.messages.document(
+  { 
+    link: "https://example.com/document.pdf",
+    filename: "Important Document.pdf"
+  },
+  15551234567
+);
+
+// Template message
+await whatsapp.messages.template(
+  {
+    name: "sample_shipping_confirmation",
+    language: { code: "en_US" },
+    components: [
+      {
+        type: "body",
+        parameters: [
+          { type: "text", text: "John" },
+          { type: "text", text: "12345" }
+        ]
+      }
+    ]
+  },
+  15551234567
+);
+
+// Interactive message with buttons
+await whatsapp.messages.interactive(
+  {
+    type: "button",
+    body: { text: "Please select an option:" },
+    action: {
+      buttons: [
+        { type: "reply", reply: { id: "btn1", title: "Option 1" } },
+        { type: "reply", reply: { id: "btn2", title: "Option 2" } }
+      ]
+    }
+  },
+  15551234567
+);
+```
+
+### Templates API
+
+Work with message templates:
+
+```typescript
+// Get all templates
+const templates = await whatsapp.template.getTemplates({
+  limit: 20
+});
+
+// Create a new template
+await whatsapp.template.createTemplate({
+  name: "my_template",
+  category: "MARKETING",
+  language: "en_US",
+  components: [
+    {
+      type: "HEADER",
+      format: "TEXT",
+      text: "Special Offer"
+    },
+    {
+      type: "BODY",
+      text: "Hi {{1}}, check out our latest offer: {{2}}!"
+    }
+  ]
+});
+```
+
+### Media API
+
+Handle media files:
+
+```typescript
+// Upload media
+const mediaResponse = await whatsapp.media.uploadMedia(
+  new File(['...'], 'image.jpg', { type: 'image/jpeg' })
+);
+
+// Get media details
+const mediaDetails = await whatsapp.media.getMediaById(mediaResponse.id);
+
+// Delete media
+await whatsapp.media.deleteMedia(mediaResponse.id);
+```
+
+## Error Handling
+
+The package provides standard error handling for Meta API responses:
+
+```typescript
+try {
+  await whatsapp.messages.text(
+    { body: "Hello world!" },
+    15551234567
+  );
+} catch (error) {
+  if (error.name === 'MetaError') {
+    console.error(`Meta API Error: ${error.error.message}`);
+    console.error(`Error Code: ${error.error.code}`);
+    
+    if (error.error.error_data) {
+      console.error(`Details: ${error.error.error_data.details}`);
+    }
+  } else {
+    console.error('Unexpected error:', error);
+  }
+}
+```
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](https://github.com/froggy1014/meta-cloud-api/blob/main/LICENSE) file for details.
+
+## Contributing
+
+Contributions welcome! Please feel free to submit a Pull Request. 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "meta-cloud-api",
-  "version": "0.0.3",
+  "version": "0.0.4",
   "description": "TypeScript SDK for WhatsApp Cloud API - simplified integration with Meta's WhatsApp Business Platform",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -32,7 +32,7 @@
   },
   "files": [
     "dist",
-    "src"
+    "README.md"
   ],
   "engines": {
     "node": ">=20"

package/src/api/base.ts

@@ -1,19 +0,0 @@
-import Logger from '../utils/logger';
-import type { BaseClass } from '../types/base';
-import type { WabaConfigType } from '../types/config';
-import type { RequesterClass } from '../types/request';
-
-const LIB_NAME = 'BaseAPI';
-const LOG_LOCAL = false;
-const LOGGER = new Logger(LIB_NAME, process.env.DEBUG === 'true' || LOG_LOCAL);
-
-export default class BaseAPI implements BaseClass {
-    protected config: WabaConfigType;
-    protected client: RequesterClass;
-
-    constructor(config: WabaConfigType, client: RequesterClass) {
-        this.config = config;
-        this.client = client;
-        LOGGER.log('Initialized with HTTPSClient');
-    }
-}

package/src/api/encryption.ts

@@ -1,34 +0,0 @@
-import { HttpMethodsEnum, WabaConfigEnum } from '../types/enums';
-import type { WabaConfigType } from '../types/config';
-import type { RequesterClass, RequesterResponseInterface, ResponseSuccess } from '../types/request';
-import BaseAPI from './base';
-import type { EncryptionClass, EncryptionPublicKeyResponse } from '../types/encryption';
-
-export default class EncryptionAPI extends BaseAPI implements EncryptionClass {
-    private readonly endpoint = 'whatsapp_business_encryption';
-
-    constructor(config: WabaConfigType, client: RequesterClass) {
-        super(config, client);
-    }
-
-    async getEncryptionPublicKey(): Promise<RequesterResponseInterface<EncryptionPublicKeyResponse>> {
-        return this.client.sendRequest(
-            HttpMethodsEnum.Get,
-            `${this.config[WabaConfigEnum.PhoneNumberId]}/${this.endpoint}`,
-            this.config[WabaConfigEnum.RequestTimeout],
-            null,
-        );
-    }
-
-    async setEncryptionPublicKey(businessPublicKey: string): Promise<RequesterResponseInterface<ResponseSuccess>> {
-        const formData = new FormData();
-        formData.append('business_public_key', businessPublicKey);
-
-        return this.client.sendRequest(
-            HttpMethodsEnum.Post,
-            `${this.config[WabaConfigEnum.PhoneNumberId]}/${this.endpoint}`,
-            this.config[WabaConfigEnum.RequestTimeout],
-            formData,
-        );
-    }
-}

package/src/api/flow.ts

@@ -1,253 +0,0 @@
-import BaseAPI from './base';
-import { WabaConfigType } from '../types/config';
-import { HttpMethodsEnum, WabaConfigEnum } from '../types/enums';
-import { RequesterClass, RequesterResponseInterface, ResponseSuccess } from '../types/request';
-import {
-    FlowClass,
-    FlowsListResponse,
-    FlowCategoryEnum,
-    Flow,
-    FlowPreviewResponse,
-    FlowAssetsResponse,
-    FlowValidationError,
-    FlowMigrationResponse,
-} from '../types/flow';
-import Logger from '../utils/logger';
-
-const LIB_NAME = 'FlowAPI';
-const LOG_LOCAL = false;
-const LOGGER = new Logger(LIB_NAME, process.env.DEBUG === 'true' || LOG_LOCAL);
-
-export default class FlowAPI extends BaseAPI implements FlowClass {
-    constructor(config: WabaConfigType, client: RequesterClass) {
-        super(config, client);
-        LOGGER.log('FlowAPI initialized');
-    }
-
-    /**
-     * List Flows
-     *
-     * @param wabaId - The WABA ID
-     * @returns Promise with the list of flows
-     */
-    async listFlows(wabaId: string): Promise<RequesterResponseInterface<FlowsListResponse>> {
-        return this.client.sendRequest(
-            HttpMethodsEnum.Get,
-            `/${wabaId}/flows`,
-            this.config[WabaConfigEnum.RequestTimeout],
-            null,
-        );
-    }
-
-    /**
-     * Create Flow
-     *
-     * @param wabaId - The WABA ID
-     * @param data - The flow data including name, categories, endpoint_uri, and optional clone_flow_id
-     * @returns Promise with the created flow ID
-     */
-    async createFlow(
-        wabaId: string,
-        data: {
-            name: string;
-            categories?: FlowCategoryEnum[];
-            endpoint_uri?: string;
-            clone_flow_id?: string;
-            flow_json?: string;
-            publish?: boolean;
-        },
-    ): Promise<
-        RequesterResponseInterface<{ id: string; success: boolean; validation_errors?: FlowValidationError[] }>
-    > {
-        const formData = new FormData();
-
-        if (data.name) formData.append('name', data.name);
-        if (data.categories) formData.append('categories', JSON.stringify(data.categories));
-        if (data.endpoint_uri) formData.append('endpoint_uri', data.endpoint_uri);
-        if (data.clone_flow_id) formData.append('clone_flow_id', data.clone_flow_id);
-        if (data.flow_json) formData.append('flow_json', data.flow_json);
-        if (data.publish !== undefined) formData.append('publish', String(data.publish));
-
-        return this.client.sendRequest(
-            HttpMethodsEnum.Post,
-            `/${wabaId}/flows`,
-            this.config[WabaConfigEnum.RequestTimeout],
-            formData,
-        );
-    }
-
-    /**
-     * Get Flow
-     *
-     * @param flowId - The flow ID
-     * @param fields - Optional fields to return
-     * @param dateFormat - Optional date format
-     * @returns Promise with the flow details
-     */
-    async getFlow(
-        flowId: string,
-        fields?: string,
-        dateFormat?: string,
-    ): Promise<RequesterResponseInterface<Flow | FlowPreviewResponse>> {
-        const params = new URLSearchParams();
-        if (fields) params.append('fields', fields);
-        if (dateFormat) params.append('date_format', dateFormat);
-
-        const queryString = params.toString() ? `?${params.toString()}` : '';
-        return this.client.sendRequest(
-            HttpMethodsEnum.Get,
-            `/${flowId}${queryString}`,
-            this.config[WabaConfigEnum.RequestTimeout],
-            null,
-        );
-    }
-
-    /**
-     * Update Flow Metadata
-     *
-     * @param flowId - The flow ID
-     * @param data - The flow metadata to update
-     * @returns Promise with the success status
-     */
-    async updateFlowMetadata(
-        flowId: string,
-        data: {
-            name?: string;
-            categories?: FlowCategoryEnum[];
-            endpoint_uri?: string;
-            application_id?: string;
-        },
-    ): Promise<RequesterResponseInterface<ResponseSuccess>> {
-        const formData = new FormData();
-
-        if (data.name) formData.append('name', data.name);
-        if (data.categories) formData.append('categories', JSON.stringify(data.categories));
-        if (data.endpoint_uri) formData.append('endpoint_uri', data.endpoint_uri);
-        if (data.application_id) formData.append('application_id', data.application_id);
-
-        return this.client.sendRequest(
-            HttpMethodsEnum.Post,
-            `/${flowId}`,
-            this.config[WabaConfigEnum.RequestTimeout],
-            formData,
-        );
-    }
-
-    /**
-     * Delete Flow
-     *
-     * @param flowId - The flow ID
-     * @returns Promise with the success status
-     */
-    async deleteFlow(flowId: string): Promise<RequesterResponseInterface<ResponseSuccess>> {
-        return this.client.sendRequest(
-            HttpMethodsEnum.Delete,
-            `/${flowId}`,
-            this.config[WabaConfigEnum.RequestTimeout],
-            null,
-        );
-    }
-
-    /**
-     * List Assets (Get Flow JSON URL)
-     *
-     * @param flowId - The flow ID
-     * @returns Promise with the list of assets
-     */
-    async listAssets(flowId: string): Promise<RequesterResponseInterface<FlowAssetsResponse>> {
-        return this.client.sendRequest(
-            HttpMethodsEnum.Get,
-            `/${flowId}/assets`,
-            this.config[WabaConfigEnum.RequestTimeout],
-            null,
-        );
-    }
-
-    /**
-     * Update Flow JSON
-     *
-     * @param flowId - The flow ID
-     * @param data - The asset data including asset_type, file, and name
-     * @returns Promise with the success status and validation errors
-     */
-    async updateFlowJson(
-        flowId: string,
-        data: {
-            asset_type: 'FLOW_JSON';
-            file: Blob;
-            name: string;
-        },
-    ): Promise<RequesterResponseInterface<{ success: boolean; validation_errors?: FlowValidationError[] }>> {
-        const formData = new FormData();
-
-        formData.append('asset_type', data.asset_type);
-        formData.append('file', data.file);
-        formData.append('name', data.name);
-
-        return this.client.sendRequest(
-            HttpMethodsEnum.Post,
-            `/${flowId}/assets`,
-            this.config[WabaConfigEnum.RequestTimeout],
-            formData,
-        );
-    }
-
-    /**
-     * Publish Flow
-     *
-     * @param flowId - The flow ID
-     * @returns Promise with the success status
-     */
-    async publishFlow(flowId: string): Promise<RequesterResponseInterface<ResponseSuccess>> {
-        return this.client.sendRequest(
-            HttpMethodsEnum.Post,
-            `/${flowId}/publish`,
-            this.config[WabaConfigEnum.RequestTimeout],
-            JSON.stringify({}),
-        );
-    }
-
-    /**
-     * Deprecate Flow
-     *
-     * @param flowId - The flow ID
-     * @returns Promise with the success status
-     */
-    async deprecateFlow(flowId: string): Promise<RequesterResponseInterface<ResponseSuccess>> {
-        return this.client.sendRequest(
-            HttpMethodsEnum.Post,
-            `/${flowId}/deprecate`,
-            this.config[WabaConfigEnum.RequestTimeout],
-            JSON.stringify({}),
-        );
-    }
-
-    /**
-     * Migrate Flows
-     *
-     * @param wabaId - The destination WABA ID
-     * @param data - The migration data including source_waba_id and optional source_flow_names
-     * @returns Promise with migration results
-     */
-    async migrateFlows(
-        wabaId: string,
-        data: {
-            source_waba_id: string;
-            source_flow_names?: string[];
-        },
-    ): Promise<RequesterResponseInterface<FlowMigrationResponse>> {
-        const formData = new FormData();
-
-        formData.append('source_waba_id', data.source_waba_id);
-        if (data.source_flow_names) {
-            formData.append('source_flow_names', JSON.stringify(data.source_flow_names));
-        }
-
-        return this.client.sendRequest(
-            HttpMethodsEnum.Post,
-            `/${wabaId}/migrate_flows`,
-            this.config[WabaConfigEnum.RequestTimeout],
-            formData,
-        );
-    }
-}

package/src/api/index.ts

@@ -1,24 +0,0 @@
-import MessagesAPI from './messages';
-import BaseAPI from './base';
-import PhoneNumberAPI from './phoneNumber';
-import TemplateAPI from './template';
-import RegistrationAPI from './registration';
-import TwoStepVerificationAPI from './twoStepVerification';
-import QrCodeAPI from './qrCode';
-import EncryptionAPI from './encryption';
-import WabaAPI from './waba';
-import MediaAPI from './media';
-import FlowAPI from './flow';
-export {
-    MessagesAPI,
-    BaseAPI,
-    PhoneNumberAPI,
-    TemplateAPI,
-    RegistrationAPI,
-    TwoStepVerificationAPI,
-    QrCodeAPI,
-    EncryptionAPI,
-    WabaAPI,
-    MediaAPI,
-    FlowAPI,
-};

package/src/api/media.ts

@@ -1,52 +0,0 @@
-import { HttpMethodsEnum, WabaConfigEnum } from '../types/enums';
-import type { RequesterClass, RequesterResponseInterface, ResponseSuccess } from '../types/request';
-import type { WabaConfigType } from '../types/config';
-import type { MediaClass, MediaResponse, MediasResponse, UploadMediaResponse } from '../types/media';
-import BaseAPI from './base';
-
-export default class MediaAPI extends BaseAPI implements MediaClass {
-    private readonly endpoint = 'media';
-
-    constructor(config: WabaConfigType, client: RequesterClass) {
-        super(config, client);
-    }
-
-    async getMediaById(mediaId: string): Promise<RequesterResponseInterface<MediaResponse>> {
-        return this.client.sendRequest(
-            HttpMethodsEnum.Get,
-            `${mediaId}`,
-            this.config[WabaConfigEnum.RequestTimeout],
-            null,
-        );
-    }
-
-    async uploadMedia(
-        file: File,
-        messagingProduct: string = 'whatsapp',
-    ): Promise<RequesterResponseInterface<UploadMediaResponse>> {
-        const formData = new FormData();
-        formData.append('file', file);
-        formData.append('messaging_product', messagingProduct);
-        formData.append('type', file.type);
-
-        return this.client.sendRequest(
-            HttpMethodsEnum.Post,
-            `${this.config[WabaConfigEnum.PhoneNumberId]}/${this.endpoint}`,
-            this.config[WabaConfigEnum.RequestTimeout],
-            formData,
-        );
-    }
-
-    async deleteMedia(mediaId: string): Promise<RequesterResponseInterface<ResponseSuccess>> {
-        return this.client.sendRequest(
-            HttpMethodsEnum.Delete,
-            `${mediaId}`,
-            this.config[WabaConfigEnum.RequestTimeout],
-            null,
-        );
-    }
-
-    async downloadMedia(mediaUrl: string): Promise<RequesterResponseInterface<Blob>> {
-        return this.client.sendRequest(HttpMethodsEnum.Get, mediaUrl, this.config[WabaConfigEnum.RequestTimeout], null);
-    }
-}