meta-cloud-api 3.8.0 → 3.9.1

package/dist/utils/node/index.d.ts

@@ -0,0 +1,682 @@
+//#region src/utils/buildFieldsQueryString.d.ts
+declare function buildFieldsQueryString(fields?: string[] | string): string;
+//#endregion
+//#region src/utils/rateLimit.d.ts
+/**
+ * Usage percentages reported by Meta. Each value is the share (0-100+) of the allowance used in the
+ * current rolling window.
+ */
+interface RateLimitUsage {
+  /** Percentage of calls made (`call_count`). */
+  callCount?: number;
+  /** Percentage of total CPU time used (`total_cputime`). */
+  totalCputime?: number;
+  /** Percentage of total time used (`total_time`). */
+  totalTime?: number;
+}
+/** One entry of the `X-Business-Use-Case-Usage` header. */
+interface BusinessUseCaseUsage extends RateLimitUsage {
+  /** The business object the entry belongs to (for WhatsApp, usually the WABA or phone number ID). */
+  businessId: string;
+  /** Rate limit type, e.g. `whatsapp_business_management` or `whatsapp`. */
+  type?: string;
+  /**
+   * `estimated_time_to_regain_access`: "Time, in minutes, until calls will no longer be throttled."
+   * `0` when not throttled.
+   */
+  estimatedTimeToRegainAccessMinutes?: number;
+  /** `ads_api_access_tier`, only sent for Marketing API use cases. */
+  adsApiAccessTier?: string;
+}
+/**
+ * Rate limit information parsed from a Graph API response.
+ *
+ * WhatsApp Cloud API responses carry `x-business-use-case-usage` (types
+ * `whatsapp_business_management` and `whatsapp`) and `x-app-usage`; throttled responses may add
+ * `Retry-After` (seconds).
+ */
+interface RateLimitInfo {
+  /** Parsed `X-App-Usage` header (platform rate limits). */
+  appUsage?: RateLimitUsage;
+  /** Parsed `X-Business-Use-Case-Usage` header, flattened across business IDs. Empty when absent. */
+  businessUseCaseUsage: BusinessUseCaseUsage[];
+  /** Parsed `Retry-After` header in milliseconds (seconds or HTTP-date form). */
+  retryAfterMs?: number;
+  /**
+   * Highest usage percentage across every parsed metric, handy for alerting before Meta starts
+   * throttling (it throttles at 100).
+   */
+  maxUsagePercent?: number;
+  /**
+   * How long Meta asks you to wait, in milliseconds: the larger of `retryAfterMs` and the largest
+   * `estimatedTimeToRegainAccessMinutes`. Undefined when Meta gave no wait time.
+   */
+  retryDelayMs?: number;
+}
+/** Headers accepted by {@link parseRateLimitHeaders}. */
+type RateLimitHeadersInput = Headers | Record<string, string | string[] | undefined> | {
+  get(name: string): string | null;
+};
+/**
+ * Parses a `Retry-After` value (delta-seconds or HTTP-date) into milliseconds.
+ * Returns undefined for missing or malformed values.
+ */
+declare function parseRetryAfter(value: string | null | undefined, now?: number): number | undefined;
+/**
+ * Parses Meta's rate limit headers (`X-App-Usage`, `X-Business-Use-Case-Usage`, `Retry-After`).
+ * Header names are matched case-insensitively. Malformed JSON or values are ignored, never thrown.
+ *
+ * Returns undefined when none of the headers are present.
+ *
+ * @see {@link https://developers.facebook.com/docs/graph-api/overview/rate-limiting/ | Graph API rate limiting}
+ *
+ * @example
+ * ```ts
+ * const info = parseRateLimitHeaders(response.headers);
+ * if ((info?.maxUsagePercent ?? 0) > 80) slowDown();
+ * ```
+ */
+declare function parseRateLimitHeaders(headers: RateLimitHeadersInput | null | undefined): RateLimitInfo | undefined;
+//#endregion
+//#region src/types/enums.d.ts
+declare enum WabaConfigEnum {
+  AppId = "M4D_APP_ID",
+  Port = "WA_PORT",
+  AppSecret = "M4D_APP_SECRET",
+  PhoneNumberId = "WA_PHONE_NUMBER_ID",
+  BusinessAcctId = "WA_BUSINESS_ACCOUNT_ID",
+  APIVersion = "CLOUD_API_VERSION",
+  AccessToken = "CLOUD_API_ACCESS_TOKEN",
+  WebhookEndpoint = "WEBHOOK_ENDPOINT",
+  WebhookVerificationToken = "WEBHOOK_VERIFICATION_TOKEN",
+  ListenerPort = "LISTENER_PORT",
+  MaxRetriesAfterWait = "MAX_RETRIES_AFTER_WAIT",
+  RequestTimeout = "REQUEST_TIMEOUT",
+  Debug = "DEBUG",
+  PrivatePem = "FLOW_API_PRIVATE_PEM",
+  Passphrase = "FLOW_API_PASSPHRASE"
+}
+//#endregion
+//#region src/types/config.d.ts
+/**
+ * Configuration for automatic retry behavior on throttling errors.
+ *
+ * When the WhatsApp API returns a rate limit error (WhatsAppThrottlingError),
+ * the SDK will automatically retry the request using exponential backoff.
+ *
+ * @example
+ * ```typescript
+ * const wa = new WhatsApp({
+ *   accessToken: '...',
+ *   phoneNumberId: 123,
+ *   retry: { maxAttempts: 3, backoff: 'exponential', initialDelayMs: 1000 },
+ * });
+ * ```
+ */
+interface RetryConfig {
+  /**
+   * Maximum number of attempts (including the initial attempt).
+   * Defaults to 3.
+   */
+  maxAttempts?: number;
+  /**
+   * Backoff strategy.
+   * - 'exponential': delay doubles each attempt (1s → 2s → 4s)
+   * - 'fixed': constant delay between attempts
+   * Defaults to 'exponential'.
+   */
+  backoff?: 'exponential' | 'fixed';
+  /**
+   * Initial delay in milliseconds before the first retry.
+   * Defaults to 1000 (1 second).
+   */
+  initialDelayMs?: number;
+  /**
+   * Wait as long as Meta asks before retrying a throttled request. When a throttling response
+   * carries `Retry-After` (seconds) or `X-Business-Use-Case-Usage` with
+   * `estimated_time_to_regain_access` (minutes), the retry waits the larger of the backoff delay and
+   * that server delay, capped at {@link RetryConfig.maxServerDelayMs}. It never adds attempts.
+   * Defaults to `true`; set `false` to use the backoff delay only.
+   */
+  respectServerDelay?: boolean;
+  /**
+   * Upper bound in milliseconds for a server-provided wait. A longer wait is shortened to this
+   * value, so the retry may still be throttled; inspect `error.rateLimit` to reschedule instead.
+   * Defaults to 30000 (30 seconds).
+   */
+  maxServerDelayMs?: number;
+}
+/** Request details passed to {@link WhatsAppConfig.onRateLimitInfo}. */
+interface RateLimitInfoContext {
+  /** HTTP method of the request. */
+  method: string;
+  /** Endpoint path or absolute URL as passed to the requester. */
+  endpoint: string;
+  /** HTTP status code of the response. */
+  statusCode: number;
+}
+/** Callback receiving rate limit information parsed from every response that carries it. */
+type RateLimitInfoListener = (info: RateLimitInfo, context: RateLimitInfoContext) => void | Promise<void>;
+type WabaConfigType = {
+  /**
+   * The Meta for Developers business application Id for this registered application.
+   */
+  [WabaConfigEnum.AppId]: string;
+  /**
+   * The Meta for Developers business application secret for this registered application.
+   */
+  [WabaConfigEnum.AppSecret]: string;
+  /**
+   * The Meta for Developers phone number id used by the registered business.
+   */
+  [WabaConfigEnum.PhoneNumberId]: number;
+  /**
+   * The Meta for Developers business id for the registered business.
+   */
+  [WabaConfigEnum.BusinessAcctId]: string;
+  /**
+   * The version of the Cloud API being used. Starts with a "v" and follows the major number.
+   */
+  [WabaConfigEnum.APIVersion]: string;
+  /**
+   * The access token to make calls on behalf of the signed in Meta for Developers account or business.
+   */
+  [WabaConfigEnum.AccessToken]: string;
+  /**
+   * The endpoint path (e.g. if the value here is webhook, the webhook URL would look like http/https://{host}/webhook).
+   */
+  [WabaConfigEnum.WebhookEndpoint]: string;
+  /**
+   * The verification token that needs to match what is sent by the Cloud API webhook in order to subscribe.
+   */
+  [WabaConfigEnum.WebhookVerificationToken]: string;
+  /**
+   * The listener port for the webhook web server.
+   */
+  [WabaConfigEnum.ListenerPort]: number;
+  /**
+   * To turn on global debugging of the logger to print verbose output across the APIs.
+   */
+  [WabaConfigEnum.Debug]: boolean;
+  /**
+   * The total number of times a request should be retried after the wait period if it fails.
+   */
+  [WabaConfigEnum.MaxRetriesAfterWait]: number;
+  /**
+   * The timeout period for a request to quit and destroy the attempt in ms.
+   */
+  [WabaConfigEnum.RequestTimeout]: number;
+  /**
+   * The private key for the Meta for Developers business.
+   */
+  [WabaConfigEnum.PrivatePem]: string;
+  /**
+   * The passphrase for the Meta for Developers business.
+   */
+  [WabaConfigEnum.Passphrase]: string;
+  /**
+   * Automatic retry configuration for throttling errors.
+   * Passed through from WhatsAppConfig.
+   */
+  retry?: RetryConfig;
+  /**
+   * Rate limit header listener. Passed through from WhatsAppConfig.
+   */
+  onRateLimitInfo?: RateLimitInfoListener;
+};
+//#endregion
+//#region src/utils/configTable.d.ts
+/**
+ * Formats configuration as a terminal table
+ * @param config - The WABA configuration object
+ * @param apiName - The name of the API being initialized
+ * @returns Formatted table string
+ */
+declare function formatConfigTable(config: WabaConfigType): string;
+//#endregion
+//#region src/utils/customerServiceWindow.d.ts
+/**
+ * Length of the customer service window: 24 hours.
+ *
+ * "When a WhatsApp user messages you or calls you, a 24-hour timer called a customer service window
+ * starts. If the user messages or calls you again before the timer expires, the timer resets to
+ * 24 hours. [...] When the window closes, you can only send pre-approved template messages."
+ *
+ * @see {@link https://developers.facebook.com/documentation/business-messaging/whatsapp/messages/send-messages/ | Send messages: customer service windows}
+ */
+declare const CUSTOMER_SERVICE_WINDOW_MS: number;
+/**
+ * SDK fallback length of a free entry point (FEP) window: 72 hours.
+ * Prefer the expiry supplied by Meta; this fallback does not establish billing eligibility.
+ *
+ * @see {@link https://developers.facebook.com/documentation/business-messaging/whatsapp/pricing/ | Pricing: free entry point windows}
+ */
+declare const FREE_ENTRY_POINT_WINDOW_MS: number;
+/**
+ * Longest free entry point window Meta documents: up to 7 days for conversations started from an
+ * ad that clicks to WhatsApp.
+ *
+ * @see {@link https://developers.facebook.com/documentation/business-messaging/whatsapp/pricing/ | Pricing: free entry point windows}
+ */
+declare const MAX_FREE_ENTRY_POINT_WINDOW_MS: number;
+/**
+ * A point in time accepted by the window helpers:
+ * - `Date`
+ * - `number`: Unix epoch in milliseconds, or in seconds when below `1e11` (before the year 5138 in
+ *   seconds, before March 1973 in milliseconds), so both `Date.now()` and webhook timestamps work
+ * - `string`: a numeric string such as the webhook `messages[].timestamp` (`"1727856000"`, Unix
+ *   seconds, same rule as numbers), or any string `Date.parse` understands (ISO 8601)
+ */
+type WindowTimestamp = Date | number | string;
+/** State of a messaging window at a given instant. */
+interface MessagingWindow {
+  /** True while the window is open (`now < expiresAt`). */
+  isOpen: boolean;
+  /** When the window closes, or `null` when there is no window (no inbound message yet). */
+  expiresAt: Date | null;
+  /** Milliseconds until the window closes, `0` once closed. Never more than the window length. */
+  remainingMs: number;
+}
+interface CustomerServiceWindowOptions {
+  /** The instant to evaluate. Defaults to `Date.now()`. */
+  now?: WindowTimestamp;
+  /**
+   * Treat the window as closing this many milliseconds early. Use it to absorb clock drift between
+   * your servers and Meta and the time a send spends in flight. Defaults to `0`.
+   */
+  safetyMarginMs?: number;
+}
+interface FreeEntryPointWindowOptions extends CustomerServiceWindowOptions {
+  /**
+   * Window length. Defaults to {@link FREE_ENTRY_POINT_WINDOW_MS} (72 hours). Meta may keep a
+   * click-to-WhatsApp ad window open for up to {@link MAX_FREE_ENTRY_POINT_WINDOW_MS} (7 days)
+   * without saying how long a given window lasts, so prefer `expiresAt` when you have it.
+   */
+  durationMs?: number;
+  /**
+   * Exact expiry when known, for example the status webhook's `conversation.expiration_timestamp`
+   * (Unix seconds). Overrides `durationMs`.
+   */
+  expiresAt?: WindowTimestamp;
+}
+/**
+ * Returns the state of the 24-hour customer service window opened by the user's last inbound
+ * message (or call).
+ *
+ * Free-form (non-template) messages can only be sent while it is open; outside it only approved
+ * template messages are delivered (Meta rejects others with error `131047`). The window is exactly
+ * 24 hours from the user's last message: at `lastInboundAt + 24h` it is closed.
+ *
+ * Pass the webhook message `timestamp` (Unix seconds string) of the latest message from the user.
+ * Messages you send do not extend the window. Pass `null`/`undefined` when the user has never
+ * messaged you; that returns a closed window with `expiresAt: null`.
+ *
+ * A free entry point window does not reopen this window: "the customer service window is independent
+ * of the FEP window, so if the customer service window closes, you will only be able to send template
+ * messages." Use {@link getFreeEntryPointWindow} for the pricing side.
+ *
+ * @throws WhatsAppValidationError when a timestamp or `safetyMarginMs` is malformed.
+ *
+ * @see {@link https://developers.facebook.com/documentation/business-messaging/whatsapp/messages/send-messages/ | Send messages: customer service windows}
+ * @see {@link https://developers.facebook.com/documentation/business-messaging/whatsapp/pricing/ | Pricing}
+ *
+ * @example
+ * ```ts
+ * const { isOpen, expiresAt } = getCustomerServiceWindow(message.timestamp);
+ * if (!isOpen) await sendTemplateInstead();
+ * ```
+ */
+declare function getCustomerServiceWindow(lastInboundAt: WindowTimestamp | null | undefined, options?: CustomerServiceWindowOptions): MessagingWindow;
+/**
+ * True when a free-form (non-template) message can be sent: the customer service window opened by
+ * the user's last inbound message is still open. See {@link getCustomerServiceWindow}.
+ *
+ * @throws WhatsAppValidationError when a timestamp or `safetyMarginMs` is malformed.
+ */
+declare function canSendFreeformMessage(lastInboundAt: WindowTimestamp | null | undefined, options?: CustomerServiceWindowOptions): boolean;
+/**
+ * Returns the state of a free entry point (FEP) window.
+ *
+ * For eligible click-to-WhatsApp ad traffic, replying within the customer service window opens
+ * a billing window from the time of your reply. Pass that first reply time as `openedAt`.
+ *
+ * Meta documents windows lasting up to 7 days for ads that click to WhatsApp. This helper uses
+ * a 72-hour fallback estimate. Pass `expiresAt` (the status webhook's
+ * `conversation.expiration_timestamp`) when you have it, or set `durationMs`.
+ *
+ * This is a billing window only. It does not allow free-form messages after the customer service
+ * window closes; check {@link canSendFreeformMessage} for that.
+ *
+ * @throws WhatsAppValidationError when a timestamp, `durationMs` or `safetyMarginMs` is malformed.
+ *
+ * @see {@link https://developers.facebook.com/documentation/business-messaging/whatsapp/pricing/ | Pricing: free entry point windows}
+ */
+declare function getFreeEntryPointWindow(openedAt: WindowTimestamp | null | undefined, options?: FreeEntryPointWindowOptions): MessagingWindow;
+//#endregion
+//#region src/utils/isMetaError.d.ts
+type MetaErrorData = {
+  message: string;
+  type: string;
+  code: number;
+  error_data?: {
+    messaging_product?: 'whatsapp';
+    details?: string;
+  };
+  error_subcode?: number;
+  fbtrace_id: string;
+};
+interface MetaError extends Error {
+  error: MetaErrorData;
+}
+declare const WHATSAPP_ERROR_CODES: readonly [0, 1, 2, 3, 4, 10, 33, 100, 190, 200, 299, 368, 613, 80007, 130429, 130472, 130497, 131000, 131005, 131008, 131009, 131016, 131020, 131021, 131026, 131030, 131031, 131037, 131041, 131042, 131044, 131045, 131047, 131048, 131049, 131050, 131051, 131052, 131053, 131055, 131056, 131057, 131059, 131061, 131062, 131063, 131201, 131202, 131203, 131204, 131207, 131208, 131209, 131210, 131211, 131212, 131213, 131214, 131215, 132000, 132001, 132005, 132007, 132008, 132012, 132015, 132016, 132068, 132069, 133000, 133004, 133005, 133006, 133008, 133009, 133010, 133015, 133016, 134011, 134100, 134101, 134102, 135000, 137000, 138000, 138001, 138002, 138003, 138004, 138005, 138006, 138007, 138009, 138012, 138013, 138018, 139000, 139001, 139002, 139003, 139004, 139100, 139101, 139102, 139103, 147005, 200005, 200006, 200007, 1752041, 2388001, 2388012, 2388019, 2388040, 2388047, 2388072, 2388073, 2388091, 2388093, 2388103, 2388293, 2388299, 2494100, 2494191, 2593079, 2593085, 2593107, 2593108];
+type ApiPermissionErrorCode = number;
+type WhatsAppErrorCode = (typeof WHATSAPP_ERROR_CODES)[number] | ApiPermissionErrorCode;
+declare const AUTHORIZATION_ERROR_CODES: readonly [0, 3, 10, 190];
+declare const THROTTLING_ERROR_CODES: readonly [4, 80007, 130429, 131048, 131056];
+declare const INTEGRITY_ERROR_CODES: readonly [368, 130497, 131031];
+declare const SEND_MESSAGE_ERROR_CODES: readonly [130472, 131000, 131005, 131008, 131009, 131016, 131021, 131026, 131030, 131042, 131044, 131045, 131047, 131050, 131051, 131052, 131053, 131056, 131057, 131048, 131061, 131062, 131063, 132000, 132001, 132005, 132007, 132008, 132012, 132015, 132016, 132068, 132069, 135000, 137000];
+declare const FLOW_ERROR_CODES: readonly [139000, 139001, 139002, 139003, 139004];
+declare const BLOCK_USER_ERROR_CODES: readonly [139100, 139101, 139102, 139103];
+declare const CALLING_ERROR_CODES: readonly [138000, 138001, 138002, 138003, 138004, 138005, 138006, 138007, 138009, 138012, 138013, 138018, 613];
+declare const GROUP_ERROR_CODES: readonly [131020, 131041, 131059, 131201, 131202, 131203, 131204, 131207, 131208, 131209, 131210, 131211, 131212, 131213, 131214, 131215];
+declare function isWhatsAppErrorCode(code: number): code is WhatsAppErrorCode;
+declare function isApiPermissionErrorCode(code: number): code is ApiPermissionErrorCode;
+declare function isAuthorizationErrorCode(code: number): code is ApiPermissionErrorCode | (typeof AUTHORIZATION_ERROR_CODES)[number];
+declare function isThrottlingErrorCode(code: number): code is (typeof THROTTLING_ERROR_CODES)[number];
+declare function isIntegrityErrorCode(code: number): code is (typeof INTEGRITY_ERROR_CODES)[number];
+declare function isSendMessageErrorCode(code: number): code is (typeof SEND_MESSAGE_ERROR_CODES)[number];
+declare function isFlowErrorCode(code: number): code is (typeof FLOW_ERROR_CODES)[number];
+declare function isBlockUserErrorCode(code: number): code is (typeof BLOCK_USER_ERROR_CODES)[number];
+declare function isCallingErrorCode(code: number): code is (typeof CALLING_ERROR_CODES)[number];
+declare function isGroupErrorCode(code: number): code is (typeof GROUP_ERROR_CODES)[number];
+declare class WhatsAppError extends Error {
+  constructor(message: string);
+}
+declare class WhatsAppApiError extends WhatsAppError {
+  readonly error: MetaErrorData;
+  readonly statusCode?: number;
+  /**
+   * Rate limit headers of the failed response, when it carried any. Set by the SDK's requester;
+   * use `rateLimit.retryDelayMs` to reschedule a throttled call.
+   */
+  rateLimit?: RateLimitInfo;
+  constructor(message: string, error: MetaErrorData, statusCode?: number);
+}
+declare class WhatsAppAuthorizationError extends WhatsAppApiError {
+  constructor(message: string, error: MetaErrorData, statusCode?: number);
+}
+declare class WhatsAppThrottlingError extends WhatsAppApiError {
+  constructor(message: string, error: MetaErrorData, statusCode?: number);
+}
+declare class WhatsAppIntegrityError extends WhatsAppApiError {
+  constructor(message: string, error: MetaErrorData, statusCode?: number);
+}
+declare class WhatsAppSendMessageError extends WhatsAppApiError {
+  constructor(message: string, error: MetaErrorData, statusCode?: number);
+}
+declare class WhatsAppFlowError extends WhatsAppApiError {
+  constructor(message: string, error: MetaErrorData, statusCode?: number);
+}
+declare class WhatsAppBlockUserError extends WhatsAppApiError {
+  constructor(message: string, error: MetaErrorData, statusCode?: number);
+}
+declare class WhatsAppCallingError extends WhatsAppApiError {
+  constructor(message: string, error: MetaErrorData, statusCode?: number);
+}
+declare class WhatsAppGroupError extends WhatsAppApiError {
+  constructor(message: string, error: MetaErrorData, statusCode?: number);
+}
+declare function createWhatsAppApiError(error: MetaErrorData, statusCode?: number): WhatsAppApiError;
+declare class WhatsAppNetworkError extends WhatsAppError {
+  readonly cause?: unknown;
+  constructor(message: string, cause?: unknown);
+}
+declare class WhatsAppUnknownError extends WhatsAppError {
+  readonly cause?: unknown;
+  constructor(message: string, cause?: unknown);
+}
+/**
+ * Thrown when an API method receives invalid input (e.g., malformed phone number,
+ * empty required array). This error is thrown client-side before any API call is made.
+ */
+declare class WhatsAppValidationError extends Error {
+  constructor(message: 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
+ */
+declare function isMetaError(error: any): error is MetaError;
+declare function isWhatsAppApiErrorResponse(error: any): error is MetaError & {
+  error: {
+    code: WhatsAppErrorCode;
+  };
+};
+declare function isWhatsAppAuthorizationError(error: unknown): error is WhatsAppAuthorizationError;
+declare function isWhatsAppThrottlingError(error: unknown): error is WhatsAppThrottlingError;
+declare function isWhatsAppIntegrityError(error: unknown): error is WhatsAppIntegrityError;
+declare function isWhatsAppSendMessageError(error: unknown): error is WhatsAppSendMessageError;
+declare function isWhatsAppFlowError(error: unknown): error is WhatsAppFlowError;
+declare function isWhatsAppBlockUserError(error: unknown): error is WhatsAppBlockUserError;
+declare function isWhatsAppCallingError(error: unknown): error is WhatsAppCallingError;
+declare function isWhatsAppGroupError(error: unknown): error is WhatsAppGroupError;
+declare function normalizeMetaError(errorData: unknown, statusCode?: number): MetaError;
+//#endregion
+//#region src/types/logger.d.ts
+interface LoggerInterface {
+  log(...data: any[]): void;
+  error(...data: any[]): void;
+  warn(...data: any[]): void;
+  info(...data: any[]): void;
+  debug(...data: any[]): void;
+}
+//#endregion
+//#region src/utils/logger.d.ts
+declare class Logger implements LoggerInterface {
+  private name;
+  private debugEnabled;
+  constructor(name: string, debug?: boolean);
+  private formatData;
+  log(...data: any[]): void;
+  error(...data: any[]): void;
+  warn(...data: any[]): void;
+  info(...data: any[]): void;
+  debug(...data: any[]): void;
+}
+//#endregion
+//#region src/utils/objectToQueryString.d.ts
+declare const objectToQueryString: (params: Record<string, any>) => string;
+//#endregion
+//#region src/api/flow/types/common.d.ts
+declare enum FlowActionEnum {
+  INIT = "INIT",
+  BACK = "BACK",
+  DATA_EXCHANGE = "data_exchange"
+}
+/**
+ * WhatsApp Flow Endpoint - Health Check Request
+ * Represents the structure of a health check request
+ */
+interface FlowHealthCheckRequest {
+  action: 'ping';
+  version: '3.0';
+}
+/**
+ * WhatsApp Flow Endpoint - Data Exchange Request
+ * Represents the structure of a data exchange request
+ */
+interface FlowDataExchangeRequest {
+  version: '3.0';
+  action: FlowActionEnum;
+  screen: string;
+  flow_token: string;
+  data?: Record<string, any> & {
+    error_message?: string;
+  };
+}
+/**
+ * WhatsApp Flow Endpoint - Error Notification Request
+ * Represents the structure of an error notification request
+ */
+interface FlowErrorNotificationRequest {
+  version: '3.0';
+  action: Exclude<FlowActionEnum, FlowActionEnum.BACK>;
+  screen: string;
+  flow_token: string;
+  data: {
+    error: string;
+    error_message: string;
+  };
+}
+/**
+ * WhatsApp Flow Endpoint - Comprehensive Request Object
+ * A combined type that includes all possible fields from different request types
+ * with all fields being optional for flexibility
+ */
+interface FlowEndpointRequest {
+  version?: '3.0';
+  action?: 'ping' | FlowActionEnum;
+  screen?: string;
+  flow_token?: string;
+  data?: Record<string, any> & {
+    error_key?: string;
+    error_message?: string;
+  };
+}
+//#endregion
+//#region src/utils/flowEncryptionUtils.d.ts
+/**
+ * Environment model for encryption keys
+ */
+type EncryptionKeyPair = {
+  passphrase: string;
+  privateKey: string;
+  publicKey: string;
+};
+/**
+ * Generates RSA key pair for WhatsApp Business Flow API encryption
+ *
+ * This function generates a 2048-bit RSA key pair with:
+ * - Public key in SPKI format (PEM)
+ * - Private key in PKCS#8 format (PEM) encrypted with AES-256-CBC
+ *
+ * @param passphrase - Passphrase to encrypt the private key. If not provided, uses FLOW_API_PASSPHRASE from environment
+ * @returns Object containing passphrase, privateKey, and publicKey
+ * @throws {Error} If passphrase is empty or key generation fails
+ * @throws {Error} If not running in Node.js environment
+ *
+ * @example
+ * ```typescript
+ * import { WhatsApp } from 'meta-cloud-api';
+ *
+ * const wa = new WhatsApp();
+ *
+ * try {
+ *   // Uses FLOW_API_PASSPHRASE from environment
+ *   const keys = wa.generateEncryption();
+ *   console.log('Public Key:', keys.publicKey);
+ *   console.log('Private Key:', keys.privateKey);
+ *
+ *   // Or provide custom passphrase
+ *   const customKeys = wa.generateEncryption('my-secret-passphrase');
+ * } catch (error) {
+ *   console.error('Failed to generate keys:', error.message);
+ * }
+ * ```
+ */
+declare function generateEncryption(passphrase?: string): EncryptionKeyPair;
+/**
+ * Decrypt a WhatsApp Flow request (Node.js only; see {@link decryptFlowRequestAsync} for every runtime)
+ * @param body - Encrypted request body containing encrypted_aes_key, encrypted_flow_data, and initial_vector
+ * @param config - WABA configuration containing FLOW_API_PRIVATE_PEM and FLOW_API_PASSPHRASE
+ * @returns Decrypted flow request body, AES key buffer, and initial vector buffer
+ * @throws {Error} If required encryption properties are missing or decryption fails
+ */
+declare function decryptFlowRequest(body: any, config: WabaConfigType): {
+  decryptedBody: FlowEndpointRequest;
+  aesKeyBuffer: Buffer;
+  initialVectorBuffer: Buffer;
+};
+/**
+ * Encrypt a WhatsApp Flow response (Node.js only; see {@link encryptFlowResponseAsync} for every runtime)
+ * @param response - Response object to encrypt
+ * @param aesKeyBuffer - AES key buffer from the decrypted request
+ * @param initialVectorBuffer - Initial vector buffer from the decrypted request
+ * @returns Base64-encoded encrypted response
+ * @throws {Error} If encryption fails
+ */
+declare function encryptFlowResponse(response: any, aesKeyBuffer: Buffer, initialVectorBuffer: Buffer): string;
+/**
+ * Result of {@link decryptFlowRequestAsync}. Pass `aesKeyBuffer` and
+ * `initialVectorBuffer` to {@link encryptFlowResponseAsync}.
+ */
+type DecryptedFlowRequest = {
+  decryptedBody: FlowEndpointRequest;
+  aesKeyBuffer: Uint8Array<ArrayBuffer>;
+  initialVectorBuffer: Uint8Array<ArrayBuffer>;
+};
+/**
+ * Decrypt a WhatsApp Flow request with Web Crypto. Works on Node.js, Bun, Deno,
+ * Cloudflare Workers and Vercel Edge.
+ *
+ * On runtimes without `node:crypto` the private key must be an unencrypted
+ * PKCS#8 PEM (`-----BEGIN PRIVATE KEY-----`); the passphrase is then ignored.
+ *
+ * @param body - Encrypted request body containing encrypted_aes_key, encrypted_flow_data, and initial_vector
+ * @param config - WABA configuration containing FLOW_API_PRIVATE_PEM and (for encrypted keys) FLOW_API_PASSPHRASE
+ * @throws {Error} If required encryption properties are missing or decryption fails
+ */
+declare function decryptFlowRequestAsync(body: any, config: WabaConfigType): Promise<DecryptedFlowRequest>;
+/**
+ * Encrypt a WhatsApp Flow response with Web Crypto. Works on every runtime.
+ * @param response - Response object to encrypt
+ * @param aesKeyBuffer - AES key from {@link decryptFlowRequestAsync} (a Node.js Buffer also works)
+ * @param initialVectorBuffer - Initial vector from {@link decryptFlowRequestAsync} (a Node.js Buffer also works)
+ * @returns Base64-encoded encrypted response
+ */
+declare function encryptFlowResponseAsync(response: any, aesKeyBuffer: Uint8Array, initialVectorBuffer: Uint8Array): Promise<string>;
+//#endregion
+//#region src/utils/flowTypeGuards.d.ts
+declare const DATA_EXCHANGE_ACTIONS: readonly [FlowActionEnum.DATA_EXCHANGE, FlowActionEnum.INIT, FlowActionEnum.BACK];
+declare const ERROR_ACTIONS: readonly [FlowActionEnum.DATA_EXCHANGE, FlowActionEnum.INIT];
+/**
+ * Type guard to check if a request is a Data Exchange request
+ * Validates the request structure according to the Flow API specifications
+ *
+ * @param request The Flow endpoint request to check
+ * @returns True if the request is a valid Data Exchange request, false otherwise
+ */
+declare function isFlowDataExchangeRequest(request: FlowEndpointRequest): request is FlowDataExchangeRequest & {
+  action: (typeof DATA_EXCHANGE_ACTIONS)[number];
+  screen?: string;
+  flow_token: string;
+  data?: Record<string, any>;
+};
+/**
+ * Type guard to check if a request is an Error Notification request
+ * Validates the request structure according to the Flow API error specifications
+ *
+ * @param request The Flow endpoint request to check
+ * @returns True if the request is a valid Error Notification request, false otherwise
+ */
+declare function isFlowErrorRequest(request: FlowEndpointRequest): request is FlowErrorNotificationRequest & {
+  action: (typeof ERROR_ACTIONS)[number];
+  screen: string;
+  flow_token: string;
+  data: {
+    error: string;
+    error_message: string;
+  };
+};
+/**
+ * Type guard to check if a request is a Ping (health check) request
+ * Simple validation for health check endpoints in the Flow API
+ *
+ * @param request The Flow endpoint request to check
+ * @returns True if the request is a Ping request, false otherwise
+ */
+declare function isFlowPingRequest(request: FlowEndpointRequest): request is FlowHealthCheckRequest;
+//#endregion
+export { AUTHORIZATION_ERROR_CODES, type ApiPermissionErrorCode, BLOCK_USER_ERROR_CODES, type BusinessUseCaseUsage, CALLING_ERROR_CODES, CUSTOMER_SERVICE_WINDOW_MS, type CustomerServiceWindowOptions, type DecryptedFlowRequest, type EncryptionKeyPair, FLOW_ERROR_CODES, FREE_ENTRY_POINT_WINDOW_MS, type FreeEntryPointWindowOptions, GROUP_ERROR_CODES, INTEGRITY_ERROR_CODES, Logger, MAX_FREE_ENTRY_POINT_WINDOW_MS, type MessagingWindow, type MetaError, type MetaErrorData, type RateLimitHeadersInput, type RateLimitInfo, type RateLimitUsage, SEND_MESSAGE_ERROR_CODES, THROTTLING_ERROR_CODES, WHATSAPP_ERROR_CODES, WhatsAppApiError, WhatsAppAuthorizationError, WhatsAppBlockUserError, WhatsAppCallingError, WhatsAppError, type WhatsAppErrorCode, WhatsAppFlowError, WhatsAppGroupError, WhatsAppIntegrityError, WhatsAppNetworkError, WhatsAppSendMessageError, WhatsAppThrottlingError, WhatsAppUnknownError, WhatsAppValidationError, type WindowTimestamp, buildFieldsQueryString, canSendFreeformMessage, createWhatsAppApiError, decryptFlowRequest, decryptFlowRequestAsync, encryptFlowResponse, encryptFlowResponseAsync, formatConfigTable, generateEncryption, getCustomerServiceWindow, getFreeEntryPointWindow, isApiPermissionErrorCode, isAuthorizationErrorCode, isBlockUserErrorCode, isCallingErrorCode, isFlowDataExchangeRequest, isFlowErrorCode, isFlowErrorRequest, isFlowPingRequest, isGroupErrorCode, isIntegrityErrorCode, isMetaError, isSendMessageErrorCode, isThrottlingErrorCode, isWhatsAppApiErrorResponse, isWhatsAppAuthorizationError, isWhatsAppBlockUserError, isWhatsAppCallingError, isWhatsAppErrorCode, isWhatsAppFlowError, isWhatsAppGroupError, isWhatsAppIntegrityError, isWhatsAppSendMessageError, isWhatsAppThrottlingError, normalizeMetaError, objectToQueryString, parseRateLimitHeaders, parseRetryAfter };
+//# sourceMappingURL=index.d.ts.map