@echofiles/echo-pdf 0.10.1 → 0.11.2

package/dist/provider-client.js

@@ -1,4 +1,28 @@
 import { resolveProviderApiKey } from "./provider-keys.js";
+class ProviderRequestError extends Error {
+    code;
+    detail;
+    constructor(code, detail) {
+        const parts = [
+            `${detail.operation} failed`,
+            `code=${code}`,
+            `url=${detail.url}`,
+            `attempt=${detail.attempt}/${detail.maxAttempts}`,
+        ];
+        if (typeof detail.status === "number")
+            parts.push(`http=${detail.status}`);
+        if (detail.contentType)
+            parts.push(`contentType=${detail.contentType}`);
+        if (detail.causeMessage)
+            parts.push(`cause=${detail.causeMessage}`);
+        if (detail.responsePreview)
+            parts.push(`preview=${JSON.stringify(detail.responsePreview)}`);
+        super(parts.join(" "));
+        this.code = code;
+        this.detail = detail;
+        this.name = "ProviderRequestError";
+    }
+}
 const defaultBaseUrl = (provider) => {
     if (provider.baseUrl)
         return provider.baseUrl;
@@ -32,33 +56,197 @@ const toAuthHeader = (config, providerAlias, provider, env, runtimeApiKeys) => {
     });
     return token ? { Authorization: `Bearer ${token}` } : {};
 };
