meta-cloud-api 0.0.1-beta.0 → 0.0.2

package/src/types/template.ts

@@ -0,0 +1,134 @@
+import { CategoryEnum, LanguagesEnum, TemplateStatusEnum } from './enums';
+import { GeneralRequestBody, RequesterResponseInterface, ResponsePagination, ResponseSuccess } from './request';
+
+export type TemplateFormat = 'TEXT' | 'IMAGE' | 'VIDEO' | 'DOCUMENT' | 'LOCATION';
+
+export type PhoneNumberButton = {
+    type: 'PHONE_NUMBER';
+    text: string; // max 25 chars
+    phone_number: string; // max 20 chars
+};
+
+export type URLButton = {
+    type: 'URL';
+    text: string; // max 25 chars
+    url: string; // max 2000 chars
+    example?: string[]; // Required if url contains variable
+};
+
+export type QuickReplyButton = {
+    type: 'QUICK_REPLY';
+    text: string; // max 25 chars
+};
+
+export type CopyCodeButton = {
+    type: 'COPY_CODE';
+    example: string; // max 15 chars
+};
+
+export type FlowButton = {
+    type: 'FLOW';
+    text: string; // max 25 chars
+    flow_id?: string;
+    flow_name?: string;
+    flow_json?: string;
+    flow_action?: 'navigate' | 'data_exchange';
+    navigate_screen?: string;
+};
+
+export type MPMButton = {
+    type: 'MPM';
+};
+
+export type OTPButton = {
+    type: 'OTP';
+};
+
+export type SPMButton = {
+    type: 'SPM';
+};
+
+export type TemplateButton =
+    | PhoneNumberButton
+    | URLButton
+    | QuickReplyButton
+    | CopyCodeButton
+    | FlowButton
+    | MPMButton
+    | OTPButton
+    | SPMButton;
+
+export type TemplateHeaderExample = {
+    header_text?: string[];
+    header_text_named_params?: Array<{
+        param_name: string;
+        example: string;
+    }>;
+    header_handle?: string[];
+};
+
+export type TemplateHeader = {
+    type: 'HEADER';
+    format: TemplateFormat;
+    text?: string; // max 60 chars
+    example?: TemplateHeaderExample;
+};
+
+export type TemplateBody = {
+    type: 'BODY';
+    text: string; // max 1024 chars
+    example?: {
+        body_text?: Array<Array<string>>; // For positional parameters
+        body_text_named_params?: Array<{
+            param_name: string; // lowercase letters and underscores only
+            example: string;
+        }>; // For named parameters
+    };
+};
+
+export type TemplateFooter = {
+    type: 'FOOTER';
+    text: string; // max 60 chars
+};
+
+export type ComponentTypes = TemplateHeader | TemplateBody | TemplateFooter | TemplateButton;
+
+export type TemplateRequestBody = GeneralRequestBody & {
+    name: string;
+    language: LanguagesEnum;
+    category?: CategoryEnum;
+    components?: ComponentTypes[];
+};
+
+export type TemplateResponse = {
+    id: string;
+    status: string;
+    language: LanguagesEnum;
+    category: CategoryEnum;
+    name: string;
+    components: ComponentTypes[];
+};
+
+export type TemplateGetParams = {
+    limit?: number;
+    name?: string;
+    language?: LanguagesEnum;
+    category?: CategoryEnum;
+    status?: TemplateStatusEnum;
+};
+
+export type TemplateDeleteParams = {
+    hsm_id: string;
+    name: string;
+};
+
+export declare class TemplateClass {
+    getTemplate(templateId: string): Promise<RequesterResponseInterface<TemplateResponse>>;
+    updateTemplate(
+        templateId: string,
+        template: Partial<TemplateRequestBody>,
+    ): Promise<RequesterResponseInterface<ResponseSuccess>>;
+    getTemplates(params: TemplateGetParams): Promise<RequesterResponseInterface<ResponsePagination<TemplateResponse>>>;
+    createTemplate(template: TemplateRequestBody): Promise<RequesterResponseInterface<TemplateResponse>>;
+    deleteTemplate(params: TemplateDeleteParams): Promise<RequesterResponseInterface<ResponseSuccess>>;
+}

package/src/types/twoStepVerification.ts

@@ -0,0 +1,9 @@
+import { RequesterResponseInterface, ResponseSuccess } from './request';
+
+export type TwoStepVerificationRequest = {
+    pin: string;
+};
+
+export interface TwoStepVerificationClass {
+    setTwoStepVerificationCode(pin: string): Promise<RequesterResponseInterface<ResponseSuccess>>;
+}

package/src/types/waba.ts

