@emailens/engine 0.3.1 → 0.5.0

package/dist/maizzle-YDSYDVSM.js

@@ -0,0 +1,8 @@
+import {
+  compileMaizzle
+} from "./chunk-SZ5O5PDZ.js";
+import "./chunk-PFONR3YC.js";
+export {
+  compileMaizzle
+};
+//# sourceMappingURL=maizzle-YDSYDVSM.js.map

package/dist/maizzle-YDSYDVSM.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/mjml-IYGC6AOM.js

@@ -0,0 +1,8 @@
+import {
+  compileMjml
+} from "./chunk-W4SPWESS.js";
+import "./chunk-PFONR3YC.js";
+export {
+  compileMjml
+};
+//# sourceMappingURL=mjml-IYGC6AOM.js.map

package/dist/mjml-IYGC6AOM.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/react-email-AN62KVVF.js

@@ -0,0 +1,8 @@
+import {
+  compileReactEmail
+} from "./chunk-LW2IMTBA.js";
+import "./chunk-PFONR3YC.js";
+export {
+  compileReactEmail
+};
+//# sourceMappingURL=react-email-AN62KVVF.js.map

package/dist/react-email-AN62KVVF.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/react-email-BQljgXbo.d.cts

@@ -0,0 +1,289 @@
+type ExportScope = "all" | "current";
+interface ExportPromptOptions {
+    originalHtml: string;
+    warnings: CSSWarning[];
+    scores: Record<string, {
+        score: number;
+        errors: number;
+        warnings: number;
+        info: number;
+    }>;
+    scope: ExportScope;
+    selectedClientId?: string;
+    format?: "html" | "jsx" | "mjml" | "maizzle";
+}
+declare function generateFixPrompt(options: ExportPromptOptions): string;
+
+interface TokenEstimate {
+    /** Estimated input tokens (prompt + system prompt) */
+    inputTokens: number;
+    /** Estimated output tokens (fixed code response) */
+    estimatedOutputTokens: number;
+    /** Raw character count of the prompt */
+    promptCharacters: number;
+    /** Character count of just the HTML being fixed */
+    htmlCharacters: number;
+    /** Total warnings included in the prompt */
+    warningCount: number;
+    /** How many warnings are structural (need HTML changes) */
+    structuralCount: number;
+    /** Whether warnings were truncated to fit within limits */
+    truncated: boolean;
+    /** Number of warnings removed during truncation */
+    warningsRemoved: number;
+}
+/**
+ * Extended return type from `estimateAiFixTokens()` that includes both the
+ * token metrics AND the (potentially truncated) warnings list. The `warnings`
+ * field is used internally by `generateAiFix()` to build the prompt with the
+ * truncated set, but is NOT exposed in `AiFixResult.tokenEstimate` to keep
+ * the public API clean.
+ */
+interface TokenEstimateWithWarnings extends TokenEstimate {
+    /** The warnings after smart truncation (may be shorter than the input list) */
+    warnings: CSSWarning[];
+}
+interface EstimateOptions extends Omit<ExportPromptOptions, "warnings"> {
+    warnings: CSSWarning[];
+    /**
+     * Maximum input tokens to target. If the estimated prompt exceeds
+     * this, warnings will be truncated (info first, then duplicates).
+     * Defaults to 16000 (~56KB of prompt text).
+     */
+    maxInputTokens?: number;
+    /**
+     * Optional precise token counter. If provided, it will be called
+     * with the final prompt text for an exact count. Consumers can wire
+     * this to `anthropic.messages.countTokens()`.
+     */
+    tokenCounter?: (text: string) => Promise<number> | number;
+    /**
+     * Token count for the system prompt. Added to the input token estimate
+     * since the system prompt counts against the context window. Defaults
+     * to 250 (matching the built-in AI_FIX_SYSTEM_PROMPT). Set to 0 if
+     * not using a system prompt, or override for custom system prompts.
+     */
+    systemPromptTokens?: number;
+}
+/**
+ * Estimate tokens for an AI fix prompt BEFORE making the API call.
+ * Use this to show cost estimates, check limits, and decide whether
+ * to proceed.
+ *
+ * @example
+ * ```ts
+ * const estimate = await estimateAiFixTokens({
+ *   originalHtml: html,
+ *   warnings,
+ *   scores,
+ *   scope: "all",
+ *   format: "jsx",
+ * });
+ *
+ * console.log(`~${estimate.inputTokens} input tokens`);
+ * console.log(`~${estimate.estimatedOutputTokens} output tokens`);
+ * console.log(`Truncated: ${estimate.truncated}`);
+ * ```
+ */
+declare function estimateAiFixTokens(options: EstimateOptions): Promise<TokenEstimateWithWarnings>;
+/**
+ * Quick synchronous heuristic token count. No deps, no API calls.
+ * Accuracy: within ~10-15% of real Claude tokenizer for code/HTML.
+ */
+declare function heuristicTokenCount(text: string): number;
+
+type SupportLevel = "supported" | "partial" | "unsupported" | "unknown";
+type Framework = "jsx" | "mjml" | "maizzle";
+type InputFormat = "html" | Framework;
+interface EmailClient {
+    id: string;
+    name: string;
+    category: "webmail" | "desktop" | "mobile";
+    engine: string;
+    darkModeSupport: boolean;
+    icon: string;
+}
+interface CodeFix {
+    before: string;
+    after: string;
+    language: "html" | "css" | "jsx" | "mjml" | "maizzle";
+    description: string;
+}
+type FixType = "css" | "structural";
+interface CSSWarning {
+    severity: "error" | "warning" | "info";
+    client: string;
+    property: string;
+    message: string;
+    suggestion?: string;
+    fix?: CodeFix;
+    fixIsGenericFallback?: boolean;
+    fixType?: FixType;
+    line?: number;
+    selector?: string;
+}
+/**
+ * Callback that sends a prompt to an LLM and returns the text response.
+ * Consumers bring their own AI provider (Anthropic SDK, Vercel AI, etc.).
+ */
+type AiProvider = (prompt: string) => Promise<string>;
+interface AiFixResult {
+    /** The fixed email code returned by the AI */
+    code: string;
+    /** The raw prompt that was sent to the AI */
+    prompt: string;
+    /** Number of warnings the fix was targeting */
+    targetedWarnings: number;
+    /** How many of those had fixType: "structural" */
+    structuralCount: number;
+    /** Token estimate for the AI call */
+    tokenEstimate: TokenEstimate;
+}
+interface TransformResult {
+    clientId: string;
+    html: string;
+    warnings: CSSWarning[];
+}
+interface PreviewResult {
+    id: string;
+    originalHtml: string;
+    transforms: TransformResult[];
+    cssReport: CSSWarning[];
+    createdAt: string;
+}
+interface DiffResult {
+    clientId: string;
+    scoreBefore: number;
+    scoreAfter: number;
+    scoreDelta: number;
+    fixed: CSSWarning[];
+    introduced: CSSWarning[];
+    unchanged: CSSWarning[];
+}
+interface SpamIssue {
+    rule: string;
+    severity: "error" | "warning" | "info";
+    message: string;
+    detail?: string;
+}
+interface SpamReport {
+    score: number;
+    level: "low" | "medium" | "high";
+    issues: SpamIssue[];
+}
+interface SpamAnalysisOptions {
+    /** Value of the List-Unsubscribe header, if present */
+    listUnsubscribeHeader?: string;
+    /** Type of email — transactional emails are exempt from unsubscribe requirements */
+    emailType?: "marketing" | "transactional";
+}
+interface LinkIssue {
+    severity: "error" | "warning" | "info";
+    rule: string;
+    message: string;
+    href?: string;
+    text?: string;
+}
+interface LinkReport {
+    totalLinks: number;
+    issues: LinkIssue[];
+    breakdown: {
+        https: number;
+        http: number;
+        mailto: number;
+        tel: number;
+        anchor: number;
+        javascript: number;
+        protocolRelative: number;
+        other: number;
+    };
+}
+interface AccessibilityIssue {
+    severity: "error" | "warning" | "info";
+    rule: string;
+    message: string;
+    element?: string;
+    details?: string;
+}
+interface AccessibilityReport {
+    score: number;
+    issues: AccessibilityIssue[];
+}
+interface ImageIssue {
+    rule: string;
+    severity: "error" | "warning" | "info";
+    message: string;
+    src?: string;
+}
+interface ImageInfo {
+    src: string;
+    alt: string | null;
+    width: string | null;
+    height: string | null;
+    isTrackingPixel: boolean;
+    dataUriBytes: number;
+    issues: string[];
+}
+interface ImageReport {
+    total: number;
+    totalDataUriBytes: number;
+    issues: ImageIssue[];
+    images: ImageInfo[];
+}
+
+/**
+ * Unified error class for all email compilation failures.
+ *
+ * Replaces the per-format error classes (ReactEmailCompileError,
+ * MjmlCompileError, MaizzleCompileError) with a single class that
+ * carries the source format and failure phase.
+ */
+declare class CompileError extends Error {
+    name: string;
+    readonly format: Exclude<InputFormat, "html">;
+    readonly phase: "validation" | "transpile" | "execution" | "render" | "compile";
+    constructor(message: string, format: CompileError["format"], phase: CompileError["phase"]);
+}
+
+/**
+ * Sandbox strategy for JSX execution.
+ *
+ * - `"vm"` — `node:vm` with hardened globals. Fast, zero-dependency,
+ *   but NOT a true security boundary (prototype-chain escapes are possible).
+ *   Suitable for CLI / local use where users run their own code.
+ *
+ * - `"isolated-vm"` (default) — Separate V8 isolate via the `isolated-vm`
+ *   npm package. True heap isolation; escapes require a V8 engine bug.
+ *   Requires `isolated-vm` to be installed (native addon).
+ *
+ * - `"quickjs"` — Validates code structure in a QuickJS WASM sandbox, then
+ *   executes in `node:vm` for React rendering. Security is equivalent to
+ *   `node:vm` — the QuickJS phase validates import restrictions only.
+ *   No native addons needed, but only supports ES2020 and is slower.
+ *   For true isolation on servers, use `isolated-vm`.
+ */
+type SandboxStrategy = "vm" | "isolated-vm" | "quickjs";
+interface CompileReactEmailOptions {
+    /**
+     * Sandbox strategy to use for executing user JSX code.
+     * @default "isolated-vm"
+     */
+    sandbox?: SandboxStrategy;
+}
+/**
+ * Compile a React Email JSX/TSX source string into an HTML email string.
+ *
+ * Pipeline:
+ *  1. Validate input (size, basic checks)
+ *  2. Transpile JSX/TSX → CommonJS JS using sucrase
+ *  3. Execute inside a sandbox (configurable strategy)
+ *  4. Render the exported component to a full HTML email string
+ *
+ * Requires peer dependencies: sucrase, react, @react-email/components,
+ * @react-email/render. Additionally:
+ *  - sandbox "isolated-vm" requires `isolated-vm`
+ *  - sandbox "quickjs" requires `quickjs-emscripten`
+ */
+declare function compileReactEmail(source: string, options?: CompileReactEmailOptions): Promise<string>;
+
+export { type AiProvider as A, type CSSWarning as C, type DiffResult as D, type EmailClient as E, type Framework as F, type ImageReport as I, type LinkReport as L, type PreviewResult as P, type SpamAnalysisOptions as S, type TransformResult as T, type CodeFix as a, type ExportPromptOptions as b, type AiFixResult as c, type SpamReport as d, type AccessibilityReport as e, type AccessibilityIssue as f, CompileError as g, type CompileReactEmailOptions as h, type EstimateOptions as i, type ExportScope as j, type FixType as k, type ImageInfo as l, type ImageIssue as m, type InputFormat as n, type LinkIssue as o, type SandboxStrategy as p, type SpamIssue as q, type SupportLevel as r, type TokenEstimate as s, type TokenEstimateWithWarnings as t, estimateAiFixTokens as u, generateFixPrompt as v, heuristicTokenCount as w, compileReactEmail as x };

