@digisglobal/omnivox-sdk 0.5.0 → 0.6.0

package/dist/index.d.ts

@@ -33,11 +33,289 @@ declare function createApiKeyTokenProvider(apiKey: string): TokenProvider;
  */
 declare function createSessionTokenProvider(): TokenProvider;
 
+/**
+ * Canned-responses module — hand-written typed wrapper over the generated client.
+ *
+ * Exposes the Phase-2 canned-responses resource:
+ *   - list(opts)           → GET   /api/v1/canned-responses (paginated)
+ *   - search(opts)         → GET   /api/v1/canned-responses?q= (title/keyword search)
+ *   - create(input)        → POST  /api/v1/canned-responses
+ *   - update(id, input)    → PATCH /api/v1/canned-responses/:id
+ *   - delete(id)           → DELETE /api/v1/canned-responses/:id
+ *
+ * Never re-exports symbols from _generated/.
+ * Contains no business logic — typed transport only.
+ */
+
+/** Options to construct the canned-responses module. */
+interface CannedResponsesModuleOptions extends TokenProvider {
+    /** Base URL of the Omnivox API (e.g. "https://api.omnivox.io"). */
+    baseUrl: string;
+}
+/** Input for creating a canned response. */
+interface CreateCannedResponseInput {
+    title: string;
+    body: string;
+    keywords: string[];
+    [key: string]: unknown;
+}
+/** Input for partially updating a canned response. */
+interface UpdateCannedResponseInput {
+    title?: string;
+    body?: string;
+    keywords?: string[];
+    [key: string]: unknown;
+}
+/** Canned response resource shape returned by the API. */
+interface CannedResponseItem {
+    id: string;
+    title: string;
+    body: string;
+    keywords: string[];
+    [key: string]: unknown;
+}
+/** Paginated list response. */
+interface PagedList$5<T> {
+    data: T[];
+    meta: {
+        page: number;
+        pageSize: number;
+        total: number;
+        hasNextPage: boolean;
+    };
+}
+/** Pagination options for list(). */
+interface CannedResponseListOpts {
+    page: number;
+    pageSize: number;
+    [key: string]: unknown;
+}
+/** Pagination + search options for search(). */
+interface CannedResponseSearchOpts {
+    page: number;
+    pageSize: number;
+    q: string;
+    [key: string]: unknown;
+}
+/**
+ * Creates the canned-responses module — a thin typed wrapper over the generated client.
+ */
+declare function createCannedResponsesModule(options: CannedResponsesModuleOptions): {
+    /**
+     * List canned responses (paginated, no search filter).
+     * pageSize is clamped to 100 per the API contract.
+     * Calls GET /api/v1/canned-responses.
+     */
+    list(opts: CannedResponseListOpts): Promise<PagedList$5<CannedResponseItem>>;
+    /**
+     * Search canned responses by title substring or keyword prefix.
+     * pageSize is clamped to 100 per the API contract.
+     * Calls GET /api/v1/canned-responses?q=<term>.
+     */
+    search(opts: CannedResponseSearchOpts): Promise<PagedList$5<CannedResponseItem>>;
+    /**
+     * Create a canned response.
+     * Calls POST /api/v1/canned-responses.
+     */
+    create(input: CreateCannedResponseInput): Promise<CannedResponseItem>;
+    /**
+     * Partially update a canned response — title, body, and/or keywords.
+     * Calls PATCH /api/v1/canned-responses/:id.
+     */
+    update(id: string, input: UpdateCannedResponseInput): Promise<CannedResponseItem>;
+    /**
+     * Delete a canned response by id.
+     * Calls DELETE /api/v1/canned-responses/:id.
+     */
+    delete(id: string): Promise<void>;
+};
+/** Return type of createCannedResponsesModule. */
+type CannedResponsesModule = ReturnType<typeof createCannedResponsesModule>;
+
+/**
+ * Templates module — hand-written typed wrapper over the generated client.
+ *
+ * Exposes the Phase-2 templates surface via two submodules:
+ *
+ * whatsapp (WABA-scoped):
+ *   - authorDraft(tenantId, wabaId, input)          → POST  /api/v1/tenants/:id/whatsapp-business-accounts/:wabaId/templates
+ *   - importApproved(tenantId, wabaId)              → POST  /api/v1/tenants/:id/whatsapp-business-accounts/:wabaId/templates/import
+ *   - update(tenantId, wabaId, templateId, input)   → PATCH /api/v1/tenants/:id/whatsapp-business-accounts/:wabaId/templates/:templateId
+ *   - history(tenantId, wabaId, templateId)         → GET   /api/v1/tenants/:id/whatsapp-business-accounts/:wabaId/templates/:templateId/history
+ *   - submit(tenantId, wabaId, templateId)          → POST  /api/v1/tenants/:id/whatsapp-business-accounts/:wabaId/templates/:templateId/submit
+ *
+ * email (tenant-scoped):
+ *   - create(input)                                 → POST  /api/v1/templates/email
+ *   - list(opts)                                    → GET   /api/v1/templates/email
+ *   - getById(id)                                   → GET   /api/v1/templates/email/:id
+ *   - patch(id, input)                              → PATCH /api/v1/templates/email/:id
+ *   - delete(id)                                    → DELETE /api/v1/templates/email/:id
+ *
+ * Never re-exports symbols from _generated/.
+ * Contains no business logic — typed transport only.
+ */
+
+/** Options to construct the templates module. */
+interface TemplatesModuleOptions extends TokenProvider {
+    /** Base URL of the Omnivox API (e.g. "https://api.omnivox.io"). */
+    baseUrl: string;
+}
+/** Input for creating a new draft WhatsApp template (version 1). */
+interface AuthorDraftInput {
+    name: string;
+    language: string;
+    category?: string;
+    [key: string]: unknown;
+}
+/** Input for updating (forking a new DRAFT version of) a WhatsApp template. */
+interface UpdateWhatsAppTemplateInput {
+    body?: string;
+    [key: string]: unknown;
+}
+/** A WhatsApp template version history event. */
+interface WhatsAppTemplateHistoryEvent {
+    version: number;
+    status: string;
+    updatedAt: string;
+    [key: string]: unknown;
+}
+/** A WhatsApp template item returned by the API. */
+interface WhatsAppTemplateItem {
+    id: string;
+    name: string;
+    language: string;
+    status?: string;
+    [key: string]: unknown;
+}
+/** Import-approved result. */
+interface ImportApprovedResult {
+    imported: number;
+    [key: string]: unknown;
+}
+/** Submit result. */
+interface SubmitResult {
+    status: string;
+    [key: string]: unknown;
+}
+/** Input for creating an Email template. */
+interface CreateEmailTemplateInput {
+    name: string;
+    subject: string;
+    htmlBody?: string;
+    textBody?: string;
+    variableSchema?: Record<string, unknown>;
+    [key: string]: unknown;
+}
+/** Input for partially updating an Email template. */
+interface PatchEmailTemplateInput {
+    name?: string;
+    subject?: string;
+    htmlBody?: string;
+    textBody?: string;
+    variableSchema?: Record<string, unknown>;
+    [key: string]: unknown;
+}
+/** An Email template item returned by the API. */
+interface EmailTemplateItem {
+    id: string;
+    name: string;
+    subject: string;
+    htmlBody?: string;
+    textBody?: string;
+    variableSchema?: Record<string, unknown>;
+    [key: string]: unknown;
+}
+/** Paginated list response. */
+interface TemplatesPagedList<T> {
+    data: T[];
+    meta: {
+        page: number;
+        pageSize: number;
+        total: number;
+        hasNextPage: boolean;
+    };
+}
+/** Pagination options for email templates list. */
+interface EmailTemplateListOpts {
+    page: number;
+    pageSize: number;
+    [key: string]: unknown;
+}
+/**
+ * Creates the templates module — a thin typed wrapper over the generated client.
+ * Returns two submodules: `whatsapp` (WABA-scoped) and `email` (tenant-scoped).
+ */
+declare function createTemplatesModule(options: TemplatesModuleOptions): {
+    /**
+     * WhatsApp template submodule — WABA-scoped operations.
+     */
+    whatsapp: {
+        /**
+         * Author a new DRAFT template (version 1) under a WhatsApp Business Account.
+         * Calls POST /api/v1/tenants/:id/whatsapp-business-accounts/:wabaId/templates.
+         */
+        authorDraft(tenantId: string, wabaId: string, input: AuthorDraftInput): Promise<WhatsAppTemplateItem>;
+        /**
+         * Import all APPROVED templates from the WABA into the system (immediately sendable).
+         * Calls POST /api/v1/tenants/:id/whatsapp-business-accounts/:wabaId/templates/import.
+         */
+        importApproved(tenantId: string, wabaId: string): Promise<ImportApprovedResult>;
+        /**
+         * Fork a new DRAFT version from the latest version of a template (update).
+         * Calls PATCH /api/v1/tenants/:id/whatsapp-business-accounts/:wabaId/templates/:templateId.
+         */
+        update(tenantId: string, wabaId: string, templateId: string, input: UpdateWhatsAppTemplateInput): Promise<WhatsAppTemplateItem>;
+        /**
+         * List all versions and status events for a template in chronological order.
+         * Calls GET /api/v1/tenants/:id/whatsapp-business-accounts/:wabaId/templates/:templateId/history.
+         */
+        history(tenantId: string, wabaId: string, templateId: string): Promise<WhatsAppTemplateHistoryEvent[]>;
+        /**
+         * Submit a DRAFT template version to Meta for review and approval (DRAFT → PENDING_APPROVAL).
+         * Calls POST /api/v1/tenants/:id/whatsapp-business-accounts/:wabaId/templates/:templateId/submit.
+         */
+        submit(tenantId: string, wabaId: string, templateId: string): Promise<SubmitResult>;
+    };
+    /**
+     * Email template submodule — tenant-scoped operations.
+     */
+    email: {
+        /**
+         * Create an Email template for the authenticated tenant.
+         * Calls POST /api/v1/templates/email.
+         */
+        create(input: CreateEmailTemplateInput): Promise<EmailTemplateItem>;
+        /**
+         * List Email templates for the authenticated tenant (paginated).
+         * Calls GET /api/v1/templates/email.
+         */
+        list(opts: EmailTemplateListOpts): Promise<TemplatesPagedList<EmailTemplateItem>>;
+        /**
+         * Get an Email template by id.
+         * Calls GET /api/v1/templates/email/:id.
+         */
+        getById(id: string): Promise<EmailTemplateItem>;
+        /**
+         * Partially update an Email template — name, subject, htmlBody, textBody, and/or variableSchema; omitted fields unchanged.
+         * Calls PATCH /api/v1/templates/email/:id.
+         */
+        patch(id: string, input: PatchEmailTemplateInput): Promise<EmailTemplateItem>;
+        /**
+         * Delete an Email template.
+         * Calls DELETE /api/v1/templates/email/:id.
+         */
+        delete(id: string): Promise<void>;
+    };
+};
+/** Return type of createTemplatesModule. */
+type TemplatesModule = ReturnType<typeof createTemplatesModule>;
+
 /**
  * Messages module — hand-written typed wrapper over the generated client.
  *
  * Exposes the Phase-1 messaging surface for the messages resource:
  *   - send(input)              → POST   /api/v1/messages
+ *   - sendTemplate(input)      → POST   /api/v1/messages/send-template
  *   - list(opts)               → GET    /api/v1/messages (pageSize capped at 100)
  *   - get(id)                  → GET    /api/v1/messages/:id
  *   - delete(id)               → DELETE /api/v1/messages/:id
@@ -55,8 +333,22 @@ interface MessagesModuleOptions extends TokenProvider {
 interface SendMessageInput {
     conversationId: string;
     body: string;
+    /**
+     * Optional list of draft attachment UUIDs to link to this message (F11-T05).
+     * Omitting the field (or passing []) skips linking.
+     */
+    attachmentIds?: string[];
     [key: string]: unknown;
 }
