best-email-builder 0.2.0 → 0.4.0

package/dist/types/features/brand/extract.d.ts

@@ -0,0 +1,61 @@
+/**
+ * The attributes of one start tag, names in lower case.
+ * @param {string} tag  `<img src="…" class=logo>`
+ * @returns {Record<string, string>}
+ */
+export function tagAttributes(tag: string): Record<string, string>;
+/**
+ * What a home page says about its brand.
+ * @param {string} html
+ * @param {string} pageUrl  the address it was read from (after redirects)
+ * @returns {PageReading}
+ */
+export function readPage(html: string, pageUrl: string): PageReading;
+/**
+ * The web-safe stack nearest to a CSS font-family.
+ * @param {string} family
+ * @returns {string|undefined}
+ */
+export function nearestFont(family: string): string | undefined;
+/**
+ * Main color, headings color and font of a site, from its CSS.
+ * @param {{css: string, themeColor?: string}} input
+ * @returns {{primary?: string, heading?: string, font?: string}}
+ */
+export function brandFromCss({ css, themeColor }: {
+    css: string;
+    themeColor?: string;
+}): {
+    primary?: string;
+    heading?: string;
+    font?: string;
+};
+/**
+ * Width and height of a PNG, GIF or JPEG, from its header; null otherwise.
+ * @param {Uint8Array} bytes
+ * @returns {{width: number, height: number}|null}
+ */
+export function imageSize(bytes: Uint8Array): {
+    width: number;
+    height: number;
+} | null;
+/**
+ * The width a logo is shown at in an email: a wordmark wider, a square mark
+ * smaller; never wider than the image itself (a blurry logo is worse than a
+ * small one). Retina images (twice the size shown) are common: halved first.
+ * @param {{width: number, height: number}} size
+ */
+export function logoWidthFor({ width, height }: {
+    width: number;
+    height: number;
+}): number;
+export type PageReading = {
+    name: string;
+    logos: {
+        url: string;
+        from: "schema" | "img" | "icon";
+    }[];
+    stylesheets: string[];
+    css: string;
+    themeColor: string;
+};

package/dist/types/features/brand/index.d.ts

@@ -0,0 +1,2 @@
+/** @type {import('../../core/EmailEditor.js').EmailBuilderFeature} */
+export const brandFeature: import("../../core/EmailEditor.js").EmailBuilderFeature;

package/dist/types/features/brand/messages.d.ts

@@ -0,0 +1,13 @@
+/**
+ * What the user is told about reading a brand from a website: why it failed
+ * (the server's answer) and what it could not find (notes under the field).
+ * English source strings, translated where they are shown.
+ */
+/**
+ * Why a website could not be read: [HTTP status, message], by
+ * BrandImportError code (src/server/brandImport.js).
+ * @type {Record<string, [number, string]>}
+ */
+export const BRAND_IMPORT_ERRORS: Record<string, [number, string]>;
+/** What could not be read, by note code. @type {Record<string, string>} */
+export const BRAND_NOTES: Record<string, string>;

package/dist/types/features/brand/useBrand.d.ts

@@ -0,0 +1,22 @@
+/**
+ * The brand of a storage: `loaded` resolves once it is known ({} when the
+ * storage keeps none, or could not be read — the builder then uses its own look).
+ * @param {any} storage
+ * @returns {BrandEntry}
+ */
+export function brandOf(storage: any): BrandEntry;
+/**
+ * @param {any} storage
+ * @returns {{brand: Brand, setBrand: (brand: Brand) => void}}
+ *   `setBrand`: tells every screen of this storage about a brand just saved.
+ */
+export function useBrand(storage: any): {
+    brand: Brand;
+    setBrand: (brand: Brand) => void;
+};
+export type Brand = import("./brand.js").Brand;
+export type BrandEntry = {
+    value: Brand;
+    loaded: Promise<Brand>;
+    listeners: Set<(brand: Brand) => void>;
+};

