@telnyx/ai-agent-lib 0.1.3 → 0.1.4

package/README.md

@@ -1,3 +1,255 @@
-# Telnyx AI Agent Library
+# Telnyx AI Agent Library
+
+A TypeScript/React library for building AI-powered voice conversation applications using Telnyx's WebRTC infrastructure. This library provides a comprehensive set of tools for managing AI agent connections, real-time transcriptions, conversation states, and audio streaming.
+
+## Features
+
+- 🎯 **Easy AI Agent Integration** - Connect to Telnyx AI agents with minimal setup
+- 🎙️ **Real-time Transcription** - Automatic speech-to-text with live updates
+- 🔊 **Audio Stream Management** - Built-in audio monitoring and playback controls
+- ⚛️ **React Hooks & Components** - Ready-to-use React components and hooks
+- 🔄 **State Management** - Automatic state synchronization using Jotai
+- 📱 **Connection Management** - Robust connection handling with error recovery
+- 🎚️ **Agent State Tracking** - Monitor agent states (listening, speaking, thinking)
+
+## Installation
+
+```bash
+npm install @telnyx/ai-agent-lib
+```
+
+### Peer Dependencies
+
+This library requires React 19.1.1+ as a peer dependency:
+
+```bash
+npm install react@^19.1.1 react-dom@^19.1.0
+```
+
+## Quick Start
+
+### 1. Wrap your app with the provider
+
+```tsx
+import React from 'react';
+import { createRoot } from 'react-dom/client';
+import { TelnyxAIAgentProvider } from '@telnyx/ai-agent-lib';
+import App from './App';
+
+createRoot(document.getElementById('root')!).render(
+  <TelnyxAIAgentProvider agentId="your-agent-id">
+    <App />
+  </TelnyxAIAgentProvider>
+);
+```
+
+### 2. Use hooks in your components
+
+```tsx
+import React, { useEffect, useRef } from 'react';
+import {
+  useClient,
+  useTranscript,
+  useConnectionState,
+  useConversation,
+  useAgentState
+} from '@telnyx/ai-agent-lib';
+
+function VoiceChat() {
+  const client = useClient();
+  const transcript = useTranscript();
+  const connectionState = useConnectionState();
+  const conversation = useConversation();
+  const agentState = useAgentState();
+  const audioRef = useRef<HTMLAudioElement>(null);
+
+  // Setup audio playback
+  useEffect(() => {
+    if (conversation?.call?.remoteStream && audioRef.current) {
+      audioRef.current.srcObject = conversation.call.remoteStream;
+    }
+  }, [conversation]);
+
+  return (
+    <div>
+      <h2>Connection: {connectionState}</h2>
+      <h3>Agent State: {agentState}</h3>
+      
+      <button 
+        onClick={() => client.startConversation()}
+        disabled={connectionState !== 'connected'}
+      >
+        Start Conversation
+      </button>
+      
+      <button onClick={() => client.endConversation()}>
+        End Conversation
+      </button>
+
+      <audio ref={audioRef} autoPlay playsInline controls />
+
+      <div>
+        <h3>Transcript ({transcript.length} items)</h3>
+        {transcript.map((item) => (
+          <div key={item.id}>
+            <strong>{item.role}:</strong> {item.content}
+            <small> - {item.timestamp.toLocaleTimeString()}</small>
+          </div>
+        ))}
+      </div>
+    </div>
+  );
+}
+```
+
+## API Reference
+
+### TelnyxAIAgentProvider Props
+
+| Prop | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| `agentId` | `string` | ✅ | - | Your Telnyx AI agent ID |
+| `versionId` | `string` | ❌ | `"main"` | Agent version to use |
+| `environment` | `"production" \| "development"` | ❌ | `"production"` | Telnyx environment |
+
+### Hooks
+
+#### `useClient()`
+Returns the `TelnyxAIAgent` instance for direct API access.
+
+**Methods:**
+- `connect()` - Connect to Telnyx platform
+- `disconnect()` - Disconnect and cleanup
+- `startConversation()` - Start a new conversation
+- `endConversation()` - End the current conversation
+- `transcript` - Get current transcript array
+
+**Events:**
+- `agent.connected` - Agent successfully connected
+- `agent.disconnected` - Agent disconnected
+- `agent.error` - Connection or operational error
+- `transcript.item` - New transcript item received
+- `conversation.update` - Conversation state updated
+- `conversation.agent.state` - Agent state changed
+
+#### `useConnectionState()`
+Returns the current connection state: `"connecting" | "connected" | "disconnected" | "error"`
+
+#### `useTranscript()`
+Returns an array of `TranscriptItem` objects representing the conversation history.
+
+**TranscriptItem:**
+```typescript
+{
+  id: string;
+  role: "user" | "assistant";
+  content: string;
+  timestamp: Date;
+}
+```
+
+#### `useConversation()`
+Returns the current conversation notification object containing call information and state.
+
+#### `useAgentState()`
+Returns the current agent state: `"listening" | "speaking" | "thinking"`
+
+### Direct Usage (Without React)
+
+You can also use the library without React:
+
+```typescript
+import { TelnyxAIAgent } from '@telnyx/ai-agent-lib';
+
+const agent = new TelnyxAIAgent({
+  agentId: 'your-agent-id',
+  versionId: 'main',
+  environment: 'production'
+});
+
+// Connect to the platform
+await agent.connect();
+
+// Listen for events
+agent.on('agent.connected', () => {
+  console.log('Agent connected!');
+});
+
+agent.on('transcript.item', (item) => {
+  console.log(`${item.role}: ${item.content}`);
+});
+
+agent.on('conversation.agent.state', (state) => {
+  console.log(`Agent is now: ${state}`);
+});
+
+// Start a conversation
+await agent.startConversation();
+
+// Access transcript
+console.log(agent.transcript);
+
+// Cleanup
+await agent.disconnect();
+```
+
+## Advanced Usage
+
+### Custom Audio Handling
+
+The library automatically handles audio stream monitoring and agent state detection based on audio levels. The audio stream is available through the conversation object:
+
+```tsx
+const conversation = useConversation();
+const audioStream = conversation?.call?.remoteStream;
+```
+
+### Error Handling
+
+```tsx
+const client = useClient();
+
+useEffect(() => {
+  const handleError = (error: Error) => {
+    console.error('Agent error:', error);
+    // Handle error (show notification, retry connection, etc.)
+  };
+
+  client.on('agent.error', handleError);
+  
+  return () => {
+    client.off('agent.error', handleError);
+  };
+}, [client]);
+```
+
+### State Persistence
+
+The library uses Jotai for state management, which automatically handles state updates across components. All state is ephemeral and resets when the provider unmounts.
+
+## TypeScript Support
+
+This library is built with TypeScript and provides full type definitions. All hooks and components are fully typed for the best development experience.
+
+## Examples
+
+Check out the `/src` directory for a complete example application demonstrating all features of the library.
+
+## Dependencies
+
+- `@telnyx/webrtc` - Telnyx WebRTC SDK
+- `eventemitter3` - Event handling
+- `jotai` - State management
+
+## License
+
+This library is part of the Telnyx ecosystem. Please refer to Telnyx's terms of service and licensing agreements.
+
+## Support
+
+For support, please contact Telnyx support or check the [Telnyx documentation](https://developers.telnyx.com/).
+
+## Contributing
+
+This library is maintained by Telnyx. For bug reports or feature requests, please contact Telnyx support.elnyx AI Agent Library
 
-This library provides a set of tools and utilities for building AI agents that can interact with Telnyx's services. It includes components for managing audio streams, handling agent states, and more.

package/dist/index.js

@@ -2614,16 +2614,23 @@ class mi extends lt {
       }
   };
 }
