@perxel/spotlight 0.1.0 → 0.1.1

package/README.md

@@ -2,6 +2,8 @@
 
 Search or ask, like Spotlight. Press ⌘K: the box searches your site as you type, in the browser, with no request and no model call. Press Enter with nothing highlighted and the question goes to an AI chat that answers from your site.
 
+![The liquid skin on perxel.com: results as you type "next", the typed word marked in each row](https://raw.githubusercontent.com/perxel/perxel-spotlight/main/docs/perxel-gate.webp)
+
 - **Search and Ask are independent.** Give it documents, an endpoint, or both. Whatever you leave out is never loaded.
 - **Headless first.** Behaviour, keys, focus, ARIA and state (`data-*`) in React parts you style yourself. A **liquid glass skin** ships as the default, themed with CSS variables.
 - **No platform assumptions.** No Next.js import in the client (navigation is a prop), a Web-standard server helper (`Request` → `Response`: Next route handlers, Workers, Hono, Node), any [AI SDK](https://ai-sdk.dev) model, MCP optional.
@@ -9,6 +11,10 @@ Search or ask, like Spotlight. Press ⌘K: the box searches your site as you typ
 
 Built for [perxel.com](https://perxel.com) (liquid skin, answers through an MCP server) and [phucbm.com](https://phucbm.com) (its own "research paper" styling on the headless parts, answers from its pages and live data, no MCP).
 
+| perxel.com: the liquid skin's chat panel | phucbm.com: the headless parts, its own styling |
+|---|---|
+| ![The chat panel answering a question, with the pages it used folded under the answer](https://raw.githubusercontent.com/perxel/perxel-spotlight/main/docs/perxel-panel.webp) | ![A plain, paper-like search box on phucbm.com](https://raw.githubusercontent.com/perxel/perxel-spotlight/main/docs/phucbm-gate.webp) |
+
 | Search only | Ask only | Both |
 |---|---|---|
 | Plain site search; Enter opens the first result; the chat code never loads | A prompt box; the search code and index never load | Results as you type; Enter with nothing highlighted asks |
@@ -99,7 +105,8 @@ export const POST = createAskHandler({
 - **Stateless**: the client sends the history; only its text reaches the model (tool results and sources from the client are dropped).
 - **Three kinds of source**, mixed freely. `contentSource` searches and reads your pages with short passages per hit and capped pages (no MCP needed). `toolSource` runs your own AI SDK tools in the route (live numbers, structured data). `mcpSource` calls a remote MCP server over streamable HTTP with no SDK, any runtime with `fetch`; `fixed` sets arguments the model never sees (a locale), `tools` allowlists: an anonymous chat must never reach a private tool.
 - **Sources cited**: `{url, title}` pairs in tool results become `source-url` parts (4 at most, 2 per result; `cite: false` turns it off).
-- **Refusals** are `{code}` JSON (`verify_failed`, `rate_limited`, `conversation_limit`, `budget`, `bad_request`, `origin`, `upstream`); the panel shows `copy.errors[code]`.
+- **Refusals** are `{code}` JSON (`verify_failed`, `rate_limited`, `conversation_limit`, `budget`, `bad_request`, `origin`); an answer that fails while streaming ends with `config` (no API key, or the provider refused it: fix the route, not a retry) or `upstream` (the provider failed). The panel shows `copy.errors[code]`; the server logs the cause through `onError`.
+- **API keys**: the model is created with the key from wherever the platform keeps secrets (`process.env` on Node and Next, the Worker's env on Cloudflare: with OpenNext, `getCloudflareContext().env`, and `initOpenNextCloudflareForDev()` in `next.config` so `next dev` reads `.dev.vars`). An empty key only fails when a question is asked, so check it in a `model` function (`throw` when it is missing: the handler refuses with `config` before any call).
 - **Limits**: `maxInputChars` (1000), `maxQuestions` (20), `maxHistory` (20), `maxSteps` (4), `maxOutputTokens` (700). CORS only when `origins` is set.
 - On Workers, pass `waitUntil` so `onFinish` outlives the response.
 

package/dist/core/copy.js

@@ -23,6 +23,7 @@ export const defaultCopy = {
         verify_failed: "We could not check that you are not a bot. Please reload and try again.",
         conversation_limit: "This conversation is at its limit. Start a new chat.",
         budget: "Ask is resting for today. Please try again tomorrow.",
+        config: "Ask is not available right now.",
         upstream: "The answer could not be written. Please try again.",
         bad_request: "That message could not be sent.",
     },

package/dist/server/handler.d.ts

@@ -11,7 +11,13 @@ import type { AskContext, AskSource, Cited, ToolRun } from "./types.js";
  * → `verify` (bot check) → `rateLimit` → the model call. A refusal is `{code}` JSON with an HTTP
  * status; the panel maps the code to its copy.
  */
-export type AskErrorCode = "origin" | "bad_request" | "verify_failed" | "rate_limited" | "conversation_limit" | "budget" | "upstream";
+export type AskErrorCode = "origin" | "bad_request" | "verify_failed" | "rate_limited" | "conversation_limit" | "budget" | "config" | "upstream";
+/**
+ * A model error's code: `config` when the route is set up wrong (no API key, or the provider
+ * refused it: 401/403), so the visitor is not told to try again and the log says what to fix;
+ * `upstream` for the rest (provider down, timeout).
+ */
+export declare function modelErrorCode(err: unknown): "config" | "upstream";
 /** One answered turn, for `onFinish` (log it, store it, count its cost). */
 export interface AskTurn {
     /** The chat id the client sent (`useChat`'s id), if any. */
@@ -86,7 +92,7 @@ export interface AskHandlerOptions {
     maxOutputTokens?: number;
     /** Request body bytes (default 256 KB). */
     maxBodyBytes?: number;
-    /** Called with errors (model, tool, `onFinish`); default `console.error`. */
+    /** Called with errors (model, tool, `onFinish`); default `console.error`, with a hint when the model has no key or it was refused. */
     onError?: (error: unknown, where: "model" | "tool" | "finish") => void;
     /** Extra `streamText` settings (temperature, providerOptions…). */
     settings?: Record<string, unknown>;

package/dist/server/handler.js

@@ -6,8 +6,31 @@ const STATUS = {
     rate_limited: 429,
     conversation_limit: 429,
     budget: 503,
+    config: 503,
     upstream: 502,
 };
+/**
+ * A model error's code: `config` when the route is set up wrong (no API key, or the provider
+ * refused it: 401/403), so the visitor is not told to try again and the log says what to fix;
+ * `upstream` for the rest (provider down, timeout).
+ */
+export function modelErrorCode(err) {
+    let e = err;
+    // A retried call fails with the last attempt's error inside.
+    if (e?.name === "AI_RetryError" && e.lastError)
+        e = e.lastError;
+    if (e?.name === "AI_LoadAPIKeyError")
+        return "config";
+    if (e?.name === "AI_APICallError" && (e.statusCode === 401 || e.statusCode === 403))
+        return "config";
+    return "upstream";
+}
+function logError(err, where) {
+    if (where === "model" && modelErrorCode(err) === "config")
+        console.error(`[spotlight] model: the AI provider has no API key or refused it. Check the key the route's model is created with (an empty Worker secret or env var is a common cause).`, err);
+    else
+        console.error(`[spotlight] ${where}:`, err);
+}
 function isRecord(v) {
     return typeof v === "object" && v !== null && !Array.isArray(v);
 }
@@ -53,7 +76,7 @@ export function sourcesIn(data, limit = 50) {
     return out;
 }
 export function createAskHandler(options) {
-    const { sources = [], uiTools = [], maxInputChars = 1000, maxQuestions = 20, maxHistory = 20, maxHistoryChars = 4000, maxSteps = 4, maxOutputTokens = 700, maxBodyBytes = 256 * 1024, onError = (err, where) => console.error(`[spotlight] ${where}:`, err), } = options;
+    const { sources = [], uiTools = [], maxInputChars = 1000, maxQuestions = 20, maxHistory = 20, maxHistoryChars = 4000, maxSteps = 4, maxOutputTokens = 700, maxBodyBytes = 256 * 1024, onError = logError, } = options;
     const cite = options.cite === false ? null : { max: options.cite?.max ?? 4, perResult: options.cite?.perResult ?? 2 };
     const ui = new Set(uiTools);
     return async function handle(request) {
@@ -120,7 +143,15 @@ export function createAskHandler(options) {
         const limited = options.rateLimit ? await options.rateLimit(ctx) : true;
         if (limited !== true)
             return refuse(typeof limited === "string" ? limited : "rate_limited", { "retry-after": "60" });
-        const model = typeof options.model === "function" ? options.model(ctx) : options.model;
+        // A model factory that throws (a missing key checked by the site) refuses with `config`.
+        let model;
+        try {
+            model = typeof options.model === "function" ? options.model(ctx) : options.model;
+        }
+        catch (err) {
+            onError(err, "model");
+            return refuse("config");
+        }
         const system = typeof options.system === "function" ? await options.system(ctx) : options.system;
         const history = turns
             .slice(0, -1)
@@ -206,13 +237,13 @@ export function createAskHandler(options) {
                     stream: result.stream,
                     onError: (err) => {
                         onError(err, "model");
-                        return "upstream";
+                        return modelErrorCode(err);
                     },
                 }));
             },
             onError: (err) => {
                 onError(err, "model");
-                return "upstream";
+                return modelErrorCode(err);
             },
         });
         const headers = options.headers ? await options.headers(ctx) : undefined;

package/dist/server/index.d.ts

@@ -1,4 +1,4 @@
-export { createAskHandler, sourcesIn, type AskErrorCode, type AskHandlerOptions, type AskTurn } from "./handler.js";
+export { createAskHandler, modelErrorCode, sourcesIn, type AskErrorCode, type AskHandlerOptions, type AskTurn } from "./handler.js";
 export { contentSource, mcpSource, toolSource, passagesOf, sectionOf, resetMcpCache, type ContentDoc, type ContentSourceOptions, type McpSourceOptions } from "./sources.js";
 export { turnstile, type TurnstileOptions } from "./turnstile.js";
 export type { AskContext, AskSource, Cited, ToolRun } from "./types.js";

package/dist/server/index.js

@@ -1,5 +1,5 @@
 // `@perxel/spotlight/server`: an optional chat endpoint for Ask. Web-standard (`Request` →
 // `Response`), any AI SDK model, tools from the site's pages, its own functions or a remote MCP.
-export { createAskHandler, sourcesIn } from "./handler.js";
+export { createAskHandler, modelErrorCode, sourcesIn } from "./handler.js";
 export { contentSource, mcpSource, toolSource, passagesOf, sectionOf, resetMcpCache } from "./sources.js";
 export { turnstile } from "./turnstile.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@perxel/spotlight",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Search or ask, like Spotlight: a ⌘K box that searches a site as you type and hands a question to an AI chat on Enter. Headless React parts, an optional liquid glass skin, and a Web-standard server helper.",
   "license": "MIT",
   "author": "Perxel (https://perxel.com)",
@@ -23,6 +23,7 @@
     "headless"
   ],
   "type": "module",
+  "packageManager": "pnpm@10.22.0",
   "sideEffects": [
     "*.css"
   ],
@@ -63,6 +64,13 @@
   "publishConfig": {
     "access": "public"
   },
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.build.json && cp src/liquid/liquid.css dist/liquid/liquid.css",
+    "dev": "tsc -p tsconfig.build.json --watch",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "prepublishOnly": "pnpm build"
+  },
   "dependencies": {
     "@radix-ui/react-dialog": "^1.2.0",
     "streamdown": "^2.6.0",
@@ -92,11 +100,5 @@
     "react-dom": "19.3.0",
     "typescript": "6.0.3",
     "vitest": "^5.0.3"
-  },
-  "scripts": {
-    "build": "rm -rf dist && tsc -p tsconfig.build.json && cp src/liquid/liquid.css dist/liquid/liquid.css",
-    "dev": "tsc -p tsconfig.build.json --watch",
-    "typecheck": "tsc --noEmit",
-    "test": "vitest run"
   }
-}
+}