@vattara/sdk 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,51 @@
+/**
+ * @vattara/sdk — Official TypeScript SDK for Vattara Observe
+ * Realtime PCM audio streaming, interruption tracking, token cost analytics & CLEAR 2.0 metrics.
+ */
+export interface VattaraOptions {
+    apiKey: string;
+    serverUrl?: string;
+    sampleRate?: 16000 | 24000;
+    tags?: Record<string, string>;
+    debug?: boolean;
+}
+export interface InterruptionEvent {
+    cutoffLatencyMs: number;
+    interruptedAt?: number;
+}
+export interface TokenUsageEvent {
+    inputTokens: number;
+    outputTokens: number;
+    model?: string;
+}
+export declare class VattaraObserveClient {
+    private apiKey;
+    private serverUrl;
+    private sampleRate;
+    private tags;
+    private debug;
+    private ws;
+    private token;
+    private buffer;
+    private isConnecting;
+    constructor(options: VattaraOptions);
+    /** Initialize session by fetching JWT token and establishing WebSocket connection. */
+    init(): Promise<void>;
+    /** Track PCM audio base64 frame (16kHz / 24kHz). */
+    sendAudioFrame(base64Data: string, sampleRate?: number): void;
+    /** Track customer barge-in / interruption event. */
+    trackInterruption(event: InterruptionEvent): void;
+    /** Track input/output token usage. */
+    trackTokens(event: TokenUsageEvent): void;
+    /** Set dynamic custom properties/tags. */
+    setTags(tags: Record<string, string>): void;
+    private sendEvent;
+    private flushBuffer;
+}
+export declare const Vattara: {
+    init(options: VattaraOptions): VattaraObserveClient;
+    sendAudioFrame(base64Data: string, sampleRate?: number): void;
+    trackInterruption(event: InterruptionEvent): void;
+    trackTokens(event: TokenUsageEvent): void;
+    setTags(tags: Record<string, string>): void;
+};

package/dist/index.js

@@ -0,0 +1,147 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  Vattara: () => Vattara,
+  VattaraObserveClient: () => VattaraObserveClient
+});
+module.exports = __toCommonJS(index_exports);
+var VattaraObserveClient = class {
+  constructor(options) {
+    this.ws = null;
+    this.token = null;
+    this.buffer = [];
+    this.isConnecting = false;
+    this.apiKey = options.apiKey;
+    this.serverUrl = options.serverUrl || "wss://vattara-observe-production.up.railway.app/api/v1/ws/telemetry";
+    this.sampleRate = options.sampleRate || 24e3;
+    this.tags = options.tags || {};
+    this.debug = options.debug || false;
+  }
+  /** Initialize session by fetching JWT token and establishing WebSocket connection. */
+  async init() {
+    if (this.isConnecting || this.ws) return;
+    this.isConnecting = true;
+    try {
+      const httpUrl = this.serverUrl.replace(/^ws/, "http").replace(/\/ws\/telemetry$/, "/auth/token");
+      const res = await fetch(httpUrl, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ api_key: this.apiKey })
+      });
+      if (!res.ok) {
+        throw new Error(`Authentication failed with status ${res.status}`);
+      }
+      const data = await res.json();
+      this.token = data.token;
+      const wsUrl = `${this.serverUrl}?token=${encodeURIComponent(this.token)}`;
+      this.ws = new WebSocket(wsUrl);
+      this.ws.onopen = () => {
+        if (this.debug) console.log("[Vattara] Telemetry WebSocket connected.");
+        this.flushBuffer();
+      };
+      this.ws.onclose = () => {
+        if (this.debug) console.log("[Vattara] Telemetry WebSocket disconnected.");
+        this.ws = null;
+      };
+      this.ws.onerror = (err) => {
+        if (this.debug) console.error("[Vattara] WebSocket error:", err);
+      };
+    } catch (err) {
+      if (this.debug) console.error("[Vattara] Initialization error:", err);
+    } finally {
+      this.isConnecting = false;
+    }
+  }
+  /** Track PCM audio base64 frame (16kHz / 24kHz). */
+  sendAudioFrame(base64Data, sampleRate) {
+    this.sendEvent({
+      type: "audio_frame",
+      sampleRate: sampleRate || this.sampleRate,
+      data: base64Data,
+      timestamp: Date.now()
+    });
+  }
+  /** Track customer barge-in / interruption event. */
+  trackInterruption(event) {
+    this.sendEvent({
+      type: "interruption",
+      cutoffLatencyMs: event.cutoffLatencyMs,
+      interruptedAt: event.interruptedAt || Date.now()
+    });
+  }
+  /** Track input/output token usage. */
+  trackTokens(event) {
+    this.sendEvent({
+      type: "token_usage",
+      inputTokens: event.inputTokens,
+      outputTokens: event.outputTokens,
+      model: event.model || "gpt-4o-realtime",
+      timestamp: Date.now()
+    });
+  }
+  /** Set dynamic custom properties/tags. */
+  setTags(tags) {
+    this.tags = { ...this.tags, ...tags };
+  }
+  sendEvent(payload) {
+    const fullPayload = { ...payload, tags: this.tags };
+    if (this.ws && this.ws.readyState === WebSocket.OPEN) {
+      this.ws.send(JSON.stringify(fullPayload));
+    } else {
+      this.buffer.push(fullPayload);
+      if (!this.isConnecting && !this.ws) {
+        this.init();
+      }
+    }
+  }
+  flushBuffer() {
+    while (this.buffer.length > 0 && this.ws && this.ws.readyState === WebSocket.OPEN) {
+      const payload = this.buffer.shift();
+      this.ws.send(JSON.stringify(payload));
+    }
+  }
+};
+var _globalClient = null;
+var Vattara = {
+  init(options) {
+    _globalClient = new VattaraObserveClient(options);
+    _globalClient.init();
+    return _globalClient;
+  },
+  sendAudioFrame(base64Data, sampleRate) {
+    _globalClient?.sendAudioFrame(base64Data, sampleRate);
+  },
+  trackInterruption(event) {
+    _globalClient?.trackInterruption(event);
+  },
+  trackTokens(event) {
+    _globalClient?.trackTokens(event);
+  },
+  setTags(tags) {
+    _globalClient?.setTags(tags);
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  Vattara,
+  VattaraObserveClient
+});

