@ovok/core 0.4.44 → 0.4.45

package/README.md

@@ -322,8 +322,8 @@ when `nextCursor` is `null`. Feed `noteCount` is nullable: `null` means the coun
 zero. Notification notes are practitioner-authored and do not acknowledge or otherwise change an
 alert. After a note mutation, mounted note and alert-feed hooks reload their data.
 
-Writes can return `OvokApiError`, which keeps the HTTP status, machine code, validation field errors,
-and any missing-baseline details. In particular, reload the affected record before retrying a 409;
+Writes can return `OvokApiError`, which keeps the HTTP status, machine code, problem `type`, `traceId`,
+validation field errors (each with its `FIELD_*` code), and any missing-baseline details. In particular, reload the affected record before retrying a 409;
 do not automatically replay a stale assignment. A 409 `signals_project_migrating` should be shown
 as a temporary home-migration conflict, not retried in a loop. Threshold writes can return 422
 validation errors or 424 when the baseline has not been collected. Hooks never replay a write with

package/dist/client/auth/session-http.js

@@ -24,6 +24,22 @@ const retryAfterMs = async (response) => {
     }
 };
 exports.retryAfterMs = retryAfterMs;
+// What `readOvokError` reads from Core's error body: the problem members and the legacy ones kept beside them.
+const PRESERVED_ERROR_KEYS = [
+    "type",
+    "status",
+    "detail",
+    "instance",
+    "traceId",
+    "errors",
+    "code",
+    "error",
+    "message",
+    "requestId",
+    "retryAfterSec",
+    "statusCode",
+    "missing",
+];
 const timeoutError = () => (0, ovok_error_utils_1.namedError)("TimeoutError", "The request timed out.");
 const withHttpErrorMetadata = async (response, retry) => {
     var _a;
@@ -47,7 +63,7 @@ const withHttpErrorMetadata = async (response, retry) => {
         ? envelope.error
         : undefined;
     const safeResponse = envelope
-        ? Object.fromEntries(Object.entries(envelope).filter(([key]) => ["code", "error", "message", "requestId", "retryAfterSec", "status", "statusCode", "errors", "missing"].includes(key)))
+        ? Object.fromEntries(Object.entries(envelope).filter(([key]) => PRESERVED_ERROR_KEYS.includes(key)))
         : { message: typeof body === "string" ? body : response.statusText };
     const status = response.status;
     const retryAfter = retry ? retry.milliseconds : await (0, exports.retryAfterMs)(response);

package/dist/client/errors/field-errors.d.ts

@@ -0,0 +1,2 @@
+import { ValidationError } from "../../types/ValidationError";
+export declare function readFieldErrors(payload: Record<string, unknown> | undefined): ValidationError[];

package/dist/client/errors/field-errors.js

@@ -0,0 +1,84 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readFieldErrors = readFieldErrors;
+const ovok_error_utils_1 = require("./ovok-error-utils");
+function readEnvelopeErrors(values) {
+    return values.flatMap((value) => {
+        const record = (0, ovok_error_utils_1.asRecord)(value);
+        if (!record || typeof record.message !== "string") {
+            return [];
+        }
+        const path = Array.isArray(record.path)
+            ? record.path.map((segment) => String(segment))
+            : [];
+        return [{
+                ...((0, ovok_error_utils_1.stringValue)(record.code) ? { code: (0, ovok_error_utils_1.stringValue)(record.code) } : {}),
+                message: record.message,
+                path,
+                ...((0, ovok_error_utils_1.stringValue)(record.validation)
+                    ? { validation: (0, ovok_error_utils_1.stringValue)(record.validation) }
+                    : {}),
+            }];
+    });
+}
+const samePath = (left, right) => left.join(".") === right.join(".");
+/** Core's problem `errors[]` (`{ field, code, params }`), worded by the legacy message Core sends for the same path. */
+function readProblemErrors(values, worded) {
+    return values.flatMap((value) => {
+        var _a, _b;
+        const record = (0, ovok_error_utils_1.asRecord)(value);
+        const code = (0, ovok_error_utils_1.stringValue)(record === null || record === void 0 ? void 0 : record.code);
+        if (!record || !code || typeof record.message === "string" || !("field" in record)) {
+            return [];
+        }
+        const path = typeof record.field === "string" ? record.field.split(".").filter(Boolean) : [];
+        const message = (_b = (_a = worded.find((entry) => samePath(entry.path, path))) === null || _a === void 0 ? void 0 : _a.message) !== null && _b !== void 0 ? _b : code;
+        return [{ code, message, path }];
+    });
+}
+function readFieldErrors(payload) {
+    const nested = (0, ovok_error_utils_1.asRecord)(payload === null || payload === void 0 ? void 0 : payload.error);
+    const listed = Array.isArray(nested === null || nested === void 0 ? void 0 : nested.errors)
+        ? nested.errors
+        : Array.isArray(payload === null || payload === void 0 ? void 0 : payload.errors)
+            ? payload.errors
+            : [];
+    const legacy = readEnvelopeErrors(Array.isArray(payload === null || payload === void 0 ? void 0 : payload.message) ? payload.message : []);
+    const problemErrors = readProblemErrors(listed, legacy);
+    const listedErrors = readEnvelopeErrors(listed);
+    // A problem body lists its fields in `errors[]` and keeps the older `message` list beside it; read either.
+    const envelopeErrors = problemErrors.length > 0
+        ? problemErrors
+        : listedErrors.length > 0
+            ? listedErrors
+            : legacy;
+    const outcome = Array.isArray(payload === null || payload === void 0 ? void 0 : payload.issue) ? payload.issue : [];
+    const nestedEnvelopeErrors = outcome.flatMap((value) => {
+        var _a;
+        const issue = (0, ovok_error_utils_1.asRecord)(value);
+        const details = (0, ovok_error_utils_1.asRecord)(issue === null || issue === void 0 ? void 0 : issue.details);
+        const nested = (_a = (0, ovok_error_utils_1.asRecord)((0, ovok_error_utils_1.parseJson)(details === null || details === void 0 ? void 0 : details.text))) !== null && _a !== void 0 ? _a : (0, ovok_error_utils_1.asRecord)((0, ovok_error_utils_1.parseJson)(issue === null || issue === void 0 ? void 0 : issue.diagnostics));
+        return nested ? readFieldErrors(nested) : [];
+    });
+    const outcomeErrors = outcome.flatMap((value) => {
+        var _a;
+        const issue = (0, ovok_error_utils_1.asRecord)(value);
+        const details = (0, ovok_error_utils_1.asRecord)(issue === null || issue === void 0 ? void 0 : issue.details);
+        const message = (_a = (0, ovok_error_utils_1.stringValue)(details === null || details === void 0 ? void 0 : details.text)) !== null && _a !== void 0 ? _a : (0, ovok_error_utils_1.stringValue)(issue === null || issue === void 0 ? void 0 : issue.diagnostics);
+        if ((issue === null || issue === void 0 ? void 0 : issue.severity) !== "error" || !message) {
+            return [];
+        }
+        const expressions = Array.isArray(issue.expression)
+            ? issue.expression
+            : Array.isArray(issue.location)
+                ? issue.location
+                : [];
+        const path = expressions.flatMap((expression) => typeof expression === "string" ? expression.split(".").filter(Boolean) : []);
+        return [{
+                ...((0, ovok_error_utils_1.stringValue)(issue.code) ? { code: (0, ovok_error_utils_1.stringValue)(issue.code) } : {}),
+                message,
+                path,
+            }];
+    });
+    return [...envelopeErrors, ...nestedEnvelopeErrors, ...outcomeErrors];
+}

package/dist/client/errors/ovok-error-utils.d.ts

@@ -1,4 +1,3 @@
-import { ValidationError } from "../../types/ValidationError";
 export declare const OVOK_HTTP_ERROR_EXTENSION_URL = "https://api.ovok.com/fhir/StructureDefinition/http-error-metadata";
 /** `reason` itself when it is an Error, else an Error carrying its string form. */
 export declare const toError: (reason: unknown) => Error;
@@ -8,7 +7,6 @@ export declare const namedError: (name: string, message: string) => Error;
 export declare const withCause: <T extends Error>(error: T, cause: unknown) => T;
 export declare const asRecord: (value: unknown) => Record<string, unknown> | undefined;
 export declare function readMessage(payload: Record<string, unknown> | undefined, error: unknown): string;
-export declare function readFieldErrors(payload: Record<string, unknown> | undefined): ValidationError[];
 export declare function codeValue(value: unknown): string | undefined;
 export declare function codeFromOutcome(value: unknown): string | undefined;
 export declare function statusFromOutcome(value: unknown): number | undefined;

package/dist/client/errors/ovok-error-utils.js

@@ -2,7 +2,6 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.asRecord = exports.withCause = exports.namedError = exports.toError = exports.OVOK_HTTP_ERROR_EXTENSION_URL = void 0;
 exports.readMessage = readMessage;
-exports.readFieldErrors = readFieldErrors;
 exports.codeValue = codeValue;
 exports.codeFromOutcome = codeFromOutcome;
 exports.statusFromOutcome = statusFromOutcome;
@@ -37,66 +36,15 @@ function readMessage(payload, error) {
             return messages.join("; ");
         }
     }
+    const detail = stringValue(payload === null || payload === void 0 ? void 0 : payload.detail);
+    if (detail) {
+        return detail;
+    }
     if (error instanceof Error) {
         return error.message;
     }
     return typeof error === "string" ? error : String(error);
 }
