webhanger 1.0.1 → 1.0.4

package/README.md

@@ -1,26 +1,51 @@
-# webhanger
+# WebHanger
 
-Component-as-a-Service platform. Bundle UI components once, deliver them securely across any website via edge CDN.
+> **Component-as-a-Service (CaaS)** — Bundle once. Encrypt with AES-256. Deliver via edge CDN. Load anywhere with zero code.
+
+WebHanger is a secure, edge-delivered component distribution platform. Think of it as npm for UI components — but instead of installing packages, you deploy encrypted components to a CDN and load them into any website with a single HTML tag.
 
 ---
 
-## Install
+## Packages
+
+| Package | Install | Description |
+|---|---|---|
+| `webhanger` | `npm install -g webhanger` | CLI + Node.js library |
+| `webhanger-front` | `npm install webhanger-front` | Browser SDK |
+
+---
+
+## Quick Start
 
 ```bash
-# CLI (global)
+# 1. Install CLI
 npm install -g webhanger
 
-# Node.js library
-npm install webhanger
+# 2. Setup your project (provisions S3 + CloudFront automatically)
+wh init
+
+# 3. Deploy all components, build site, zip for upload — one command
+wh ship ./components ./docs 1.0.0 ./dist
+```
+
+Load in any website — zero JS required:
+
+```html
+<script src="https://unpkg.com/webhanger-front@latest/browser.min.js"></script>
+<script>WebHangerFront.initialize("./wh-manifest.json");</script>
+
+<wh-component name="navbar"></wh-component>
+<wh-component name="hero"></wh-component>
+<wh-component name="footer"></wh-component>
 ```
 
 ---
 
-## CLI
+## CLI Reference
 
 ### `wh init`
 
-Interactive setup. Provisions your storage + CDN + database.
+Interactive project setup. Provisions infrastructure automatically.
 
 ```bash
 wh init
@@ -30,147 +55,483 @@ Prompts:
 - Project name
 - Storage provider: `s3` | `r2` | `minio` | `local`
 - Database provider: `firebase` | `supabase` | `mongodb`
-- Credentials for each
+- Credentials
+
+For **S3**: automatically creates the bucket, configures CORS + versioning, spins up a CloudFront distribution. No AWS Console needed.
+
+Optional: setup Cloudflare Edge Worker for token validation + geo routing at the edge.
+
+Generates `webhanger.config.json`.
+
+---
+
+### `wh ship` ⭐ The main command
+
+Deploy + build + zip in one shot.
+
+```bash
+wh ship <components-dir> <site-dir> [version] [out-dir]
+```
+
+```bash
+wh ship ./components ./docs 1.0.0 ./dist
+```
+
+What it does:
+1. Deploys all components (bundle → AES encrypt → upload → sign → register)
+2. Resolves dependency graph
+3. Writes `wh-manifest.json` (no sensitive data in HTML)
+4. Production builds the site (minify HTML, inline CSS/JS)
+5. Zips output for direct upload
 
-For `s3` — automatically creates the S3 bucket, configures CORS, versioning, and spins up a CloudFront distribution. No manual AWS Console steps needed.
+```
+🚀 [1/4] Deploying components...
+  navbar@1.0.0...    ✅
+  hero@1.0.0...      ✅
+
+🔍 [2/4] Resolving dependency graph...
 
-Generates `webhanger.config.json` in your project root.
+🏗️  [3/4] Building ./docs → ./dist...
+  index.html         4.2 kB
+
+📦 [4/4] Zipping ./dist...
+
+✅ Ship complete!
+  Deploy zip: ./deploy.zip (12.4 kB)
+```
+
+Upload `deploy.zip` to Netlify, S3, cPanel, or any static host.
 
 ---
 
 ### `wh deploy`
 
-Bundle and deploy a component.
+Deploy a single component.
 
 ```bash
 wh deploy <component-dir> <name> <version>
