esender-email-editor 1.0.2 → 1.1.0

package/README.md

@@ -16,19 +16,40 @@ npm install esender-email-editor
 
 ## Peer dependencies
 
-The package externalizes its heavy runtime deps so the host app provides them. Install the tested versions:
+The package externalizes its heavy runtime deps so the host app provides them. Peer ranges are intentionally permissive — any version within the declared range works, and hosts that already satisfy a peer can skip it.
 
 ```bash
 npm install \
-  react@^18.3.1 react-dom@^18.3.1 \
-  antd@^5.25.1 @ant-design/icons@^5.6.1 @ant-design/pro-components@^2.8.7 \
-  @reduxjs/toolkit@^2.1.0 react-redux@^9.2.0 redux-persist@^6.0.0 \
-  mjml-browser@^4.15.3 cheerio@1.0.0-rc.12 \
-  lodash@^4.17.21 axios@^1.9.0 swr@^2.3.3 \
-  framer-motion@^12.12.1 html2canvas@^1.4.1 \
-  styled-components@^6.1.18 use-sync-external-store@^1.5.0
+  react@^18 react-dom@^18 \
+  antd@^5 @ant-design/icons@^5 @ant-design/pro-components@^2 \
+  @reduxjs/toolkit@^2 react-redux@^9 redux-persist@^6 \
+  mjml-browser@^4 cheerio@1.0.0-rc.12 \
+  lodash@^4 axios@^1 swr@^2 \
+  framer-motion@^12 html2canvas@^1 \
+  styled-components@^6 use-sync-external-store@^1
 ```
 
+### Supported version ranges
+
+| Package | Declared range | Notes |
+|---|---|---|
+| `react`, `react-dom` | `>=18.0.0 <19.0.0` | React 19 is **not** supported (see below). |
+| `antd` | `>=5.0.0 <6.0.0` | |
+| `@ant-design/icons` | `>=5.0.0 <6.0.0` | v6 conflicts with `pro-components`. |
+| `@ant-design/pro-components` | `>=2.0.0 <3.0.0` | |
+| `@reduxjs/toolkit` | `>=2.0.0 <3.0.0` | |
+| `react-redux` | `>=8.0.0 <10.0.0` | v8 and v9 both work under React 18. |
+| `redux-persist` | `>=6.0.0 <7.0.0` | |
+| `mjml-browser` | `>=4.15.0 <6.0.0` | v5 still requires `cheerio`. |
+| `lodash` | `>=4.17.0 <5.0.0` | |
+| `axios` | `>=1.0.0 <2.0.0` | |
+| `swr` | `>=2.0.0 <3.0.0` | |
+| `framer-motion` | `>=10.0.0 <13.0.0` | v10+; older majors removed `motion` imports we use. |
+| `html2canvas` | `>=1.0.0 <2.0.0` | |
+| `styled-components` | `>=5.0.0 <7.0.0` | v5 and v6 both work. |
+| `use-sync-external-store` | `>=1.0.0 <2.0.0` | |
+| `cheerio` | `1.0.0-rc.12` | Transitive of `mjml-browser`; host must install. Not declared as a peer. |
+
 ### The non-negotiables
 
 | Constraint | Why |