@@ -0,0 +1,18 @@
+import { RequesterResponseInterface, ResponseData, ResponseSuccess } from './request';
+
+export type WabaSubscription = {
+    whatsapp_business_api_data: {
+        id: string;
+        link: string;
+        name: string;
+    };
+};
+
+export type WabaSubscriptions = ResponseData<Array<WabaSubscription>>;
+
+export declare class WABAClass {
+    getAllWabaSubscriptions(): Promise<RequesterResponseInterface<WabaSubscriptions>>;
+    subscribeToWaba(): Promise<RequesterResponseInterface<ResponseSuccess>>;
+    unsubscribeFromWaba(): Promise<RequesterResponseInterface<ResponseSuccess>>;
+    overrideWabaWebhook(webhookUrl: string, verifyToken: string): Promise<RequesterResponseInterface<ResponseSuccess>>;
+}

package/src/types/whatsapp.ts

@@ -0,0 +1,31 @@
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ * All rights reserved.
+ *
+ * This source code is licensed under the license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+export type WhatsAppConfig = {
+    accessToken: string;
+    baseUrl?: string;
+    appId?: string;
+    appSecret?: string;
+    phoneNumberId?: number;
+    businessAcctId?: string;
+    apiVersion?: string;
+    webhookEndpoint?: string;
+    webhookVerificationToken?: string;
+    listenerPort?: number;
+    debug?: boolean;
+    maxRetriesAfterWait?: number;
+    requestTimeout?: number;
+};
+
+export declare class WhatsAppClass {
+    constructor(config?: WhatsAppConfig);
+    updateTimeout(ms: number): boolean;
+    updatePhoneNumberId(phoneNumberId: number): boolean;
+    updateAccessToken(accessToken: string): boolean;
+    updateWabaId(wabaId: string): boolean;
+}

package/src/utils/generateXHub256Sig.ts

@@ -0,0 +1,5 @@
+import * as crypto from 'crypto';
+
+export const generateXHub256Sig = (body: string, appSecret: string) => {
+    return crypto.createHmac('sha256', appSecret).update(body, 'utf-8').digest('hex');
+};

package/src/utils/importConfig.ts

@@ -0,0 +1,55 @@
+import Logger from './logger';
+import type { WabaConfigType } from '../types/config';
+import { WabaConfigEnum } from '../types/enums';
+import { WhatsAppConfig } from 'src/types/whatsapp';
+
+const LIB_NAME = 'UTILS';
+const LOG_LOCAL = false;
+const LOGGER = new Logger(LIB_NAME, process.env.DEBUG === 'true' || LOG_LOCAL);
+const DEFAULT_BASE_URL = 'graph.facebook.com';
+const DEFAULT_APIVersion = 'v22.0';
+const DEFAULT_LISTENER_PORT = 3000;
+const DEFAULT_MAX_RETRIES_AFTER_WAIT = 30;
+const DEFAULT_REQUEST_TIMEOUT = 20000;
+
+const emptyConfigChecker = (phoneNumberId?: number, accessToken?: string) => {
+    if (!process.env[WabaConfigEnum.PhoneNumberId] && !phoneNumberId) {
+        LOGGER.log(`Environmental variable: WA_PHONE_NUMBER_ID and/or sender phone number id argument is undefined.`);
+        throw new Error('Missing WhatsApp sender phone number Id.');
+    }
+
+    if (!process.env[WabaConfigEnum.AccessToken] && !accessToken) {
+        LOGGER.log(`Environmental variable: CLOUD_API_ACCESS_TOKEN and/or access token argument is undefined.`);
+        throw new Error('Missing WhatsApp access token.');
+    }
+
+    if (!process.env[WabaConfigEnum.APIVersion]) {
+        LOGGER.log(`Environmental variable: CLOUD_API_VERSION is undefined.`);
+        throw new Error('Missing WhatsApp API version.');
+    }
+};
+
+export const importConfig = (inputConfig?: WhatsAppConfig) => {
+    emptyConfigChecker(inputConfig?.phoneNumberId, inputConfig?.accessToken);
+
+    const wabaConfig: WabaConfigType = {
+        [WabaConfigEnum.BaseURL]: process.env.WA_BASE_URL || DEFAULT_BASE_URL,
+        [WabaConfigEnum.AppId]: process.env.M4D_APP_ID || '',
+        [WabaConfigEnum.AppSecret]: process.env.M4D_APP_SECRET || '',
+        [WabaConfigEnum.PhoneNumberId]: inputConfig?.phoneNumberId || parseInt(process.env.WA_PHONE_NUMBER_ID || ''),
+        [WabaConfigEnum.BusinessAcctId]: process.env.WA_BUSINESS_ACCOUNT_ID || '',
+        [WabaConfigEnum.APIVersion]: process.env.CLOUD_API_VERSION || DEFAULT_APIVersion,
+        [WabaConfigEnum.AccessToken]: inputConfig?.accessToken || process.env.CLOUD_API_ACCESS_TOKEN || '',
+        [WabaConfigEnum.WebhookEndpoint]: process.env.WEBHOOK_ENDPOINT || '',
+        [WabaConfigEnum.WebhookVerificationToken]: process.env.WEBHOOK_VERIFICATION_TOKEN || '',
+        [WabaConfigEnum.ListenerPort]: parseInt(process.env.LISTENER_PORT || '') || DEFAULT_LISTENER_PORT,
+        [WabaConfigEnum.MaxRetriesAfterWait]:
+            parseInt(process.env.MAX_RETRIES_AFTER_WAIT || '') || DEFAULT_MAX_RETRIES_AFTER_WAIT,
+        [WabaConfigEnum.RequestTimeout]: parseInt(process.env.REQUEST_TIMEOUT || '') || DEFAULT_REQUEST_TIMEOUT,
+        [WabaConfigEnum.Debug]: process.env.DEBUG === 'true',
+    };
+
+    LOGGER.log(`Configuration loaded for App Id ${wabaConfig[WabaConfigEnum.AppId]}`);
+
+    return wabaConfig;
+};

