@snf/access-qa-bot 2.1.0-rc.7 → 2.3.0-beta.1

package/README.md

@@ -1,8 +1,6 @@
-# Q&A Bot
+# ACCESS Q&A Bot
 
-A React component for integrating the Q&A Bot into your application. The bot can operate in two modes: **floating** (chat button that opens/closes a window) or **embedded** (always visible inline).
-
-**Architecture**: Everything is React-backed for consistency and simplicity. HTML/plain JS usage loads a React-based standalone bundle.
+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.
 
 ## Installation
 
@@ -27,106 +25,64 @@ npm run build
 npx serve
 ```
 
-### Floating vs Embedded Modes
+## Features
+
+- **🤖 Intelligent Q&A**: AI-powered responses to user questions about ACCESS
+- **🎫 Support Tickets**: Create help tickets for general support, ACCESS login issues, and resource provider login problems
+- **📝 Feedback Collection**: Gather user feedback and suggestions  
+- **👤 User Pre-population**: Auto-fill forms with user info when logged in
+- **🎨 Rich Formatting**: Support for HTML and Markdown in responses
+- **♿ 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
 
-**All integration methods support both modes**, but have different defaults:
-
-| Method | Default Mode | Override |
-|--------|--------------|----------|
-| Element ID (`#qa-bot`) | Floating | Set `embedded: true` |
-| CSS Class (`.embedded-qa-bot`) | Embedded | n/a |
-| JavaScript API | Floating | Set `embedded: true` |
+## 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
+- Negative feedback offers direct path to support ticket creation
+- Requires user to be logged in
+
+### 🎫 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
+
+### 🔒 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
 
 ## Integration Methods
 
-### Method 1: Auto-Detection by Element ID (Floating by Default)
-
-Simply add a div with id `qa-bot` to your HTML:
-
-```html
-<script src="https://unpkg.com/@snf/access-qa-bot@0.2.0/dist/access-qa-bot.standalone.js"></script>
-
-<!-- Automatically creates a floating chat button -->
-<div id="qa-bot"></div>
-```
-
-### Method 2: Auto-Detection by CSS Class (Embedded by Default)
-
-Use the `embedded-qa-bot` class with optional data attributes:
-
-```html
-<script src="https://unpkg.com/@snf/access-qa-bot@0.2.0/dist/access-qa-bot.standalone.js"></script>
-
-<!-- Automatically creates an embedded chat widget -->
-<div class="embedded-qa-bot"
-     data-welcome="Hello!"></div>
-```
-
-### Method 3: Programmatic JavaScript API (Floating by Default)
-
-Call the `qaBot()` function with full control:
-
-```html
-<script src="https://unpkg.com/@snf/access-qa-bot@0.2.0/dist/access-qa-bot.standalone.js"></script>
+The QABot can be integrated using a standalone javascript function, or as a react/preact component.
 
-<div id="my-bot-container"></div>
+### React Component
 
-<script>
-// Check if user is logged in by looking for auth cookie
-function isUserLoggedIn() {
-    return document.cookie.split(';').some(cookie => {
-        return cookie.trim().startsWith('SESSaccesscisso=');
-    });
-}
-
-window.addEventListener('load', function() {
-    const botController = qaBot({
-        target: document.getElementById('my-bot-container'),
-        embedded: false,  // false = floating (default), true = embedded
-        welcome: "Custom welcome message!",
-        isLoggedIn: isUserLoggedIn(),
-        defaultOpen: false,
-    });
-
-    // Use the controller to interact with the bot
-    botController.addMessage("Hello from JavaScript!");
-    botController.openChat();  // Only works in floating mode
-});
-</script>
-```
-
-## Programmatic Control
-
-When using the JavaScript API in plain HTML/JS (requires standalone bundle), you get a controller object with these methods:
-
-```javascript
-const botController = qaBot({...});
-
-// Add a message to the chat
-botController.addMessage("Hello World!");
-
-// Set user login status
-botController.setBotIsLoggedIn(true);
-
-// Control chat window (floating mode only)
-botController.openChat();
-botController.closeChat();
-botController.toggleChat();
-
-// Cleanup
-botController.destroy();
-```
-
-**Note**: The `qaBot()` function requires the standalone bundle (`access-qa-bot.standalone.js`) to be loaded first. React/Preact applications should use the `<QABot />` component instead.
-
-## As a React Component
-
-For React applications, import and use the component directly. If you want to be able to imperatively add a message to the chat, you can use the ref to do so.
+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
 
 ```jsx
 import React, { useRef, useState } from 'react';
@@ -166,8 +122,8 @@ function MyApp() {
             </button>
 
             <QABot
-                ref={botRef} // This is only needed if you want to add a message from outside the flow
-                embedded={false}  // true for embedded, false for floating
+                ref={botRef} // only needed if you want use the addMessage function
+                embedded={false}
                 isLoggedIn={isLoggedIn}
                 open={chatOpen}
                 onOpenChange={setChatOpen}
@@ -179,28 +135,78 @@ function MyApp() {
 }
 ```
 
