{"_id":"@adalink/spark-chat","name":"@adalink/spark-chat","dist-tags":{"latest":"1.0.0"},"versions":{"1.0.0":{"name":"@adalink/spark-chat","description":"Universal Web Components library for building chat interfaces with built-in observability","type":"module","version":"1.0.0","license":"Apache-2.0","keywords":["web-components","chat","observability","o11y","ai","conversational-ui"],"repository":{"type":"git","url":"git+ssh://git@github.com/Adalink-ai/spark_chat.git"},"bugs":{"url":"https://github.com/Adalink-ai/spark_chat/issues"},"homepage":"https://github.com/Adalink-ai/spark_chat#readme","author":{"name":"Cleber de Moraes Goncalves","email":"cleber.engineer@gmail.com","url":"https://github.com/deMGoncalves"},"exports":{".":{"import":"./dist/chat.js","require":"./dist/chat.cjs"},"./agent":{"import":"./dist/agent.js","require":"./dist/agent.cjs"},"./pipe":{"import":"./dist/pipe.js","require":"./dist/pipe.cjs"}},"main":"./dist/chat.js","module":"./dist/chat.js","dependencies":{"@adalink/spark-echo":"^1.0.0","@adalink/spark-std":"^1.3.4","@mlc-ai/web-llm":"^0.2.81","showdown":"^2.1.0"},"devDependencies":{"@biomejs/biome":"2.4.7","@commitlint/cli":"^20.5.0","@commitlint/config-conventional":"^20.5.0","esbuild":"^0.27.2","husky":"^9.1.7","lint-staged":"^16.4.0","typescript":"^5.7.2","vite":"^8.0.0"},"scripts":{"build":"vite build","dev":"vite","prepare":"husky"},"_id":"@adalink/spark-chat@1.0.0","gitHead":"a98b5b8cd9f5f19fa3171f33ee307f55879d608f","_nodeVersion":"20.20.1","_npmVersion":"10.8.2","dist":{"integrity":"sha512-1MPUjk6k2wnzBhW8qi9Jbb5ea4nvw4jHexXei4l6yoDEOo4QkWXg5uGYKZZjoyqXnMLLj4OdWPOySx18xGmE+Q==","shasum":"f51341f1f39deaca3b9f64547bf968e68a048be9","tarball":"https://registry.npmjs.org/@adalink/spark-chat/-/spark-chat-1.0.0.tgz","fileCount":13,"unpackedSize":217769,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQDz+l0HYSR7tF0e+NZjZBLF+AhWcr5r5YKy7ZYXNZE5TgIhAMnQ+dbccjf2QLRHgexg49XU8e24uMm176cYUGalUOMP"}]},"_npmUser":{"name":"cleiton.couto","email":"cleiton.couto@adalink.ai"},"directories":{},"maintainers":[{"name":"cleiton.couto","email":"cleiton.couto@adalink.ai"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/spark-chat_1.0.0_1774361980834_0.145931801341058"},"_hasShrinkwrap":false}},"time":{"created":"2026-03-24T14:19:40.722Z","1.0.0":"2026-03-24T14:19:40.993Z","modified":"2026-03-24T14:19:41.169Z"},"maintainers":[{"name":"cleiton.couto","email":"cleiton.couto@adalink.ai"}],"description":"Universal Web Components library for building chat interfaces with built-in observability","homepage":"https://github.com/Adalink-ai/spark_chat#readme","keywords":["web-components","chat","observability","o11y","ai","conversational-ui"],"repository":{"type":"git","url":"git+ssh://git@github.com/Adalink-ai/spark_chat.git"},"author":{"name":"Cleber de Moraes Goncalves","email":"cleber.engineer@gmail.com","url":"https://github.com/deMGoncalves"},"bugs":{"url":"https://github.com/Adalink-ai/spark_chat/issues"},"license":"Apache-2.0","readme":"# ⚡ Spark Chat\n\n[![npm version](https://img.shields.io/npm/v/@adalink/spark-chat?style=flat-square)](https://www.npmjs.com/package/@adalink/spark-chat)\n[![License](https://img.shields.io/npm/l/@adalink/spark-chat?style=flat-square)](LICENSE)\n[![Build Status](https://img.shields.io/github/actions/workflow/status/Adalink-ai/spark_chat/ci.yml?style=flat-square)](https://github.com/Adalink-ai/spark_chat/actions)\n[![Code Style](https://img.shields.io/badge/code_style-biome-purple?style=flat-square)](https://biomejs.dev)\n[![Ecosystem](https://img.shields.io/badge/Spark_Ecosystem-compatible-blue?style=flat-square)](https://github.com/Adalink-ai)\n\n**Universal Web Components library for building chat interfaces with built-in observability. Zero framework dependencies, tree-shakeable packages.**\n\n---\n\n## 📖 What is Spark Chat?\n\nSpark Chat is a modern, lightweight library that provides **production-ready chat components with integrated observability**. Built on native Web Components APIs, it enables you to build chat interfaces that work with React, Vue, Angular, or vanilla JavaScript—no framework dependencies required.\n\n### 🎯 Why Choose Spark Chat?\n\n- **Zero Framework Dependencies** - Pure Web Components, no runtime overhead\n- **Framework Agnostic** - Works with any framework or vanilla JavaScript\n- **Built-in Observability** - Real-time conversation monitoring and analytics\n- **Pluggable AI Agents** - Easy integration with OpenAI, Anthropic, or custom AI services\n- **Middleware Pipes** - Flexible message processing through pipe system\n- **Production Ready** - Battle-tested with comprehensive testing\n- **Performance First** - Optimized for speed with minimal bundle size (~3KB)\n\n### 🚀 Perfect For\n\n- **Web Components Projects** - Add chat functionality to native Web Components\n- **Framework-Independent Apps** - Build once, use everywhere\n- **AI-Powered Applications** - Easy integration with AI agents\n- **Performance-Critical Apps** - Minimal overhead, maximum speed\n- **Micro-Frontends** - Isolated chat components with clean interfaces\n- **Monitoring & Analytics** - Built-in observability for conversations\n\n---\n\n## ✨ Key Features\n\n### 🎯 Declarative API\n\nDescribe chat behavior via HTML attributes, not imperative code:\n\n```javascript\n// Traditional approach\nclass ChatComponent extends HTMLElement {\n  constructor() {\n    super();\n    this.attachShadow({ mode: 'open' });\n    this.shadowRoot.addEventListener('sent', this.handleSent.bind(this));\n  }\n\n  handleSent(event) {\n    this.sendMessage(event.detail.content);\n  }\n\n  sendMessage(content) {\n    // Complex imperative code\n  }\n}\n\n// Spark Chat approach\n@define('ada-chat')\n@paint(component, style)\nclass Chat extends Echo(HTMLElement) {\n  @on.sent('[name=\"input\"]')\n  handleSent(event) {\n    this[event.notify](event.detail)\n  }\n}\n```\n\n### 📦 Modular Package System\n\nImport only what you need:\n\n```javascript\n// Complete chat library\nimport Chat from '@adalink/spark-chat'\n\n// Individual packages\nimport { Agent } from '@adalink/spark-chat/agent'\nimport { Pipe } from '@adalink/spark-chat/pipe'\n```\n\n### ⚡ Built-in Observability\n\nMonitor conversations in real-time:\n\n```javascript\nimport { Chat } from '@adalink/spark-chat'\n\nconst monitor = Chat.monitor(document.querySelector('ada-chat'))\n\nmonitor.push([\n  { role: 'user', content: 'Hello!' },\n  { role: 'assistant', content: 'Hi there!' }\n])\n\n// Get conversation state\nconsole.log(monitor.get())\n```\n\n### 🔌 Pluggable AI Agents\n\nEasy integration with any AI service:\n\n```javascript\nimport { Agent } from '@adalink/spark-chat'\n\n// OpenAI\nAgent.processor(async (payload) => {\n  const response = await fetch('https://api.openai.com/v1/chat/completions', {\n    body: JSON.stringify({\n      model: 'gpt-4',\n      messages: payload.messages\n    })\n  })\n\n  return {\n    content: data.choices[0].message.content,\n    role: 'assistant'\n  }\n})\n\n// Anthropic, custom AI, or any service\nAgent.processor(customHandler)\n```\n\n### 🛠️ Middleware Pipes\n\nProcess messages through a middleware chain:\n\n```javascript\nimport { Pipe } from '@adalink/spark-chat'\n\n// Log all messages\nPipe.add('ask', async (payload, next) => {\n  console.log('User asked:', payload)\n  return next(payload)\n})\n\n// Validate messages\nPipe.add('ask', async (payload, next) => {\n  if (!payload.content) {\n    throw new Error('Content required')\n  }\n  return next(payload)\n})\n\n// Transform responses\nPipe.add('respond', async (payload, next) => {\n  const transformed = {\n    ...payload,\n    timestamp: Date.now()\n  }\n  return next(transformed)\n})\n```\n\n### ⚡ High Performance\n\n- Shadow DOM (style encapsulation)\n- Event delegation (single listener per component)\n- Lazy loading (load on demand)\n- No virtual DOM overhead\n- Tree-shakeable imports\n\n---\n\n## 🔗 Integração com Spark Ecosystem\n\nO Spark Chat é uma biblioteca de aplicações do Spark Ecosystem, trabalhando em harmonia com outras bibliotecas Spark para criar interfaces de chat reativas e observáveis.\n\n### 📦 Pacotes Relacionados\n\n**[@adalink/spark-std](https://github.com/Adalink-ai/spark_std)** - Biblioteca padrão para desenvolvimento web\n\nUse Spark Std para criar componentes com decorators e utilities:\n\n```javascript\nimport { define, paint } from '@adalink/spark-std/directive'\nimport { html, css } from '@adalink/spark-std/dom'\n\n@define('my-chat')\n@paint(component, style)\nclass MyChat extends HTMLElement {\n  // Component logic\n}\n```\n\n**[@adalink/spark-echo](https://github.com/Adalink-ai/spark_echo)** - Sistema de comunicação reativa entre componentes\n\nUse Spark Echo para adicionar comunicação reativa:\n\n```javascript\nimport Echo from '@adalink/spark-echo'\n\nclass MyChat extends Echo(HTMLElement) {\n  // Reactive event arc functionality\n}\n```\n\n### 💻 Exemplo Completo\n\n```javascript\nimport { define, paint } from '@adalink/spark-std/directive'\nimport { html, css } from '@adalink/spark-std/dom'\nimport { event } from '@adalink/spark-std/event'\nimport Echo from '@adalink/spark-echo'\nimport Chat from '@adalink/spark-chat'\n\n@define('my-app')\n@paint(component, style)\nclass MyApp extends Echo(HTMLElement) {\n  @event.customEvent('chat:sent')\n  handleChatSent(event) {\n    console.log('Chat message sent:', event.detail)\n  }\n}\n```\n\n---\n\n## 🚀 Quick Start\n\n### Installation\n\n```bash\nnpm install @adalink/spark-chat\n# or\nyarn add @adalink/spark-chat\n# or\nbun add @adalink/spark-chat\n```\n\n### Basic Usage\n\n```html\n<!DOCTYPE html>\n<html>\n<head>\n  <title>Spark Chat Example</title>\n</head>\n<body>\n  <ada-chat state=\"opened\"></ada-chat>\n\n  <script type=\"module\">\n    import '@adalink/spark-chat'\n  </script>\n</body>\n</html>\n```\n\n### With AI Agent\n\n```html\n<!DOCTYPE html>\n<html>\n<head>\n  <title>Spark Chat with AI</title>\n</head>\n<body>\n  <ada-chat state=\"opened\"></ada-chat>\n\n  <script type=\"module\">\n    import { Agent } from '@adalink/spark-chat/agent'\n    import '@adalink/spark-chat'\n\n    // Configure AI agent\n    Agent.processor(async (payload) => {\n      const response = await fetch('https://api.openai.com/v1/chat/completions', {\n        method: 'POST',\n        headers: {\n          'Content-Type': 'application/json',\n          'Authorization': `Bearer ${API_KEY}`\n        },\n        body: JSON.stringify({\n          model: 'gpt-4',\n          messages: payload.messages\n        })\n      })\n\n      const data = await response.json()\n      return {\n        content: data.choices[0].message.content,\n        role: 'assistant'\n      }\n    })\n  </script>\n</body>\n</html>\n```\n\n---\n\n## 📦 Package Structure\n\n### Entry Points\n\n| Import | Bundle Size | Use Case |\n|--------|--------------|----------|\n| `@adalink/spark-chat` | ~3.0 KB | Complete chat library |\n| `@adalink/spark-chat/chat` | ~2.5 KB | Chat component only |\n| `@adalink/spark-chat/agent` | ~2.5 KB | AI agent system only |\n| `@adalink/spark-chat/pipe` | ~1.0 KB | Middleware pipes only |\n\n### Imports\n\n```javascript\n// Complete library\nimport '@adalink/spark-chat'\n\n// Chat component\nimport Chat from '@adalink/spark-chat'\n\n// AI Agent\nimport { Agent } from '@adalink/spark-chat/agent'\n\n// Middleware Pipes\nimport { Pipe } from '@adalink/spark-chat/pipe'\n```\n\n---\n\n## 🎨 Customization\n\n### Design Tokens\n\nCustomize via CSS variables:\n\n```html\n<style>\n  :root {\n    --color-primary: #6366f1;\n    --spacing-md: 1rem;\n    --font-family-base: 'Inter', sans-serif;\n    --border-radius-md: 8px;\n  }\n</style>\n\n<script type=\"module\">\n  import '@adalink/spark-chat'\n</script>\n```\n\n### CSS Parts\n\nStyle internal elements with `::part()`:\n\n```css\nada-chat::part(message) {\n  padding: 1.5rem;\n  border-left: 4px solid var(--color-primary);\n}\n\nada-chat::part(input) {\n  border: 2px solid #e2e8f0;\n  border-radius: 12px;\n}\n\nada-chat::part(send-button) {\n  background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);\n}\n```\n\n**Available Parts:**\n- `message` - Message bubbles\n- `input` - Input field\n- `send-button` - Send button\n- `display` - Message display area\n- `header` - Chat header\n- `status` - Status indicators\n\n---\n\n## 🔧 API Reference\n\n### Chat Component\n\n#### Properties\n\n```javascript\nconst chat = document.querySelector('ada-chat')\n\n// State management\nchat.state = 'opened'  // 'closed', 'opened', 'expanded'\n\n// Variant\nchat.variant = 'floating'  // 'floating', 'inline'\n```\n\n#### Methods\n\n```javascript\n// Programmatic control\nchat.open()    // Open chat\nchat.close()   // Close chat\nchat.expand()  // Expand chat\n\n// Static monitoring API\nimport { Chat } from '@adalink/spark-chat'\n\nconst monitor = Chat.monitor(chat)\n\nmonitor.push([\n  { role: 'user', content: 'Hello!' }\n])\n\nmonitor.clear()\n\nmonitor.abort()\n```\n\n#### Events\n\n```javascript\nchat.addEventListener('sent', (event) => {\n  console.log('Message sent:', event.detail)\n})\n\nchat.addEventListener('responded', (event) => {\n  console.log('AI responded:', event.detail)\n})\n\nchat.addEventListener('thinking', (event) => {\n  console.log('AI thinking...')\n})\n```\n\n### Agent API\n\n```javascript\nimport { Agent } from '@adalink/spark-chat/agent'\n\n// Set AI processor\nAgent.processor(async (payload) => {\n  // Process message and return AI response\n  return {\n    content: 'Response text',\n    role: 'assistant'\n  }\n})\n\n// Get current processor\nconst processor = Agent.processor\n```\n\n### Pipe API\n\n```javascript\nimport { Pipe } from '@adalink/spark-chat/pipe'\n\n// Add middleware\nPipe.add('ask', async (payload, next) => {\n  console.log('Processing:', payload)\n  return next(payload)\n})\n\nPipe.add('respond', async (payload, next) => {\n  const transformed = transform(payload)\n  return next(transformed)\n})\n\n// Execute pipe\nconst result = await Pipe.execute('ask', payload)\n```\n\n---\n\n## 📚 Examples\n\n### React Integration\n\n```jsx\nimport '@adalink/spark-chat'\nimport { useEffect, useRef } from 'react'\n\nfunction ChatApp() {\n  const chatRef = useRef(null)\n\n  useEffect(() => {\n    if (chatRef.current) {\n      const monitor = Chat.monitor(chatRef.current)\n      monitor.push([{ role: 'user', content: 'Hello!' }])\n    }\n  }, [])\n\n  return <ada-chat ref={chatRef} state=\"opened\" />\n}\n```\n\n### Vue Integration\n\n```vue\n<template>\n  <ada-chat ref=\"chat\" state=\"opened\" />\n</template>\n\n<script setup>\nimport '@adalink/spark-chat'\nimport { ref, onMounted } from 'vue'\n\nconst chat = ref(null)\n\nonMounted(() => {\n  const monitor = Chat.monitor(chat.value)\n  monitor.push([{ role: 'user', content: 'Hello!' }])\n})\n</script>\n```\n\n### Vanilla JavaScript\n\n```html\n<ada-chat id=\"chat\" state=\"opened\"></ada-chat>\n\n<script type=\"module\">\n  import { Chat } from '@adalink/spark-chat'\n\n  const chat = document.getElementById('chat')\n  const monitor = Chat.monitor(chat)\n\n  monitor.push([{ role: 'user', content: 'Hello!' }])\n\n  chat.addEventListener('responded', (event) => {\n    console.log('AI responded:', event.detail)\n  })\n</script>\n```\n\n---\n\n## 🛠️ Development\n\n### Prerequisites\n\n- Bun (recommended) or Node.js 18+\n- Git\n\n### Setup\n\n```bash\ngit clone https://github.com/Adalink-ai/spark_chat.git\ncd spark_chat\nbun install\n```\n\n### Commands\n\n```bash\n# Development server (http://localhost:5173)\nbun run dev\n\n# Storybook (http://localhost:6006)\nbun run story\n\n# Production build\nbun run build\n\n# Lint and format\nbunx biome check --write packages/\n\n# Type checking\ntsc --noEmit\n```\n\n### Code Standards\n\n- Maximum 50 lines per class\n- Maximum 15 lines per method\n- Cyclomatic complexity ≤ 5\n- No `else` clauses - use guard clauses\n- Use path aliases (`@chat`, `@agent`, `@pipe`)\n- Conventional Commits\n\nSee `ARCHITECTURE.md` for detailed design patterns and principles.\n\n---\n\n## 📖 Documentation\n\n- [ARCHITECTURE.md](ARCHITECTURE.md) - Architecture and design decisions\n- [AUTHORS.md](AUTHORS.md) - Authors and contributors\n- [CONTRIBUTING.md](CONTRIBUTING.md) - Contributing guidelines\n- [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) - Community guidelines\n- [SECURITY.md](SECURITY.md) - Security policies\n- [CHANGELOG.md](CHANGELOG.md) - Version history\n\n---\n\n## 📝 License\n\nApache License 2.0 - see [LICENSE](LICENSE) for details.\n\n---\n\n## 🤝 Contributing\n\nContributions are welcome! Please read our [Contributing Guide](CONTRIBUTING.md) before submitting pull requests.\n\n---\n\n## 🌟 Related Projects\n\n- **[@adalink/spark-std](https://github.com/Adalink-ai/spark_std)** - Standard library for web development\n- **[@adalink/spark-echo](https://github.com/Adalink-ai/spark_echo)** - Reactive web components library\n\n---\n\n## 📞 Support\n\n- 📧 Email: cleber.engineer@gmail.com\n- 🐙 GitHub: [Adalink-ai/spark_chat](https://github.com/Adalink-ai/spark_chat/issues)\n- 💬 Discussions: [GitHub Discussions](https://github.com/Adalink-ai/spark_chat/discussions)\n\n---\n\n**Built with ❤️ by Cleber de Moraes Goncalves** ⚡\n","readmeFilename":"README.md","_rev":"1-51b37b6e1c1a3893e2414e8a505e8aee"}