+/** Input for sending a template message in a conversation. */
+interface SendTemplateInput {
+    conversationId: string;
+    templateId: string;
+    /** Positional variables for WhatsApp templates (index-ordered). */
+    variables?: string[];
+    /** Named variables for Email templates (key = variable name from variableSchema). */
+    emailVariables?: Record<string, string>;
+}
 /** Message resource shape returned by the API. */
 interface MessageItem {
     id: string;
@@ -106,6 +398,13 @@ declare function createMessagesModule(options: MessagesModuleOptions): {
      * Calls DELETE /api/v1/messages/:id.
      */
     delete(id: string): Promise<void>;
+    /**
+     * Send a template message in a conversation (WhatsApp or Email).
+     * Branches on the conversation channel type — WhatsApp uses positional
+     * `variables`; Email uses named `emailVariables`.
+     * Calls POST /api/v1/messages/send-template.
+     */
+    sendTemplate(input: SendTemplateInput): Promise<MessageItem>;
 };
 /** Return type of createMessagesModule. */
 type MessagesModule = ReturnType<typeof createMessagesModule>;
@@ -120,6 +419,7 @@ type MessagesModule = ReturnType<typeof createMessagesModule>;
  *   - assign(id, input)               → PATCH /api/v1/conversations/:id/assign
  *   - listLobby(opts)                 → GET   /api/v1/conversations/lobby (pageSize capped at 100)
  *   - pickup(entryId, input)          → POST  /api/v1/conversations/lobby/:entryId/pickup
+ *   - whatsappRecoveryOptions(id)     → GET   /api/v1/conversations/:id/whatsapp-recovery-options
  *
  * Never re-exports symbols from _generated/.
  * Contains no business logic — typed transport only.
@@ -193,6 +493,17 @@ interface LobbyListOpts {
     page: number;
     pageSize: number;
 }
+/**
+ * A single WhatsApp template eligible to re-open an expired 24-hour
+ * customer-service window. Mirrors RecoveryOptionResult from the API service.
+ */
+interface WhatsAppRecoveryOption {
+    templateId: string;
+    name: string;
+    language: string;
+    versionId: string;
+    versionNumber: number;
+}
 /**
  * Creates the conversations module — a thin typed wrapper over the generated client.
  */
@@ -238,6 +549,13 @@ declare function createConversationsModule(options: ConversationsModuleOptions):
     pickup(entryId: string, input: PickupInput): Promise<{
         data: ConversationItem;
     }>;
+    /**
+     * List APPROVED + SENDABLE WhatsApp templates eligible to re-open an
+     * expired 24-hour customer-service window for the given conversation.
+     * Returns an empty array when the channel is not WhatsApp or has no linked WABA.
+     * Calls GET /api/v1/conversations/:id/whatsapp-recovery-options.
+     */
+    whatsappRecoveryOptions(id: string): Promise<WhatsAppRecoveryOption[]>;
 };
 /** Return type of createConversationsModule. */
 type ConversationsModule = ReturnType<typeof createConversationsModule>;
