@foisit/angular-wrapper 1.2.0 → 2.1.1

package/README.md

@@ -1,216 +1,653 @@
-# 🎙️ Foisit Angular Wrapper: Speak, and it’s Done.
+# @foisit/angular-wrapper
 
-The **Foisit Angular Wrapper** brings voice interactivity to your Angular apps with the power of the **Foisit Assistant**. Imagine saying "background red" and watching your app come alive—now that's ✨magic✨!
+[![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)
 
-### **Why Foisit Angular Wrapper?**
+> **The AI-Powered Conversational Assistant for Angular Applications**
 
-- 🧩 **Dynamic Commands**: Add or remove commands on the fly.
-- 🎨 **Visual Feedback**: Show visual cues when the assistant is active.
-- 🚀 **Effortless Integration**: Set up voice commands in minutes with minimal code.
-- 🗣️ **Voice Feedback**: Interactive voice responses make the assistant engaging.
-- 🔄 **Double Activation**: Activate or put the assistant to sleep with a double-tap.
+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.
 
-### 🌐 **Live Demo**
+> [!NOTE]
+> 🎙️ **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.
 
-🎉 [Test the Angular Assistant here!](https://ng-foisit-demo.netlify.app/)
+---
+
+## 📋 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)
 
 ---
 
-## 🚀 Installation
+## ✨ 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
+
+---
 
-Get started by installing the library:
+## 🚀 Installation
 
 ```bash
 npm install @foisit/angular-wrapper
 ```
 
-or
+### Peer Dependencies
 
-```bash
-yarn add @foisit/angular-wrapper
+```json
+{
+  "@angular/core": "^17.0.0 || ^18.0.0",
+  "@angular/common": "^17.0.0 || ^18.0.0"
+}
 ```
 
 ---
 
-## 🔧 Setup
+## 🏁 Quick Start
+
+### Step 1: Import the Module
 
-Here's how you can integrate the Foisit Assistant into your Angular app in just a few steps:
+#### For Standalone Apps (Recommended)
 
-### Step 1: Import the `AssistantModule`
+```typescript
+// app.config.ts
+import { ApplicationConfig, importProvidersFrom } from '@angular/core';
+import { AssistantModule } from '@foisit/angular-wrapper';
 
-#### Using `forRoot` in `app.module.ts`
+export const appConfig: ApplicationConfig = {
+  providers: [
+    importProvidersFrom(
+      AssistantModule.forRoot({
+        introMessage: 'Welcome! How can I assist you today?',
+        enableSmartIntent: true,
+        commands: [
+          {
+            command: 'navigate to profile',
+            action: () => console.log('Navigating to profile...'),
+          },
+        ],
+      })
+    ),
+  ],
+};
+```
+
+#### For Module-Based Apps
 
 ```typescript
+// app.module.ts
 import { NgModule } from '@angular/core';
-import { BrowserModule } from '@angular/platform-browser';
-import { AppComponent } from './app.component';
 import { AssistantModule } from '@foisit/angular-wrapper';
 
 @NgModule({
-  declarations: [AppComponent],
   imports: [
-    BrowserModule,
     AssistantModule.forRoot({
-      activationCommand: 'John',
-      fallbackResponse: 'Sorry, I didn’t understand that.',
+      introMessage: 'Welcome! How can I assist you today?',
       commands: [
-        { command: 'show profile', action: () => console.log('Showing profile...') },
-        { command: 'log out', action: () => console.log('Logging out...') },
+        /* your commands */
       ],
     }),
   ],
-  bootstrap: [AppComponent],
 })
 export class AppModule {}
 ```
 
-#### Or Using `app.config.ts` (Latest Versions)
+### Step 2: Use the Service
 
 ```typescript
-import { ApplicationConfig, provideZoneChangeDetection, importProvidersFrom } from '@angular/core';
-import { provideRouter } from '@angular/router';
-import { appRoutes } from './app.routes';
-import { AssistantModule } from '@foisit/angular-wrapper';
+// my-component.ts
+import { Component } from '@angular/core';
+import { AssistantService } from '@foisit/angular-wrapper';
 
-export const appConfig: ApplicationConfig = {
-  providers: [
-    provideZoneChangeDetection({ eventCoalescing: true }),
-    provideRouter(appRoutes),
-    importProvidersFrom(
-      AssistantModule.forRoot({
-        activationCommand: 'John',
-        fallbackResponse: 'Sorry, I didn’t understand that.',
-        commands: [
-          { command: 'show profile', action: () => console.log('Showing profile...') },
-          { command: 'log out', action: () => console.log('Logging out...') },
-        ],
-      })
-    ),
+@Component({
+  selector: 'app-my-component',
+  template: ` <button (click)="openAssistant()">Open Assistant</button> `,
+})
+export class MyComponent {
+  constructor(private assistant: AssistantService) {}
+
+  openAssistant() {
+    this.assistant.toggle();
+  }
+}
+```
+
+---
+
+## 🎯 Core Concepts
+
+### 1. Commands
+
+Commands are the building blocks of your assistant. Each command represents an action users can trigger through natural language.
+
+```typescript
+{
+  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)
+}
 ```
 
 ---
 
-### Step 2: Interact with the Service 🗣️
+## 📘 API Reference
 
-Define and remove voice commands and inject the `AssistantService` into your components, start the party by calling `startListening()`.
+### `AssistantService`
 
-#### `app.component.ts`
+Injectable service for programmatic control:
+
+#### Methods
+
+##### `toggle(onSubmit?, onClose?)`
+
+Opens or closes the assistant overlay.
 
 ```typescript
-import { Component, signal } from '@angular/core';
+// 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: [
+    {
+      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);
+```
+
+---
+
+## 🔧 Configuration Options
+
+### `AssistantConfig`
+
+```typescript
+interface AssistantConfig {
+  // Activation keyword (optional)
+  activationCommand?: string;
+
+  // Welcome message shown when assistant opens
+  introMessage?: string;
+
+  // Response for unrecognized inputs
+  fallbackResponse?: string;
+
+  // 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 };
+  };
+}
+```
+
+---
+
+## 🎨 Advanced Usage
+
+### Example 1: Multi-Step Booking System
+
+```typescript
+import { Component } from '@angular/core';
 import { AssistantService } from '@foisit/angular-wrapper';
 
 @Component({
-  selector: 'app-root',
-  templateUrl: './app.component.html',
-  styleUrls: ['./app.component.scss'],
+  selector: 'app-booking',
+  template: `<button (click)="setupBooking()">Enable Booking</button>`,
 })
-export class AppComponent {
-  title = 'Angular Assistant Demo';
-  color = signal('transparent'); // Reactive color signal
-
-  constructor(private assistantService: AssistantService) {
-    // Define voice commands
-    this.assistantService.addCommand('background red', () => {
-      this.color.set('red');
+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}!`,
+        };
+      },
     });
+  }
+}
+```
 
-    this.assistantService.addCommand('remove background', () => {
-      this.color.set('transparent');
-    });
+### Example 2: E-Commerce Product Search
 
-    this.assistantService.addCommand('sleep', () => {
-      this.assistantService.stopListening();
+```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}"`;
+  },
+});
+```
 
-    // Start listening immediately
-    this.assistantService.startListening();
-  }
-}
+### 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}`,
+      };
+    }
+  },
+});
 ```
 
 ---
 
-### Step 3: Craft the UI 🎨
+## 📝 TypeScript Support
 
-Create a clean UI to showcase your assistant's magic.
+### Full Type Definitions
 
-#### `app.component.html`
-
-```html
-<div
-  class="content-container"
-  [ngStyle]="{
-    'background-color': color(),
-    'padding': '20px'
-  }"
->
-  <h1>🧙‍♂️ Angular Assistant Demo</h1>
-  <p>Say the magic words to see the assistant in action:</p>
-  <ul>
-    <li>🟥 Say <strong>"background red"</strong> to make the background red.</li>
-    <li>🔄 Say <strong>"remove background"</strong> to reset the background.</li>
-    <li>😴 Say <strong>"sleep"</strong> to put the assistant to rest.</li>
-  </ul>
-  <p>🎨 Current Background: <strong>{{ color() }}</strong></p>
-</div>
+```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}`,
+    };
+  },
+};
 ```
 
 ---
 
-### Step 4: Run the App 🏃
+## 🎯 Best Practices
 
-Start your Angular app and watch the magic happen! ✨
+### 1. Command Naming
 
-```bash
-ng serve
+✅ **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 {
+  theme = signal<'light' | 'dark'>('light');
+
+  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}`;
+    });
+  }
+}
 ```
 
 ---
 
