best-email-builder 0.5.1 → 0.6.0

package/CHANGELOG.md

@@ -6,6 +6,32 @@ All notable changes are documented here. The format follows
 
 ## [Unreleased]
 
+## [0.6.0] — 2026-10-15
+
+### Added
+- **The user chooses the provider.** `createAi({ provider: [...], askKey: true })`
+  takes a list: the Connect dialog shows the providers as cards (name, model,
+  free or not, a dot on those whose key this browser keeps; arrows move
+  through them). The choice and one key per provider are remembered, and a
+  provider whose key is kept needs nothing pasted. `ai.key` gains `provider`,
+  `providers`, `choose(id)` and `get(id)`; `ai.key.request()` opens the dialog
+  to change provider.
+- **`claudeProvider({ client })`** — Claude as one of those providers, with
+  the user's own Anthropic key; the application's SDK is loaded when Claude
+  is chosen.
+- **`failureCode(status, message)`** — the rule that turns a provider's
+  failure into the interface's error, exported for a model of your own.
+- The live demo offers OpenAI, Claude, Mistral, Gemini and OpenRouter, says
+  which one is connected, and has a *Change provider* link.
+
+### Fixed
+- **An exhausted quota said "busy, try again".** OpenAI answers a quota
+  spent with a 429 (`insufficient_quota`), Anthropic an empty credit balance
+  with a 400: both are now `MODEL_CREDITS`.
+- **Claude's failures were all "could not answer".** The SDK's errors are now
+  read like every provider's: a refused key is `KEY_REFUSED` (asked again with
+  `askKey`), no credits `MODEL_CREDITS`, overloaded (529) `MODEL_BUSY`.
+
 ## [0.5.1] — 2026-10-15
 
 ### Fixed

package/README.md

@@ -61,7 +61,8 @@ Best Email Builder is the second option done once, properly, and given away:
   model's MJML is cleaned and checked like any template before it gets there.
   OpenRouter, Gemini, Groq, Mistral, OpenAI, DeepSeek, Cerebras, Ollama or any
   OpenAI-compatible API by its key — free tiers included — and Claude through
-  its SDK; on your server, or in the page with each user's own key.
+  its SDK; on your server, or in the page with each user's own key — and the
+  provider they choose.
 - **Any text rewritten in one click** — select a text or a button: *Shorter*,
   *Longer*, *Fix mistakes*, *Friendlier*, *More formal*, *Translate* into 13
   languages, or say what to change in your own words. The text changes in
