best-email-builder 0.3.0 → 0.5.0

package/dist/types/server/brandImport.d.ts

@@ -0,0 +1,93 @@
+/**
+ * May the server connect to this IP address? Public unicast only.
+ * @param {string} address
+ */
+export function isPublicAddress(address: string): boolean;
+/**
+ * What the user typed, as the address of a home page: "acme.com" →
+ * "https://acme.com/".
+ * @param {unknown} input
+ */
+export function siteUrl(input: unknown): string;
+/**
+ * GET one address and its redirects, under the rules above.
+ * @param {string} address
+ * @param {{
+ *   allow: (address: string) => boolean,
+ *   allowPort?: (port: number) => boolean,
+ *   signal: AbortSignal,
+ *   maxBytes: number,
+ *   truncate?: boolean,
+ *   accept?: string,
+ *   redirects?: number,
+ * }} options
+ *   `truncate`: past `maxBytes`, keep what came (a page's head, the start of
+ *   a stylesheet) instead of failing.
+ * @returns {Promise<{bytes: Buffer, url: string, contentType: string}>}
+ */
+export function safeGet(address: string, { allow, allowPort, signal, maxBytes, truncate, accept, redirects }: {
+    allow: (address: string) => boolean;
+    allowPort?: (port: number) => boolean;
+    signal: AbortSignal;
+    maxBytes: number;
+    truncate?: boolean;
+    accept?: string;
+    redirects?: number;
+}): Promise<{
+    bytes: Buffer;
+    url: string;
+    contentType: string;
+}>;
+/**
+ * @param {{
+ *   timeoutMs?: number,
+ *   allowAddress?: (address: string) => boolean,
+ *   allowPort?: (port: number) => boolean,
+ * }} [options]
+ *   `allowAddress`, `allowPort`: which IP addresses and ports may be reached
+ *   (default: public addresses, ports 80 and 443). Tests reading a local
+ *   server loosen them; nothing else should.
+ */
+export function createBrandImporter({ timeoutMs, allowAddress, allowPort, }?: {
+    timeoutMs?: number;
+    allowAddress?: (address: string) => boolean;
+    allowPort?: (port: number) => boolean;
+}): {
+    import: (input: unknown, { signal }?: {
+        signal?: AbortSignal;
+    }) => Promise<BrandImport>;
+};
+export namespace BRAND_IMPORT_LIMITS {
+    export let pageBytes: number;
+    export let cssBytes: number;
+    export { MAX_IMAGE_BYTES as logoBytes };
+    export let stylesheets: number;
+    export let logos: number;
+    export let redirects: number;
+    export let timeoutMs: number;
+}
+/** Why an import failed; the handler turns `code` into a message. */
+export class BrandImportError extends Error {
+    /** @param {BrandImportCode} code @param {string} [detail] */
+    constructor(code: BrandImportCode, detail?: string);
+    code: BrandImportCode;
+}
+export type BrandImportCode = "BAD_URL" | "PRIVATE_ADDRESS" | "UNREACHABLE" | "TIMEOUT" | "HTTP_ERROR" | "NOT_HTML" | "TOO_MANY_REDIRECTS" | "TOO_LARGE";
+/**
+ * `LOGO_UNSUPPORTED`: the site's logo is an SVG or a WebP, which most email
+ * apps do not show; `LOGO_ICON`: the site's icon was used instead.
+ */
+export type BrandNote = "LOGO_NOT_FOUND" | "LOGO_UNSUPPORTED" | "LOGO_ICON" | "COLORS_NOT_FOUND";
+export type BrandImport = {
+    brand: import("../features/brand/brand.js").Brand;
+    logo: {
+        bytes: Uint8Array;
+        width: number;
+        height: number;
+        type: string;
+        ext: string;
+        shownWidth: number;
+    } | null;
+    notes: BrandNote[];
+};
+import { MAX_IMAGE_BYTES } from '../validation/images.js';

package/dist/types/server/compileMjml.d.ts

