atoms-widget-sdk

v1.2.0

Published

7 months ago

Atoms Widget SDK for React applications

Downloads

0High
0Medium
0Low

developer-smallestai

atoms react widget sdk embeddable

Atoms Widget SDK

A React-based widget SDK for integrating Atoms AI chat and voice functionality into web applications.

🚀 Current Status

✅ Implemented Features

Chat Functionality: Full chat implementation using atoms-client-sdk
React Component: <AtomsWidget /> component for React/Next.js projects
HTML Embedding: <atoms-widget> custom element for vanilla HTML
TypeScript Support: Full type safety and IntelliSense
Multiple Themes: Light/dark theme support
Customizable UI: Colors, sizes, positioning options
Auto Token Management: Automatic access token retrieval from Atoms API

⏳ Planned Features

Voice Calling: Currently skeleton implementation only
Hybrid Mode: Switch between chat and voice seamlessly
Advanced Customization: More UI customization options

📦 Installation

For React/Next.js Projects

npm install atoms-widget-sdk

import { AtomsWidget } from "atoms-widget-sdk";

function App() {
  return (
    <AtomsWidget
      assistantId="your-assistant-id"
      mode="chat"
      theme="light"
      accentColor="#2d9d9f"
      title="AI Assistant"
    />
  );
}

For HTML/Vanilla JS Projects

<!DOCTYPE html>
<html>
  <head>
    <!-- Include the widget (CSS is automatically injected) -->
    <script src="https://unpkg.com/atoms-widget-sdk/dist/embed/widget.umd.js"></script>
  </head>
  <body>
    <!-- Add the widget -->
    <atoms-widget
      assistant-id="your-assistant-id"
      mode="chat"
      theme="light"
      size="full"
      accent-color="#3B82F6"
      cta-button-color="#1F2937"
      cta-button-text-color="#FFFFFF"
      title="AI Assistant"
      cta-title="Chat with us"
      cta-subtitle="24/7 Support"
      chat-placeholder="How can I help you today?"
    ></atoms-widget>
  </body>
</html>

🔧 Configuration Options

| Property | Type | Default | Description | | ----------------- | ------------------------------------------------------------ | ---------------------- | --------------------------------------- | | assistantId | string | required | Your assistant ID | | mode | "chat" | "voice" | "hybrid" | "chat" | Widget mode (only chat works currently) | | theme | "light" | "dark" | "light" | UI theme | | size | "tiny" | "compact" | "full" | "full" | Widget size | | position | "bottom-right" | "bottom-left" | "top-right" | "top-left" | "bottom-right" | Widget position | | accentColor | string | "#2d9d9f" | Accent color (hex) | | title | string | "Talk with AI" | Widget title | | chatPlaceholder | string | "Type your message..." | Chat input placeholder |

🏗️ Development

Build Commands

# Install dependencies
npm install

# Build React library
npm run build

# Build HTML embedding
npm run build:widget

# Build both
npm run build:all

Project Structure

atoms-widget-sdk/
├── src/
│   ├── components/          # UI components
│   │   ├── AtomsWidget.tsx  # Main widget component
│   │   └── widget/          # UI subcomponents
│   ├── hooks/               # React hooks
│   │   ├── useAtomsWidget.ts # Main orchestrator hook
│   │   ├── useAtomsChat.ts   # Chat functionality
│   │   └── useAtomsCall.ts   # Voice functionality (skeleton)
│   ├── utils/               # Utility functions
│   │   └── apiClient.ts     # API integration
│   └── widget/              # HTML embedding
│       └── index.ts         # Widget loader for HTML
├── dist/                    # Built library
│   ├── index.js            # React library
│   └── embed/              # HTML embedding
│       └── widget.umd.js   # Widget bundle
└── test-chat.html          # Demo page

🔌 API Integration

The widget automatically handles:

Token Management: Fetches access tokens from https://atoms-api.smallest.ai/api/v1/conversation/{mode}
Session Management: Manages connection lifecycle with atoms-client-sdk
Event Handling: Processes transcript, error, and connection events
Message State: Maintains conversation history and typing indicators

🎯 Usage Examples

Chat Mode Demo

Open test-chat.html in your browser to see the chat functionality in action.

React Integration

import { AtomsWidget } from "atoms-widget-sdk";

export default function ChatSupport() {
  return (
    <AtomsWidget
      publicKey={process.env.NEXT_PUBLIC_ATOMS_KEY}
      assistantId={process.env.NEXT_PUBLIC_ASSISTANT_ID}
      mode="chat"
      theme="dark"
      accentColor="#3B82F6"
      ctaTitle="Need Help?"
      ctaSubtitle="Chat with our AI assistant"
      onMessage={(message) => console.log("New message:", message)}
      onError={(error) => console.error("Chat error:", error)}
    />
  );
}

🔄 Architecture

The widget follows a clean architecture:

AtomsWidget: Main UI component
useAtomsWidget: Orchestrates chat and voice hooks
useAtomsChat: Manages chat functionality with atoms-client-sdk
useAtomsCall: Voice functionality (skeleton for future implementation)
apiClient: Handles API communication for token management

📄 License

MIT

🤝 Contributing

This is currently a focused implementation for chat functionality. Voice calling and hybrid mode will be added in future iterations.