@@ -363,9 +364,19 @@ the provider refuses is forgotten and asked again. Off by default:
 const ai = createAi({ provider: 'openrouter', askKey: true });
 ```
 
-`ai.key` reads and changes it: `get()`, `set(key)`, `forget()`,
-`request()`, `subscribe(fn)`, `state()` (`{ asking, refused, connected }`).
-This is what the live demo does.
+Give a list and each user chooses: the dialog shows the providers as cards
+(name, model, free or not, a dot on those whose key this browser keeps). The
+choice and one key per provider are remembered; going back to a provider whose
+key is kept needs nothing pasted.
+
+```jsx
+const ai = createAi({ provider: ['openai', 'mistral', 'gemini', 'openrouter'], askKey: true });
+```
+
+`ai.key` reads and changes it: `provider` (the one in use), `providers`,
+`choose(id)`, `get(id?)`, `set(key)`, `forget()`, `request()` (opens the
+dialog — to change provider, for one), `subscribe(fn)`, `state()`
+(`{ asking, refused, connected }`). This is what the live demo does.
 
 **In the page, with one key for everyone** — prototypes and internal tools
 only, the key is in the page's code: `createAi({ provider: 'groq', apiKey })`.
@@ -411,7 +422,10 @@ providerEmailModel({ provider: { baseUrl: 'http://localhost:1234/v1', model: 'qw
   quotes of HTML) can be told to skip it: `provider: { …, format: 'text' }`.
 - The provider's failures become errors the interface explains, in its
   language: `KEY_MISSING`, `KEY_REFUSED`, `MODEL_CREDITS`, `MODEL_BUSY`,
-  `MODEL_ERROR` (with the provider's own text in `detail`). None is a 401:
+  `MODEL_ERROR` (with the provider's own text in `detail`). An exhausted
+  quota is `MODEL_CREDITS`, not `MODEL_BUSY`, even when it comes as a 429
+  (OpenAI's `insufficient_quota`) or a 400 (Anthropic's credit balance);
+  `failureCode(status, message)` is that rule, for a model of your own. None is a 401:
   the key is the AI's, not the user's session. A 403 about the model (not
   available here, in this region) or the content is not `KEY_REFUSED`: with
   `askKey`, the user's key is not thrown away for it.
@@ -419,7 +433,21 @@ providerEmailModel({ provider: { baseUrl: 'http://localhost:1234/v1', model: 'qw
   Anthropic SDK (`npm install @anthropic-ai/sdk`) — `claude-opus-5-5` by
   default, `effort: 'medium'`, structured output, streamed so a long email
   does not hit a request timeout — or through OpenRouter with an
-  `anthropic/…` model and one key for every model.
+  `anthropic/…` model and one key for every model. With `askKey`, Claude is
+  one more provider to choose, with the user's own Anthropic key and the SDK
+  loaded only when it is chosen:
+
+  ```js
+  import { claudeProvider, createAi } from 'best-email-builder/ai';
+
+  const claude = claudeProvider({
+    client: async (apiKey) => {
+      const { default: Anthropic } = await import('@anthropic-ai/sdk');
+      return new Anthropic({ apiKey, dangerouslyAllowBrowser: true });
+    },
+  });
+  createAi({ provider: ['openai', claude, 'gemini'], askKey: true });
+  ```
 - **Anything else** is a function `({ system, messages, schema, signal, task })
   => Promise<string>` returning the JSON text — `createEmailGenerator({ model })`
   on the server, `createAi({ model })` in the page.
@@ -474,7 +502,8 @@ another click another one, the first row brings the user's subject back.
   are exported.
 
 The live demo has no server: there, the AI runs in the page with the
-visitor's own OpenRouter key (`createAi({ provider: 'openrouter', askKey: true })`).
+visitor's own key, for the provider they choose — OpenAI, Claude, Mistral,
+Gemini or OpenRouter (`createAi({ provider: ['openai', claude, 'mistral', 'gemini', 'openrouter'], askKey: true })`).
 
 ### 5. Your brand (optional)
 

package/dist/ai-server.js

@@ -20,6 +20,7 @@ import {
   createRewriter,
   createSubjectSuggester,
   emailWords,
+  failureCode,
   normalizeGeneratedMjml,
   parseDraft,
   providerEmailModel,
@@ -29,7 +30,7 @@ import {
   reviewDraft,
   reviewRewrite,
   reviewSubjects
-} from "./chunk-BAA5XMWY.js";
+} from "./chunk-NZIQF7IW.js";
 import "./chunk-OWVXKMLI.js";
 import "./chunk-W424KPCR.js";
 import "./chunk-JI36FNWE.js";
@@ -55,6 +56,7 @@ export {
   createRewriter,
   createSubjectSuggester,
   emailWords,
+  failureCode,
   normalizeGeneratedMjml,
   parseDraft,
   providerEmailModel,

package/dist/ai.js

@@ -23,8 +23,8 @@ import {
   createHttpCaller,
   useSearchShortcut,
   useUi
-} from "./chunk-N7DEVAIP.js";
-import "./chunk-H4W65GBX.js";
+} from "./chunk-JU3OUO6X.js";
+import "./chunk-QPAZLCPO.js";
 import {
   AI_MESSAGES,
   AI_PROVIDERS,
@@ -38,12 +38,14 @@ import {
   REWRITE_ACTIONS,
   REWRITE_LANGUAGES,
   claudeEmailModel,
+  claudeProvider,
   createEmailGenerator,
   emailWords,
+  failureCode,
   providerEmailModel,
   purposesByCategory,
   resolveProvider
-} from "./chunk-BAA5XMWY.js";
+} from "./chunk-NZIQF7IW.js";
 import "./chunk-OWVXKMLI.js";
 import "./chunk-W424KPCR.js";
 import {
@@ -53,6 +55,7 @@ import {
 
 // src/ai/keys.js
 var STORAGE_PREFIX = "best-email-builder:ai-key:";
+var CHOICE_SLOT = "best-email-builder:ai-provider";
 function browserStorage() {
   try {
     const storage = globalThis.localStorage;
@@ -61,21 +64,31 @@ function browserStorage() {
     return null;
   }
 }
-function createKeyStore(provider) {
-  const slot = STORAGE_PREFIX + provider.id;
-  let memory = "";
+var choiceOf = (provider) => Object.freeze({
+  id: provider.id,
+  name: provider.name,
+  model: provider.model ?? null,
+  keyUrl: provider.keyUrl,
+  keyHint: provider.keyHint,
+  free: provider.free
+});
+function createKeyStore(providerOrList) {
+  const providers = Object.freeze((Array.isArray(providerOrList) ? providerOrList : [providerOrList]).map(choiceOf));
+  if (!providers.length) throw new TypeError("createKeyStore: at least one provider");
+  const known = (id) => providers.some((provider) => provider.id === id);
+  const memory = /* @__PURE__ */ new Map();
   let refused = false;
   let pending = null;
   const listeners = /* @__PURE__ */ new Set();
   let snapshot;
-  const read = () => {
+  const read = (slot) => {
     try {
       return browserStorage()?.getItem(slot) || "";
     } catch {
       return "";
     }
   };
-  const write = (value) => {
+  const write = (slot, value) => {
     try {
       const storage = browserStorage();
       if (value) storage?.setItem(slot, value);
@@ -83,7 +96,14 @@ function createKeyStore(provider) {
     } catch {
     }
   };
-  const get = () => memory || read();
+  const keyOf = (id) => memory.has(id) ? memory.get(id) : read(STORAGE_PREFIX + id);
+  const keep = (id, value) => {
+    memory.set(id, value);
+    write(STORAGE_PREFIX + id, value);
+  };
+  const kept = read(CHOICE_SLOT);
+  let current = known(kept) ? kept : (providers.find((provider) => keyOf(provider.id)) || providers[0]).id;
+  const get = (id) => keyOf(id === void 0 ? current : String(id));
   const changed = () => {
     snapshot = Object.freeze({ asking: Boolean(pending), refused, connected: Boolean(get()) });
     for (const listener of [...listeners]) listener();
@@ -92,9 +112,8 @@ function createKeyStore(provider) {
   const answer = (key) => {
     const value = String(key || "").trim();
     if (value) {
-      memory = value;
+      keep(current, value);
       refused = false;
-      write(value);
     }
     const waiting = pending;
     pending = null;
@@ -102,15 +121,28 @@ function createKeyStore(provider) {
     waiting?.resolve(value);
   };
   return Object.freeze({
-    provider: Object.freeze({ id: provider.id, name: provider.name, keyUrl: provider.keyUrl, keyHint: provider.keyHint, free: provider.free }),
+    get provider() {
+      return (
+        /** @type {ProviderChoice} */
+        providers.find((provider) => provider.id === current)
+      );
+    },
+    providers,
     get,
     set: (key) => {
       if (typeof key !== "string" || !key.trim()) throw new TypeError("ai.key.set: a non-empty key");
       answer(key);
     },
     forget: () => {
-      memory = "";
-      write("");
+      keep(current, "");
+      changed();
+    },
+    choose: (id) => {
+      if (!known(id)) throw new TypeError(`ai.key.choose: one of ${providers.map((provider) => provider.id).join(", ")}`);
+      if (id === current) return;
+      current = id;
+      refused = false;
+      write(CHOICE_SLOT, id);
       changed();
     },
     request: () => {
@@ -130,8 +162,7 @@ function createKeyStore(provider) {
     state: () => snapshot,
     answer: (key) => answer(key || ""),
     refuse: () => {
-      memory = "";
-      write("");
+      keep(current, "");
       refused = true;
       changed();
     }
@@ -147,28 +178,54 @@ function ConnectAi({ aiKey }) {
   const state = useSyncExternalStore(aiKey.subscribe, aiKey.state, aiKey.state);
   const [value, setValue] = useState("");
   const [shown, setShown] = useState(false);
+  const [chosenId, setChosenId] = useState(aiKey.provider.id);
   const inputRef = useRef(
     /** @type {HTMLInputElement|null} */
     null
   );
+  const choicesRef = useRef(
+    /** @type {HTMLDivElement|null} */
+    null
+  );
   const inputId = useId();
   const hintId = useId();
-  const { name, keyUrl, keyHint, free } = aiKey.provider;
+  const choices = aiKey.providers;
+  const chosen = choices.find((provider) => provider.id === chosenId) || aiKey.provider;
+  const { name, keyUrl, keyHint, free } = chosen;
   useEffect(() => {
     if (!state.asking) return;
+    setChosenId(aiKey.provider.id);
     setValue("");
     setShown(false);
-  }, [state.asking]);
+  }, [state.asking, aiKey]);
   const key = value.trim();
+  const saved = aiKey.get(chosen.id);
   const unusual = Boolean(key && keyHint && !key.startsWith(keyHint));
+  const refused = state.refused && chosen.id === aiKey.provider.id;
   const submit = (event) => {
     event.preventDefault();
-    if (key) aiKey.answer(key);
+    const answer = key || saved;
+    if (!answer) return;
+    if (chosen.id !== aiKey.provider.id) aiKey.choose(chosen.id);
+    aiKey.answer(answer);
+  };
+  const choose = (id) => {
+    setChosenId(id);
+    setValue("");
+  };
+  const onChoicesKeyDown = (event) => {
+    const at = choices.findIndex((provider) => provider.id === chosen.id);
+    const step = { ArrowDown: 1, ArrowRight: 1, ArrowUp: -1, ArrowLeft: -1 }[event.key];
+    const to = step ? (at + step + choices.length) % choices.length : event.key === "Home" ? 0 : event.key === "End" ? choices.length - 1 : -1;
+    if (to === -1) return;
+    event.preventDefault();
+    choose(choices[to].id);
+    choicesRef.current?.querySelectorAll('[role="radio"]')[to]?.focus();
   };
   return /* @__PURE__ */ jsx(Dialog, { open: state.asking, onOpenChange: (open) => !open && aiKey.answer(null), children: /* @__PURE__ */ jsx(
     DialogContent,
     {
-      className: "eb:gap-0 eb:overflow-hidden eb:p-0 eb:sm:max-w-md",
+      className: cn("eb:gap-0 eb:overflow-hidden eb:p-0", choices.length > 1 ? "eb:sm:max-w-xl" : "eb:sm:max-w-md"),
       "data-testid": "eb-ai-connect",
       onOpenAutoFocus: (event) => {
         event.preventDefault();
@@ -183,7 +240,44 @@ function ConnectAi({ aiKey }) {
               /* @__PURE__ */ jsx(DialogDescription, { className: "eb:text-[13px] eb:leading-relaxed eb:text-foreground-lighter", children: t("The AI writes with your own {provider} key. Connect it once: this browser remembers it.", { provider: name }) })
             ] })
           ] }),
-          state.refused && /* @__PURE__ */ jsxs("p", { role: "alert", className: "eb:flex eb:items-start eb:gap-2 eb:rounded-md eb:border eb:border-destructive/30 eb:bg-destructive/10 eb:px-3 eb:py-2 eb:text-[12.5px] eb:text-destructive", children: [
+          choices.length > 1 && /* @__PURE__ */ jsx(
+            "div",
+            {
+              ref: choicesRef,
+              role: "radiogroup",
+              "aria-label": t("AI provider"),
+              className: "eb:grid eb:grid-cols-2 eb:gap-1.5 eb:sm:grid-cols-3",
+              onKeyDown: onChoicesKeyDown,
+              "data-testid": "eb-ai-connect-providers",
+              children: choices.map((provider) => {
+                const checked = provider.id === chosen.id;
+                return /* @__PURE__ */ jsxs(
+                  "button",
+                  {
+                    type: "button",
+                    role: "radio",
+                    "aria-checked": checked,
+                    tabIndex: checked ? 0 : -1,
+                    onClick: () => choose(provider.id),
+                    className: cn(
+                      "eb:flex eb:min-w-0 eb:flex-col eb:gap-0.5 eb:rounded-md eb:border eb:px-2.5 eb:py-2 eb:text-left eb:transition-colors eb:outline-none eb:focus-visible:ring-[3px] eb:focus-visible:ring-ring/50",
+                      checked ? "eb:border-primary eb:bg-primary/10" : "eb:border-border eb:hover:bg-muted"
+                    ),
+                    children: [
+                      /* @__PURE__ */ jsxs("span", { className: "eb:flex eb:items-center eb:gap-1.5 eb:text-[13px] eb:leading-tight eb:font-medium eb:text-foreground", children: [
+                        /* @__PURE__ */ jsx("span", { className: "eb:truncate", children: provider.name }),
+                        provider.free && /* @__PURE__ */ jsx(Gift, { className: "eb:size-3 eb:shrink-0 eb:text-success", "aria-label": t(provider.free) }),
+                        aiKey.get(provider.id) && /* @__PURE__ */ jsx("span", { className: "eb:ml-auto eb:size-1.5 eb:shrink-0 eb:rounded-full eb:bg-success", title: t("Key saved"), "aria-label": t("Key saved") })
+                      ] }),
+                      provider.model && /* @__PURE__ */ jsx("span", { className: "eb:truncate eb:font-mono eb:text-[10.5px] eb:text-foreground-muted", title: provider.model, children: provider.model })
+                    ]
+                  },
+                  provider.id
+                );
+              })
+            }
+          ),
+          refused && /* @__PURE__ */ jsxs("p", { role: "alert", className: "eb:flex eb:items-start eb:gap-2 eb:rounded-md eb:border eb:border-destructive/30 eb:bg-destructive/10 eb:px-3 eb:py-2 eb:text-[12.5px] eb:text-destructive", children: [
             /* @__PURE__ */ jsx(TriangleAlert, { className: "eb:mt-px eb:size-3.5 eb:shrink-0", "aria-hidden": "true" }),
             t("{provider} refused the last key. Paste another one.", { provider: name })
           ] }),
@@ -230,7 +324,7 @@ function ConnectAi({ aiKey }) {
                 }
               )
             ] }),
-            /* @__PURE__ */ jsx("p", { id: hintId, className: "eb:min-h-4 eb:text-[11.5px] eb:text-foreground-muted", children: unusual ? /* @__PURE__ */ jsx("span", { className: "eb:text-warning", children: t("{provider} keys usually start with {prefix}.", { provider: name, prefix: keyHint }) }) : keyHint ? t("{provider} keys start with {prefix}.", { provider: name, prefix: keyHint }) : null })
+            /* @__PURE__ */ jsx("p", { id: hintId, className: "eb:min-h-4 eb:text-[11.5px] eb:text-foreground-muted", children: unusual ? /* @__PURE__ */ jsx("span", { className: "eb:text-warning", children: t("{provider} keys usually start with {prefix}.", { provider: name, prefix: keyHint }) }) : saved && !key ? t("A key for {provider} is saved in this browser: Connect uses it, or paste another one.", { provider: name }) : keyHint ? t("{provider} keys start with {prefix}.", { provider: name, prefix: keyHint }) : null })
           ] })
         ] }),
         /* @__PURE__ */ jsxs("div", { className: "eb:flex eb:items-start eb:gap-2 eb:border-t eb:border-border eb:bg-surface-75 eb:px-6 eb:py-3 eb:text-[11.5px] eb:leading-relaxed eb:text-foreground-lighter", children: [
@@ -239,7 +333,7 @@ function ConnectAi({ aiKey }) {
         ] }),
         /* @__PURE__ */ jsxs(DialogFooter, { className: "eb:border-t eb:border-border eb:px-6 eb:py-4", children: [
           /* @__PURE__ */ jsx(Button, { type: "button", variant: "ghost", onClick: () => aiKey.answer(null), children: t("Cancel") }),
-          /* @__PURE__ */ jsx(Button, { type: "submit", disabled: !key, "data-testid": "eb-ai-connect-submit", children: t("Connect") })
+          /* @__PURE__ */ jsx(Button, { type: "submit", disabled: !key && !saved, "data-testid": "eb-ai-connect-submit", children: t("Connect") })
         ] })
       ] })
     }
@@ -753,7 +847,13 @@ function createAi(options = {}) {
   }
   if (typeof askKey !== "boolean") throw new TypeError("createAi: `askKey` must be true or false");
   if (apiKey && askKey) throw new TypeError("createAi: `apiKey` (one key for all) or `askKey` (each user's own), not both");
-  const provider = usesProvider ? resolveProvider(providerOption) : null;
+  const choice = Array.isArray(providerOption);
+  if (choice && (!providerOption.length || !askKey)) {
+    throw new TypeError("createAi: a list of providers is for `askKey: true` \u2014 each user chooses one and connects their own key");
+  }
+  const providers = usesProvider ? (choice ? providerOption : [providerOption]).map(providerOf) : [];
+  if (new Set(providers.map((provider2) => provider2.id)).size !== providers.length) throw new TypeError("createAi: each provider once");
+  const [provider = null] = providers;
   if (provider && !apiKey && !askKey && !provider.keyless) {
     throw new TypeError(`createAi: ${provider.name} needs a key \u2014 \`apiKey\`, or \`askKey: true\` to let each user connect their own`);
   }
