@cognigy/click-to-call-sdk 0.0.7

package/README.md

@@ -0,0 +1,121 @@
+# Click To Call SDK
+
+A standalone, framework-agnostic SDK for SIP-based voice calling with WebRTC. Built on JsSIP.
+
+## Features
+
+- 🚀 **Framework Agnostic** — works with React, Angular, Vue, or vanilla JS.
+- 🔒 **Type Safe** — full TypeScript support.
+- 📞 **SIP/WebRTC** — built on JsSIP for reliable communication.
+- 🎛️ **Full Control** — start, end, mute, unmute, send info messages.
+- 🔄 **Event Driven** — 17 events for real-time state updates.
+- 🎵 **Auto Audio** — remote audio plays automatically; raw stream available via `captureAudio` event.
+- 💬 **Transcription** — real-time transcription events, auto-separated from info messages.
+
+## Installation
+
+```bash
+npm install @cognigy/click-to-call-sdk
+```
+
+## Quick Start
+
+```typescript
+import { createWebRTCClient, checkWebRTCSupport } from '@cognigy/click-to-call-sdk';
+
+// 1. Check browser support
+const support = checkWebRTCSupport();
+if (!support.supported) throw new Error('Missing: ' + support.missing);
+
+// 2. Create client
+const client = await createWebRTCClient({
+  endpointUrl: 'https://your-cognigy-environment.com/token',
+  userId: 'user-123',
+});
+
+// 3. Listen to events
+client.on('answered', (session) => console.log('Call answered:', session.id));
+client.on('ended', (session, endInfo) => console.log('Call ended:', endInfo.cause));
+client.on('error', (error) => console.error('Error:', error.message));
+
+// 4. Connect and call
+await client.connectAndCall();
+
+// 5. Cleanup on page unload
+window.addEventListener('beforeunload', () => {
+  void client.destroy().catch(() => {
+    // Ignore errors during page unload
+  });
+});
+```
+
+> **Note:** The call must be initiated from a user gesture (e.g. button click) for browser autoplay policies to allow audio.
+
+## Configuration
+
+```typescript
+interface WebRTCClientConfig {
+  endpointUrl: string;        // URL to fetch SIP configuration
+  userId?: string;            // Optional user identifier
+  pcConfig?: RTCConfiguration; // WebRTC peer connection config
+  captureAudio?: boolean;     // Enable captureAudio event to receive raw MediaStream
+}
+```
+
+## API
+
+| Method                  | Description                                  |
+|-------------------------|----------------------------------------------|
+| `connect()`             | Connect to SIP server and register           |
+| `disconnect()`          | Disconnect from SIP server                   |
+| `connectAndCall()`      | Connect + start call in one step             |
+| `startCall()`           | Start a call (must be connected first)       |
+| `endCall()`             | End the current call                         |
+| `mute()` / `unmute()`   | Toggle microphone                            |
+| `sendInfo(text, data?)` | Send info message during a call              |
+| `isConnected()`         | Check connection state                       |
+| `getCurrentSession()`   | Get active `CallSession` or `null`           |
+| `on(event, callback)`   | Add event listener (returns `this`)          |
+| `off(event, callback)`  | Remove event listener (returns `this`)       |
+| `destroy()`             | Disconnect, end calls, release all resources |
+
+## Events
+
+| Event           | Callback                                                                |
+|-----------------|-------------------------------------------------------------------------|
+| `connecting`    | `()`                                                                    |
+| `connected`     | `()`                                                                    |
+| `disconnected`  | `()`                                                                    |
+| `registered`    | `()`                                                                    |
+| `unregistered`  | `()`                                                                    |
+| `ringing`       | `(session: CallSession)`                                                |
+| `answered`      | `(session: CallSession)`                                                |
+| `ended`         | `(session: CallSession, endInfo: CallEndInfo)`                          |
+| `failed`        | `(session: CallSession, endInfo: CallEndInfo)`                          |
+| `muted`         | `(session: CallSession)`                                                |
+| `unmuted`       | `(session: CallSession)`                                                |
+| `captureAudio`  | Remote audio stream available (requires opt-in) `(stream: MediaStream)` |
+| `audioEnded`    | `()`                                                                    |
+| `infoSent`      | `(text: string, data: Record<string, any>)`                             |
+| `infoReceived`  | `(data: { originator: string; info: { body: string } })`                |
+| `transcription` | `(transcription: { originator: string; messages: { text: string }[] })` |
+| `error`         | `(error: Error)`                                                        |
+
+## Browser Compatibility
+
+Chrome 93+ · Firefox 92+ · Safari 15.4+ · Edge 93+
+
+## Documentation
+
+For the full guide, API reference, event reference, and troubleshooting:
+
+- [Getting Started](https://docs.cognigy.com/click-to-call/sdkgetting-started.mdx)
+- [API Reference](https://docs.cognigy.com/click-to-call/sdkapi-reference/overview.mdx)
+- [Event Reference](https://docs.cognigy.com/click-to-call/sdkevent-reference/overview.mdx)
+- [Custom Audio](https://docs.cognigy.com/click-to-call/sdkcustom-audio.mdx)
+- [Security](https://docs.cognigy.com/click-to-call/sdksecurity.mdx)
+- [Troubleshooting](https://docs.cognigy.com/click-to-call/sdktroubleshooting.mdx)
+
+## License
+
+MIT

package/dist/AudioManager.d.ts

@@ -0,0 +1,22 @@
+import { SDKEventEmitter } from './utils/events.js';
+export declare class AudioManager extends SDKEventEmitter {
+    private state;
+    constructor();
+    private initializeDefaultAudio;
+    handleRemoteStream(stream: MediaStream): void;
+    private playDefaultAudio;
+    stopAudio(): void;
+    setVolume(volume: number): void;
+    getVolume(): number;
+    setMuted(muted: boolean): void;
+    isMuted(): boolean;
+    getCurrentStream(): MediaStream | null;
+    setCaptureAudio(enabled: boolean): void;
+    getState(): {
+        hasRemoteAudio: boolean;
+        hasCurrentStream: boolean;
+        volume: number;
+        muted: boolean;
+    };
+    destroy(): void;
+}

package/dist/ConfigManager.d.ts

@@ -0,0 +1,32 @@
+import { EndpointConfig } from './types/index.js';
+export declare class ConfigManager {
+    private config;
+    private readonly endpointUrl;
+    private userId;
+    private readonly userProvidedId;
+    constructor(endpointUrl: string, userId?: string);
+    fetchConfig(): Promise<EndpointConfig>;
+    getConfig(): EndpointConfig | null;
+    getSipCredentials(): {
+        fullUsername: string;
+        password: string;
+        username: string;
+        wsUri: string;
+        applicationSid: string;
+        realm: string;
+    };
+    getApplicationSid(): string;
+    isActive(): boolean;
+    getPrivacySettings(): {
+        enabled: boolean;
+        text: string;
+        cancelButtonText: string;
+        submitButtonText: string;
+        urlText: string;
+        url: string;
+    };
+    clearConfig(): void;
+    isConfigValid(): boolean;
+    getPeerConnectionConfig(): RTCConfiguration | undefined;
+}
+export declare function createConfigManager(endpointUrl: string): ConfigManager;

package/dist/SessionManager.d.ts

@@ -0,0 +1,29 @@
+import { SDKEventEmitter } from './utils/events.js';
+import { ExtendedRTCSession } from './types/internal.js';
+import { CallSession } from './types/index.js';
+export declare class SessionManager extends SDKEventEmitter {
+    private sessions;
+    private activeSessionId;
+    private audioManager?;
+    constructor(_pcConfig?: RTCConfiguration);
+    setAudioManager(audioManager: any): void;
+    createSession(rtcSession: ExtendedRTCSession): string;
+    private setupSessionEventHandlers;
+    private handleNewInfo;
+    private setupPeerConnectionHandlers;
+    private handleSessionEnd;
+    private updateSession;
+    private getPublicSession;
+    private calculateDuration;
+    setActiveSession(sessionId: string): void;
+    getActiveSession(): CallSession | null;
+    getSession(sessionId: string): CallSession | null;
+    getAllSessions(): CallSession[];
+    mute(): void;
+    unmute(): void;
+    sendInfo(text: string, data?: Record<string, any>): void;
+    terminate(sipCode?: number, sipReason?: string): void;
+    private getActiveSessionState;
+    private removeSession;
+    destroy(): void;
+}

package/dist/SipManager.d.ts

@@ -0,0 +1,20 @@
+import { UA as IUA } from 'jssip';
+import { SDKEventEmitter } from './utils/events.js';
+import { InternalClientConfig, InternalClientSettings, SipManagerState } from './types/internal.js';
+export declare class SipManager extends SDKEventEmitter {
+    private ua;
+    private pcConfig?;
+    private state;
+    initialize(client: InternalClientConfig, settings: InternalClientSettings): void;
+    private setupEventHandlers;
+    private handleNewSession;
+    start(): void;
+    stop(): void;
+    call(number: string, originalNumber?: string): void;
+    getState(): SipManagerState;
+    isConnected(): boolean;
+    isRegistered(): boolean;
+    isConnecting(): boolean;
+    getUserAgent(): IUA | null;
+    destroy(): void;
+}

package/dist/WebRTCClient.d.ts

@@ -0,0 +1,31 @@
+import { SDKEventEmitter } from './utils/events.js';
+import { WebRTCClient as IWebRTCClient, WebRTCClientConfig, CallSession, EventName, EventCallback } from './types/index.js';
+export declare class WebRTCClient extends SDKEventEmitter implements IWebRTCClient {
+    private configManager;
+    private sipManager;
+    private sessionManager;
+    private audioManager;
+    private isInitialized;
+    private isDestroyed;
+    constructor(config: WebRTCClientConfig);
+    private setupEventHandlers;
+    connect(): Promise<void>;
+    disconnect(): Promise<void>;
+    startCall(): Promise<void>;
+    endCall(): Promise<void>;
+    mute(): Promise<void>;
+    unmute(): Promise<void>;
+    connectAndCall(): Promise<void>;
+    sendInfo(text: string, data?: Record<string, any>): Promise<void>;
+    on<T extends EventName>(event: T, callback: EventCallback<T>): this;
+    off<T extends EventName>(event: T, callback: EventCallback<T>): this;
+    isConnected(): boolean;
+    getCurrentSession(): CallSession | null;
+    destroy(): Promise<void>;
+    getStatus(): {
+        connected: boolean;
+        registered: boolean;
+        activeSession: CallSession | null;
+        audioState: any;
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,13 @@
+import { WebRTCClient } from './WebRTCClient.js';
+import { isWebRTCSupported } from './utils/helpers.js';
+import { WebRTCClientConfig } from './types/index.js';
+export type { WebRTCClient as IWebRTCClient, WebRTCClientConfig, CreateWebRTCClientOptions, CreateWebRTCClient, EndpointConfig, SipConnectivityInfo, CallSession, CallEndInfo, SessionStatus, EventName, EventCallback, WebRTCClientEvents, } from './types/index.js';
+export { WebRTCClient };
+export { isWebRTCSupported };
+export declare function createWebRTCClient(config: WebRTCClientConfig): Promise<WebRTCClient>;
+export declare const VERSION = "1.0.0";
+export declare const SDK_NAME = "@cognigy/webrtc-sdk";
+export declare function checkWebRTCSupport(): {
+    supported: boolean;
+    missing: string[];
+};

package/dist/types/index.d.ts

@@ -0,0 +1,102 @@
+export interface EndpointConfig {
+    organisationId: string;
+    projectId: string;
+    endpointSettings: {
+        snapshotId: string | null;
+        endpointUrlToken: string;
+        endpointName: string;
+        channel: string;
+        localeReferenceId: string;
+        collectAnalytics: boolean;
+        active: boolean;
+        version?: string;
+        sipConnectivityInfo: SipConnectivityInfo;
+        webrtcWidgetConfig: {
+            active: boolean;
+            label?: string;
+        };
+    };
+    settings?: {
+        privacyNotice?: {
+            enabled: boolean;
+            text: string;
+            cancelButtonText: string;
+            submitButtonText: string;
+            urlText: string;
+            url: string;
+        };
+    };
+}
+export interface SipConnectivityInfo {
+    userId?: string;
+    username: string;
+    applicationSid: string;
+    password: string;
+    wsUri: string;
+    realm: string;
+    clientSid?: string;
+}
+export interface WebRTCClientConfig {
+    endpointUrl: string;
+    userId?: string;
+    pcConfig?: RTCConfiguration;
+    captureAudio?: boolean;
+}
+export interface CallSession {
+    id: string;
+    status: SessionStatus;
+    direction: 'incoming' | 'outgoing';
+    startTime: Date;
+    answerTime?: Date;
+    duration: number;
+    muted: boolean;
+    localHold: boolean;
+    remoteHold: boolean;
+}
+export type SessionStatus = 'init' | 'ringing' | 'answered' | 'failed' | 'ended';
+export interface CallEndInfo {
+    originator: 'local' | 'remote' | null;
+    cause: string | null;
+    description?: string | null;
+}
+export interface WebRTCClientEvents {
+    'connecting': () => void;
+    'connected': () => void;
+    'disconnected': () => void;
+    'registered': () => void;
+    'unregistered': () => void;
+    'ringing': (session: CallSession) => void;
+    'answered': (session: CallSession) => void;
+    'ended': (session: CallSession, endInfo: CallEndInfo) => void;
+    'failed': (session: CallSession, endInfo: CallEndInfo) => void;
+    'muted': (session: CallSession) => void;
+    'unmuted': (session: CallSession) => void;
+    'audioEnded': () => void;
+    'infoSent': (text: string, data: Record<string, any>) => void;
+    'infoReceived': (data: {
+        originator: string;
+        info: any;
+    }) => void;
+    'error': (error: Error) => void;
+    'captureAudio': (stream: MediaStream) => void;
+}
+export type EventName = keyof WebRTCClientEvents;
+export type EventCallback<T extends EventName> = WebRTCClientEvents[T];
+export interface WebRTCClient {
+    startCall(): Promise<void>;
+    endCall(): Promise<void>;
+    mute(): Promise<void>;
+    unmute(): Promise<void>;
+    sendInfo(text: string, data?: Record<string, any>): Promise<void>;
+    on<T extends EventName>(event: T, callback: EventCallback<T>): this;
+    off<T extends EventName>(event: T, callback: EventCallback<T>): this;
+    isConnected(): boolean;
+    getCurrentSession(): CallSession | null;
+    connect(): Promise<void>;
+    disconnect(): Promise<void>;
+    destroy(): Promise<void>;
+    connectAndCall(): Promise<void>;
+}
+export interface CreateWebRTCClientOptions extends WebRTCClientConfig {
+}
+export type CreateWebRTCClient = (config: CreateWebRTCClientOptions) => Promise<WebRTCClient>;

package/dist/types/internal.d.ts

@@ -0,0 +1,55 @@
+import { RTCSession } from 'jssip/lib/RTCSession';
+import { UA } from 'jssip';
+import { CallEndInfo, SessionStatus } from './index.js';
+export type ExtendedRTCSession = Omit<RTCSession, 'sendInfo'> & {
+    _connection: RTCSession['connection'];
+    sendInfo: (text: string, data: Record<string, any>) => void;
+    data: {
+        originalNumber?: string;
+        replaces?: boolean;
+        [key: string]: any;
+    };
+};
+export interface SessionOptions {
+    pcConfig?: RTCConfiguration;
+    onSession: (rtcSession: ExtendedRTCSession) => void;
+}
+export interface InternalClientConfig {
+    fullUsername: string;
+    password: string;
+    username: string;
+}
+export interface InternalClientSettings {
+    wsUri: string;
+    pcConfig?: RTCConfiguration;
+}
+export interface SessionState {
+    id: string;
+    startTime: Date;
+    status: SessionStatus;
+    active: boolean;
+    endInfo: CallEndInfo;
+    muted: boolean;
+    localHold: boolean;
+    remoteHold: boolean;
+    doingAttendedTransfer: boolean;
+    autoMerge: boolean;
+    rtcSession: ExtendedRTCSession;
+}
+export interface AudioState {
+    remoteAudio: HTMLAudioElement | null;
+    currentStream: MediaStream | null;
+    captureAudio: boolean;
+}
+export interface SipManagerState {
+    ua: UA | null;
+    connected: boolean;
+    registered: boolean;
+    connecting: boolean;
+}
+export interface EventEmitter {
+    on(event: string, listener: (...args: any[]) => void): this;
+    off(event: string, listener: (...args: any[]) => void): this;
+    emit(event: string, ...args: any[]): void;
+    removeAllListeners(event?: string): void;
+}

package/dist/utils/events.d.ts

@@ -0,0 +1,35 @@
+import { EventEmitter as NodeEventEmitter } from 'events';
+import { EventEmitter } from '../types/internal.js';
+export declare class SDKEventEmitter extends NodeEventEmitter implements EventEmitter {
+    constructor();
+    on(event: string, listener: (...args: any[]) => void): this;
+    off(event: string, listener: (...args: any[]) => void): this;
+    emit(event: string, ...args: any[]): boolean;
+    removeAllListeners(event?: string): this;
+    once(event: string, listener: (...args: any[]) => void): this;
+    listenerCount(event: string): number;
+    listeners(event: string): ((...args: any[]) => void)[];
+}
+export declare const COGNIGY_WEBRTC_EVENTS: {
+    readonly CONNECTING: "connecting";
+    readonly CONNECTED: "connected";
+    readonly DISCONNECTED: "disconnected";
+    readonly REGISTERED: "registered";
+    readonly UNREGISTERED: "unregistered";
+    readonly RINGING: "ringing";
+    readonly ANSWERED: "answered";
+    readonly ENDED: "ended";
+    readonly FAILED: "failed";
+    readonly MUTED: "muted";
+    readonly UNMUTED: "unmuted";
+    readonly AUDIO_ENDED: "audioEnded";
+    readonly INFO_SENT: "infoSent";
+    readonly ERROR: "error";
+    readonly SESSION_CREATED: "sessionCreated";
+    readonly SESSION_UPDATED: "sessionUpdated";
+    readonly SESSION_DESTROYED: "sessionDestroyed";
+    readonly INFO_RECEIVED: "infoReceived";
+    readonly TRANSCRIPTION: "transcription";
+    readonly CAPTURE_AUDIO: "captureAudio";
+};
+export type SDKEventName = typeof COGNIGY_WEBRTC_EVENTS[keyof typeof COGNIGY_WEBRTC_EVENTS];

package/dist/utils/helpers.d.ts

@@ -0,0 +1,12 @@
+export declare function randomId(prefix?: string): string;
+export declare function isValidSipUri(uri: string): boolean;
+export declare function isValidWsUri(uri: string): boolean;
+export declare function delay(ms: number): Promise<void>;
+export declare function safeJsonParse<T>(jsonString: string, fallback: T): T;
+export declare function isBrowser(): boolean;
+export declare function isWebRTCSupported(): boolean;
+export declare function validateEndpointConfig(config: any): boolean;
+export declare function getNestedProperty(obj: any, path: string): any;
+export declare function debounce<T extends (...args: any[]) => any>(func: T, wait: number): (...args: Parameters<T>) => void;
+export declare function withTimeout<T>(promise: Promise<T>, timeoutMs: number): Promise<T>;
+export declare function formatDuration(seconds: number): string;