@iyulab/enterprise 0.13.0 → 0.14.0

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # Changelog
 
+## [0.14.0] - 2026-09-20
+
+### Fixed
+
+- **A failed `api*` write told the user nothing.** `notify.error` was wired into the OData writes
+  only, so a custom REST write that came back 4xx threw an `ApiError` and left the screen exactly as
+  it was — indistinguishable from nothing having happened, even when the server had returned a
+  precise reason. The four `api*` writes now notify on failure and rethrow, on the same terms as
+  their OData siblings (401 excluded, since `onUnauthorized` already covers it). Reads are unchanged
+  and still silent on both sides.
+
+### Added
+
+- **`apiPostQuiet`, `apiPutQuiet`, `apiPatchQuiet`, `apiDeleteQuiet`.** The opt-out for the above,
+  matching the existing `odata*Quiet` naming: use them when one user action issues several requests,
+  or when the calling code already reports failures itself and would otherwise show two messages.
+
+### Documentation
+
+- **The README said which hooks exist but not where they apply**, which read as "wire `notify` and
+  failures become visible". It now carries a per-method table and states the axis: writes notify,
+  reads do not, `*Quiet` opts out, 401 never notifies, and `api*` has no success message because the
+  library cannot invent wording for an arbitrary endpoint.
+
 ## 0.13.0
 
 ### Changed

package/README.md

@@ -121,10 +121,29 @@ await svc.apiPost<Order>('orders/7/attachments', form)
 | `baseUrl` | 모든 요청의 오리진 (필수) |
 | `odataPrefix` / `apiPrefix` | 엔드포인트 prefix (기본 `$data` / `api`) |
 | `onUnauthorized(status)` | 401 시 호출 — 리다이렉트/재진입 가드는 앱이 처리 |
-| `notify.success/error` | 토스트 훅 (생략 시 토스트 없음 — 순수) |
+| `notify.success/error` | 토스트 훅 (생략 시 토스트 없음 — 순수). **메서드마다 걸리는 방식이 다르다 — 바로 아래 표 참조** |
 | `messages` | 사용자 대면 문구 (기본 영어, 지정 키만 대체) |
 | `formatError(info)` | 에러 메시지 포매팅 오버라이드 (앱별 정책) — `info` 는 `status`/`statusText`/`rawMessage`/`details`(검증된 `error.details`)/`body` 를 받는다 |
 
+#### `notify` 가 걸리는 자리 — 축은 «쓰기 ↔ 읽기» 다
+
+| 메서드 | 실패 시 `error` | 성공 시 `success` |
+|---|---|---|
+| `odataPost` · `odataPatch` · `odataDelete` | ✅ (401 제외) | ✅ `saved`·`updated`·`deleted` |
+| `apiPost` · `apiPut` · `apiPatch` · `apiDelete` | ✅ (401 제외) | ❌ |
+| `*Quiet` 전부 (`odataPostQuiet` … `apiDeleteQuiet`) | ❌ | ❌ |
+| `odataGet` · `odataGetById` · `odataCount` · `apiGet` · `fetchRaw` | ❌ | ❌ |
+
+- **조회는 통지하지 않는다.** 빈 화면 자체가 신호이고, 목록을 열 때마다 토스트가 뜨면 읽을 수 없다.
+- **쓰기는 통지한다.** 결과가 화면에 안 보일 수 있기 때문이다 — 서버가 409 와 사유를 돌려줘도,
+  통지가 없으면 아무 일도 일어나지 않은 화면과 구별되지 않는다.
+- **401 은 통지하지 않는다** — `onUnauthorized` 가 이미 안내하므로 겹친다.
+- **`api*` 에는 성공 토스트가 없다.** 임의의 RPC(상태 전이·발행·업로드)를 태우는 경로라
+  «저장되었습니다» 같은 문구를 라이브러리가 지어낼 수 없다. 실패 메시지는 서버가 주므로 어느
+  엔드포인트에서나 뜻이 통하지만, 성공 문구는 그렇지 않다 — 필요하면 호출한 쪽이 띄운다.
+- **이미 자기 래퍼로 통지하고 있다면 `*Quiet` 로 바꾼다.** 이중 토스트를 막는 탈출구이고,
+  `odata*Quiet` 와 같은 관용구다(한 사용자 액션이 여러 요청을 낼 때도 같은 것을 쓴다).
+
 > 도메인 액션(상태 전이 등)·엔티티 목록·권한 코드는 라이브러리에 넣지 말고 앱 adapter 에 둔다.
 
 #### 실패 응답 — `ApiError`

package/dist/data/ODataService.d.ts