-const withTimeout = async (url, init, timeoutMs) => {
+const isPrivateIpv4 = (hostname) => /^10\./.test(hostname) ||
+    /^127\./.test(hostname) ||
+    /^192\.168\./.test(hostname) ||
+    /^172\.(1[6-9]|2\d|3[0-1])\./.test(hostname);
+const isLocalOpenAiCompatible = (provider, url) => {
+    try {
+        const parsed = new URL(url);
+        const hostname = parsed.hostname.toLowerCase();
+        return (provider.type === "openai-compatible" &&
+            (hostname === "localhost" || hostname === "::1" || isPrivateIpv4(hostname)));
+    }
+    catch {
+        return false;
+    }
+};
+const maxAttemptsFor = (provider, url, method, operation) => {
+    if (method !== "POST")
+        return 1;
+    if (operation === "Model list request")
+        return 1;
+    return isLocalOpenAiCompatible(provider, url) ? 2 : 1;
+};
+const truncate = (value, length = 800) => value.slice(0, length);
+const withTimeout = async (input) => {
     const ctrl = new AbortController();
-    const timer = setTimeout(() => ctrl.abort("timeout"), timeoutMs);
+    const timer = setTimeout(() => ctrl.abort("timeout"), input.timeoutMs);
     try {
-        return await fetch(url, { ...init, signal: ctrl.signal });
+        return await fetch(input.url, { ...input.init, signal: ctrl.signal });
     }
     catch (error) {
         if (error instanceof Error && error.name === "AbortError") {
-            throw new Error(`Request timeout after ${timeoutMs}ms for ${url}`);
+            throw new ProviderRequestError("PROVIDER_REQUEST_TIMEOUT", {
+                operation: input.operation,
+                providerAlias: input.providerAlias,
+                url: input.url,
+                attempt: input.attempt,
+                maxAttempts: input.maxAttempts,
+                causeMessage: `timeout after ${input.timeoutMs}ms`,
+            });
         }
-        throw error;
+        throw new ProviderRequestError("PROVIDER_REQUEST_SEND_FAILED", {
+            operation: input.operation,
+            providerAlias: input.providerAlias,
+            url: input.url,
+            attempt: input.attempt,
+            maxAttempts: input.maxAttempts,
+            causeMessage: error instanceof Error ? error.message : String(error),
+        });
     }
     finally {
         clearTimeout(timer);
     }
 };
-const responseDetail = async (response) => {
-    const contentType = response.headers.get("content-type") ?? "";
+const readResponseText = async (input) => {
+    const reader = input.response.body?.getReader();
+    if (!reader) {
+        try {
+            return await input.response.text();
+        }
+        catch (error) {
+            throw new ProviderRequestError("PROVIDER_RESPONSE_BODY_READ_FAILED", {
+                operation: input.operation,
+                providerAlias: input.providerAlias,
+                url: input.url,
+                status: input.response.status,
+                contentType: input.response.headers.get("content-type") ?? "",
+                attempt: input.attempt,
+                maxAttempts: input.maxAttempts,
+                causeMessage: error instanceof Error ? error.message : String(error),
+            });
+        }
+    }
+    const chunks = [];
+    let total = 0;
     try {
-        if (contentType.includes("application/json")) {
-            return JSON.stringify(await response.json()).slice(0, 800);
+        while (true) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            if (!value || value.length === 0)
+                continue;
+            chunks.push(value);
+            total += value.length;
         }
-        return (await response.text()).slice(0, 800);
     }
-    catch {
-        return "<unable to parse response payload>";
+    catch (error) {
+        const combined = new Uint8Array(total);
+        let offset = 0;
+        for (const chunk of chunks) {
+            combined.set(chunk, offset);
+            offset += chunk.length;
+        }
+        throw new ProviderRequestError("PROVIDER_RESPONSE_BODY_READ_FAILED", {
+            operation: input.operation,
+            providerAlias: input.providerAlias,
+            url: input.url,
+            status: input.response.status,
+            contentType: input.response.headers.get("content-type") ?? "",
+            attempt: input.attempt,
+            maxAttempts: input.maxAttempts,
+            causeMessage: error instanceof Error ? error.message : String(error),
+            responsePreview: truncate(new TextDecoder().decode(combined)),
+        });
+    }
+    const combined = new Uint8Array(total);
+    let offset = 0;
+    for (const chunk of chunks) {
+        combined.set(chunk, offset);
+        offset += chunk.length;
     }
+    return new TextDecoder().decode(combined);
+};
+const parseJsonResponse = (input) => {
+    try {
+        return JSON.parse(input.rawText);
+    }
+    catch (error) {
+        throw new ProviderRequestError("PROVIDER_RESPONSE_JSON_PARSE_FAILED", {
+            operation: input.operation,
+            providerAlias: input.providerAlias,
+            url: input.url,
+            status: input.response.status,
+            contentType: input.response.headers.get("content-type") ?? "",
+            attempt: input.attempt,
+            maxAttempts: input.maxAttempts,
+            causeMessage: error instanceof Error ? error.message : String(error),
+            responsePreview: truncate(input.rawText),
+        });
+    }
+};
+const requestJson = async (input) => {
+    const maxAttempts = maxAttemptsFor(input.provider, input.url, input.method, input.operation);
+    let lastError = null;
+    for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
+        try {
+            const response = await withTimeout({
+                operation: input.operation,
+                providerAlias: input.providerAlias,
+                url: input.url,
+                init: {
+                    method: input.method,
+                    headers: input.headers,
+                    ...(typeof input.body === "string" ? { body: input.body } : {}),
+                },
+                timeoutMs: input.provider.timeoutMs ?? 30000,
+                attempt,
+                maxAttempts,
+            });
+            const rawText = await readResponseText({
+                response,
+                operation: input.operation,
+                providerAlias: input.providerAlias,
+                url: input.url,
+                attempt,
+                maxAttempts,
+            });
+            if (!response.ok) {
+                throw new ProviderRequestError("PROVIDER_HTTP_ERROR", {
+                    operation: input.operation,
+                    providerAlias: input.providerAlias,
+                    url: input.url,
+                    status: response.status,
+                    contentType: response.headers.get("content-type") ?? "",
+                    attempt,
+                    maxAttempts,
+                    responsePreview: truncate(rawText),
+                });
+            }
+            return parseJsonResponse({
+                rawText,
+                response,
+                operation: input.operation,
+                providerAlias: input.providerAlias,
+                url: input.url,
+                attempt,
+                maxAttempts,
+            });
+        }
+        catch (error) {
+            lastError = error instanceof Error ? error : new Error(String(error));
+            if (attempt < maxAttempts &&
+                lastError instanceof ProviderRequestError &&
+                (lastError.code === "PROVIDER_REQUEST_SEND_FAILED" ||
+                    lastError.code === "PROVIDER_RESPONSE_BODY_READ_FAILED" ||
+                    lastError.code === "PROVIDER_RESPONSE_JSON_PARSE_FAILED")) {
+                continue;
+            }
+            throw lastError;
+        }
+    }
+    throw lastError ?? new Error(`${input.operation} failed`);
 };
 const getProvider = (config, alias) => {
     const provider = config.providers[alias];
@@ -70,18 +258,20 @@ const getProvider = (config, alias) => {
 export const listProviderModels = async (config, env, alias, runtimeApiKeys) => {
     const provider = getProvider(config, alias);
     const url = resolveEndpoint(provider, "modelsPath");
-    const response = await withTimeout(url, {
+    const payload = await requestJson({
+        operation: "Model list request",
+        config,
+        env,
+        providerAlias: alias,
+        provider,
+        url,
         method: "GET",
         headers: {
             Accept: "application/json",
             ...toAuthHeader(config, alias, provider, env, runtimeApiKeys),
             ...(provider.headers ?? {}),
         },
-    }, provider.timeoutMs ?? 30000);
-    if (!response.ok) {
-        throw new Error(`Model list request failed: HTTP ${response.status} url=${url} detail=${await responseDetail(response)}`);
-    }
-    const payload = await response.json();
+    });
     const data = payload.data;
     if (!Array.isArray(data))
         return [];
@@ -93,7 +283,13 @@ export const listProviderModels = async (config, env, alias, runtimeApiKeys) =>
 export const visionRecognize = async (input) => {
     const provider = getProvider(input.config, input.providerAlias);
     const url = resolveEndpoint(provider, "chatCompletionsPath");
-    const response = await withTimeout(url, {
+    const payload = await requestJson({
+        operation: "Vision request",
+        config: input.config,
+        env: input.env,
+        providerAlias: input.providerAlias,
+        provider,
+        url,
         method: "POST",
         headers: {
             "Content-Type": "application/json",
@@ -112,11 +308,7 @@ export const visionRecognize = async (input) => {
                 },
             ],
         }),
-    }, provider.timeoutMs ?? 30000);
-    if (!response.ok) {
-        throw new Error(`Vision request failed: HTTP ${response.status} url=${url} detail=${await responseDetail(response)}`);
-    }
-    const payload = await response.json();
+    });
     const message = payload.choices?.[0]?.message;
     if (!message)
         return "";
@@ -135,7 +327,13 @@ export const visionRecognize = async (input) => {
 export const generateText = async (input) => {
     const provider = getProvider(input.config, input.providerAlias);
     const url = resolveEndpoint(provider, "chatCompletionsPath");
-    const response = await withTimeout(url, {
+    const payload = await requestJson({
+        operation: "Text generation request",
+        config: input.config,
+        env: input.env,
+        providerAlias: input.providerAlias,
+        provider,
+        url,
         method: "POST",
         headers: {
             "Content-Type": "application/json",
@@ -151,11 +349,7 @@ export const generateText = async (input) => {
                 },
             ],
         }),
-    }, provider.timeoutMs ?? 30000);
-    if (!response.ok) {
-        throw new Error(`Text generation request failed: HTTP ${response.status} url=${url} detail=${await responseDetail(response)}`);
-    }
-    const payload = await response.json();
+    });
     const message = payload.choices?.[0]?.message;
     if (!message)
         return "";

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@echofiles/echo-pdf",
   "description": "Local-first PDF document component core with CLI, workspace artifacts, and reusable page primitives.",
-  "version": "0.10.1",
+  "version": "0.11.2",
   "type": "module",
   "homepage": "https://pdf.echofile.ai/",
   "repository": {
@@ -57,7 +57,7 @@
     "test:unit": "npm run check:runtime && vitest run tests/unit",
     "test:acceptance": "npm run check:runtime && npm run build && vitest run tests/acceptance",
     "test:import-smoke": "npm run check:runtime && npm run build && vitest run tests/integration/npm-pack-import.integration.test.ts tests/integration/ts-nodenext-consumer.integration.test.ts",
-    "test:integration": "npm run check:runtime && npm run build && vitest run tests/integration/local-document-cli.integration.test.ts tests/integration/local-document.integration.test.ts tests/integration/local-semantic-structure.integration.test.ts tests/integration/npm-pack-import.integration.test.ts tests/integration/ts-nodenext-consumer.integration.test.ts",
+    "test:integration": "npm run check:runtime && npm run build && vitest run tests/integration/local-document-cli.integration.test.ts tests/integration/local-document.integration.test.ts tests/integration/local-provider-stability.integration.test.ts tests/integration/local-semantic-structure.integration.test.ts tests/integration/npm-pack-import.integration.test.ts tests/integration/ts-nodenext-consumer.integration.test.ts",
     "test": "npm run test:unit && npm run test:acceptance && npm run test:integration",
     "smoke": "bash ./scripts/smoke.sh",
     "prepublishOnly": "npm run build && npm run typecheck && npm run test"