wakz-sdk 1.0.0

package/README.md

@@ -0,0 +1,264 @@
+# @wakz/sdk
+
+Official WAKZ AI SDK — Embed intelligent chat assistants in any website or application with WebSocket + HTTP fallback, automatic reconnection, and HMAC-signed authentication.
+
+## Installation
+
+```bash
+npm install @wakz/sdk
+# or
+yarn add @wakz/sdk
+# or
+pnpm add @wakz/sdk
+# or
+bun add @wakz/sdk
+```
+
+## Quick Start
+
+```typescript
+import { WAKZClient } from '@wakz/sdk';
+
+// Initialize the client with your API key
+const client = new WAKZClient({
+  apiKey: 'wakz_live_xxxxx',
+});
+
+// Connect to the WAKZ API
+await client.connect();
+
+// Listen for messages
+client.on('message', (msg) => {
+  console.log(`[${msg.role}]: ${msg.content}`);
+});
+
+// Send a message and get the AI response
+const response = await client.sendMessage('Hello! How can you help me?');
+
+if (response.success) {
+  console.log('AI Response:', response.message?.content);
+} else {
+  console.error('Error:', response.error);
+}
+
+// Disconnect when done
+client.disconnect();
+```
+
+## React Integration
+
+```tsx
+import { useEffect, useRef, useState } from 'react';
+import { WAKZClient, type ChatMessage } from '@wakz/sdk';
+
+export function WAKZChat() {
+  const [messages, setMessages] = useState<ChatMessage[]>([]);
+  const [input, setInput] = useState('');
+  const clientRef = useRef<WAKZClient | null>(null);
+
+  useEffect(() => {
+    const client = new WAKZClient({
+      apiKey: 'wakz_live_xxxxx',
+    });
+
+    client.on('message', (msg) => {
+      setMessages((prev) => [...prev, msg]);
+    });
+
+    client.connect();
+    clientRef.current = client;
+
+    return () => {
+      client.destroy();
+    };
+  }, []);
+
+  const handleSend = async () => {
+    if (!input.trim() || !clientRef.current) return;
+
+    setMessages((prev) => [
+      ...prev,
+      {
+        id: Date.now().toString(),
+        role: 'user',
+        content: input,
+        timestamp: new Date().toISOString(),
+      },
+    ]);
+
+    await clientRef.current.sendMessage(input);
+    setInput('');
+  };
+
+  return (
+    <div>
+      {messages.map((msg) => (
+        <div key={msg.id}>{msg.content}</div>
+      ))}
+      <input
+        value={input}
+        onChange={(e) => setInput(e.target.value)}
+        onKeyDown={(e) => e.key === 'Enter' && handleSend()}
+      />
+      <button onClick={handleSend}>Send</button>
+    </div>
+  );
+}
+```
+
+## API Reference
+
+### `new WAKZClient(options)`
+
+Creates a new WAKZ SDK client instance.
+
+#### Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `apiKey` | `string` | **required** | Your WAKZ API key (starts with `wakz_live_`) |
+| `baseUrl` | `string` | `'https://api.wakz.dev'` | API base URL |
+| `websocketUrl` | `string` | derived from baseUrl | WebSocket server URL |
+| `autoReconnect` | `boolean` | `true` | Enable automatic reconnection |
+| `maxRetries` | `number` | `5` | Max reconnection attempts before HTTP fallback |
+| `initialRetryDelay` | `number` | `1000` | Initial retry delay in ms |
+| `maxRetryDelay` | `number` | `30000` | Maximum retry delay in ms |
+| `visitorId` | `string` | auto-generated | Custom visitor identifier |
+| `metadata` | `object` | `{}` | Visitor metadata (browser, OS, etc.) |
+| `timeout` | `number` | `30000` | Request timeout in ms |
+| `debug` | `boolean` | `false` | Enable debug logging |
+
+### Methods
+
+#### `client.connect(): Promise<void>`
+
+Connect to the WAKZ API. Attempts WebSocket first, falls back to HTTP.
+
+#### `client.sendMessage(content: string): Promise<SendMessageResponse>`
+
+Send a message and receive the AI response.
+
+#### `client.disconnect(): void`
+
+Disconnect from the API.
+
+#### `client.getSession(): Promise<SessionInfo>`
+
+Get the current session information.
+
+#### `client.getVisitorId(): string`
+
+Get the current visitor ID.
+
+#### `client.getStatus(): ConnectionStatus`
+
+Get the current connection status (`'disconnected' | 'connecting' | 'connected' | 'reconnecting' | 'failed'`).
+
+#### `client.getTransport(): TransportMode`
+
+Get the current transport mode (`'websocket' | 'http'`).
+
+#### `client.getWidgetConfig(): Promise<WidgetConfig | null>`
+
+Fetch widget configuration from the API.
+
+#### `client.healthCheck(): Promise<HealthCheckResult>`
+
+Perform a health check against the API.
+
+#### `client.updateMetadata(metadata: Record<string, string>): void`
+
+Update visitor metadata.
+
+#### `client.destroy(): void`
+
+Disconnect and clean up all resources.
+
+### Events
+
+| Event | Data | Description |
+|-------|------|-------------|
+| `connected` | `void` | Successfully connected to the API |
+| `disconnected` | `{ code: number, reason: string }` | Disconnected from the API |
+| `reconnecting` | `{ attempt: number, delay: number }` | Attempting to reconnect |
+| `reconnect_failed` | `{ reason: string }` | All reconnection attempts exhausted |
+| `message` | `ChatMessage` | Received a message from the AI |
+| `error` | `Error` | An error occurred |
+| `session_start` | `SessionInfo` | A new session started |
+| `session_end` | `{ sessionId: string }` | The session ended |
+| `transport_change` | `{ from: TransportMode, to: TransportMode }` | Transport mode changed |
+| `health_check` | `{ latency: number, transport: TransportMode }` | Health check completed |
+
+### Static Methods
+
+#### `WAKZClient.healthCheck(baseUrl?, timeout?): Promise<HealthCheckResult>`
+
+Perform a quick connectivity check without creating a client instance.
+
+```typescript
+const health = await WAKZClient.healthCheck();
+if (health.healthy) {
+  console.log(`WAKZ API is up (${health.latency}ms)`);
+}
+```
+
+## Transport Architecture
+
+```
+┌─────────────┐     WebSocket      ┌──────────────┐
+│             │ ─────────────────►  │              │
+│  WAKZ SDK   │                     │  WAKZ API    │
+│             │ ◄─────────────────  │              │
+│             │     Real-time       │              │
+│             │                     │              │
+│             │     HTTP/REST       │              │
+│             │ ─────────────────►  │              │
+│             │ ◄─────────────────  │              │
+└─────────────┘     Fallback        └──────────────┘
+```
+
+1. **Primary**: WebSocket for real-time, low-latency communication
+2. **Fallback**: HTTP/REST when WebSocket is unavailable or fails
+3. **Auto-switch**: Automatically falls back to HTTP after max retries
+4. **Reconnection**: Exponential backoff with jitter (1s → 2s → 4s → ... → 30s max)
+
+## Authentication
+
+All requests are authenticated using your API key with HMAC-SHA256 signing:
+
+- **`X-API-Key`**: Your raw API key
+- **`X-Timestamp`**: ISO 8601 timestamp
+- **`X-Signature`**: HMAC-SHA256 of `{timestamp}.{payload}` using your API key
+
+## TypeScript Support
+
+Full TypeScript support with comprehensive type definitions:
+
+```typescript
+import type {
+  ChatMessage,
+  SessionInfo,
+  WAKZClientOptions,
+  TransportMode,
+  ConnectionStatus,
+  HealthCheckResult,
+  WAKZEventType,
+  WAKZEventMap,
+} from '@wakz/sdk';
+```
+
+## Browser Support
+
+- Chrome 80+
+- Firefox 80+
+- Safari 14+
+- Edge 80+
+
+## Node.js Support
+
+- Node.js 16+
+- Works with `ws` package for WebSocket support
+
+## License
+
+MIT License — see [LICENSE](LICENSE) for details.