package/dist/react-email-BQljgXbo.d.ts

@@ -0,0 +1,289 @@
+type ExportScope = "all" | "current";
+interface ExportPromptOptions {
+    originalHtml: string;
+    warnings: CSSWarning[];
+    scores: Record<string, {
+        score: number;
+        errors: number;
+        warnings: number;
+        info: number;
+    }>;
+    scope: ExportScope;
+    selectedClientId?: string;
+    format?: "html" | "jsx" | "mjml" | "maizzle";
+}
+declare function generateFixPrompt(options: ExportPromptOptions): string;
+
+interface TokenEstimate {
+    /** Estimated input tokens (prompt + system prompt) */
+    inputTokens: number;
+    /** Estimated output tokens (fixed code response) */
+    estimatedOutputTokens: number;
+    /** Raw character count of the prompt */
+    promptCharacters: number;
+    /** Character count of just the HTML being fixed */
+    htmlCharacters: number;
+    /** Total warnings included in the prompt */
+    warningCount: number;
+    /** How many warnings are structural (need HTML changes) */
+    structuralCount: number;
+    /** Whether warnings were truncated to fit within limits */
+    truncated: boolean;
+    /** Number of warnings removed during truncation */
+    warningsRemoved: number;
+}
+/**
+ * Extended return type from `estimateAiFixTokens()` that includes both the
+ * token metrics AND the (potentially truncated) warnings list. The `warnings`
+ * field is used internally by `generateAiFix()` to build the prompt with the
+ * truncated set, but is NOT exposed in `AiFixResult.tokenEstimate` to keep
+ * the public API clean.
+ */
+interface TokenEstimateWithWarnings extends TokenEstimate {
+    /** The warnings after smart truncation (may be shorter than the input list) */
+    warnings: CSSWarning[];
+}
+interface EstimateOptions extends Omit<ExportPromptOptions, "warnings"> {
+    warnings: CSSWarning[];
+    /**
+     * Maximum input tokens to target. If the estimated prompt exceeds
+     * this, warnings will be truncated (info first, then duplicates).
+     * Defaults to 16000 (~56KB of prompt text).
+     */
+    maxInputTokens?: number;
+    /**
+     * Optional precise token counter. If provided, it will be called
+     * with the final prompt text for an exact count. Consumers can wire
+     * this to `anthropic.messages.countTokens()`.
+     */
+    tokenCounter?: (text: string) => Promise<number> | number;
+    /**
+     * Token count for the system prompt. Added to the input token estimate
+     * since the system prompt counts against the context window. Defaults
+     * to 250 (matching the built-in AI_FIX_SYSTEM_PROMPT). Set to 0 if
+     * not using a system prompt, or override for custom system prompts.
+     */
+    systemPromptTokens?: number;
+}
+/**
+ * Estimate tokens for an AI fix prompt BEFORE making the API call.
+ * Use this to show cost estimates, check limits, and decide whether
+ * to proceed.
+ *
+ * @example
+ * ```ts
+ * const estimate = await estimateAiFixTokens({
+ *   originalHtml: html,
+ *   warnings,
+ *   scores,
+ *   scope: "all",
+ *   format: "jsx",
+ * });
+ *
+ * console.log(`~${estimate.inputTokens} input tokens`);
+ * console.log(`~${estimate.estimatedOutputTokens} output tokens`);
+ * console.log(`Truncated: ${estimate.truncated}`);
+ * ```
+ */
+declare function estimateAiFixTokens(options: EstimateOptions): Promise<TokenEstimateWithWarnings>;
+/**
+ * Quick synchronous heuristic token count. No deps, no API calls.
+ * Accuracy: within ~10-15% of real Claude tokenizer for code/HTML.
+ */
+declare function heuristicTokenCount(text: string): number;
+
+type SupportLevel = "supported" | "partial" | "unsupported" | "unknown";
+type Framework = "jsx" | "mjml" | "maizzle";
+type InputFormat = "html" | Framework;
+interface EmailClient {
+    id: string;
+    name: string;
+    category: "webmail" | "desktop" | "mobile";
+    engine: string;
+    darkModeSupport: boolean;
+    icon: string;
+}
+interface CodeFix {
+    before: string;
+    after: string;
+    language: "html" | "css" | "jsx" | "mjml" | "maizzle";
+    description: string;
+}
+type FixType = "css" | "structural";
+interface CSSWarning {
+    severity: "error" | "warning" | "info";
+    client: string;
+    property: string;
+    message: string;
+    suggestion?: string;
+    fix?: CodeFix;
+    fixIsGenericFallback?: boolean;
+    fixType?: FixType;
+    line?: number;
+    selector?: string;
+}
+/**
+ * Callback that sends a prompt to an LLM and returns the text response.
+ * Consumers bring their own AI provider (Anthropic SDK, Vercel AI, etc.).
+ */
+type AiProvider = (prompt: string) => Promise<string>;
+interface AiFixResult {
+    /** The fixed email code returned by the AI */
+    code: string;
+    /** The raw prompt that was sent to the AI */
+    prompt: string;
+    /** Number of warnings the fix was targeting */
+    targetedWarnings: number;
+    /** How many of those had fixType: "structural" */
+    structuralCount: number;
+    /** Token estimate for the AI call */
+    tokenEstimate: TokenEstimate;
+}
+interface TransformResult {
+    clientId: string;
+    html: string;
+    warnings: CSSWarning[];
+}
+interface PreviewResult {
+    id: string;
+    originalHtml: string;
+    transforms: TransformResult[];
+    cssReport: CSSWarning[];
+    createdAt: string;
+}
+interface DiffResult {
+    clientId: string;
+    scoreBefore: number;
+    scoreAfter: number;
+    scoreDelta: number;
+    fixed: CSSWarning[];
+    introduced: CSSWarning[];
+    unchanged: CSSWarning[];
+}
+interface SpamIssue {
+    rule: string;
+    severity: "error" | "warning" | "info";
+    message: string;
+    detail?: string;
+}
+interface SpamReport {
+    score: number;
+    level: "low" | "medium" | "high";
+    issues: SpamIssue[];
+}
+interface SpamAnalysisOptions {
+    /** Value of the List-Unsubscribe header, if present */
+    listUnsubscribeHeader?: string;
+    /** Type of email — transactional emails are exempt from unsubscribe requirements */
+    emailType?: "marketing" | "transactional";
+}
+interface LinkIssue {
+    severity: "error" | "warning" | "info";
+    rule: string;
+    message: string;
+    href?: string;
+    text?: string;
+}
+interface LinkReport {
+    totalLinks: number;
+    issues: LinkIssue[];
+    breakdown: {
+        https: number;
+        http: number;
+        mailto: number;
+        tel: number;
+        anchor: number;
+        javascript: number;
+        protocolRelative: number;
+        other: number;
+    };
+}
+interface AccessibilityIssue {
+    severity: "error" | "warning" | "info";
+    rule: string;
+    message: string;
+    element?: string;
+    details?: string;
+}
+interface AccessibilityReport {
+    score: number;
+    issues: AccessibilityIssue[];
+}
+interface ImageIssue {
+    rule: string;
+    severity: "error" | "warning" | "info";
+    message: string;
+    src?: string;
+}
+interface ImageInfo {
+    src: string;
+    alt: string | null;
+    width: string | null;
+    height: string | null;
+    isTrackingPixel: boolean;
+    dataUriBytes: number;
+    issues: string[];
+}
+interface ImageReport {
+    total: number;
+    totalDataUriBytes: number;
+    issues: ImageIssue[];
+    images: ImageInfo[];
+}
+
+/**
+ * Unified error class for all email compilation failures.
+ *
+ * Replaces the per-format error classes (ReactEmailCompileError,
+ * MjmlCompileError, MaizzleCompileError) with a single class that
+ * carries the source format and failure phase.
+ */
+declare class CompileError extends Error {
+    name: string;
+    readonly format: Exclude<InputFormat, "html">;
+    readonly phase: "validation" | "transpile" | "execution" | "render" | "compile";
+    constructor(message: string, format: CompileError["format"], phase: CompileError["phase"]);
+}
+
+/**
+ * Sandbox strategy for JSX execution.
+ *
+ * - `"vm"` — `node:vm` with hardened globals. Fast, zero-dependency,
+ *   but NOT a true security boundary (prototype-chain escapes are possible).
+ *   Suitable for CLI / local use where users run their own code.
+ *
+ * - `"isolated-vm"` (default) — Separate V8 isolate via the `isolated-vm`
+ *   npm package. True heap isolation; escapes require a V8 engine bug.
+ *   Requires `isolated-vm` to be installed (native addon).
+ *
+ * - `"quickjs"` — Validates code structure in a QuickJS WASM sandbox, then
+ *   executes in `node:vm` for React rendering. Security is equivalent to
+ *   `node:vm` — the QuickJS phase validates import restrictions only.
+ *   No native addons needed, but only supports ES2020 and is slower.
+ *   For true isolation on servers, use `isolated-vm`.
+ */
+type SandboxStrategy = "vm" | "isolated-vm" | "quickjs";
+interface CompileReactEmailOptions {
+    /**
+     * Sandbox strategy to use for executing user JSX code.
+     * @default "isolated-vm"
+     */
+    sandbox?: SandboxStrategy;
+}
+/**
+ * Compile a React Email JSX/TSX source string into an HTML email string.
+ *
+ * Pipeline:
+ *  1. Validate input (size, basic checks)
+ *  2. Transpile JSX/TSX → CommonJS JS using sucrase
+ *  3. Execute inside a sandbox (configurable strategy)
+ *  4. Render the exported component to a full HTML email string
+ *
+ * Requires peer dependencies: sucrase, react, @react-email/components,
+ * @react-email/render. Additionally:
+ *  - sandbox "isolated-vm" requires `isolated-vm`
+ *  - sandbox "quickjs" requires `quickjs-emscripten`
+ */
+declare function compileReactEmail(source: string, options?: CompileReactEmailOptions): Promise<string>;
+
+export { type AiProvider as A, type CSSWarning as C, type DiffResult as D, type EmailClient as E, type Framework as F, type ImageReport as I, type LinkReport as L, type PreviewResult as P, type SpamAnalysisOptions as S, type TransformResult as T, type CodeFix as a, type ExportPromptOptions as b, type AiFixResult as c, type SpamReport as d, type AccessibilityReport as e, type AccessibilityIssue as f, CompileError as g, type CompileReactEmailOptions as h, type EstimateOptions as i, type ExportScope as j, type FixType as k, type ImageInfo as l, type ImageIssue as m, type InputFormat as n, type LinkIssue as o, type SandboxStrategy as p, type SpamIssue as q, type SupportLevel as r, type TokenEstimate as s, type TokenEstimateWithWarnings as t, estimateAiFixTokens as u, generateFixPrompt as v, heuristicTokenCount as w, compileReactEmail as x };