best-email-builder 0.3.0 → 0.5.0

package/dist/types/ai/draft.d.ts

@@ -0,0 +1,163 @@
+/**
+ * The email in a model's answer.
+ * @param {string} text
+ * @returns {EmailDraft}
+ */
+/**
+ * Markup a model escaped twice — `<mj-text align=\\"center\\">` once the JSON
+ * is read — decoded once more. Markup with real quotes is left as it is.
+ * @param {string} markup
+ */
+export function unescapedTwice(markup: string): string;
+export function parseDraft(text: any): {
+    name: string;
+    subject: string;
+    preheader: string;
+    mjml: string;
+};
+/**
+ * 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 };
+    }
+    namespace KEY_MISSING {
+        let status_11: number;
+        export { status_11 as status };
+        let message_11: string;
+        export { message_11 as message };
+    }
+    namespace KEY_REFUSED {
+        let status_12: number;
+        export { status_12 as status };
+        let message_12: string;
+        export { message_12 as message };
+    }
+    namespace MODEL_CREDITS {
+        let status_13: number;
+        export { status_13 as status };
+        let message_13: string;
+        export { message_13 as message };
+    }
+    namespace MODEL_BUSY {
+        let status_14: number;
+        export { status_14 as status };
+        let message_14: string;
+        export { message_14 as message };
+    }
+    namespace MODEL_ERROR {
+        let status_15: number;
+        export { status_15 as status };
+        let message_15: string;
+        export { message_15 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" | "KEY_MISSING" | "KEY_REFUSED" | "MODEL_CREDITS" | "MODEL_BUSY" | "MODEL_ERROR";
+    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/ai/generator.d.ts

@@ -0,0 +1,123 @@
+/**
+ * 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: import("./rewrite.js").RewriteInput, options?: {
+        signal?: AbortSignal;
+    }) => Promise<{
+        text: string;
+        attempts: number;
+    }>;
+    suggestSubjects: (input: import("./subjects.js").SubjectsInput, options?: {
+        signal?: AbortSignal;
+    }) => Promise<{
+        subjects: string[];
+        attempts: number;
+    }>;
+    messages: Record<string, Record<string, string>>;
+};
+/**
+ * @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
+ * @typedef {import('./rewrite.js').RewriteInput} RewriteInput
+ * @typedef {import('./subjects.js').SubjectsInput} SubjectsInput
+ */
+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;
+};
+export type RewriteInput = import("./rewrite.js").RewriteInput;
+export type SubjectsInput = import("./subjects.js").SubjectsInput;

package/dist/types/ai/i18n/fr.d.ts

@@ -0,0 +1,2 @@
+/** @type {Record<string, string>} */
+export const fr: Record<string, string>;

package/dist/types/ai/i18n/index.d.ts

@@ -0,0 +1,2 @@
+/** @type {Record<string, Record<string, string>>} */
+export const AI_MESSAGES: Record<string, Record<string, string>>;

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

@@ -0,0 +1,9 @@
+export { createAi } from "./createAi.js";
+export { AI_MESSAGES } from "./i18n/index.js";
+export { emailWords } from "./subjects.js";
+export { createEmailGenerator } from "./generator.js";
+export { EMAIL_PURPOSES, PURPOSE_CATEGORIES } from "./purposes.js";
+export { REWRITE_ACTIONS, REWRITE_LANGUAGES } from "./rewrite.js";
+export { EmailGenerationError, GENERATION_ERRORS } from "./draft.js";
+export { claudeEmailModel, DEFAULT_CLAUDE_MODEL } from "./claude.js";
+export { AI_PROVIDERS, providerEmailModel, resolveProvider } from "./providers.js";

package/dist/types/ai/keys.d.ts

@@ -0,0 +1,46 @@
+/**
+ * @typedef {{
+ *   provider: Readonly<{id: string, name: string, keyUrl: string|null, keyHint: string, free: string|null}>,
+ *   get: () => string,
+ *   set: (key: string) => void,
+ *   forget: () => void,
+ *   request: () => Promise<string>,
+ *   subscribe: (listener: () => void) => () => void,
+ *   state: () => Readonly<{asking: boolean, refused: boolean, connected: boolean}>,
+ *   answer: (key: string|null) => void,
+ *   refuse: () => void,
+ * }} AiKey
+ *   `state`, `answer` and `refuse` serve the Connect dialog and the module:
+ *   whether the user is being asked, whether the last key was refused.
+ */
+/**
+ * @param {AiProvider} provider
+ * @returns {AiKey}
+ */
+export function createKeyStore(provider: AiProvider): AiKey;
+/**
+ * `state`, `answer` and `refuse` serve the Connect dialog and the module:
+ * whether the user is being asked, whether the last key was refused.
+ */
+export type AiKey = {
+    provider: Readonly<{
+        id: string;
+        name: string;
+        keyUrl: string | null;
+        keyHint: string;
+        free: string | null;
+    }>;
+    get: () => string;
+    set: (key: string) => void;
+    forget: () => void;
+    request: () => Promise<string>;
+    subscribe: (listener: () => void) => () => void;
+    state: () => Readonly<{
+        asking: boolean;
+        refused: boolean;
+        connected: boolean;
+    }>;
+    answer: (key: string | null) => void;
+    refuse: () => void;
+};
+export type AiProvider = import("./providers.js").AiProvider;