@@ -1,3 +1,5 @@
+/** @param {string} html */
+export function withClientMetas(html: string): string;
 /** @typedef {{line?: number, message: string, tagName?: string}} CompileWarning */
 /**
  * @param {string} mjml

package/dist/types/server/handler.d.ts

@@ -23,8 +23,30 @@ export type HandlerOptions = {
     assetsPath?: string;
     publicUrl?: string | null;
     transport?: import("./sendTest.js").EmailTransport | null;
+    generator?: {
+        generate?: (input: import("../ai/generator.js").GenerateInput, options?: {
+            signal?: AbortSignal;
+        }) => Promise<import("../ai/generator.js").GeneratedEmail>;
+        rewrite?: (input: import("../ai/rewrite.js").RewriteInput, options?: {
+            signal?: AbortSignal;
+        }) => Promise<{
+            text: string;
+        }>;
+        suggestSubjects?: (input: import("../ai/subjects.js").SubjectsInput, options?: {
+            signal?: AbortSignal;
+        }) => Promise<{
+            subjects: string[];
+        }>;
+        messages?: Record<string, Record<string, string>>;
+    } | null;
     variables?: import("../features/variables/catalog.js").EmailVariable[];
     variableStore?: import("./variables.js").VariableRepository | null;
+    brandStore?: import("./brand.js").BrandRepository | null;
+    brandImporter?: {
+        import: (url: string, options?: {
+            signal?: AbortSignal;
+        }) => Promise<import("./brandImport.js").BrandImport>;
+    } | null;
     locale?: string;
     messages?: Record<string, string>;
     lang?: string;
@@ -34,6 +56,10 @@ export type HandlerOptions = {
     rateLimits?: {
         testPerHour?: number;
         uploadsPerHour?: number;
+        generatePerHour?: number;
+        rewritePerHour?: number;
+        subjectsPerHour?: number;
+        brandImportsPerHour?: number;
     };
     onError?: (error: unknown, request: Request) => void;
 };

package/dist/types/server/index.d.ts

@@ -2,12 +2,16 @@ export { createEmailBuilderHandler } from "./handler.js";
 export { toNodeListener } from "./node.js";
 export { HttpError } from "./errors.js";
 export { compileMjml } from "./compileMjml.js";
+export { simulateDarkMode } from "../features/preview/darkMode.js";
 export { prepareMjml } from "../renderer/prepareMjml.js";
 export { createTemplateService, createMemoryTemplateRepository, MAX_ACTIVE_VERSIONS, LIMITS } from "./templates.js";
 export { createAssetService, createMemoryAssetRepository, inspectAsset } from "./assets.js";
 export { compileTemplate, personalize, renderEmail, htmlToText } from "./render.js";
 export { sendTestEmail, MAX_TEST_RECIPIENTS } from "./sendTest.js";
 export { createVariableService, createMemoryVariableRepository } from "./variables.js";
+export { createBrandService, createMemoryBrandRepository } from "./brand.js";
+export { createBrandImporter, isPublicAddress, BrandImportError, BRAND_IMPORT_LIMITS } from "./brandImport.js";
+export { applyBrand, cleanBrand } from "../features/brand/brand.js";
 export { DEFAULT_VARIABLES, defineVariables, mergeVariables, tokenOf, keyFromLabel, validateCustomVariable } from "../features/variables/catalog.js";
 export { applyVariables, applyVariablesToText, mapVariables, sampleValues, usedVariables, unknownVariables } from "../features/variables/service.js";
 export { applyServiceLinks, absoluteAssetUrls, isAssetPath, DEFAULT_ASSETS_PATH } from "../renderer/links.js";
@@ -16,4 +20,4 @@ export { validateProject, assertValidProject } from "../validation/projectValida
 export { qualityReport, GMAIL_CLIP_BYTES } from "../validation/quality.js";
 export { readDocument, createDocument, serializeDocument, EmailDocumentError } from "../core/document.js";
 export { EMAIL_BUILDER_VERSION, EMAIL_DOCUMENT_SCHEMA_VERSION } from "../core/constants.js";
-export { createTranslator, translatorFor, LOCALES } from "../i18n/index.js";
+export { createTranslator, translatorFor, messagesOf, LOCALES } from "../i18n/index.js";

package/dist/types/storage/client.d.ts

@@ -1,34 +1,67 @@
+/**
+ * The HTTP side of a client: JSON in and out, the host's headers, errors as
+ * `StorageError` (with the server's code). Shared by `createHttpStorage` and
+ * the AI module (`best-email-builder/ai`).
+ *
+ * @param {{baseUrl?: string, headers?: Record<string, string> | (() => Record<string, string>), fetch?: typeof fetch}} [options]
+ */
+export function createHttpCaller({ baseUrl, headers, fetch: fetchImpl }?: {
+    baseUrl?: string;
+    headers?: Record<string, string> | (() => Record<string, string>);
+    fetch?: typeof fetch;
+}): {
+    root: string;
+    call: (path: string, init?: RequestInit) => Promise<any>;
+    unwrap: (res: Response) => Promise<any>;
+    doFetch: typeof fetch;
+    extraHeaders: () => Record<string, string>;
+};
 /**
  * Client for the routes of `createEmailBuilderHandler` (`best-email-builder/server`).
+ * The AI is a module of its own: `createAi` (`best-email-builder/ai`).
+ *
+ * `brand: true` turns on the Brand button: the server must have a
+ * `brandStore`, and a `brandImporter` to read a brand from a website
+ * (`brand: {import: false}` when it has none).
  *
  * @param {{
  *   baseUrl?: string,
  *   headers?: Record<string, string> | (() => Record<string, string>),
  *   fetch?: typeof fetch,
+ *   brand?: boolean|{import?: boolean},
  * }} [options]
  * @returns {TemplateStorage}
  */