+wh deploy ./components/navbar navbar 1.0.0
 ```
 
+Prompts for token (auto-generate or custom) and expiry (never or seconds).
+
+---
+
+### `wh graph-deploy`
+
+Deploy all components in a directory and resolve the dependency graph.
+
 ```bash
-wh deploy ./components/navbar navbar 1.0.0
+wh graph-deploy <components-dir> [version] [out-dir]
+wh graph-deploy ./components 1.0.0 ./output
 ```
 
-Your component folder should contain any of:
-- `index.html` — markup
-- `style.css` — styles
-- `script.js` — behaviour
+---
 
-All three are bundled into a single encrypted payload, uploaded to your storage, and registered in your database.
+### `wh build`
 
-You'll be asked:
-- Custom token? (or auto-generate)
-- Set expiry? (or never expire)
+Production build — minifies HTML, inlines local CSS/JS.
 
-Output:
+```bash
+wh build <src-dir> [out-dir]
+wh build ./docs ./dist
 ```
-✅ Deployed successfully!
-📦 CDN URL : https://xxx.cloudfront.net/components/navbar@1.0.0.js
-🔐 Token   : abc123...
-⏱  Expires : 0 (never)
+
+---
+
+### `wh zip`
+
+Zip a directory for deployment.
+
+```bash
+wh zip <src-dir> [out-file]
+wh zip ./dist ./deploy.zip
 ```
 
 ---
 
-## Node.js API
+### `wh analyze`
+
+Detect framework, styling approach, and CDN dependencies automatically.
+
+```bash
+wh analyze ./components/navbar
+```
+
+```
+🔍 Component Analysis
+
+Framework : vanilla
+Styling   : tailwind
+Imports   : gsap, axios
+CDN Assets:
+  [script] https://cdn.tailwindcss.com
+  [script] https://cdnjs.cloudflare.com/ajax/libs/gsap/3.12.2/gsap.min.js
+```
+
+---
+
+### `wh convert`
+
+Convert a vanilla HTML/CSS/JS component to any framework.
+
+```bash
+wh convert <dir> <name> <target> [out-dir]
+wh convert ./components/navbar navbar react ./output
+```
+
+Supported targets: `react` `vue` `svelte` `next` `angular` `astro`
+
+---
+
+### `wh access`
+
+Role-based access control for teams.
+
+```bash
+wh access grant          # generate API key with role
+wh access revoke <key>   # revoke a key
+wh access list           # list all keys
+```
+
+Roles:
+
+| Role | deploy | read | delete | manage_access |
+|---|---|---|---|---|
+| owner | ✅ | ✅ | ✅ | ✅ |
+| admin | ✅ | ✅ | ✅ | ✅ |
+| deployer | ✅ | ✅ | ❌ | ❌ |
+| viewer | ❌ | ✅ | ❌ | ❌ |
+
+---
+
+### `wh edge-init`
+
+Setup Cloudflare Edge Worker for production-grade delivery.
+
+```bash
+wh edge-init
+# then:
+cd edge && wrangler deploy
+```
+
+---
+
+## Component Structure
+
+```
+components/
+  navbar/
+    index.html              ← markup
+    style.css               ← styles
+    script.js               ← behaviour
+    webhanger.component.json ← assets + dependencies
+```
+
+### `webhanger.component.json`
+
+```json
+{
+  "assets": [
+    { "type": "script", "url": "https://cdn.tailwindcss.com" },
+    { "type": "script", "url": "https://cdnjs.cloudflare.com/ajax/libs/gsap/3.12.2/gsap.min.js" }
+  ],
+  "dependencies": ["navbar@1.0.0", "chart@2.0.0"]
+}
+```
+
+CDN assets are auto-detected by `wh analyze` and merged automatically on deploy.
+
+---
+
+## Dependency Graph
+
+npm-like dependency resolution for UI components.
+
+```
+dashboard@1.0.0
+  ├── navbar@1.0.0
+  └── statsbar@1.0.0
+        └── chart@1.0.0
+```
+
+- Depth-first resolution
+- Circular dependency detection with full chain error
+- Deps load before parent component
+- Stored in Firestore per project
+
+```bash
+wh graph-deploy ./components 1.0.0 ./output
+```
+
+Programmatic:
 
 ```js
