@iyulab/enterprise 0.11.1 → 0.12.0

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # Changelog
 
+## 0.12.0
+
+### Added
+
+- **`ApiError.details`** — OData v4 error envelopes carry per-field validation
+  errors in `error.details`, and `ODataService` already parsed that envelope to
+  build `ApiError.message`, but discarded the rest of the same parse. `ApiError`
+  now also carries `details` (`ApiErrorDetail[] | undefined`), so a caller can
+  bind server-side validation failures to the fields that produced them instead
+  of showing one flattened string. Backward compatible: callers that never read
+  `.details` are unaffected.
+  - Per the OData JSON Format v4.0 spec each detail entry MUST have `code` and
+    `message` and MAY have `target`, so `target` is optional on `ApiErrorDetail`
+    and entries that lack a string `code`/`message` are dropped; when nothing
+    usable remains `details` is `undefined` rather than an empty array.
+- **`formatError(info)` now receives `details`** — the callback that shapes the
+  user-facing message previously got only `rawMessage` and the raw `body`, so an
+  app wanting to summarize per-field failures had to re-dig and re-validate the
+  same `error.details` the service had just parsed. `info` now carries the
+  validated array alongside the derived `rawMessage` it already had. Purely
+  additive to a callback input: existing implementations ignore the new field.
+
 ## 0.11.1
 
 ### Fixed

package/README.md

@@ -18,7 +18,7 @@ npm install @iyulab/enterprise
 | `FormRow` | React | 2컬럼 그리드 폼 행(`full`로 1컬럼) |
 | `ApiConfig` | class | baseUrl/OData·API prefix·dev 판별 중앙 설정 |
 | `createODataService` | factory | OData v4 + custom REST CRUD 서비스(401·토스트·에러파싱) |
-| `ApiError` | class | HTTP status 를 실은 API 호출 실패 에러 |
+| `ApiError` | class | HTTP status + OData `error.details`(필드별 검증 상세)를 실은 API 호출 실패 에러 |
 | `createAuthClient` | factory | 쿠키 세션 인증(fetchMe/login/logout) — 제네릭 user/자격증명 |
 | `createPermissionStore` · `hasPermission` 외 | store | 권한 스냅샷 store + 판정 free 함수 |
 | `CurrencyHelper` | class | 통화 포맷(`formatKRW` 등) |
@@ -121,10 +121,34 @@ await svc.apiPost<Order>('orders/7/attachments', form)
 | `onUnauthorized(status)` | 401 시 호출 — 리다이렉트/재진입 가드는 앱이 처리 |
 | `notify.success/error` | 토스트 훅 (생략 시 토스트 없음 — 순수) |
 | `messages` | 사용자 대면 문구 (기본 영어, 지정 키만 대체) |
-| `formatError(info)` | 에러 메시지 포매팅 오버라이드 (앱별 정책) |
+| `formatError(info)` | 에러 메시지 포매팅 오버라이드 (앱별 정책) — `info` 는 `status`/`statusText`/`rawMessage`/`details`(검증된 `error.details`)/`body` 를 받는다 |
 
 > 도메인 액션(상태 전이 등)·엔티티 목록·권한 코드는 라이브러리에 넣지 말고 앱 adapter 에 둔다.
 
+#### 실패 응답 — `ApiError`
+
+모든 메서드는 실패 시 `ApiError`(`Error` 상속)를 던진다. `status` 로 상태별 분기하고,
+서버가 OData v4 오류 봉투에 필드별 검증 상세(`error.details`)를 실어 보내면 `details` 로
+읽어 폼의 필드별 오류 표시에 바로 연결할 수 있다.
+
+```typescript
+try {
+  await svc.odataPost('Roles', draft)
+} catch (e) {
+  if (e instanceof ApiError && e.details) {
+    // [{ code: 'ValidationError', message: 'The Name field is required.', target: 'Name' }, …]
+    for (const d of e.details) markFieldError(d.target, d.message)
+  }
+}
+```
+
+| 필드 | 설명 |
+|------|------|
+| `message` | 사용자 대면 메시지 (`formatError` → 서버 raw → status 폴백 순으로 결정) |
+| `status` | HTTP status |
+| `details` | `error.details` 항목 배열 — 규격상 `code`/`message` 는 필수, `target`(속성 이름)은 선택. 상세가 없거나 규격 형태가 아니면 `undefined` |
+
+
 ### 인증 + 권한 (`createAuthClient` · 권한 store)
 
 쿠키 세션 인증 흐름과 권한 스냅샷을 승격. 사용자·자격증명 **형태는 앱이 제네릭으로 정의**하고, 권한 코드는 불투명 문자열로만 다룬다. `getPermissions` 를 주면 로그인/세션 조회 성공 시 권한 store 가 자동 갱신된다.

package/dist/data/ODataService.d.ts

@@ -1,11 +1,25 @@
 import { HttpResponse } from '@iyulab/http-client';