-export function createHttpStorage({ baseUrl, headers, fetch: fetchImpl }?: {
+export function createHttpStorage({ baseUrl, headers, fetch: fetchImpl, brand }?: {
     baseUrl?: string;
     headers?: Record<string, string> | (() => Record<string, string>);
     fetch?: typeof fetch;
+    brand?: boolean | {
+        import?: boolean;
+    };
 }): TemplateStorage;
 /**
  * In-memory storage, same contract. Documents are kept SERIALIZED.
  * `render` and `sendTest` cannot run in a browser (MJML compiles on the
- * server): pass implementations to enable the preview and test buttons.
+ * server): pass implementations to enable the preview and test buttons;
+ * `importBrand` likewise for reading a brand from a website. The brand itself is kept in memory (`brand`: the
+ * one to start with).
  *
  * @param {{
  *   render?: TemplateStorage['render'],
  *   sendTest?: TemplateStorage['sendTest'],
+ *   importBrand?: TemplateStorage['importBrand'],
+ *   brand?: Brand|null,
  *   assetsPath?: string,
  *   systemVariables?: EmailVariable[],
  * }} [options]  `systemVariables`: keys a custom variable may not take
  * @returns {TemplateStorage & {dump: () => object}}
  */
-export function createMemoryStorage({ render, sendTest, assetsPath, systemVariables }?: {
+export function createMemoryStorage({ render, sendTest, importBrand, brand, assetsPath, systemVariables, }?: {
     render?: TemplateStorage["render"];
     sendTest?: TemplateStorage["sendTest"];
+    importBrand?: TemplateStorage["importBrand"];
+    brand?: Brand | null;
     assetsPath?: string;
     systemVariables?: EmailVariable[];
 }): TemplateStorage & {
@@ -74,6 +107,10 @@ export function createMemoryStorage({ render, sendTest, assetsPath, systemVariab
  *
  * @typedef {{mjml: string, subject?: string|null, preheader?: string|null}} RenderInput
  * @typedef {{html: string, warnings: {message: string}[], quality: {code: string, level: string, message: string}[]}} RenderResult
+ * @typedef {import('../features/brand/brand.js').Brand} Brand
+ * @typedef {{brand: Brand, notes: string[]}} BrandImportResult
+ *   `notes`: what could not be read (`LOGO_NOT_FOUND`, `LOGO_UNSUPPORTED`,
+ *   `LOGO_ICON`, `COLORS_NOT_FOUND`).
  * @typedef {{email: string, ok: boolean, error: string|null}} TestResult
  * @typedef {{sent: number, failed: number, invalid: string[], results: TestResult[]}} SendTestResult
  *
@@ -92,6 +129,9 @@ export function createMemoryStorage({ render, sendTest, assetsPath, systemVariab
  *   listVariables?: () => Promise<EmailVariable[]>,
  *   saveVariable?: (variable: Partial<EmailVariable>, options?: {create?: boolean}) => Promise<EmailVariable>,
  *   deleteVariable?: (key: string) => Promise<void>,
+ *   loadBrand?: () => Promise<Brand>,
+ *   saveBrand?: (brand: Brand) => Promise<Brand>,
+ *   importBrand?: (url: string, options?: {signal?: AbortSignal}) => Promise<BrandImportResult>,
  * }} TemplateStorage
  */
 export class StorageError extends Error {
@@ -149,6 +189,15 @@ export type RenderResult = {
         message: string;
     }[];
 };
+export type Brand = import("../features/brand/brand.js").Brand;
+/**
+ * `notes`: what could not be read (`LOGO_NOT_FOUND`, `LOGO_UNSUPPORTED`,
+ * `LOGO_ICON`, `COLORS_NOT_FOUND`).
+ */
+export type BrandImportResult = {
+    brand: Brand;
+    notes: string[];
+};
 export type TestResult = {
     email: string;
     ok: boolean;
@@ -201,4 +250,9 @@ export type TemplateStorage = {
         create?: boolean;
     }) => Promise<EmailVariable>;
     deleteVariable?: (key: string) => Promise<void>;
+    loadBrand?: () => Promise<Brand>;
+    saveBrand?: (brand: Brand) => Promise<Brand>;
+    importBrand?: (url: string, options?: {
+        signal?: AbortSignal;
+    }) => Promise<BrandImportResult>;
 };

package/dist/types/ui/EmailBuilder.d.ts

@@ -17,10 +17,13 @@
  *   onSaved?: (template: object) => void,
  *   onDirtyChange?: (dirty: boolean) => void,
  *   dirtyCheckRef?: {current: null | (() => boolean)},
+ *   ai?: import('../ai/createAi.js').EmailBuilderAi|null,
  *   className?: string,
  * }} props
+ *   `ai`: the AI module, `createAi()` from `best-email-builder/ai`. Without
+ *   it, no AI button and no AI code.
  */
-export default function EmailBuilder({ locale, messages, onNotify, ...props }: {
+export default function EmailBuilder({ locale, messages, onNotify, ai: aiProp, ...props }: {
     storage?: import("../storage/client.js").TemplateStorage;
     templateId?: string | number | null;
     editor?: import("../core/EmailEditor.js").EmailEditor;
@@ -45,5 +48,6 @@ export default function EmailBuilder({ locale, messages, onNotify, ...props }: {
     dirtyCheckRef?: {
         current: null | (() => boolean);
     };
+    ai?: import("../ai/createAi.js").EmailBuilderAi | null;
     className?: string;
 }): import("react").JSX.Element;

package/dist/types/ui/EmailStudio.d.ts

@@ -15,8 +15,12 @@
  * `libraryProps` / `builderProps` reach only one. Coming back from the editor, the library selects the template that was
  * just edited or created.
  *
+ * `ai` (`createAi()` from `best-email-builder/ai`) goes to the editor only:
+ * without it, the editor has no AI button at all.
+ *
  * @param {{
  *   storage?: import('../storage/client.js').TemplateStorage,
+ *   ai?: import('../ai/createAi.js').EmailBuilderAi|null,
  *   locale?: string,
  *   messages?: Record<string, string>,
  *   onNotify?: (level: 'success'|'info'|'warning'|'error', message: string) => void,
@@ -28,8 +32,9 @@
  *   className?: string,
  * }} props  `onClose`: shows the library's close button.
  */
-export default function EmailStudio({ storage: injectedStorage, locale, messages, onNotify, sender, templates, onClose, libraryProps, builderProps, className, }: {
+export default function EmailStudio({ storage: injectedStorage, ai, locale, messages, onNotify, sender, templates, onClose, libraryProps, builderProps, className, }: {
     storage?: import("../storage/client.js").TemplateStorage;
+    ai?: import("../ai/createAi.js").EmailBuilderAi | null;
     locale?: string;
     messages?: Record<string, string>;
     onNotify?: (level: "success" | "info" | "warning" | "error", message: string) => void;

package/dist/types/ui/PropertiesPanel.d.ts

@@ -1,4 +1,4 @@
-export default function PropertiesPanel({ editor, selection, meta, onMetaChange, changes, actions, showErrors, services, variables, onDismiss, }: {
+export default function PropertiesPanel({ editor, selection, meta, onMetaChange, changes, actions, showErrors, services, ai, variables, onDismiss, }: {
     editor: any;
     selection: any;
     meta: any;
@@ -7,6 +7,7 @@ export default function PropertiesPanel({ editor, selection, meta, onMetaChange,
     actions?: null | undefined;
     showErrors?: boolean | undefined;
     services?: null | undefined;
+    ai?: null | undefined;
     variables?: null | undefined;
     onDismiss?: null | undefined;
 }): import("react").JSX.Element;

package/dist/types/ui/fields.d.ts

@@ -4,9 +4,10 @@ export function emailColor(value: any): string | null;
  * Field of a property. The caller's `key` (element + property) remounts it on
  * every selection change: a draft never carries over from one element to another.
  */
-export function PropertyField({ property, value, onCommit, idPrefix, services }: {
+export function PropertyField({ property, value, fallback, onCommit, idPrefix, services }: {
     property: any;
     value: any;
+    fallback?: string | undefined;
     onCommit: any;
     idPrefix?: string | undefined;
     services?: null | undefined;

package/dist/types/ui/primitives/button.d.ts

@@ -8,5 +8,5 @@ export function Button({ className, variant, size, asChild, type, ...props }: {
 }): import("react").JSX.Element;
 export const buttonVariants: (props?: ({
     variant?: "link" | "default" | "destructive" | "outline" | "secondary" | "ghost" | null | undefined;
-    size?: "default" | "xs" | "sm-compact" | "sm" | "lg" | "icon" | "icon-xs" | "icon-sm-compact" | "icon-sm" | null | undefined;
+    size?: "default" | "icon" | "xs" | "sm-compact" | "sm" | "lg" | "icon-xs" | "icon-sm-compact" | "icon-sm" | null | undefined;
 } & import("class-variance-authority/types").ClassProp) | undefined) => string;

package/dist/types/ui/primitives/color-picker.d.ts

@@ -2,9 +2,10 @@
  * Colour field: a swatch opening a full-spectrum picker (with alpha), a hex
  * input and presets. `value` is `#RRGGBB` or `#RRGGBBAA`; `onChange(hex)`.
  */
-export function ColorPicker({ value, onChange, id, className }: {
+export function ColorPicker({ value, onChange, id, className, placeholder }: {
     value: any;
     onChange: any;
     id: any;
     className: any;
+    placeholder?: string | undefined;
 }): import("react").JSX.Element;

package/dist/types/ui/primitives/searchShortcut.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Ctrl+K (⌘K) puts the cursor in this search field, its words selected, for
+ * as long as the field is on screen — the library's search, the one of
+ * "Generate", the one of the variables menu.
+ * @param {{current: HTMLInputElement|null}} inputRef
+ */
+export function useSearchShortcut(inputRef: {
+    current: HTMLInputElement | null;
+}): void;
+/** The key hint at the end of a search field: Ctrl K (⌘K), or `children` instead. */
+export function SearchKeyHint({ className, children }: {
+    className: any;
+    children?: null | undefined;
+}): import("react").JSX.Element;
+/** What a search field announces to assistive technologies. */
+export const SEARCH_KEYS: "Control+K Meta+K";

package/dist/types/ui/useLayoutWidth.d.ts

@@ -3,7 +3,7 @@ export function layoutFor(width: number): "wide" | "medium" | "narrow";
 /** @param {{current: HTMLElement|null}} ref */
 export function useLayoutWidth(ref: {
     current: HTMLElement | null;
-}): "wide" | "medium" | "narrow";
+}): "medium" | "wide" | "narrow";
 export namespace LAYOUT_BREAKPOINTS {
     let wide: number;
     let medium: number;

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "best-email-builder",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "Drag-and-drop email builder for React: MJML output that renders in Outlook, Gmail and Apple Mail, with server-side rendering, versions, variables and image uploads.",
   "keywords": [
     "email",
     "email-builder",
     "mjml",
     "react",
-    "grapesjs",
+    "email-template",
     "newsletter",
     "drag-and-drop",
     "email-editor"
@@ -28,9 +28,21 @@
   "types": "./dist/types/index.d.ts",
   "typesVersions": {
     "*": {
-      "builder": ["./dist/types/builder.d.ts"],
-      "library": ["./dist/types/library.d.ts"],
-      "server": ["./dist/types/server/index.d.ts"]
+      "builder": [
+        "./dist/types/builder.d.ts"
+      ],
+      "library": [
+        "./dist/types/library.d.ts"
+      ],
+      "server": [
+        "./dist/types/server/index.d.ts"
+      ],
+      "ai": [
+        "./dist/types/ai/index.d.ts"
+      ],
+      "ai/server": [
+        "./dist/types/ai/server.d.ts"
+      ]
     }
   },
   "exports": {
@@ -50,6 +62,14 @@
       "types": "./dist/types/server/index.d.ts",
       "import": "./dist/server.js"
     },
+    "./ai": {
+      "types": "./dist/types/ai/index.d.ts",
+      "import": "./dist/ai.js"
+    },
+    "./ai/server": {
+      "types": "./dist/types/ai/server.d.ts",
+      "import": "./dist/ai-server.js"
+    },
     "./styles.css": "./dist/styles.css",
     "./package.json": "./package.json"
   },
@@ -92,15 +112,15 @@
   "dependencies": {
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
-    "grapesjs": "^0.23.6",
-    "grapesjs-mjml": "1.0.8",
     "lucide-react": "^1.55.0",
     "mjml": "^5.4.1",
+    "mjml-browser": "^5.4.1",
     "radix-ui": "^1.8.0",
     "react-colorful": "^5.8.1",
     "tailwind-merge": "^3.4.1"
   },
   "devDependencies": {
+    "@anthropic-ai/sdk": "^0.130.0",
     "@eslint/js": "^10.0.1",
     "@ladle/react": "^5.1.1",
     "@playwright/test": "^1.64.0",