package/dist/types/ai/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/ai/providers.d.ts

@@ -0,0 +1,67 @@
+/**
+ * A provider by id, or a provider object of one's own.
+ * @param {string|Partial<AiProvider>} provider
+ * @returns {AiProvider}
+ */
+export function resolveProvider(provider: string | Partial<AiProvider>): AiProvider;
+/**
+ * @param {{
+ *   provider?: string|Partial<AiProvider>,
+ *   apiKey?: string|(() => string|Promise<string>),
+ *   model?: string,
+ *   baseUrl?: string,
+ *   headers?: Record<string, string>,
+ *   maxTokens?: number,
+ *   temperature?: number,
+ *   fetch?: typeof fetch,
+ * }} options
+ *   `apiKey`: the key, or a function that gives it at each call (asked to the
+ *   user, read from a vault); `model`, `baseUrl`: instead of the provider's;
+ *   `maxTokens`: the longest answer (an email is about 6 000).
+ * @returns {import('./generator.js').EmailModel & {provider: AiProvider, model: string}}
+ */
+export function providerEmailModel(options?: {
+    provider?: string | Partial<AiProvider>;
+    apiKey?: string | (() => string | Promise<string>);
+    model?: string;
+    baseUrl?: string;
+    headers?: Record<string, string>;
+    maxTokens?: number;
+    temperature?: number;
+    fetch?: typeof fetch;
+}): import("./generator.js").EmailModel & {
+    provider: AiProvider;
+    model: string;
+};
+/** The providers `providerEmailModel` knows, by id. */
+export const AI_PROVIDERS: Readonly<{
+    openrouter: AiProvider;
+    openai: AiProvider;
+    gemini: AiProvider;
+    groq: AiProvider;
+    mistral: AiProvider;
+    deepseek: AiProvider;
+    cerebras: AiProvider;
+    ollama: AiProvider;
+    'openai-compatible': AiProvider;
+}>;
+export type AnswerFormat = "json_schema" | "json_object" | "text";
+/**
+ * `model`: the default (null: to be given); `keyUrl`: where a user gets a
+ * key; `keyHint`: what a key starts with; `free`: what can be used without
+ * paying, in a few words (null: paid only); `format`: the best answer format
+ * the provider takes; `tokens`: how it names the output limit.
+ */
+export type AiProvider = {
+    id: string;
+    name: string;
+    baseUrl: string;
+    model: string | null;
+    keyUrl: string | null;
+    keyHint: string;
+    free: string | null;
+    format: AnswerFormat;
+    tokens: "max_tokens" | "max_completion_tokens";
+    keyless?: boolean;
+    headers?: Record<string, string>;
+};

package/dist/types/ai/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/ai/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): string;
+/**
+ * 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;
+};

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

@@ -0,0 +1,9 @@
+export { AI_MESSAGES } from "./i18n/index.js";
+export { createEmailGenerator, cleanGenerateInput, MAX_DETAILS_LENGTH } from "./generator.js";
+export { claudeEmailModel, DEFAULT_CLAUDE_MODEL } from "./claude.js";
+export { AI_PROVIDERS, providerEmailModel, resolveProvider } from "./providers.js";
+export { EmailGenerationError, GENERATION_ERRORS, normalizeGeneratedMjml, parseDraft, reviewDraft } from "./draft.js";
+export { EMAIL_PURPOSES, PURPOSE_CATEGORIES, purposeById, purposesByCategory } from "./purposes.js";
+export { SYSTEM_PROMPT, EMAIL_DRAFT_SCHEMA, buildUserPrompt } from "./prompt.js";
+export { REWRITE_ACTIONS, REWRITE_LANGUAGES, REWRITE_SYSTEM_PROMPT, createRewriter, reviewRewrite } from "./rewrite.js";
+export { SUBJECTS_SYSTEM_PROMPT, createSubjectSuggester, emailWords, reviewSubjects } from "./subjects.js";