mind-link-ai-widget/README.md

A react widget for React Web and React-Native Mobile integrations.

# Mind Link AI Widget

The MindLink-AI widget is built with React, TypeScript, and Vite. Easily embed in any web app or React Native app.

## Table of Contents
- [Azure VM Deployment](#azure-vm-deployment)
- [Local Development](#local-development)
- [Web Usage](#web-usage)
- [React Native Usage](#react-native-usage)
- [Building for Production](#building-for-production)

## Azure VM Deployment

This guide will help you deploy the MindLink-AI widget on an Azure Linux (RHEL/CentOS) VM with HTTPS on port 8000.

### Prerequisites
- Azure subscription with a Linux VM (RHEL/CentOS 7/8/9)
- SSH access to the VM
- Domain name (for HTTPS)
- SSL certificate (or use Let's Encrypt)

### Deployment Steps

1. **Update system packages**
   ```bash
   sudo yum update -y
   ```

2. **Install Node.js 22+**
   ```bash
   curl -fsSL https://rpm.nodesource.com/setup_22.x | sudo bash -
   sudo yum install -y nodejs
   node -v  # Verify installation
   ```

3. **Install Nginx**
   ```bash
   sudo yum install -y nginx
   ```

4. **Install and configure PM2**
   ```bash
   sudo npm install -g pm2
   ```

5. **Configure firewall for HTTPS**
   ```bash
   sudo firewall-cmd --permanent --add-port=8000/tcp
   sudo firewall-cmd --permanent --add-port=443/tcp
   sudo firewall-cmd --reload
   ```

6. **Start Nginx**
   ```bash
   sudo systemctl start nginx
   sudo systemctl enable nginx
   sudo systemctl status nginx  # Verify Nginx is running
   ```

7. **Deploy the application**
   ```bash
   # Create backup of current deployment (if exists)
   TIMESTAMP=$(date +%Y%m%d%H%M%S)
   [ -d "/mindlink-ui/dist" ] && \
     mv /mindlink-ui/dist "/mindlink-ui/backup-$TIMESTAMP"
   
   # Extract new version
   mkdir -p /mindlink-ui/dist
   tar -xzf /tmp/mindlink-ui-dist.tar.gz -C /mindlink-ui/dist
   
   # Set permissions
   chmod -R 755 /mindlink-ui/*
   ```

8. **Configure PM2 to serve the application**
   ```bash
   # Stop existing instance if running
   pm2 delete mindlink-ui || true
   
   # Start new instance
   cd /mindlink-ui/dist
   pm2 serve --spa --name "mindlink-ui" . 8000
   
   # Save PM2 process list and set up startup script
   pm2 save
   pm2 startup
   ```

9. **Configure Nginx as reverse proxy**
   Create a new Nginx configuration:
   ```bash
   sudo nano /etc/nginx/conf.d/mindlink-ui.conf
   ```
   
   Add the following configuration:
   ```nginx
   server {
       listen 80;
       server_name carelonhealth.com uat.api-az.carelonhealth.com;
       return 301 https://$host$request_uri;
   }

   server {
       listen 443 ssl http2;
       listen [::]:443 ssl http2;
       server_name carelonhealth.com uat.api-az.carelonhealth.com;

       # SSL Configuration
       ssl_certificate /mindlink-ui/certs/np.api.carelonhealth.com.pem;
       ssl_certificate_key /mindlink-ui/certs/np.api.carelonhealth.com.pem;
       ssl_protocols TLSv1.2 TLSv1.3;
       ssl_prefer_server_ciphers on;
       ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:DHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-GCM-SHA384;

       location / {
           proxy_pass https://localhost:8000;
           proxy_http_version 1.1;
           proxy_set_header Upgrade $http_upgrade;
           proxy_set_header Connection 'upgrade';
           proxy_set_header Host $host;
           proxy_set_header X-Real-IP $remote_addr;
           proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
           proxy_set_header X-Forwarded-Proto $scheme;
           proxy_cache_bypass $http_upgrade;
           
           # Increase timeouts if needed
           proxy_connect_timeout 300s;
           proxy_send_timeout 300s;
           proxy_read_timeout 300s;
       }
   }
   ```

10. **Test Nginx configuration and restart**
    ```bash
    sudo nginx -t
    sudo systemctl restart nginx
    ```

11. **Configure SELinux (if enabled)**
    ```bash
    # Allow Nginx to connect to port 8000
    sudo setsebool -P httpd_can_network_connect 1
    
    # If you encounter permission issues with the certificate files:
    sudo chcon -Rt httpd_sys_content_t /mindlink-ui/certs/
    ```

### Verifying the Setup
- Access your application at `https://uat.api-az.carelonhealth.com:8000`
- Check if the connection is secure (look for the lock icon in your browser)
- Check PM2 logs: `pm2 logs mindlink-ui`
- Check Nginx logs: `sudo journalctl -u nginx -f`
- Check if the service is listening on port 8000: `sudo ss -tulnp | grep 8000`

### Maintenance
- To update the application:
  1. On your local machine:
     ```bash
     npm install
     npm run build
     tar -czf mindlink-ui-dist.tar.gz -C dist .
     scp mindlink-ui-dist.tar.gz username@your-vm-ip:/tmp/
     ```
  
  2. On the server:
     ```bash
     # Follow steps 7-12 from the deployment section above
     # This will create a backup and deploy the new version
     ```

### Rollback
If you need to rollback to a previous version:
```bash
# List available backups
ls -l /mindlink-ui/backup-*

# Stop current instance
pm2 delete mindlink-ui

# Restore from backup
BACKUP_TIMESTAMP=20250101120000  # Replace with actual backup timestamp
mv /mindlink-ui/dist "/mindlink-ui/failed-$(date +%Y%m%d%H%M%S)"
mv "/mindlink-ui/backup-$BACKUP_TIMESTAMP" /mindlink-ui/dist

# Start the application
cd /mindlink-ui/dist
pm2 serve --spa --name "mindlink-ui" . 8000
pm2 save
```

---

## Usage

### Web (React/Vite/CRA/Next.js)

1. **Install**
   ```bash
   npm install mind-link-ai-widget
   # or
   yarn add mind-link-ai-widget
   ```

2. **Import and Use**
   ```jsx
   import MindLinkAIWidget from 'mind-link-ai-widget';

   function App() {
     return (
       <div>
         <MindLinkAIWidget />
       </div>
     );
   }
   export default App;
   ```

---

### React Native

1. **Install**
   ```bash
   npm install mind-link-ai-widget
   # or
   yarn add mind-link-ai-widget
   ```

2. **Configure Metro (Required)**
   Add to your `metro.config.js`:
   ```js
   const { getDefaultConfig } = require('expo/metro-config');
   
   const config = getDefaultConfig(__dirname);
   
   config.resolver.resolverMainFields = ['react-native', 'browser', 'main'];
   config.resolver.platforms = ['ios', 'android', 'native', 'web'];
   
   module.exports = config;
   ```

3. **Link Peer Dependencies**
   Ensure `react`, `react-native`, and `react-dom` are installed in your project.

4. **Import and Use**
   ```jsx
   import MindLinkAIWidget from 'mind-link-ai-widget';

   export default function App() {
     return <MindLinkAIWidget />;
   }
   ```

---

## Build as a Library

To build the widget for distribution:

```bash
npm run build-widget
```
- Output: `widgets/mind-link-ai-widget.umd.js`

---

## Development

- `npm run dev` - Start dev server
- `npm run build-widget` - Build library for distribution

---

## Running with Custom Vite Modes and Environment Variables

You can pass Vite CLI arguments (such as `--mode`) to both the build and dev server using the npm `start` script. This is enabled by the `cross-env-shell` utility in `package.json`.

### Usage

- To start the app with a specific Vite mode (e.g., `dev`, `uat`, `prod`):

  ```sh
  npm run start -- --mode=dev
  npm run start -- --mode=uat
  npm run start -- --mode=prod
  ```
  This will run both the build and the dev server with the same mode:
  - `npm run build -- --mode=dev && vite --mode=dev`

- You can also pass any other Vite CLI arguments in the same way:

  ```sh
  npm run start -- --mode=uat --port=9000
  ```

- To override environment variables at runtime (for any variable starting with `VITE_`):

  ```sh
  VITE_VITE_API_HOST=https://custom-api.com npm run start -- --mode=dev
  ```

### How it works
- The `start` script in `package.json` uses `cross-env-shell` to forward all CLI arguments to both the build and dev server.
- This makes it easy to automate environment selection and variable overrides for any deployment or local workflow.

---

## License
MIT

---

# React + TypeScript + Vite

This template provides a minimal setup to get React working in Vite with HMR and some ESLint rules.

Currently, two official plugins are available:

- [@vitejs/plugin-react](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react) uses [Babel](https://babeljs.io/) for Fast Refresh
- [@vitejs/plugin-react-swc](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react-swc) uses [SWC](https://swc.rs/) for Fast Refresh

## Expanding the ESLint configuration

If you are developing a production application, we recommend updating the configuration to enable type-aware lint rules:

```js
export default tseslint.config([
  globalIgnores(['dist']),
  {
    files: ['**/*.{ts,tsx}'],
    extends: [
      // Other configs...

      // Remove tseslint.configs.recommended and replace with this
      ...tseslint.configs.recommendedTypeChecked,
      // Alternatively, use this for stricter rules
      ...tseslint.configs.strictTypeChecked,
      // Optionally, add this for stylistic rules
      ...tseslint.configs.stylisticTypeChecked,

      // Other configs...
    ],
    languageOptions: {
      parserOptions: {
        project: ['./tsconfig.node.json', './tsconfig.app.json'],
        tsconfigRootDir: import.meta.dirname,
      },
      // other options...
    },
  },
])
```

You can also install [eslint-plugin-react-x](https://github.com/Rel1cx/eslint-react/tree/main/packages/plugins/eslint-plugin-react-x) and [eslint-plugin-react-dom](https://github.com/Rel1cx/eslint-react/tree/main/packages/plugins/eslint-plugin-react-dom) for React-specific lint rules:

```js
// eslint.config.js
import reactX from 'eslint-plugin-react-x'
import reactDom from 'eslint-plugin-react-dom'

export default tseslint.config([
  globalIgnores(['dist']),
  {
    files: ['**/*.{ts,tsx}'],
    extends: [
      // Other configs...
      // Enable lint rules for React
      reactX.configs['recommended-typescript'],
      // Enable lint rules for React DOM
      reactDom.configs.recommended,
    ],
    languageOptions: {
      parserOptions: {
        project: ['./tsconfig.node.json', './tsconfig.app.json'],
        tsconfigRootDir: import.meta.dirname,
      },
      // other options...
    },
  },
])
```

## Using as a Web Script

You can inject the MindLinkAI widget into any web app using the UMD bundle:

1. Add React and ReactDOM to your page (if not already present):
   ```html
   <script src="https://unpkg.com/react@18/umd/react.production.min.js"></script>
   <script src="https://unpkg.com/react-dom@18/umd/react-dom.production.min.js"></script>
   ```
2. Add the UMD bundle (after building, found in `widgets/mind-link-ai-widget.umd.js`):
   ```html
   <script src="/path/to/widgets/mind-link-ai-widget.umd.js"></script>
   <div id="my-ai-widget"></div>
   <script>
     ReactDOM.createRoot(document.getElementById('my-ai-widget')).render(
       React.createElement(MindLinkAIWidget, {
         onSendMessage: async (msg) => `Echo: ${msg}`
       })
     );
   </script>
   ```

- The widget is available as `MindLinkAIWidget`.
- You can pass props as you would in React.

## Tech Stack & Requirements

- **Node.js:** ^20.19.0 or >=22.12.0 (recommended: latest LTS)
- **React:** ^19.1.0
- **React DOM:** ^19.1.0
- **Vite:** ^7.0.3
- **TypeScript:** ~5.8.3
- **react-icons:** ^5.5.0

> **Note:** Vite 7+ requires Node.js ^20.19.0 or >=22.12.0. If you see errors about `crypto.hash is not a function`, upgrade your Node.js version.