@insure-os/client 0.0.3

package/CDN_SETUP.md

@@ -0,0 +1,332 @@
+# CDN Deployment Setup
+
+This document explains how to deploy the InsureOS embeddable script to Cloudflare R2 CDN.
+
+## Prerequisites
+
+1. **Cloudflare R2 Bucket**: Already set up at `cdn.os.insure`
+2. **R2 API Credentials**: Generate from Cloudflare dashboard
+3. **Node.js**: v18 or higher
+4. **pnpm**: Package manager used in this monorepo
+
+## Initial Setup
+
+### 1. Generate R2 API Credentials
+
+1. Log in to Cloudflare Dashboard
+2. Navigate to **R2** > **Overview**
+3. Click **Manage R2 API Tokens**
+4. Click **Create API Token**
+5. Configure the token:
+   - **Token name**: `insureos-cdn-deploy`
+   - **Permissions**: Object Read & Write
+   - **TTL**: Never expire (or set appropriate expiry)
+   - **Bucket**: `insure-os` (or apply to all buckets)
+6. Copy the **Access Key ID** and **Secret Access Key**
+
+### 2. Configure Environment Variables
+
+Create a `.env` file in `packages/client`:
+
+```bash
+cp .env.example .env
+```
+
+Edit `.env` and add your credentials:
+
+```bash
+R2_ACCESS_KEY_ID=your_access_key_id_here
+R2_SECRET_ACCESS_KEY=your_secret_access_key_here
+R2_BUCKET_NAME=insure-os
+CDN_DOMAIN=cdn.os.insure
+```
+
+**Important**: Never commit `.env` to version control!
+
+### 3. Configure R2 Bucket (One-time setup)
+
+#### Enable Public Access via Custom Domain
+
+1. In Cloudflare Dashboard, go to **R2** > **Buckets** > `insure-os`
+2. Click **Settings** tab
+3. Under **Custom Domains**, click **Connect Domain**
+4. Enter `cdn.os.insure` and complete the setup
+5. Cloudflare will automatically configure DNS and SSL
+
+#### Configure CORS (Optional but recommended)
+
+If you need to support older browsers or specific CORS requirements:
+
+1. In the bucket settings, find **CORS Policy**
+2. Add the following configuration:
+
+```json
+[
+  {
+    "AllowedOrigins": ["*"],
+    "AllowedMethods": ["GET", "HEAD"],
+    "AllowedHeaders": ["*"],
+    "ExposeHeaders": ["ETag"],
+    "MaxAgeSeconds": 3600
+  }
+]
+```
+
+### 4. Install Dependencies
+
+```bash
+cd packages/client
+pnpm install
+```
+
+## Deployment Commands
+
+### Build for Production
+
+```bash
+pnpm build:prod
+```
+
+This creates optimized bundles in `dist/`:
+- `index.umd.js` - Universal module for CDN (used for deployment)
+- `index.esm.js` - ES module format
+- `index.cjs` - CommonJS format
+- Type definitions and source maps
+
+### Deploy to CDN
+
+```bash
+# Option 1: Build and deploy separately
+pnpm build:prod
+pnpm publish:cdn
+
+# Option 2: Build and deploy in one command
+pnpm release:cdn
+
+# Option 3: Bump version, build, and deploy
+pnpm release  # Bumps patch version (0.0.0 -> 0.0.1)
+```
+
+### Version Management
+
+Use standard npm versioning:
+
+```bash
+npm version patch  # 0.0.1 -> 0.0.2
+npm version minor  # 0.0.2 -> 0.1.0
+npm version major  # 0.1.0 -> 1.0.0
+```
+
+## CDN Structure
+
+Files are uploaded to multiple paths with different caching strategies:
+
+```
+cdn.os.insure/
+├── v0.0.1/
+│   ├── insureos.min.js         # Immutable, cached forever
+│   ├── insureos.min.js.map     # Source map
+│   └── metadata.json           # Version info + SRI hash
+├── v0/
+│   ├── insureos.min.js         # Auto-updates with v0.x.x releases (1hr cache)
+│   └── insureos.min.js.map
+└── latest/
+    ├── insureos.min.js         # Always latest stable (5min cache)
+    └── insureos.min.js.map
+```
+
+## Usage Examples
+
+### For Production (Recommended)
+
+Use immutable versioned URLs with SRI integrity:
+
+```html
+<script
+  src="https://cdn.os.insure/v0.0.1/insureos.min.js"
+  integrity="sha384-[generated-hash]"
+  crossorigin="anonymous">
+</script>
+```
+
+The deployment script will output the exact snippet with the correct SRI hash.
+
+### For Development
+
+Use the auto-updating major version:
+
+```html
+<script src="https://cdn.os.insure/v0/insureos.min.js"></script>
+```
+
+### For Testing Latest
+
+Use the latest channel (not recommended for production):
+
+```html
+<script src="https://cdn.os.insure/latest/insureos.min.js"></script>
+```
+
+## Integration Example
+
+After loading the script, initialize InsureOS:
+
+```html
+<!DOCTYPE html>
+<html>
+<head>
+  <title>Insurance Quote</title>
+  <script
+    src="https://cdn.os.insure/v0.0.1/insureos.min.js"
+    integrity="sha384-..."
+    crossorigin="anonymous">
+  </script>
+</head>
+<body>
+  <div id="insureos-container"></div>
+
+  <script>
+    const client = new InsureOSScripts.InsureOS({
+      apiKey: 'your-api-key',
+      environment: 'production',
+    });
+
+    client.mount('#insureos-container', {
+      quoteIntentId: 'your-quote-intent-id',
+      // Additional configuration...
+    });
+  </script>
+</body>
+</html>
+```
+
+## CI/CD Integration
+
+### GitHub Actions Example
+
+Create `.github/workflows/deploy-cdn.yml`:
+
+```yaml
+name: Deploy to CDN
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: pnpm/action-setup@v2
+        with:
+          version: 8
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 18
+          cache: 'pnpm'
+
+      - name: Install dependencies
+        run: pnpm install
+
+      - name: Build and deploy
+        env:
+          R2_ACCESS_KEY_ID: ${{ secrets.R2_ACCESS_KEY_ID }}
+          R2_SECRET_ACCESS_KEY: ${{ secrets.R2_SECRET_ACCESS_KEY }}
+          R2_BUCKET_NAME: insure-os
+          CDN_DOMAIN: cdn.os.insure
+        run: |
+          cd packages/client
+          pnpm release:cdn
+```
+
+Add secrets to GitHub:
+- Settings > Secrets > Actions
+- Add `R2_ACCESS_KEY_ID` and `R2_SECRET_ACCESS_KEY`
+
+## Troubleshooting
+
+### Upload Fails
+
+**Problem**: `AccessDenied` error
+
+**Solution**:
+- Verify R2 API token has read/write permissions
+- Check bucket name is correct (`insure-os`)
+- Ensure token hasn't expired
+
+### CDN URL Not Accessible
+
+**Problem**: `404` or SSL errors when accessing `cdn.os.insure`
+
+**Solution**:
+- Verify custom domain is properly connected in R2 settings
+- Check DNS records are propagating (may take a few minutes)
+- Ensure bucket has files uploaded
+
+### CORS Errors in Browser
+
+**Problem**: Browser blocks script loading due to CORS
+
+**Solution**:
+- Add CORS policy to bucket (see setup section)
+- Verify `crossorigin="anonymous"` attribute is present in script tag
+
+### SRI Integrity Check Fails
+
+**Problem**: Browser refuses to execute script due to SRI mismatch
+
+**Solution**:
+- Always use the SRI hash output by the deployment script
+- Don't manually edit the deployed files
+- Clear CDN cache if you re-deployed the same version
+
+## Monitoring
+
+### Check Deployed Version
+
+```bash
+curl https://cdn.os.insure/v0.0.1/metadata.json
+```
+
+Returns:
+
+```json
+{
+  "version": "0.0.1",
+  "timestamp": "2025-10-02T10:30:00.000Z",
+  "sri": "sha384-...",
+  "urls": {
+    "immutable": "https://cdn.os.insure/v0.0.1/insureos.min.js",
+    "major": "https://cdn.os.insure/v0/insureos.min.js",
+    "latest": "https://cdn.os.insure/latest/insureos.min.js"
+  },
+  "size": {
+    "original": 190240,
+    "gzipped": 55281
+  }
+}
+```
+
+### Monitor Usage
+
+Use Cloudflare Analytics:
+1. R2 Dashboard > `insure-os` bucket
+2. View request metrics, bandwidth, and storage
+
+## Security Best Practices
+
+1. **Use SRI hashes** for production deployments
+2. **Pin specific versions** rather than using `latest`
+3. **Rotate API tokens** periodically
+4. **Monitor bucket access** via Cloudflare logs
+5. **Keep credentials secure** - never commit `.env` files
+
+## Support
+
+For issues or questions:
+- Check Cloudflare R2 documentation
+- Review deployment script output for errors
+- Contact DevOps team for access issues