-**React Component Notes:**
-- Uses **controlled component pattern**: manage `open` and `isLoggedIn` state in your parent component
-- `onOpenChange` callback receives the new open state when user interacts with chat
-- For programmatic message injection, use the ref: `botRef.current?.addMessage("Hello!")`
-- `defaultOpen` prop not available - use `open` prop with `useState` instead
-- For state management (login, chat open/close), use props and state instead of imperative methods
-
-## Configuration Properties
-
-| Property | Type | Description |
-|----------|------|-------------|
-| `apiKey` / `api-key` | string | API key for authentication (defaults to demo key) |
-| `defaultOpen` / `default-open` | boolean | Whether floating chat opens initially (ignored in embedded mode) **React Component: Use `open` prop instead** |
-| `embedded` | boolean | **false** = floating mode, **true** = embedded mode |
-| `isLoggedIn` / `is-logged-in` | boolean | Sets initial login state and reacts to changes |
-| `loginUrl` / `login-url` | string | URL to redirect for login (default: '/login') |
-| `open` | boolean | **React Component only**: Controls chat window open state (floating mode only) |
-| `onOpenChange` | function | **React Component only**: Callback when chat window open state changes |
-| `ringEffect` / `ring-effect` | boolean | Enable phone ring animation on tooltip (floating mode only) |
-| `welcome` | string | Welcome message shown to the user |
-
-**Note**: The React component uses a controlled component pattern with `open`/`onOpenChange`, while the JavaScript API uses `defaultOpen` for initial state.
+#### React Component Props
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `apiKey` | string | `"demo-key"` | API key for authentication |
+| `embedded` | boolean | `false` | Floating or embedded mode |
+| `isLoggedIn` | boolean | `false` | User login state |
+| `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) |
+| `username` | string | - | User's username/ACCESS ID (pre-populates ticket forms when logged in) |
+
+### Standalone Javascript
+
+```html
+<script src="https://unpkg.com/@snf/access-qa-bot@2.x/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,
+});
+</script>
+```
+
+#### Programmatic Control
+
+When using the JavaScript API in plain HTML/JS (requires standalone bundle), you get a controller object with imperative methods:
+
+```javascript
+const botController = qaBot({
+    target: document.getElementById('qa-bot'),
+    embedded: false,
+    welcome: "Custom welcome message!",
+    defaultOpen: false,
+});
+
+botController.addMessage("Hello World!");
+botController.setBotIsLoggedIn(true);
+// (floating mode only)
+botController.openChat();
+botController.closeChat();
+botController.toggleChat();
+// Cleanup
+botController.destroy();
+```
+
+#### JavaScript API Configuration
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `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 |
+| `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) |
+| `username` | string | - | User's username/ACCESS ID (pre-populates ticket forms when logged in) |
+
+> **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)
 
@@ -214,77 +220,169 @@ Customize the appearance by setting CSS custom properties on the container:
 "></div>
 ```
 
-## Direct CDN Deployment
+## Configuration
 
-For websites that don't use npm, include directly via CDN:
+### Environment Variables
 
