zaileys 4.7.2 → 4.8.0

package/dist/client/client.d.ts

@@ -7,7 +7,9 @@ import type { MediaDownloadResult } from '../events/types.js';
 import type { AuthStoreBundle } from '../auth/types.js';
 import type { MessageStore } from '../store/types.js';
 import { TypedEventEmitter } from './event-emitter.js';
-import type { BaileysSocket, ClientEventMap, ClientOptions, ConnectionState } from './types.js';
+import type { BaileysSocket, ClientEventMap, ClientOptions, ConnectionState, ProviderKind } from './types.js';
+import { CloudModule } from '../cloud/module.js';
+import { type WebhookHandler } from '../cloud/webhook.js';
 export declare class Client extends TypedEventEmitter<ClientEventMap> {
     readonly sessionId: string;
     auth: AuthStoreBundle;
@@ -67,13 +69,21 @@ export declare class Client extends TypedEventEmitter<ClientEventMap> {
     private pluginLoader;
     private waVersion?;
     private versionWarming?;
+    private readonly _provider;
+    private readonly cloudOptions;
+    private cloudTransport;
+    private cloudRuntimeReady;
+    private _cloudModule;
     constructor(options?: ClientOptions);
     private warmVersion;
     private emitAutoConnectError;
     private logStatus;
     private resolveMe;
+    get provider(): ProviderKind;
     get state(): ConnectionState;
     get socket(): BaileysSocket | undefined;
+    /** Web-only surfaces fail loud on the cloud provider instead of dying deeper with a vague error. */
+    private assertWebProvider;
     get group(): GroupModule;
     get privacy(): PrivacyModule;
     get newsletter(): NewsletterModule;
@@ -88,6 +98,16 @@ export declare class Client extends TypedEventEmitter<ClientEventMap> {
     private ensureScheduler;
     private dispatchSnapshot;
     connect(): Promise<void>;
+    /** Create the cloud transport + attach the inbound pipeline exactly once — independent of connect(). */
+    private ensureCloudRuntime;
+    private connectCloud;
+    private attachCloudPipeline;
+    /**
+     * Framework-agnostic Meta webhook endpoint (cloud provider only): handles the GET
+     * verification challenge and signed POST deliveries, then feeds events into the client.
+     */
+    webhook(): WebhookHandler;
+    private disconnectCloud;
     disconnect(): Promise<void>;
     logout(): Promise<void>;
     command(spec: string, handler: CommandHandler): this;
@@ -101,12 +121,22 @@ export declare class Client extends TypedEventEmitter<ClientEventMap> {
     edit(key: WAMessageKey): EditBuilder;
     delete(key: WAMessageKey, opts?: DeleteOptions): Promise<void>;
     react(key: WAMessageKey, emoji: string): Promise<WAMessageKey>;
+    /** Cloud provider only: management surface (templates, profile, flows, blocklist, qr, analytics, phone). */
+    get cloud(): CloudModule;
+    /** Cloud provider only: send an approved Meta message template by name + language. */
+    sendTemplate(to: string, name: string, languageCode: string, components?: Array<Record<string, unknown>>): Promise<WAMessageKey>;
+    /** Cloud provider only: mark an inbound message read (optionally showing a typing indicator). */
+    markRead(messageId: string, opts?: {
+        typing?: boolean;
+    }): Promise<void>;
     forward(key: WAMessageKey, to: string): Promise<WAMessageKey>;
     pin(key: WAMessageKey, opts?: PinOptions): Promise<WAMessageKey>;
     unpin(key: WAMessageKey): Promise<WAMessageKey>;
     setDisappearing(to: string, seconds: number): Promise<void>;
     private resolveRecipient;
     private requireSocket;
+    /** Messaging seam: baileys socket or the cloud transport, whichever the provider dictates. */
+    private requireBuilderSocket;
     private attachEmitterLogger;
     private wireSocket;
     private handleConnectionUpdate;

package/dist/client/types.d.ts

@@ -9,6 +9,9 @@ import type { CitationConfig } from '../events/context.js';
 import type { InboundEventMap } from '../events/types.js';
 import type { MessageStore } from '../store/types.js';
 import type { PluginsOptions } from '../plugin/types.js';
+import type { CloudOptions } from '../cloud/types.js';
+import type { CloudFlowResponseEvent, CloudOrderEvent, CloudStatusEvent, CloudTemplateStatusEvent } from '../cloud/translate/inbound.js';
+export type ProviderKind = 'baileys' | 'cloud';
 export type ConnectionState = 'idle' | 'connecting' | 'qr-pending' | 'pairing-pending' | 'connected' | 'reconnecting' | 'disconnecting' | 'disconnected';
 export type ConnectionAuthType = 'qr' | 'pairing';
 export interface Logger {
@@ -28,6 +31,10 @@ export interface ReconnectOptions {
     rateLimitedDelayMs?: number;
 }
 export interface ClientOptions {
+    /** Message transport: baileys (WhatsApp Web, default) or the official Meta Cloud API. */
+    provider?: ProviderKind;
+    /** Cloud API credentials/config — required when `provider: 'cloud'`. */
+    cloud?: CloudOptions;
     sessionId?: string;
     auth?: AuthStoreBundle;
     store?: MessageStore;
@@ -96,6 +103,14 @@ export type ConnectionEventMap = {
         sessionId: string;
         error: Error;
     };
+    /** Cloud provider: delivery lifecycle of outbound messages (sent/delivered/read/failed). */
+    'message-status': CloudStatusEvent;
+    /** Cloud provider: template review lifecycle (APPROVED/REJECTED/PAUSED...). */
+    'template-status': CloudTemplateStatusEvent;
+    /** Cloud provider: WhatsApp Flow completion (nfm_reply) with parsed response payload. */
+    'flow-response': CloudFlowResponseEvent;
+    /** Cloud provider: catalog order placed by the customer. */
+    order: CloudOrderEvent;
 };
 export type ConnectionEventName = keyof ConnectionEventMap;
 export type ConnectionEventHandler<E extends ConnectionEventName> = (payload: ConnectionEventMap[E]) => void;

package/dist/cloud/errors.d.ts

@@ -0,0 +1,14 @@
+export type CloudErrorCode = 'CONFIG' | 'AUTH' | 'REQUEST_FAILED' | 'RATE_LIMITED' | 'NOT_IMPLEMENTED';
+/** Thrown when a WhatsApp-Web-only surface is used on the official Cloud API provider. */
+export declare class ZaileysProviderError extends Error {
+    readonly code = "UNSUPPORTED_ON_CLOUD";
+    readonly feature: string;
+    constructor(feature: string);
+}
+export declare class ZaileysCloudError extends Error {
+    readonly code: CloudErrorCode;
+    readonly cause?: unknown;
+    constructor(code: CloudErrorCode, message: string, options?: {
+        cause?: unknown;
+    });
+}

package/dist/cloud/graph-client.d.ts

@@ -0,0 +1,15 @@
+import type { CloudOptions } from './types.js';
+/** Pinned default Graph API version — override via CloudOptions.apiVersion. */
+export declare const DEFAULT_GRAPH_VERSION = "v23.0";
+export declare const DEFAULT_GRAPH_BASE_URL = "https://graph.facebook.com";
+export interface GraphClientDeps {
+    delay?: (ms: number) => Promise<void>;
+}
+export interface GraphClient {
+    get<T>(path: string): Promise<T>;
+    post<T>(path: string, body: unknown): Promise<T>;
+    postForm<T>(path: string, form: FormData): Promise<T>;
+    delete<T = unknown>(path: string, body?: unknown): Promise<T>;
+    url(path: string): string;
+}
+export declare function createGraphClient(options: CloudOptions, deps?: GraphClientDeps): GraphClient;

package/dist/cloud/index.d.ts

@@ -0,0 +1,6 @@
+export { ZaileysCloudError, ZaileysProviderError, type CloudErrorCode } from './errors.js';
+export { validateCloudOptions, type CloudOptions } from './types.js';
+export { CloudTransport, DEFAULT_GRAPH_VERSION } from './transport.js';
+export { CloudModule, type CloudTemplate, type CloudBusinessProfile, type FlowSendOptions } from './module.js';
+export { createWebhookHandler, type WebhookHandler, type WebhookHandlerOptions } from './webhook.js';
+export type { CloudFlowResponseEvent, CloudMessageStatus, CloudOrderEvent, CloudStatusEvent, CloudTemplateStatusEvent, } from './translate/inbound.js';

package/dist/cloud/media.d.ts

@@ -0,0 +1,15 @@
+import type { AnyMessageContent } from 'baileys';
+import type { GraphClient } from './graph-client.js';
+export type CloudMediaKind = 'image' | 'video' | 'audio' | 'document' | 'sticker';
+export interface OutboundMedia {
+    kind: CloudMediaKind;
+    buffer: Buffer;
+    caption?: string;
+    fileName?: string;
+    mimetype?: string;
+}
+/** Detect a builder media content (`{ image: Buffer, caption? }` etc.); null when not media. */
+export declare function outboundMediaOf(content: AnyMessageContent): OutboundMedia | null;
+/** Upload bytes to the Cloud media endpoint; returns the media id to reference in sends. */
+export declare function uploadMedia(graph: GraphClient, phoneNumberId: string, media: OutboundMedia): Promise<string>;
+export declare function mediaMessageBody(media: OutboundMedia, mediaId: string): Record<string, unknown>;

package/dist/cloud/module.d.ts

@@ -0,0 +1,147 @@
+import type { WAMessageKey } from 'baileys';
+import type { CloudTransport } from './transport.js';
+import type { CloudOptions } from './types.js';
+export interface FlowSendOptions {
+    flowId?: string;
+    flowName?: string;
+    cta: string;
+    bodyText: string;
+    headerText?: string;
+    footerText?: string;
+    screen: string;
+    flowToken?: string;
+    data?: Record<string, unknown>;
+    mode?: 'draft' | 'published';
+    action?: 'navigate' | 'data_exchange';
+}
+export interface CloudTemplate {
+    id: string;
+    name: string;
+    status: string;
+    category?: string;
+    language?: string;
+    components?: Array<Record<string, unknown>>;
+}
+export interface CloudBusinessProfile {
+    about?: string;
+    address?: string;
+    description?: string;
+    email?: string;
+    websites?: string[];
+    vertical?: string;
+    messaging_product?: string;
+}
+/** Cloud-only management surface: templates, profile, flows, commerce, blocklist, qr, analytics, phone. */
+export declare class CloudModule {
+    private readonly graph;
+    private readonly options;
+    private readonly getTransport;
+    constructor(options: CloudOptions, getTransport: () => CloudTransport);
+    private requireWaba;
+    /** This sender's phone-number node: display number, verified name, quality rating, throughput. */
+    info(): Promise<Record<string, unknown>>;
+    /** All phone numbers registered under the WhatsApp Business Account. */
+    phoneNumbers(): Promise<Array<Record<string, unknown>>>;
+    /** Request the user's shipping address (interactive address_message; ID/BR only per Meta). */
+    sendAddressRequest(to: string, opts: {
+        bodyText: string;
+        countryIso: string;
+        values?: Record<string, unknown>;
+    }): Promise<WAMessageKey>;
+    readonly commerce: {
+        catalogs: () => Promise<Array<{
+            id: string;
+            name: string;
+        }>>;
+        products: (catalogId: string, limit?: number) => Promise<Array<{
+            id: string;
+            retailer_id: string;
+            name: string;
+            price?: string;
+            availability?: string;
+        }>>;
+        sendProduct: (to: string, opts: {
+            catalogId: string;
+            retailerId: string;
+            bodyText?: string;
+            footerText?: string;
+        }) => Promise<WAMessageKey>;
+        sendProductList: (to: string, opts: {
+            catalogId: string;
+            headerText: string;
+            bodyText: string;
+            footerText?: string;
+            sections: Array<{
+                title: string;
+                productIds: string[];
+            }>;
+        }) => Promise<WAMessageKey>;
+    };
+    readonly templates: {
+        list: (params?: {
+            status?: string;
+            limit?: number;
+        }) => Promise<CloudTemplate[]>;
+        get: (idOrName: string) => Promise<CloudTemplate | null>;
+        create: (template: {
+            name: string;
+            category: 'MARKETING' | 'UTILITY' | 'AUTHENTICATION';
+            language: string;
+            components: Array<Record<string, unknown>>;
+        }) => Promise<{
+            id: string;
+            status: string;
+        }>;
+        delete: (name: string, id?: string) => Promise<void>;
+    };
+    readonly profile: {
+        get: () => Promise<CloudBusinessProfile>;
+        update: (fields: CloudBusinessProfile) => Promise<void>;
+    };
+    readonly flows: {
+        list: () => Promise<Array<{
+            id: string;
+            name: string;
+            status: string;
+        }>>;
+        send: (to: string, opts: FlowSendOptions) => Promise<WAMessageKey>;
+    };
+    readonly blocklist: {
+        add: (numbers: string[]) => Promise<void>;
+        remove: (numbers: string[]) => Promise<void>;
+        list: () => Promise<Array<{
+            wa_id: string;
+        }>>;
+    };
+    readonly qr: {
+        create: (prefilledMessage: string, imageFormat?: 'SVG' | 'PNG') => Promise<{
+            code: string;
+            prefilled_message: string;
+            qr_image_url?: string;
+        }>;
+        list: () => Promise<Array<{
+            code: string;
+            prefilled_message: string;
+        }>>;
+        delete: (code: string) => Promise<void>;
+    };
+    readonly analytics: {
+        conversations: (params: {
+            start: number;
+            end: number;
+            granularity?: 'HALF_HOUR' | 'DAILY' | 'MONTHLY';
+        }) => Promise<unknown>;
+        messages: (params: {
+            start: number;
+            end: number;
+            granularity?: 'HALF_HOUR' | 'DAY' | 'MONTH';
+        }) => Promise<unknown>;
+    };
+    readonly phone: {
+        /** Registers the number for Cloud API messaging. Touches live registration — use with care. */
+        register: (pin: string) => Promise<void>;
+        deregister: () => Promise<void>;
+        requestCode: (method: 'SMS' | 'VOICE', language?: string) => Promise<void>;
+        verifyCode: (code: string) => Promise<void>;
+    };
+}

package/dist/cloud/translate/inbound.d.ts

@@ -0,0 +1,119 @@
+import type { WAMessage } from 'baileys';
+export interface CloudInboundMedia {
+    id?: string;
+    mime_type?: string;
+    sha256?: string;
+    caption?: string;
+    filename?: string;
+    voice?: boolean;
+    animated?: boolean;
+}
+export interface CloudWebhookMessage {
+    from?: string;
+    id?: string;
+    timestamp?: string;
+    type?: string;
+    text?: {
+        body?: string;
+    };
+    image?: CloudInboundMedia;
+    video?: CloudInboundMedia;
+    audio?: CloudInboundMedia;
+    document?: CloudInboundMedia;
+    sticker?: CloudInboundMedia;
+    [key: string]: unknown;
+}
+export interface CloudWebhookValue {
+    messaging_product?: string;
+    metadata?: {
+        display_phone_number?: string;
+        phone_number_id?: string;
+    };
+    contacts?: Array<{
+        profile?: {
+            name?: string;
+        };
+        wa_id?: string;
+    }>;
+    messages?: CloudWebhookMessage[];
+    statuses?: Array<Record<string, unknown>>;
+}
+export interface CloudWebhookPayload {
+    object?: string;
+    entry?: Array<{
+        id?: string;
+        changes?: Array<{
+            value?: CloudWebhookValue;
+            field?: string;
+        }>;
+    }>;
+}
+export interface CloudTemplateStatusEvent {
+    event: string;
+    id: string;
+    name: string;
+    language?: string;
+    reason?: string;
+}
+export type CloudMessageStatus = 'sent' | 'delivered' | 'read' | 'failed';
+export interface CloudStatusEvent {
+    id: string;
+    status: CloudMessageStatus;
+    recipientId: string;
+    timestamp: number;
+    conversationId?: string;
+    error?: {
+        code?: number;
+        title?: string;
+        message?: string;
+    };
+}
+export interface CloudFlowResponseEvent {
+    id: string;
+    name: string;
+    body?: string;
+    response: Record<string, unknown>;
+    senderId: string;
+    senderName?: string;
+    timestamp: number;
+}
+export interface CloudOrderEvent {
+    id: string;
+    catalogId: string;
+    text?: string;
+    items: Array<{
+        productRetailerId: string;
+        quantity: number;
+        price: number;
+        currency: string;
+    }>;
+    senderId: string;
+    senderName?: string;
+    timestamp: number;
+}
+export interface CloudReactionItem {
+    key: {
+        id: string;
+        remoteJid: string;
+        fromMe: boolean;
+    };
+    reaction: {
+        key: {
+            id: string;
+            remoteJid: string;
+            fromMe: boolean;
+        };
+        text: string;
+        senderTimestampMs: number;
+    };
+    pushName?: string;
+}
+/** Flatten a Meta webhook delivery into baileys-shaped events the existing pipeline can decode. */
+export declare function translateInbound(payload: CloudWebhookPayload): {
+    messages: WAMessage[];
+    reactions: CloudReactionItem[];
+    statuses: CloudStatusEvent[];
+    templateStatuses: CloudTemplateStatusEvent[];
+    flowResponses: CloudFlowResponseEvent[];
+    orders: CloudOrderEvent[];
+};

package/dist/cloud/translate/interactive.d.ts

@@ -0,0 +1,2 @@
+/** Translate the builder's relay proto (interactiveMessage) into a Graph `interactive` object. */
+export declare function translateInteractiveProto(message: Record<string, unknown>): Record<string, unknown> | null;

package/dist/cloud/translate/outbound.d.ts

@@ -0,0 +1,21 @@
+import type { AnyMessageContent, MiscMessageGenerationOptions, WAMessage } from 'baileys';
+export interface GraphMessagePayload {
+    messaging_product: 'whatsapp';
+    recipient_type: 'individual';
+    to: string;
+    type: string;
+    context?: {
+        message_id: string;
+    };
+    [key: string]: unknown;
+}
+/** Graph `to` is a bare number — strip any jid server suffix. */
+export declare const toGraphRecipient: (to: string) => string;
+export declare const toJid: (recipient: string) => string;
+export declare const basePayload: (to: string, type: string, options?: MiscMessageGenerationOptions) => GraphMessagePayload;
+/** Translate baileys-style outbound content to a Graph payload; null = not translatable yet. */
+export declare function translateOutbound(to: string, content: AnyMessageContent, options?: MiscMessageGenerationOptions): GraphMessagePayload | null;
+/** Minimal vcard extraction (FN/N + TELs) — Graph requires formatted_name plus one name part. */
+export declare function vcardToGraphContact(vcard: string): Record<string, unknown> | null;
+/** Minimal baileys-shaped WAMessage so recordSent/store/reply keep working on cloud. */
+export declare function synthesizeSentMessage(wamid: string, to: string, content: AnyMessageContent, timestampMs: number): WAMessage;

package/dist/cloud/transport.d.ts

@@ -0,0 +1,51 @@
+import { EventEmitter } from 'node:events';
+import type { AnyMessageContent, MiscMessageGenerationOptions, WAMessage } from 'baileys';
+import type { Transport } from '../transport/types.js';
+import type { CloudOptions } from './types.js';
+import { DEFAULT_GRAPH_BASE_URL, DEFAULT_GRAPH_VERSION } from './graph-client.js';
+export { DEFAULT_GRAPH_BASE_URL, DEFAULT_GRAPH_VERSION };
+export interface CloudMe {
+    id: string;
+    name?: string;
+}
+export declare class CloudTransport implements Transport {
+    readonly ev: EventEmitter<[never]>;
+    readonly user: {
+        id: string;
+    };
+    private readonly options;
+    private readonly graph;
+    constructor(options: CloudOptions);
+    get apiVersion(): string;
+    get baseUrl(): string;
+    url(path: string): string;
+    /** Health check: token+phoneNumberId must resolve the phone-number node. No retry — a bad token never heals. */
+    connect(): Promise<CloudMe>;
+    disconnect(): Promise<void>;
+    /**
+     * Relay seam used by the builder for interactive sends (buttons/list/cta). Translates the
+     * proto to a Graph interactive payload. Returns the builder's messageId per contract, but
+     * the store records the real wamid via the upsert emit.
+     */
+    relayMessage: (jid: string, message: unknown, options: {
+        messageId: string;
+        additionalNodes?: unknown[];
+    }) => Promise<string>;
+    /** Post a raw interactive object to /messages; shared by flows/commerce/address sends. */
+    sendInteractive(to: string, interactive: Record<string, unknown>): Promise<WAMessage>;
+    /** Send an approved Meta message template (Cloud-only; templates are managed in Business Manager). */
+    sendTemplate(to: string, name: string, languageCode: string, components?: Array<Record<string, unknown>>): Promise<WAMessage>;
+    /** Mark an inbound message read; optionally show a typing indicator alongside. */
+    markRead(messageId: string, opts?: {
+        typing?: boolean;
+    }): Promise<void>;
+    /** Resolve a Meta media id to bytes: GET /{mediaId} -> short-lived CDN url -> authorized fetch. */
+    downloadMedia(mediaId: string): Promise<{
+        buffer: Buffer;
+        mime: string;
+        size: number;
+    } | null>;
+    /** Feed a verified webhook payload into the shared event pipeline. */
+    ingest(payload: unknown): void;
+    sendMessage(jid: string, content: AnyMessageContent, options?: MiscMessageGenerationOptions): Promise<WAMessage | undefined>;
+}

package/dist/cloud/types.d.ts

@@ -0,0 +1,17 @@
+export interface CloudOptions {
+    /** Permanent or system-user access token for the WhatsApp Business app. */
+    accessToken: string;
+    /** Sender phone-number id (not the phone number itself). */
+    phoneNumberId: string;
+    /** WhatsApp Business Account id — optional, needed only for account-level ops. */
+    wabaId?: string;
+    /** Token echoed back on the webhook GET verification challenge. */
+    verifyToken?: string;
+    /** Meta app secret; enables X-Hub-Signature-256 verification of webhook POSTs. */
+    appSecret?: string;
+    /** Graph API version, e.g. 'v23.0'. Defaults to the pinned stable version. */
+    apiVersion?: string;
+    /** Override the Graph API origin (tests / proxies). */
+    baseUrl?: string;
+}
+export declare function validateCloudOptions(cloud: CloudOptions | undefined): CloudOptions;

package/dist/cloud/webhook.d.ts

@@ -0,0 +1,11 @@
+export type WebhookHandler = (req: Request) => Promise<Response>;
+export interface WebhookHandlerOptions {
+    verifyToken?: string;
+    appSecret?: string;
+    onPayload: (payload: unknown) => void;
+}
+/**
+ * Framework-agnostic Meta webhook endpoint: handles the GET verification challenge and
+ * signed POST deliveries. Mount it on any server that speaks Web Request/Response.
+ */
+export declare function createWebhookHandler(options: WebhookHandlerOptions): WebhookHandler;