-## 🛠️ API Reference
+## 🧪 Testing
 
-### `AssistantConfig`
+### Unit Testing Commands
 
-Configure your assistant's behavior with this object.
+```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...
 
-| Property            | Type     | Description                                       |
-| ------------------- | -------- | ------------------------------------------------- |
-| `activationCommand` | `string` | The keyword to wake the assistant.                |
-| `fallbackResponse`  | `string` | The message when a command isn’t recognized.      |
-| `commands`          | `Array`  | A list of `{ command: string, action: Function }` |
+    expect(executed).toBe(true);
+  });
+});
+```
 
 ---
 
-### 🔑 Service Methods
+## � Related Packages
 
-| Method           | Description                             |
-| ---------------- | --------------------------------------- |
-| `addCommand`     | Dynamically add a new command.          |
-| `removeCommand`  | Remove an existing command dynamically. |
-| `startListening` | Start listening for voice commands.     |
-| `stopListening`  | Stop listening for voice commands.      |
+- **[@foisit/core](../core)** - Core engine (auto-installed)
+- **[@foisit/react-wrapper](../react-wrapper)** - React integration
+- **[@foisit/vue-wrapper](../vue-wrapper)** - Vue integration
 
 ---
 
-## 🌟 Features
+## 🐛 Troubleshooting
+
+### Assistant not appearing
+
+Ensure `AssistantModule.forRoot()` is imported in your app configuration and double-tap the floating button.
+
+### Commands not executing
 
-- 🧩 **Dynamic Commands**: Add or remove commands on the fly.
-- 🎨 **Visual Feedback**: Show visual cues when the assistant is active.
-- 🚀 **Easy Integration**: Integrate the assistant with just a few lines of code.
-- 🗣️ **Voice Feedback**: The assistant can respond with voice feedback.
-- 🔄 **Double Activation**: The assistant can be activated with a double-click and also put to sleep with a double-click when active.
+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
 
-Want to make the assistant even better? PRs are welcomed! 🙌
+Contributions are welcome! Please read our [Contributing Guide](../../CONTRIBUTING.md) first.
 
 ---
 
-## 📄 License
+## 📬 Support
+
+- 📧 Email: support@foisit.com
+- 💬 Discord: [Join our community](https://discord.gg/foisit)
+- 🐛 Issues: [GitHub Issues](https://github.com/boluwatifee4/foisit/issues)
+
+---
 
-This library is licensed under the MIT License.
+**Made with ❤️ by the Foisit Team**

package/package.json

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