@@ -765,18 +865,31 @@ function createAi(options = {}) {
   }
   const ownOnly = !model && !http && PARTS.some((part) => typeof options[part] === "function");
   let transport = {};
-  const key = provider && askKey ? createKeyStore(provider) : null;
+  const key = provider && askKey ? createKeyStore(providers) : null;
   if (provider) {
-    const generator = createEmailGenerator({
-      model: providerEmailModel({
-        provider,
-        fetch: fetchImpl,
-        // The user's key, asked when there is none ('' when they cancel: KEY_MISSING).
-        apiKey: key ? async () => key.get() || await key.request() : apiKey
-      }),
-      maxAttempts,
-      compile
-    });
+    const models = /* @__PURE__ */ new Map();
+    const keyFor = () => key ? key.get() : apiKey || "";
+    const modelOf = (id) => {
+      if (!models.has(id)) {
+        const chosen = (
+          /** @type {import('./providers.js').AiProvider} */
+          providers.find((item) => item.id === id)
+        );
+        models.set(
+          id,
+          chosen.createModel ? chosen.createModel({ apiKey: keyFor, fetch: fetchImpl }) : providerEmailModel({ provider: chosen, fetch: fetchImpl, apiKey: keyFor })
+        );
+      }
+      return (
+        /** @type {import('./generator.js').EmailModel} */
+        models.get(id)
+      );
+    };
+    const model2 = async (request) => {
+      if (key && !key.get() && !providers.find((item) => item.id === key.provider.id)?.keyless) await key.request();
+      return modelOf(key ? key.provider.id : provider.id)(request);
+    };
+    const generator = createEmailGenerator({ model: model2, maxAttempts, compile });
     for (const part of PARTS) transport[part] = key ? askedAgain(generator[part], key) : generator[part];
   } else if (model) {
     transport = createEmailGenerator({ model, maxAttempts, compile });
@@ -810,6 +923,19 @@ function createAi(options = {}) {
     components: Object.freeze({ Generate: GenerateButton, Rewrite: RewriteText, Subjects: SubjectIdeas, Connect: key ? ConnectAi : null })
   });
 }
+function providerOf(option) {
+  if (option && typeof option === "object" && typeof option.createModel === "function") {
+    if (!option.id || !option.name) throw new TypeError("createAi: a provider with `createModel` needs an `id` and a `name`");
+    return (
+      /** @type {import('./providers.js').AiProvider} */
+      option
+    );
+  }
+  return resolveProvider(
+    /** @type {any} */
+    option
+  );
+}
 function askedAgain(run, key) {
   return async (input, options) => {
     try {
@@ -843,9 +969,11 @@ export {
   REWRITE_ACTIONS,
   REWRITE_LANGUAGES,
   claudeEmailModel,
+  claudeProvider,
   createAi,
   createEmailGenerator,
   emailWords,
+  failureCode,
   providerEmailModel,
   resolveProvider
 };