@@ -550,6 +868,203 @@ declare function createTenantsModule(options: TenantsModuleOptions): {
 /** Return type of createTenantsModule. */
 type TenantsModule = ReturnType<typeof createTenantsModule>;
 
+/**
+ * WS-only event payload registry — single source of truth for the four
+ * WS-only events that have no REST/openapi counterpart and therefore no
+ * orval → _generated pipeline:
+ *
+ *   typing:indicator  ·  message:read:update  ·  participant:joined  ·  participant:left
+ *
+ * The runtime constant {@link WS_EVENT_REGISTRY} must stay byte-identical with
+ * ws-event-shapes.fixture.json. Two contract tests enforce this:
+ *
+ *   1. packages/sdk/src/ws/ws-event-registry.test.ts — asserts WS_EVENT_REGISTRY
+ *      matches the fixture at the SDK level.
+ *   2. apps/api/tests/contract/ws-event-shapes.test.ts — asserts the ChatGateway
+ *      source emits each event with exactly the fields listed in the fixture.
+ *
+ * Any divergence — whether the gateway changes an emit payload or this registry
+ * drifts from the fixture — fails CI before the change can ship.
+ *
+ * Typed transport only — no imports from apps/api/, no _generated/ re-exports,
+ * no business logic.
+ */
+/**
+ * Payload for the `typing:indicator` server → client event.
+ * Emitted by the gateway when an agent starts or stops typing in a conversation.
+ */
+interface TypingIndicatorPayload {
+    conversationId: string;
+    actor: unknown;
+    state: 'start' | 'stop';
+}
+/**
+ * Payload for the `message:read:update` server → client event.
+ * Emitted when an agent's read cursor advances in a conversation.
+ */
+interface MessageReadUpdatePayload {
+    conversationId: string;
+    agentId: string;
+    lastReadMessageId: string;
+    readAt: string;
+    [key: string]: unknown;
+}
+/**
+ * Payload for the `participant:joined` and `participant:left` server → client events.
+ * Emitted when an agent enters or leaves a conversation room.
+ */
+interface ParticipantPayload {
+    conversationId: string;
+    actor: unknown;
+    [key: string]: unknown;
+}
+
+/**
+ * WebSocket client — hand-written typed wrapper over socket.io-client.
+ *
+ * Connects to the Omnivox API's `/ws/chat` namespace. Reconnection with
+ * exponential backoff + jitter (cap 30 s) is configured automatically —
+ * the consumer never needs to wire reconnect logic.
+ *
+ * Event payloads for the four WS-only events (typing:indicator,
+ * message:read:update, participant:joined, participant:left) are defined once
+ * in ws-event-registry.ts and imported here. All other payload types
+ * (message:new, message:status, conversation:update) are defined locally
+ * because they mirror the REST openapi view contracts.
+ *
+ * Never re-exports symbols from _generated/.
+ * Contains no business logic — typed transport only.
+ */
+
+/** Authentication credential for the WebSocket handshake. */
+type WsAuth = {
+    token: string;
+} | {
+    apiKey: string;
+};
+/** Observable connection state for the WebSocket client. */
+type WsConnectionState = 'connecting' | 'connected' | 'reconnecting' | 'disconnected';
+/** Options to construct the WS client. */
+interface WsClientOptions {
+    /**
+     * Base URL of the Omnivox API (e.g. "https://api.omnivox.io").
+     * The WS client appends `/ws/chat` to form the namespace URL.
+     */
+    baseUrl: string;
+    /**
+     * Authentication for the Socket.IO handshake.
+     * Pass `{ token }` for session/OIDC auth or `{ apiKey }` for API-key auth.
+     * These map directly to `socket.handshake.auth.token` /
+     * `socket.handshake.auth.apiKey` on the server.
+     *
+     * Omit entirely when authenticating via an HttpOnly session cookie — the
+     * browser sends the cookie automatically when `withCredentials` is true.
+     */
+    auth?: WsAuth;
+    /**
+     * When true, socket.io-client sends credentials (cookies, TLS client certs)
+     * on the polling/WebSocket handshake requests. Required for the Console,
+     * which authenticates via an HttpOnly SESSION COOKIE with no explicit token.
+     *
+     * Defaults to false (matches socket.io-client's default).
+     */
+    withCredentials?: boolean;
+}
+/** Payload for the `message:status` server event. */
+interface MessageStatusPayload {
+    messageId: string;
+    conversationId: string;
+    status: string;
+    [key: string]: unknown;
+}
+/**
+ * Maps every server-emitted event name to its payload type.
+ *
+ * `message:new` and `conversation:update` reuse the SDK's MessageItem /
+ * ConversationItem types which mirror the openapi view contracts.
+ * All other payload types are defined locally — only the mapping is hand-written.
+ */
+interface WsEventPayloads {
+    'message:new': MessageItem;
+    'message:status': MessageStatusPayload;
+    'conversation:update': ConversationItem;
+    'message:read:update': MessageReadUpdatePayload;
+    'participant:joined': ParticipantPayload;
+    'participant:left': ParticipantPayload;
+    'typing:indicator': TypingIndicatorPayload;
+}
+/** The WebSocket client returned by {@link createWsClient}. */
+interface WsClient {
+    /** Current connection state — safe to read synchronously at any time. */
+    readonly state: WsConnectionState;
+    /**
+     * Subscribe to connection state changes.
+     * Returns an unsubscribe function. Call it to stop receiving notifications.
+     */
+    onStateChange(listener: (state: WsConnectionState) => void): () => void;
+    /**
+     * Subscribe to a typed server event.
+     * Returns an unsubscribe function. Call it to remove the handler.
+     *
+     * @example
+     * const unsub = client.on('message:new', (msg) => console.log(msg.id))
+     * // later:
+     * unsub()
+     */
+    on<K extends keyof WsEventPayloads>(event: K, handler: (payload: WsEventPayloads[K]) => void): () => void;
+    /**
+     * Request to join a conversation room.
+     * Emits `conversation:join` to the server; the server verifies ownership
+     * before adding the socket to the room.
+     */
+    joinConversation(conversationId: string): void;
+    /**
+     * Request to leave a conversation room.
+     * Emits `conversation:leave` to the server.
+     */
+    leaveConversation(conversationId: string): void;
+    /**
+     * Signal that the local agent started typing in a conversation.
+     * Emits `typing:start` to the server.
+     */
+    typingStart(conversationId: string): void;
+    /**
+     * Signal that the local agent stopped typing in a conversation.
+     * Emits `typing:stop` to the server.
+     */
+    typingStop(conversationId: string): void;
+    /**
+     * Mark messages as read up to and including `lastReadMessageId`.
+     * Emits `message:read` to the server.
+     */
+    markRead(conversationId: string, lastReadMessageId: string): void;
+    /**
+     * Disconnect the socket and release all internal resources.
+     * After calling this, the client is unusable.
+     */
+    disconnect(): void;
+}
+/**
+ * Creates a WebSocket client connected to `<baseUrl>/ws/chat`.
+ *
+ * Reconnection is fully automatic — the consumer must not wire reconnect logic.
+ * The socket reconnects with exponential backoff starting at 1 s, doubling
+ * each attempt with ±50 % jitter, capped at 30 s. Socket.IO handles all
+ * transport-level retry internally.
+ *
+ * @example
+ * const ws = createWsClient({
+ *   baseUrl: 'https://api.omnivox.io',
+ *   auth: { apiKey: 'ovx_live_abc123' },
+ * })
+ *
+ * const unsub = ws.on('message:new', (msg) => console.log(msg))
+ * ws.joinConversation('conv_001')
+ */
+declare function createWsClient(options: WsClientOptions): WsClient;
+/** Return type of {@link createWsClient}. */
+type WsClientInstance = ReturnType<typeof createWsClient>;
+
 /** Options for {@link createOmnivoxClient}. */
 interface OmnivoxClientOptions {
     /** Base URL of the Omnivox API (e.g. "https://api.omnivox.io"). */
@@ -560,6 +1075,7 @@ interface OmnivoxClientOptions {
      */
     tokenProvider: TokenProvider;
 }
+
 /**
  * Creates a composed Omnivox client exposing every Phase-1 resource module.
  * The token provider is read per request (not captured at construction), so
@@ -614,13 +1130,66 @@ declare function createOmnivoxClient(options: OmnivoxClientOptions): {
         pickup(entryId: string, input: PickupInput): Promise<{
             data: ConversationItem;
         }>;
+        whatsappRecoveryOptions(id: string): Promise<WhatsAppRecoveryOption[]>;
     };
     messages: {
         send(input: SendMessageInput): Promise<MessageItem>;
         list(opts: MessageListOpts): Promise<PagedList$4<MessageItem>>;
         get(id: string): Promise<MessageItem>;
         delete(id: string): Promise<void>;
+        sendTemplate(input: SendTemplateInput): Promise<MessageItem>;
+    };
+    templates: {
+        whatsapp: {
+            authorDraft(tenantId: string, wabaId: string, input: AuthorDraftInput): Promise<WhatsAppTemplateItem>;
+            importApproved(tenantId: string, wabaId: string): Promise<ImportApprovedResult>;
+            update(tenantId: string, wabaId: string, templateId: string, input: UpdateWhatsAppTemplateInput): Promise<WhatsAppTemplateItem>;
+            history(tenantId: string, wabaId: string, templateId: string): Promise<WhatsAppTemplateHistoryEvent[]>;
+            submit(tenantId: string, wabaId: string, templateId: string): Promise<SubmitResult>;
+        };
+        email: {
+            create(input: CreateEmailTemplateInput): Promise<EmailTemplateItem>;
+            list(opts: EmailTemplateListOpts): Promise<TemplatesPagedList<EmailTemplateItem>>;
+            getById(id: string): Promise<EmailTemplateItem>;
+            patch(id: string, input: PatchEmailTemplateInput): Promise<EmailTemplateItem>;
+            delete(id: string): Promise<void>;
+        };
+    };
+    cannedResponses: {
+        list(opts: CannedResponseListOpts): Promise<PagedList$5<CannedResponseItem>>;
+        search(opts: CannedResponseSearchOpts): Promise<PagedList$5<CannedResponseItem>>;
+        create(input: CreateCannedResponseInput): Promise<CannedResponseItem>;
+        update(id: string, input: UpdateCannedResponseInput): Promise<CannedResponseItem>;
+        delete(id: string): Promise<void>;
+    };
+    attachments: {
+        upload(file: Blob | Uint8Array, _opts?: Record<string, unknown>): Promise<AttachmentUploadResult>;
+        url(id: string): Promise<AttachmentUrlResult>;
     };
+    whatsappBusinessAccounts: {
+        list(tenantId: string): Promise<WhatsAppBusinessAccountItem[]>;
+        get(tenantId: string, wabaRowId: string): Promise<WhatsAppBusinessAccountItem>;
+    };
+    /**
+     * Creates a WebSocket client connected to the `/ws/chat` namespace.
+     *
+     * Call this factory once and reuse the returned client. Reconnection with
+     * exponential backoff + jitter (cap 30 s) is fully automatic.
+     *
+     * For API-key or token auth, pass the credential explicitly:
+     * @example
+     * const ws = client.connect({ apiKey: 'ovx_live_abc' })
+     * ws.on('message:new', (msg) => console.log(msg))
+     * ws.joinConversation('conv_001')
+     *
+     * For session/cookie auth (Console), call with no argument — the token
+     * provider's `getCredentials() === 'include'` signals cookie mode and
+     * `withCredentials` is set automatically:
+     * @example
+     * const ws = client.connect()
+     * ws.on('message:new', (msg) => console.log(msg))
+     */
+    connect: (auth?: WsAuth) => WsClient;
 };
 /** Composed client returned by {@link createOmnivoxClient}. */
 type OmnivoxClient = ReturnType<typeof createOmnivoxClient>;
@@ -896,4 +1465,127 @@ declare function createChannelsModule(options: ChannelsModuleOptions): {
 /** Return type of createChannelsModule. */
 type ChannelsModule = ReturnType<typeof createChannelsModule>;
 
-export { type AddIdentityInput, type AgentItem, type AgentsModule, type AgentsModuleOptions, type ApiKeyItem, type AssignInput, type AuthMeAgent, type AuthMeModule, type AuthMeModuleOptions, type AuthMeResponse, type AuthMeTenant, type BasicEmailChannelConfig, type BasicEmailChannelSecret, type Channel, type ChannelListItem, type ChannelStatus, type ChannelType, type ChannelsModule, type ChannelsModuleOptions, type ContactIdentity, type ContactIdentityInput, type ContactItem, type ContactSearchOpts, type ContactsMetadata, type ContactsModule, type ContactsModuleOptions, type ConversationItem, type ConversationListOpts, type ConversationsModule, type ConversationsModuleOptions, type CreateAgentInput, type CreateApiKeyInput, type CreateApiKeyResponse, type CreateChannelBody, type CreateContactInput, type CreateEmailChannelBody, type CreateWhatsAppChannelBody, type CredentialsMode, type EmailChannelConfig, type EmailChannelSecret, type EmailImapConfig, type EmailSmtpConfig, type LobbyEntry, type LobbyListOpts, type MessageItem, type MessageListOpts, type MessagesModule, type MessagesModuleOptions, type OAuth2CertificateEmailChannelSecret, type OAuth2ClientSecretEmailChannelSecret, type OAuth2EmailChannelConfig, type OAuth2EmailChannelSecret, type OmnivoxClient, type OmnivoxClientOptions, OmnivoxRequestError, type PageOpts, type PageParams, type PagedResponse, type PatchContactInput, type PickupInput, type ReopenOrCreateInput, type RevokeApiKeyResponse, type SendMessageInput, type TenantsModule, type TenantsModuleOptions, type TokenProvider, type UpdateChannelBody, type UpdateStatusInput, type WhatsAppChannelConfig, buildPageParams, createAgentsModule, createApiKeyTokenProvider, createAuthMeModule, createChannelsModule, createContactsModule, createConversationsModule, createMessagesModule, createOmnivoxClient, createSessionTokenProvider, createTenantsModule, iteratePages };
+/**
+ * Attachments module — hand-written typed wrapper over the generated client.
+ *
+ * Exposes the Phase-2 attachment surface:
+ *   - upload(file, opts?)  → POST  /api/v1/attachments  (multipart/form-data)
+ *   - url(id)              → GET   /api/v1/attachments/:id/url
+ *
+ * Upload works in both Node 22+ (Blob/Uint8Array) and the browser (File/Blob).
+ * Content-Type is NOT set manually — fetch sets the multipart boundary.
+ *
+ * Never re-exports symbols from _generated/.
+ * Contains no business logic — typed transport only.
+ */
+
+/** Options to construct the attachments module. */
+interface AttachmentsModuleOptions extends TokenProvider {
+    /** Base URL of the Omnivox API (e.g. "https://api.omnivox.io"). */
+    baseUrl: string;
+}
+/** Response shape returned by POST /api/v1/attachments. */
+interface AttachmentUploadResult {
+    /** Opaque attachment identifier. Pass this to the send-message endpoint. */
+    attachmentId: string;
+    /** MIME type detected by the API. */
+    mimeType: string;
+    /** File size in bytes. */
+    sizeBytes: number;
+}
+/** Response shape returned by GET /api/v1/attachments/:id/url. */
+interface AttachmentUrlResult {
+    /** Short-lived presigned GET URL (TTL ≤ 15 min). */
+    url: string;
+    /** ISO-8601 string at which the presigned URL expires. */
+    expiresAt: string;
+}
+/**
+ * Creates the attachments module — a thin typed wrapper over the generated client.
+ */
+declare function createAttachmentsModule(options: AttachmentsModuleOptions): {
+    /**
+     * Upload a file as a draft attachment.
+     *
+     * Accepts a Blob or File (browser) or a Uint8Array wrapped in a Blob (Node 22+).
+     * Content-Type is intentionally omitted from headers so that fetch (both
+     * Node 22 built-in and browser) can set the multipart/form-data boundary.
+     *
+     * Calls POST /api/v1/attachments.
+     */
+    upload(file: Blob | Uint8Array, _opts?: Record<string, unknown>): Promise<AttachmentUploadResult>;
+    /**
+     * Get a short-lived presigned download URL for a stored attachment.
+     * The URL is valid for ≤ 15 minutes (NF-09).
+     *
+     * Calls GET /api/v1/attachments/:id/url.
+     */
+    url(id: string): Promise<AttachmentUrlResult>;
+};
+/** Return type of createAttachmentsModule. */
+type AttachmentsModule = ReturnType<typeof createAttachmentsModule>;
+
+/**
+ * WhatsApp Business Accounts module — hand-written typed wrapper over the generated client.
+ *
+ * Exposes the WABA read surface (WABA-as-identity, tenant-scoped):
+ *   - list(tenantId)           → GET /api/v1/tenants/:id/whatsapp-business-accounts
+ *   - get(tenantId, wabaRowId) → GET /api/v1/tenants/:id/whatsapp-business-accounts/:wabaRowId
+ *
+ * The Console's WhatsApp templates page uses this to let an admin pick a WABA
+ * before authoring templates (`sdk.templates.whatsapp.*` requires a `wabaId`).
+ *
+ * Never re-exports symbols from _generated/.
+ * Contains no business logic — typed transport only.
+ */
+
+/** Options to construct the WhatsApp Business Accounts module. */
+interface WhatsAppBusinessAccountsModuleOptions extends TokenProvider {
+    /** Base URL of the Omnivox API (e.g. "https://api.omnivox.io"). */
+    baseUrl: string;
+}
+/**
+ * Non-secret WABA view returned by the API.
+ * Never includes `secretRef` or any secret material (ADR-0011).
+ */
+interface WhatsAppBusinessAccountItem {
+    /** Row id (internal, use this for template API calls as `wabaId`). */
+    id: string;
+    /** The Meta WABA id string stored on the row. */
+    wabaId: string;
+    /** Human-readable display name set by the tenant admin. */
+    name: string;
+    /** ISO 8601 creation timestamp. */
+    createdAt: string;
+    /** ISO 8601 last-updated timestamp. */
+    updatedAt: string;
+}
+/**
+ * Creates the WhatsApp Business Accounts module — a thin typed wrapper over
+ * the generated client. Covers the WABA read surface (list + get by row id).
+ */
+declare function createWhatsAppBusinessAccountsModule(options: WhatsAppBusinessAccountsModuleOptions): {
+    /**
+     * List all WhatsApp Business Accounts for the tenant.
+     * Returns a non-secret view — no secretRef is exposed.
+     * Calls GET /api/v1/tenants/:id/whatsapp-business-accounts.
+     *
+     * @example
+     * const wabas = await sdk.whatsappBusinessAccounts.list('ten_acmecorp')
+     * // pick wabas[0].id as the wabaId for sdk.templates.whatsapp.*
+     */
+    list(tenantId: string): Promise<WhatsAppBusinessAccountItem[]>;
+    /**
+     * Get a single WhatsApp Business Account by its row id.
+     * Returns a non-secret view — no secretRef is exposed.
+     * Calls GET /api/v1/tenants/:id/whatsapp-business-accounts/:wabaRowId.
+     *
+     * @example
+     * const waba = await sdk.whatsappBusinessAccounts.get('ten_acmecorp', 'waba_row_001')
+     */
+    get(tenantId: string, wabaRowId: string): Promise<WhatsAppBusinessAccountItem>;
+};
+/** Return type of createWhatsAppBusinessAccountsModule. */
+type WhatsAppBusinessAccountsModule = ReturnType<typeof createWhatsAppBusinessAccountsModule>;
+
+export { type AddIdentityInput, type AgentItem, type AgentsModule, type AgentsModuleOptions, type ApiKeyItem, type AssignInput, type AttachmentUploadResult, type AttachmentUrlResult, type AttachmentsModule, type AttachmentsModuleOptions, type AuthMeAgent, type AuthMeModule, type AuthMeModuleOptions, type AuthMeResponse, type AuthMeTenant, type AuthorDraftInput, type BasicEmailChannelConfig, type BasicEmailChannelSecret, type CannedResponseItem, type CannedResponseListOpts, type CannedResponseSearchOpts, type CannedResponsesModule, type CannedResponsesModuleOptions, type Channel, type ChannelListItem, type ChannelStatus, type ChannelType, type ChannelsModule, type ChannelsModuleOptions, type ContactIdentity, type ContactIdentityInput, type ContactItem, type ContactSearchOpts, type ContactsMetadata, type ContactsModule, type ContactsModuleOptions, type ConversationItem, type ConversationListOpts, type ConversationsModule, type ConversationsModuleOptions, type CreateAgentInput, type CreateApiKeyInput, type CreateApiKeyResponse, type CreateCannedResponseInput, type CreateChannelBody, type CreateContactInput, type CreateEmailChannelBody, type CreateEmailTemplateInput, type CreateWhatsAppChannelBody, type CredentialsMode, type EmailChannelConfig, type EmailChannelSecret, type EmailImapConfig, type EmailSmtpConfig, type EmailTemplateItem, type EmailTemplateListOpts, type ImportApprovedResult, type LobbyEntry, type LobbyListOpts, type MessageItem, type MessageListOpts, type MessageReadUpdatePayload, type MessageStatusPayload, type MessagesModule, type MessagesModuleOptions, type OAuth2CertificateEmailChannelSecret, type OAuth2ClientSecretEmailChannelSecret, type OAuth2EmailChannelConfig, type OAuth2EmailChannelSecret, type OmnivoxClient, type OmnivoxClientOptions, OmnivoxRequestError, type PageOpts, type PageParams, type PagedResponse, type ParticipantPayload, type PatchContactInput, type PatchEmailTemplateInput, type PickupInput, type ReopenOrCreateInput, type RevokeApiKeyResponse, type SendMessageInput, type SendTemplateInput, type SubmitResult, type TemplatesModule, type TemplatesModuleOptions, type TenantsModule, type TenantsModuleOptions, type TokenProvider, type TypingIndicatorPayload, type UpdateCannedResponseInput, type UpdateChannelBody, type UpdateStatusInput, type UpdateWhatsAppTemplateInput, type WhatsAppBusinessAccountItem, type WhatsAppBusinessAccountsModule, type WhatsAppBusinessAccountsModuleOptions, type WhatsAppChannelConfig, type WhatsAppRecoveryOption, type WhatsAppTemplateHistoryEvent, type WhatsAppTemplateItem, type WsAuth, type WsClient, type WsClientInstance, type WsClientOptions, type WsConnectionState, type WsEventPayloads, buildPageParams, createAgentsModule, createApiKeyTokenProvider, createAttachmentsModule, createAuthMeModule, createCannedResponsesModule, createChannelsModule, createContactsModule, createConversationsModule, createMessagesModule, createOmnivoxClient, createSessionTokenProvider, createTemplatesModule, createTenantsModule, createWhatsAppBusinessAccountsModule, createWsClient, iteratePages };