@souldi/try-on 0.1.0 → 0.1.1

package/README.md

@@ -0,0 +1,214 @@
+# @souldi/try-on
+
+**Drop a virtual try-on button into any e-commerce site in under 5 minutes.**
+
+Let your customers see how clothes look on them — powered by AI, embedded with a single script tag. No iframes, no redirects, no heavy dependencies.
+
+---
+
+## Quick Start
+
+### 1. Install
+
+```bash
+npm install @souldi/try-on
+```
+
+Or load directly via CDN:
+
+```html
+<script src="https://unpkg.com/@souldi/try-on/dist/widget.umd.js"></script>
+```
+
+### 2. Initialize
+
+```html
+<script>
+  VirtualTryOn.init({
+    apiBaseUrl: 'https://api.yourdomain.com',
+    tenantApiKey: 'your_publishable_api_key',
+  });
+</script>
+```
+
+### 3. Add a Try-On Button
+
+```html
+<div id="try-on-jacket"></div>
+
+<script>
+  VirtualTryOn.createButton({
+    containerId: 'try-on-jacket',
+    garmentUrl: 'https://your-cdn.com/images/jacket.png',
+    targetImageId: 'product-image',  // optional: auto-swaps this <img> with the result
+  });
+</script>
+```
+
+That's it. Your customers can now try on clothes with AI.
+
+---
+
+## How It Works
+
+1. Customer clicks the **Try On** button
+2. First-time users verify their email (magic link OTP — no passwords)
+3. They upload a photo of themselves
+4. AI generates a realistic try-on image in seconds
+5. The result appears directly on your product page
+
+Returning users skip straight to step 4 — their session and photo are remembered.
+
+---
+
+## Configuration
+
+### `init(options)`
+
+Call once per page load to configure the widget.
+
+| Option | Type | Required | Description |
+|--------|------|----------|-------------|
+| `apiBaseUrl` | `string` | Yes | Your Souldi API endpoint URL |
+| `tenantApiKey` | `string` | Yes | Your publishable API key (from your Souldi dashboard) |
+| `theme` | `object` | No | Customize the widget appearance ([see Theming](#theming)) |
+| `onGenerationStart` | `function` | No | Called when AI generation begins |
+| `onGenerationSuccess` | `function(resultUrl)` | No | Called with the result image URL on success |
+| `onError` | `function(message)` | No | Called when something goes wrong |
+| `onLogout` | `function` | No | Called when the user logs out |
+
+### `createButton(options)`
+
+Add a try-on button for a specific garment. Call once per product on the page.
+
+| Option | Type | Required | Description |
+|--------|------|----------|-------------|
+| `containerId` | `string` | Yes | ID of the DOM element where the button will render |
+| `garmentUrl` | `string` | Yes | Public URL of the garment image |
+| `targetImageId` | `string` | No | ID of an `<img>` element to auto-swap with the try-on result |
+
+---
+
+## Theming
+
+The widget ships with **dark** and **light** themes and supports deep customization to match your store's brand.
+
+### Theme Modes
+
+```javascript
+VirtualTryOn.init({
+  apiBaseUrl: 'https://api.yourdomain.com',
+  tenantApiKey: 'your_key',
+  theme: {
+    mode: 'light',  // 'dark' (default) or 'light'
+  },
+});
+```
+
+### Custom Brand Colors
+
+Override individual properties to match your brand:
+
+```javascript
+VirtualTryOn.init({
+  apiBaseUrl: 'https://api.yourdomain.com',
+  tenantApiKey: 'your_key',
+  theme: {
+    mode: 'dark',
+    accentColor: '#7C3AED',          // Primary button & accent color
+    accentTextColor: '#FFFFFF',       // Text color on accent buttons
+    borderRadius: '8px',             // Border radius for cards & modals
+    fontFamily: '"Inter", sans-serif',
+    headingFontFamily: '"Playfair Display", serif',
+    buttonOutlineColor: '#7C3AED',   // Outline on the split button
+  },
+});
+```
+
+### Available Theme Options
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `mode` | `'dark' \| 'light'` | `'dark'` | Base color palette |
+| `accentColor` | CSS color | `#adcfab` (dark) / `#4d7c4b` (light) | Primary action color |
+| `accentTextColor` | CSS color | `#193620` (dark) / `#ffffff` (light) | Text on accent buttons |
+| `borderRadius` | CSS value | `12px` | Corner rounding for cards and modals |
+| `fontFamily` | CSS font stack | `'Manrope', system-ui, sans-serif` | Body text font |
+| `headingFontFamily` | CSS font stack | `'Newsreader', serif` | Heading font |
+| `buttonOutlineColor` | CSS color | `transparent` | Border color on the try-on button |
+
+All UI is rendered inside a **Shadow DOM**, so your site's CSS will never leak into the widget and the widget will never break your styles.
+
+---
+
+## Full Example
+
+```html
+<!DOCTYPE html>
+<html>
+<head>
+  <title>My Store</title>
+  <script src="https://unpkg.com/@souldi/try-on/dist/widget.umd.js"></script>
+</head>
+<body>
+  <div class="product-card">
+    <img id="product-image" src="/images/jacket.jpg" alt="Jacket" />
+    <h2>Classic Denim Jacket</h2>
+    <p>$89.00</p>
+
+    <!-- The try-on button renders here -->
+    <div id="try-on-btn"></div>
+  </div>
+
+  <script>
+    VirtualTryOn.init({
+      apiBaseUrl: 'https://api.yourdomain.com',
+      tenantApiKey: 'pk_live_abc123',
+      theme: { mode: 'light', accentColor: '#2563EB' },
+      onGenerationSuccess: (url) => {
+        console.log('Try-on result:', url);
+      },
+      onError: (msg) => {
+        console.error('Try-on error:', msg);
+      },
+    });
+
+    VirtualTryOn.createButton({
+      containerId: 'try-on-btn',
+      garmentUrl: 'https://your-cdn.com/images/jacket-flat.png',
+      targetImageId: 'product-image',
+    });
+  </script>
+</body>
+</html>
+```
+
+---
+
+## Keys & Authentication
+
+| Key | Where to use | Purpose |
+|-----|-------------|---------|
+| **Publishable API Key** (`tenantApiKey`) | In your frontend code | Identifies your store — safe to expose in client-side code |
+| **Secret API Key** | Backend only, never in frontend | Used for server-to-server API calls (manage your account, view usage, etc.) |
+
+Your API keys are available in your **Souldi Dashboard**. The publishable key is scoped to the domains you whitelist — it cannot be used from unauthorized origins.
+
+> **Security note:** The widget communicates exclusively with your Souldi API endpoint. No third-party services are contacted from the browser. All authentication, file uploads, and AI generation are handled server-side.
+
+---
+
+## Browser Support
+
+Works in all modern browsers:
+
+- Chrome 80+
+- Firefox 78+
+- Safari 14+
+- Edge 80+
+
+---
+
+## License
+
+UNLICENSED - Proprietary software. See your Souldi service agreement for usage terms.