-const bi = 5;
-class yi {
+function bi(t, e) {
+  let n = 0;
+  return (...i) => {
+    const s = Date.now();
+    s - n >= e && (n = s, t(...i));
+  };
+}
+const yi = 10;
+class _i {
   animationFrameId = null;
   stream = null;
   audioContext = null;
   source = null;
   analyser = null;
-  updateAgentState = (e) => {
+  updateAgentState = bi((e) => {
     Ee.emit("conversation.agent.state", e);
-  };
+  }, 100);
   setMonitoredAudioStream(e) {
     this.stream && this.stopAudioStreamMonitor(), this.stream = e, this.startAudioStreamMonitor();
   }
@@ -2635,7 +2642,7 @@ class yi {
     this.audioContext = new AudioContext(), this.source = this.audioContext.createMediaStreamSource(this.stream), this.analyser = this.audioContext.createAnalyser(), this.source.connect(this.analyser), this.analyser.fftSize = 512;
     const e = new Uint8Array(this.analyser.frequencyBinCount), n = () => {
       const i = e.reduce((s, c) => s + c, 0) / e.length;
-      this.analyser?.getByteFrequencyData(e), i > bi ? this.updateAgentState("speaking") : this.updateAgentState("listening"), this.animationFrameId = requestAnimationFrame(n);
+      this.analyser?.getByteFrequencyData(e), i >= yi ? this.updateAgentState("speaking") : this.updateAgentState("listening"), this.animationFrameId = requestAnimationFrame(n);
     };
     this.animationFrameId = requestAnimationFrame(n);
   }
@@ -2659,7 +2666,7 @@ class Ot extends lt {
     }), this.telnyxRTC.on(O.Ready, this.onClientReady), this.telnyxRTC.on(O.Error, this.onClientOrSocketError), this.telnyxRTC.on(O.SocketError, this.onClientOrSocketError), this.telnyxRTC.on(O.Notification, this.onNotification), this.transcription = new mi(this.telnyxRTC), this.transcription.addListener("transcript.item", this.onTranscriptItem), Ee.addListener(
       "conversation.agent.state",
       this.onAgentStateChange
-    ), this.audioStreamMonitor = new yi();
+    ), this.audioStreamMonitor = new _i();
   }
   async connect() {
     return this.telnyxRTC.connect();
@@ -2716,7 +2723,7 @@ var Oe = { exports: {} }, ve = {};
  * LICENSE file in the root directory of this source tree.
  */
 var Lt;
-function _i() {
+function wi() {
   if (Lt) return ve;
   Lt = 1;
   var t = Symbol.for("react.transitional.element"), e = Symbol.for("react.fragment");
@@ -2748,7 +2755,7 @@ var me = {};
  * LICENSE file in the root directory of this source tree.
  */
 var Mt;
-function wi() {
+function Si() {
   return Mt || (Mt = 1, process.env.NODE_ENV !== "production" && function() {
     function t(v) {
       if (v == null) return null;
@@ -2981,10 +2988,10 @@ React keys must be passed directly to JSX without using spread:
   }()), me;
 }
 var Nt;
-function Si() {
-  return Nt || (Nt = 1, process.env.NODE_ENV === "production" ? Oe.exports = _i() : Oe.exports = wi()), Oe.exports;
+function Ci() {
+  return Nt || (Nt = 1, process.env.NODE_ENV === "production" ? Oe.exports = wi() : Oe.exports = Si()), Oe.exports;
 }
-var be = Si();
+var be = Ci();
 const we = {}, Dt = (t, e) => t.unstable_is ? t.unstable_is(e) : e === t, Pt = (t) => "init" in t, He = (t) => !!t.write, jt = (t) => "v" in t || "e" in t, Le = (t) => {
   if ("e" in t)
     throw t.e;
@@ -2994,7 +3001,7 @@ const we = {}, Dt = (t, e) => t.unstable_is ? t.unstable_is(e) : e === t, Pt = (
 }, $e = /* @__PURE__ */ new WeakMap(), Ut = (t) => {
   var e;
   return Ve(t) && !!((e = $e.get(t)) != null && e[0]);
-}, Ci = (t) => {
+}, Ii = (t) => {
   const e = $e.get(t);
   e?.[0] && (e[0] = !1, e[1].forEach((n) => n()));
 }, rn = (t, e) => {
@@ -3021,7 +3028,7 @@ const we = {}, Dt = (t, e) => t.unstable_is ? t.unstable_is(e) : e === t, Pt = (
   if (Ve(e))
     for (const a of i.d.keys())
       an(t, e, n(a));
-  i.v = e, delete i.e, (!s || !Object.is(c, i.v)) && (++i.n, Ve(c) && Ci(c));
+  i.v = e, delete i.e, (!s || !Object.is(c, i.v)) && (++i.n, Ve(c) && Ii(c));
 }, $t = (t, e, n) => {
   var i;
   const s = /* @__PURE__ */ new Set();
@@ -3030,7 +3037,7 @@ const we = {}, Dt = (t, e) => t.unstable_is ? t.unstable_is(e) : e === t, Pt = (
   for (const c of e.p)
     s.add(c);
   return s;
-}, Ii = () => {
+}, Ei = () => {
   const t = /* @__PURE__ */ new Set(), e = () => {
     t.forEach((n) => n());
   };
@@ -3048,7 +3055,7 @@ const we = {}, Dt = (t, e) => t.unstable_is ? t.unstable_is(e) : e === t, Pt = (
       a?.delete(s), a.size || e.delete(c);
     };
   }, n;
-}, Ei = (t) => (t.c || (t.c = Qe()), t.m || (t.m = Qe()), t.u || (t.u = Qe()), t.f || (t.f = Ii()), t), ki = Symbol(), Ti = (t = /* @__PURE__ */ new WeakMap(), e = /* @__PURE__ */ new WeakMap(), n = /* @__PURE__ */ new WeakMap(), i = /* @__PURE__ */ new Set(), s = /* @__PURE__ */ new Set(), c = /* @__PURE__ */ new Set(), a = {}, l = (C, ...I) => C.read(...I), h = (C, ...I) => C.write(...I), p = (C, I) => {
+}, ki = (t) => (t.c || (t.c = Qe()), t.m || (t.m = Qe()), t.u || (t.u = Qe()), t.f || (t.f = Ei()), t), Ti = Symbol(), Ri = (t = /* @__PURE__ */ new WeakMap(), e = /* @__PURE__ */ new WeakMap(), n = /* @__PURE__ */ new WeakMap(), i = /* @__PURE__ */ new Set(), s = /* @__PURE__ */ new Set(), c = /* @__PURE__ */ new Set(), a = {}, l = (C, ...I) => C.read(...I), h = (C, ...I) => C.write(...I), p = (C, I) => {
   var w;
   return (w = C.unstable_onInit) == null ? void 0 : w.call(C, I);
 }, f = (C, I) => {
@@ -3312,29 +3319,29 @@ const we = {}, Dt = (t, e) => t.unstable_is ? t.unstable_is(e) : e === t, Pt = (
       };
     }
   };
-  return Object.defineProperty(ee, ki, { value: G }), ee;
-}, cn = Ti, Ri = Ei, Vt = rn, ut = {};
-let xi = 0;
+  return Object.defineProperty(ee, Ti, { value: G }), ee;
+}, cn = Ri, xi = ki, Vt = rn, ut = {};
+let Ai = 0;
 function Fe(t, e) {
-  const n = `atom${++xi}`, i = {
+  const n = `atom${++Ai}`, i = {
     toString() {
       return (ut ? "production" : void 0) !== "production" && this.debugLabel ? n + ":" + this.debugLabel : n;
     }
   };
-  return typeof t == "function" ? i.read = t : (i.init = t, i.read = Ai, i.write = Oi), i;
+  return typeof t == "function" ? i.read = t : (i.init = t, i.read = Oi, i.write = Li), i;
 }
-function Ai(t) {
+function Oi(t) {
   return t(this);
 }
-function Oi(t, e, n) {
+function Li(t, e, n) {
   return e(
     this,
     typeof n == "function" ? n(t(this)) : n
   );
 }
-const Li = () => {
+const Mi = () => {
   let t = 0;
-  const e = Ri({}), n = /* @__PURE__ */ new WeakMap(), i = /* @__PURE__ */ new WeakMap(), s = cn(
+  const e = xi({}), n = /* @__PURE__ */ new WeakMap(), i = /* @__PURE__ */ new WeakMap(), s = cn(
     n,
     i,
     void 0,
@@ -3374,20 +3381,20 @@ const Li = () => {
     }
   });
 };
-function Mi() {
-  return (ut ? "production" : void 0) !== "production" ? Li() : cn();
+function Ni() {
+  return (ut ? "production" : void 0) !== "production" ? Mi() : cn();
 }
 let ye;
-function Ni() {
-  return ye || (ye = Mi(), (ut ? "production" : void 0) !== "production" && (globalThis.__JOTAI_DEFAULT_STORE__ || (globalThis.__JOTAI_DEFAULT_STORE__ = ye), globalThis.__JOTAI_DEFAULT_STORE__ !== ye && console.warn(
+function Di() {
+  return ye || (ye = Ni(), (ut ? "production" : void 0) !== "production" && (globalThis.__JOTAI_DEFAULT_STORE__ || (globalThis.__JOTAI_DEFAULT_STORE__ = ye), globalThis.__JOTAI_DEFAULT_STORE__ !== ye && console.warn(
     "Detected multiple Jotai instances. It may cause unexpected behavior with the default store. https://github.com/pmndrs/jotai/discussions/2044"
   ))), ye;
 }
-const Di = {}, Pi = Bt(
+const Pi = {}, ji = Bt(
   void 0
 );
 function dn(t) {
-  return Gt(Pi) || Ni();
+  return Gt(ji) || Di();
 }
 const st = (t) => typeof t?.then == "function", ot = (t) => {
   t.status || (t.status = "pending", t.then(
@@ -3398,7 +3405,7 @@ const st = (t) => typeof t?.then == "function", ot = (t) => {
       t.status = "rejected", t.reason = e;
     }
   ));
-}, ji = rt.use || // A shim for older React versions
+}, Ui = rt.use || // A shim for older React versions
 ((t) => {
   if (t.status === "pending")
     throw t;
@@ -3453,7 +3460,7 @@ function Ge(t, e) {
     return h(), f;
   }, [s, t, n, i]), mn(p), st(p)) {
     const f = Ft(p, () => s.get(t));
-    return i && ot(f), ji(f);
+    return i && ot(f), Ui(f);
   }
   return p;
 }
@@ -3461,7 +3468,7 @@ function Be(t, e) {
   const n = dn();
   return bn(
     (...s) => {
-      if ((Di ? "production" : void 0) !== "production" && !("write" in t))
+      if ((Pi ? "production" : void 0) !== "production" && !("write" in t))
         throw new Error("not writable atom");
       return n.set(t, ...s);
     },
@@ -3469,10 +3476,10 @@ function Be(t, e) {
   );
 }
 const ln = Fe([]);
-function zi() {
+function Ji() {
   return Ge(ln);
 }
-function Ui() {
+function $i() {
   return Be(ln);
 }
 const We = () => {
@@ -3481,8 +3488,8 @@ const We = () => {
     throw new Error("useClient must be used within a TelnyxAIAgentProvider");
   return t;
 };
-function $i() {
-  const t = We(), e = Ui();
+function Vi() {
+  const t = We(), e = $i();
   return ce(() => {
     const n = (i) => e((s) => [...s, i]);
     return t.addListener("transcript.item", n), () => {
@@ -3491,14 +3498,14 @@ function $i() {
   }, [t, e]), null;
 }
 const un = Fe("connecting");
-function Ji() {
+function Hi() {
   return Ge(un);
 }
-function Vi() {
+function Fi() {
   return Be(un);
 }
-function Fi() {
-  const t = We(), e = Vi();
+function Gi() {
+  const t = We(), e = Fi();
   return ce(() => {
     const n = () => e("connected"), i = () => e("disconnected"), s = () => e("error");
     return t.addListener("agent.connected", n), t.addListener("agent.disconnected", i), t.addListener("agent.error", s), () => {
@@ -3507,14 +3514,14 @@ function Fi() {
   }, [t, e]), null;
 }
 const hn = Fe(null);
-function Hi() {
+function Ki() {
   return Ge(hn);
 }
-function Gi() {
+function Bi() {
   return Be(hn);
 }
-const Bi = () => {
-  const t = We(), e = Gi();
+const Wi = () => {
+  const t = We(), e = Bi();
   return ce(() => {
     const n = (i) => {
       e(i);
@@ -3524,14 +3531,14 @@ const Bi = () => {
     };
   }, [t, e]), null;
 }, pn = Fe("listening");
-function Ki() {
+function Qi() {
   return Ge(pn);
 }
-function Wi() {
+function qi() {
   return Be(pn);
 }
-function qi() {
-  const t = We(), e = Wi();
+function Yi() {
+  const t = We(), e = qi();
   return ce(() => {
     const n = (i) => {
       e(i);
@@ -3541,7 +3548,7 @@ function qi() {
     };
   }, [t, e]), null;
 }
-const fn = Bt(null), Qi = ({
+const fn = Bt(null), Xi = ({
   children: t,
   agentId: e,
   environment: n,
@@ -3558,24 +3565,24 @@ const fn = Bt(null), Qi = ({
   }, [e, s, n, i]), ce(() => {
     s?.connect();
   }, [s]), /* @__PURE__ */ be.jsxs(fn.Provider, { value: s, children: [
-    /* @__PURE__ */ be.jsx($i, {}),
-    /* @__PURE__ */ be.jsx(Fi, {}),
-    /* @__PURE__ */ be.jsx(Bi, {}),
-    /* @__PURE__ */ be.jsx(qi, {}),
+    /* @__PURE__ */ be.jsx(Vi, {}),
+    /* @__PURE__ */ be.jsx(Gi, {}),
+    /* @__PURE__ */ be.jsx(Wi, {}),
+    /* @__PURE__ */ be.jsx(Yi, {}),
     t
   ] });
 };
 export {
   fn as ClientContext,
   Ot as TelnyxAIAgent,
-  Qi as TelnyxAIAgentProvider,
-  Ki as useAgentState,
+  Xi as TelnyxAIAgentProvider,
+  Qi as useAgentState,
   We as useClient,
-  Ji as useConnectionState,
-  Hi as useConversation,
-  Wi as useSetAgentState,
-  Vi as useSetConnectionState,
-  Gi as useSetConversation,
-  Ui as useSetTranscript,
-  zi as useTranscript
+  Hi as useConnectionState,
+  Ki as useConversation,
+  qi as useSetAgentState,
+  Fi as useSetConnectionState,
+  Bi as useSetConversation,
+  $i as useSetTranscript,
+  Ji as useTranscript
 };

package/dist/util.d.ts

@@ -1 +1,2 @@
 export declare function debounce<T extends unknown[]>(fn: (...args: T) => void, delay: number): (...args: T) => void;
+export declare function throttle<T extends unknown[]>(fn: (...args: T) => void, delay: number): (...args: T) => void;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@telnyx/ai-agent-lib",
   "private": false,
-  "version": "0.1.3",
+  "version": "0.1.4",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -25,8 +25,8 @@
     "jotai": "^2.12.5"
   },
   "devDependencies": {
-    "@types/node": "^24.1.0",
     "@eslint/js": "^9.30.1",
+    "@types/node": "^24.1.0",
     "@types/react": "^19.1.8",
     "@types/react-dom": "^19.1.6",
     "@vitejs/plugin-react-swc": "^3.10.2",
@@ -34,6 +34,8 @@
     "eslint-plugin-react-hooks": "^5.2.0",
     "eslint-plugin-react-refresh": "^0.4.20",
     "globals": "^16.3.0",
+    "react": "^19.1.1",
+    "react-dom": "^19.1.1",
     "release-it": "^19.0.4",
     "typescript": "~5.8.3",
     "typescript-eslint": "^8.35.1",