{"_id":"@arbolai/use-arbol-assistant","_rev":"2-6c8d4e5d0f661413c8499b47e9fda303","name":"@arbolai/use-arbol-assistant","dist-tags":{"latest":"1.0.1"},"versions":{"1.0.0":{"name":"@arbolai/use-arbol-assistant","version":"1.0.0","keywords":["react","hook","openai","realtime","voice","ai","conversation","webrtc","arbol"],"author":{"name":"Arbolai Company"},"license":"MIT","_id":"@arbolai/use-arbol-assistant@1.0.0","maintainers":[{"name":"llampiez","email":"llopezampiez7@gmail.com"}],"homepage":"https://github.com/eusoumaxi/arbol-ai/tree/ARBOLITO-F5/packages/use-arbol-assistant#readme","bugs":{"url":"https://github.com/eusoumaxi/arbol-ai/issues"},"dist":{"shasum":"1dd15ef656b2efd65a45188068c6b9defb70298d","tarball":"https://registry.npmjs.org/@arbolai/use-arbol-assistant/-/use-arbol-assistant-1.0.0.tgz","fileCount":8,"integrity":"sha512-1feqz17imAEp2IWwHz4CR6LeHtbwm/9asChx6bRjSePp3KyMLsZFbT/DOiH9dYCdmqcUh49RV0//wS2qGwk9Sg==","signatures":[{"sig":"MEYCIQDGmdoZlwzCVOkszQGLXoUAH5DpETZLCFnAXIk5NgyxdQIhAIP5QyNTt+P0UVYHmR2JPJAHu9wWsN+b8OZSzMNKvctY","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":66896},"main":"dist/index.js","types":"dist/index.d.ts","module":"dist/index.mjs","engines":{"node":">=18.0.0"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.mjs","require":"./dist/index.js"}},"gitHead":"2941ce124919f0d2d9762bd33a61af90d6ec69a1","private":false,"scripts":{"dev":"tsup --watch","lint":"eslint src","build":"tsup","type-check":"tsc --noEmit","build:complete":"npm run build","prepublishOnly":"npm run build:complete"},"_npmUser":{"name":"llampiez","email":"llopezampiez7@gmail.com"},"repository":{"url":"git+https://github.com/eusoumaxi/arbol-ai.git#main","type":"git"},"_npmVersion":"11.0.0","description":"React hook for real-time AI voice conversations using OpenAI Realtime API","directories":{},"_nodeVersion":"22.12.0","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsup":"^8.0.0","react":"^18.2.0","eslint":"^8.0.0","typescript":"^5.0.0","@types/react":"^18.2.0","@types/minimatch":"^6.0.0","@typescript-eslint/parser":"^6.0.0","@typescript-eslint/eslint-plugin":"^6.0.0"},"peerDependencies":{"react":">=18.0.0"},"_npmOperationalInternal":{"tmp":"tmp/use-arbol-assistant_1.0.0_1753473179910_0.9804622345917404","host":"s3://npm-registry-packages-npm-production"}},"1.0.1":{"name":"@arbolai/use-arbol-assistant","version":"1.0.1","private":false,"publishConfig":{"access":"public"},"description":"React hook for real-time AI voice conversations using OpenAI Realtime API","main":"dist/index.js","module":"dist/index.mjs","types":"dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.mjs","require":"./dist/index.js"}},"scripts":{"build":"tsup","build:complete":"npm run build","dev":"tsup --watch","type-check":"tsc --noEmit","lint":"eslint src","prepublishOnly":"npm run build:complete"},"keywords":["react","hook","openai","realtime","voice","ai","conversation","webrtc","arbol"],"author":{"name":"Arbolai Company"},"license":"MIT","repository":{"type":"git","url":"git+https://github.com/eusoumaxi/arbol-ai.git#main"},"homepage":"https://github.com/eusoumaxi/arbol-ai/tree/main/packages/use-arbol-assistant#readme","peerDependencies":{"react":">=18.0.0"},"devDependencies":{"@types/minimatch":"^6.0.0","@types/react":"^18.2.0","@typescript-eslint/eslint-plugin":"^6.0.0","@typescript-eslint/parser":"^6.0.0","eslint":"^8.0.0","react":"^18.2.0","tsup":"^8.0.0","typescript":"^5.0.0"},"engines":{"node":">=18.0.0"},"_id":"@arbolai/use-arbol-assistant@1.0.1","gitHead":"a979bee9e854fad6f5c0799478b9fc0286d6225b","bugs":{"url":"https://github.com/eusoumaxi/arbol-ai/issues"},"_nodeVersion":"22.12.0","_npmVersion":"11.0.0","dist":{"integrity":"sha512-mukFjWX6LPt/sm76NP/vd+QNgfBWUQ4LLzZHosqhQojqUmfvX6wt3XUlBijrd3a7CT3ntQNRoeBBe49mfRpr1Q==","shasum":"d647bc03374a495f88881fb2b69dca6dac63ee64","tarball":"https://registry.npmjs.org/@arbolai/use-arbol-assistant/-/use-arbol-assistant-1.0.1.tgz","fileCount":8,"unpackedSize":64423,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQCYQsG9uG9TZgdEYw73yh4ZPNFIZRN1QMtpb0HBCrYOogIhAO0Cwfuj5NxJmkfcLnlen+oVD1gqvVE2931Mn0iBZTdI"}]},"_npmUser":{"name":"llampiez","email":"llopezampiez7@gmail.com"},"directories":{},"maintainers":[{"name":"llampiez","email":"llopezampiez7@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/use-arbol-assistant_1.0.1_1753488593131_0.41208999188255424"},"_hasShrinkwrap":false}},"time":{"created":"2025-07-25T19:52:59.828Z","modified":"2025-07-26T00:09:53.501Z","1.0.0":"2025-07-25T19:53:00.116Z","1.0.1":"2025-07-26T00:09:53.320Z"},"bugs":{"url":"https://github.com/eusoumaxi/arbol-ai/issues"},"author":{"name":"Arbolai Company"},"license":"MIT","homepage":"https://github.com/eusoumaxi/arbol-ai/tree/main/packages/use-arbol-assistant#readme","keywords":["react","hook","openai","realtime","voice","ai","conversation","webrtc","arbol"],"repository":{"type":"git","url":"git+https://github.com/eusoumaxi/arbol-ai.git#main"},"description":"React hook for real-time AI voice conversations using OpenAI Realtime API","maintainers":[{"name":"llampiez","email":"llopezampiez7@gmail.com"}],"readme":"# use-arbol-assistant\r\n\r\nA **simple** React hook for integrating real-time AI voice conversations using OpenAI's Realtime API with Arbol's platform.\r\n\r\n## Features\r\n\r\n- 🎤 **Real-time voice conversations** with OpenAI's latest Realtime API\r\n- 🔊 **Audio streaming** via WebRTC for low latency\r\n- 📝 **Automatic transcription** of both user and assistant speech\r\n- ⚡ **Ultra-simple API** - just one function call\r\n- 🛡️ **TypeScript first** with full type safety\r\n- 🚀 **Easy integration** with existing React applications\r\n\r\n## Installation\r\n\r\n```bash\r\nnpm install use-arbol-assistant\r\n```\r\n\r\n```bash\r\nyarn add use-arbol-assistant\r\n```\r\n\r\n```bash\r\npnpm add use-arbol-assistant\r\n```\r\n\r\n```bash\r\nbun add use-arbol-assistant\r\n```\r\n\r\n## Quick Start\r\n\r\n```tsx\r\nimport { useArbolAssistant } from 'use-arbol-assistant'\r\n\r\nfunction VoiceAssistant() {\r\n  const { isLoading, isActiveSession, error, toggleSession } = useArbolAssistant('your-tenant-id')\r\n\r\n  return (\r\n    <div>\r\n      {error && <div className=\"mb-2 rounded bg-red-100 p-2 text-red-700\">Error: {error}</div>}\r\n\r\n      <button onClick={toggleSession} disabled={isLoading}>\r\n        {isLoading ? 'Connecting...' : isActiveSession ? 'Stop Conversation' : 'Start Conversation'}\r\n      </button>\r\n\r\n      {isActiveSession && (\r\n        <div className=\"flex items-center gap-2\">\r\n          <div className=\"h-2 w-2 animate-pulse rounded-full bg-green-500\" />\r\n          <span>Conversation active</span>\r\n        </div>\r\n      )}\r\n    </div>\r\n  )\r\n}\r\n```\r\n\r\n## API Reference\r\n\r\n### `useArbolAssistant(tenantId)`\r\n\r\n#### Parameters\r\n\r\n- **`tenantId`** (`string`): Your Arbol tenant ID\r\n\r\n#### Returns (`UseArbolAssistantReturn`)\r\n\r\n- **`isLoading`** (`boolean`): Whether the session is being established\r\n- **`isActiveSession`** (`boolean`): Whether a conversation is currently active\r\n- **`error`** (`string | null`): Current error message, if any (e.g., \"Tenant not found\", \"Failed to create session\")\r\n- **`toggleSession`** (`() => Promise<void>`): Start or stop the conversation\r\n\r\nThat's it! Super simple. 🎉\r\n\r\n## Examples\r\n\r\n### Basic Usage\r\n\r\n```tsx\r\nimport { useArbolAssistant } from 'use-arbol-assistant'\r\n\r\nfunction App() {\r\n  const { isLoading, isActiveSession, error, toggleSession } = useArbolAssistant('my-tenant-id')\r\n\r\n  return (\r\n    <div className=\"p-4\">\r\n      <h1>AI Voice Assistant</h1>\r\n\r\n      {error && (\r\n        <div className=\"mb-4 rounded bg-red-100 p-3 text-red-700\">\r\n          <strong>Error:</strong> {error}\r\n        </div>\r\n      )}\r\n\r\n      <button\r\n        onClick={toggleSession}\r\n        disabled={isLoading}\r\n        className={`rounded px-4 py-2 ${isActiveSession ? 'bg-red-500 text-white' : 'bg-blue-500 text-white'}`}\r\n      >\r\n        {isLoading && 'Connecting...'}\r\n        {!isLoading && isActiveSession && 'End Conversation'}\r\n        {!isLoading && !isActiveSession && 'Start Conversation'}\r\n      </button>\r\n    </div>\r\n  )\r\n}\r\n```\r\n\r\n### Sidebar Integration\r\n\r\nPerfect for navigation bars or sidebars:\r\n\r\n```tsx\r\nimport { useArbolAssistant } from 'use-arbol-assistant'\r\nimport { MicrophoneIcon, ExclamationTriangleIcon } from '@heroicons/react/16/solid'\r\n\r\nfunction SidebarConversation({ tenantId }: { tenantId: string }) {\r\n  const { isLoading, isActiveSession, error, toggleSession } = useArbolAssistant(tenantId)\r\n  const [isHovering, setIsHovering] = useState(false)\r\n\r\n  const getLabel = () => {\r\n    if (error) {\r\n      return isHovering ? 'Retry connection' : 'Connection failed'\r\n    }\r\n\r\n    if (isLoading && !isActiveSession) {\r\n      return 'Connecting...'\r\n    }\r\n\r\n    if (isActiveSession && !isLoading) {\r\n      return isHovering ? 'Stop conversation' : 'Ongoing conversation'\r\n    }\r\n\r\n    return 'Start conversation'\r\n  }\r\n\r\n  const getIcon = () => {\r\n    if (error) {\r\n      return <ExclamationTriangleIcon className=\"text-red-500\" />\r\n    }\r\n    return <MicrophoneIcon />\r\n  }\r\n\r\n  const getStatusIndicator = () => {\r\n    if (error) {\r\n      return (\r\n        <div className=\"ml-auto\">\r\n          <div className=\"h-2 w-2 rounded-full bg-red-500\" />\r\n        </div>\r\n      )\r\n    }\r\n\r\n    if (isActiveSession) {\r\n      return (\r\n        <div className=\"ml-auto\">\r\n          <div className=\"h-2 w-2 animate-pulse rounded-full bg-green-500\" />\r\n        </div>\r\n      )\r\n    }\r\n\r\n    return null\r\n  }\r\n\r\n  return (\r\n    <SidebarItem\r\n      onClick={toggleSession}\r\n      disabled={isLoading}\r\n      onMouseEnter={() => setIsHovering(true)}\r\n      onMouseLeave={() => setIsHovering(false)}\r\n      className={error ? 'hover:bg-red-50' : ''}\r\n    >\r\n      {getIcon()}\r\n      <SidebarLabel>{getLabel()}</SidebarLabel>\r\n      {getStatusIndicator()}\r\n    </SidebarItem>\r\n  )\r\n}\r\n```\r\n\r\n### Error Handling\r\n\r\nHandle different error scenarios:\r\n\r\n```tsx\r\nimport { useArbolAssistant } from 'use-arbol-assistant'\r\n\r\nfunction ErrorHandlingExample() {\r\n  const { isLoading, isActiveSession, error, toggleSession } = useArbolAssistant('tenant-id')\r\n\r\n  if (error) {\r\n    return (\r\n      <div className=\"rounded-lg border border-red-200 bg-red-50 p-4\">\r\n        <div className=\"flex items-start\">\r\n          <ExclamationTriangleIcon className=\"h-5 w-5 text-red-400\" />\r\n          <div className=\"ml-3\">\r\n            <h3 className=\"text-sm font-medium text-red-800\">Connection Error</h3>\r\n            <p className=\"mt-1 text-sm text-red-700\">{error}</p>\r\n            <button\r\n              onClick={toggleSession}\r\n              className=\"mt-2 rounded bg-red-100 px-3 py-1 text-sm text-red-800 hover:bg-red-200\"\r\n            >\r\n              Retry Connection\r\n            </button>\r\n          </div>\r\n        </div>\r\n      </div>\r\n    )\r\n  }\r\n\r\n  if (isLoading && !isActiveSession) {\r\n    return <div>🔄 Connecting to AI assistant...</div>\r\n  }\r\n\r\n  if (isActiveSession) {\r\n    return (\r\n      <div>\r\n        <div>🎤 Conversation active - speak now!</div>\r\n        <button onClick={toggleSession}>End Conversation</button>\r\n      </div>\r\n    )\r\n  }\r\n\r\n  return <button onClick={toggleSession}>🚀 Start AI Conversation</button>\r\n}\r\n```\r\n\r\n### Loading States\r\n\r\nHandle different loading states:\r\n\r\n```tsx\r\nimport { useArbolAssistant } from 'use-arbol-assistant'\r\n\r\nfunction LoadingExample() {\r\n  const { isLoading, isActiveSession, toggleSession } = useArbolAssistant('tenant-id')\r\n\r\n  if (isLoading && !isActiveSession) {\r\n    return <div>🔄 Connecting to AI assistant...</div>\r\n  }\r\n\r\n  if (isActiveSession) {\r\n    return (\r\n      <div>\r\n        <div>🎤 Conversation active - speak now!</div>\r\n        <button onClick={toggleSession}>End Conversation</button>\r\n      </div>\r\n    )\r\n  }\r\n\r\n  return <button onClick={toggleSession}>🚀 Start AI Conversation</button>\r\n}\r\n```\r\n\r\n## Requirements\r\n\r\n- React 18+\r\n- Modern browser with WebRTC support\r\n- Microphone access permission\r\n- Valid Arbol tenant ID\r\n\r\n## Browser Support\r\n\r\nThis library requires a modern browser with support for:\r\n\r\n- WebRTC\r\n- MediaDevices API\r\n- Web Audio API\r\n- ES2020 features\r\n\r\n## Built-in Features\r\n\r\nThe hook automatically handles:\r\n\r\n- ✅ **Audio streaming** via WebRTC\r\n- ✅ **Automatic transcription** of conversations\r\n- ✅ **Session cleanup** on component unmount\r\n- ✅ **Connection retry** logic\r\n- ✅ **OpenAI API integration**\r\n\r\n## Configuration\r\n\r\nThe hook uses optimized defaults:\r\n\r\n- **Voice**: `alloy`\r\n- **Model**: `gpt-4o-realtime-preview-2024-12-17`\r\n- **API**: `https://dev-api.arbol.uno`\r\n- **Debug mode**: `false`\r\n\r\nNo configuration needed! 🎯\r\n\r\n## Development\r\n\r\nTo run the library in development mode:\r\n\r\n```bash\r\n# Install dependencies\r\nbun install\r\n\r\n# Build the library\r\nbun run build\r\n\r\n# Run type checking\r\nbun run type-check\r\n\r\n# Run linting\r\nbun run lint\r\n```\r\n\r\n## Contributing\r\n\r\nContributions are welcome! Please read our contributing guidelines and submit pull requests to our GitHub repository.\r\n\r\n## License\r\n\r\nMIT © Arbol AI\r\n\r\n## Support\r\n\r\nFor support, please contact [support@arbol.ai](mailto:support@arbol.ai) or create an issue in our GitHub repository.\r\n","readmeFilename":"README.md"}