package/dist/types/features/generate/GenerateButton.d.ts

@@ -0,0 +1,3 @@
+export default function GenerateButton({ context }: {
+    context: any;
+}): import("react").JSX.Element;

package/dist/types/features/generate/RewriteText.d.ts

@@ -0,0 +1,5 @@
+export default function RewriteText({ editor, selection, rewrite }: {
+    editor: any;
+    selection: any;
+    rewrite: any;
+}): import("react").JSX.Element;

package/dist/types/features/generate/SubjectIdeas.d.ts

@@ -0,0 +1,16 @@
+/**
+ * SUGGEST SUBJECTS — under the subject of the email.
+ *
+ * One click: three other subject lines, drawn from the words of the email.
+ * They are a list to pick from, the user's own subject first: a click puts
+ * one in the field, another click another one, the first row brings the
+ * user's subject back. "More ideas" asks for three new ones; "Done" closes
+ * the list and keeps the subject in the field.
+ */
+export default function SubjectIdeas({ editor, meta, onSubject, suggest, variables }: {
+    editor: any;
+    meta: any;
+    onSubject: any;
+    suggest: any;
+    variables?: null | undefined;
+}): import("react").JSX.Element;

package/dist/types/features/generate/chip.d.ts

@@ -0,0 +1 @@
+export function chipClassName(selected?: boolean): string;

package/dist/types/features/generate/claude.d.ts

@@ -0,0 +1,21 @@
+/**
+ * @param {{
+ *   client: any,
+ *   model?: string,
+ *   effort?: 'low'|'medium'|'high'|'xhigh'|'max',
+ *   rewriteEffort?: 'low'|'medium'|'high'|'xhigh'|'max',
+ *   maxTokens?: number,
+ * }} options
+ *   `effort`: how much the model thinks before writing an email — `low`
+ *   answers faster, `high` takes more care. `rewriteEffort`: the same for
+ *   the light jobs the user waits on — one text rewritten, subject ideas.
+ * @returns {import('./generator.js').EmailModel}
+ */
+export function claudeEmailModel({ client, model, effort, rewriteEffort, maxTokens, }?: {
+    client: any;
+    model?: string;
+    effort?: "low" | "medium" | "high" | "xhigh" | "max";
+    rewriteEffort?: "low" | "medium" | "high" | "xhigh" | "max";
+    maxTokens?: number;
+}): import("./generator.js").EmailModel;
+export const DEFAULT_CLAUDE_MODEL: "claude-opus-5-5";

package/dist/types/features/generate/draft.d.ts

