{"_id":"@ansa-so/sdk","name":"@ansa-so/sdk","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@ansa-so/sdk","version":"0.1.0","description":"JavaScript SDK for Ansa AI agents","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 src/index.ts --format cjs,esm --dts","dev":"tsup src/index.ts --format cjs,esm --dts --watch","clean":"rm -rf dist"},"keywords":["ansa","ai","chatbot","agents","conversational-ai","sdk"],"author":{"name":"Ansa"},"devDependencies":{"tsup":"^8.0.0","typescript":"^5.0.0"},"_id":"@ansa-so/sdk@0.1.0","gitHead":"d2bb0b4f1c4f120e1272a068fd8582df6947b019","_nodeVersion":"24.6.0","_npmVersion":"11.5.1","dist":{"integrity":"sha512-pRs1NP5wkiB1Epp5xQdkD7I0OJjCPYJTCsV9NxMVJ/2M1i372f/JTr7c7PotuMqk12wwICpIEDexOO4GRo8bxw==","shasum":"f8b6a459df0af2fb7a81b4167bbde70c9888423a","tarball":"https://registry.npmjs.org/@ansa-so/sdk/-/sdk-0.1.0.tgz","fileCount":6,"unpackedSize":44904,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCICRO+j7wArErkVnx/gdTrGoMyiFFo4xayhChZej1+fqzAiB10k8p0gRoNhlw+NzHiisNdHcBDjXlu9KhkBV5pmjzXA=="}]},"_npmUser":{"name":"ansa.so","email":"prod@ansa.so"},"directories":{},"maintainers":[{"name":"ansa.so","email":"prod@ansa.so"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/sdk_0.1.0_1769427071353_0.026151865792946705"},"_hasShrinkwrap":false}},"time":{"created":"2026-01-26T11:31:11.257Z","0.1.0":"2026-01-26T11:31:11.494Z","modified":"2026-01-26T11:31:11.719Z"},"maintainers":[{"name":"ansa.so","email":"prod@ansa.so"}],"description":"JavaScript SDK for Ansa AI agents","keywords":["ansa","ai","chatbot","agents","conversational-ai","sdk"],"author":{"name":"Ansa"},"readme":"# @ansa/sdk\n\nThe official JavaScript/TypeScript SDK for [Ansa](https://ansa.so) - AI agents that actually do things.\n\n## Features\n\n- 🤖 **Chat API** - Send messages and get responses from AI agents\n- 🌊 **Streaming** - Real-time streaming responses with callbacks\n- 🔌 **Widget Embed** - Easily embed the chat widget on any website\n- 🎛️ **Widget Control** - Programmatically control the widget (open, close, forms, etc.)\n- 📝 **TypeScript** - Full type definitions included\n- ⚡ **Command Queuing** - Commands are queued until widget is ready\n\n## Installation\n\n```bash\nnpm install @ansa/sdk\n# or\npnpm add @ansa/sdk\n# or\nyarn add @ansa/sdk\n```\n\n## Quick Start\n\n```typescript\nimport { createClient } from '@ansa/sdk';\n\nconst ansa = createClient({\n  apiKey: 'your-api-key', // Get from dashboard\n});\n\n// Send a message\nconst response = await ansa.chat('agent-id', 'What are your business hours?');\nconsole.log(response.message);\n```\n\n## Streaming\n\n```typescript\nawait ansa.chatStream('agent-id', 'Tell me about your products', {\n  onToken: (token) => process.stdout.write(token),\n  onComplete: () => console.log('\\n--- Done ---'),\n  onError: (error) => console.error(error),\n});\n```\n\n## Widget Embed\n\nFor simple website integration, use the embed helper:\n\n```typescript\nimport { embedWidget } from '@ansa/sdk';\n\nembedWidget({\n  agentId: 'your-agent-id',\n});\n```\n\nOr use the script tag directly:\n\n```html\n<script>\n  window.__ansa_config = {\n    agentId: 'your-agent-id',\n  };\n</script>\n<script src=\"https://cdn.ansa.so/embed.js\"></script>\n```\n\n## Widget Control\n\nControl the widget programmatically after embedding:\n\n### `openWidget(initMessage?)`\n\nOpen the widget chat. Optionally show initial greeting message(s) from the assistant.\n\n```typescript\nimport { openWidget } from '@ansa/sdk';\n\n// Just open\nopenWidget();\n\n// Open with a single greeting message\nopenWidget('Hello! How can I help you today?');\n\n// Open with multiple greeting messages\nopenWidget(['Welcome!', 'I can help you with orders, returns, and more.']);\n```\n\n### `closeWidget()`\n\nClose the widget chat.\n\n```typescript\nimport { closeWidget } from '@ansa/sdk';\n\ncloseWidget();\n```\n\n### `toggleWidget()`\n\nToggle the widget open/closed.\n\n```typescript\nimport { toggleWidget } from '@ansa/sdk';\n\ntoggleWidget();\n```\n\n### `isWidgetOpen()`\n\nCheck if the widget is currently open.\n\n```typescript\nimport { isWidgetOpen } from '@ansa/sdk';\n\nif (isWidgetOpen()) {\n  console.log('Widget is open');\n}\n```\n\n### `isWidgetReady()`\n\nCheck if the widget has finished loading.\n\n```typescript\nimport { isWidgetReady } from '@ansa/sdk';\n\nif (isWidgetReady()) {\n  console.log('Widget is ready');\n}\n```\n\n### `showBubbles(messages, duration?)`\n\nShow bubble message(s) near the widget button. Multiple messages are displayed with staggered timing.\n\n```typescript\nimport { showBubbles } from '@ansa/sdk';\n\n// Single bubble\nshowBubbles('Need help?');\n\n// Multiple bubbles (displayed 1 second apart)\nshowBubbles(['Any questions?', \"I'm here to help!\"]);\n\n// Auto-hide after 10 seconds\nshowBubbles('Limited time offer!', 10);\n```\n\n### `hideBubbles()`\n\nHide any visible bubble messages.\n\n```typescript\nimport { hideBubbles } from '@ansa/sdk';\n\nhideBubbles();\n```\n\n### `showForm(form, options?)`\n\nShow a form in the widget. Can be a server-side form (by name) or a client-side form (with schema).\n\n```typescript\nimport { showForm } from '@ansa/sdk';\n\n// Server-side form (fetched from your dashboard)\nshowForm('contact_form');\n\n// Client-side form with callback\nshowForm({\n  title: 'Get a Quote',\n  fields: [\n    { name: 'email', label: 'Email', type: 'email', validation: { required: { value: true, message: 'Required' } } },\n    { name: 'budget', label: 'Budget', type: 'select', options: [\n      { label: '$1,000 - $5,000', value: '1000-5000' },\n      { label: '$5,000 - $10,000', value: '5000-10000' },\n      { label: '$10,000+', value: '10000+' },\n    ]},\n    { name: 'message', label: 'Message', type: 'textarea' },\n  ],\n  submitButtonText: 'Request Quote',\n}, {\n  onSubmit: (data) => {\n    console.log('Form submitted:', data);\n    fetch('/api/quotes', { method: 'POST', body: JSON.stringify(data) });\n  },\n  onCancel: () => {\n    console.log('Form cancelled');\n  },\n});\n\n// Send form data to the agent as a chat message\nshowForm({\n  title: 'Contact Us',\n  fields: [\n    { name: 'name', label: 'Name', type: 'text' },\n    { name: 'question', label: 'Question', type: 'textarea' },\n  ],\n}, {\n  sendToAgent: true, // Form data becomes a chat message\n});\n\n// Both: callback AND send to agent\nshowForm({ ... }, {\n  onSubmit: (data) => analytics.track('form_submit', data),\n  sendToAgent: true,\n});\n```\n\n### `triggerEvent(eventName, data?)`\n\nTrigger a custom event. Useful for custom_event triggers configured in your dashboard.\n\n```typescript\nimport { triggerEvent } from '@ansa/sdk';\n\n// Trigger when user adds item to cart\ntriggerEvent('add_to_cart', { productId: '123', price: 29.99 });\n\n// Trigger on checkout\ntriggerEvent('checkout_started');\n```\n\n### `identify(identity)`\n\nIdentify the current user. User data will be available in forms and conversations.\n\n```typescript\nimport { identify } from '@ansa/sdk';\n\nidentify({\n  userId: 'user_123',\n  userMetadata: {\n    email: 'john@example.com',\n    name: 'John Doe',\n    plan: 'premium',\n  },\n});\n```\n\n### `clearIdentity()`\n\nClear the current user identity.\n\n```typescript\nimport { clearIdentity } from '@ansa/sdk';\n\nclearIdentity();\n```\n\n### `getVisitorId()`\n\nGet the anonymous visitor ID for the current session.\n\n```typescript\nimport { getVisitorId } from '@ansa/sdk';\n\nconst visitorId = getVisitorId();\nif (visitorId) {\n  console.log('Visitor ID:', visitorId);\n}\n```\n\n## Command Queuing\n\nAll widget control functions automatically queue commands if called before the widget is ready. You don't need to wait for the widget to load:\n\n```typescript\nimport { embedWidget, openWidget, showBubbles } from '@ansa/sdk';\n\n// These commands are queued and will execute once widget is ready\nembedWidget({ agentId: 'your-agent-id' });\nshowBubbles(['Welcome!', 'How can I help you today?']);\nopenWidget();\n```\n\n## API Reference\n\n### `createClient(config)`\n\nCreate a new Ansa client.\n\n```typescript\nconst ansa = createClient({\n  apiKey: 'your-api-key',\n  baseUrl: 'https://api.ansa.so', // Optional\n  timeout: 30000, // Optional, in ms\n});\n```\n\n### `ansa.chat(agentId, message, options?)`\n\nSend a message and get a response.\n\n```typescript\nconst response = await ansa.chat('agent-id', 'Hello!', {\n  conversationId: 'existing-conversation-id', // Optional\n  metadata: { userId: '123' }, // Optional\n});\n```\n\n### `ansa.chatStream(agentId, message, callbacks, options?)`\n\nStream a response with callbacks.\n\n```typescript\nawait ansa.chatStream('agent-id', 'Hello!', {\n  onToken: (token) => { /* each token as it arrives */ },\n  onMessage: (message) => { /* full message when complete */ },\n  onToolCall: (toolCall) => { /* when a tool is called */ },\n  onError: (error) => { /* on error */ },\n  onComplete: () => { /* when streaming is done */ },\n});\n```\n\n### `ansa.getAgents()`\n\nGet all your agents.\n\n```typescript\nconst agents = await ansa.getAgents();\n```\n\n### `ansa.getAgent(agentId)`\n\nGet a specific agent.\n\n```typescript\nconst agent = await ansa.getAgent('agent-id');\n```\n\n### `ansa.getConversations(agentId)`\n\nGet all conversations for an agent.\n\n```typescript\nconst conversations = await ansa.getConversations('agent-id');\n```\n\n### `ansa.getConversation(conversationId)`\n\nGet a conversation with messages.\n\n```typescript\nconst conversation = await ansa.getConversation('conversation-id');\n```\n\n## TypeScript\n\nThis package is written in TypeScript and includes full type definitions.\n\n```typescript\nimport type {\n  Agent,\n  Conversation,\n  Message,\n  ChatResponse,\n  ChatOptions,\n  AnsaConfig,\n  StreamCallbacks,\n  ToolCall,\n  WidgetConfig,\n  FormSchema,\n  FormField,\n  ShowFormOptions,\n} from '@ansa/sdk';\n```\n\n## Error Handling\n\nThe SDK throws `AnsaError` for API errors:\n\n```typescript\nimport { createClient, AnsaError } from '@ansa/sdk';\n\nconst ansa = createClient({ apiKey: 'your-api-key' });\n\ntry {\n  await ansa.chat('agent-id', 'Hello!');\n} catch (error) {\n  if (error instanceof AnsaError) {\n    console.error('API Error:', error.message);\n    console.error('Status:', error.statusCode);\n    console.error('Code:', error.code);\n  }\n}\n```\n\n## License\n\nMIT\n","readmeFilename":"README.md","_rev":"1-0ffe9f581d4b6b359cc41ea4f8c2ef67"}