package/dist/index.mjs

@@ -0,0 +1,121 @@
+// src/index.ts
+var VattaraObserveClient = class {
+  constructor(options) {
+    this.ws = null;
+    this.token = null;
+    this.buffer = [];
+    this.isConnecting = false;
+    this.apiKey = options.apiKey;
+    this.serverUrl = options.serverUrl || "wss://vattara-observe-production.up.railway.app/api/v1/ws/telemetry";
+    this.sampleRate = options.sampleRate || 24e3;
+    this.tags = options.tags || {};
+    this.debug = options.debug || false;
+  }
+  /** Initialize session by fetching JWT token and establishing WebSocket connection. */
+  async init() {
+    if (this.isConnecting || this.ws) return;
+    this.isConnecting = true;
+    try {
+      const httpUrl = this.serverUrl.replace(/^ws/, "http").replace(/\/ws\/telemetry$/, "/auth/token");
+      const res = await fetch(httpUrl, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ api_key: this.apiKey })
+      });
+      if (!res.ok) {
+        throw new Error(`Authentication failed with status ${res.status}`);
+      }
+      const data = await res.json();
+      this.token = data.token;
+      const wsUrl = `${this.serverUrl}?token=${encodeURIComponent(this.token)}`;
+      this.ws = new WebSocket(wsUrl);
+      this.ws.onopen = () => {
+        if (this.debug) console.log("[Vattara] Telemetry WebSocket connected.");
+        this.flushBuffer();
+      };
+      this.ws.onclose = () => {
+        if (this.debug) console.log("[Vattara] Telemetry WebSocket disconnected.");
+        this.ws = null;
+      };
+      this.ws.onerror = (err) => {
+        if (this.debug) console.error("[Vattara] WebSocket error:", err);
+      };
+    } catch (err) {
+      if (this.debug) console.error("[Vattara] Initialization error:", err);
+    } finally {
+      this.isConnecting = false;
+    }
+  }
+  /** Track PCM audio base64 frame (16kHz / 24kHz). */
+  sendAudioFrame(base64Data, sampleRate) {
+    this.sendEvent({
+      type: "audio_frame",
+      sampleRate: sampleRate || this.sampleRate,
+      data: base64Data,
+      timestamp: Date.now()
+    });
+  }
+  /** Track customer barge-in / interruption event. */
+  trackInterruption(event) {
+    this.sendEvent({
+      type: "interruption",
+      cutoffLatencyMs: event.cutoffLatencyMs,
+      interruptedAt: event.interruptedAt || Date.now()
+    });
+  }
+  /** Track input/output token usage. */
+  trackTokens(event) {
+    this.sendEvent({
+      type: "token_usage",
+      inputTokens: event.inputTokens,
+      outputTokens: event.outputTokens,
+      model: event.model || "gpt-4o-realtime",
+      timestamp: Date.now()
+    });
+  }
+  /** Set dynamic custom properties/tags. */
+  setTags(tags) {
+    this.tags = { ...this.tags, ...tags };
+  }
+  sendEvent(payload) {
+    const fullPayload = { ...payload, tags: this.tags };
+    if (this.ws && this.ws.readyState === WebSocket.OPEN) {
+      this.ws.send(JSON.stringify(fullPayload));
+    } else {
+      this.buffer.push(fullPayload);
+      if (!this.isConnecting && !this.ws) {
+        this.init();
+      }
+    }
+  }
+  flushBuffer() {
+    while (this.buffer.length > 0 && this.ws && this.ws.readyState === WebSocket.OPEN) {
+      const payload = this.buffer.shift();
+      this.ws.send(JSON.stringify(payload));
+    }
+  }
+};
+var _globalClient = null;
+var Vattara = {
+  init(options) {
+    _globalClient = new VattaraObserveClient(options);
+    _globalClient.init();
+    return _globalClient;
+  },
+  sendAudioFrame(base64Data, sampleRate) {
+    _globalClient?.sendAudioFrame(base64Data, sampleRate);
+  },
+  trackInterruption(event) {
+    _globalClient?.trackInterruption(event);
+  },
+  trackTokens(event) {
+    _globalClient?.trackTokens(event);
+  },
+  setTags(tags) {
+    _globalClient?.setTags(tags);
+  }
+};
+export {
+  Vattara,
+  VattaraObserveClient
+};

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@vattara/sdk",
+  "version": "1.0.0",
+  "description": "Official TypeScript SDK for Vattara Observe — Realtime AI Voice Agent Observability & CLEAR 2.0 Evaluation",
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs,esm && tsc --emitDeclarationOnly"
+  },
+  "keywords": [
+    "vattara",
+    "voice-ai",
+    "observability",
+    "clear-framework",
+    "telemetry",
+    "retell",
+    "vapi"
+  ],
+  "author": "Vattara AI",
+  "license": "MIT",
+  "devDependencies": {
+    "tsup": "^8.3.5",
+    "typescript": "^5.7.2"
+  }
+}

