@foisit/angular-wrapper 2.0.0 → 2.1.1

package/README.md

@@ -1,9 +1,41 @@
 # @foisit/angular-wrapper
 
-Power your Angular apps with an AI-driven text assistant.
+[![npm version](https://img.shields.io/npm/v/@foisit/angular-wrapper.svg)](https://www.npmjs.com/package/@foisit/angular-wrapper)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+> **The AI-Powered Conversational Assistant for Angular Applications**
+
+Transform your Angular app into an intelligent, voice-ready platform. Foisit provides a drop-in AI layer that understands natural language, manages multi-step workflows, and executes actions—all with zero backend required.
 
 > [!NOTE]
-> 🎙️ **Coming Soon**: Voice recognition and responses are planned for a future release. Current support is focused on text-based interactions and AI intent matching.
+> 🎙️ **Voice Support Status**: Voice recognition and responses are currently in development and will be released in a future update. The current version focuses on high-performance text-based interactions and AI intent matching.
+
+---
+
+## 📋 Table of Contents
+
+- [Features](#-features)
+- [Installation](#-installation)
+- [Quick Start](#-quick-start)
+- [Core Concepts](#-core-concepts)
+- [API Reference](#-api-reference)
+- [Advanced Usage](#-advanced-usage)
+- [Examples](#-examples)
+- [TypeScript Support](#-typescript-support)
+- [Best Practices](#-best-practices)
+
+---
+
+## ✨ Features
+
+- **🧠 Natural Language Understanding** - AI-powered intent matching using GPT-4o mini (proxied securely)
+- **📝 Smart Slot Filling** - Auto-generates forms for missing parameters
+- **⚠️ Critical Action Protection** - Built-in confirmation dialogs for dangerous operations
+- **🎨 Premium UI** - Glassmorphic overlay with dark/light mode support
+- **🔒 Zero Backend Required** - Secure proxy architecture keeps API keys server-side
+- **⚡ Angular Native** - Uses Dependency Injection, Signals, and RxJS
+- **🎯 Type-Safe** - Full TypeScript support with comprehensive types
+- **📱 Responsive** - Works flawlessly on desktop and mobile
 
 ---
 
@@ -13,29 +45,38 @@ Power your Angular apps with an AI-driven text assistant.
 npm install @foisit/angular-wrapper
 ```
 
----
+### Peer Dependencies
 
-## 🔧 Basic Setup
+```json
+{
+  "@angular/core": "^17.0.0 || ^18.0.0",
+  "@angular/common": "^17.0.0 || ^18.0.0"
+}
+```
 
-### 1. Import `AssistantModule`
+---
+
+## 🏁 Quick Start
 
-Add `AssistantModule.forRoot()` to your `app.config.ts` (for Standalone) or `app.module.ts`.
+### Step 1: Import the Module
 
-#### `app.config.ts` (Standalone)
+#### For Standalone Apps (Recommended)
 
 ```typescript
+// app.config.ts
+import { ApplicationConfig, importProvidersFrom } from '@angular/core';
 import { AssistantModule } from '@foisit/angular-wrapper';
 
 export const appConfig: ApplicationConfig = {
   providers: [
     importProvidersFrom(
       AssistantModule.forRoot({
+        introMessage: 'Welcome! How can I assist you today?',
         enableSmartIntent: true,
-        introMessage: 'Welcome! How can I help?',
         commands: [
           {
-            command: 'profile',
-            action: () => router.navigate(['/profile']),
+            command: 'navigate to profile',
+            action: () => console.log('Navigating to profile...'),
           },
         ],
       })
@@ -44,55 +85,569 @@ export const appConfig: ApplicationConfig = {
 };
 ```
 
+#### For Module-Based Apps
+
+```typescript
+// app.module.ts
+import { NgModule } from '@angular/core';
+import { AssistantModule } from '@foisit/angular-wrapper';
+
+@NgModule({
+  imports: [
+    AssistantModule.forRoot({
+      introMessage: 'Welcome! How can I assist you today?',
+      commands: [
+        /* your commands */
+      ],
+    }),
+  ],
+})
+export class AppModule {}
+```
+
+### Step 2: Use the Service
+
+```typescript
+// my-component.ts
+import { Component } from '@angular/core';
+import { AssistantService } from '@foisit/angular-wrapper';
+
+@Component({
+  selector: 'app-my-component',
+  template: ` <button (click)="openAssistant()">Open Assistant</button> `,
+})
+export class MyComponent {
+  constructor(private assistant: AssistantService) {}
+
+  openAssistant() {
+    this.assistant.toggle();
+  }
+}
+```
+
 ---
 
-## 🛡️ Critical Actions
+## 🎯 Core Concepts
+
+### 1. Commands
 
-Commands marked as `critical` will automatically trigger a confirmation flow in the UI.
+Commands are the building blocks of your assistant. Each command represents an action users can trigger through natural language.
 
 ```typescript
-const config = {
-  commands: [
+{
+  command: 'delete account',
+  description: 'Permanently delete user account',
+  action: () => this.accountService.delete()
+}
+```
+
+### 2. Parameters (Slot Filling)
+
+Define parameters and Foisit will automatically generate forms to collect them:
+
+```typescript
+{
+  command: 'create user',
+  description: 'Create a new user account',
+  parameters: [
+    { name: 'username', type: 'string', required: true },
+    { name: 'email', type: 'string', required: true },
+    { name: 'age', type: 'number', required: false }
+  ],
+  action: (params) => this.userService.create(params)
+}
+```
+
+**Supported Parameter Types:**
+
+- `string` - Text input
+- `number` - Numeric input
+- `date` - Date picker
+- `select` - Dropdown (static or async options)
+
+### 3. Critical Actions
+
+Protect dangerous operations with automatic confirmation dialogs:
+
+```typescript
+{
+  command: 'delete all data',
+  critical: true, // 🔒 Requires confirmation
+  description: 'Permanently delete all application data',
+  action: async () => {
+    await this.dataService.deleteAll();
+    return '✅ All data deleted successfully.';
+  }
+}
+```
+
+### 4. Select Parameters (Static)
+
+Provide predefined options:
+
+```typescript
+{
+  command: 'set theme',
+  parameters: [{
+    name: 'theme',
+    type: 'select',
+    options: [
+      { label: 'Light Mode', value: 'light' },
+      { label: 'Dark Mode', value: 'dark' },
+      { label: 'Auto', value: 'auto' }
+    ]
+  }],
+  action: (params) => this.themeService.set(params.theme)
+}
+```
+
+### 5. Dynamic Select Parameters
+
+Load options from APIs:
+
+```typescript
+{
+  command: 'assign to user',
+  parameters: [{
+    name: 'userId',
+    type: 'select',
+    getOptions: async () => {
+      const users = await this.userService.getAll();
+      return users.map(u => ({
+        label: `${u.name} (${u.email})`,
+        value: u.id
+      }));
+    }
+  }],
+  action: (params) => this.taskService.assign(params.userId)
+}
+```
+
+---
+
+## 📘 API Reference
+
+### `AssistantService`
+
+Injectable service for programmatic control:
+
+#### Methods
+
+##### `toggle(onSubmit?, onClose?)`
+
+Opens or closes the assistant overlay.
+
+```typescript
+// Basic usage
+this.assistant.toggle();
+
+// With callbacks
+this.assistant.toggle(
+  (userInput) => console.log('User said:', userInput),
+  () => console.log('Assistant closed')
+);
+```
+
+##### `addCommand(command, action?)`
+
+Dynamically add a command at runtime.
+
+```typescript
+// Add a simple command
+this.assistant.addCommand('refresh data', () => {
+  this.dataService.refresh();
+  return 'Data refreshed!';
+});
+
+// Add a command with full config
+this.assistant.addCommand({
+  command: 'export report',
+  description: 'Export data as PDF',
+  parameters: [
     {
-      command: 'delete post',
-      critical: true,
-      description: 'permanently delete this post',
-      action: () => this.postService.delete(),
+      name: 'format',
+      type: 'select',
+      options: [
+        { label: 'PDF', value: 'pdf' },
+        { label: 'Excel', value: 'xlsx' },
+      ],
     },
   ],
-};
+  action: async (params) => {
+    await this.reportService.export(params.format);
+    return `Report exported as ${params.format}`;
+  },
+});
+```
+
+##### `removeCommand(commandPhrase)`
+
+Remove a registered command.
+
+```typescript
+this.assistant.removeCommand('delete account');
+```
+
+##### `getCommands()`
+
+Get list of all registered command names.
+
+```typescript
+const commands = this.assistant.getCommands();
+console.log('Available commands:', commands);
 ```
 
 ---
 
-## 🧠 AI Intent Matching
+## 🔧 Configuration Options
+
+### `AssistantConfig`
 
-Enable `enableSmartIntent: true` to allow the assistant to understand natural language.
+```typescript
+interface AssistantConfig {
+  // Activation keyword (optional)
+  activationCommand?: string;
+
+  // Welcome message shown when assistant opens
+  introMessage?: string;
+
+  // Response for unrecognized inputs
+  fallbackResponse?: string;
 
-**User says:** _"Go to my profile"_  
-**Matched Command:** `{ command: 'profile', keywords: ['account', 'user settings'], ... }`
+  // Enable AI-powered natural language understanding
+  enableSmartIntent?: boolean;
+
+  // Input field placeholder text
+  inputPlaceholder?: string;
+
+  // List of commands
+  commands: AssistantCommand[];
+
+  // Floating button configuration
+  floatingButton?: {
+    visible?: boolean;
+    tooltip?: string;
+    customHtml?: string;
+    position?: { bottom: string; right: string };
+  };
+}
+```
 
 ---
 
-## 🛠️ Service Usage: `AssistantService`
+## 🎨 Advanced Usage
 
-Interact with the assistant dynamically from your components.
+### Example 1: Multi-Step Booking System
 
 ```typescript
+import { Component } from '@angular/core';
 import { AssistantService } from '@foisit/angular-wrapper';
 
-@Component({...})
+@Component({
+  selector: 'app-booking',
+  template: `<button (click)="setupBooking()">Enable Booking</button>`,
+})
+export class BookingComponent {
+  constructor(private assistant: AssistantService, private bookingService: BookingService) {}
+
+  setupBooking() {
+    this.assistant.addCommand({
+      command: 'book appointment',
+      description: 'Schedule a new appointment',
+      parameters: [
+        {
+          name: 'service',
+          description: 'Type of service',
+          type: 'select',
+          required: true,
+          getOptions: async () => {
+            const services = await this.bookingService.getServices();
+            return services.map((s) => ({
+              label: s.name,
+              value: s.id,
+            }));
+          },
+        },
+        {
+          name: 'date',
+          description: 'Preferred date',
+          type: 'date',
+          required: true,
+        },
+        {
+          name: 'notes',
+          description: 'Additional notes',
+          type: 'string',
+          required: false,
+        },
+      ],
+      action: async (params) => {
+        const booking = await this.bookingService.create(params);
+        return {
+          type: 'success',
+          message: `✅ Appointment booked for ${params.date}!`,
+        };
+      },
+    });
+  }
+}
+```
+
+### Example 2: E-Commerce Product Search
+
+```typescript
+this.assistant.addCommand({
+  command: 'search products',
+  parameters: [
+    { name: 'query', type: 'string', required: true },
+    {
+      name: 'category',
+      type: 'select',
+      required: false,
+      options: [
+        { label: 'Electronics', value: 'electronics' },
+        { label: 'Clothing', value: 'clothing' },
+        { label: 'Books', value: 'books' },
+      ],
+    },
+    {
+      name: 'minPrice',
+      type: 'number',
+      required: false,
+    },
+  ],
+  action: async (params) => {
+    const results = await this.productService.search(params);
+    this.router.navigate(['/products'], {
+      queryParams: { q: params.query },
+    });
+    return `Found ${results.length} products matching "${params.query}"`;
+  },
+});
+```
+
+### Example 3: Form Validation with Error Handling
+
+```typescript
+this.assistant.addCommand({
+  command: 'create account',
+  parameters: [
+    { name: 'email', type: 'string', required: true },
+    { name: 'password', type: 'string', required: true },
+    { name: 'age', type: 'number', required: true },
+  ],
+  action: async (params) => {
+    // Validation
+    if (params.age < 18) {
+      return {
+        type: 'error',
+        message: '❌ You must be 18 or older to create an account.',
+      };
+    }
+
+    if (!params.email.includes('@')) {
+      return {
+        type: 'error',
+        message: '❌ Please provide a valid email address.',
+      };
+    }
+
+    // Create account
+    try {
+      await this.authService.register(params);
+      return {
+        type: 'success',
+        message: '✅ Account created successfully! You can now log in.',
+      };
+    } catch (error) {
+      return {
+        type: 'error',
+        message: `❌ Registration failed: ${error.message}`,
+      };
+    }
+  },
+});
+```
+
+---
+
+## 📝 TypeScript Support
+
+### Full Type Definitions
+
+```typescript
+import { AssistantCommand, InteractiveResponse } from '@foisit/core';
+
+// Type-safe command definition
+const myCommand: AssistantCommand = {
+  command: 'update settings',
+  description: 'Update user preferences',
+  parameters: [
+    {
+      name: 'theme',
+      type: 'select',
+      required: true,
+      options: [
+        { label: 'Light', value: 'light' },
+        { label: 'Dark', value: 'dark' },
+      ],
+    },
+  ],
+  action: async (params: { theme: string }): Promise<InteractiveResponse> => {
+    await this.settingsService.update(params.theme);
+    return {
+      type: 'success',
+      message: `Theme updated to ${params.theme}`,
+    };
+  },
+};
+```
+
+---
+
+## 🎯 Best Practices
+
+### 1. Command Naming
+
+✅ **Good:**
+
+- "create user"
+- "delete account"
+- "export report"
+
+❌ **Avoid:**
+
+- "CreateUser" (not natural)
+- "usr_del" (not descriptive)
+- "do the thing" (too vague)
+
+### 2. Descriptions
+
+Always provide clear descriptions for AI matching:
+
+```typescript
+{
+  command: 'reset password',
+  description: 'Reset the user password and send recovery email',
+  // AI can match: "forgot my password", "can't log in", etc.
+}
+```
+
+### 3. Error Handling
+
+Return user-friendly error messages:
+
+```typescript
+action: async (params) => {
+  try {
+    await this.api.call(params);
+    return { type: 'success', message: '✅ Done!' };
+  } catch (error) {
+    return {
+      type: 'error',
+      message: `❌ Something went wrong: ${error.message}`,
+    };
+  }
+};
+```
+
+### 4. Use Signals for Reactive State
+
+```typescript
+import { signal } from '@angular/core';
+
 export class MyComponent {
-  constructor(private assistant: AssistantService) {}
+  theme = signal<'light' | 'dark'>('light');
 
-  addCommand() {
-    this.assistant.addCommand('clear', () => this.clearAll());
+  constructor(private assistant: AssistantService) {
+    this.assistant.addCommand('toggle theme', () => {
+      const newTheme = this.theme() === 'light' ? 'dark' : 'light';
+      this.theme.set(newTheme);
+      return `Theme switched to ${newTheme}`;
+    });
   }
 }
 ```
 
 ---
 
-## 👋 Gesture Activation
+## 🧪 Testing
+
+### Unit Testing Commands
+
+```typescript
+import { TestBed } from '@angular/core/testing';
+import { AssistantService } from '@foisit/angular-wrapper';
+
+describe('AssistantService', () => {
+  let service: AssistantService;
+
+  beforeEach(() => {
+    TestBed.configureTestingModule({
+      imports: [AssistantModule.forRoot({ commands: [] })],
+    });
+    service = TestBed.inject(AssistantService);
+  });
+
+  it('should add and execute command', () => {
+    let executed = false;
+    service.addCommand('test', () => {
+      executed = true;
+    });
+
+    // Trigger command execution
+    service.toggle();
+    // Test execution...
+
+    expect(executed).toBe(true);
+  });
+});
+```
+
+---
+
+## � Related Packages
+
+- **[@foisit/core](../core)** - Core engine (auto-installed)
+- **[@foisit/react-wrapper](../react-wrapper)** - React integration
+- **[@foisit/vue-wrapper](../vue-wrapper)** - Vue integration
+
+---
+
+## 🐛 Troubleshooting
+
+### Assistant not appearing
+
+Ensure `AssistantModule.forRoot()` is imported in your app configuration and double-tap the floating button.
+
+### Commands not executing
+
+Check browser console for errors. Ensure `action` functions are returning values or promises.
+
+### TypeScript errors
+
+Make sure you're using Angular 17+ and have `@angular/core` installed.
+
+---
+
+## 📄 License
+
+MIT © [Foisit](https://github.com/boluwatifee4/foisit)
+
+---
+
+## 🤝 Contributing
+
+Contributions are welcome! Please read our [Contributing Guide](../../CONTRIBUTING.md) first.
+
+---
+
+## 📬 Support
+
+- 📧 Email: support@foisit.com
+- 💬 Discord: [Join our community](https://discord.gg/foisit)
+- 🐛 Issues: [GitHub Issues](https://github.com/boluwatifee4/foisit/issues)
+
+---
 
-Once integrated, a subtle **"Powered by Foisit"** watermark appears. **Double-click** it to open the chat overlay.
+**Made with ❤️ by the Foisit Team**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@foisit/angular-wrapper",
-  "version": "2.0.0",
+  "version": "2.1.1",
   "peerDependencies": {
     "@angular/common": "^19.0.0",
     "@angular/core": "^19.0.0"