esender-email-editor 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Bitbeast Private Limited
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,249 @@
+# antd-email-editor-bitbeast
+
+A drag-and-drop **MJML email editor** for React 18 + Ant Design 5. The editor renders inside a single `<Package />` component, exposes a small imperative API for getting / loading / saving templates, and gates access behind the **eSender license** system.
+
+> **Scope:** this package ships the UI, MJML pipeline, export logic, template save/load API client, and license handshake. Premium / business logic (template storage backend, AI integrations, billing) lives on the eSender backend.
+
+---
+
+## Installation
+
+The package is published on the public **npm registry**.
+
+```bash
+npm install antd-email-editor-bitbeast --legacy-peer-deps
+```
+
+> `--legacy-peer-deps` is required because a transitive dep (`react-giphy-searchbox`) still declares a `react@16` peer range. The runtime works on React 18 — only the peer declaration is stale.
+
+## Peer dependencies
+
+The package externalizes its heavy runtime deps so the host app provides them. Install the tested versions:
+
+```bash
+npm install --legacy-peer-deps \
+  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
+```
+
+### The non-negotiables
+
+| Constraint | Why |
+|---|---|
+| **React must be 18.x** (not 19) | antd v5 only officially supports React 16–18. Under React 19 you will see `[antd: compatible]` warnings and cascading hook bugs in dropdown / tooltip / message. |
+| **Single React copy** in `node_modules` | Two copies of React → `Invalid hook call`. Run `npm ls react` — it must show exactly one version. For Vite hosts use `resolve.dedupe`. |
+| **`cheerio@1.0.0-rc.12` must be installable** | `mjml-browser`'s UMD wrapper `require`s `cheerio`. Without it, `getHtml()` returns non-string and the canvas renders `errors: please check dev console`. Newer cheerio 1.x is ESM-only and breaks Vite's optimizer. |
+| **`@ant-design/icons` stays on v5** | `@ant-design/pro-components` resolves icons v5. Installing v6 forces `--legacy-peer-deps` everywhere and can cause runtime mismatches. |
+
+## Quick start
+
+```tsx
+import { useRef } from 'react';
+import Package, { type EditorHandle, type LicenseError } from 'antd-email-editor-bitbeast';
+import 'antd-email-editor-bitbeast/styles.css';
+
+export const Composer = () => {
+  const ref = useRef<EditorHandle>(null);
+  const projectId = 'proj_123';
+
+  const save = async () => {
+    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
+  };
+
+  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>
+
+      <Package
+        ref={ref}
+        apiKey={process.env.NEXT_PUBLIC_ESENDER_KEY!}
+        onLicenseError={(err: LicenseError) => console.error(err)}
+        showUndoRedo
+      />
+    </>
+  );
+};
+```
+
+`Package` is the default export. Named import (`{ Package }`) also works.
+
+## Public API
+
+### `<Package />` props
+
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `apiKey` | `string` | yes | eSender license key. Exchanged for a JWT on mount. |
+| `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. |
+| `projectId` | `string` | no | **Deprecated.** Ignored at runtime. Kept only for migration. |
+
+### `EditorHandle` (`ref.current`)
+
+| Method | Returns | Description |
+|---|---|---|
+| `getJson()` | `string` | Stringified MJML JSON tree (export-ready). |
+| `getHtml()` | `string` | Compiled email HTML via `mjml-browser`. |
+| `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(...)`. |
+
+## License handshake
+
+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>`.
+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.
+
+No further token management is required from the host.
+
+## Styling
+
+Import the bundled stylesheet once at your app root:
+
+```ts
+import 'antd-email-editor-bitbeast/styles.css';
+```
+
+The package depends on Ant Design 5. Antd v5's runtime CSS-in-JS handles its own component styles, so you do **not** need a separate antd reset. The bundled `styles.css` only contains editor chrome overrides (CKEditor 5, Quill, antd tweaks).
+
+## SSR / Next.js / Remix
+
+`Package` touches the DOM, drag-and-drop, and `localStorage`, so it must render on the client only. Use dynamic import:
+
+```tsx
+// Next.js (app/ or pages/)
+import dynamic from 'next/dynamic';
+
+const Package = dynamic(() => import('antd-email-editor-bitbeast'), { ssr: false });
+```
+
+Module-level code in the package is SSR-safe (all `window` / `document` / `localStorage` access is `typeof`-guarded), so importing it on the server will not crash — only mounting it will.
+
+## Routing
+
+`Package` mounts its own `MemoryRouter` internally so it can coexist with a host app's `BrowserRouter` (Next.js, react-router, Remix, etc.). The internal routes never affect the host URL. Do **not** wrap `<Package />` in a second router — and do not need to.
+
+## Vite consumer config
+
+```ts
+// vite.config.ts
+import { defineConfig } from 'vite';
+import react from '@vitejs/plugin-react';
+
+export default defineConfig({
+  plugins: [react()],
+  resolve: {
+    dedupe: ['react', 'react-dom', 'react/jsx-runtime', 'react/jsx-dev-runtime'],
+  },
+  optimizeDeps: {
+    include: [
+      'antd-email-editor-bitbeast',
+      'mjml-browser', 'cheerio',
+      'antd', '@ant-design/icons', '@ant-design/pro-components',
+      'react-is', 'react-redux',
+      'use-sync-external-store',
+      'use-sync-external-store/shim',
+      'use-sync-external-store/shim/with-selector',
+      'use-sync-external-store/with-selector',
+      '@reduxjs/toolkit', 'axios', 'framer-motion', 'html2canvas',
+      'lodash', 'redux-persist', 'styled-components', 'swr', 'classnames',
+    ],
+  },
+});
+```
+
+After changing dep versions or reinstalling the package, restart with `vite --force` so the optimizer rebuilds.
+
+## Bundle
+
+- Single ESM + CJS bundle (`dist/index.js`, `dist/index.cjs`), tree-shakeable.
+- Type declarations at `dist/index.d.ts`.
+- CSS extracted to `dist/styles.css` (not auto-injected — import it once).
+- All peer deps (React, antd, mjml-browser, lodash, redux, etc.) are externalized.
+- `console.*` and `debugger` are stripped from the production bundle.
+- The bundle is minified by terser and obfuscated twice (rollup-time + post-build). Debug from source.
+
+## TypeScript surface
+
+```ts
+import Package, {
+  // value (also available as default)
+  // Package,
+  // types
+  type EditorHandle,
+  type PackageProps,
+  type SaveTemplateOptions,
+  type LoadTemplateOptions,
+  type LicenseError,
+  type LicenseErrorCode,
+  type VerifyLicenseResponse,
+  type RefreshTokenResponse,
+  type TemplateApiResponse,
+  type TemplateDocument,
+} from 'antd-email-editor-bitbeast';
+```
+
+## Troubleshooting
+
+| Symptom | Cause / fix |
+|---|---|
+| `Invalid hook call` | Two copies of React are loaded. Run `npm ls react` — must show one version. Vite: add `resolve.dedupe`. |
+| Canvas shows `errors: please check dev console` | `cheerio` is not resolvable in the host. Install `cheerio@1.0.0-rc.12` (newer versions are ESM-only and break Vite). |
+| Vite: `'classnames' does not provide an export named 'default'` | Vite hasn't pre-bundled antd's CJS transitive deps. Add the `optimizeDeps.include` list above, delete `node_modules/.vite`, and restart with `vite --force`. |
+| antd `[antd: compatible] React is 16 ~ 18` warning + broken dropdowns / tooltips | You are on React 19. Downgrade to React 18.3.1. |
+| Editor shows "Editor unavailable" forever | License verify failed. Check the `/license/verify` network response, confirm `apiKey`, watch `onLicenseError`. |
+| Editor renders fine then suddenly fails | Access token expired and refresh failed. Clear `localStorage` (`esender.accessToken`, `esender.refreshToken`) and reload. |
+| `You cannot render a <Router> inside another <Router>` | You're on an outdated version. Update — current package uses `MemoryRouter` internally. |
+| Renders during SSR throw | Mount the component client-side only (see Next.js example above). |
+
+## Publishing (maintainers)
+
+```bash
+# 1. Bump version (semver)
+npm version patch  # or minor / major
+
+# 2. prepublishOnly chains: check-secrets → typecheck → rollup (clean + bundle + obfuscate + bundle check)
+npm publish
+```
+
+Pre-publish hooks:
+- `check-secrets` — scans for forbidden files (`.env`, `.pem`, `.key`) and provider-prefixed key strings (AWS / OpenAI / SendGrid / Google / GitHub / Slack / private-key blocks).
+- `typecheck` — `tsc --noEmit`.
+- `rollup` — produces `dist/index.js`, `dist/index.cjs`, `dist/index.d.ts`, `dist/styles.css`, then runs `scripts/obfuscate.js` and `scripts/check-bundle.js`.
+
+Inspect the publish tarball before pushing:
+
+```bash
+npm pack --dry-run
+```
+
+Only the contents of `dist/`, `README.md`, `LICENSE`, and `package.json` ship.
+
+## Versioning
+
+Strict semver:
+- **PATCH** — bug fixes, no API changes.
+- **MINOR** — additive features, no breakage.
+- **MAJOR** — breaking changes to `<Package />` props or `EditorHandle`.
+
+## License
+
+MIT — see [LICENSE](LICENSE).