hivewrite-sdk 1.0.3 → 1.0.6

package/README.md

@@ -1,11 +1,25 @@
 # HiveWrite Email Editor SDK
 
-The HiveWrite Email Editor SDK is a powerful, flexible, and easy-to-integrate drag-and-drop email builder for your React or JavaScript applications.
+A powerful, flexible, and easy-to-integrate drag-and-drop email builder for React or JavaScript applications. Create beautiful, responsive emails with a modern WYSIWYG editor.
 
 [![NPM Version](https://img.shields.io/npm/v/hivewrite-sdk.svg)](https://www.npmjs.com/package/hivewrite-sdk)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-## Installation
+## ✨ Features
+
+- 📧 **Drag & Drop Editor** - Intuitive block-based email building
+- 🎨 **Rich Block Types** - Text, images, buttons, videos, countdown timers, social icons, and more
+- 📱 **Mobile Preview** - Real-time mobile (320px) and desktop preview modes
+- 🌙 **Dark/Light Theme** - Built-in theme support
+- 📤 **HTML/MJML Export** - Export responsive HTML emails compatible with all email clients
+- 🎯 **Merge Tags** - Dynamic content placeholders for personalization
+- 🖼️ **Stock Images** - Built-in Unsplash integration for stock photos
+- 🏗️ **Pre-built Templates** - E-commerce, marketing, and transactional email templates
+- 🔧 **Fully Customizable** - White-labeling, permissions, and branding options
+
+---
+
+## 📦 Installation
 
 ### Via NPM
 ```bash
@@ -19,23 +33,25 @@ npm install hivewrite-sdk
 
 ---
 
-## Quick Start
+## 🚀 Quick Start
 
 ### React Integration
 
 ```tsx
 import React, { useEffect, useRef } from 'react';
-import { EmailEditor } from 'hivewrite-sdk';
+import { hivewrite } from 'hivewrite-sdk';
 
 const MyEditor = () => {
   const containerRef = useRef(null);
 
   useEffect(() => {
     if (containerRef.current) {
-      EmailEditor.init({
+      hivewrite.init({
         apiKey: 'your-api-key',
         container: containerRef.current,
         mode: 'FULL_EDITOR',
+        theme: 'dark',
+        locale: 'en',
         callbacks: {
           onLoad: () => console.log('Editor ready'),
           onSave: (design) => console.log('Saved:', design),
@@ -56,86 +72,210 @@ const MyEditor = () => {
 
 <script src="https://cdn.jsdelivr.net/npm/hivewrite-sdk/bundle.min.js"></script>
 <script>
-  EmailEditor.init({
-    apiKey: 'your-api-key',
-    container: '#editor-container',
-    mode: 'FULL_EDITOR',
-    callbacks: {
-      onLoad: () => console.log('Ready!')
-    }
-  });
+    hivewrite.init({
+        apiKey: 'your-api-key',
+        container: '#editor-container',
+        mode: 'FULL_EDITOR',
+        theme: 'dark',
+        locale: 'en',
+        callbacks: {
+            onLoad: () => console.log('Editor ready'),
+            onSave: (design) => console.log('Saved:', design),
+            onExport: (html) => console.log('HTML:', html)
+        }
+    });
 </script>
 ```
 
 ---
 
-## API Reference
+## 📖 API Reference
+
+### `hivewrite.init(config: SDKConfig)`
 
-### `EmailEditor.init(config: SDKConfig)`
 Initializes and mounts the editor.
 
-#### `SDKConfig` Parameters:
+#### SDKConfig Parameters
 
 | Parameter | Type | Required | Description |
 | :--- | :--- | :--- | :--- |
-| `apiKey` | `string` | Yes | Your HiveWrite API Key. |
-| `container` | `string \| HTMLElement` | Yes | CSS selector or DOM element to mount the editor. |
-| `mode` | `string` | Yes | `'FULL_EDITOR'`, `'DESIGN_ONLY'`, `'READ_ONLY'`, `'HTML_IMPORT'` |
-| `user` | `object` | No | `{ id: string, email: string }` for tracking. |
-| `branding` | `object` | No | Custom white-labeling options (see below). |
-| `mergeTags` | `array` | No | Array of `{ label, value }` for dynamic content. |
-| `callbacks` | `object` | No | Event hooks for SDK actions. |
+| `apiKey` | `string` | Yes | Your HiveWrite API Key |
+| `container` | `string \| HTMLElement` | Yes | CSS selector or DOM element to mount the editor |
+| `mode` | `string` | Yes | `'FULL_EDITOR'`, `'DESIGN_ONLY'`, `'READ_ONLY'` |
+| `theme` | `string` | No | `'light'` (default) or `'dark'` |
+| `locale` | `string` | No | `'en'` (default), `'es'`, or `'fr'` |
+| `branding` | `object` | No | Custom white-labeling options |
+| `permissions` | `object` | No | Toggle features: `exportHTML`, `aiMagic`, `uploadImages` |
+| `mergeTags` | `array` | No | Array of `{ name, value, category }` for dynamic content |
+| `callbacks` | `object` | No | Event hooks for SDK actions |
 
 ---
 
-### Callbacks
+## 🧱 Available Block Types
+
+| Block | Description |
+| :--- | :--- |
+| `text` | Rich text paragraph |
+| `heading1`, `heading2`, `heading3` | Heading elements |
+| `image` | Image with alt text, link, and styling |
+| `button` | CTA button with customizable colors and links |
+| `divider` | Horizontal line separator |
+| `video` | Video embed with poster image and play button |
+| `timer` | Countdown timer (static snapshot in email export) |
+| `icon` | Social/brand icons with shape options (circle, square, none) |
+| `tiktok` | TikTok video embed card |
+| `twitter` | X/Twitter post embed card |
+| `bulletList`, `numberedList` | List elements |
+| `blockquote` | Quote block |
+| `columns2`, `columns3` | Multi-column layouts |
+| `section` | Single column container |
+| `html` | Custom HTML code block |
 
-| Callback | Arguments | Description |
-| :--- | :--- | :--- |
-| `onLoad` | `()` | Triggered when the editor is fully initialized. |
-| `onSave` | `(jsonDesign: any)` | Triggered when the user clicks save or `saveDesign` is called. |
-| `onExport` | `(html: string)` | Triggered when the user exports or `exportHtml` is called. |
-| `onError` | `(err: any)` | Triggered during initialization or processing errors. |
-| `onImageUpload`| `(file: File)` | **Async**. Intercept image uploads and return a URL string. |
-| `onTemplateChange`| `(id: string)` | Triggered when a new template is selected. |
+---
+
+## 📤 Export Options
+
+### Export to HTML
+```javascript
+const result = await hivewrite.export({ 
+  format: 'html',
+  minify: true,
+  inlineCSS: true 
+});
+console.log(result.html);
+```
+
+### Export to JSON (Design)
+```javascript
+const result = await hivewrite.export({ format: 'json' });
+console.log(result.design);
+```
+
+### Export Features
+- **Responsive HTML** - MJML-based output compatible with all email clients
+- **Inline CSS** - Optional CSS inlining for maximum compatibility
+- **Minification** - Reduce file size for production
+- **Static Snapshots** - Countdown timers, videos, and embeds render as email-safe static content
 
 ---
 
-### Methods
+## 🎨 Theming & Branding
 
-#### `loadTemplate(data: { templateId?: string; design?: any })`
-Loads a template by ID or a raw JSON design object.
+### Theme Modes
+```javascript
+hivewrite.init({
+  theme: 'dark', // or 'light'
+  // ...
+});
+
+// Switch theme at runtime
+hivewrite.setTheme('light');
+```
 
-#### `saveDesign(callback?: (json: any) => void)`
-Manually triggers the save process. Returns the JSON design.
+### White Labeling
+```javascript
+branding: {
+  primaryColor: '#6366f1',      // Main accent color
+  secondaryColor: '#8b5cf6',    // Secondary elements
+  accentColor: '#ec4899',       // Highlights and focus
+  logoUrl: 'https://yoursite.com/logo.png',
+  customCSS: '.my-class { color: red; }'
+}
+```
+
+---
 
-#### `exportHtml(callback?: (html: string) => void)`
-Compiles the current design into MJML-based responsive HTML.
+## 🔐 Permissions
 
-#### `importHTML(data: { html: string })`
-Imports raw HTML (Experimental).
+Control what features are available:
+
+```javascript
+permissions: {
+  exportHTML: true,       // Allow HTML export
+  aiMagic: true,          // Enable AI features
+  uploadImages: false     // Disable uploads (stock images only)
+}
+```
 
 ---
 
-## Advanced Features
+## 🏷️ Merge Tags
 
-### White Labeling (`branding`)
-Customize the editor appearance to match your brand:
-- `primaryColor`: Accent color for buttons and highlights.
-- `logoUrl`: Custom logo in the editor sidebar/loading screen.
-- `hidePoweredBy`: Remove HiveWrite branding.
-- `customCSS`: Inject global CSS for deep styling overrides.
+Add dynamic content placeholders:
 
-### Merge Tags
-Provide dynamic tags for personalization:
 ```javascript
 mergeTags: [
-  { label: 'First Name', value: '{{first_name}}' },
-  { label: 'Unsubscribe Link', value: '{{unsub_url}}' }
+  { name: 'First Name', value: '{{first_name}}', category: 'User' },
+  { name: 'Company', value: '{{company}}', category: 'User' },
+  { name: 'Unsubscribe Link', value: '{{unsubscribe_url}}', category: 'Links' }
 ]
 ```
 
 ---
 
-## License
+## 📞 Callbacks
+
+| Callback | Arguments | Description |
+| :--- | :--- | :--- |
+| `onLoad` | `()` | Editor fully initialized |
+| `onSave` | `(json: any)` | User saves or `saveDesign` called |
+| `onExport` | `(html: string)` | User exports or `exportHtml` called |
+| `onError` | `(err: any)` | Initialization or processing error |
+| `onImageUpload` | `(file: File)` | **Async**. Handle image uploads, return URL |
+
+### Image Upload Example
+```javascript
+callbacks: {
+  onImageUpload: async (file) => {
+    const formData = new FormData();
+    formData.append('image', file);
+    const res = await fetch('/api/upload', { method: 'POST', body: formData });
+    const data = await res.json();
+    return data.url; // Return the uploaded image URL
+  }
+}
+```
+
+---
+
+## 📱 Mobile Preview
+
+The editor includes a mobile preview mode (320px width) with automatic scaling:
+- Font sizes scale proportionally
+- Images adapt to container width
+- Spacing adjusts for mobile screens
+
+Toggle between desktop and mobile using the view mode controls in the toolbar.
+
+---
+
+## 📧 Email Client Compatibility
+
+Exported HTML is fully compatible with:
+- Gmail (Web, iOS, Android)
+- Apple Mail
+- Outlook (Desktop, Web, Mobile)
+- Yahoo Mail
+- Samsung Mail
+- And many more...
+
+> **Note**: Some features like videos and iframes are rendered as static fallbacks since email clients don't support embedded media.
+
+---
+
+## 🛠️ Methods
+
+| Method | Description |
+| :--- | :--- |
+| `init(config)` | Initialize the editor |
+| `export({ format, minify?, inlineCSS? })` | Export design to HTML or JSON |
+| `saveTemplate({ name })` | Save as reusable template |
+| `importHTML({ html })` | Import HTML into editor (experimental) |
+| `setTheme(theme)` | Switch theme at runtime |
+| `destroy()` | Unmount and cleanup |
+
+---
+
+## 📄 License
+
 MIT © [Babber Maven](https://github.com/babbermaven)