package/dist/client.d.ts

@@ -0,0 +1,124 @@
+import type { WAKZClientOptions, WAKZEventType, WAKZEventMap, WAKZEventCallback, SendMessageResponse, SessionInfo, WidgetConfig, HealthCheckResult, TransportMode, ConnectionStatus } from './types';
+import { WAKZEventEmitter } from './events';
+/**
+ * WAKZ SDK Client — The main entry point for integrating WAKZ AI.
+ *
+ * Features:
+ * - Dual transport: WebSocket (primary) with HTTP/REST fallback
+ * - Automatic reconnection with exponential backoff
+ * - API key authentication with HMAC-SHA256 request signing
+ * - Typed event emitter for real-time updates
+ * - Session management with visitor fingerprinting
+ * - Works in both browser and Node.js environments
+ *
+ * @example
+ * ```typescript
+ * const client = new WAKZClient({
+ *   apiKey: 'wakz_live_xxxxx',
+ * });
+ *
+ * await client.connect();
+ * client.on('message', (msg) => console.log(msg));
+ * const response = await client.sendMessage('Hello!');
+ * ```
+ */
+export declare class WAKZClient extends WAKZEventEmitter {
+    private options;
+    private wsTransport;
+    private httpTransport;
+    private sessionManager;
+    private logger;
+    private _status;
+    private _currentTransport;
+    /**
+     * Create a new WAKZ SDK client instance.
+     *
+     * @param options - Client configuration options
+     */
+    constructor(options: WAKZClientOptions);
+    /**
+     * Connect to the WAKZ API.
+     *
+     * Attempts WebSocket connection first. Falls back to HTTP if:
+     * - WebSocket is not available in the environment
+     * - WebSocket connection fails after max retries
+     *
+     * @returns Promise that resolves when connected
+     */
+    connect(): Promise<void>;
+    /**
+     * Send a chat message.
+     *
+     * Uses the current active transport (WebSocket or HTTP).
+     *
+     * @param content - The message text to send
+     * @returns Promise resolving to the assistant's reply
+     */
+    sendMessage(content: string): Promise<SendMessageResponse>;
+    /**
+     * Disconnect from the WAKZ API.
+     */
+    disconnect(): void;
+    /**
+     * Register an event listener.
+     */
+    on<K extends WAKZEventType>(event: K, callback: WAKZEventCallback<WAKZEventMap[K]>): this;
+    /**
+     * Register a one-time event listener.
+     */
+    once<K extends WAKZEventType>(event: K, callback: WAKZEventCallback<WAKZEventMap[K]>): this;
+    /**
+     * Remove an event listener.
+     */
+    off<K extends WAKZEventType>(event: K, callback: WAKZEventCallback<WAKZEventMap[K]>): this;
+    /**
+     * Get the current session information.
+     */
+    getSession(): Promise<SessionInfo>;
+    /**
+     * Get the current visitor ID.
+     */
+    getVisitorId(): string;
+    /**
+     * Get the current connection status.
+     */
+    getStatus(): ConnectionStatus;
+    /**
+     * Get the current transport mode.
+     */
+    getTransport(): TransportMode;
+    /**
+     * Fetch the widget configuration from the API.
+     */
+    getWidgetConfig(): Promise<WidgetConfig | null>;
+    /**
+     * Perform a health check against the WAKZ API.
+     */
+    healthCheck(): Promise<HealthCheckResult>;
+    /**
+     * Update visitor metadata.
+     */
+    updateMetadata(metadata: Record<string, string>): void;
+    /**
+     * Destroy the client — disconnect and clean up all resources.
+     */
+    destroy(): void;
+    /**
+     * ─── Static Methods ──────────────────────────────────────
+     */
+    /**
+     * Perform a quick health check against a WAKZ API endpoint.
+     * Useful for checking connectivity before creating a client instance.
+     *
+     * @param baseUrl - The API base URL to check
+     * @param timeout - Request timeout in ms (default: 10000)
+     * @returns Health check result
+     */
+    static healthCheck(baseUrl?: string, timeout?: number): Promise<HealthCheckResult>;
+    /**
+     * Connect via WebSocket transport.
+     */
+    private connectWebSocket;
+    private warn;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EACV,iBAAiB,EACjB,aAAa,EACb,YAAY,EACZ,iBAAiB,EACjB,mBAAmB,EAEnB,WAAW,EACX,YAAY,EACZ,iBAAiB,EACjB,aAAa,EACb,gBAAgB,EACjB,MAAM,SAAS,CAAC;AAEjB,OAAO,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAC;AAM5C;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,qBAAa,UAAW,SAAQ,gBAAgB;IAC9C,OAAO,CAAC,OAAO,CACuD;IACtE,OAAO,CAAC,WAAW,CAAmC;IACtD,OAAO,CAAC,aAAa,CAAgB;IACrC,OAAO,CAAC,cAAc,CAAiB;IACvC,OAAO,CAAC,MAAM,CAAS;IAEvB,OAAO,CAAC,OAAO,CAAoC;IACnD,OAAO,CAAC,iBAAiB,CAAyB;IAElD;;;;OAIG;gBACS,OAAO,EAAE,iBAAiB;IA0CtC;;;;;;;;OAQG;IACG,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IA2B9B;;;;;;;OAOG;IACG,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,mBAAmB,CAAC;IA+ChE;;OAEG;IACH,UAAU,IAAI,IAAI;IAOlB;;OAEG;IACM,EAAE,CAAC,CAAC,SAAS,aAAa,EACjC,KAAK,EAAE,CAAC,EACR,QAAQ,EAAE,iBAAiB,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,GAC3C,IAAI;IAKP;;OAEG;IACM,IAAI,CAAC,CAAC,SAAS,aAAa,EACnC,KAAK,EAAE,CAAC,EACR,QAAQ,EAAE,iBAAiB,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,GAC3C,IAAI;IAKP;;OAEG;IACM,GAAG,CAAC,CAAC,SAAS,aAAa,EAClC,KAAK,EAAE,CAAC,EACR,QAAQ,EAAE,iBAAiB,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,GAC3C,IAAI;IAKP;;OAEG;IACG,UAAU,IAAI,OAAO,CAAC,WAAW,CAAC;IAIxC;;OAEG;IACH,YAAY,IAAI,MAAM;IAItB;;OAEG;IACH,SAAS,IAAI,gBAAgB;IAI7B;;OAEG;IACH,YAAY,IAAI,aAAa;IAI7B;;OAEG;IACG,eAAe,IAAI,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC;IAIrD;;OAEG;IACG,WAAW,IAAI,OAAO,CAAC,iBAAiB,CAAC;IAQ/C;;OAEG;IACH,cAAc,CAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI;IAItD;;OAEG;IACH,OAAO,IAAI,IAAI;IAQf;;OAEG;IAEH;;;;;;;OAOG;WACU,WAAW,CACtB,OAAO,GAAE,MAA+B,EACxC,OAAO,GAAE,MAAc,GACtB,OAAO,CAAC,iBAAiB,CAAC;IA6B7B;;OAEG;YACW,gBAAgB;IA2D9B,OAAO,CAAC,IAAI;CAGb"}