@ihoomanai/chat-widget 2.0.0

package/README.md

@@ -0,0 +1,188 @@
+# @ihooman/chat-widget
+
+Universal chat support widget for any website. Uses secure Widget ID based initialization - no API keys exposed in client code.
+
+## Installation
+
+```bash
+npm install @ihooman/chat-widget
+# or
+yarn add @ihooman/chat-widget
+# or
+pnpm add @ihooman/chat-widget
+```
+
+## Quick Start
+
+### ES Modules
+
+```typescript
+import { IhoomanChat } from '@ihooman/chat-widget';
+
+IhoomanChat.init({
+  widgetId: 'wgt_your_widget_id', // Get this from your Ihooman dashboard
+});
+```
+
+### CommonJS
+
+```javascript
+const { IhoomanChat } = require('@ihooman/chat-widget');
+
+IhoomanChat.init({
+  widgetId: 'wgt_your_widget_id',
+});
+```
+
+### CDN / Script Tag
+
+```html
+<script src="https://cdn.ihooman.ai/widget/latest/chat.min.js"></script>
+<script>
+  IhoomanChat.init({
+    widgetId: 'wgt_your_widget_id',
+  });
+</script>
+```
+
+## Configuration Options
+
+```typescript
+IhoomanChat.init({
+  // Required
+  widgetId: 'wgt_your_widget_id',
+  
+  // Optional
+  theme: 'light', // 'light' | 'dark'
+  position: 'bottom-right', // 'bottom-right' | 'bottom-left' | 'top-right' | 'top-left'
+  title: 'Chat Support',
+  subtitle: 'We typically reply within minutes',
+  welcomeMessage: 'Hi there! 👋 How can we help you today?',
+  placeholder: 'Type a message...',
+  primaryColor: '#00aeff',
+  startOpen: false,
+  
+  // Callbacks
+  onReady: () => console.log('Widget ready'),
+  onOpen: () => console.log('Widget opened'),
+  onClose: () => console.log('Widget closed'),
+  onMessage: (message) => console.log('Message:', message),
+  onError: (error) => console.error('Error:', error),
+});
+```
+
+
+## API Methods
+
+### `IhoomanChat.init(config)`
+
+Initialize the widget with configuration options. Returns a Promise that resolves when the widget is ready.
+
+### `IhoomanChat.open()`
+
+Open the chat widget window.
+
+### `IhoomanChat.close()`
+
+Close the chat widget window.
+
+### `IhoomanChat.toggle()`
+
+Toggle the chat widget window open/closed.
+
+### `IhoomanChat.destroy()`
+
+Destroy the widget and clean up all resources.
+
+### `IhoomanChat.sendMessage(content)`
+
+Send a message programmatically.
+
+```typescript
+IhoomanChat.sendMessage('Hello, I need help!');
+```
+
+### `IhoomanChat.setUser(user)`
+
+Set user information for personalization.
+
+```typescript
+IhoomanChat.setUser({
+  name: 'John Doe',
+  email: 'john@example.com',
+  metadata: {
+    plan: 'premium',
+  },
+});
+```
+
+### `IhoomanChat.clearHistory()`
+
+Clear chat history and start a new conversation.
+
+### `IhoomanChat.on(event, callback)`
+
+Subscribe to widget events.
+
+```typescript
+IhoomanChat.on('message', (message) => {
+  console.log('New message:', message);
+});
+```
+
+### `IhoomanChat.off(event, callback)`
+
+Unsubscribe from widget events.
+
+### `IhoomanChat.getState()`
+
+Get the current widget state.
+
+```typescript
+const state = IhoomanChat.getState();
+console.log('Is open:', state.isOpen);
+console.log('Messages:', state.messages);
+```
+
+## Events
+
+- `ready` - Widget is initialized and ready
+- `open` - Widget window opened
+- `close` - Widget window closed
+- `message` - Message sent or received
+- `error` - An error occurred
+
+## TypeScript Support
+
+This package includes TypeScript type definitions. All types are exported:
+
+```typescript
+import type {
+  WidgetConfig,
+  WidgetState,
+  UserInfo,
+  Message,
+  WidgetEvent,
+} from '@ihooman/chat-widget';
+```
+
+## Security
+
+This widget uses Widget ID based initialization, which means:
+
+- ✅ No API keys are exposed in client-side code
+- ✅ Domain validation ensures the widget only works on authorized domains
+- ✅ All sensitive operations happen server-side
+
+Get your Widget ID from the [Ihooman Dashboard](https://dashboard.ihooman.ai).
+
+## Browser Support
+
+- Chrome (latest)
+- Firefox (latest)
+- Safari (latest)
+- Edge (latest)
+
+## License
+
+MIT © [Ihooman AI](https://ihooman.ai)

package/cdn/CDN_DEPLOYMENT.md

@@ -0,0 +1,199 @@
+# CDN Deployment Guide
+
+This document describes how to deploy the Ihooman Chat Widget to a CDN with proper URL structure and caching configuration.
+
+## Overview
+
+The widget is served from `https://cdn.ihooman.ai/widget/` with the following URL structure:
+
+| URL Pattern | Description | Cache Duration |
+|-------------|-------------|----------------|
+| `/v2/chat.min.js` | Latest v2.x.x release | 1 year (immutable) |
+| `/v2.1.0/chat.min.js` | Specific version | 1 year (immutable) |
+| `/latest/chat.min.js` | Always latest stable | 5 minutes |
+
+## URL Structure
+
+### Versioned URLs (Recommended for Production)
+
+```
+https://cdn.ihooman.ai/widget/v2/chat.min.js          # Latest v2.x.x
+https://cdn.ihooman.ai/widget/v2.1.0/chat.min.js      # Specific version
+https://cdn.ihooman.ai/widget/v2.1.0/chat.min.js.map  # Source map
+```
+
+### Latest URL (For Development/Testing)
+
+```
+https://cdn.ihooman.ai/widget/latest/chat.min.js      # Always latest stable
+https://cdn.ihooman.ai/widget/latest/chat.min.js.map  # Source map
+```
+
+## Cache Headers
+
+### Versioned Content (v2/, v2.1.0/, etc.)
+
+```
+Cache-Control: public, max-age=31536000, immutable
+```
+
+- **max-age=31536000**: Cache for 1 year (365 days)
+- **immutable**: Content will never change, browsers can skip revalidation
+- **public**: Can be cached by CDN edge nodes and browsers
+
+### Latest Content (/latest/)
+
+```
+Cache-Control: public, max-age=300
+```
+
+- **max-age=300**: Cache for 5 minutes
+- **public**: Can be cached by CDN edge nodes and browsers
+- No `immutable` flag since content changes with each release
+
+## Deployment Options
+
+### Option 1: AWS CloudFront + S3
+
+See `cloudfront-config.json` for CloudFront distribution configuration.
+
+### Option 2: Cloudflare
+
+See `cloudflare-config.json` for Cloudflare configuration.
+
+### Option 3: Nginx (Self-Hosted)
+
+See `nginx.conf` for Nginx configuration.
+
+## Deployment Steps
+
+### 1. Build CDN Assets
+
+```bash
+cd packages/chat-widget
+npm run build:cdn
+```
+
+This generates:
+- `cdn/v2/` - Major version directory
+- `cdn/v2.x.x/` - Full version directory
+- `cdn/latest/` - Latest version directory
+- `cdn/manifest.json` - Build manifest with SRI hashes
+
+### 2. Upload to CDN Origin
+
+Upload the contents of the `cdn/` directory to your CDN origin (S3, R2, or origin server).
+
+```bash
+# Example: AWS S3
+aws s3 sync cdn/ s3://cdn-ihooman-widget/widget/ \
+  --cache-control "public, max-age=31536000, immutable" \
+  --exclude "latest/*"
+
+aws s3 sync cdn/latest/ s3://cdn-ihooman-widget/widget/latest/ \
+  --cache-control "public, max-age=300"
+```
+
+### 3. Invalidate CDN Cache (if updating)
+
+```bash
+# AWS CloudFront
+aws cloudfront create-invalidation \
+  --distribution-id YOUR_DISTRIBUTION_ID \
+  --paths "/widget/latest/*" "/widget/v2/*"
+```
+
+### 4. Verify Deployment
+
+```bash
+# Check versioned URL
+curl -I https://cdn.ihooman.ai/widget/v2.0.0/chat.min.js
+
+# Expected headers:
+# Cache-Control: public, max-age=31536000, immutable
+# Content-Type: application/javascript
+
+# Check latest URL
+curl -I https://cdn.ihooman.ai/widget/latest/chat.min.js
+
+# Expected headers:
+# Cache-Control: public, max-age=300
+# Content-Type: application/javascript
+```
+
+## CORS Configuration
+
+The CDN must allow cross-origin requests for the widget to work on any domain:
+
+```
+Access-Control-Allow-Origin: *
+Access-Control-Allow-Methods: GET, HEAD, OPTIONS
+Access-Control-Allow-Headers: Content-Type
+```
+
+## Security Headers
+
+Recommended security headers for the CDN:
+
+```
+X-Content-Type-Options: nosniff
+X-Frame-Options: DENY
+Referrer-Policy: strict-origin-when-cross-origin
+```
+
+## Monitoring
+
+### Key Metrics to Monitor
+
+1. **Cache Hit Ratio**: Should be >95% for versioned URLs
+2. **Latency**: P99 should be <100ms globally
+3. **Error Rate**: Should be <0.1%
+4. **Bandwidth**: Track for cost optimization
+
+### Health Check Endpoint
+
+Create a health check at `/widget/health.json`:
+
+```json
+{
+  "status": "healthy",
+  "version": "2.0.0",
+  "timestamp": "2024-01-01T00:00:00Z"
+}
+```
+
+## Rollback Procedure
+
+If a deployment causes issues:
+
+1. **For versioned URLs**: Deploy the previous version to the major version directory
+2. **For latest URL**: Update the latest directory to point to the previous stable version
+
+```bash
+# Rollback latest to v2.0.0
+aws s3 sync s3://cdn-ihooman-widget/widget/v2.0.0/ \
+  s3://cdn-ihooman-widget/widget/latest/ \
+  --cache-control "public, max-age=300"
+
+# Invalidate latest cache
+aws cloudfront create-invalidation \
+  --distribution-id YOUR_DISTRIBUTION_ID \
+  --paths "/widget/latest/*"
+```
+
+## Version Management
+
+### Semantic Versioning
+
+- **Major version (v2/)**: Updated only for breaking changes
+- **Minor/Patch versions (v2.1.0/)**: Immutable, never updated
+- **Latest**: Always points to the most recent stable release
+
+### Release Process
+
+1. Build new version: `npm run build:cdn`
+2. Upload new version directory (e.g., `v2.1.1/`)
+3. Update major version directory (`v2/`) with new content
+4. Update `latest/` directory with new content
+5. Invalidate CDN cache for `latest/` and major version
+6. Update `manifest.json` with new SRI hashes

package/cdn/SRI_HASHES.md

@@ -0,0 +1,66 @@
+# SRI Hashes for @ihooman/chat-widget
+
+## Version: 2.0.0
+
+Build Date: 2026-01-31T15:26:43.871Z
+
+## Subresource Integrity (SRI) Hashes
+
+Use these hashes to ensure the integrity of the widget script when loading from CDN.
+
+### Minified Bundle (Recommended for Production)
+
+| Version | URL | SRI Hash |
+|---------|-----|----------|
+| Major (v2) | `https://cdn.ihooman.ai/widget/v2/chat.min.js` | `sha384-mlEtuVKMa+PyLTHKqrCGcvMEKTbkhS4wZbVw89B39K3f7WnGjXkh5N672KmRXPMH` |
+| Full (v2.0.0) | `https://cdn.ihooman.ai/widget/v2.0.0/chat.min.js` | `sha384-mlEtuVKMa+PyLTHKqrCGcvMEKTbkhS4wZbVw89B39K3f7WnGjXkh5N672KmRXPMH` |
+| Latest | `https://cdn.ihooman.ai/widget/latest/chat.min.js` | *(SRI not recommended for latest)* |
+
+### Unminified Bundle (For Development/Debugging)
+
+| Version | URL | SRI Hash |
+|---------|-----|----------|
+| Major (v2) | `https://cdn.ihooman.ai/widget/v2/chat.js` | `sha384-zCM1t6eGYjrL9CIiDq2M+sJzCcPkXGi8UKO6OMglPGsb/vGj6N2urtUat80fzKGE` |
+| Full (v2.0.0) | `https://cdn.ihooman.ai/widget/v2.0.0/chat.js` | `sha384-zCM1t6eGYjrL9CIiDq2M+sJzCcPkXGi8UKO6OMglPGsb/vGj6N2urtUat80fzKGE` |
+| Latest | `https://cdn.ihooman.ai/widget/latest/chat.js` | *(SRI not recommended for latest)* |
+
+## Usage Examples
+
+### With SRI (Recommended for versioned URLs)
+
+```html
+<script src="https://cdn.ihooman.ai/widget/v2.0.0/chat.min.js"
+        integrity="sha384-mlEtuVKMa+PyLTHKqrCGcvMEKTbkhS4wZbVw89B39K3f7WnGjXkh5N672KmRXPMH"
+        crossorigin="anonymous"></script>
+<script>
+  IhoomanChat.init({
+    widgetId: 'YOUR_WIDGET_ID'
+  });
+</script>
+```
+
+### Without SRI (For latest URL)
+
+```html
+<script src="https://cdn.ihooman.ai/widget/latest/chat.min.js"></script>
+<script>
+  IhoomanChat.init({
+    widgetId: 'YOUR_WIDGET_ID'
+  });
+</script>
+```
+
+## Notes
+
+- **SRI hashes are recommended** for versioned URLs to ensure script integrity
+- **SRI is not recommended** for the `latest` URL as the content changes with each release
+- The `crossorigin="anonymous"` attribute is required when using SRI
+- Major version URLs (e.g., `/v2/`) always point to the latest patch within that major version
+- Full version URLs (e.g., `/v2.1.0/`) are immutable and will never change
+
+## Cache Headers
+
+| URL Type | Cache-Control |
+|----------|---------------|
+| Versioned (`/v2/`, `/v2.1.0/`) | `public, max-age=31536000, immutable` |
+| Latest (`/latest/`) | `public, max-age=300` |

package/cdn/cloudflare-config.json

@@ -0,0 +1,203 @@
+{
+  "$schema": "https://developers.cloudflare.com/api/",
+  "_comment": "Cloudflare Configuration for Ihooman Chat Widget CDN",
+  "zone": {
+    "name": "ihooman.ai",
+    "settings": {
+      "ssl": "full_strict",
+      "min_tls_version": "1.2",
+      "http3": "on",
+      "brotli": "on",
+      "minify": {
+        "js": false,
+        "css": false,
+        "html": false
+      }
+    }
+  },
+  "dns_records": [
+    {
+      "type": "CNAME",
+      "name": "cdn",
+      "content": "cdn-ihooman-widget.r2.cloudflarestorage.com",
+      "proxied": true,
+      "comment": "CDN subdomain for widget distribution"
+    }
+  ],
+  "page_rules": [
+    {
+      "_comment": "Versioned URLs - Long cache with immutable",
+      "targets": [
+        {
+          "target": "url",
+          "constraint": {
+            "operator": "matches",
+            "value": "cdn.ihooman.ai/widget/v*"
+          }
+        }
+      ],
+      "actions": [
+        {
+          "id": "cache_level",
+          "value": "cache_everything"
+        },
+        {
+          "id": "edge_cache_ttl",
+          "value": 31536000
+        },
+        {
+          "id": "browser_cache_ttl",
+          "value": 31536000
+        }
+      ],
+      "priority": 1,
+      "status": "active"
+    },
+    {
+      "_comment": "Latest URL - Short cache",
+      "targets": [
+        {
+          "target": "url",
+          "constraint": {
+            "operator": "matches",
+            "value": "cdn.ihooman.ai/widget/latest/*"
+          }
+        }
+      ],
+      "actions": [
+        {
+          "id": "cache_level",
+          "value": "cache_everything"
+        },
+        {
+          "id": "edge_cache_ttl",
+          "value": 300
+        },
+        {
+          "id": "browser_cache_ttl",
+          "value": 300
+        }
+      ],
+      "priority": 2,
+      "status": "active"
+    }
+  ],
+  "cache_rules": [
+    {
+      "name": "Widget Versioned Cache",
+      "description": "Cache versioned widget files for 1 year",
+      "expression": "(http.host eq \"cdn.ihooman.ai\" and starts_with(http.request.uri.path, \"/widget/v\"))",
+      "action": "set_cache_settings",
+      "action_parameters": {
+        "cache": true,
+        "edge_ttl": {
+          "mode": "override_origin",
+          "default": 31536000
+        },
+        "browser_ttl": {
+          "mode": "override_origin",
+          "default": 31536000
+        }
+      }
+    },
+    {
+      "name": "Widget Latest Cache",
+      "description": "Cache latest widget files for 5 minutes",
+      "expression": "(http.host eq \"cdn.ihooman.ai\" and starts_with(http.request.uri.path, \"/widget/latest/\"))",
+      "action": "set_cache_settings",
+      "action_parameters": {
+        "cache": true,
+        "edge_ttl": {
+          "mode": "override_origin",
+          "default": 300
+        },
+        "browser_ttl": {
+          "mode": "override_origin",
+          "default": 300
+        }
+      }
+    }
+  ],
+  "transform_rules": {
+    "response_headers": [
+      {
+        "name": "Widget CORS Headers",
+        "description": "Add CORS headers for widget requests",
+        "expression": "(http.host eq \"cdn.ihooman.ai\" and starts_with(http.request.uri.path, \"/widget/\"))",
+        "action": "set",
+        "action_parameters": {
+          "headers": [
+            {
+              "name": "Access-Control-Allow-Origin",
+              "value": "*"
+            },
+            {
+              "name": "Access-Control-Allow-Methods",
+              "value": "GET, HEAD, OPTIONS"
+            },
+            {
+              "name": "Access-Control-Allow-Headers",
+              "value": "Content-Type, Accept, Origin"
+            },
+            {
+              "name": "Access-Control-Max-Age",
+              "value": "86400"
+            },
+            {
+              "name": "X-Content-Type-Options",
+              "value": "nosniff"
+            },
+            {
+              "name": "X-Frame-Options",
+              "value": "DENY"
+            },
+            {
+              "name": "Referrer-Policy",
+              "value": "strict-origin-when-cross-origin"
+            }
+          ]
+        }
+      },
+      {
+        "name": "Widget Versioned Cache Headers",
+        "description": "Add immutable cache header for versioned files",
+        "expression": "(http.host eq \"cdn.ihooman.ai\" and starts_with(http.request.uri.path, \"/widget/v\") and not starts_with(http.request.uri.path, \"/widget/latest/\"))",
+        "action": "set",
+        "action_parameters": {
+          "headers": [
+            {
+              "name": "Cache-Control",
+              "value": "public, max-age=31536000, immutable"
+            }
+          ]
+        }
+      },
+      {
+        "name": "Widget Latest Cache Headers",
+        "description": "Add short cache header for latest files",
+        "expression": "(http.host eq \"cdn.ihooman.ai\" and starts_with(http.request.uri.path, \"/widget/latest/\"))",
+        "action": "set",
+        "action_parameters": {
+          "headers": [
+            {
+              "name": "Cache-Control",
+              "value": "public, max-age=300"
+            }
+          ]
+        }
+      }
+    ]
+  },
+  "r2_bucket": {
+    "name": "cdn-ihooman-widget",
+    "location": "auto",
+    "cors_rules": [
+      {
+        "allowed_origins": ["*"],
+        "allowed_methods": ["GET", "HEAD"],
+        "allowed_headers": ["*"],
+        "max_age_seconds": 86400
+      }
+    ]
+  }
+}