package/src/utils/index.ts

@@ -0,0 +1,2 @@
+export * from './isMetaError';
+export * from './importConfig';

package/src/utils/isMetaError.ts

@@ -0,0 +1,44 @@
+export interface MetaError extends Error {
+    error: {
+        message: string;
+        type: string;
+        code: number;
+        error_data?: {
+            messaging_product: 'whatsapp';
+            details: string;
+        };
+        error_subcode?: number;
+        fbtrace_id: string;
+    };
+}
+
+/**
+ * Determines if the error is a Meta API error response
+ * @param error Any error object to check
+ * @returns Type guard indicating if error is a Meta API error
+ */
+export function isMetaError(error: any): error is MetaError {
+    return (
+        error != null &&
+        typeof error === 'object' &&
+        'error' in error &&
+        typeof error.error === 'object' &&
+        error.error != null &&
+        'message' in error.error &&
+        typeof error.error.message === 'string' &&
+        'type' in error.error &&
+        typeof error.error.type === 'string' &&
+        'code' in error.error &&
+        typeof error.error.code === 'number' &&
+        'fbtrace_id' in error.error &&
+        typeof error.error.fbtrace_id === 'string' &&
+        (!('error_data' in error.error) ||
+            (typeof error.error.error_data === 'object' &&
+                error.error.error_data != null &&
+                'messaging_product' in error.error.error_data &&
+                error.error.error_data.messaging_product === 'whatsapp' &&
+                'details' in error.error.error_data &&
+                typeof error.error.error_data.details === 'string')) &&
+        (!('error_subcode' in error.error) || typeof error.error.error_subcode === 'number')
+    );
+}

package/src/utils/logger.ts

@@ -0,0 +1,46 @@
+// @ts-nocheck
+import type { LoggerInterface } from '../types/logger';
+
+export default class Logger implements LoggerInterface {
+    private name: string;
+    private debug: boolean;
+
+    constructor(name: string, debug: boolean = false) {
+        this.name = name;
+        this.debug = debug;
+    }
+
+    log(...data: any[]) {
+        if (this.debug) {
+            let prefix = `[ ${Date.now()} ]`;
+            if (this.name) {
+                prefix += ` - ${this.name}`;
+            }
+            console.log.apply(console, [prefix, ': ', ...data]);
+        }
+    }
+
+    error(...data: any[]) {
+        let prefix = `[ ${Date.now()} ] - ERROR`;
+        if (this.name) {
+            prefix += ` - ${this.name}`;
+        }
+        console.error.apply(console, [prefix, ': ', ...data]);
+    }
+
+    warn(...data: any[]) {
+        let prefix = `[ ${Date.now()} ] - WARN`;
+        if (this.name) {
+            prefix += ` - ${this.name}`;
+        }
+        console.warn.apply(console, [prefix, ': ', ...data]);
+    }
+
+    info(...data: any[]) {
+        let prefix = `[ ${Date.now()} ] - INFO`;
+        if (this.name) {
+            prefix += ` - ${this.name}`;
+        }
+        console.info.apply(console, [prefix, ': ', ...data]);
+    }
+}

package/src/utils/objectToQueryString.ts