@@ -0,0 +1,122 @@
+/**
+ * The email in a model's answer.
+ * @param {string} text
+ * @returns {EmailDraft}
+ */
+export function parseDraft(text: string): EmailDraft;
+/**
+ * The MJML of a generated email, rewritten as the builder writes it.
+ *
+ * @param {string} mjml
+ * @param {{variables?: {key: string}[], keepImages?: string[]}} [options]
+ *   `variables`: the catalog (`unsubscribe` is always known);
+ *   `keepImages`: image sources kept as they are (the sender's logo).
+ */
+export function normalizeGeneratedMjml(mjml: string, { variables, keepImages }?: {
+    variables?: {
+        key: string;
+    }[];
+    keepImages?: string[];
+}): string;
+/**
+ * What still keeps the email from being used as it is — in English, written
+ * for the model that will correct it.
+ *
+ * @param {EmailDraft} draft
+ * @param {{kind?: string, compileWarnings?: {message: string}[]}} [options]
+ * @returns {{blocking: string[], advice: string[]}}
+ *   `blocking`: the builder must not open it (rejected by the validator);
+ *   `advice`: it opens, but is not what was asked.
+ */
+export function reviewDraft(draft: EmailDraft, { kind, compileWarnings }?: {
+    kind?: string;
+    compileWarnings?: {
+        message: string;
+    }[];
+}): {
+    blocking: string[];
+    advice: string[];
+};
+export namespace GENERATION_ERRORS {
+    namespace NOTHING_TO_GENERATE {
+        let status: number;
+        let message: string;
+    }
+    namespace REFUSED {
+        let status_1: number;
+        export { status_1 as status };
+        let message_1: string;
+        export { message_1 as message };
+    }
+    namespace TRUNCATED {
+        let status_2: number;
+        export { status_2 as status };
+        let message_2: string;
+        export { message_2 as message };
+    }
+    namespace INVALID_ANSWER {
+        let status_3: number;
+        export { status_3 as status };
+        let message_3: string;
+        export { message_3 as message };
+    }
+    namespace INVALID_OUTPUT {
+        let status_4: number;
+        export { status_4 as status };
+        let message_4: string;
+        export { message_4 as message };
+    }
+    namespace NOTHING_TO_REWRITE {
+        let status_5: number;
+        export { status_5 as status };
+        let message_5: string;
+        export { message_5 as message };
+    }
+    namespace REWRITE_REFUSED {
+        let status_6: number;
+        export { status_6 as status };
+        let message_6: string;
+        export { message_6 as message };
+    }
+    namespace REWRITE_UNUSABLE {
+        let status_7: number;
+        export { status_7 as status };
+        let message_7: string;
+        export { message_7 as message };
+    }
+    namespace NOTHING_TO_SUGGEST {
+        let status_8: number;
+        export { status_8 as status };
+        let message_8: string;
+        export { message_8 as message };
+    }
+    namespace SUBJECTS_REFUSED {
+        let status_9: number;
+        export { status_9 as status };
+        let message_9: string;
+        export { message_9 as message };
+    }
+    namespace SUBJECTS_UNUSABLE {
+        let status_10: number;
+        export { status_10 as status };
+        let message_10: string;
+        export { message_10 as message };
+    }
+}
+export class EmailGenerationError extends Error {
+    /**
+     * @param {keyof typeof GENERATION_ERRORS} code
+     * @param {string} [detail]  what went wrong, for logs and for the model
+     */
+    constructor(code: keyof typeof GENERATION_ERRORS, detail?: string);
+    code: "NOTHING_TO_GENERATE" | "REFUSED" | "TRUNCATED" | "INVALID_ANSWER" | "INVALID_OUTPUT" | "NOTHING_TO_REWRITE" | "REWRITE_REFUSED" | "REWRITE_UNUSABLE" | "NOTHING_TO_SUGGEST" | "SUBJECTS_REFUSED" | "SUBJECTS_UNUSABLE";
+    status: number;
+    detail: string;
+}
+export type EmailNode = import("../../engine/model.js").EmailNode;
+export type EmailDraft = {
+    name: string;
+    subject: string;
+    preheader: string;
+    mjml: string;
+};

package/dist/types/features/generate/generator.d.ts

