best-email-builder 0.6.0 → 0.8.0

package/dist/ai-server.js

@@ -1,4 +1,6 @@
 import {
+  AGENT_ERROR_CODES,
+  AGENT_PROTOCOL,
   AI_MESSAGES,
   AI_PROVIDERS,
   DEFAULT_CLAUDE_MODEL,
@@ -13,6 +15,7 @@ import {
   REWRITE_SYSTEM_PROMPT,
   SUBJECTS_SYSTEM_PROMPT,
   SYSTEM_PROMPT,
+  agentEmailModel,
   buildUserPrompt,
   claudeEmailModel,
   cleanGenerateInput,
@@ -21,6 +24,7 @@ import {
   createSubjectSuggester,
   emailWords,
   failureCode,
+  listProviderModels,
   normalizeGeneratedMjml,
   parseDraft,
   providerEmailModel,
@@ -30,11 +34,116 @@ import {
   reviewDraft,
   reviewRewrite,
   reviewSubjects
-} from "./chunk-NZIQF7IW.js";
+} from "./chunk-SHHHYRPC.js";
 import "./chunk-OWVXKMLI.js";
-import "./chunk-W424KPCR.js";
-import "./chunk-JI36FNWE.js";
+import "./chunk-AXIM6E7T.js";
+import "./chunk-62HBUBBI.js";
+
+// src/ai/agentEndpoint.js
+var TASKS = ["generate", "rewrite", "subjects"];
+var MAX_BODY_BYTES = 2 * 1024 * 1024;
+var MAX_MESSAGES = 20;
+var json = (body, status = 200) => new Response(JSON.stringify(body), { status, headers: { "Content-Type": "application/json; charset=utf-8", "Cache-Control": "no-store" } });
+var refuse = (error, code, status) => json({ error, code }, status);
+function problemOf(body) {
+  if (!body || typeof body !== "object") return "The body is not a JSON object";
+  if (body.protocol !== AGENT_PROTOCOL) return `Unsupported protocol ${JSON.stringify(body.protocol)} \u2014 this endpoint speaks ${AGENT_PROTOCOL}`;
+  if (!TASKS.includes(body.task)) return `Unknown task ${JSON.stringify(body.task)}`;
+  if (typeof body.system !== "string") return "`system` must be a string";
+  if (!body.schema || typeof body.schema !== "object") return "`schema` must be an object";
+  const { messages } = body;
+  if (!Array.isArray(messages) || !messages.length || messages.length > MAX_MESSAGES) return `\`messages\` must hold 1 to ${MAX_MESSAGES} messages`;
+  for (const message of messages) {
+    if (!message || message.role !== "user" && message.role !== "assistant" || typeof message.content !== "string") {
+      return 'Each message is { role: "user"|"assistant", content: string }';
+    }
+  }
+  return null;
+}
+function createAgentEndpoint({ complete, onError = (error) => console.error("[agent]", error) } = (
+  /** @type {any} */
+  {}
+)) {
+  if (typeof complete !== "function") throw new TypeError("createAgentEndpoint: `complete` must be a function \u2014 your agent");
+  return async function agentEndpoint(request) {
+    if (request.method.toUpperCase() !== "POST") return refuse("POST only", "METHOD_NOT_ALLOWED", 405);
+    const length = Number(request.headers.get("content-length") || 0);
+    if (length > MAX_BODY_BYTES) return refuse("Request too large", "TOO_LARGE", 413);
+    const raw = await request.text();
+    if (raw.length > MAX_BODY_BYTES) return refuse("Request too large", "TOO_LARGE", 413);
+    let body;
+    try {
+      body = JSON.parse(raw);
+    } catch {
+      return refuse("Invalid JSON", "INVALID_JSON", 400);
+    }
+    const problem = problemOf(body);
+    if (problem) return refuse(problem, "INVALID_REQUEST", 400);
+    try {
+      const answer = await complete({
+        task: body.task,
+        system: body.system,
+        messages: body.messages.map((m) => ({ role: m.role, content: m.content })),
+        schema: body.schema,
+        request,
+        signal: request.signal
+      });
+      if (typeof answer === "string") return json({ text: answer });
+      if (answer && typeof answer === "object") return json({ output: answer });
+      return refuse("The agent gave no answer", "MODEL_ERROR", 502);
+    } catch (error) {
+      const code = (
+        /** @type {any} */
+        error?.code
+      );
+      if (AGENT_ERROR_CODES.includes(code)) {
+        const known = GENERATION_ERRORS[
+          /** @type {keyof typeof GENERATION_ERRORS} */
+          code
+        ];
+        return refuse(String(
+          /** @type {any} */
+          error?.detail || /** @type {any} */
+          error?.message || known.message
+        ), code, known.status);
+      }
+      onError(error, request);
+      return refuse("The agent could not answer", "MODEL_ERROR", 502);
+    }
+  };
+}
+var SAMPLE_TEXT = '<p>Our summer sale starts on Monday: 30% off everything in store, for three days only. It ends on Wednesday at midnight. <a href="https://example.com/sale">See the offers</a>.</p>';
+async function checkAgent({ url, headers, user, fetch: fetchImpl, timeout, compile, language = "en" }) {
+  const model = agentEmailModel({ url, headers, fetch: fetchImpl, timeout });
+  const generator = createEmailGenerator({ model, compile });
+  const steps = [
+    ["generate", () => generator.generate({ purpose: "welcome", language }, { user }), (r) => ({ subject: r.subject, warnings: r.warnings })],
+    ["rewrite", () => generator.rewrite({ action: "shorter", text: SAMPLE_TEXT, format: "html" }, { user }), (r) => r.text],
+    [
+      "subjects",
+      () => generator.suggestSubjects({ subject: "Summer sale: 30% off", text: "Our summer sale starts on Monday: 30% off everything in store, for three days only.", language }, { user }),
+      (r) => r.subjects
+    ]
+  ];
+  const results = [];
+  for (const [task, run, sampleOf] of steps) {
+    const started = Date.now();
+    try {
+      const result = await run();
+      results.push({ task, ok: true, ms: Date.now() - started, attempts: result.attempts, sample: sampleOf(result) });
+    } catch (error) {
+      const failure = (
+        /** @type {any} */
+        error
+      );
+      results.push({ task, ok: false, ms: Date.now() - started, code: failure?.code || "ERROR", error: String(failure?.detail || failure?.message || error) });
+    }
+  }
+  return { ok: results.every((result) => result.ok), results };
+}
 export {
+  AGENT_ERROR_CODES,
+  AGENT_PROTOCOL,
   AI_MESSAGES,
   AI_PROVIDERS,
   DEFAULT_CLAUDE_MODEL,
@@ -49,14 +158,18 @@ export {
   REWRITE_SYSTEM_PROMPT,
   SUBJECTS_SYSTEM_PROMPT,
   SYSTEM_PROMPT,
+  agentEmailModel,
   buildUserPrompt,
+  checkAgent,
   claudeEmailModel,
   cleanGenerateInput,
+  createAgentEndpoint,
   createEmailGenerator,
   createRewriter,
   createSubjectSuggester,
   emailWords,
   failureCode,
+  listProviderModels,
   normalizeGeneratedMjml,
   parseDraft,
   providerEmailModel,

package/dist/ai-server.js.map

@@ -1 +1 @@
-{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}
+{"version":3,"sources":["../src/ai/agentEndpoint.js"],"sourcesContent":["// @ts-check\n/**\n * THE AGENT'S SIDE of `best-email-builder/agent@1` (see agent.js), for an\n * agent written in JavaScript — and `checkAgent`, to try any agent with the\n * builder's own checks before plugging it in.\n *\n *   const endpoint = createAgentEndpoint({\n *     complete: async ({ task, system, messages, schema, request }) => {\n *       const who = await sessionOf(request);           // your rights\n *       return myAgent.answer({ system, messages, who }); // text, or the answer as an object\n *     },\n *   });\n *   // Next.js: export const POST = endpoint;   Express: app.post('/email-builder', toNodeListener(endpoint))\n *\n *   const report = await checkAgent({ url: 'http://localhost:8800/email-builder', headers, compile: compileMjml });\n *   // { ok, results: [{ task: 'generate', ok, ms, attempts, sample }, …] }\n */\n\nimport { AGENT_ERROR_CODES, AGENT_PROTOCOL, agentEmailModel } from './agent.js';\nimport { GENERATION_ERRORS } from './draft.js';\nimport { createEmailGenerator } from './generator.js';\n\nconst TASKS = ['generate', 'rewrite', 'subjects'];\n/** A repair turn carries the last answer: a whole email at most. */\nconst MAX_BODY_BYTES = 2 * 1024 * 1024;\nconst MAX_MESSAGES = 20;\n\n/**\n * @typedef {{\n *   task: 'generate'|'rewrite'|'subjects',\n *   system: string,\n *   messages: {role: 'user'|'assistant', content: string}[],\n *   schema: object,\n *   request: Request,\n *   signal: AbortSignal,\n * }} AgentTask\n */\n\n/** @param {unknown} body @param {number} status */\nconst json = (body, status = 200) =>\n  new Response(JSON.stringify(body), { status, headers: { 'Content-Type': 'application/json; charset=utf-8', 'Cache-Control': 'no-store' } });\n\n/** @param {string} error @param {string} code @param {number} status */\nconst refuse = (error, code, status) => json({ error, code }, status);\n\n/**\n * What the builder sent, checked; or why not.\n * @param {any} body\n * @returns {string|null} the problem\n */\nfunction problemOf(body) {\n  if (!body || typeof body !== 'object') return 'The body is not a JSON object';\n  if (body.protocol !== AGENT_PROTOCOL) return `Unsupported protocol ${JSON.stringify(body.protocol)} — this endpoint speaks ${AGENT_PROTOCOL}`;\n  if (!TASKS.includes(body.task)) return `Unknown task ${JSON.stringify(body.task)}`;\n  if (typeof body.system !== 'string') return '`system` must be a string';\n  if (!body.schema || typeof body.schema !== 'object') return '`schema` must be an object';\n  const { messages } = body;\n  if (!Array.isArray(messages) || !messages.length || messages.length > MAX_MESSAGES) return `\\`messages\\` must hold 1 to ${MAX_MESSAGES} messages`;\n  for (const message of messages) {\n    if (!message || (message.role !== 'user' && message.role !== 'assistant') || typeof message.content !== 'string') {\n      return 'Each message is { role: \"user\"|\"assistant\", content: string }';\n    }\n  }\n  return null;\n}\n\n/**\n * @param {{\n *   complete: (task: AgentTask) => Promise<string | object> | string | object,\n *   onError?: (error: unknown, request: Request) => void,\n * }} options\n *   `complete`: your agent. It answers with the text of its model, or with\n *   the answer as an object. To fail with a reason the builder explains, throw\n *   an error whose `code` is one of AGENT_ERROR_CODES ('REFUSED',\n *   'MODEL_BUSY'…); any other error is logged with `onError` and answered as\n *   MODEL_ERROR, its message kept out of the response.\n * @returns {(request: Request) => Promise<Response>}\n */\nexport function createAgentEndpoint({ complete, onError = (error) => console.error('[agent]', error) } = /** @type {any} */ ({})) {\n  if (typeof complete !== 'function') throw new TypeError('createAgentEndpoint: `complete` must be a function — your agent');\n\n  return async function agentEndpoint(request) {\n    if (request.method.toUpperCase() !== 'POST') return refuse('POST only', 'METHOD_NOT_ALLOWED', 405);\n    const length = Number(request.headers.get('content-length') || 0);\n    if (length > MAX_BODY_BYTES) return refuse('Request too large', 'TOO_LARGE', 413);\n    const raw = await request.text();\n    if (raw.length > MAX_BODY_BYTES) return refuse('Request too large', 'TOO_LARGE', 413);\n    /** @type {any} */\n    let body;\n    try {\n      body = JSON.parse(raw);\n    } catch {\n      return refuse('Invalid JSON', 'INVALID_JSON', 400);\n    }\n    const problem = problemOf(body);\n    if (problem) return refuse(problem, 'INVALID_REQUEST', 400);\n\n    try {\n      const answer = await complete({\n        task: body.task,\n        system: body.system,\n        messages: body.messages.map((/** @type {any} */ m) => ({ role: m.role, content: m.content })),\n        schema: body.schema,\n        request,\n        signal: request.signal,\n      });\n      if (typeof answer === 'string') return json({ text: answer });\n      if (answer && typeof answer === 'object') return json({ output: answer });\n      return refuse('The agent gave no answer', 'MODEL_ERROR', 502);\n    } catch (error) {\n      const code = /** @type {any} */ (error)?.code;\n      if (AGENT_ERROR_CODES.includes(code)) {\n        const known = GENERATION_ERRORS[/** @type {keyof typeof GENERATION_ERRORS} */ (code)];\n        return refuse(String(/** @type {any} */ (error)?.detail || /** @type {any} */ (error)?.message || known.message), code, known.status);\n      }\n      onError(error, request);\n      return refuse('The agent could not answer', 'MODEL_ERROR', 502);\n    }\n  };\n}\n\nconst SAMPLE_TEXT =\n  '<p>Our summer sale starts on Monday: 30% off everything in store, for three days only. ' +\n  'It ends on Wednesday at midnight. <a href=\"https://example.com/sale\">See the offers</a>.</p>';\n\n/**\n * Tries an agent with the builder's own checks: one email written, one text\n * rewritten, subject ideas — in turn, each as the builder would ask it (with\n * its repair turn). Three to six calls to the agent.\n * @param {{\n *   url: string,\n *   headers?: import('./agent.js').AgentHeaders,\n *   user?: any,\n *   fetch?: typeof fetch,\n *   timeout?: number,\n *   compile?: (mjml: string) => Promise<{warnings?: {message: string}[]}>,\n *   language?: string,\n * }} options\n *   `user`: what `headers` gets, as the handler's `authorize` would give it.\n *   `compile`: `compileMjml` (best-email-builder/server), for MJML's own\n *   warnings as on the server.\n * @returns {Promise<{ok: boolean, results: {task: string, ok: boolean, ms: number, attempts?: number, sample?: unknown, code?: string, error?: string}[]}>}\n */\nexport async function checkAgent({ url, headers, user, fetch: fetchImpl, timeout, compile, language = 'en' }) {\n  const model = agentEmailModel({ url, headers, fetch: fetchImpl, timeout });\n  const generator = createEmailGenerator({ model, compile });\n  /** @type {[string, () => Promise<any>, (result: any) => unknown][]} */\n  const steps = [\n    ['generate', () => generator.generate({ purpose: 'welcome', language }, { user }), (r) => ({ subject: r.subject, warnings: r.warnings })],\n    ['rewrite', () => generator.rewrite({ action: 'shorter', text: SAMPLE_TEXT, format: 'html' }, { user }), (r) => r.text],\n    [\n      'subjects',\n      () => generator.suggestSubjects({ subject: 'Summer sale: 30% off', text: 'Our summer sale starts on Monday: 30% off everything in store, for three days only.', language }, { user }),\n      (r) => r.subjects,\n    ],\n  ];\n  const results = [];\n  for (const [task, run, sampleOf] of steps) {\n    const started = Date.now();\n    try {\n      const result = await run();\n      results.push({ task, ok: true, ms: Date.now() - started, attempts: result.attempts, sample: sampleOf(result) });\n    } catch (error) {\n      const failure = /** @type {any} */ (error);\n      results.push({ task, ok: false, ms: Date.now() - started, code: failure?.code || 'ERROR', error: String(failure?.detail || failure?.message || error) });\n    }\n  }\n  return { ok: results.every((result) => result.ok), results };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAsBA,IAAM,QAAQ,CAAC,YAAY,WAAW,UAAU;AAEhD,IAAM,iBAAiB,IAAI,OAAO;AAClC,IAAM,eAAe;AAcrB,IAAM,OAAO,CAAC,MAAM,SAAS,QAC3B,IAAI,SAAS,KAAK,UAAU,IAAI,GAAG,EAAE,QAAQ,SAAS,EAAE,gBAAgB,mCAAmC,iBAAiB,WAAW,EAAE,CAAC;AAG5I,IAAM,SAAS,CAAC,OAAO,MAAM,WAAW,KAAK,EAAE,OAAO,KAAK,GAAG,MAAM;AAOpE,SAAS,UAAU,MAAM;AACvB,MAAI,CAAC,QAAQ,OAAO,SAAS,SAAU,QAAO;AAC9C,MAAI,KAAK,aAAa,eAAgB,QAAO,wBAAwB,KAAK,UAAU,KAAK,QAAQ,CAAC,gCAA2B,cAAc;AAC3I,MAAI,CAAC,MAAM,SAAS,KAAK,IAAI,EAAG,QAAO,gBAAgB,KAAK,UAAU,KAAK,IAAI,CAAC;AAChF,MAAI,OAAO,KAAK,WAAW,SAAU,QAAO;AAC5C,MAAI,CAAC,KAAK,UAAU,OAAO,KAAK,WAAW,SAAU,QAAO;AAC5D,QAAM,EAAE,SAAS,IAAI;AACrB,MAAI,CAAC,MAAM,QAAQ,QAAQ,KAAK,CAAC,SAAS,UAAU,SAAS,SAAS,aAAc,QAAO,+BAA+B,YAAY;AACtI,aAAW,WAAW,UAAU;AAC9B,QAAI,CAAC,WAAY,QAAQ,SAAS,UAAU,QAAQ,SAAS,eAAgB,OAAO,QAAQ,YAAY,UAAU;AAChH,aAAO;AAAA,IACT;AAAA,EACF;AACA,SAAO;AACT;AAcO,SAAS,oBAAoB,EAAE,UAAU,UAAU,CAAC,UAAU,QAAQ,MAAM,WAAW,KAAK,EAAE;AAAA;AAAA,EAAwB,CAAC;AAAA,GAAI;AAChI,MAAI,OAAO,aAAa,WAAY,OAAM,IAAI,UAAU,sEAAiE;AAEzH,SAAO,eAAe,cAAc,SAAS;AAC3C,QAAI,QAAQ,OAAO,YAAY,MAAM,OAAQ,QAAO,OAAO,aAAa,sBAAsB,GAAG;AACjG,UAAM,SAAS,OAAO,QAAQ,QAAQ,IAAI,gBAAgB,KAAK,CAAC;AAChE,QAAI,SAAS,eAAgB,QAAO,OAAO,qBAAqB,aAAa,GAAG;AAChF,UAAM,MAAM,MAAM,QAAQ,KAAK;AAC/B,QAAI,IAAI,SAAS,eAAgB,QAAO,OAAO,qBAAqB,aAAa,GAAG;AAEpF,QAAI;AACJ,QAAI;AACF,aAAO,KAAK,MAAM,GAAG;AAAA,IACvB,QAAQ;AACN,aAAO,OAAO,gBAAgB,gBAAgB,GAAG;AAAA,IACnD;AACA,UAAM,UAAU,UAAU,IAAI;AAC9B,QAAI,QAAS,QAAO,OAAO,SAAS,mBAAmB,GAAG;AAE1D,QAAI;AACF,YAAM,SAAS,MAAM,SAAS;AAAA,QAC5B,MAAM,KAAK;AAAA,QACX,QAAQ,KAAK;AAAA,QACb,UAAU,KAAK,SAAS,IAAI,CAAoB,OAAO,EAAE,MAAM,EAAE,MAAM,SAAS,EAAE,QAAQ,EAAE;AAAA,QAC5F,QAAQ,KAAK;AAAA,QACb;AAAA,QACA,QAAQ,QAAQ;AAAA,MAClB,CAAC;AACD,UAAI,OAAO,WAAW,SAAU,QAAO,KAAK,EAAE,MAAM,OAAO,CAAC;AAC5D,UAAI,UAAU,OAAO,WAAW,SAAU,QAAO,KAAK,EAAE,QAAQ,OAAO,CAAC;AACxE,aAAO,OAAO,4BAA4B,eAAe,GAAG;AAAA,IAC9D,SAAS,OAAO;AACd,YAAM;AAAA;AAAA,QAA2B,OAAQ;AAAA;AACzC,UAAI,kBAAkB,SAAS,IAAI,GAAG;AACpC,cAAM,QAAQ;AAAA;AAAA,UAAiE;AAAA,QAAK;AACpF,eAAO,OAAO;AAAA;AAAA,UAA2B,OAAQ;AAAA,UAA8B,OAAQ,WAAW,MAAM;AAAA,QAAO,GAAG,MAAM,MAAM,MAAM;AAAA,MACtI;AACA,cAAQ,OAAO,OAAO;AACtB,aAAO,OAAO,8BAA8B,eAAe,GAAG;AAAA,IAChE;AAAA,EACF;AACF;AAEA,IAAM,cACJ;AAqBF,eAAsB,WAAW,EAAE,KAAK,SAAS,MAAM,OAAO,WAAW,SAAS,SAAS,WAAW,KAAK,GAAG;AAC5G,QAAM,QAAQ,gBAAgB,EAAE,KAAK,SAAS,OAAO,WAAW,QAAQ,CAAC;AACzE,QAAM,YAAY,qBAAqB,EAAE,OAAO,QAAQ,CAAC;AAEzD,QAAM,QAAQ;AAAA,IACZ,CAAC,YAAY,MAAM,UAAU,SAAS,EAAE,SAAS,WAAW,SAAS,GAAG,EAAE,KAAK,CAAC,GAAG,CAAC,OAAO,EAAE,SAAS,EAAE,SAAS,UAAU,EAAE,SAAS,EAAE;AAAA,IACxI,CAAC,WAAW,MAAM,UAAU,QAAQ,EAAE,QAAQ,WAAW,MAAM,aAAa,QAAQ,OAAO,GAAG,EAAE,KAAK,CAAC,GAAG,CAAC,MAAM,EAAE,IAAI;AAAA,IACtH;AAAA,MACE;AAAA,MACA,MAAM,UAAU,gBAAgB,EAAE,SAAS,wBAAwB,MAAM,uFAAuF,SAAS,GAAG,EAAE,KAAK,CAAC;AAAA,MACpL,CAAC,MAAM,EAAE;AAAA,IACX;AAAA,EACF;AACA,QAAM,UAAU,CAAC;AACjB,aAAW,CAAC,MAAM,KAAK,QAAQ,KAAK,OAAO;AACzC,UAAM,UAAU,KAAK,IAAI;AACzB,QAAI;AACF,YAAM,SAAS,MAAM,IAAI;AACzB,cAAQ,KAAK,EAAE,MAAM,IAAI,MAAM,IAAI,KAAK,IAAI,IAAI,SAAS,UAAU,OAAO,UAAU,QAAQ,SAAS,MAAM,EAAE,CAAC;AAAA,IAChH,SAAS,OAAO;AACd,YAAM;AAAA;AAAA,QAA8B;AAAA;AACpC,cAAQ,KAAK,EAAE,MAAM,IAAI,OAAO,IAAI,KAAK,IAAI,IAAI,SAAS,MAAM,SAAS,QAAQ,SAAS,OAAO,OAAO,SAAS,UAAU,SAAS,WAAW,KAAK,EAAE,CAAC;AAAA,IACzJ;AAAA,EACF;AACA,SAAO,EAAE,IAAI,QAAQ,MAAM,CAAC,WAAW,OAAO,EAAE,GAAG,QAAQ;AAC7D;","names":[]}