npm package: @jutech-devs/agent-sdk
Description: Modern embeddable AI agent chat widget with voice support and payment integration
Latest version: 1.5.3

# @jutech-devs/agent-sdk

Enterprise AI Agent Widget with E-commerce Integration

A powerful, embeddable AI agent widget that handles customer support, product sales, order processing, and payment collection. Perfect for businesses looking to automate customer interactions and boost conversions.

## 🆕 Latest Updates (v1.0.65)

- **User Persistence**: Automatic user info storage across sessions
- **Smart User Collection**: Collects name/email once, remembers forever
- **Per-Agent Storage**: Separate user data for each agent
- **Server Sync**: User info automatically synced with backend

## 🚀 Features

- **💬 Intelligent Conversations** - Context-aware AI that remembers previous interactions
- **🛒 E-commerce Integration** - Complete product catalog and shopping cart functionality
- **💳 Payment Processing** - Secure Paystack integration with address collection
- **📦 Order Management** - Real-time order tracking and status updates
- **📱 Mobile Responsive** - Works perfectly on all devices
- **🎨 Customizable** - Match your brand colors and styling
- **⚡ Real-time** - Streaming responses for instant user feedback
- **🔒 Secure** - Enterprise-grade security and data protection

## Installation

```bash
npm install @jutech-devs/agent-sdk
```

## Quick Start

### React Integration

```jsx
import { AgentWidget } from '@jutech-devs/agent-sdk'

function App() {
  return (
    <div>
      <h1>My Website</h1>
      
      <AgentWidget
        apiKey="sk_your_api_key_here"
        agentId="your_agent_id"
        baseUrl="https://your-api-server.com"
        primaryColor="#6366f1"
        position="bottom-right"
      />
    </div>
  )
}
```

### HTML/JavaScript

```html
<!DOCTYPE html>
<html>
<head>
  <script src="https://unpkg.com/react@18/umd/react.production.min.js"></script>
  <script src="https://unpkg.com/react-dom@18/umd/react-dom.production.min.js"></script>
  <script src="https://unpkg.com/@jutech-devs/agent-sdk/dist/index.umd.js"></script>
</head>
<body>
  <div id="chat-widget"></div>
  
  <script>
    const { AgentWidget } = window.AgentSDK
    
    ReactDOM.render(
      React.createElement(AgentWidget, {
        apiKey: 'sk_your_api_key_here',
        agentId: 'your_agent_id',
        baseUrl: 'https://your-api-server.com',
        primaryColor: '#6366f1'
      }),
      document.getElementById('chat-widget')
    )
  </script>
</body>
</html>
```

## Configuration

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `apiKey` | string | **required** | Your project API key |
| `agentId` | string | **required** | ID of the agent to chat with |
| `baseUrl` | string | `http://localhost:3001` | Your API server URL |
| `user` | object | `undefined` | User info: `{id, name, email}` |
| `onUserUpdate` | function | `undefined` | Callback when user info changes |
| `theme` | `'light' \| 'dark' \| 'auto'` | `'light'` | Widget theme |
| `position` | `'bottom-right' \| 'bottom-left' \| 'top-right' \| 'top-left'` | `'bottom-right'` | Widget position |
| `primaryColor` | string | `'#6366f1'` | Primary brand color |
| `title` | string | `'AI Assistant'` | Widget header title |
| `subtitle` | string | `'How can I help you today?'` | Widget subtitle |
| `placeholder` | string | `'Type your message...'` | Input placeholder |
| `className` | string | `''` | Additional CSS classes |

## E-commerce Features

### Product Management
Your AI agent can showcase products, handle inquiries, and guide customers through the purchase process:

```jsx
// Agent automatically displays products and handles:
// - Product recommendations
// - Price inquiries
// - Feature comparisons
// - Stock availability
// - Add to cart functionality
```

### Payment Processing
Integrated Paystack payment system with:
- Secure payment collection
- Address and delivery information
- Order confirmation
- Payment receipts

### Order Tracking
Customers can track their orders directly through the chat:
- Real-time order status
- Delivery tracking
- Order history
- Support for order issues

## Advanced Usage

### User Persistence

The widget automatically handles user information persistence:

```jsx
// Option 1: Provide user upfront (skips collection)
<AgentWidget
  apiKey="sk_your_api_key"
  agentId="your_agent_id"
  user={{
    id: 'user_123',
    name: 'John Doe',
    email: 'john@example.com'
  }}
  onUserUpdate={(user) => {
    // Called when user info is collected or updated
    console.log('User info updated:', user)
    // Sync with your user management system
  }}
/>

// Option 2: Let widget collect info (remembers for future visits)
<AgentWidget
  apiKey="sk_your_api_key"
  agentId="your_agent_id"
  onUserUpdate={(user) => {
    // Save to your database
    saveUserToDatabase(user)
  }}
/>
```

**How it works:**
- **First visit**: Widget asks for name and email, stores in localStorage
- **Return visits**: Widget loads user from localStorage automatically
- **With user prop**: Widget uses provided data immediately
- **Cross-session**: User data persists across browser sessions
- **Per-agent**: Each agent has separate user storage (`agent_user_${agentId}`)

### Event Handling

```jsx
<AgentWidget
  apiKey="sk_your_api_key"
  agentId="your_agent_id"
  onUserUpdate={(user) => {
    console.log('User updated:', user)
    // Sync with your user system
    updateUserProfile(user)
  }}
  onOrderComplete={(order) => {
    console.log('Order completed:', order)
    // Track conversion in analytics
    analytics.track('order_completed', order)
  }}
  onPaymentSuccess={(payment) => {
    console.log('Payment successful:', payment)
    // Update user's purchase history
  }}
/>
```

## Styling

### Custom Colors

```jsx
<AgentWidget
  primaryColor="#your-brand-color"
  theme="dark"
  className="custom-widget-styles"
/>
```

### CSS Customization

```css
.agent-widget {
  --primary-color: #6366f1;
  --text-color: #1f2937;
  --background-color: #ffffff;
  --border-radius: 12px;
}

.agent-widget.dark {
  --text-color: #f9fafb;
  --background-color: #1f2937;
}
```

## API Integration

The widget works with your backend API to provide:

- **Chat Endpoints**: Real-time messaging with streaming responses
- **Product API**: Dynamic product catalog and inventory
- **Order API**: Order creation, tracking, and management
- **Payment API**: Secure payment processing with Paystack
- **User API**: Customer data and conversation history

## Browser Support

- Chrome 60+
- Firefox 60+
- Safari 12+
- Edge 79+
- Mobile browsers (iOS Safari, Chrome Mobile)

## Security

- API key authentication
- HTTPS-only communication
- XSS protection
- CSRF protection
- PCI DSS compliant payments

## Development

```bash
# Clone the repository
git clone https://github.com/jutech-devs/agent-sdk

# Install dependencies
npm install

# Start development server
npm run dev

# Build for production
npm run build

# Run tests
npm test
```

## Examples

Check out our example implementations:
- [React E-commerce Store](./examples/react-ecommerce)
- [HTML Landing Page](./examples/html-integration)
- [Next.js Application](./examples/nextjs-app)

## Support

- 📧 Email: support@jutech-devs.com
- 📖 Documentation: [docs.jutech-devs.com](https://docs.jutech-devs.com)
- 🐛 Issues: [GitHub Issues](https://github.com/jutech-devs/agent-sdk/issues)

## License

MIT License - see [LICENSE](./LICENSE) for details.

---

Built with ❤️ by [Jutech Devs](https://jutechhub.com)