@@ -0,0 +1,118 @@
+/**
+ * The input as the generator uses it: bounded strings, a known purpose or
+ * none, an https logo or none, the brand's colors and font or none.
+ * @param {GenerateInput} input
+ */
+export function cleanGenerateInput(input: GenerateInput): {
+    purpose: import("./purposes.js").EmailPurpose | null;
+    details: string;
+    language: string;
+    sender: {
+        name: string;
+        address: string;
+        logoUrl: string;
+    };
+    brand: {
+        font?: string | undefined;
+        heading?: string | undefined;
+        primary?: string | undefined;
+    };
+    variables: {
+        key: string;
+        label: string;
+    }[];
+};
+/**
+ * @param {{
+ *   model: EmailModel,
+ *   maxAttempts?: number,
+ *   compile?: (mjml: string) => Promise<{warnings?: {message: string}[]}>,
+ * }} options
+ *   `compile`: compiles the MJML and returns MJML's own warnings, fed back to
+ *   the model (the server passes `compileMjml`).
+ */
+export function createEmailGenerator({ model, maxAttempts, compile }?: {
+    model: EmailModel;
+    maxAttempts?: number;
+    compile?: (mjml: string) => Promise<{
+        warnings?: {
+            message: string;
+        }[];
+    }>;
+}): {
+    generate: (input: GenerateInput, { signal }?: {
+        signal?: AbortSignal;
+    }) => Promise<GeneratedEmail>;
+    rewrite: (input: RewriteInput, options?: {
+        signal?: AbortSignal;
+    }) => Promise<{
+        text: string;
+        attempts: number;
+    }>;
+    suggestSubjects: (input: SubjectsInput, options?: {
+        signal?: AbortSignal;
+    }) => Promise<{
+        subjects: string[];
+        attempts: number;
+    }>;
+};
+/**
+ * @typedef {{role: 'user'|'assistant', content: string}} ModelMessage
+ * @typedef {(request: {system: string, messages: ModelMessage[], schema: object, signal?: AbortSignal, task?: 'generate'|'rewrite'|'subjects'}) => Promise<string>} EmailModel
+ *   `task`: a whole email, one text rewritten or subject ideas (lighter jobs:
+ *   a model may answer them with less effort).
+ *
+ * @typedef {{
+ *   purpose?: string|null,
+ *   details?: string,
+ *   language?: string,
+ *   sender?: {name?: string, address?: string, logoUrl?: string},
+ *   brand?: {primary?: string, heading?: string, font?: string},
+ *   variables?: {key: string, label?: string}[],
+ * }} GenerateInput
+ *   `brand`: the colors and font the email is written in (features/brand).
+ *
+ * @typedef {import('./draft.js').EmailDraft & {warnings: string[], attempts: number}} GeneratedEmail
+ */
+export const MAX_DETAILS_LENGTH: 2000;
+export type ModelMessage = {
+    role: "user" | "assistant";
+    content: string;
+};
+/**
+ * `task`: a whole email, one text rewritten or subject ideas (lighter jobs:
+ * a model may answer them with less effort).
+ */
+export type EmailModel = (request: {
+    system: string;
+    messages: ModelMessage[];
+    schema: object;
+    signal?: AbortSignal;
+    task?: "generate" | "rewrite" | "subjects";
+}) => Promise<string>;
+/**
+ * `brand`: the colors and font the email is written in (features/brand).
+ */
+export type GenerateInput = {
+    purpose?: string | null;
+    details?: string;
+    language?: string;
+    sender?: {
+        name?: string;
+        address?: string;
+        logoUrl?: string;
+    };
+    brand?: {
+        primary?: string;
+        heading?: string;
+        font?: string;
+    };
+    variables?: {
+        key: string;
+        label?: string;
+    }[];
+};
+export type GeneratedEmail = import("./draft.js").EmailDraft & {
+    warnings: string[];
+    attempts: number;
+};

package/dist/types/features/generate/index.d.ts

@@ -0,0 +1,2 @@
+/** @type {import('../../core/EmailEditor.js').EmailBuilderFeature} */
+export const generateFeature: import("../../core/EmailEditor.js").EmailBuilderFeature;

package/dist/types/features/generate/prompt.d.ts