@@ -49,26 +70,36 @@ export const Composer = () => {
   const ref = useRef<EditorHandle>(null);
   const projectId = 'proj_123';
 
-  const save = async () => {
+  const create = async () => {
+    // Omit templateId → server creates a new template.
     const res = await ref.current?.saveTemplate({ projectId });
     if (!res?.status) console.error(res?.message);
   };
 
-  const load = async () => {
-    await ref.current?.loadTemplate({ projectId }); // omit templateId → latest for project
+  const update = async (templateId: string) => {
+    // Pass templateId → server updates the existing template.
+    await ref.current?.saveTemplate({ projectId, templateId });
+  };
+
+  const load = async (templateId?: string) => {
+    // Omit templateId → loads the project's current template.
+    await ref.current?.loadTemplate({ projectId, templateId });
   };
 
   return (
     <>
       <button onClick={() => console.log(ref.current?.getHtml())}>Export HTML</button>
       <button onClick={() => console.log(ref.current?.getJson())}>Export JSON</button>
-      <button onClick={save}>Save to API</button>
-      <button onClick={load}>Load from API</button>
+      <button onClick={create}>Create</button>
+      <button onClick={() => load()}>Load latest</button>
 
       <Package
         ref={ref}
         apiKey={process.env.NEXT_PUBLIC_ESENDER_KEY!}
         onLicenseError={(err: LicenseError) => console.error(err)}
+        onSave={(e) => console.log('saved', e.templateId, e.response)}
+        onLoad={(e) => console.log('loaded', e.response)}
+        onTemplateChange={(json) => console.log('changed', json)}
         showUndoRedo
       />
     </>
@@ -84,10 +115,16 @@ export const Composer = () => {
 
 | Prop | Type | Required | Description |
 |---|---|---|---|
-| `apiKey` | `string` | yes | eSender license key. Exchanged for a JWT on mount. |
+| `apiKey` | `string` | yes | License key. Exchanged for a JWT on mount. |
+| `apiConfig` | `ApiConfig` | no | Override base URL and any endpoint path. See [API configuration](#api-configuration). |
 | `customButtons` | `ReactNode` | no | Slot rendered in the editor's top-right toolbar. |
 | `showUndoRedo` | `boolean` | no | Show the undo/redo toolbar (default `true`). |
 | `onLicenseError` | `(error: LicenseError) => void` | no | Fires when the license verify call fails. |
+| `onSave` | `(event: SaveEvent) => void` | no | Fires after a successful `saveTemplate()` call. |
+| `onLoad` | `(event: LoadEvent) => void` | no | Fires after a successful `loadTemplate()` call. |
+| `onTemplateChange` | `(json: unknown) => void` | no | Fires on every edit (the exported JSON object — not stringified). |
+| `onHtmlExport` | `(html: string) => void` | no | Fires when `ref.current.getHtml()` is invoked. |
+| `onMediaUpload` | `(event: MediaUploadEvent) => void` | no | Fires after a successful media upload. |
 | `projectId` | `string` | no | **Deprecated.** Ignored at runtime. Kept only for migration. |
 
 ### `EditorHandle` (`ref.current`)
@@ -95,10 +132,68 @@ export const Composer = () => {
 | Method | Returns | Description |
 |---|---|---|
 | `getJson()` | `string` | Stringified MJML JSON tree (export-ready). |
-| `getHtml()` | `string` | Compiled email HTML via `mjml-browser`. |
+| `getHtml()` | `string` | Compiled email HTML via `mjml-browser`. Triggers `onHtmlExport`. |
 | `loadJson(json, raw?)` | `void` | Load a previously saved template. `json` is the same string `getJson()` produced. Pass `null` to clear. |
-| `saveTemplate({ projectId })` | `Promise<TemplateApiResponse>` | POSTs the current HTML + JSON to `/license/template/create`. |
-| `loadTemplate({ projectId, templateId? })` | `Promise<TemplateApiResponse>` | GETs `/license/template/:projectId[/:templateId]` and pipes the JSON back into `loadJson(...)`. |
+| `saveTemplate({ projectId, templateId? })` | `Promise<TemplateApiResponse>` | Create or update a template. Omit `templateId` to create; include it to update. POSTs to the configured `saveTemplateUrl` (default `/template/create`). |
+| `loadTemplate({ projectId, templateId? })` | `Promise<TemplateApiResponse>` | GET the configured `getTemplatesUrl` or `getTemplateByIdUrl` and pipe the JSON back into `loadJson(...)`. |
+
+## API configuration
+
+The editor talks to a small set of backend endpoints. Defaults point at the hosted eSender API, but every URL is overridable via the `apiConfig` prop so consumers can self-host the backend.
+
+```tsx
+<Package
+  ref={ref}
+  apiKey="…"
+  apiConfig={{
+    baseUrl: 'https://api.example.com',
+    verifyUrl: '/license/verify',
+    refreshUrl: '/license/refresh',
+    saveTemplateUrl: '/templates',
+    getTemplatesUrl: '/templates/:projectId',
+    getTemplateByIdUrl: '/templates/:projectId/:templateId',
+    uploadMediaUrl: '/media',
+  }}
+/>
+```
+
+### Defaults
+
+| Field | Default | Method | Purpose |
+|---|---|---|---|
+| `baseUrl` | `https://esender.in/api` | — | Prepended to every relative URL below. |
+| `verifyUrl` | `/verify` | POST | Exchange `apiKey` for access + refresh tokens. |
+| `refreshUrl` | `/refresh` | POST | Exchange a refresh token for a new access token. |
+| `saveTemplateUrl` | `/template/create` | POST | Create (or update, if `templateId` is in the body) a template. |
+| `getTemplatesUrl` | `/template/:projectId` | GET | Load the project's current template. |
+| `getTemplateByIdUrl` | `/template/:projectId/:templateId` | GET | Load a specific template. |
+| `uploadMediaUrl` | `/media/add` | POST (multipart) | Upload an image; returns a hosted URL. |
+
+Template URLs may contain `:projectId` and `:templateId` placeholders. They're substituted at call time and URL-encoded.
+
+## Events
+
+All callbacks are optional. Pass any subset.
+
+| Callback | Argument | Fires when |
+|---|---|---|
+| `onSave` | `{ projectId, templateId?, response }` | `saveTemplate()` returns `status: true`. |
+| `onLoad` | `{ projectId, templateId?, response }` | `loadTemplate()` returns `status: true` and the JSON is applied. |
+| `onTemplateChange` | The exported JSON object | The editor's MJML tree changes (every edit, drag/drop, undo/redo, `loadJson`). |
+| `onHtmlExport` | `string` (the HTML) | A consumer calls `ref.current.getHtml()`. |
+| `onMediaUpload` | `{ url, file?, response? }` | The uploader receives a hosted URL from `uploadMediaUrl`. |
+
+Callbacks are stored internally in a ref, so inline arrow functions are safe — they will not cause spurious re-fires.
+
+## Theme isolation
+
+The editor mounts its own `<ConfigProvider>` with the eSender primary color and uses an internal `getPopupContainer` so antd portals (Tooltip, Dropdown, Select, Drawer, Popover) render inside the editor's root rather than escaping to `document.body`. As a result:
+
+- The editor will **not** restyle your host app's antd components.
+- Your host app's `<ConfigProvider theme={…}>` will **not** restyle the editor.
+- Antd's `message` / `notification` / `Modal.useApp` are scoped via `<App />` inside the editor.
+
+You can safely nest `<Package />` inside a host app that already uses antd with a different theme.
 
 ## License handshake
 
@@ -106,9 +201,9 @@ The editor will not render until the eSender license is verified:
 
 1. Host passes `apiKey` to `<Package />`.
 2. On mount, the package checks `localStorage` for a cached access token.
-3. If absent, it `POST`s to `https://esender.in/api/license/verify` with `x-api-key: <apiKey>`.
+3. If absent, it `POST`s to `{baseUrl}{verifyUrl}` (default `https://esender.in/api/verify`) with `x-api-key: <apiKey>`.
 4. On success the returned `accessToken` and `refreshToken` are stored in `localStorage` and the editor mounts.
-5. While running, the internal axios client attaches the access token to protected calls; on `401` / `token expired` it calls `/license/refresh` once and retries. If refresh fails, tokens are cleared and the next mount re-runs verify.
+5. While running, the internal axios client attaches the access token to protected calls; on `401` / `token expired` it calls `{baseUrl}{refreshUrl}` once and retries. If refresh fails, tokens are cleared and the next mount re-runs verify.
 
 No further token management is required from the host.
 
@@ -196,6 +291,11 @@ import Package, {
   type RefreshTokenResponse,
   type TemplateApiResponse,
   type TemplateDocument,
+  type ApiConfig,
+  type EditorEventCallbacks,
+  type SaveEvent,
+  type LoadEvent,
+  type MediaUploadEvent,
 } from 'esender-email-editor';
 ```