@one-million-lines/email-builder 0.1.4 → 0.2.1

package/CHANGELOG.md

@@ -6,6 +6,24 @@ This project adheres to [Semantic Versioning](https://semver.org/) and the
 
 ## [Unreleased]
 
+### Added
+- **AI assistant module** (`src/ai/`) — optional chat-driven editing. When an AI
+  provider is configured an **AI** tab appears in the left sidebar. The client
+  sends a catalog of real modules so the assistant only ever assembles valid,
+  renderable emails; every response is validated with `documentSchema` and gets
+  fresh ids before being applied. New exports: `aiAssistantPlugin`,
+  `createHttpAIProvider`, `buildCatalog`, `applyAIResponse`, `mockAIProvider`,
+  `applyAIActions`, `validateAIDocument`, and the related types. New `aiEndpoint`
+  prop on `<EmailBuilder>`. See `src/ai/README.md`.
+- **Python AI backend** (`backend/`) — a small Flask service (`app.py`,
+  `ai_service.py`) exposing `GET /health` and `POST /ai/generate`. Works with any
+  OpenAI-compatible endpoint and falls back to a deterministic offline planner
+  when no API key is set. See `backend/README.md`.
+- **Feature module additions** — five new blocks added to the Feature category:
+  `feature.gradient_hero` (launch CTA hero), `feature.pull_quote`,
+  `feature.stat_row`, `feature.single_product_spotlight`, `feature.pill_nav`.
+
+
 ## [0.1.4] — 2026-07-02
 
 ### Changed

package/README.md

@@ -15,6 +15,8 @@ Marketing teams often need a reusable editor that produces email-safe HTML witho
 - Visual editor with top bar, left sidebar, canvas, and right sidebar
 - JSON-first email document model
 - Built-in modules, templates, and themes
+- **AI assistant module** — optional chat-driven editing backed by a simple
+  Python service
 - Table-based HTML rendering for email output
 - Local autosave via Zustand store
 - React component API and vanilla JS factory
@@ -45,12 +47,14 @@ src/
   core/             document types, renderer, validation, AI actions, plugins
   editor/           top bar, sidebars, canvas
   modules/          module registry and built-in modules
+  ai/               AI assistant module: provider, catalog, chat panel (see ai/README.md)
   recommendations/  recommendation and fallback logic
   store/            editor state and persistence
   templates/        built-in email templates
   themes/           theme definitions
   plugins/          extension points, including image uploader helpers
   index.ts          public API for embedding
+backend/            Python (Flask) AI service (see backend/README.md)
 ```
 
 ## Install
@@ -131,6 +135,26 @@ Vue and Angular mount the React-based editor through the framework-neutral
 `createEmailBuilder()` factory (`getDocument` / `exportHtml` / `exportJson` /
 `destroy`). React and ReactDOM remain peer dependencies in all cases.
 
+### AI assistant module
+
+Enable chat-driven editing by pointing the builder at the Python AI service in
+[`backend/`](./backend). When configured, an **AI** tab appears in the left
+sidebar.
+
+```tsx
+<EmailBuilder aiEndpoint="http://localhost:3001/ai/generate" />
+```
+
+```ts
+import { registerPlugin, aiAssistantPlugin } from "@one-million-lines/email-builder";
+registerPlugin(aiAssistantPlugin({ endpoint: "http://localhost:3001/ai/generate" }));
+```
+
+The assistant only ever assembles emails from real, renderable modules, and every
+response is validated with Zod before it is applied. See
+[`src/ai/README.md`](./src/ai/README.md) and
+[`backend/README.md`](./backend/README.md).
+
 ### Styling & isolation
 
 The stylesheet at `@one-million-lines/email-builder/styles.css` is designed to
@@ -212,6 +236,20 @@ npm run validate:pack # build + npm pack --dry-run
 npm run build:demo    # build the standalone demo app
 ```
 
+### AI backend (optional)
+
+The AI assistant needs the Python service in [`backend/`](./backend):
+
+```bash
+cd backend
+python -m venv .venv && source .venv/bin/activate
+pip install -r requirements.txt
+python app.py          # offline heuristic mode; set AI_API_KEY for a real model
+```
+
+Then set `VITE_AI_ENDPOINT=http://localhost:3001/ai/generate` in a root `.env`
+to enable the AI tab in `npm run dev`.
+
 ## Building & publishing
 
 ```bash

package/dist/ai/AIChatPanel.d.ts

@@ -0,0 +1,3 @@
+/** Hook: is an AI provider currently configured? Reactive. */
+export declare function useAIAvailable(): boolean;
+export declare function AIChatPanel(): import("react").JSX.Element;

package/dist/ai/applyResponse.d.ts

@@ -0,0 +1,20 @@
+import { EmailDocument } from '../core/types';
+import { AIResponse } from '../core/aiActions';
+export interface ApplyResult {
+    document: EmailDocument;
+    /** Assistant chat text, if any. */
+    text?: string;
+    /** Short human summary of what changed, for the chat log. */
+    summary: string;
+}
+/**
+ * Apply an {@link AIResponse} to `doc`. Returns the next document plus a summary,
+ * or an error string when the result fails validation.
+ */
+export declare function applyAIResponse(doc: EmailDocument, res: AIResponse): {
+    ok: true;
+    result: ApplyResult;
+} | {
+    ok: false;
+    error: string;
+};

package/dist/ai/catalog.d.ts

@@ -0,0 +1,15 @@
+import { EmailModule } from '../core/types';
+export interface CatalogEntry {
+    type: string;
+    category: string;
+    name: string;
+    description: string;
+    tags: string[];
+    source: "module";
+    /** A concrete, renderable instance of the module (ids included). */
+    sample: EmailModule;
+}
+/**
+ * Build the catalog sent to the AI backend.
+ */
+export declare function buildCatalog(): CatalogEntry[];

package/dist/ai/index.d.ts

@@ -0,0 +1,22 @@
+import { Plugin } from '../core/plugins';
+import { HttpAIProviderOptions } from './provider';
+export { createHttpAIProvider } from './provider';
+export type { HttpAIProviderOptions } from './provider';
+export { buildCatalog } from './catalog';
+export type { CatalogEntry } from './catalog';
+export { applyAIResponse } from './applyResponse';
+export type { ApplyResult } from './applyResponse';
+export { AIChatPanel, useAIAvailable } from './AIChatPanel';
+export { getAIProvider as getActiveAIProvider, setAIProvider as setActiveAIProvider, } from './state';
+export interface AIAssistantOptions extends HttpAIProviderOptions {
+}
+/**
+ * Plugin factory that wires an HTTP-backed AI provider into the builder and
+ * enables the chat panel.
+ *
+ * @example
+ *   import { registerPlugin } from "@one-million-lines/email-builder";
+ *   import { aiAssistantPlugin } from "@one-million-lines/email-builder";
+ *   registerPlugin(aiAssistantPlugin({ endpoint: "http://localhost:3001/ai/generate" }));
+ */
+export declare function aiAssistantPlugin(opts: AIAssistantOptions): Plugin;

package/dist/ai/provider.d.ts

@@ -0,0 +1,23 @@
+import { AIProvider, AIResponse } from '../core/aiActions';
+export interface HttpAIProviderOptions {
+    /** Absolute or same-origin URL that implements POST /ai/generate. Required. */
+    endpoint: string;
+    /** Extra headers (e.g. Authorization). */
+    headers?: Record<string, string>;
+    /** Send cookies with the request. Default: false. */
+    withCredentials?: boolean;
+    /** Abort the request after this many ms. Default: 60000. */
+    timeoutMs?: number;
+    /**
+     * Map a raw server JSON body to an `AIResponse`.
+     * Default expects the body to already be an `AIResponse`.
+     */
+    transformResponse?: (body: unknown) => AIResponse;
+}
+/**
+ * Create an {@link AIProvider} backed by an HTTP endpoint.
+ *
+ * @example
+ *   const provider = createHttpAIProvider({ endpoint: "http://localhost:3001/ai/generate" });
+ */
+export declare function createHttpAIProvider(opts: HttpAIProviderOptions): AIProvider;

package/dist/ai/state.d.ts

@@ -0,0 +1,11 @@
+import { AIProvider } from '../core/aiActions';
+type Listener = () => void;
+/** Set (or clear) the active AI provider. Notifies subscribers. */
+export declare function setAIProvider(next: AIProvider | null): void;
+/** The active AI provider, or null when AI is not configured. */
+export declare function getAIProvider(): AIProvider | null;
+/** Subscribe to provider changes (for `useSyncExternalStore`). */
+export declare const subscribeAIProvider: (listener: Listener) => (() => void);
+/** Monotonic version; changes whenever the provider is set or cleared. */
+export declare const getAIProviderVersion: () => number;
+export {};