-function readFieldErrors(payload) {
-    const messageErrors = Array.isArray(payload === null || payload === void 0 ? void 0 : payload.message) ? payload.message : [];
-    const nested = (0, exports.asRecord)(payload === null || payload === void 0 ? void 0 : payload.error);
-    const rawErrors = Array.isArray(nested === null || nested === void 0 ? void 0 : nested.errors)
-        ? nested.errors
-        : Array.isArray(payload === null || payload === void 0 ? void 0 : payload.errors)
-            ? payload.errors
-            : messageErrors;
-    const envelopeErrors = rawErrors.flatMap((value) => {
-        const record = (0, exports.asRecord)(value);
-        if (!record || typeof record.message !== "string") {
-            return [];
-        }
-        const path = Array.isArray(record.path)
-            ? record.path.map((segment) => String(segment))
-            : [];
-        return [{
-                ...(stringValue(record.code) ? { code: stringValue(record.code) } : {}),
-                message: record.message,
-                path,
-                ...(stringValue(record.validation)
-                    ? { validation: stringValue(record.validation) }
-                    : {}),
-            }];
-    });
-    const outcome = Array.isArray(payload === null || payload === void 0 ? void 0 : payload.issue) ? payload.issue : [];
-    const nestedEnvelopeErrors = outcome.flatMap((value) => {
-        var _a;
-        const issue = (0, exports.asRecord)(value);
-        const details = (0, exports.asRecord)(issue === null || issue === void 0 ? void 0 : issue.details);
-        const nested = (_a = (0, exports.asRecord)(parseJson(details === null || details === void 0 ? void 0 : details.text))) !== null && _a !== void 0 ? _a : (0, exports.asRecord)(parseJson(issue === null || issue === void 0 ? void 0 : issue.diagnostics));
-        return nested ? readFieldErrors(nested) : [];
-    });
-    const outcomeErrors = outcome.flatMap((value) => {
-        var _a;
-        const issue = (0, exports.asRecord)(value);
-        const details = (0, exports.asRecord)(issue === null || issue === void 0 ? void 0 : issue.details);
-        const message = (_a = stringValue(details === null || details === void 0 ? void 0 : details.text)) !== null && _a !== void 0 ? _a : stringValue(issue === null || issue === void 0 ? void 0 : issue.diagnostics);
-        if ((issue === null || issue === void 0 ? void 0 : issue.severity) !== "error" || !message) {
-            return [];
-        }
-        const expressions = Array.isArray(issue.expression)
-            ? issue.expression
-            : Array.isArray(issue.location)
-                ? issue.location
-                : [];
-        const path = expressions.flatMap((expression) => typeof expression === "string" ? expression.split(".").filter(Boolean) : []);
-        return [{
-                ...(stringValue(issue.code) ? { code: stringValue(issue.code) } : {}),
-                message,
-                path,
-            }];
-    });
-    return [...envelopeErrors, ...nestedEnvelopeErrors, ...outcomeErrors];
-}
 function codeValue(value) {
     return typeof value === "string" && /^[a-z][a-z0-9_]+$/.test(value)
         ? value

package/dist/client/errors/ovok-error.d.ts

@@ -1,12 +1,18 @@
 import { ValidationError } from "../../types/ValidationError";
-export { asRecord, readFieldErrors, readMessage } from "./ovok-error-utils";
+export { asRecord, readMessage } from "./ovok-error-utils";
+export { readFieldErrors } from "./field-errors";
 export type ParsedOvokError = {
     message: string;
     fieldErrors: ValidationError[];
 };
 export type OvokErrorDetails = ParsedOvokError & {
     status: number | undefined;
+    /** The condition the server named; undefined when the error is known only by its status. */
     code: string | undefined;
+    /** The problem type URI, `https://docs.ovok.com/errors/<code>`, which also names status-only errors. */
+    type?: string;
+    /** Equals the `x-trace-id` response header; quote it when reporting an error. */
+    traceId?: string;
     requestId?: string;
     retryAfterMs?: number;
     missing: string[];
@@ -17,6 +23,8 @@ export declare const readOvokError: (error: unknown) => OvokErrorDetails;
 export declare class OvokApiError extends Error {
     readonly status: number;
     readonly code: string | undefined;
+    readonly type: string | undefined;
+    readonly traceId: string | undefined;
     readonly fieldErrors: ValidationError[];
     readonly missing: string[];
     readonly requestId: string | undefined;

package/dist/client/errors/ovok-error.js

@@ -1,13 +1,16 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.parseOvokError = exports.OvokApiError = exports.readOvokError = exports.readMessage = exports.readFieldErrors = exports.asRecord = void 0;
+exports.parseOvokError = exports.OvokApiError = exports.readOvokError = exports.readFieldErrors = exports.readMessage = exports.asRecord = void 0;
 exports.isOvokApiError = isOvokApiError;
 exports.mapOvokApiError = mapOvokApiError;
+const field_errors_1 = require("./field-errors");
 const ovok_error_utils_1 = require("./ovok-error-utils");
+const problem_code_1 = require("./problem-code");
 var ovok_error_utils_2 = require("./ovok-error-utils");
 Object.defineProperty(exports, "asRecord", { enumerable: true, get: function () { return ovok_error_utils_2.asRecord; } });
-Object.defineProperty(exports, "readFieldErrors", { enumerable: true, get: function () { return ovok_error_utils_2.readFieldErrors; } });
 Object.defineProperty(exports, "readMessage", { enumerable: true, get: function () { return ovok_error_utils_2.readMessage; } });
+var field_errors_2 = require("./field-errors");
+Object.defineProperty(exports, "readFieldErrors", { enumerable: true, get: function () { return field_errors_2.readFieldErrors; } });
 const STATUS_BY_BARE_CODE = {
     INVALID_SETTING_VALUE: 422,
     APP_URL_NOT_ALLOWED: 400,
@@ -31,6 +34,8 @@ const readOvokError = (error) => {
         return {
             status: error.status,
             code: error.code,
+            ...(error.type === undefined ? {} : { type: error.type }),
+            ...(error.traceId === undefined ? {} : { traceId: error.traceId }),
             ...(error.requestId === undefined ? {} : { requestId: error.requestId }),
             ...(error.retryAfterMs === undefined ? {} : { retryAfterMs: error.retryAfterMs }),
             message: error.message,
@@ -56,9 +61,12 @@ const readOvokError = (error) => {
         && !HTTP_REASON_PHRASES.has(bareMessage.toLowerCase())
         ? bareMessage
         : undefined;
-    const code = (_l = (_k = (_j = (_h = (0, ovok_error_utils_1.stringValue)(payload === null || payload === void 0 ? void 0 : payload.code)) !== null && _h !== void 0 ? _h : (0, ovok_error_utils_1.stringValue)(nestedError === null || nestedError === void 0 ? void 0 : nestedError.code)) !== null && _j !== void 0 ? _j : (0, ovok_error_utils_1.codeValue)(payload === null || payload === void 0 ? void 0 : payload.error)) !== null && _k !== void 0 ? _k : bareCode) !== null && _l !== void 0 ? _l : (0, ovok_error_utils_1.codeFromOutcome)((_m = payload === null || payload === void 0 ? void 0 : payload.outcome) !== null && _m !== void 0 ? _m : payload);
+    const writtenCode = (_h = (0, ovok_error_utils_1.stringValue)(nestedError === null || nestedError === void 0 ? void 0 : nestedError.code)) !== null && _h !== void 0 ? _h : (0, ovok_error_utils_1.codeValue)(payload === null || payload === void 0 ? void 0 : payload.error);
+    const code = (_l = (_k = (_j = (0, problem_code_1.conditionCode)((0, problem_code_1.ownCode)(payload === null || payload === void 0 ? void 0 : payload.code), writtenCode)) !== null && _j !== void 0 ? _j : writtenCode) !== null && _k !== void 0 ? _k : bareCode) !== null && _l !== void 0 ? _l : (0, ovok_error_utils_1.codeFromOutcome)((_m = payload === null || payload === void 0 ? void 0 : payload.outcome) !== null && _m !== void 0 ? _m : payload);
+    const type = (0, problem_code_1.problemTypeOf)(payload === null || payload === void 0 ? void 0 : payload.type);
+    const traceId = (0, ovok_error_utils_1.stringValue)(payload === null || payload === void 0 ? void 0 : payload.traceId);
     const status = (_v = (_t = (_s = (_r = (_q = (_p = (_o = metadata.status) !== null && _o !== void 0 ? _o : (0, ovok_error_utils_1.numberValue)(root === null || root === void 0 ? void 0 : root.status)) !== null && _p !== void 0 ? _p : (0, ovok_error_utils_1.numberValue)(root === null || root === void 0 ? void 0 : root.statusCode)) !== null && _q !== void 0 ? _q : (0, ovok_error_utils_1.numberValue)(response === null || response === void 0 ? void 0 : response.status)) !== null && _r !== void 0 ? _r : (0, ovok_error_utils_1.numberValue)(payload === null || payload === void 0 ? void 0 : payload.status)) !== null && _s !== void 0 ? _s : (0, ovok_error_utils_1.numberValue)(payload === null || payload === void 0 ? void 0 : payload.statusCode)) !== null && _t !== void 0 ? _t : (0, ovok_error_utils_1.statusFromOutcome)((_u = payload === null || payload === void 0 ? void 0 : payload.outcome) !== null && _u !== void 0 ? _u : payload)) !== null && _v !== void 0 ? _v : (code ? STATUS_BY_BARE_CODE[code] : undefined);
-    const fieldErrors = (0, ovok_error_utils_1.readFieldErrors)(payload);
+    const fieldErrors = (0, field_errors_1.readFieldErrors)(payload);
     const missing = Array.isArray(payload === null || payload === void 0 ? void 0 : payload.missing)
         ? payload.missing.filter((entry) => typeof entry === "string")
         : [];
@@ -68,6 +76,8 @@ const readOvokError = (error) => {
     return {
         status,
         code,
+        ...(type === undefined ? {} : { type }),
+        ...(traceId === undefined ? {} : { traceId }),
         ...(requestId === undefined ? {} : { requestId }),
         ...(retryAfterMs === undefined ? {} : { retryAfterMs }),
         message: (0, ovok_error_utils_1.readMessage)(payload, error),
@@ -84,6 +94,8 @@ class OvokApiError extends Error {
         this.name = "OvokApiError";
         this.status = (_a = details.status) !== null && _a !== void 0 ? _a : 0;
         this.code = details.code;
+        this.type = details.type;
+        this.traceId = details.traceId;
         this.fieldErrors = details.fieldErrors;
         this.missing = details.missing;
         this.requestId = details.requestId;

package/dist/client/errors/problem-code.d.ts

@@ -0,0 +1,4 @@
+export declare const ownCode: (value: unknown) => string | undefined;
+/** Core sends a throw site's code upper-cased in `code` and as written in `error`: keep the written form. */
+export declare const conditionCode: (problemCode: string | undefined, writtenCode: string | undefined) => string | undefined;
+export declare const problemTypeOf: (value: unknown) => string | undefined;

package/dist/client/errors/problem-code.js

@@ -0,0 +1,45 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.problemTypeOf = exports.conditionCode = exports.ownCode = void 0;
+const ovok_error_utils_1 = require("./ovok-error-utils");
+const PROBLEM_TYPE_PREFIX = "https://docs.ovok.com/errors/";
+// The codes Core gives an error by its status alone: they name no condition, so `code` stays undefined for them.
+const STATUS_ONLY_CODES = new Set([
+    "MALFORMED_REQUEST",
+    "UNAUTHENTICATED",
+    "FORBIDDEN",
+    "NOT_FOUND",
+    "METHOD_NOT_ALLOWED",
+    "NOT_ACCEPTABLE",
+    "REQUEST_TIMEOUT",
+    "CONFLICT",
+    "GONE",
+    "PRECONDITION_FAILED",
+    "CONTENT_TOO_LARGE",
+    "UNSUPPORTED_MEDIA_TYPE",
+    "VALIDATION_FAILED",
+    "LOCKED",
+    "FAILED_DEPENDENCY",
+    "PRECONDITION_REQUIRED",
+    "TOO_MANY_REQUESTS",
+    "INTERNAL_ERROR",
+    "NOT_IMPLEMENTED",
+    "UPSTREAM_ERROR",
+    "SERVICE_UNAVAILABLE",
+    "UPSTREAM_TIMEOUT",
+    "SERVER_ERROR",
+    "CLIENT_ERROR",
+]);
+const ownCode = (value) => {
+    const code = (0, ovok_error_utils_1.stringValue)(value);
+    return code && !STATUS_ONLY_CODES.has(code) ? code : undefined;
+};
+exports.ownCode = ownCode;
+/** Core sends a throw site's code upper-cased in `code` and as written in `error`: keep the written form. */
+const conditionCode = (problemCode, writtenCode) => problemCode && (writtenCode === null || writtenCode === void 0 ? void 0 : writtenCode.toUpperCase()) === problemCode.toUpperCase() ? writtenCode : problemCode;
+exports.conditionCode = conditionCode;
+const problemTypeOf = (value) => {
+    const type = (0, ovok_error_utils_1.stringValue)(value);
+    return (type === null || type === void 0 ? void 0 : type.startsWith(PROBLEM_TYPE_PREFIX)) ? type : undefined;
+};
+exports.problemTypeOf = problemTypeOf;

package/dist/conformance/capability-requirements.js

@@ -48,7 +48,7 @@ exports.OVOK_CORE_REQUIREMENTS = {
     description: "The FHIR surface a server must provide for the @ovok/core client library's own methods to function.",
     software: {
         name: "@ovok/core",
-        version: "0.4.44",
+        version: "0.4.45",
     },
     fhirVersion: "4.0.1",
     format: ["json"],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ovok/core",
-  "version": "0.4.44",
+  "version": "0.4.45",
   "private": false,
   "main": "dist/index.js",
   "types": "dist/index.d.ts",