+/**
+ * OData v4 오류 봉투의 `error.details` 항목 — 필드별 검증 실패 상세.
+ *
+ * 규격(OData JSON Format v4.0)상 각 항목은 `code`/`message` 를 **반드시** 갖고
+ * `target`(오류가 난 속성 이름)은 **선택**이다 — 필수로 선언하면 target 을 생략한
+ * 서버 응답에서 타입이 거짓말을 하게 된다.
+ */
+export interface ApiErrorDetail {
+    code: string;
+    message: string;
+    target?: string;
+}
 /**
  * API 호출 실패 에러 — HTTP status 를 실어 호출부가 상태별 분기(예: 404 도메인 문구)를 할 수 있게 한다.
  * `Error` 를 상속하므로 기존 `e instanceof Error`/`e.message` 소비처는 그대로 동작한다.
  */
 export declare class ApiError extends Error {
     readonly status: number;
-    constructor(message: string, status: number);
+    /** OData v4 오류 봉투의 `error.details`(필드별 검증 상세) — 서버 응답에 없거나 파싱 실패면 undefined. */
+    readonly details?: ApiErrorDetail[];
+    constructor(message: string, status: number, details?: ApiErrorDetail[]);
 }
 /** 서비스가 토스트/에러에 쓰는 사용자 대면 문구. 기본값은 영어 — 앱이 로케일별로 오버라이드한다. */
 export interface ODataServiceMessages {
@@ -49,6 +63,8 @@ export interface ODataServiceConfig {
         status: number;
         statusText: string;
         rawMessage?: string;
+        /** OData v4 `error.details` — 검증을 마친 항목만 실린다(`ApiError.details` 와 같은 값). */
+        details?: ApiErrorDetail[];
         body?: unknown;
     }) => string | undefined;
 }

package/dist/index.js

@@ -613,14 +613,31 @@ var ApiConfig = class {
 * const rows = await svc.odataGet<BankAccount>('BankAccounts', { $top: '20' })
 */
 /**
+* `error.details` 를 검증해 추출한다 — 규격이 요구하는 형태(`code`/`message` 둘 다 문자열)를
+* 갖춘 항목만 남긴다. 이 파일이 `error.message` 에 이미 적용하는 규칙(`typeof === "string"` 을
+* 확인한 뒤 사용)과 같은 이유다: 검증 없이 캐스팅하면 타입만 맞고 런타임에 호출부가 깨진다.
+* 쓸 수 있는 항목이 하나도 없으면 undefined 로 정규화한다 — 빈 배열을 주면 호출부의
+* `if (e.details)` 가 참이 되어 "상세가 있다"고 오해한다.
+*/
+function extractErrorDetails(raw) {
+	if (!Array.isArray(raw)) return void 0;
+	const details = raw.filter((d) => {
+		if (typeof d !== "object" || d === null) return false;
+		const rec = d;
+		return typeof rec.code === "string" && typeof rec.message === "string";
+	});
+	return details.length > 0 ? details : void 0;
+}
+/**
 * API 호출 실패 에러 — HTTP status 를 실어 호출부가 상태별 분기(예: 404 도메인 문구)를 할 수 있게 한다.
 * `Error` 를 상속하므로 기존 `e instanceof Error`/`e.message` 소비처는 그대로 동작한다.
 */
 var ApiError = class extends Error {
-	constructor(message, status) {
+	constructor(message, status, details) {
 		super(message);
 		this.name = "ApiError";
 		this.status = status;
+		this.details = details;
 	}
 };
 var DEFAULT_MESSAGES = {
@@ -674,27 +691,39 @@ function createODataService(config) {
 		const clean = path.startsWith("/") ? path.slice(1) : path;
 		return `${baseUrl}/${apiPrefix}/${clean}`;
 	};
-	/** OData 응답에서 사용자 친화적 에러 메시지 추출. */
-	async function extractErrorMsg(res) {
+	/** OData 응답에서 사용자 친화적 에러 메시지 + 구조화된 필드별 상세를 추출. */
+	async function extractErrorInfo(res) {
 		let body;
 		try {
 			body = await res.json();
 		} catch {
 			body = void 0;
 		}
-		const rawVal = (body?.error)?.message ?? body?.message ?? body?.Message;
+		const errorObj = body?.error;
+		const rawVal = errorObj?.message ?? body?.message ?? body?.Message;
 		const rawMessage = typeof rawVal === "string" ? rawVal : void 0;
+		const details = extractErrorDetails(errorObj?.details);
 		if (config.formatError) {
 			const m = config.formatError({
 				status: res.status,
 				statusText: res.statusText,
 				rawMessage,
+				details,
 				body
 			});
-			if (m) return m;
+			if (m) return {
+				message: m,
+				details
+			};
 		}
-		if (rawMessage && rawMessage.length <= 200) return rawMessage;
-		return messages.http[res.status] ?? `${messages.requestFailed} (${res.status})`;
+		if (rawMessage && rawMessage.length <= 200) return {
+			message: rawMessage,
+			details
+		};
+		return {
+			message: messages.http[res.status] ?? `${messages.requestFailed} (${res.status})`,
+			details
+		};
 	}
 	/** 에러 확인 후 throw. 401 은 onUnauthorized 통지 후 세션 만료 에러로 단락. */
 	async function throwIfError(res) {
@@ -703,7 +732,8 @@ function createODataService(config) {
 			config.onUnauthorized?.(401);
 			throw new ApiError(messages.sessionExpired, 401);
 		}
-		throw new ApiError(await extractErrorMsg(res), res.status);
+		const { message, details } = await extractErrorInfo(res);
+		throw new ApiError(message, res.status, details);
 	}
 	async function odataGet(entity, params) {
 		const u = new URL(odataUrl(entity));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@iyulab/enterprise",
-  "version": "0.11.1",
+  "version": "0.12.0",
   "description": "Enterprise utilities and components for iyulab framework",
   "keywords": [
     "enterprise",