@sprout_ai_labs/sidekick 1.0.0

package/README.md

@@ -0,0 +1,305 @@
+# Sprout Sidekick
+
+A Vue 3 plugin providing responsive chat components with custom Sidekick branding, Rubik font, and shared state management.
+
+[![Demo](https://img.shields.io/badge/🚀-Live%20Demo-blue?style=for-the-badge)](https://ljocson.github.io/sidekick/demo)
+
+## Features
+
+- 🎨 **Custom Branding**: Built-in Sidekick design with Rubik font
+- 💬 **Chat Components**: Ready-to-use chat interface components
+- 🔄 **Shared State**: Automatic state synchronization between components
+- 📱 **Responsive**: Mobile-friendly design
+- 🎯 **TypeScript**: Full TypeScript support
+- 🎨 **Tailwind CSS**: Styled with Tailwind CSS
+- ⚡ **Vue 3**: Built for Vue 3 with Composition API
+- 🔔 **Error Handling**: Built-in snackbar notifications for errors and success messages
+
+## Demo
+
+🚀 **[Try the Live Demo](https://ljocson.github.io/sidekick/demo)** - See the components in action with interactive examples.
+
+## Installation
+
+```bash
+npm install @sprout_ai_labs/sidekick
+```
+
+## Quick Start
+
+### 1. Install the plugin
+
+```javascript
+import { createApp } from 'vue'
+import App from './App.vue'
+import SproutSidekick from '@sprout_ai_labs/sidekick'
+import '@sprout_ai_labs/sidekick/dist/sprout-sidekick.css'
+
+const app = createApp(App)
+
+app.use(SproutSidekick, {
+  mode: 'PROD', // Required: 'QA' or 'PROD'
+  appName: 'My Application', // Required: Your app name (used for analytics)
+  skipDesignSystem: true, // Optional: Skip if design system is already installed
+})
+
+app.mount('#app')
+```
+
+### 2. Use the components
+
+```vue
+<template>
+  <div>
+    <!-- Full chat interface -->
+    <SidekickChat />
+
+    <!-- Floating chat widget -->
+    <SidekickChatPlugin />
+  </div>
+</template>
+
+<script setup>
+import { useChatStore } from '@sprout_ai_labs/sidekick'
+
+const chatStore = useChatStore()
+
+onMounted(() => {
+  // Set the token
+  chatStore.setToken('your-token-here')
+})
+</script>
+```
+
+## Components
+
+### SidekickChat
+
+The main chat interface component for full-page chat experiences.
+
+```vue
+<SidekickChat />
+```
+
+### SidekickChatPlugin
+
+A floating chat widget component that can be positioned anywhere on the page.
+
+```vue
+<SidekickChatPlugin />
+```
+
+### Additional Components
+
+The plugin also includes:
+
+- `SidekickChatInput` - Standalone chat input component
+- `SidekickLoader` - Loading animation component
+- `SidekickMessages` - Message display component
+
+## Plugin Options
+
+```typescript
+interface SidekickChatOptions {
+  mode: 'QA' | 'PROD' | 'qa' | 'prod' // Required: Backend environment
+  appName: string // Required: Your application name (for analytics)
+  skipDesignSystem?: boolean // Optional: Skip design system installation
+  baseUrl?: string // Optional: Custom backend URL (overrides mode)
+  deviceSource?: 'mobile' | 'web' // Optional: Device type (default: 'web')
+}
+```
+
+### Required Parameters
+
+- **`mode`**: Specifies which backend environment to use (`'QA'` or `'PROD'`)
+- **`appName`**: Identifies your application in analytics tracking
+
+### Optional Parameters
+
+- **`baseUrl`**: Custom backend URL (takes precedence over `mode`)
+- **`deviceSource`**: Device type identifier (`'mobile'` or `'web'`, default: `'web'`)
+- **`skipDesignSystem`**: Skip design system installation if already installed
+
+### Environment Variables
+
+The plugin requires environment variables to be set in your `.env` file:
+
+```env
+VITE_CHAT_BE_QA=https://agent-center-be-qa.sprout.ph
+VITE_CHAT_BE_PROD=https://agent-center-be.sprout.ph
+```
+
+### Configuration Examples
+
+**Minimal configuration (QA environment):**
+
+```javascript
+app.use(SproutSidekickPlugin, {
+  mode: 'QA', // Required
+  appName: 'Sprout HR', // Required
+})
+```
+
+**Production configuration:**
+
+```javascript
+app.use(SproutSidekickPlugin, {
+  mode: 'PROD', // Required
+  appName: 'Sprout Payroll', // Required
+  skipDesignSystem: true,
+})
+```
+
+**Mobile app configuration:**
+
+```javascript
+app.use(SproutSidekickPlugin, {
+  mode: 'PROD', // Required
+  appName: 'Sprout Mobile', // Required
+  deviceSource: 'mobile', // Optional
+})
+```
+
+**Using custom baseUrl:**
+
+```javascript
+app.use(SproutSidekickPlugin, {
+  mode: 'QA', // Required (even though baseUrl will override)
+  appName: 'Custom App', // Required
+  baseUrl: 'https://my-custom-backend.com', // This URL will be used
+})
+```
+
+**Priority Order for Backend URL:**
+
+1. `baseUrl` (if provided) - highest priority
+2. `mode` (uses corresponding environment variable)
+3. Throws error if neither is properly configured
+
+::: warning
+Both `mode` and `appName` are **required**. The plugin will throw an error at installation time if either is missing.
+:::
+
+### Design System Handling
+
+The plugin automatically detects if the Sprout Design System is already installed in your application to prevent duplicate installations. This ensures optimal performance and avoids conflicts.
+
+**Automatic Detection**: The plugin checks for existing design system components before installation.
+
+**Manual Control**: You can explicitly skip design system installation:
+
+```javascript
+app.use(SproutSidekickPlugin, {
+  skipDesignSystem: true, // Skip design system installation
+})
+```
+
+**Use Cases for `skipDesignSystem: true`**:
+
+- Your application already has the design system installed
+- You want to use a different version of the design system
+- You're managing design system installation separately
+
+## Error Handling
+
+The plugin includes built-in error handling with user-friendly snackbar notifications for various scenarios:
+
+- **Authentication Errors**: Invalid tokens, expired sessions, permission issues
+- **Message Sending Failures**: Network connectivity, server errors, validation issues
+- **Session Management**: Errors when clearing conversations or managing sessions
+- **Network Issues**: Connection timeouts, offline status, server unavailability
+
+Error notifications appear automatically using the design system's snackbar component and provide specific, actionable feedback to users.
+
+## State Management
+
+Use the built-in chat store for state management:
+
+```javascript
+import { useChatStore } from '@sprout_ai_labs/sidekick'
+
+const chatStore = useChatStore()
+
+// Access chat state
+console.log(chatStore.messages)
+console.log(chatStore.isTyping)
+
+// Send a message
+chatStore.sendMessage('Hello, world!')
+
+// Authentication
+chatStore.setToken('your-token')
+chatStore.clearToken()
+```
+
+## Types
+
+The plugin exports comprehensive TypeScript types:
+
+```typescript
+// Plugin options
+interface SidekickChatOptions {
+  mode: 'QA' | 'PROD' | 'qa' | 'prod'
+  appName: string
+  skipDesignSystem?: boolean
+  baseUrl?: string
+  deviceSource?: 'mobile' | 'web'
+}
+
+// Chat message
+interface ChatMessage {
+  id: string
+  text: string
+  sender: 'user' | 'bot' | 'ticket'
+  timestamp: Date
+  isStreaming?: boolean
+  thoughtSteps?: ThoughtStep[]
+  thinkingDuration?: number
+  isError?: boolean
+  errorDetails?: ErrorDetails
+  feedback?: Feedback
+  analyticsId?: string
+  redactedText?: string
+  kbSources?: KBSource[]
+}
+
+// Chat state
+interface ChatState {
+  messages: ChatMessage[]
+  isTyping: boolean
+  isConnected: boolean
+  token: string | null
+  isOpen: boolean
+  user: AuthUser | null
+  currentStreamingMessage: ChatMessage | null
+}
+```
+
+See the full [TypeScript definitions](./dist/index.d.ts) for all available types.
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Start development server
+npm run dev
+
+# Build the library
+npm run build
+
+# Run tests
+npm run test:unit
+
+# Lint code
+npm run lint
+```
+
+## License
+
+MIT
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.

package/dist/index.d.ts

@@ -0,0 +1,122 @@
+import type { App, Plugin } from 'vue'
+
+        // Plugin options interface
+        export interface SidekickChatOptions {
+          mode: 'QA' | 'PROD' | 'qa' | 'prod'
+          appName: string
+          skipDesignSystem?: boolean
+          baseUrl?: string
+          deviceSource?: 'mobile' | 'web'
+        }
+
+        // KB Source interface
+        export interface KBSource {
+          id: string
+          title: string
+          url: string
+          snippet: string[]
+        }
+
+        // Feedback interface
+        export interface Feedback {
+          is_helpful?: boolean
+          is_not_helpful?: boolean
+          user_feedback?: string
+          user_feedback_more?: string
+          analytics_id?: string
+        }
+
+        // Error details interface
+        export interface ErrorDetails {
+          code: string
+          status: number
+          message: string
+          file?: string
+          line?: string
+          lineno?: number
+          traceback?: string
+        }
+
+        // Thought step interface
+        export interface ThoughtStep {
+          event: string
+          message: string
+          agent_name?: string
+          agent_id?: string
+          tool_details?: Record<string, unknown>
+          completed: boolean
+        }
+
+        // Chat message interface
+        export interface ChatMessage {
+          id: string
+          text: string
+          sender: 'user' | 'bot' | 'ticket'
+          timestamp: Date
+          isStreaming?: boolean
+          thoughtSteps?: ThoughtStep[]
+          thinkingDuration?: number
+          isError?: boolean
+          errorDetails?: ErrorDetails
+          feedback?: Feedback
+          analyticsId?: string
+          redactedText?: string
+          kbSources?: KBSource[]
+        }
+
+        // Auth user interface
+        export interface AuthUser {
+          agentCenterUserId: string
+          accessLevel: string
+          agentCenterAccessLevel: string
+          hrDomain: string
+          employeeId: string
+          sessionId: string
+          realm: string
+          companyId: string
+          userId: string
+          email: string
+          company?: string
+          clientId?: string
+          viewingType?: string
+        }
+
+        // Chat state interface
+        export interface ChatState {
+          messages: ChatMessage[]
+          isTyping: boolean
+          isConnected: boolean
+          token: string | null
+          isOpen: boolean
+          user: AuthUser | null
+          currentStreamingMessage: ChatMessage | null
+        }
+
+        // Snackbar message interface
+        export interface SnackbarMessage {
+          id: string
+          message: string
+          type: 'success' | 'error' | 'warning' | 'info'
+          duration?: number
+        }
+
+        // Vue components
+        export declare const SidekickChat: any
+        export declare const SidekickChatPlugin: any
+        export declare const SidekickLoader: any
+        export declare const SidekickChatInput: any
+
+        // Store composable
+        export declare function useChatStore(options?: SidekickChatOptions): any
+
+        // Snackbar composable
+        export declare function useSnackbar(): any
+
+        // Storage utilities
+        export declare const storageUtils: any
+
+        // Plugin exports
+        declare const SproutSidekickPlugin: Plugin<[SidekickChatOptions]>
+        export default SproutSidekickPlugin
+
+        export declare const VueSidekickChat: Plugin<[SidekickChatOptions]>