@coffer-org/server 2.3.1 → 2.3.2

package/dist/embed-openai.d.ts

@@ -1,5 +1,19 @@
 export declare const EMBED_MODEL = "text-embedding-3-small";
 export declare const EMBED_DIM = 1024;
+export type EmbeddingFailureReason = 'billing' | 'auth' | 'rate_limit' | 'server' | 'network' | 'unknown';
+export declare class OpenAIEmbeddingError extends Error {
+    readonly status: number | null;
+    readonly code: string | null;
+    readonly reason: EmbeddingFailureReason;
+    constructor(args: {
+        status?: number | null;
+        code?: string | null;
+        detail?: string;
+        reason?: EmbeddingFailureReason;
+        cause?: unknown;
+    });
+}
+export declare function embeddingFailureMessage(error: unknown): string;
 export declare function embedBatch(texts: string[], apiKey: string, fetchImpl?: typeof fetch): Promise<{
     vectors: number[][];
     tokens: number;

package/dist/embed-openai.js

@@ -1,19 +1,78 @@
 const OPENAI_URL = 'https://api.openai.com/v1/embeddings';
 export const EMBED_MODEL = 'text-embedding-3-small';
 export const EMBED_DIM = 1024;
+export class OpenAIEmbeddingError extends Error {
+    status;
+    code;
+    reason;
+    constructor(args) {
+        const status = args.status ?? null;
+        const suffix = args.detail ? `: ${args.detail}` : '';
+        super(`openai embeddings${status == null ? '' : ` ${status}`}${suffix}`, { cause: args.cause });
+        this.name = 'OpenAIEmbeddingError';
+        this.status = status;
+        this.code = args.code ?? null;
+        this.reason = args.reason ?? classifyEmbeddingFailure(status, args.code, args.detail);
+    }
+}
+function parseErrorBody(body) {
+    try {
+        const value = JSON.parse(body);
+        const code = typeof value.error?.code === 'string' ? value.error.code : null;
+        const message = typeof value.error?.message === 'string' ? value.error.message : '';
+        if (code || message)
+            return { code, detail: message || code || 'request failed' };
+    }
+    catch {
+    }
+    return { code: null, detail: body.slice(0, 200) || 'request failed' };
+}
+function classifyEmbeddingFailure(status, code, detail) {
+    const marker = `${code ?? ''} ${detail ?? ''}`.toLowerCase();
+    if (status === 402 || /insufficient_quota|billing|payment_required|payment required|hard.?limit|quota exceeded/.test(marker))
+        return 'billing';
+    if (status === 401 || status === 403)
+        return 'auth';
+    if (status === 429 || /rate.?limit/.test(marker))
+        return 'rate_limit';
+    if (status != null && status >= 500)
+        return 'server';
+    return 'unknown';
+}
+export function embeddingFailureMessage(error) {
+    if (!(error instanceof OpenAIEmbeddingError))
+        return error instanceof Error ? error.message : String(error);
+    switch (error.reason) {
+        case 'billing':
+            return 'OpenAI billing or quota is unavailable. RAG indexing/search is paused; records are still saved and indexing will retry after billing is restored.';
+        case 'auth':
+            return 'The OpenAI API key was rejected. RAG indexing/search is unavailable; records are still saved.';
+        case 'rate_limit':
+            return 'OpenAI rate limit reached. RAG indexing/search will retry; records are still saved.';
+        default:
+            return `OpenAI embeddings are unavailable${error.status == null ? '' : ` (HTTP ${error.status})`}. RAG will retry; records are still saved.`;
+    }
+}
 export async function embedBatch(texts, apiKey, fetchImpl = fetch) {
     if (texts.length === 0)
         return { vectors: [], tokens: 0 };
     if (!apiKey)
         throw new Error('embeddings: missing API key (OPENAI_API_KEY)');
-    const res = await fetchImpl(OPENAI_URL, {
-        method: 'POST',
-        headers: { 'content-type': 'application/json', authorization: `Bearer ${apiKey}` },
-        body: JSON.stringify({ model: EMBED_MODEL, input: texts, dimensions: EMBED_DIM }),
-    });
+    let res;
+    try {
+        res = await fetchImpl(OPENAI_URL, {
+            method: 'POST',
+            headers: { 'content-type': 'application/json', authorization: `Bearer ${apiKey}` },
+            body: JSON.stringify({ model: EMBED_MODEL, input: texts, dimensions: EMBED_DIM }),
+        });
+    }
+    catch (cause) {
+        throw new OpenAIEmbeddingError({ reason: 'network', detail: 'network request failed', cause });
+    }
     if (!res.ok) {
         const body = await res.text().catch(() => '');
-        throw new Error(`openai embeddings ${res.status}: ${body.slice(0, 200)}`);
+        const parsed = parseErrorBody(body);
+        throw new OpenAIEmbeddingError({ status: res.status, code: parsed.code, detail: parsed.detail });
     }
     const json = (await res.json());
     const vectors = [...json.data].sort((a, b) => a.index - b.index).map((d) => d.embedding);

package/dist/mcp-tools.js

@@ -11,7 +11,7 @@ import { describeCondition } from '@coffer-org/sdk/condition';
 import { getEm } from "./db.js";
 import { getPluginSettings } from "./plugin-runtime.js";
 import { searchEmbeddings } from "./embeddings.js";
-import { embedOne } from "./embed-openai.js";
+import { embedOne, embeddingFailureMessage } from "./embed-openai.js";
 import { getLogger } from "./log.js";
 import { writePluginSettings, listSettings } from "./settings-write.js";
 import { ValidationError, NotFoundError } from "./mutate.js";
@@ -143,7 +143,7 @@ export async function collectMcpTools(opts = {}) {
                     return { content: [{ type: 'text', text: formatHits(hits) }] };
                 }
                 catch (e) {
-                    return fail(`Error: ${e.message}`);
+                    return fail(`RAG unavailable: ${embeddingFailureMessage(e)} Use the regular coffer tools (list_records/get_record) instead.`);
                 }
             },
         });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@coffer-org/server",
-  "version": "2.3.1",
+  "version": "2.3.2",
   "type": "module",
   "engines": {
     "node": ">=24"