@seedgrid/fe-core 2026.6.3 → 2026.6.4

package/dist/ai/seedgrid-core.manifest.json

@@ -661,7 +661,7 @@
         "displayName": "API Error Message Extractor",
         "category": "utility",
         "subcategory": "http",
-        "description": "Reads API problem payloads and extracts the best user-facing message, prioritizing RFC7807 violations before generic detail/title fields.",
+        "description": "Reads API problem payloads and extracts the best user-facing message, prioritizing RFC7807 violations before userMessage/detail/title. Walks the whole error chain (responseBody/cause/error/data/body) so it works even when the problem payload is nested, rewrapped, or has crossed a bundle boundary.",
         "tags": [
           "api",
           "http",
@@ -673,8 +673,10 @@
           "api-client-error",
           "rfc7807",
           "violations",
+          "user-message",
           "error-message",
-          "json-string-body"
+          "json-string-body",
+          "nested-error-chain"
         ],
         "fieldSemantics": [
           "error",

package/dist/http/api-errors.d.ts

@@ -1,9 +1,29 @@
-export declare function isApiClientErrorLike(error: unknown): error is {
+type ApiClientErrorLike = {
+    cause?: unknown;
+    body?: unknown;
+    data?: unknown;
+    error?: unknown;
     message?: unknown;
-    responseBody?: unknown;
     detail?: unknown;
     status?: unknown;
+    responseBody?: unknown;
 };
+/**
+ * Type guard mantido por compatibilidade: qualquer objeto pode carregar um
+ * `responseBody`/`detail` de onde extrair a mensagem.
+ */
+export declare function isApiClientErrorLike(error: unknown): error is ApiClientErrorLike;
+/**
+ * Melhor mensagem amigável a partir de QUALQUER valor lançado por uma chamada de
+ * API. Varre a cadeia do erro, então acha o problem+json mesmo aninhado/embrulhado.
+ * Cai no `.message` do próprio erro só quando não há payload de problema.
+ */
 export declare function extractApiErrorMessage(error: unknown): string | null;
+/**
+ * Mensagem a partir de UM corpo já em mãos (objeto problem+json, ou string JSON que
+ * parseie em um). Texto simples não-JSON -> o próprio texto; objeto sem mensagem
+ * útil -> null (nunca o JSON cru).
+ */
 export declare function readApiErrorMessage(body: unknown): string | null;
+export {};
 //# sourceMappingURL=api-errors.d.ts.map

package/dist/http/api-errors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"api-errors.d.ts","sourceRoot":"","sources":["../../src/http/api-errors.ts"],"names":[],"mappings":"AAMA,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,OAAO,GACb,KAAK,IAAI;IACV,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB,CAEA;AAED,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAqBpE;AAED,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAoChE"}
+{"version":3,"file":"api-errors.d.ts","sourceRoot":"","sources":["../../src/http/api-errors.ts"],"names":[],"mappings":"AAiCA,KAAK,kBAAkB,GAAG;IACxB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB,CAAC;AAEF;;;GAGG;AACH,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,OAAO,GACb,KAAK,IAAI,kBAAkB,CAE7B;AAED;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAapE;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAMhE"}

package/dist/http/api-errors.js

@@ -1,75 +1,149 @@
 // seedgrid:managed
-import { ApiClientError } from "./api-client";
+/**
+ * Type guard mantido por compatibilidade: qualquer objeto pode carregar um
+ * `responseBody`/`detail` de onde extrair a mensagem.
+ */
 export function isApiClientErrorLike(error) {
     return Boolean(error && typeof error === "object");
 }
+/**
+ * Melhor mensagem amigável a partir de QUALQUER valor lançado por uma chamada de
+ * API. Varre a cadeia do erro, então acha o problem+json mesmo aninhado/embrulhado.
+ * Cai no `.message` do próprio erro só quando não há payload de problema.
+ */
 export function extractApiErrorMessage(error) {
-    if (error instanceof ApiClientError) {
-        return (readApiErrorMessage(error.responseBody) ??
-            pickString(error.message));
+    const fromProblem = readProblemMessage(findProblemDetails(error));
+    if (fromProblem) {
+        return fromProblem;
     }
-    if (isApiClientErrorLike(error)) {
-        return (readApiErrorMessage(error.responseBody) ??
-            pickString(error.message) ??
-            pickString(error.detail));
-    }
-    if (error instanceof Error) {
-        return pickString(error.message);
+    // Sem payload de problema útil: cai no `.message` do erro APENAS quando não é um
+    // erro do httpclient. O ApiClientError carrega `responseBody` e tem `.message`
+    // genérico ("API request failed with status N") — devolver isso vazaria texto
+    // técnico e impediria o fallback amigável por-ação do chamador; então retorna null.
+    if (isRecord(error) && "responseBody" in error) {
+        return null;
     }
-    return null;
+    return pickString(readErrorMessage(error));
 }
+/**
+ * Mensagem a partir de UM corpo já em mãos (objeto problem+json, ou string JSON que
+ * parseie em um). Texto simples não-JSON -> o próprio texto; objeto sem mensagem
+ * útil -> null (nunca o JSON cru).
+ */
 export function readApiErrorMessage(body) {
-    const normalizedBody = normalizeApiBody(body);
-    if (!normalizedBody || typeof normalizedBody !== "object") {
-        return pickString(normalizedBody);
-    }
-    const record = normalizedBody;
-    if (Array.isArray(record.violations)) {
-        for (const entry of record.violations) {
-            const violationMessage = readRecordMessage(entry);
-            if (violationMessage) {
-                return violationMessage;
-            }
-        }
+    const normalized = normalizeApiBody(body);
+    if (!isRecord(normalized)) {
+        return pickString(normalized);
+    }
+    return readProblemMessage(normalized);
+}
+function readProblemMessage(problem) {
+    if (!problem) {
+        return null;
     }
-    if (Array.isArray(record.errors)) {
-        for (const entry of record.errors) {
-            const nestedMessage = readRecordMessage(entry);
-            if (nestedMessage) {
-                return nestedMessage;
+    return (readViolationMessage(problem.violations) ??
+        readViolationMessage(problem.errors) ??
+        pickString(problem.userMessage) ??
+        pickString(problem.detail) ??
+        pickString(problem.message) ??
+        pickString(problem.error) ??
+        pickString(problem.title));
+}
+function findProblemDetails(error) {
+    const queue = [error];
+    const visited = new Set();
+    while (queue.length > 0) {
+        const current = queue.shift();
+        if (current == null) {
+            continue;
+        }
+        // Uma string pode ser ela mesma o payload problem+json (corpo não desserializado).
+        if (typeof current === "string") {
+            const parsed = parseProblemDetails(current);
+            if (parsed && hasProblemSignals(parsed)) {
+                return parsed;
             }
+            continue;
+        }
+        if (typeof current !== "object" || visited.has(current)) {
+            continue;
+        }
+        visited.add(current);
+        // Pula o `.message` genérico de Error pra alcançar o responseBody real — senão a
+        // mensagem genérica ("Request failed with 400") mascararia o detail do RFC7807.
+        if (current instanceof Error) {
+            const candidate = current;
+            queue.push(candidate.responseBody, candidate.cause, candidate.data, candidate.body);
+            continue;
         }
+        if (hasProblemSignals(current)) {
+            return current;
+        }
+        const candidate = current;
+        queue.push(candidate.responseBody, candidate.cause, candidate.error, candidate.data, candidate.body);
+    }
+    return null;
+}
+function hasProblemSignals(problem) {
+    return readProblemMessage(problem) != null;
+}
+function parseProblemDetails(value) {
+    if (isRecord(value)) {
+        return value;
+    }
+    if (typeof value !== "string") {
+        return null;
+    }
+    try {
+        const parsed = JSON.parse(value);
+        return isRecord(parsed) ? parsed : null;
+    }
+    catch {
+        return null;
     }
-    return (pickString(record.userMessage) ??
-        pickString(record.detail) ??
-        pickString(record.message) ??
-        pickString(record.error) ??
-        pickString(record.title));
 }
 function normalizeApiBody(body) {
     if (typeof body !== "string") {
         return body;
     }
-    const normalized = body.trim();
-    if (!normalized) {
+    const trimmed = body.trim();
+    if (!trimmed) {
         return body;
     }
     try {
-        return JSON.parse(normalized);
+        return JSON.parse(trimmed);
     }
     catch {
         return body;
     }
 }
-function readRecordMessage(value) {
-    if (!value || typeof value !== "object") {
+function readViolationMessage(value) {
+    if (!Array.isArray(value)) {
         return null;
     }
-    const record = value;
-    return (pickString(record.userMessage) ??
-        pickString(record.message) ??
-        pickString(record.error) ??
-        pickString(record.description));
+    for (const violation of value) {
+        if (!isRecord(violation)) {
+            continue;
+        }
+        const entry = violation;
+        const message = pickString(entry.message) ??
+            pickString(entry.userMessage) ??
+            pickString(entry.error) ??
+            pickString(entry.description);
+        if (message) {
+            return message;
+        }
+    }
+    return null;
+}
+function readErrorMessage(error) {
+    if (!isRecord(error) || !("message" in error)) {
+        return null;
+    }
+    return error.message ?? null;
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null;
 }
 function pickString(value) {
     return typeof value === "string" && value.trim().length > 0

package/dist/http/api-errors.meta.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"api-errors.meta.d.ts","sourceRoot":"","sources":["../../src/http/api-errors.meta.ts"],"names":[],"mappings":"AAAA,KAAK,YAAY,GAAG;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,YAAY,CAAC,EACT,OAAO,GACP,OAAO,GACP,YAAY,GACZ,UAAU,GACV,YAAY,GACZ,OAAO,GACP,MAAM,CAAC;IACX,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB,CAAC;AAEF,KAAK,QAAQ,GAAG;IACd,OAAO,EAAE,KAAK,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B,KAAK,CAAC,EAAE,YAAY,EAAE,CAAC;IACvB,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;CACnB,CAAC;AAEF,KAAK,WAAW,GAAG;IACjB,OAAO,EAAE,KAAK,CAAC;IACf,iBAAiB,EAAE,MAAM,EAAE,CAAC;IAC5B,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IACzB,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,mBAAmB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC/B,gBAAgB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC5B,cAAc,CAAC,EAAE;QACf,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,gBAAgB,CAAC,EAAE,MAAM,CAAC;QAC1B,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,WAAW,CAAC,EAAE,MAAM,CAAC;KACtB,CAAC;CACH,CAAC;AAEF,eAAO,MAAM,MAAM,EAAE,QA+BpB,CAAC;AAEF,eAAO,MAAM,OAAO,EAAE,WA6BrB,CAAC"}
+{"version":3,"file":"api-errors.meta.d.ts","sourceRoot":"","sources":["../../src/http/api-errors.meta.ts"],"names":[],"mappings":"AAAA,KAAK,YAAY,GAAG;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,YAAY,CAAC,EACT,OAAO,GACP,OAAO,GACP,YAAY,GACZ,UAAU,GACV,YAAY,GACZ,OAAO,GACP,MAAM,CAAC;IACX,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB,CAAC;AAEF,KAAK,QAAQ,GAAG;IACd,OAAO,EAAE,KAAK,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B,KAAK,CAAC,EAAE,YAAY,EAAE,CAAC;IACvB,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;CACnB,CAAC;AAEF,KAAK,WAAW,GAAG;IACjB,OAAO,EAAE,KAAK,CAAC;IACf,iBAAiB,EAAE,MAAM,EAAE,CAAC;IAC5B,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IACzB,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,mBAAmB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC/B,gBAAgB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC5B,cAAc,CAAC,EAAE;QACf,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,gBAAgB,CAAC,EAAE,MAAM,CAAC;QAC1B,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,WAAW,CAAC,EAAE,MAAM,CAAC;KACtB,CAAC;CACH,CAAC;AAEF,eAAO,MAAM,MAAM,EAAE,QAiCpB,CAAC;AAEF,eAAO,MAAM,OAAO,EAAE,WA6BrB,CAAC"}

package/dist/http/api-errors.meta.js

@@ -7,14 +7,16 @@ export const sgMeta = {
     displayName: "API Error Message Extractor",
     category: "utility",
     subcategory: "http",
-    description: "Reads API problem payloads and extracts the best user-facing message, prioritizing RFC7807 violations before generic detail/title fields.",
+    description: "Reads API problem payloads and extracts the best user-facing message, prioritizing RFC7807 violations before userMessage/detail/title. Walks the whole error chain (responseBody/cause/error/data/body) so it works even when the problem payload is nested, rewrapped, or has crossed a bundle boundary.",
     tags: ["api", "http", "error", "rfc7807", "validation"],
     capabilities: [
         "api-client-error",
         "rfc7807",
         "violations",
+        "user-message",
         "error-message",
         "json-string-body",
+        "nested-error-chain",
     ],
     fieldSemantics: ["error", "validation", "problem-details", "http"],
     props: [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@seedgrid/fe-core",
-  "version": "2026.6.3",
+  "version": "2026.6.4",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -29,6 +29,7 @@
   },
   "scripts": {
     "build": "tsc -p tsconfig.json && node scripts/build-ai-manifest.mjs",
-    "typecheck": "tsc -p tsconfig.json --noEmit"
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "pnpm run build && node --test tests/api-errors.test.mjs"
   }
 }