@elqnt/chat 2.0.8 → 3.0.1

package/dist/transport/index.d.ts

@@ -0,0 +1,243 @@
+import { R as RetryConfig, T as TransportLogger, C as ChatTransport, a as TransportConfig } from '../types-7UNI1iYv.js';
+export { b as ConnectionMetrics, c as CreateChatOptions, D as DEFAULT_RETRY_CONFIG, E as EndChatOptions, d as EventHandler, L as LoadChatOptions, S as SendMessageOptions, e as TransportError, f as TransportFactory, g as TransportState, U as Unsubscribe, h as calculateRetryInterval, i as createLogger } from '../types-7UNI1iYv.js';
+import { ChatEvent } from '../models/index.js';
+import '@elqnt/types';
+
+/**
+ * SSE Transport (Browser)
+ *
+ * Uses native EventSource for receiving server events and fetch POST for sending.
+ * This is the default transport for browser environments.
+ *
+ * @example
+ * ```typescript
+ * import { createSSETransport } from "@elqnt/chat/transport";
+ *
+ * const transport = createSSETransport();
+ * await transport.connect({ baseUrl, orgId, userId, clientType: "customer" });
+ * ```
+ */
+
+/**
+ * SSE Transport options
+ */
+interface SSETransportOptions {
+    /** Retry configuration */
+    retryConfig?: RetryConfig;
+    /** Enable debug logging */
+    debug?: boolean;
+    /** Custom logger */
+    logger?: TransportLogger;
+}
+/**
+ * Create an SSE transport for browser environments
+ */
+declare function createSSETransport(options?: SSETransportOptions): ChatTransport;
+
+/**
+ * SSE Transport (Fetch-based)
+ *
+ * Uses fetch with ReadableStream for receiving server events and fetch POST for sending.
+ * Designed for React Native and environments without native EventSource support.
+ *
+ * @example
+ * ```typescript
+ * import { createFetchSSETransport } from "@elqnt/chat/transport";
+ *
+ * const transport = createFetchSSETransport();
+ * await transport.connect({ baseUrl, orgId, userId, clientType: "customer" });
+ * ```
+ */
+
+/**
+ * Fetch SSE Transport options
+ */
+interface FetchSSETransportOptions {
+    /** Retry configuration */
+    retryConfig?: RetryConfig;
+    /** Enable debug logging */
+    debug?: boolean;
+    /** Custom logger */
+    logger?: TransportLogger;
+    /** Custom fetch implementation (useful for React Native) */
+    customFetch?: typeof fetch;
+}
+/**
+ * Create a fetch-based SSE transport for React Native and polyfill environments
+ */
+declare function createFetchSSETransport(options?: FetchSSETransportOptions): ChatTransport;
+
+/**
+ * WhatsApp Business API Transport (Stub)
+ *
+ * This module provides the interface for integrating with WhatsApp Business API.
+ * The implementation connects to a webhook receiver that bridges WhatsApp messages
+ * to the chat system.
+ *
+ * ## Integration Architecture
+ *
+ * ```
+ * WhatsApp User → WhatsApp Cloud API → Your Webhook → Chat Service → SSE to Admin
+ *                                                   ↓
+ *                                              NATS Events
+ * ```
+ *
+ * ## Setup Requirements
+ *
+ * 1. Register a WhatsApp Business Account
+ * 2. Create a Meta Business App with WhatsApp integration
+ * 3. Configure webhook URL pointing to your chat service
+ * 4. Set up message templates for outbound messages
+ *
+ * ## Backend Integration
+ *
+ * Your backend should expose webhook endpoints that:
+ * - Verify webhook (GET /webhook with hub.verify_token)
+ * - Receive messages (POST /webhook with message payload)
+ * - Map WhatsApp user IDs to chat users
+ * - Create/load chats for new conversations
+ *
+ * @example Backend Webhook Handler (Go)
+ * ```go
+ * func HandleWhatsAppWebhook(w http.ResponseWriter, r *http.Request) {
+ *     if r.Method == "GET" {
+ *         // Webhook verification
+ *         verifyToken := r.URL.Query().Get("hub.verify_token")
+ *         if verifyToken == os.Getenv("WHATSAPP_VERIFY_TOKEN") {
+ *             w.Write([]byte(r.URL.Query().Get("hub.challenge")))
+ *             return
+ *         }
+ *         http.Error(w, "Invalid verify token", 403)
+ *         return
+ *     }
+ *
+ *     // Handle incoming message
+ *     var payload WhatsAppPayload
+ *     json.NewDecoder(r.Body).Decode(&payload)
+ *
+ *     // Map to chat event and publish to NATS
+ *     chatEvent := mapWhatsAppToChatEvent(payload)
+ *     natsClient.Publish("chat.events", chatEvent)
+ * }
+ * ```
+ *
+ * @see https://developers.facebook.com/docs/whatsapp/cloud-api
+ */
+
+/**
+ * WhatsApp transport configuration
+ */
+interface WhatsAppTransportConfig extends TransportConfig {
+    /** WhatsApp Business API access token */
+    accessToken: string;
+    /** Phone number ID from Meta Business */
+    phoneNumberId: string;
+    /** Webhook verify token for setup */
+    verifyToken?: string;
+}
+/**
+ * WhatsApp transport options
+ */
+interface WhatsAppTransportOptions {
+    /** Enable debug logging */
+    debug?: boolean;
+    /** Custom logger */
+    logger?: TransportLogger;
+}
+/**
+ * WhatsApp message types
+ */
+type WhatsAppMessageType = "text" | "image" | "document" | "audio" | "video" | "sticker" | "location" | "contacts" | "interactive" | "template";
+/**
+ * Create a WhatsApp Business API transport
+ *
+ * NOTE: This is a stub implementation. The actual WhatsApp integration
+ * happens on the backend via webhooks. This transport is for:
+ * - Type definitions
+ * - Documentation
+ * - Future client-side WhatsApp Web integration
+ */
+declare function createWhatsAppTransport(options?: WhatsAppTransportOptions): ChatTransport;
+/**
+ * Helper: Convert WhatsApp webhook payload to ChatEvent
+ *
+ * Use this in your backend webhook handler to map incoming
+ * WhatsApp messages to the chat system format.
+ */
+interface WhatsAppWebhookPayload {
+    object: "whatsapp_business_account";
+    entry: Array<{
+        id: string;
+        changes: Array<{
+            value: {
+                messaging_product: "whatsapp";
+                metadata: {
+                    display_phone_number: string;
+                    phone_number_id: string;
+                };
+                contacts?: Array<{
+                    profile: {
+                        name: string;
+                    };
+                    wa_id: string;
+                }>;
+                messages?: Array<{
+                    from: string;
+                    id: string;
+                    timestamp: string;
+                    type: WhatsAppMessageType;
+                    text?: {
+                        body: string;
+                    };
+                    image?: {
+                        id: string;
+                        mime_type: string;
+                        sha256: string;
+                    };
+                    document?: {
+                        id: string;
+                        mime_type: string;
+                        filename: string;
+                    };
+                    audio?: {
+                        id: string;
+                        mime_type: string;
+                    };
+                    video?: {
+                        id: string;
+                        mime_type: string;
+                    };
+                    location?: {
+                        latitude: number;
+                        longitude: number;
+                        name?: string;
+                    };
+                }>;
+                statuses?: Array<{
+                    id: string;
+                    status: "sent" | "delivered" | "read" | "failed";
+                    timestamp: string;
+                    recipient_id: string;
+                }>;
+            };
+        }>;
+    }>;
+}
+/**
+ * Example: Map WhatsApp payload to ChatEvent (for backend use)
+ *
+ * @example
+ * ```typescript
+ * // In your backend webhook handler
+ * import { mapWhatsAppToChatEvent } from "@elqnt/chat/transport";
+ *
+ * app.post("/webhook/whatsapp", (req, res) => {
+ *   const events = mapWhatsAppToChatEvent(req.body, orgId);
+ *   events.forEach(event => publishToChatService(event));
+ *   res.sendStatus(200);
+ * });
+ * ```
+ */
+declare function mapWhatsAppToChatEvent(payload: WhatsAppWebhookPayload, orgId: string): ChatEvent[];
+
+export { ChatTransport, type FetchSSETransportOptions, RetryConfig, type SSETransportOptions, TransportConfig, TransportLogger, type WhatsAppMessageType, type WhatsAppTransportConfig, type WhatsAppTransportOptions, type WhatsAppWebhookPayload, createFetchSSETransport, createSSETransport, createWhatsAppTransport, mapWhatsAppToChatEvent };