@@ -0,0 +1,16 @@
+export const objectToQueryString = (params: Record<string, any>): string => {
+    if (!params || Object.keys(params).length === 0) {
+        return '';
+    }
+
+    const searchParams = new URLSearchParams();
+
+    for (const [key, value] of Object.entries(params)) {
+        if (value !== undefined) {
+            searchParams.append(key, String(value));
+        }
+    }
+
+    const queryString = searchParams.toString();
+    return queryString ? `?${queryString}` : '';
+};

package/src/whatsapp.ts

@@ -0,0 +1,96 @@
+import { WabaConfigType } from './types/config';
+import * as SDKEnums from './types/enums';
+import Logger from './utils/logger';
+
+import { importConfig } from './utils/importConfig';
+import Requester from './request';
+import { WhatsAppClass, WhatsAppConfig } from './types/whatsapp';
+import {
+    MessagesAPI,
+    PhoneNumberAPI,
+    TemplateAPI,
+    QrCodeAPI,
+    EncryptionAPI,
+    TwoStepVerificationAPI,
+    RegistrationAPI,
+    MediaAPI,
+    WabaAPI,
+    FlowAPI,
+} from './api';
+
+const LIB_NAME = 'WHATSAPP';
+const LOG_LOCAL = false;
+const LOGGER = new Logger(LIB_NAME, process.env.DEBUG === 'true' || LOG_LOCAL);
+
+const headerPrefix = 'WA_SDK';
+
+export default class WhatsApp implements WhatsAppClass {
+    config: WabaConfigType;
+
+    requester: Readonly<Requester>;
+
+    readonly messages: MessagesAPI;
+    readonly templates: TemplateAPI;
+    readonly phoneNumber: PhoneNumberAPI;
+    readonly qrCode: QrCodeAPI;
+    readonly encryption: EncryptionAPI;
+    readonly twoStepVerification: TwoStepVerificationAPI;
+    readonly registration: RegistrationAPI;
+    readonly media: MediaAPI;
+    readonly waba: WabaAPI;
+    readonly flow: FlowAPI;
+    static readonly Enums = SDKEnums;
+
+    constructor(config?: WhatsAppConfig) {
+        this.config = importConfig(config);
+        this.requester = new Requester(
+            this.config[SDKEnums.WabaConfigEnum.BaseURL],
+            this.config[SDKEnums.WabaConfigEnum.APIVersion],
+            this.config[SDKEnums.WabaConfigEnum.PhoneNumberId],
+            this.config[SDKEnums.WabaConfigEnum.AccessToken],
+            this.config[SDKEnums.WabaConfigEnum.BusinessAcctId],
+            this.userAgent(),
+        );
+
+        this.messages = new MessagesAPI(this.config, this.requester);
+        this.templates = new TemplateAPI(this.config, this.requester);
+        this.phoneNumber = new PhoneNumberAPI(this.config, this.requester);
+        this.qrCode = new QrCodeAPI(this.config, this.requester);
+        this.encryption = new EncryptionAPI(this.config, this.requester);
+        this.twoStepVerification = new TwoStepVerificationAPI(this.config, this.requester);
+        this.registration = new RegistrationAPI(this.config, this.requester);
+        this.media = new MediaAPI(this.config, this.requester);
+        this.waba = new WabaAPI(this.config, this.requester);
+        this.flow = new FlowAPI(this.config, this.requester);
+        LOGGER.log('WhatsApp Node.js SDK instantiated!');
+    }
+
+    private userAgent(): string {
+        const userAgentString = `${headerPrefix}/${'0.0.1'} (Node.js ${process.version})`;
+        return userAgentString;
+    }
+
+    updateTimeout(ms: number): boolean {
+        this.config[SDKEnums.WabaConfigEnum.RequestTimeout] = ms;
+        LOGGER.log(`Updated request timeout to ${ms}ms`);
+        return true;
+    }
+
+    updatePhoneNumberId(phoneNumberId: number): boolean {
+        this.config[SDKEnums.WabaConfigEnum.PhoneNumberId] = phoneNumberId;
+        LOGGER.log(`Updated sender phone number id to ${phoneNumberId}`);
+        return true;
+    }
+
+    updateAccessToken(accessToken: string): boolean {
+        this.config[SDKEnums.WabaConfigEnum.AccessToken] = accessToken;
+        LOGGER.log(`Updated access token`);
+        return true;
+    }
+
+    updateWabaId(wabaId: string): boolean {
+        this.config[SDKEnums.WabaConfigEnum.BusinessAcctId] = wabaId;
+        LOGGER.log(`Updated business account id to ${wabaId}`);
+        return true;
+    }
+}