@jad.mahmoud/cooriroo-agent

v0.0.51

Published

5 months ago

> **Your intelligent conversational companion for seamless customer support and assistance**

0High
0Medium
0Low

cooriroo

abdellatif-devtech

dan_mic

🤖 Cooriroo AI Agent

Your intelligent conversational companion for seamless customer support and assistance

A modern, feature-rich AI chatbot widget built with React, TypeScript, and Tailwind CSS. Designed to provide intelligent conversational experiences with configurable positioning, real-time messaging, and seamless integration capabilities.

✨ Features

🎯 Core Capabilities

Intelligent Conversations - Powered by AI for natural, contextual responses
Real-time Messaging - WebSocket-based instant communication
Multi-language Support - Internationalization ready
Voice Integration - Speech-to-text and text-to-speech capabilities
File Upload Support - Handle images, documents, and media files

🎨 UI/UX Excellence

Responsive Design - Works perfectly on desktop and mobile
Configurable Positioning - Customize widget placement with pixel-perfect control
Smooth Animations - Framer Motion powered transitions
Dark/Light Themes - Adaptive styling with Tailwind CSS
Accessibility First - WCAG compliant and screen reader friendly

🔧 Developer Experience

TypeScript First - Full type safety and IntelliSense support
Modular Architecture - Clean, maintainable component structure
Hot Reload - Lightning-fast development with Vite
ESLint + Prettier - Consistent code formatting
Comprehensive Testing - Built for reliability

🚀 Quick Start

Installation

npm install @jad.mahmoud/cooriroo-agent

Basic Usage

<!DOCTYPE html>
<html>
<head>
    <title>My App</title>
</head>
<body>
    <div id="app"></div>
    
    <!-- Include the chatbot script -->
    <script type="module" src="https://unpkg.com/@jad.mahmoud/cooriroo-agent@latest/dist-embed/pilot.js"></script>
    
    <script>
        // Initialize the chatbot
        window.initAiCoPilot({
            token: 'your-auth-token',
            apiUrl: 'https://api.your-domain.com',
            apiKey: 'your-openai-key',
            initialMessage: 'Hello! How can I help you today?',
            triggerSelector: '#chat-trigger', // Optional: custom trigger element
            offsetBottom: '20px',  // Custom positioning
            offsetRight: '20px',   // Custom positioning
        });
    </script>
</body>
</html>

⚙️ Configuration Options

Essential Options

| Option | Type | Required | Description | |--------|------|----------|-------------| | token | string | ✅ | Authentication token for your service | | apiUrl | string | ✅ | Base URL for your API endpoints | | apiKey | string | ✅ | OpenAI API key for AI responses | | initialMessage | string | ✅ | First message shown to users |

Positioning & Layout

| Option | Type | Default | Description | |--------|------|---------|-------------| | offsetBottom | string | "10px" | Bottom offset for widget positioning | | offsetRight | string | "20px" | Right offset for widget positioning | | triggerSelector | string | - | CSS selector for custom trigger element | | defaultOpen | boolean | false | Whether widget starts open |

Customization

| Option | Type | Description | |--------|------|-------------| | user.name | string | Custom user name display | | user.avatarUrl | string | Custom user avatar | | bot.name | string | Custom bot name | | bot.avatarUrl | string | Custom bot avatar | | language | LangType | Interface language | | debug | boolean | Enable debug mode |

Advanced Options

| Option | Type | Description | |--------|------|-------------| | headers | Record<string, string> | Custom HTTP headers | | queryParams | Record<string, string> | URL query parameters | | socketUrl | string | WebSocket connection URL | | warnBeforeClose | boolean | Show warning before closing | | onClose | () => void | Custom close handler | | onHandoff | (handoff) => void | Human handoff handler |

🎨 Customization Examples

Minimal Setup

window.initAiCoPilot({
    token: 'your-token',
    apiUrl: 'https://api.example.com',
    apiKey: 'sk-...',
    initialMessage: 'Hi there! 👋',
});

Custom Positioning

window.initAiCoPilot({
    // ... basic config
    offsetBottom: '0px',    // Stick to bottom
    offsetRight: '0px',     // Stick to right
});

Custom Trigger

// Add a custom button
document.body.innerHTML += '<button id="my-chat-btn">💬 Chat with us</button>';

window.initAiCoPilot({
    // ... basic config
    triggerSelector: '#my-chat-btn',
    defaultOpen: false,
});

Branded Experience

window.initAiCoPilot({
    // ... basic config
    user: {
        name: 'John Doe',
        avatarUrl: 'https://example.com/avatar.jpg'
    },
    bot: {
        name: 'Cooriroo Assistant',
        avatarUrl: 'https://example.com/bot-avatar.png'
    },
    initialMessage: 'Welcome to Cooriroo! How can I assist you today?'
});

🛠️ Development

Prerequisites

Node.js 18+
npm or pnpm

Setup

# Clone the repository
git clone <repository-url>
cd chatbot-frontend

# Install dependencies
npm install

# Start development server
npm run dev

Build Commands

# Build embed version (for unpkg)
npm run build:embed

# Build library version
npm run build:lib

# Clean build artifacts
npm run clean

# Lint code
npm run lint

# Preview production build
npm run preview

Project Structure

chatbot-frontend/
├── lib/                    # Main library code
│   ├── components/         # Reusable UI components
│   ├── contexts/          # React contexts
│   ├── hooks/             # Custom React hooks
│   ├── screens/           # Screen components
│   ├── types/             # TypeScript type definitions
│   ├── utils/             # Utility functions
│   ├── CopilotWidget.tsx  # Main widget component
│   └── Root.tsx           # Root component
├── src/                   # Source files
│   ├── main.tsx          # Entry point
│   └── utils.ts          # Utilities
├── styles/               # Global styles
├── dist/                 # Library build output
├── dist-embed/           # Embed build output
└── package.json

🔧 API Reference

Core Components

`CopilotWidget`

The main chat widget component with configurable positioning and behavior.

interface CopilotWidgetProps {
  triggerSelector?: string;
  __isEmbedded?: boolean;
  offsetBottom?: string;
  offsetRight?: string;
}

`Root`

The root component that provides context and styling.

interface RootProps {
  children: React.ReactNode;
  options: ConfigDataContextType;
  containerProps?: React.HTMLAttributes<HTMLDivElement>;
}

Hooks

`useWidget`

Manages widget state and interactions.

const { open, toggleWidget, isFullScreen, hover, setHover } = useWidget();

🚀 Deployment

Publishing to npm

# Update version
npm version patch

# Publish
npm publish

Using with unpkg

The widget is automatically available via unpkg:

<script src="https://unpkg.com/@jad.mahmoud/cooriroo-agent@latest/dist-embed/pilot.js"></script>

🤝 Contributing

We welcome contributions! Please see our Contributing Guidelines for details.

Development Workflow

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

📝 Changelog

See CHANGELOG.md for a detailed history of changes.

Recent Updates

v0.0.50 - Added configurable widget positioning
v0.0.49 - Initial release with core functionality

📄 License

This project is licensed under the ISC License - see the LICENSE file for details.

🆘 Support

Documentation: Read the docs
Issues: GitHub Issues
Discussions: GitHub Discussions
Email: [email protected]

🙏 Acknowledgments

Built with React
Styled with Tailwind CSS
Powered by Vite
Icons by Lucide React