package/src/index.ts

@@ -0,0 +1,170 @@
+/**
+ * @vattara/sdk — Official TypeScript SDK for Vattara Observe
+ * Realtime PCM audio streaming, interruption tracking, token cost analytics & CLEAR 2.0 metrics.
+ */
+
+export interface VattaraOptions {
+  apiKey: string;
+  serverUrl?: string;
+  sampleRate?: 16000 | 24000;
+  tags?: Record<string, string>;
+  debug?: boolean;
+}
+
+export interface InterruptionEvent {
+  cutoffLatencyMs: number;
+  interruptedAt?: number;
+}
+
+export interface TokenUsageEvent {
+  inputTokens: number;
+  outputTokens: number;
+  model?: string;
+}
+
+export class VattaraObserveClient {
+  private apiKey: string;
+  private serverUrl: string;
+  private sampleRate: number;
+  private tags: Record<string, string>;
+  private debug: boolean;
+  private ws: WebSocket | null = null;
+  private token: string | null = null;
+  private buffer: any[] = [];
+  private isConnecting: boolean = false;
+
+  constructor(options: VattaraOptions) {
+    this.apiKey = options.apiKey;
+    this.serverUrl = options.serverUrl || 'wss://vattara-observe-production.up.railway.app/api/v1/ws/telemetry';
+    this.sampleRate = options.sampleRate || 24000;
+    this.tags = options.tags || {};
+    this.debug = options.debug || false;
+  }
+
+  /** Initialize session by fetching JWT token and establishing WebSocket connection. */
+  async init(): Promise<void> {
+    if (this.isConnecting || this.ws) return;
+    this.isConnecting = true;
+
+    try {
+      // Exchange API Key for short-lived JWT token
+      const httpUrl = this.serverUrl.replace(/^ws/, 'http').replace(/\/ws\/telemetry$/, '/auth/token');
+      const res = await fetch(httpUrl, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ api_key: this.apiKey }),
+      });
+
+      if (!res.ok) {
+        throw new Error(`Authentication failed with status ${res.status}`);
+      }
+
+      const data = await res.json();
+      this.token = data.token;
+
+      // Establish WebSocket Connection
+      const wsUrl = `${this.serverUrl}?token=${encodeURIComponent(this.token!)}`;
+      this.ws = new WebSocket(wsUrl);
+
+      this.ws.onopen = () => {
+        if (this.debug) console.log('[Vattara] Telemetry WebSocket connected.');
+        this.flushBuffer();
+      };
+
+      this.ws.onclose = () => {
+        if (this.debug) console.log('[Vattara] Telemetry WebSocket disconnected.');
+        this.ws = null;
+      };
+
+      this.ws.onerror = (err) => {
+        if (this.debug) console.error('[Vattara] WebSocket error:', err);
+      };
+
+    } catch (err) {
+      if (this.debug) console.error('[Vattara] Initialization error:', err);
+    } finally {
+      this.isConnecting = false;
+    }
+  }
+
+  /** Track PCM audio base64 frame (16kHz / 24kHz). */
+  sendAudioFrame(base64Data: string, sampleRate?: number): void {
+    this.sendEvent({
+      type: 'audio_frame',
+      sampleRate: sampleRate || this.sampleRate,
+      data: base64Data,
+      timestamp: Date.now(),
+    });
+  }
+
+  /** Track customer barge-in / interruption event. */
+  trackInterruption(event: InterruptionEvent): void {
+    this.sendEvent({
+      type: 'interruption',
+      cutoffLatencyMs: event.cutoffLatencyMs,
+      interruptedAt: event.interruptedAt || Date.now(),
+    });
+  }
+
+  /** Track input/output token usage. */
+  trackTokens(event: TokenUsageEvent): void {
+    this.sendEvent({
+      type: 'token_usage',
+      inputTokens: event.inputTokens,
+      outputTokens: event.outputTokens,
+      model: event.model || 'gpt-4o-realtime',
+      timestamp: Date.now(),
+    });
+  }
+
+  /** Set dynamic custom properties/tags. */
+  setTags(tags: Record<string, string>): void {
+    this.tags = { ...this.tags, ...tags };
+  }
+
+  private sendEvent(payload: any): void {
+    const fullPayload = { ...payload, tags: this.tags };
+    if (this.ws && this.ws.readyState === WebSocket.OPEN) {
+      this.ws.send(JSON.stringify(fullPayload));
+    } else {
+      this.buffer.push(fullPayload);
+      if (!this.isConnecting && !this.ws) {
+        this.init();
+      }
+    }
+  }
+
+  private flushBuffer(): void {
+    while (this.buffer.length > 0 && this.ws && this.ws.readyState === WebSocket.OPEN) {
+      const payload = this.buffer.shift();
+      this.ws.send(JSON.stringify(payload));
+    }
+  }
+}
+
+/** Global Singleton Helper (CAST AI Style) */
+let _globalClient: VattaraObserveClient | null = null;
+
+export const Vattara = {
+  init(options: VattaraOptions): VattaraObserveClient {
+    _globalClient = new VattaraObserveClient(options);
+    _globalClient.init();
+    return _globalClient;
+  },
+
+  sendAudioFrame(base64Data: string, sampleRate?: number): void {
+    _globalClient?.sendAudioFrame(base64Data, sampleRate);
+  },
+
+  trackInterruption(event: InterruptionEvent): void {
+    _globalClient?.trackInterruption(event);
+  },
+
+  trackTokens(event: TokenUsageEvent): void {
+    _globalClient?.trackTokens(event);
+  },
+
+  setTags(tags: Record<string, string>): void {
+    _globalClient?.setTags(tags);
+  },
+};

package/tsconfig.json

@@ -0,0 +1,13 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "CommonJS",
+    "declaration": true,
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true
+  },
+  "include": ["src/**/*"]
+}