package/DEPLOYMENT.md

@@ -0,0 +1,192 @@
+# Quick Deployment Reference
+
+## 🚀 Deploy New Version
+
+### Simple One-Command Deploy (CDN + NPM)
+
+```bash
+pnpm release
+```
+
+This will:
+1. Bump patch version (0.0.0 → 0.0.1)
+2. Build production bundle
+3. Upload to CDN (cdn.os.insure)
+4. Publish to NPM (@insure-os/scripts)
+
+### Deploy to Specific Destinations
+
+```bash
+# CDN only
+pnpm release:cdn
+
+# NPM only
+pnpm release:npm
+
+# Both (no version bump)
+pnpm release:all
+```
+
+### Manual Version Control
+
+```bash
+# Choose version bump type
+npm version patch   # Bug fixes: 0.0.1 → 0.0.2
+npm version minor   # New features: 0.1.0 → 0.2.0
+npm version major   # Breaking changes: 1.0.0 → 2.0.0
+
+# Then deploy to both
+pnpm release:all
+```
+
+### Build Only (No Deploy)
+
+```bash
+pnpm build:prod
+```
+
+### Individual Publish Commands
+
+```bash
+# CDN
+pnpm publish:cdn
+
+# NPM (test first!)
+pnpm publish:npm:dry    # Dry-run
+pnpm publish:npm        # Actual publish
+```
+
+## 📦 What Gets Deployed
+
+Every deployment uploads to **3 different paths**:
+
+| Path | Cache | Purpose |
+|------|-------|---------|
+| `v0.0.1/insureos.min.js` | Forever | **Production** - Immutable, use with SRI |
+| `v0/insureos.min.js` | 1 hour | **Auto-update** - Gets latest v0.x.x |
+| `latest/insureos.min.js` | 5 min | **Testing** - Always newest |
+
+## 🔗 URLs After Deployment
+
+Base URL: `https://cdn.os.insure`
+
+```
+https://cdn.os.insure/v0.0.1/insureos.min.js          ← Specific version
+https://cdn.os.insure/v0.0.1/insureos.min.js.map      ← Source map
+https://cdn.os.insure/v0.0.1/metadata.json            ← Version info + SRI
+
+https://cdn.os.insure/v0/insureos.min.js              ← Auto-updating v0
+https://cdn.os.insure/latest/insureos.min.js          ← Latest release
+```
+
+## ✅ Verify Deployment
+
+```bash
+# Check deployed version
+curl https://cdn.os.insure/v0.0.1/metadata.json
+
+# Test in browser
+open https://cdn.os.insure/v0.0.1/insureos.min.js
+
+# Check all versions
+curl https://cdn.os.insure/latest/metadata.json
+```
+
+## 📋 After Deployment Checklist
+
+- [ ] Copy the SRI hash from deployment output
+- [ ] Update customer documentation with new version
+- [ ] Test the script in a sample HTML page
+- [ ] Update any example code with new version number
+- [ ] Notify customers if breaking changes in major version
+
+## 🔧 Troubleshooting
+
+### Build fails
+```bash
+# Clean and rebuild
+pnpm clean
+pnpm install
+pnpm build:prod
+```
+
+### Upload fails
+```bash
+# Check environment variables
+cat .env
+
+# Verify R2 credentials are correct
+# - R2_ACCESS_KEY_ID (32 characters)
+# - R2_SECRET_ACCESS_KEY (64 characters)
+```
+
+### CDN not accessible
+- Wait 1-2 minutes for DNS propagation
+- Check Cloudflare R2 bucket has public custom domain enabled
+- Verify `cdn.os.insure` is properly configured in Cloudflare
+
+## 🔐 Security Notes
+
+- Never commit `.env` file (already in .gitignore)
+- Rotate R2 API tokens periodically
+- Always use SRI hashes for production deployments
+- Monitor Cloudflare analytics for unusual traffic
+
+## 📚 Full Documentation
+
+- **Detailed setup**: See [CDN_SETUP.md](./CDN_SETUP.md)
+- **Usage examples**: See [README.md](./README.md)
+- **Development**: See package.json scripts section
+
+## 🆘 Common Commands
+
+```bash
+# Development
+pnpm dev              # Watch mode for local development
+pnpm test             # Run tests
+pnpm lint             # Lint code
+
+# Size analysis
+pnpm size:detailed    # Show bundle sizes with gzip
+
+# CI/CD
+pnpm ci:bundle-check  # Verify bundle size limits
+pnpm ci:performance   # Run performance checks
+```
+
+## 📝 Version History Template
+
+When releasing, document changes:
+
+```markdown
+## v0.0.2 - 2025-10-02
+
+### Added
+- New feature X
+- Support for Y
+
+### Fixed
+- Bug fix Z
+
+### Changed
+- Improved performance of A
+
+### Breaking Changes (for major versions only)
+- Removed deprecated API B
+- Changed behavior of C
+```
+
+## 🎯 Release Workflow
+
+1. **Make changes** → Develop and test locally
+2. **Run tests** → `pnpm test`
+3. **Check bundle size** → `pnpm size:detailed`
+4. **Commit changes** → `git commit -am "feat: description"`
+5. **Deploy** → `pnpm release`
+6. **Verify** → Test on staging site
+7. **Document** → Update CHANGELOG or release notes
+8. **Notify** → Inform team/customers if needed
+
+---
+
+**Need help?** See [CDN_SETUP.md](./CDN_SETUP.md) for troubleshooting or ask your team lead.