@snf/access-qa-bot 2.7.3 → 3.0.1

package/README.md

@@ -1,6 +1,9 @@
 # ACCESS Q&A Bot
 
-A React component for integrating the ACCESS Q&A Bot into your application. Features intelligent Q&A responses, support ticket creation with ProForma integration, and user feedback collection. Also includes a standalone bundle for plain HTML/JS usage.
+A React wrapper around [@snf/qa-bot-core](https://github.com/necyberteam/qa-bot-core) that adds ACCESS-specific functionality. This package serves two purposes:
+
+1. **Production use**: The official Q&A bot for ACCESS websites
+2. **Reference implementation**: An example of how to build organization-specific wrappers around qa-bot-core
 
 ## Installation
 
@@ -8,401 +11,345 @@ A React component for integrating the ACCESS Q&A Bot into your application. Feat
 npm install @snf/access-qa-bot
 ```
 
-## Developing React App
-
-```bash
-npm install
-npm run start
-```
-
-## Running the Demo
-
-This will serve the index.html file in the root directory, which demonstrates different ways to integrate the bot.
-
-```bash
-npm run build:lib
-npm run build
-npx serve
-```
-
 ## Features
 
-- **🤖 Intelligent Q&A**: AI-powered responses to user questions about ACCESS
+- **🤖 Intelligent Q&A**: AI-powered responses about ACCESS resources and services
 - **🎫 Support Tickets**: Create help tickets for general support, ACCESS login issues, and resource provider login problems
-- **📝 Feedback Collection**: Gather user feedback and suggestions  
+- **🔒 Security Reporting**: Report security incidents with priority levels and file attachments
+- **📊 Metrics/XDMoD**: Query usage and performance data for ACCESS resources
+- **📎 File Attachments**: Upload screenshots, logs, and documents with tickets
 - **👤 User Pre-population**: Auto-fill forms with user info when logged in
-- **🎨 Rich Formatting**: Support for HTML and Markdown in responses
+- **🎨 Theming**: Customizable colors and branding via qa-bot-core
 - **♿ Accessibility**: Full screen reader support and keyboard navigation
 - **📱 Responsive**: Works on desktop and mobile devices
 
 ### Display Modes
 
-The Q&A Bot supports two display modes:
-
-- **Floating Mode** (default): Shows a chat button that opens/closes a floating chat window
-- **Embedded Mode**: Always visible, embedded directly in the page content
+- **Floating Mode** (default): Chat button that opens/closes a floating window
+- **Embedded Mode**: Always visible, embedded in page content
 
 ## Available Flows
 
-The bot supports several conversation flows:
-
 ### 🤖 Q&A Flow
 - Ask questions about ACCESS resources, services, and documentation
-- Receive AI-powered responses with HTML and Markdown formatting
-- Built-in feedback system with thumbs up/down options after each response
-- Automatic feedback tracking and analytics
-- Users can provide feedback or continue asking questions immediately
-- Requires user to be logged in
+- AI-powered responses with HTML and Markdown formatting
+- Thumbs up/down feedback after each response
+- Requires login (gated by default)
 
 ### 🎫 Support Ticket Flows
-- **General Help**: Create support tickets for any ACCESS-related issues
-- **ACCESS Login**: Get help with ACCESS website login problems  
-- **Resource Login**: Get help with resource provider login issues
-- All flows support file attachments and are integrated with JSM ProForma
-
-### 📝 Feedback Flow
-- Collect user feedback and suggestions
-- Optional file attachments for screenshots or documents
+- **General Help**: Any ACCESS-related issues
+- **ACCESS Login**: Problems logging into access-ci.org
+- **Resource Login**: Problems logging into resource providers (Anvil, Expanse, etc.)
+- All flows support file attachments and integrate with JSM ProForma
 
 ### 🔒 Security Incident Flow
 - Report security issues, vulnerabilities, and incidents
-- Dedicated priority levels: Critical, High, Medium, Low
-- Direct routing to ACCESS cybersecurity team (Service Desk ID: 3)
-- Support for file attachments (screenshots, logs, evidence)
-- Professional incident tracking with ticket reference links
-- User contact information pre-population when logged in
+- Priority levels: Critical, High, Medium, Low
+- Direct routing to ACCESS cybersecurity team
+- File attachments for evidence
 
-## Integration Methods
+### 📊 Metrics/XDMoD Flow
+- Query usage and performance data
+- Interactive Q&A loop with feedback buttons
 
-The QABot can be integrated using a standalone javascript function, or as a react/preact component.
+---
+
+## Integration Methods
 
 ### React Component
 
-For React applications, import and use the component directly.
-- To control the chat programmatically, manage `open` and `isLoggedIn` state in your parent component.
-- Use `onOpenChange` to keep your state in sync with user interactions.
-- You can imperatively add a message to the bot using the `addMessage` function
+For React applications, import and use the component directly:
 
-```jsx
+```tsx
 import React, { useRef, useState } from 'react';
-import { QABot } from '@snf/access-qa-bot';
+import { AccessQABot } from '@snf/access-qa-bot';
 
 function MyApp() {
-    const [isLoggedIn, setIsLoggedIn] = useState(false);
-    const [chatOpen, setChatOpen] = useState(false);
-    const botRef = useRef();
-
-    const handleAddMessage = () => {
-        botRef.current?.addMessage("Hello from React!");
-    };
-
-    const handleOpenChat = () => {
-        setChatOpen(true);
-    };
-
-    const handleToggleLogin = () => {
-        setIsLoggedIn(!isLoggedIn);
-    };
-
-    return (
-        <div className="app">
-            <h1>My React Application</h1>
-
-            <button onClick={handleAddMessage}>
-                Send Message to Bot
-            </button>
-
-            <button onClick={handleOpenChat}>
-                Open Chat (Controlled)
-            </button>
-
-            <button onClick={handleToggleLogin}>
-                Toggle Login State
-            </button>
-
-            <QABot
-                ref={botRef} // only needed if you want use the addMessage function
-                embedded={false}
-                isLoggedIn={isLoggedIn}
-                open={chatOpen}
-                onOpenChange={setChatOpen}
-                welcome="Welcome to the ACCESS Q&A Bot!"
-                apiKey={process.env.REACT_APP_API_KEY}
-            />
-        </div>
-    );
+  const [isLoggedIn, setIsLoggedIn] = useState(false);
+  const [chatOpen, setChatOpen] = useState(false);
+  const botRef = useRef();
+
+  return (
+    <div className="app">
+      <h1>My Application</h1>
+
+      <button onClick={() => botRef.current?.addMessage("Hello!")}>
+        Send Message
+      </button>
+
+      <button onClick={() => setChatOpen(true)}>
+        Open Chat
+      </button>
+
+      <AccessQABot
+        ref={botRef}
+        isLoggedIn={isLoggedIn}
+        open={chatOpen}
+        onOpenChange={setChatOpen}
+        userEmail="user@example.com"
+        userName="Jane Doe"
+        accessId="jdoe"
+        apiKey={process.env.VITE_API_KEY}
+      />
+    </div>
+  );
 }
 ```
 
-#### React Component Props
+#### React Props
 
 | Property | Type | Default | Description |
 |----------|------|---------|-------------|
+| `isLoggedIn` | boolean | `false` | User login state (gates Q&A, shows login/user icon) |
 | `apiKey` | string | `"demo-key"` | API key for authentication |
-| `embedded` | boolean | `false` | Floating or embedded mode |
-| `isLoggedIn` | boolean | `false` | User login state |
+| `embedded` | boolean | `false` | Embedded or floating mode |
 | `loginUrl` | string | `"/login"` | Login redirect URL |
-| `open` | boolean | - | Controls chat window (floating mode only) |
-| `onOpenChange` | function | - | Chat window state change callback |
-| `ringEffect` | boolean | `false` | Phone ring animation on tooltip |
-| `welcome` | string | - | Welcome message |
-| `userEmail` | string | - | User's email (pre-populates ticket forms when logged in) |
-| `userName` | string | - | User's display name (pre-populates ticket forms when logged in) |
-| `accessId` | string | - | User's ACCESS ID (pre-populates ticket forms when logged in) |
+| `open` | boolean | - | Control chat window (floating mode) |
+| `onOpenChange` | function | - | Chat window state callback |
+| `welcome` | string | - | Custom welcome message |
+| `userEmail` | string | - | Pre-populate email in forms |
+| `userName` | string | - | Pre-populate name in forms |
+| `accessId` | string | - | Pre-populate ACCESS ID in forms |
+
+#### Ref Methods
 
-### Standalone Javascript
+```tsx
+const botRef = useRef<AccessQABotRef>(null);
 
-**Recommended approach** - use the self-contained standalone bundle:
+// Add a message programmatically
+botRef.current?.addMessage("Hello from code!");
+```
+
+---
+
+### Standalone JavaScript
+
+For plain HTML/JS, use the self-contained standalone bundle:
 
 ```html
-<script src="https://unpkg.com/@snf/access-qa-bot@2.4.0/dist/access-qa-bot.standalone.js"></script>
+<script src="https://unpkg.com/@snf/access-qa-bot@3.0.0/dist/access-qa-bot.standalone.js"></script>
 
 <div id="qa-bot"></div>
 
 <script>
-qaBot({
-    target: document.getElementById('qa-bot'),
-    embedded: false,
-    welcome: "Custom welcome message!",
-    defaultOpen: false,
+const bot = qaBot({
+  target: document.getElementById('qa-bot'),
+  isLoggedIn: false,
+  embedded: false,
+  welcome: "Welcome! How can I help you today?",
+  defaultOpen: false,
 });
 </script>
 ```
 
-> **Note**: Early versions (v0.1.x) supported a "three files" CDN approach using `/build/` directory files. This approach is no longer supported as the build architecture changed from auto-executing scripts to library exports. Use the standalone bundle above instead.
-
 #### Programmatic Control
 
-When using the JavaScript API in plain HTML/JS (requires standalone bundle), you get a controller object with imperative methods:
+The `qaBot()` function returns a controller object:
 
 ```javascript
-const botController = qaBot({
-    target: document.getElementById('qa-bot'),
-    embedded: false,
-    welcome: "Custom welcome message!",
-    defaultOpen: false,
+const bot = qaBot({
+  target: document.getElementById('qa-bot'),
+  isLoggedIn: false,
 });
 
-botController.addMessage("Hello World!");
-botController.setBotIsLoggedIn(true);
-// (floating mode only)
-botController.openChat();
-botController.closeChat();
-botController.toggleChat();
+// Add messages
+bot.addMessage("Hello World!");
+
+// Update login state
+bot.setBotIsLoggedIn(true);
+
+// Control chat window (floating mode only)
+bot.openChat();
+bot.closeChat();
+bot.toggleChat();
+
 // Cleanup
-botController.destroy();
+bot.destroy();
 ```
 
-#### JavaScript API Configuration
+#### Standalone Config
 
 | Property | Type | Default | Description |
 |----------|------|---------|-------------|
-| `target` | HTMLElement | - | **Required**: DOM element to render into |
+| `target` | HTMLElement | **required** | DOM element to render into |
 | `apiKey` | string | `"demo-key"` | API key for authentication |
 | `defaultOpen` | boolean | `false` | Initial chat window state |
-| `embedded` | boolean | `false` | Floating or embedded mode |
+| `embedded` | boolean | `false` | Embedded or floating mode |
 | `isLoggedIn` | boolean | `false` | User login state |
 | `loginUrl` | string | `"/login"` | Login redirect URL |
-| `ringEffect` | boolean | `false` | Phone ring animation on tooltip |
 | `welcome` | string | - | Welcome message |
-| `userEmail` | string | - | User's email (pre-populates ticket forms when logged in) |
-| `userName` | string | - | User's display name (pre-populates ticket forms when logged in) |
-| `accessId` | string | - | User's ACCESS ID (pre-populates ticket forms when logged in) |
+| `userEmail` | string | - | Pre-populate email |
+| `userName` | string | - | Pre-populate name |
+| `accessId` | string | - | Pre-populate ACCESS ID |
 
-> **More Examples**: See `index.html` in this repository for examples including login state management, embedded mode, and programmatic control. Run the react app to see the same in a react context.
+---
 
-### CSS Custom Properties (Theming)
+### CDN Usage
 
-Customize the appearance by setting CSS custom properties on the container:
+#### unpkg (npm-based)
 
 ```html
-<div id="qa-bot" style="
-    --primary-color: #007bff;
-    --secondary-color: #6c757d;
-    --font-family: 'Arial', sans-serif;
-"></div>
+<script src="https://unpkg.com/@snf/access-qa-bot@3.0.0/dist/access-qa-bot.standalone.js"></script>
 ```
 
-## Configuration
-
-### Environment Variables
+#### jsdelivr (GitHub-based)
 
-For React applications, you can set these environment variables:
-
-```bash
-REACT_APP_API_KEY=your-api-key-here
+```html
+<script src="https://cdn.jsdelivr.net/gh/necyberteam/access-qa-bot@v3.0.0/dist/access-qa-bot.standalone.js"></script>
 ```
 
-### API Integration
-
-The bot integrates with the ACCESS Q&A API and JSM (Jira Service Management) for ticket creation. Configure your backend endpoints to handle:
-
-- Q&A queries with JSON responses
-- Support ticket creation with ProForma field mapping
-- File upload processing
-- User authentication and session management
+---
 
-## Development & Release
+## Building Your Own Wrapper
 
-### Building the Library
+This repository demonstrates the **wrapper pattern** for extending qa-bot-core with organization-specific functionality. Use this as a reference for building your own wrapper.
 
-To build the distributable library files:
+### Architecture
 
-```bash
-npm run build:lib
+```
+YourWrapper (this pattern)
+  └── QABot (from @snf/qa-bot-core)
+      └── react-chatbotify
 ```
 
-This creates the distribution files in the `dist/` directory:
-- `access-qa-bot.js` (ES module)
-- `access-qa-bot.umd.cjs` (UMD/CommonJS) 
-- `access-qa-bot.standalone.js` (Standalone version)
+### What qa-bot-core Provides
+
+- Chat UI (floating/embedded modes)
+- Q&A flow with feedback
+- Login state management
+- Theming and branding props
+- `customFlow` prop for extending functionality
+
+### What Your Wrapper Adds
+
+- Organization-specific flows (tickets, security, etc.)
+- Integration with your backend services (JIRA, APIs)
+- Custom form validation and state management
+- Environment-specific configuration
+
+### Key Files to Study
+
+| File | Purpose |
+|------|---------|
+| `src/components/AccessQABot.tsx` | Main wrapper component - combines flows, passes props to core |
+| `src/flows/*.ts` | Custom conversation flows using react-chatbotify format |
+| `src/utils/flow-context.ts` | Form state management across flow steps |
+| `src/utils/ticket-api.ts` | Backend integration (JIRA ticket submission) |
+| `src/standalone.tsx` | Standalone JS API wrapper |
+| `src/config/constants.ts` | Environment config and defaults |
+
+### Creating Custom Flows
+
+Flows use the [react-chatbotify](https://react-chatbotify.com/) format:
+
+```typescript
+import { Flow } from 'react-chatbotify';
+
+export function createMyFlow(): Flow {
+  return {
+    my_start: {
+      message: "Hello! What would you like to do?",
+      options: ["Option A", "Option B"],
+      path: (params) => {
+        if (params.userInput === "Option A") return "option_a_step";
+        return "option_b_step";
+      },
+    },
+    option_a_step: {
+      message: "You chose A!",
+      path: "end",
+    },
+    // ... more steps
+  };
+}
+```
 
-### Build Directory
+### Combining Flows
 
-The package includes both `/dist/` and `/build/` directories:
+In your wrapper component:
 
-- **`/dist/`**: Library files for npm consumers and CDN usage
-  - `access-qa-bot.js` (ES module for React apps)
-  - `access-qa-bot.umd.cjs` (CommonJS)
-  - `access-qa-bot.standalone.js` (Self-contained for plain HTML)
+```tsx
+import { QABot, applyFlowSettings } from '@snf/qa-bot-core';
 
-- **`/build/`**: React app build files
-  - **Not for standalone CDN usage** (use `/dist/access-qa-bot.standalone.js` instead)
-  - Required for shadow DOM implementations that need to import CSS directly
-  - Example: `import qaStyle from '@snf/access-qa-bot/build/static/css/main.css?inline'`
-  - Maintained for backward compatibility with existing integrations
+const customFlow = useMemo(() => {
+  const flow1 = createMenuFlow();
+  const flow2 = createTicketFlow();
+  const flow3 = createMyCustomFlow();
 
-Both directories are published to npm to support different integration patterns.
+  const combined = { ...flow1, ...flow2, ...flow3 };
 
-### NPM Beta Release
+  // Auto-set chatDisabled based on options/checkboxes
+  return applyFlowSettings(combined, { disableOnOptions: true });
+}, [dependencies]);
 
-To release a beta version:
+return (
+  <QABot
+    isLoggedIn={isLoggedIn}
+    customFlow={customFlow}
+    // ... other props
+  />
+);
+```
 
-```bash
-# 1. Update version to beta (without git operations)
-npm version 2.2.0-beta.0 --no-git-tag-version
+---
 
-# 2. Build the library distribution files
-npm run build:lib
+## Environment Variables
 
-# 3. Publish to npm with beta tag
-npm publish --tag beta
+Create `.env.local` from `.env.example`:
 
-# 4. Create meaningful git commit and tag
-git add package.json
-git commit -m "Release v2.2.0-beta.0: Add keyboard accessibility for checkboxes
+```env
+VITE_API_ENDPOINT=https://your-qa-api.com/api/
+VITE_RATING_ENDPOINT=https://your-qa-api.com/rating/
+VITE_NETLIFY_BASE_URL=https://your-ticket-api.netlify.app
+VITE_METRICS_API_ENDPOINT=https://your-metrics-api.com/
+VITE_API_KEY=your_api_key_here
+```
 
-- Implement full keyboard navigation for feedback form checkboxes
-- Fix focus persistence issues between questions  
-- Add consistent styling across all interactive elements
-- Enhance screen reader support with ARIA attributes"
+## Development
 
-# 5. Create git tag and push
-git tag v2.2.0-beta.0
-git push origin main --tags
-```
+```bash
+# Install dependencies
+npm install
 
-### Installing Beta Versions
+# Start dev server
+npm run dev
 
-Users can install beta versions with:
+# Build all outputs (ESM, UMD, standalone)
+npm run build
 
-```bash
-# Install latest beta
-npm install @snf/access-qa-bot@beta
+# Build library only (ESM, UMD)
+npm run build:lib
 
-# Install specific beta version
-npm install @snf/access-qa-bot@2.2.0-beta.0
+# Type check
+npm run type-check
 ```
 
-### Promoting Beta to Stable
+## Build Outputs
 
-After testing and validation:
+| File | Format | Use Case |
+|------|--------|----------|
+| `dist/access-qa-bot.js` | ESM | npm import (React apps) |
+| `dist/access-qa-bot.umd.cjs` | UMD | CommonJS require |
+| `dist/access-qa-bot.standalone.js` | IIFE | CDN/script tag (bundles Preact) |
+| `dist/style.css` | CSS | Styles (auto-imported by standalone) |
 
-```bash
-# Option A: Promote existing beta to latest
-npm dist-tag add @snf/access-qa-bot@2.2.0-beta.0 latest
+## Version History
 
-# Option B: Release new stable version
-npm version 2.2.0 --no-git-tag-version
-npm run build:lib
-npm publish
-git add package.json
-git commit -m "Release v2.2.0: Stable release with keyboard accessibility"
-git tag v2.2.0
-git push origin main --tags
-```
+This package continues the `@snf/access-qa-bot` npm package:
 
-### Release Verification
+| Version | Repository | Notes |
+|---------|------------|-------|
+| v0.x - v2.x | [qa-bot](https://github.com/necyberteam/qa-bot) (deprecated) | Original implementation |
+| v3.0.0+ | [access-qa-bot](https://github.com/necyberteam/access-qa-bot) (this repo) | Rewrite using qa-bot-core |
 
-Check that the release was successful:
+### What's New in v3.0.0
 
-```bash
-# View all published versions
-npm view @snf/access-qa-bot versions --json
-
-# Check beta tag specifically
-npm view @snf/access-qa-bot@beta
+- **Architecture**: Now wraps @snf/qa-bot-core instead of embedding all logic
+- **TypeScript**: Full TypeScript rewrite with type definitions
+- **Build**: Vite-based build system (was Rollup + CRA)
+- **Props**: `enabled` → `isLoggedIn` (breaking change)
+- **Flows**: Same user-facing flows, cleaner implementation
 
-# Test installation
-npm install @snf/access-qa-bot@beta
-```
+## License
 
-## Changelog
-
-### Version 2.3.0
-
-#### ✨ New Features
-- **Security Incident Reporting**: Complete security incident reporting flow for cybersecurity team
-- **Dedicated Security Routing**: Direct integration with ACCESS cybersecurity team (Service Desk ID: 3)
-- **Professional Security Flow**: Priority levels, detailed incident tracking, and file attachments
-- **Enhanced API Integration**: Expanded API endpoints for security incident submission
-
-#### 🔧 Security & Infrastructure
-- **Robust Error Handling**: Comprehensive null checks and error handling across all flows
-- **Security Portal Integration**: Proper routing to dedicated security service desk
-- **File Upload Support**: Attachment support for security evidence and documentation
-
-### Version 2.2.0
-
-#### ✨ New Features
-- **Integrated Feedback System**: Added thumbs up/down feedback collection after each Q&A response
-- **Seamless User Experience**: Users can provide feedback or continue asking questions without interruption
-- **Smart Flow Routing**: Negative feedback automatically offers direct path to support ticket creation
-- **Feedback Analytics**: Automatic tracking of user satisfaction with API endpoint integration
-- **Responsive Design**: Optimized feedback UI with hover effects and accessibility features
-
-#### 🎨 UI/UX Improvements
-- Streamlined Q&A conversation flow with optional feedback prompts
-- Enhanced button styling with smooth animations and brand color consistency
-- Improved input field placeholder text for better user guidance
-- Fixed horizontal scroll bar issues in user message bubbles
-
-### Version 2.1.0
-
-#### ✨ New Features
-- **Form Context System**: Implemented React Context to solve closure issues and ensure fresh form state
-- **User Info Pre-population**: Added support for pre-filling ticket forms with user email, name, and username when logged in
-- **HTML & Markdown Rendering**: Added support for rich text formatting in Q&A responses
-- **Enhanced Ticket Flows**: Improved all support ticket flows with better user experience
-
-#### 🐛 Bug Fixes
-- Fixed React closure issues causing stale form data in ticket summaries
-- Resolved priority and ACCESS ID display issues in ticket forms
-- Fixed form state management across all ticket flows
-
-#### 🎨 UI/UX Improvements
-- Updated button text: "Create XXX Ticket" → "Yes, let's create a ticket"
-- Changed "New Chat" button to "Restart" for clarity
-- Improved accessibility with better ARIA labels
-- Enhanced responsive design for mobile devices
-
-#### 🔧 Technical Improvements
-- Removed unused helper functions (`getCurrentPriority`, `getCurrentAccessId`)
-- Cleaned up debug console statements for production
-- Added markdown renderer plugin alongside HTML renderer
-- Improved build configuration and updated build directory handling
-
-#### 📚 Documentation
-- Updated README with comprehensive feature list and integration examples
-- Added detailed API documentation and configuration options
-- Included changelog for version tracking
+MIT