@@ -0,0 +1,76 @@
+/**
+ * English name of a language code ("fr" → "French"), the code itself when
+ * the runtime does not know it.
+ * @param {string} code
+ */
+export function languageName(code: string): string;
+/**
+ * The request message.
+ *
+ * @param {{
+ *   purpose?: EmailPurpose|null,
+ *   details?: string,
+ *   language?: string,
+ *   sender?: PromptSender,
+ *   brand?: {primary?: string, heading?: string, font?: string},
+ *   variables?: PromptVariable[],
+ * }} input
+ */
+export function buildUserPrompt({ purpose, details, language, sender, brand, variables }: {
+    purpose?: EmailPurpose | null;
+    details?: string;
+    language?: string;
+    sender?: PromptSender;
+    brand?: {
+        primary?: string;
+        heading?: string;
+        font?: string;
+    };
+    variables?: PromptVariable[];
+}): string;
+/**
+ * The message that asks the model to correct its email.
+ * @param {string[]} problems
+ */
+export function buildRepairPrompt(problems: string[]): string;
+export namespace EMAIL_DRAFT_SCHEMA {
+    let type: string;
+    namespace properties {
+        namespace name {
+            let type_1: string;
+            export { type_1 as type };
+            export let description: string;
+        }
+        namespace subject {
+            let type_2: string;
+            export { type_2 as type };
+            let description_1: string;
+            export { description_1 as description };
+        }
+        namespace preheader {
+            let type_3: string;
+            export { type_3 as type };
+            let description_2: string;
+            export { description_2 as description };
+        }
+        namespace mjml {
+            let type_4: string;
+            export { type_4 as type };
+            let description_3: string;
+            export { description_3 as description };
+        }
+    }
+    let required: string[];
+    let additionalProperties: boolean;
+}
+export const SYSTEM_PROMPT: string;
+export type EmailPurpose = import("./purposes.js").EmailPurpose;
+export type PromptVariable = {
+    key: string;
+    label?: string;
+};
+export type PromptSender = {
+    name?: string;
+    address?: string;
+    logoUrl?: string;
+};

package/dist/types/features/generate/purposes.d.ts

@@ -0,0 +1,48 @@
+/** @param {string|null|undefined} id */
+export function purposeById(id: string | null | undefined): EmailPurpose | null;
+/** Purposes grouped by category, in category order. */
+export function purposesByCategory(purposes?: EmailPurpose[]): {
+    purposes: EmailPurpose[];
+    id: string;
+    label: string;
+}[];
+/**
+ * WHAT AN EMAIL IS FOR — the purposes offered by "Generate".
+ *
+ * Each purpose carries a short BRIEF for the model: the sections and the
+ * information such an email needs (a password reset needs the link's expiry
+ * and a "not you?" line; a sale needs the offer, its end date and a code).
+ * The brief is the part of the prompt that changes with the purpose; the
+ * design and MJML rules stay the same (see `prompt.js`).
+ *
+ * `kind` sets the footer:
+ *   marketing      sent in bulk: an unsubscribe link is required (CAN-SPAM, GDPR);
+ *   transactional  triggered by the recipient's action: a discreet link to the
+ *                  email preferences;
+ *   security       account security: no unsubscribe link at all, a line says
+ *                  why the message was sent.
+ *
+ * Plain data: labels are English keys translated by the interface, briefs
+ * stay in English (they are written for the model, not shown).
+ */
+/**
+ * @typedef {'marketing'|'transactional'|'security'} PurposeKind
+ * @typedef {{id: string, label: string}} PurposeCategory
+ * @typedef {{id: string, label: string, category: string, kind: PurposeKind, brief: string}} EmailPurpose
+ */
+/** @type {PurposeCategory[]} */
+export const PURPOSE_CATEGORIES: PurposeCategory[];
+/** @type {EmailPurpose[]} */
+export const EMAIL_PURPOSES: EmailPurpose[];
+export type PurposeKind = "marketing" | "transactional" | "security";
+export type PurposeCategory = {
+    id: string;
+    label: string;
+};
+export type EmailPurpose = {
+    id: string;
+    label: string;
+    category: string;
+    kind: PurposeKind;
+    brief: string;
+};

package/dist/types/features/generate/rewrite.d.ts