@@ -94,16 +94,28 @@ export interface ODataService {
     odataDelete(entity: string, id: string): Promise<void>;
     /** custom REST GET — 204 등 빈 바디를 안전 파싱. */
     apiGet<T>(path: string): Promise<T>;
-    /** custom REST POST. `body`가 `FormData` 인스턴스면 그대로(직렬화 없이) 멀티파트로
-     *  전송된다 — `@iyulab/http-client`가 Content-Type을 브라우저 자동 설정에 맡기고
-     *  JSON 직렬화 분기를 타지 않는다. `apiPut`/`apiPatch`도 동일하게 동작한다. */
+    /** custom REST POST — 실패 시 `error` 토스트 후 rethrow(401 제외). `body`가 `FormData`
+     *  인스턴스면 그대로(직렬화 없이) 멀티파트로 전송된다 — `@iyulab/http-client`가
+     *  Content-Type을 브라우저 자동 설정에 맡기고 JSON 직렬화 분기를 타지 않는다.
+     *  `apiPut`/`apiPatch`도 동일하게 동작한다. */
     apiPost<T>(path: string, body?: unknown): Promise<T>;
-    /** custom REST PUT(리소스 전체 교체/생성). `body`의 `FormData` 처리는 `apiPost` 참조. */
+    /** custom REST POST — 토스트 없이 결과만(`odataPostQuiet`와 같은 이유: 한 사용자 액션이
+     *  여러 요청을 내거나, 소비자가 자기 래퍼로 이미 통지할 때). */
+    apiPostQuiet<T>(path: string, body?: unknown): Promise<T>;
+    /** custom REST PUT(리소스 전체 교체/생성) — 실패 시 `error` 토스트 후 rethrow(401 제외).
+     *  `body`의 `FormData` 처리는 `apiPost` 참조. */
     apiPut<T>(path: string, body?: unknown): Promise<T>;
-    /** custom REST PATCH. `body`의 `FormData` 처리는 `apiPost` 참조. */
+    /** custom REST PUT — 토스트 없이 결과만. */
+    apiPutQuiet<T>(path: string, body?: unknown): Promise<T>;
+    /** custom REST PATCH — 실패 시 `error` 토스트 후 rethrow(401 제외). `body`의 `FormData`
+     *  처리는 `apiPost` 참조. */
     apiPatch<T>(path: string, body?: unknown): Promise<T>;
-    /** custom REST DELETE — 대부분 204 No Content. */
+    /** custom REST PATCH — 토스트 없이 결과만. */
+    apiPatchQuiet<T>(path: string, body?: unknown): Promise<T>;
+    /** custom REST DELETE — 실패 시 `error` 토스트 후 rethrow(401 제외). 대부분 204 No Content. */
     apiDelete<T = void>(path: string): Promise<T>;
+    /** custom REST DELETE — 토스트 없이 결과만. */
+    apiDeleteQuiet<T = void>(path: string): Promise<T>;
     /** URL 을 직접 조립한 커스텀 조회(csv-export 등)를 위해 raw 응답을 반환. */
     fetchRaw(url: string): Promise<HttpResponse>;
     /**

package/dist/index.js

@@ -774,44 +774,58 @@ function createODataService(config) {
 		await throwIfError(res);
 		return (await res.json())["@odata.count"] ?? 0;
 	}
+	/**
+	* 쓰기 실패를 사용자에게 알린 뒤 그대로 다시 던진다.
+	*
+	* 🔴**이 서비스의 통지 축은 «쓰기 ↔ 읽기» 이지 «odata ↔ api» 가 아니다.** 조회
+	* (`odataGet`·`odataGetById`·`odataCount`·`apiGet`·`fetchRaw`)는 어느 쪽도 통지하지
+	* 않는다 — 화면이 비어 있는 것 자체가 신호이고, 목록 조회마다 토스트를 띄우면 읽을 수
+	* 없다. 쓰기는 **결과가 화면에 안 보일 수 있으므로** 통지한다: 서버가 409 와 사유를
+	* 돌려줘도 아무 일도 일어나지 않은 화면과 구별되지 않는다.
+	*
+	* ⚠**401 은 제외한다** — `onUnauthorized` 가 이미 안내하므로 토스트가 겹친다.
+	*
+	* ⚠성공 토스트는 **`odata*` 쓰기에만** 있다. `api*` 는 임의의 RPC(상태 전이·발행·업로드)를
+	* 태우는 경로라 «저장되었습니다» 같은 문구를 우리가 지어낼 수 없다 — 실패 메시지는 서버가
+	* 주므로 어느 엔드포인트에서나 뜻이 통하지만, 성공 문구는 그렇지 않다.
+	*/
+	async function notifyingWrite(run) {
+		try {
+			return await run();
+		} catch (e) {
+			if (!(e instanceof ApiError && e.status === 401)) notifyError?.(e instanceof Error ? e.message : messages.requestFailed);
+			throw e;
+		}
+	}
 	async function odataPostQuiet(entity, body) {
 		const res = await client.post(odataUrl(entity), normalizeBody(body));
 		await throwIfError(res);
 		return res.json();
 	}
 	async function odataPost(entity, body) {
-		try {
+		return notifyingWrite(async () => {
 			const result = await odataPostQuiet(entity, body);
 			notifySuccess?.(messages.saved);
 			return result;
-		} catch (e) {
-			if (!(e instanceof ApiError && e.status === 401)) notifyError?.(e instanceof Error ? e.message : messages.requestFailed);
-			throw e;
-		}
+		});
 	}
 	async function odataPatchQuiet(entity, id, body) {
 		await throwIfError(await client.patch(`${odataUrl(entity)}(${id})`, normalizeBody(body)));
 	}
 	async function odataPatch(entity, id, body) {
-		try {
+		return notifyingWrite(async () => {
 			await odataPatchQuiet(entity, id, body);
 			notifySuccess?.(messages.updated);
-		} catch (e) {
-			if (!(e instanceof ApiError && e.status === 401)) notifyError?.(e instanceof Error ? e.message : messages.requestFailed);
-			throw e;
-		}
+		});
 	}
 	async function odataDeleteQuiet(entity, id) {
 		await throwIfError(await client.delete(`${odataUrl(entity)}(${id})`));
 	}
 	async function odataDelete(entity, id) {
-		try {
+		return notifyingWrite(async () => {
 			await odataDeleteQuiet(entity, id);
 			notifySuccess?.(messages.deleted);
-		} catch (e) {
-			if (!(e instanceof ApiError && e.status === 401)) notifyError?.(e instanceof Error ? e.message : messages.requestFailed);
-			throw e;
-		}
+		});
 	}
 	async function apiGet(path) {
 		const [p, ...q] = path.split("?");
@@ -820,26 +834,38 @@ function createODataService(config) {
 		await throwIfError(res);
 		return parseJsonBody(res);
 	}
-	async function apiPost(path, body) {
+	async function apiPostQuiet(path, body) {
 		const res = await client.post(apiUrl(path), body ?? {});
 		await throwIfError(res);
 		return parseJsonBody(res);
 	}
-	async function apiPut(path, body) {
+	async function apiPost(path, body) {
+		return notifyingWrite(() => apiPostQuiet(path, body));
+	}
+	async function apiPutQuiet(path, body) {
 		const res = await client.put(apiUrl(path), body ?? {});
 		await throwIfError(res);
 		return parseJsonBody(res);
 	}
-	async function apiPatch(path, body) {
+	async function apiPut(path, body) {
+		return notifyingWrite(() => apiPutQuiet(path, body));
+	}
+	async function apiPatchQuiet(path, body) {
 		const res = await client.patch(apiUrl(path), body ?? {});
 		await throwIfError(res);
 		return parseJsonBody(res);
 	}
-	async function apiDelete(path) {
+	async function apiPatch(path, body) {
+		return notifyingWrite(() => apiPatchQuiet(path, body));
+	}
+	async function apiDeleteQuiet(path) {
 		const res = await client.delete(apiUrl(path));
 		await throwIfError(res);
 		return parseJsonBody(res);
 	}
+	async function apiDelete(path) {
+		return notifyingWrite(() => apiDeleteQuiet(path));
+	}
 	async function fetchRaw(url) {
 		const res = await client.get(url);
 		await throwIfError(res);
@@ -859,9 +885,13 @@ function createODataService(config) {
 		odataDelete,
 		apiGet,
 		apiPost,
+		apiPostQuiet,
 		apiPut,
+		apiPutQuiet,
 		apiPatch,
+		apiPatchQuiet,
 		apiDelete,
+		apiDeleteQuiet,
 		fetchRaw,
 		sourceDefaults: {
 			baseUrl,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@iyulab/enterprise",
-  "version": "0.13.0",
+  "version": "0.14.0",
   "description": "Enterprise utilities and components for iyulab framework",
   "keywords": [
     "enterprise",
@@ -61,7 +61,7 @@
     "typescript": "^6.0.2",
     "vite": "^8.1.4",
     "vite-plugin-dts": "^5.0.3",
-    "vitest": "^4.1.10"
+    "vitest": "^5.0.0"
   },
   "peerDependencies": {
     "react": ">=18",