-import { WebHanger } from "webhanger";
+import { resolveGraph } from "webhanger";
+const graph = await resolveGraph(config.db, projectId, "dashboard", "1.0.0");
+// Returns: [chart, navbar, statsbar, dashboard] — deps first
+```
+
+---
+
+## Security
+
+### AES-256-GCM Encryption
+
+Every component chunk (HTML/CSS/JS) is encrypted before upload.
+
+```
+Key     = SHA-256(projectId + salt)
+Payload = iv:tag:ciphertext  (base64)
+Salts   = "::html" | "::css" | "::js"
+```
+
+### HMAC-SHA256 Signed URLs
 
-const wh = new WebHanger();
 ```
+token = HMAC-SHA256(projectId:componentPath:expires, secretKey)
+```
+
+### Integrity Check
+
+SHA-256 hash of raw content stored in payload. Verified after decryption — detects tampering.
 
-### `wh.deploy(componentDir, name, version, options?)`
+### Domain Restriction
 
 ```js
-const result = await wh.deploy("./components/navbar", "navbar", "1.0.0", {
-    expiresInSeconds: 86400,  // optional — omit for no expiry
-    token: "my-custom-token", // optional — omit to auto-generate
-    dependencies: ["sidebar@1.0.0"] // optional
+WebHangerFront.load(url, pid, token, 0, "[data-wh]", null, [], {
+    allowedDomains: ["mysite.com", "app.io"]
 });
+```
+
+### Token Expiry
 
-// result: { cdnUrl, token, expires }
+```js
+// Never expires
+wh.deploy("./navbar", "navbar", "1.0.0");
+
+// Expires in 24 hours
+wh.deploy("./navbar", "navbar", "1.0.0", { expiresInSeconds: 86400 });
 ```
 
-### `wh.resolve(name, version?)`
+### Manifest-based Delivery
 
-Fetch component metadata and verify token.
+Tokens, projectId, and CDN URLs never appear in HTML. Fetched at runtime from `wh-manifest.json`.
 
-```js
-const component = await wh.resolve("navbar", "1.0.0");
-// { cdnUrl, token, expires, dependencies }
+---
+
+## Edge Worker (Cloudflare Workers)
+
+Runs at the edge before S3:
+
+- HMAC token validation
+- Version resolution (`latest` → `1.2.0` from KV)
+- Geo-based routing (India → ap-south-1, Europe → eu-west-1)
+- Rate limiting (100 req/min per IP)
+
+```bash
+wh init  # answer yes to edge worker setup
+cd edge && wrangler deploy
 ```
 
-### `wh.resign(name, version, options?)`
+Update `cdn.url` in `webhanger.config.json` to your worker URL — all requests now go through the edge.
+
+---
 
-Rotate token without redeploying the component.
+## Multi-CDN Failover
+
+```json
+{
+  "cdn": {
+    "url": "https://primary.cloudfront.net",
+    "fallbacks": [
+      "https://fallback.r2.dev",
+      "https://backup.b-cdn.net"
+    ]
+  }
+}
+```
+
+SDK tries each URL in order. If primary fails, automatically falls back — zero code changes needed.
+
+---
+
+## Browser SDK
+
+### Zero-code (recommended)
+
+```html
+<script src="https://unpkg.com/webhanger-front@latest/browser.min.js"></script>
+<script>WebHangerFront.initialize("./wh-manifest.json");</script>
+
+<wh-component name="navbar"></wh-component>
+<wh-component name="hero"></wh-component>
+<wh-component name="footer" sandbox></wh-component>
+```
+
+### Manual load
 
 ```js
-const result = await wh.resign("navbar", "1.0.0", {
-    expiresInSeconds: 3600
+WebHangerFront.load(
+    cdnUrl,      // string or array (multi-CDN)
+    projectId,   // decrypt key
+    token,       // HMAC token
+    expires,     // unix timestamp, 0 = never
+    selector,    // CSS selector, default "[data-wh]"
+    onSignal,    // optional signal callback
+    deps,        // optional pre-resolved deps array
+    options      // optional options object
+);
+```
+
+### Lifecycle hooks
+
+```js
+WebHangerFront.load(url, pid, token, 0, "[data-wh]", null, [], {
+    beforeMount: ({ html }) => showSpinner(),
+    afterMount:  ({ target }) => hideSpinner(),
+    onError:     (err) => showFallback(err),
+    sandbox:     true,                          // Shadow DOM isolation
+    allowedDomains: ["mysite.com"]              // domain restriction
 });
-// { cdnUrl, token, expires }
 ```
 
-### `wh.remove(name, version)`
+### Signal callback
 
-Delete a component from storage.
+```js
+WebHangerFront.load(url, pid, token, 0, "[data-wh]", ({ stage, ...detail }) => {
+    // stages: start → fetching → assets → deps → injecting → done | error
+    console.log(stage, detail.time, detail.source);
+});
+```
+
+### Plugin system
 
 ```js
-await wh.remove("navbar", "1.0.0");
+WebHangerFront.use({
+    install({ on, emit }) {
+        on("load",   ({ time, source }) => analytics.track("load", { time, source }));
+        on("error",  ({ message })      => errorTracker.capture(message));
+        on("metric", ({ name, value })  => dashboard.update(name, value));
+    }
+});
 ```
 
-### `wh.getConfig()`
+### Observability
 
-Returns the loaded `webhanger.config.json`.
+```js
+WebHangerFront.on("load",   ({ time, source }) => console.log(time, source));
+WebHangerFront.on("metric", ({ name, value })  => console.log(name, value));
+
+console.log(WebHangerFront.metrics);
+// { loads: 5, cacheHits: 3, errors: 0, totalTime: 420 }
+```
+
+### Hard flush
 
 ```js
-const config = wh.getConfig();
+await WebHangerFront.clearCache();
+// Clears: localStorage, IndexedDB, SW caches, sessionStorage, unregisters SW
 ```
 
 ---
 
-## Named exports
+## Caching
+
+| Layer | Used for |
+|---|---|
+| `localStorage` | Components < 50KB |
+| `IndexedDB` | Components ≥ 50KB |
+| Service Worker | Offline fallback |
+
+**Stale-while-revalidate** — returns cached version instantly, refreshes in background.
 
-Use individual functions directly without instantiation.
+---
+
+## Node.js API
+
+```js
+import { WebHanger } from "webhanger";
+const wh = new WebHanger();
+
+// Deploy
+const result = await wh.deploy("./components/navbar", "navbar", "1.0.0", {
+    expiresInSeconds: 86400,   // optional
+    token: "custom-token",     // optional
+    dependencies: ["chart@1.0.0"]
+});
+// { cdnUrl, cdnUrls, token, expires, dependencies }
+
+// Resolve
+const comp = await wh.resolve("navbar", "1.0.0");
+
+// Rotate token without redeploying
+await wh.resign("navbar", "1.0.0", { expiresInSeconds: 3600 });
+
+// Delete from storage
+await wh.remove("navbar", "1.0.0");
+
+// Get config
+const config = wh.getConfig();
+```
+
+### Named exports
 
 ```js
 import {
-    bundle,
-    signUrl,
-    verifyToken,
-    generateSecretKey,
-    upload,
-    remove,
-    registerComponent,
-    getComponent,
-    provisionBucket,
-    provisionCloudFront,
-    deploy,
+    bundle, encrypt, decrypt, integrityHash,
+    signUrl, verifyToken, generateSecretKey,
+    upload, remove,
+    registerComponent, getComponent,
+    deploy, resolveGraph,
+    convert, analyzeComponent,
+    build,
+    grantAccess, revokeAccess, checkPermission, listAccess, generateApiKey,
+    provisionBucket, provisionCloudFront,
     loadConfig
 } from "webhanger";
 ```
 
 ---
 
-## webhanger.config.json
+## Storage Providers
 
-Generated by `wh init`. Keep this file private — never commit it.
+| Provider | Notes |
+|---|---|
+| `s3` | AWS S3 — auto-provisions bucket + CloudFront |
+| `r2` | Cloudflare R2 — zero egress fees |
+| `minio` | Self-hosted MinIO — S3-compatible |
+| `local` | Local disk — dev/testing only |
+
+## Database Providers
+
+| Provider | Notes |
+|---|---|
+| `firebase` | Firebase Firestore — free tier, real-time |
+| `supabase` | Supabase Postgres — open source |
+| `mongodb` | MongoDB Atlas — flexible documents |
+
+---
+
+## `webhanger.config.json`
 
 ```json
 {
   "project": "my-app",
   "projectId": "wh_1234567890",
-  "secretKey": "your-secret-key",
+  "secretKey": "64-char-hex-secret",
   "webHangerVersion": "1.0.0",
   "storage": {
     "provider": "s3",
     "accessKey": "...",
     "secretKey": "...",
     "bucket": "my-bucket",
-    "region": "ap-south-1"
+    "region": "ap-south-1",
+    "distributionId": "EXXXXX"
   },
   "cdn": {
-    "url": "https://xxx.cloudfront.net"
+    "url": "https://primary.cloudfront.net",
+    "fallbacks": ["https://fallback.r2.dev"]
   },
   "db": {
     "provider": "firebase",
@@ -179,26 +540,55 @@ Generated by `wh init`. Keep this file private — never commit it.
 }
 ```
 
+> Keep this file private. Never commit it. Add to `.gitignore`.
+
 ---
 
-## Component folder structure
+## Architecture
 
 ```
-components/
-  navbar/
-    index.html
-    style.css
-    script.js
+Developer
+  └── wh ship ./components ./docs
+        ├── wh analyze    → detect Tailwind, GSAP, deps
+        ├── wh bundle     → html + css + js → single payload
+        ├── AES-256-GCM   → encrypt each chunk (SHA-256 key)
+        ├── SHA-256 hash  → integrity fingerprint
+        ├── S3 upload     → store encrypted payload
+        ├── HMAC sign     → project-scoped signed URL
+        ├── Firestore     → register metadata + dep graph
+        ├── wh build      → minify HTML, inline assets
+        └── wh zip        → deploy.zip ready for upload
+
+Browser
+  └── <wh-component name="navbar">
+        ├── fetch wh-manifest.json
+        ├── check token expiry
+        ├── stale-while-revalidate cache
+        ├── fetch from CloudFront (or Edge Worker)
+        │     └── Edge: validate token + geo route + rate limit
+        ├── multi-CDN failover if primary fails
+        ├── load CDN assets (Tailwind, GSAP, etc.)
+        ├── resolve + load dependency graph
+        ├── AES-256-GCM decrypt in memory
+        ├── SHA-256 integrity verify
+        ├── domain restriction check
+        ├── inject CSS → HTML → JS (or Shadow DOM)
+        ├── fire lifecycle hooks
+        └── emit metrics + plugin events
 ```
 
-All files are optional except at least one of `index.html` or `script.js`.
+---
+
+## Real-World Use Cases
+
+- **Enterprise micro-frontends** — shared UI across 50+ apps, update once
+- **Education platforms** — push UI updates to all school sites instantly
+- **Low-bandwidth regions** — cache once, serve offline via Service Worker
+- **Security platforms** — inject warnings/banners dynamically across sites
+- **White-label SaaS** — per-tenant component customization
 
 ---
 
-## Security
+## License
 
-- Every component is encrypted using XOR cipher with `projectId` as the key
-- Each chunk (html/css/js) uses a different salt — `::html`, `::css`, `::js`
-- CDN URLs are HMAC-SHA256 signed and scoped to your project
-- Tokens can carry expiry or be permanent — your choice
-- CloudFront forces HTTPS only
+ISC