-```html
-<!-- CSS (optional, for embedded styling) -->
-<link rel="stylesheet" href="https://cdn.jsdelivr.net/gh/necyberteam/qa-bot@v0.2.0/build/static/css/main.css">
-
-<!-- JavaScript -->
-<script src="https://cdn.jsdelivr.net/gh/necyberteam/qa-bot@v0.2.0/dist/access-qa-bot.standalone.js"></script>
+For React applications, you can set these environment variables:
 
-<!-- Your content -->
-<div id="qa-bot"></div>
+```bash
+REACT_APP_API_KEY=your-api-key-here
 ```
 
-## Development and Testing
+### 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 streaming responses
+- Support ticket creation with ProForma field mapping
+- File upload processing
+- User authentication and session management
+
+## Development & Release
+
+### Building the Library
+
+To build the distributable library files:
 
-### Development Server (React Implementation)
 ```bash
-npm start
-# Opens http://localhost:3000 with React dev server
+npm run build:lib
 ```
 
-### Testing Standalone Integration
+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)
+
+### NPM Beta Release
+
+To release a beta version:
+
 ```bash
-# Build the library and project
+# 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
-npm run build
 
-# Serve the standalone demo files
-npx serve
+# 3. Publish to npm with beta tag
+npm publish --tag beta
 
-# Then visit:
-# http://localhost:3000/index.html (integration demos)
+# 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
+
+- 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"
+
+# 5. Create git tag and push
+git tag v2.2.0-beta.0
+git push origin main --tags
 ```
 
-## File Structure Guide
+### Installing Beta Versions
+
+Users can install beta versions with:
+
+```bash
+# Install latest beta
+npm install @snf/access-qa-bot@beta
+
+# Install specific beta version
+npm install @snf/access-qa-bot@2.2.0-beta.0
+```
 
-- **`index.html`** - Main demo showing all integration methods
-- **`public/index.html`** - React app template (Create React App)
-- **`build/index.html`** - Built React app
-- **`src/`** - Source code
-  - **`components/QABot.js`** - Main React component
-  - **`lib.js`** - React-backed implementation for all usage patterns
+### Promoting Beta to Stable
 
-## Important Notes
+After testing and validation:
 
-1. **React-Backed Architecture**:
-   - Everything uses React components internally for consistency
-   - HTML/plain JS usage loads a React-based standalone bundle
-   - Single implementation reduces complexity and bugs
+```bash
+# Option A: Promote existing beta to latest
+npm dist-tag add @snf/access-qa-bot@2.2.0-beta.0 latest
 
-2. **Embedded vs Floating**:
-   - Embedded mode is always visible and ignores `defaultOpen`
-   - Floating mode shows a chat button; `defaultOpen` controls initial state
-   - Chat window controls (`openChat`, `closeChat`, `toggleChat`) only work in floating mode
+# 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
+```
 
-3. **Ring Effect**:
-   - Only works in floating mode when the tooltip is visible
-   - Triggers a phone-like ring animation to draw attention
-   - Activates once when the bot is first loaded (500ms delay)
-   - Won't repeat if user has already interacted with the chat
+### Release Verification
 
-4. **Auto-Detection**: The standalone script automatically detects and initializes:
-   - `#qa-bot` → Floating mode
-   - `.embedded-qa-bot` → Embedded mode
+Check that the release was successful:
 
-5. **API Key**: Defaults to demo key if not provided
+```bash
+# View all published versions
+npm view @snf/access-qa-bot versions --json
 
-6. **Browser Support**: Uses modern browser features; consider polyfills for older browsers
+# Check beta tag specifically
+npm view @snf/access-qa-bot@beta
 
-## Examples Repository
+# Test installation
+npm install @snf/access-qa-bot@beta
+```
 
-See the demo files in this repository for complete working examples of all integration methods.
+## 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 excluded build directory from version control
+
+#### 📚 Documentation
+- Updated README with comprehensive feature list and integration examples
+- Added detailed API documentation and configuration options
+- Included changelog for version tracking