Simple Assistant

A flexible, event-driven assistant system for frontend applications with support for message queuing, chaining, priority handling, and context-based triggers.

📦 Installation

npm install simple-assistant

📚 Documentation

For complete documentation, API reference, and examples, see the library README.

✨ Features

• 🎯 Priority Queue System - High-priority messages can interrupt or queue behind persistent messages
• ⛓️ Message Chaining - Display multiple related messages sequentially
• 🎮 Context-Aware Triggers - Execute scripts based on application state conditions
• ⏱️ Smart Auto-Close - Configurable auto-close with timer management
• 🔒 Persistent Messages - Mark critical messages as non-interruptible
• 🔄 Script Lifecycle Hooks - Full control over script execution
• 📊 Execution History - Track and analyze script execution patterns
• 🛠️ TypeScript First - Complete type safety

🚀 Quick Start

import { Assistant } from 'simple-assistant'

const assistant = new Assistant({
  initialContext: { isLoggedIn: false }
})

assistant.on('message:triggered', (message, script, messageIndex) => {
  console.log(message.content)
})

assistant.registerScript({
  id: 'welcome',
  name: 'Welcome Message',
  messages: [{ type: 'text', content: 'Welcome!' }],
  trigger: { type: 'immediate' }
})

assistant.start()

🔧 Development

# Install dependencies
pnpm install

# Build library
pnpm build

# Test package locally
npm pack

📖 Key Concepts

Scripts

Scripts define what messages to display, when to display them, and how they behave:

{
  id: 'cart-reminder',
  priority: 10,
  messages: [
    { type: 'text', content: '🛒 Complete your purchase!' }
  ],
  persistent: true,  // Cannot be interrupted
  autoClose: false,  // Must be manually closed
  displayDuration: 5000
}

Message Chaining

Display multiple messages sequentially:

{
  id: 'tutorial',
  messages: [
    { type: 'text', content: 'Step 1: ...' },
    { type: 'text', content: 'Step 2: ...' },
    { type: 'text', content: 'Step 3: ...' }
  ],
  displayDuration: 4000  // Each message shows for 4s
}

Context-Based Triggers

React to application state changes:

{
  id: 'login-prompt',
  trigger: { type: 'conditional' },
  triggerConditions: {
    operator: 'equals',
    contextKey: 'isLoggedIn',
    expectedValue: false,
    evaluate: (ctx) => ctx.get('isLoggedIn') === false
  }
}

🏗️ Project Structure

simple-assistant/
├── src/assistant/         # 📦 Library source code
│   ├── core/             # Core classes (Assistant, RuntimeProcessor, ScriptManager)
│   ├── interfaces/       # TypeScript interfaces
│   ├── models/           # Data models
│   ├── types/            # Type definitions
│   ├── utils/            # Utilities (EventEmitter, Logger)
│   ├── index.ts          # Main entry point
│   └── README.md         # Complete documentation
├── dist/                 # Built library (after npm run build)
├── vite.lib.config.ts    # Library build configuration
├── tsconfig.lib.json     # TypeScript configuration
└── package.json

📄 License

MIT © [Your Name]

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

🔗 Links

• Full Documentation
• npm Package
• GitHub Repository
• Issue Tracker