@@ -0,0 +1,83 @@
+/**
+ * @typedef {{
+ *   action: string,
+ *   text: string,
+ *   format?: 'html'|'plain',
+ *   targetLanguage?: string,
+ *   instruction?: string,
+ * }} RewriteInput
+ *   `action`: an id of REWRITE_ACTIONS, `translate` (with `targetLanguage`)
+ *   or `custom` (with `instruction`).
+ */
+/**
+ * The request as the rewriter uses it, or an error when there is nothing to do.
+ * @param {RewriteInput} input
+ */
+export function cleanRewriteInput(input: RewriteInput): {
+    format: "html" | "plain";
+    text: string;
+    change: string;
+};
+/** @param {{format: 'html'|'plain', text: string, change: string}} request */
+export function buildRewritePrompt({ format, text, change }: {
+    format: "html" | "plain";
+    text: string;
+    change: string;
+}): string;
+/** The text in a model's answer: the JSON field, or the bare answer. @param {string} answer */
+export function parseRewrite(answer: string): any;
+/**
+ * What is wrong with a rewritten text, for the model (empty: usable).
+ * @param {string} original @param {string} rewritten @param {'html'|'plain'} format
+ */
+export function reviewRewrite(original: string, rewritten: string, format: "html" | "plain"): string[];
+/**
+ * @param {{model: import('./generator.js').EmailModel, maxAttempts?: number}} options
+ * @returns {(input: RewriteInput, options?: {signal?: AbortSignal}) => Promise<{text: string, attempts: number}>}
+ */
+export function createRewriter({ model, maxAttempts }: {
+    model: import("./generator.js").EmailModel;
+    maxAttempts?: number;
+}): (input: RewriteInput, options?: {
+    signal?: AbortSignal;
+}) => Promise<{
+    text: string;
+    attempts: number;
+}>;
+/**
+ * The actions offered as buttons, in order. `translate` takes a language,
+ * a custom change (`custom`) takes the user's words.
+ */
+export const REWRITE_ACTIONS: {
+    id: string;
+    label: string;
+    change: string;
+}[];
+/** Languages offered by "Translate", shown under their own name. */
+export const REWRITE_LANGUAGES: string[];
+export const MAX_REWRITE_TEXT: 6000;
+export const MAX_REWRITE_INSTRUCTION: 300;
+export namespace REWRITE_SCHEMA {
+    let type: string;
+    namespace properties {
+        namespace text {
+            let type_1: string;
+            export { type_1 as type };
+            export let description: string;
+        }
+    }
+    let required: string[];
+    let additionalProperties: boolean;
+}
+export const REWRITE_SYSTEM_PROMPT: "You are an email copywriter. You rewrite ONE piece of text taken from an email, as asked, and answer with the rewritten text only, in the JSON field \"text\".\n\nThe text is one of:\n- HTML, the content of a text block: keep the same kind of markup. Allowed tags: <p>, <br>, <b>, <strong>, <i>, <em>, <u>, <s>, <span style=\"...\">, <a href=\"...\">, <ul>, <ol>, <li>, <sup>, <sub>. No other tag, no class, no new style. Keep bold, italic and links on the words they belong to.\n- plain text, the label of a button: answer plain text without HTML, a short call to action of a few words.\n\nAlways:\n- Keep every link: each <a href=\"...\"> of the text stays, with its href unchanged; the words of the link may change. Add no link.\n- Keep every merge tag in double braces exactly as written, e.g. {{contact.firstname}} or {{ unsubscribe }}. In {{key|fallback}} only the fallback after \"|\" may change (translated, for instance). Add no merge tag.\n- Keep [placeholders in square brackets]: the user replaces them later. Translate their words when translating.\n- Invent no facts: no new price, date, number, name, guarantee or promise.\n- Write in the language of the text, unless asked to translate.\n- No preamble, no comment, no quotation marks around the text.";
+/**
+ * `action`: an id of REWRITE_ACTIONS, `translate` (with `targetLanguage`)
+ * or `custom` (with `instruction`).
+ */
+export type RewriteInput = {
+    action: string;
+    text: string;
+    format?: "html" | "plain";
+    targetLanguage?: string;
+    instruction?: string;
+};