@iyulab/enterprise 0.3.0 → 0.4.0

package/README.md

@@ -17,6 +17,10 @@ npm install @iyulab/enterprise
 | `FormSection` | React | 제목 + 세로 스택 폼 섹션 |
 | `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 호출 실패 에러 |
+| `createAuthClient` | factory | 쿠키 세션 인증(fetchMe/login/logout) — 제네릭 user/자격증명 |
+| `createPermissionStore` · `hasPermission` 외 | store | 권한 스냅샷 store + 판정 free 함수 |
 | `CurrencyHelper` | class | 통화 포맷(`formatKRW` 등) |
 | `DateHelper` | class | 날짜 포맷/파싱 |
 | `ProgressHelper` | class | 진행률 계산 |
@@ -62,6 +66,71 @@ ApiConfig.getUrlWithParams('report', { year: 2026, active: true })
 ApiConfig.isDevelopment                   // 환경 판별
 ```
 
+### OData 서비스 (`createODataService`)
+
+OData v4 + custom REST CRUD 를 한 번에 구성한다. 401 세션 처리·에러 메시지 추출·성공 토스트·204 빈 바디 안전 파싱이 내장돼 있고, **도메인/로케일 요소는 전부 주입**으로 앱 adapter 에 남긴다.
+
+```typescript
+import { createODataService } from '@iyulab/enterprise'
+import { app } from '@iyulab/modern-app'
+
+// 앱 adapter (예: src/lib/odata.ts) — 라이브러리는 이 배선만 받는다.
+export const svc = createODataService({
+  baseUrl: window.location.origin,
+  onUnauthorized: () => { window.location.href = '/' },        // 세션 만료 리다이렉트는 앱이 결정
+  notify: { success: (m) => app.success(m), error: (m) => app.error(m) },
+  messages: {                                                   // 기본은 영어 — 로케일 오버라이드
+    saved: '저장되었습니다', updated: '수정되었습니다', deleted: '삭제되었습니다',
+    sessionExpired: '세션이 만료되었습니다. 다시 로그인하세요.',
+  },
+})
+
+await svc.odataGet<Order>('Orders', { $top: '20' })   // value 배열 언랩
+await svc.odataPost<Order>('Orders', { name: 'A', note: '' })  // '' → null 정규화 + 성공 토스트
+await svc.apiDelete('orders/7')                        // 204 안전
+svc.odataUrl('Orders')                                 // flex-table useODataSource 엔드포인트
+svc.sourceDefaults                                     // { baseUrl, onUnauthorized } 주입용
+```
+
+주입 항목:
+
+| config | 용도 |
+|--------|------|
+| `baseUrl` | 모든 요청의 오리진 (필수) |
+| `odataPrefix` / `apiPrefix` | 엔드포인트 prefix (기본 `$data` / `api`) |
+| `onUnauthorized(status)` | 401 시 호출 — 리다이렉트/재진입 가드는 앱이 처리 |
+| `notify.success/error` | 토스트 훅 (생략 시 토스트 없음 — 순수) |
+| `messages` | 사용자 대면 문구 (기본 영어, 지정 키만 대체) |
+| `formatError(info)` | 에러 메시지 포매팅 오버라이드 (앱별 정책) |
+
+> 도메인 액션(상태 전이 등)·엔티티 목록·권한 코드는 라이브러리에 넣지 말고 앱 adapter 에 둔다.
+
+### 인증 + 권한 (`createAuthClient` · 권한 store)
+
+쿠키 세션 인증 흐름과 권한 스냅샷을 승격. 사용자·자격증명 **형태는 앱이 제네릭으로 정의**하고, 권한 코드는 불투명 문자열로만 다룬다. `getPermissions` 를 주면 로그인/세션 조회 성공 시 권한 store 가 자동 갱신된다.
+
+```typescript
+import { createAuthClient, hasPermission, setPermissions } from '@iyulab/enterprise'
+
+interface User { Id: string; Permissions: string[] }   // 도메인 형태 = 앱 소유
+
+export const auth = createAuthClient<User, { Username: string; Password: string }>({
+  meUrl: '/api/auth/me', loginUrl: '/api/auth/login', logoutUrl: '/api/auth/logout',
+  getPermissions: (u) => u.Permissions,                 // 성공 시 권한 store 자동 set
+  messages: { invalidCredentials: '사용자명 또는 비밀번호가 올바르지 않습니다.' },
+})
+
+// 부팅 게이트
+const user = await auth.fetchMe()   // null → 미인증(로그인 화면)
+
+// 어디서나 권한 판정(부팅 스냅샷)
+if (hasPermission('orders.write')) { /* 저장 버튼 노출 */ }
+```
+
+- `fetchMe()` 는 401/네트워크 오류 시 `null` — 이 신호가 로그인 게이트를 구동한다(라이브러리가 리다이렉트하지 않음).
+- 격리가 필요하면 `createPermissionStore()` 로 별도 store 를 만들어 `permissionStore` 로 주입한다.
+- 도메인 판정(`isPortalUser` 등)·권한 코드 상수는 라이브러리가 아니라 앱 adapter 에 둔다.
+
 ### 도메인 헬퍼
 
 ```typescript

package/dist/auth/AuthClient.d.ts

@@ -0,0 +1,46 @@
+import { PermissionStore } from './permissions';
+export interface AuthClientMessages {
+    /** 401 로그인 실패 */
+    invalidCredentials: string;
+    /** 기타 로그인 실패(non-401) 폴백 */
+    loginFailed: string;
+    /** 네트워크/예외 */
+    networkError: string;
+}
+export interface LoginResult<TUser> {
+    ok: boolean;
+    user?: TUser;
+    message?: string;
+}
+export interface AuthClientConfig<TUser> {
+    /** 현재 세션 조회 URL (GET) */
+    meUrl: string;
+    /** 로그인 URL (POST, 자격증명을 JSON 바디로) */
+    loginUrl: string;
+    /** 로그아웃 URL (POST) */
+    logoutUrl: string;
+    /** 상대 URL 앞에 붙일 오리진(기본 '' = same-origin). */
+    baseUrl?: string;
+    /** fetch credentials 모드(기본 'same-origin' — 쿠키 세션). */
+    credentials?: RequestCredentials;
+    /** 사용자 대면 문구(로케일). 기본 영어. */
+    messages?: Partial<AuthClientMessages>;
+    /** 로그인 실패(non-401) 응답 바디에서 서버 메시지 추출. 기본: `body.Message ?? body.message`. */
+    extractLoginError?: (body: unknown) => string | undefined;
+    /**
+     * user 에서 권한 코드 배열을 추출. 지정하면 `fetchMe`/`login` 성공 시 권한 store 를 자동 갱신,
+     * `fetchMe`→null / `logout` 시 자동 clear.
+     */
+    getPermissions?: (user: TUser) => string[];
+    /** 권한 자동 갱신 대상 store(기본: `defaultPermissionStore`). */
+    permissionStore?: PermissionStore;
+}
+export interface AuthClient<TUser, TCredentials> {
+    /** 현재 세션 조회. 미인증/세션 만료 시 `null`. 성공 시 권한 store 자동 갱신(getPermissions 지정 시). */
+    fetchMe(): Promise<TUser | null>;
+    /** 로그인. 성공 시 권한 store 자동 갱신(getPermissions 지정 시). */
+    login(credentials: TCredentials): Promise<LoginResult<TUser>>;
+    /** 로그아웃. 권한 store 자동 clear(getPermissions 지정 시). */
+    logout(): Promise<void>;
+}
+export declare function createAuthClient<TUser, TCredentials = Record<string, unknown>>(config: AuthClientConfig<TUser>): AuthClient<TUser, TCredentials>;

package/dist/auth/permissions.d.ts

@@ -0,0 +1,43 @@
+/**
+ * 권한 스냅샷 store — 부팅 시점의 현재 사용자 권한 코드 집합을 보관하고
+ * `hasPermission`/`hasAny`/`hasAll` 판정을 제공한다. 프레임워크 무관(React·Lit 공통)이며
+ * 권한 코드는 **불투명 문자열**로만 다룬다(도메인 의미는 앱이 소유).
+ *
+ * 부팅 시점 스냅샷 모델 — 권한 변경은 다음 로그인(재-set)까지 반영되지 않는다. 단일 운영자
+ * 모델에 충분하며, 실시간 권한 회수/멀티테넌트가 필요하면 `subscribe` 로 반응형 확장 가능.
+ */
+export interface PermissionStore {
+    /** 현재 권한 집합을 통째로 교체한다(로그인/세션 조회 성공 시). */
+    set(codes: Iterable<string>): void;
+    /** 현재 권한 집합(읽기 전용). */
+    get(): ReadonlySet<string>;
+    /** 단일 권한 코드 보유 여부. */
+    has(code: string): boolean;
+    /** 주어진 코드 중 하나라도 보유. 빈 목록은 `true`(제약 없음). */
+    hasAny(codes: Iterable<string>): boolean;
+    /** 주어진 코드를 모두 보유. 빈 목록은 `true`. */
+    hasAll(codes: Iterable<string>): boolean;
+    /** 권한을 비운다(로그아웃/세션 만료 시). */
+    clear(): void;
+    /** 권한 변경 구독. 해제 함수를 반환한다. */
+    subscribe(listener: (codes: ReadonlySet<string>) => void): () => void;
+}
+/** 독립적인 권한 store 를 생성한다(테스트 격리·다중 컨텍스트에 유리). */
+export declare function createPermissionStore(initial?: Iterable<string>): PermissionStore;
+/**
+ * 기본 싱글톤 권한 store. 앱 전역에서 `hasPermission(code)` 를 어디서나 호출하는
+ * 흔한 패턴을 위해 free 함수로 바인딩해 노출한다. 격리가 필요하면 `createPermissionStore()` 를 쓴다.
+ */
+export declare const defaultPermissionStore: PermissionStore;
+/** 기본 store 의 권한을 교체한다(부팅 시 `setPermissions(user.Permissions)`). */
+export declare const setPermissions: (codes: Iterable<string>) => void;
+/** 기본 store 의 현재 권한 집합. */
+export declare const getPermissions: () => ReadonlySet<string>;
+/** 기본 store 기준 단일 권한 보유 여부. */
+export declare const hasPermission: (code: string) => boolean;
+/** 기본 store 기준 하나라도 보유. */
+export declare const hasAnyPermission: (codes: Iterable<string>) => boolean;
+/** 기본 store 기준 모두 보유. */
+export declare const hasAllPermissions: (codes: Iterable<string>) => boolean;
+/** 기본 store 권한을 비운다. */
+export declare const clearPermissions: () => void;

package/dist/data/ODataService.d.ts

@@ -0,0 +1,99 @@
+import { HttpResponse } from '@iyulab/http-client';
+/**
+ * API 호출 실패 에러 — HTTP status 를 실어 호출부가 상태별 분기(예: 404 도메인 문구)를 할 수 있게 한다.
+ * `Error` 를 상속하므로 기존 `e instanceof Error`/`e.message` 소비처는 그대로 동작한다.
+ */
+export declare class ApiError extends Error {
+    readonly status: number;
+    constructor(message: string, status: number);
+}
+/** 서비스가 토스트/에러에 쓰는 사용자 대면 문구. 기본값은 영어 — 앱이 로케일별로 오버라이드한다. */
+export interface ODataServiceMessages {
+    /** POST 성공 토스트 */
+    saved: string;
+    /** PATCH 성공 토스트 */
+    updated: string;
+    /** DELETE 성공 토스트 */
+    deleted: string;
+    /** 401 세션 만료 시 throw 되는 에러 메시지 */
+    sessionExpired: string;
+    /** status별 매핑이 없을 때의 폴백 */
+    requestFailed: string;
+    /** 서버 raw 메시지가 없거나 너무 길 때 status → 친화 메시지 */
+    http: Record<number, string>;
+}
+export interface ODataServiceConfig {
+    /** 모든 요청의 베이스 URL (예: `window.location.origin`). 슬래시 없이 오리진만. */
+    baseUrl: string;
+    /** OData 엔드포인트 prefix (기본 `$data`) */
+    odataPrefix?: string;
+    /** custom REST 엔드포인트 prefix (기본 `api`) */
+    apiPrefix?: string;
+    /**
+     * 401 응답 시 호출된다(모든 메서드 공통). 세션 만료 리다이렉트는 앱이 결정한다.
+     * 재진입 가드(한 번만 리다이렉트)도 앱 콜백 쪽에서 처리한다 — 라이브러리는 status만 통지.
+     */
+    onUnauthorized?: (status: number) => void;
+    /** 성공/실패 토스트 훅. 생략하면 토스트를 내지 않는다(순수 · 테스트 용이). */
+    notify?: {
+        success?: (message: string) => void;
+        error?: (message: string) => void;
+    };
+    /** 사용자 대면 문구 오버라이드(로케일). 지정한 키만 기본값을 대체한다. */
+    messages?: Partial<ODataServiceMessages>;
+    /**
+     * 에러 메시지 포매팅 오버라이드. 반환값이 있으면 그것을 에러 메시지로 사용한다.
+     * (앱별 정책 — 예: 영문 raw OData 메시지를 로케일 친화 문구로 치환 — 을 여기에 둔다.)
+     */
+    formatError?: (info: {
+        status: number;
+        statusText: string;
+        rawMessage?: string;
+        body?: unknown;
+    }) => string | undefined;
+}
+export interface ODataService {
+    /** 설정된 prefix + baseUrl 로 OData 엔티티 URL 을 만든다(flex-table useODataSource 등에서 사용). */
+    odataUrl(entity: string): string;
+    /** 설정된 prefix + baseUrl 로 REST 엔드포인트 URL 을 만든다. */
+    apiUrl(path: string): string;
+    /** OData GET(목록). `value` 배열을 벗겨 반환한다. */
+    odataGet<T>(entity: string, params?: Record<string, string>): Promise<T[]>;
+    /** OData GET(단건, key). */
+    odataGetById<T>(entity: string, id: string): Promise<T>;
+    /** `$count=true&$top=0` — 데이터 없이 총 건수만. */
+    odataCount(entity: string, filter?: Record<string, unknown>): Promise<number>;
+    /** OData POST(생성) — 토스트 없이 결과만(일괄 처리에서 토스트 폭주 방지). */
+    odataPostQuiet<T>(entity: string, body: Partial<T>): Promise<T>;
+    /** OData POST(생성) — 성공 시 `saved` 토스트. */
+    odataPost<T>(entity: string, body: Partial<T>): Promise<T>;
+    /** OData PATCH(수정) — 성공 시 `updated` 토스트. */
+    odataPatch<T>(entity: string, id: string, body: Partial<T>): Promise<void>;
+    /** OData DELETE — 성공 시 `deleted` 토스트. */
+    odataDelete(entity: string, id: string): Promise<void>;
+    /** custom REST GET — 204 등 빈 바디를 안전 파싱. */
+    apiGet<T>(path: string): Promise<T>;
+    /** custom REST POST. */
+    apiPost<T>(path: string, body?: unknown): Promise<T>;
+    /** custom REST PATCH. */
+    apiPatch<T>(path: string, body?: unknown): Promise<T>;
+    /** custom REST DELETE — 대부분 204 No Content. */
+    apiDelete<T = void>(path: string): Promise<T>;
+    /** URL 을 직접 조립한 커스텀 조회(csv-export 등)를 위해 raw 응답을 반환. */
+    fetchRaw(url: string): Promise<HttpResponse>;
+    /**
+     * flex-table `useODataSource` 에 주입할 공용 transport 옵션.
+     * useODataSource 는 자체 fetcher 를 쓰므로 별도로 `onUnauthorized` 를 배선해야 401 처리가 걸린다.
+     */
+    readonly sourceDefaults: {
+        baseUrl: string;
+        onUnauthorized: () => void;
+    };
+    /** `instanceof` 판정을 위해 재노출. (모듈 export `ApiError` 와 동일 클래스) */
+    readonly ApiError: typeof ApiError;
+}
+/**
+ * OData v4 + custom REST 서비스를 생성한다.
+ * 반환된 서비스는 상태를 공유하지 않는 순수 클로저이므로 여러 개를 만들어도 안전하다(테스트 격리에도 유리).
+ */
+export declare function createODataService(config: ODataServiceConfig): ODataService;

package/dist/index.d.ts

@@ -6,3 +6,6 @@ export { FormSection } from './FormSection';
 export { FormRow } from './FormRow';
 export * from './helpers';
 export * from './ApiConfig';
+export * from './data/ODataService';
+export * from './auth/permissions';
+export * from './auth/AuthClient';

package/dist/index.js

@@ -1,4 +1,5 @@
 import { jsx, jsxs } from "react/jsx-runtime";
+import { HttpClient } from "@iyulab/http-client";
 //#region src/FormSection.tsx
 function FormSection({ title, children }) {
 	return /* @__PURE__ */ jsxs("div", {
@@ -511,6 +512,656 @@ var ApiConfig = class {
 		this._apiPrefix = "api";
 		this._isDevelopment = void 0;
 	}
+}, e = [
+	"eq",
+	"ne",
+	"gt",
+	"ge",
+	"lt",
+	"le"
+], t = [
+	"and",
+	"or",
+	"not"
+], n = ["any", "all"], r = [
+	"startswith",
+	"endswith",
+	"contains",
+	"matchespattern"
+], i = [
+	"expand",
+	"levels",
+	"select",
+	"skip",
+	"top",
+	"count",
+	"orderby",
+	"filter"
+], a = /\((.*)\)/, o = /(?!indexof)\((\w+)\)/;
+function g(e, t) {
+	if (t) {
+		let n = e === "", r = o.test(e), i = a.test(e);
+		return n ? t : r ? y(e, t, o) : i ? y(e, t, a) : `${t}/${e}`;
+	}
+	return e;
+}
+function _(e) {
+	return t.indexOf(e) !== -1;
+}
+function v(e) {
+	return `not (${e.join(" and ")})`;
+}
+function y(e, t, n) {
+	return e.replace(n, (e, n) => n.trim() === "" ? `(${t})` : `(${t}/${n.trim()})`);
+}
+function b(e, t, n = []) {
+	return `${e} eq ${w(t, n)}`;
+}
+function x({ key: e, value: t, aliases: n, propPrefix: r }) {
+	let i = [], a = e, o = _(a), s = t.map((e) => O(e, n, r)).filter((e) => e).map((e) => o ? `(${e})` : e);
+	return s.length && (o ? a === "not" ? i.push(v(s)) : i.push(`(${s.join(` ${a} `)})`) : i.push(s.join(` ${a} `))), i;
+}
+function S({ propName: e, value: t }) {
+	let n = [], r = e, i = Object.keys(t).map((e) => k({ [e]: t[e] }));
+	return i.length && (r === "not" ? n.push(v(i)) : n.push(`(${i.join(` ${r} `)})`)), n;
+}
+function C({ key: i, propName: a, value: o, aliases: s }) {
+	let c = [];
+	return "type" in o ? c.push(b(a, o, s)) : Object.keys(o).forEach((l) => {
+		if (o[l] !== void 0) if (e.indexOf(l) !== -1) c.push(`${a} ${l} ${w(o[l], s)}`);
+		else if (t.indexOf(l) !== -1) Array.isArray(o[l]) ? c.push(o[l].map((e) => "(" + O(e, s, a) + ")").join(` ${l} `)) : c.push("(" + O(o[l], s, a) + ")");
+		else if (n.indexOf(l) !== -1) {
+			let e = A({
+				lambdaParameter: i.toLowerCase(),
+				value: o[l],
+				op: l,
+				propName: a,
+				aliases: s
+			});
+			e && c.push(e);
+		} else if (l === "has") c.push(`${a} ${l} ${w(o[l], s)}`);
+		else if (l === "in") {
+			let e = Array.isArray(o[l]) ? o[l] : o[l].value.map((e) => ({
+				type: o[l].type,
+				value: e
+			}));
+			c.push(a + " in (" + e.map((e) => w(e, s)).join(",") + ")");
+		} else if (r.indexOf(l) !== -1) c.push(`${l}(${a},${w(o[l], s)})`);
+		else {
+			let e = /\/not/g.test(a), t = e ? a.replace(/\/not/g, "") : a, n = e ? v([O({ [l]: o[l] }, s, t)]) : O({ [l]: o[l] }, s, t);
+			n && c.push(n);
+		}
+	}), c;
+}
+function w(e, t) {
+	if (typeof e == "string") return `'${D(e)}'`;
+	if (e instanceof Date) return e.toISOString();
+	if (typeof e == "number") return e;
+	if (Array.isArray(e)) return `[${e.map((e) => w(e)).join(",")}]`;
+	if (e === null) return e;
+	if (typeof e == "object") switch (e.type) {
+		case "raw":
+		case "guid": return e.value;
+		case "duration": return `duration'${e.value}'`;
+		case "binary": return `binary'${e.value}'`;
+		case "alias": return Array.isArray(t) && t.push(e), `@${e.name}`;
+		case "json": return escape(JSON.stringify(e.value));
+		case "decimal": return `${e.value}M`;
+		default: return Object.entries(e).filter(([, e]) => e !== void 0).map(([e, n]) => `${e}=${w(n, t)}`).join(",");
+	}
+	return e;
+}
+function T(e, t, n, r) {
+	return `${r}/${n}(${e}: ${e} ${n == "all" ? "ne" : "eq"} '${t}')`;
+}
+function E(e) {
+	return e.replace(/'/g, "''");
+}
+function D(e) {
+	return encodeURIComponent(E(e));
+}
+function O(e = {}, t = [], n = "") {
+	return (Array.isArray(e) ? e : [e]).reduce((e, r) => {
+		if (r) {
+			let i = k(r, t, n);
+			i && e.push(i);
+		}
+		return e;
+	}, []).join(" and ");
+}
+function k(e = {}, t = [], n = "") {
+	let r = "";
+	return typeof e == "string" ? r = e : e && typeof e == "object" && (r = Object.keys(e).reduce((r, i) => {
+		let a = e[i];
+		if (a === void 0) return r;
+		let o = i === "", s = g(i, n);
+		if (o && Array.isArray(a)) return r.concat(a.map((e) => b(s, e)));
+		let c = [
+			"number",
+			"string",
+			"boolean"
+		].indexOf(typeof a) !== -1 || a instanceof Date || a === null, l = Array.isArray(a), u = typeof a == "object";
+		if (c) r.push(b(s, a, t));
+		else if (l) r.push(...x({
+			key: i,
+			value: a,
+			aliases: t,
+			propPrefix: n
+		}));
+		else if (_(s)) r.push(...S({
+			propName: s,
+			value: a
+		}));
+		else if (u) r.push(...C({
+			key: i,
+			propName: s,
+			value: a,
+			aliases: t
+		}));
+		else throw Error(`Unexpected value type: ${a}`);
+		return r;
+	}, []).join(" and ")), r;
+}
+function A({ lambdaParameter: e, value: t, op: n, propName: r, aliases: i }) {
+	let a = "";
+	if (typeof t == "string" || t instanceof String) a = T(e, t, n, r);
+	else if (t) {
+		let o = O(Array.isArray(t) ? t.reduce((e, t) => t.hasOwnProperty("") ? (e.hasOwnProperty("") || (e[""] = []), e[""].push(t[""]), e) : {
+			...e,
+			...t
+		}, {}) : t, i, e);
+		a = `${r}/${n}(${o ? `${e}:${o}` : ""})`;
+	}
+	return a;
+}
+function j(e) {
+	if (typeof e == "number") return e;
+	if (typeof e == "string") return e.indexOf("/") === -1 ? e : e.split("/").reverse().reduce((e, t, n, r) => n === 0 ? `$expand=${t}` : n === r.length - 1 ? `${t}(${e})` : `$expand=${t}(${e})`, "");
+	if (Array.isArray(e)) return `${e.map((e) => j(e)).join(",")}`;
+	if (typeof e == "object") {
+		let t = Object.keys(e);
+		return t.some((e) => i.indexOf(e.toLowerCase()) !== -1) ? t.map((t) => {
+			let n;
+			switch (t) {
+				case "filter":
+					n = O(e[t]);
+					break;
+				case "orderBy":
+					n = F(e[t]);
+					break;
+				case "levels":
+				case "count":
+				case "skip":
+				case "top":
+					n = `${e[t]}`;
+					break;
+				default: n = j(e[t]);
+			}
+			return `$${t.toLowerCase()}=${n}`;
+		}).join(";") : t.map((t) => {
+			let n = j(e[t]);
+			return n ? `${t}(${n})` : t;
+		}).join(",");
+	}
+	return "";
+}
+function M(e) {
+	return (Array.isArray(e) ? e : [e]).reduce((e, t) => {
+		for (let n of Object.keys(t)) switch (n) {
+			case "aggregate": {
+				let r = t[n];
+				r && e.push(`aggregate(${N(r)})`);
+				break;
+			}
+			case "filter": {
+				let r = t[n];
+				if (r) {
+					let t = O(r);
+					t && e.push(`filter(${t})`);
+				}
+				break;
+			}
+			case "groupBy": {
+				let r = t[n];
+				r && e.push(`groupby(${P(r)})`);
+				break;
+			}
+			default: throw Error(`Unsupported transform: ${n}`);
+		}
+		return e;
+	}, []).join("/") || void 0;
+}
+function N(e) {
+	return (Array.isArray(e) ? e : [e]).map((e) => typeof e == "string" ? e : Object.keys(e).map((t) => {
+		let n = e[t];
+		if (!n.with && n.as) return `${t} as ${n.as}`;
+		if (!n.with) throw Error(`'with' property required for '${t}'`);
+		if (!n.as) throw Error(`'as' property required for '${t}'`);
+		return `${t} with ${n.with} as ${n.as}`;
+	})).join(",");
+}
+function P(e) {
+	if (!e.properties) throw Error("'properties' property required for groupBy");
+	let t = `(${e.properties.join(",")})`;
+	return e.transform && (t += `,${M(e.transform)}`), t;
+}
+function F(e, t = "") {
+	return Array.isArray(e) ? e.map((e) => Array.isArray(e) && e.length === 2 && ["asc", "desc"].indexOf(e[1]) !== -1 ? e.join(" ") : e).map((e) => `${t}${String(e)}`).join(",") : typeof e == "object" ? Object.entries(e).map(([e, t]) => F(t, `${e}/`)).map((e) => `${t}${e}`).join(",") : `${t}${String(e)}`;
+}
+function I(e, t) {
+	let n = Object.getOwnPropertyNames(t).filter((e) => t[e] !== void 0 && t[e] !== "").map((e) => `${e}=${t[e]}`);
+	return n.length ? `${e}?${n.join("&")}` : e;
+}
+function L({ select: e, search: t, skiptoken: n, format: r, top: i, skip: a, filter: o, transform: s, orderBy: c, key: l, count: u, expand: d, action: f, func: p } = {}) {
+	let m = "", h = [], g = {};
+	if (l != null && (m += `(${w(l, h)})`), (o || typeof u == "object") && (g.$filter = O(typeof u == "object" ? u : o, h)), s && (g.$apply = M(s)), d && (g.$expand = j(d)), c && (g.$orderby = F(c)), u && (typeof u == "boolean" ? g.$count = !0 : m += "/$count"), typeof i == "number" && (g.$top = i), typeof a == "number" && (g.$skip = a), f && (m += `/${f}`), p) {
+		if (typeof p == "string") m += `/${p}`;
+		else if (typeof p == "object") {
+			let [e] = Object.keys(p), t = w(p[e], h);
+			m += `/${e}`, t !== "" && (m += `(${t})`);
+		}
+	}
+	return h.length > 0 && Object.assign(g, h.reduce((e, t) => Object.assign(e, { [`@${t.name}`]: w(t.value) }), {})), t && (g.$search = encodeURIComponent(t)), I(m, {
+		$select: e,
+		$skiptoken: n,
+		$format: r,
+		...g
+	});
+}
+//#endregion
+//#region src/data/ODataService.ts
+/**
+* OData v4 + custom REST 서비스 팩토리.
+*
+* 여러 소비앱이 글자 단위로 동일하게 재작성하던 OData/REST CRUD 래퍼 —
+* 401 세션 처리, 에러 메시지 추출, 성공 토스트, 빈-바디(204) 안전 파싱 — 를
+* 범용 primitive 로 승격한 것. 도메인/로케일 요소(엔티티 목록, 한국어 문구,
+* 도메인 액션)는 라이브러리에 넣지 않고 주입(config)으로 앱 adapter 에 남긴다.
+*
+* @example
+* const svc = createODataService({
+*   baseUrl: window.location.origin,
+*   onUnauthorized: () => { window.location.href = '/' },
+*   notify: { success: (m) => app.success(m), error: (m) => app.error(m) },
+*   messages: { saved: '저장되었습니다', updated: '수정되었습니다', deleted: '삭제되었습니다' },
+* })
+* const rows = await svc.odataGet<BankAccount>('BankAccounts', { $top: '20' })
+*/
+/**
+* API 호출 실패 에러 — HTTP status 를 실어 호출부가 상태별 분기(예: 404 도메인 문구)를 할 수 있게 한다.
+* `Error` 를 상속하므로 기존 `e instanceof Error`/`e.message` 소비처는 그대로 동작한다.
+*/
+var ApiError = class extends Error {
+	constructor(message, status) {
+		super(message);
+		this.name = "ApiError";
+		this.status = status;
+	}
+};
+var DEFAULT_MESSAGES = {
+	saved: "Saved",
+	updated: "Updated",
+	deleted: "Deleted",
+	sessionExpired: "Your session has expired. Please sign in again.",
+	requestFailed: "Request failed",
+	http: {
+		400: "Bad request",
+		403: "Forbidden",
+		404: "Not found",
+		409: "Conflict",
+		500: "Server error"
+	}
+};
+/** 빈 문자열을 null 로 정규화 — OData 서버가 빈 문자열을 400으로 거부하는 패턴 방지. */
+function normalizeBody(body) {
+	return Object.fromEntries(Object.entries(body).map(([k, v]) => [k, v === "" ? null : v]));
+}
+/**
+* 응답 바디를 안전하게 JSON 파싱 — custom REST 엔드포인트 다수가 성공 시 204 No Content(빈 바디)를
+* 반환한다. `res.json()` 은 빈 바디에서 SyntaxError 를 던지므로 항상 `.text()` 로 먼저 읽고
+* 내용이 있을 때만 파싱한다.
+*/
+async function parseJsonBody(res) {
+	const text = await res.text();
+	return text ? JSON.parse(text) : void 0;
+}
+/**
+* OData v4 + custom REST 서비스를 생성한다.
+* 반환된 서비스는 상태를 공유하지 않는 순수 클로저이므로 여러 개를 만들어도 안전하다(테스트 격리에도 유리).
+*/
+function createODataService(config) {
+	const baseUrl = config.baseUrl;
+	const odataPrefix = config.odataPrefix ?? "$data";
+	const apiPrefix = config.apiPrefix ?? "api";
+	const messages = {
+		...DEFAULT_MESSAGES,
+		...config.messages,
+		http: {
+			...DEFAULT_MESSAGES.http,
+			...config.messages?.http
+		}
+	};
+	const notifySuccess = config.notify?.success;
+	const notifyError = config.notify?.error;
+	const client = new HttpClient({});
+	const odataUrl = (entity) => `${baseUrl}/${odataPrefix}/${entity}`;
+	const apiUrl = (path) => {
+		const clean = path.startsWith("/") ? path.slice(1) : path;
+		return `${baseUrl}/${apiPrefix}/${clean}`;
+	};
+	/** OData 응답에서 사용자 친화적 에러 메시지 추출. */
+	async function extractErrorMsg(res) {
+		let body;
+		try {
+			body = await res.json();
+		} catch {
+			body = void 0;
+		}
+		const rawVal = (body?.error)?.message ?? body?.message ?? body?.Message;
+		const rawMessage = typeof rawVal === "string" ? rawVal : void 0;
+		if (config.formatError) {
+			const m = config.formatError({
+				status: res.status,
+				statusText: res.statusText,
+				rawMessage,
+				body
+			});
+			if (m) return m;
+		}
+		if (rawMessage && rawMessage.length <= 200) return rawMessage;
+		return messages.http[res.status] ?? `${messages.requestFailed} (${res.status})`;
+	}
+	/** 에러 확인 후 throw. 401 은 onUnauthorized 통지 후 세션 만료 에러로 단락. */
+	async function throwIfError(res) {
+		if (res.ok) return;
+		if (res.status === 401) {
+			config.onUnauthorized?.(401);
+			throw new ApiError(messages.sessionExpired, 401);
+		}
+		throw new ApiError(await extractErrorMsg(res), res.status);
+	}
+	async function odataGet(entity, params) {
+		const u = new URL(odataUrl(entity));
+		if (params) for (const [k, v] of Object.entries(params)) u.searchParams.set(k, v);
+		const res = await client.get(u.toString());
+		await throwIfError(res);
+		const json = await res.json();
+		return json.value ?? json;
+	}
+	async function odataGetById(entity, id) {
+		const res = await client.get(`${odataUrl(entity)}(${id})`);
+		await throwIfError(res);
+		return res.json();
+	}
+	async function odataCount(entity, filter) {
+		const qs = L({
+			filter,
+			top: 0,
+			count: true
+		});
+		const res = await client.get(`${odataUrl(entity)}${qs}`);
+		await throwIfError(res);
+		return (await res.json())["@odata.count"] ?? 0;
+	}
+	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 {
+			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 odataPatch(entity, id, body) {
+		const res = await client.patch(`${odataUrl(entity)}(${id})`, normalizeBody(body));
+		if (!res.ok) {
+			if (res.status === 401) {
+				config.onUnauthorized?.(401);
+				throw new ApiError(messages.sessionExpired, 401);
+			}
+			const msg = await extractErrorMsg(res);
+			notifyError?.(msg);
+			throw new ApiError(msg, res.status);
+		}
+		notifySuccess?.(messages.updated);
+	}
+	async function odataDelete(entity, id) {
+		const res = await client.delete(`${odataUrl(entity)}(${id})`);
+		if (!res.ok) {
+			if (res.status === 401) {
+				config.onUnauthorized?.(401);
+				throw new ApiError(messages.sessionExpired, 401);
+			}
+			const msg = await extractErrorMsg(res);
+			notifyError?.(msg);
+			throw new ApiError(msg, res.status);
+		}
+		notifySuccess?.(messages.deleted);
+	}
+	async function apiGet(path) {
+		const [p, ...q] = path.split("?");
+		const url = q.length ? `${apiUrl(p)}?${q.join("?")}` : apiUrl(p);
+		const res = await client.get(url);
+		await throwIfError(res);
+		return parseJsonBody(res);
+	}
+	async function apiPost(path, body) {
+		const res = await client.post(apiUrl(path), body ?? {});
+		await throwIfError(res);
+		return parseJsonBody(res);
+	}
+	async function apiPatch(path, body) {
+		const res = await client.patch(apiUrl(path), body ?? {});
+		await throwIfError(res);
+		return parseJsonBody(res);
+	}
+	async function apiDelete(path) {
+		const res = await client.delete(apiUrl(path));
+		await throwIfError(res);
+		return parseJsonBody(res);
+	}
+	async function fetchRaw(url) {
+		const res = await client.get(url);
+		await throwIfError(res);
+		return res;
+	}
+	return {
+		odataUrl,
+		apiUrl,
+		odataGet,
+		odataGetById,
+		odataCount,
+		odataPostQuiet,
+		odataPost,
+		odataPatch,
+		odataDelete,
+		apiGet,
+		apiPost,
+		apiPatch,
+		apiDelete,
+		fetchRaw,
+		sourceDefaults: {
+			baseUrl,
+			onUnauthorized: () => config.onUnauthorized?.(401)
+		},
+		ApiError
+	};
+}
+//#endregion
+//#region src/auth/permissions.ts
+/** 독립적인 권한 store 를 생성한다(테스트 격리·다중 컨텍스트에 유리). */
+function createPermissionStore(initial) {
+	let codes = new Set(initial ?? []);
+	const listeners = /* @__PURE__ */ new Set();
+	const emit = () => {
+		for (const l of listeners) l(codes);
+	};
+	return {
+		set(next) {
+			codes = new Set(next);
+			emit();
+		},
+		get() {
+			return codes;
+		},
+		has(code) {
+			return codes.has(code);
+		},
+		hasAny(list) {
+			const arr = [...list];
+			if (arr.length === 0) return true;
+			return arr.some((c) => codes.has(c));
+		},
+		hasAll(list) {
+			return [...list].every((c) => codes.has(c));
+		},
+		clear() {
+			if (codes.size === 0) return;
+			codes = /* @__PURE__ */ new Set();
+			emit();
+		},
+		subscribe(listener) {
+			listeners.add(listener);
+			return () => listeners.delete(listener);
+		}
+	};
+}
+/**
+* 기본 싱글톤 권한 store. 앱 전역에서 `hasPermission(code)` 를 어디서나 호출하는
+* 흔한 패턴을 위해 free 함수로 바인딩해 노출한다. 격리가 필요하면 `createPermissionStore()` 를 쓴다.
+*/
+var defaultPermissionStore = createPermissionStore();
+/** 기본 store 의 권한을 교체한다(부팅 시 `setPermissions(user.Permissions)`). */
+var setPermissions = (codes) => defaultPermissionStore.set(codes);
+/** 기본 store 의 현재 권한 집합. */
+var getPermissions = () => defaultPermissionStore.get();
+/** 기본 store 기준 단일 권한 보유 여부. */
+var hasPermission = (code) => defaultPermissionStore.has(code);
+/** 기본 store 기준 하나라도 보유. */
+var hasAnyPermission = (codes) => defaultPermissionStore.hasAny(codes);
+/** 기본 store 기준 모두 보유. */
+var hasAllPermissions = (codes) => defaultPermissionStore.hasAll(codes);
+/** 기본 store 권한을 비운다. */
+var clearPermissions = () => defaultPermissionStore.clear();
+//#endregion
+//#region src/auth/AuthClient.ts
+/**
+* 쿠키 세션 인증 클라이언트 팩토리.
+*
+* 여러 소비앱이 동일하게 재작성하던 `fetchMe`/`login`/`logout` 흐름을 범용 primitive 로 승격.
+* **원시 `fetch`** 를 쓴다(HttpClient 의 401 인터셉터를 의도적으로 우회) — `fetchMe` 가 401 에
+* `null` 을 반환하는 것이 곧 "미인증" 신호이고, 이 신호가 로그인 게이트를 구동하기 때문.
+*
+* 사용자/자격증명 형태는 앱이 제네릭 타입으로 정의한다(라이브러리는 URL 을 호출만).
+* 권한 추출기(`getPermissions`)를 주면 `fetchMe`/`login` 성공 시 자동으로 권한 store 를 갱신한다.
+*
+* @example
+* interface User { Id: string; Permissions: string[] }
+* const auth = createAuthClient<User, { Username: string; Password: string }>({
+*   meUrl: '/api/auth/me', loginUrl: '/api/auth/login', logoutUrl: '/api/auth/logout',
+*   getPermissions: (u) => u.Permissions,   // → 성공 시 defaultPermissionStore 자동 set
+*   messages: { invalidCredentials: '사용자명 또는 비밀번호가 올바르지 않습니다.' },
+* })
+* const user = await auth.fetchMe()          // null → 미인증(로그인 게이트)
+*/
+var DEFAULT_AUTH_MESSAGES = {
+	invalidCredentials: "Invalid username or password.",
+	loginFailed: "Login failed.",
+	networkError: "A network error occurred."
 };
+function pickServerMessage(body) {
+	if (body && typeof body === "object") {
+		const b = body;
+		const m = b.Message ?? b.message;
+		if (typeof m === "string") return m;
+	}
+}
+function createAuthClient(config) {
+	const messages = {
+		...DEFAULT_AUTH_MESSAGES,
+		...config.messages
+	};
+	const credentials = config.credentials ?? "same-origin";
+	const baseUrl = config.baseUrl ?? "";
+	const store = config.permissionStore ?? defaultPermissionStore;
+	const url = (u) => baseUrl && u.startsWith("/") ? `${baseUrl}${u}` : u;
+	const syncPermissions = (user) => {
+		if (!config.getPermissions) return;
+		if (user) store.set(config.getPermissions(user));
+		else store.clear();
+	};
+	async function fetchMe() {
+		try {
+			const res = await fetch(url(config.meUrl), { credentials });
+			if (!res.ok) {
+				syncPermissions(null);
+				return null;
+			}
+			const user = await res.json();
+			syncPermissions(user);
+			return user;
+		} catch {
+			syncPermissions(null);
+			return null;
+		}
+	}
+	async function login(cred) {
+		try {
+			const res = await fetch(url(config.loginUrl), {
+				method: "POST",
+				headers: { "Content-Type": "application/json" },
+				credentials,
+				body: JSON.stringify(cred)
+			});
+			if (res.status === 401) return {
+				ok: false,
+				message: messages.invalidCredentials
+			};
+			if (!res.ok) {
+				let msg = messages.loginFailed;
+				try {
+					const body = await res.json();
+					const extracted = (config.extractLoginError ?? pickServerMessage)(body);
+					if (extracted) msg = extracted;
+				} catch {}
+				return {
+					ok: false,
+					message: msg
+				};
+			}
+			const user = await res.json();
+			syncPermissions(user);
+			return {
+				ok: true,
+				user
+			};
+		} catch {
+			return {
+				ok: false,
+				message: messages.networkError
+			};
+		}
+	}
+	async function logout() {
+		try {
+			await fetch(url(config.logoutUrl), {
+				method: "POST",
+				credentials
+			});
+		} catch {}
+		syncPermissions(null);
+	}
+	return {
+		fetchMe,
+		login,
+		logout
+	};
+}
 //#endregion
-export { ApiConfig, CurrencyHelper, DateHelper, FormRow, FormSection, ProgressHelper, UrgencyHelper };
+export { ApiConfig, ApiError, CurrencyHelper, DateHelper, FormRow, FormSection, ProgressHelper, UrgencyHelper, clearPermissions, createAuthClient, createODataService, createPermissionStore, defaultPermissionStore, getPermissions, hasAllPermissions, hasAnyPermission, hasPermission, setPermissions };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@iyulab/enterprise",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Enterprise utilities and components for iyulab framework",
   "keywords": [
     "enterprise",
@@ -28,17 +28,21 @@
     }
   },
   "scripts": {
-    "build": "vite build"
+    "build": "vite build",
+    "test": "vitest run"
   },
   "dependencies": {
     "@iyulab/components": "^1.1.1",
     "@iyulab/data-components": "^0.6.1",
-    "@iyulab/modern-app": "^0.3.7"
+    "@iyulab/http-client": "^0.9.0",
+    "@iyulab/modern-app": "^0.3.7",
+    "odata-query": "^8.0.7"
   },
   "devDependencies": {
     "@types/node": "^25.8.0",
     "typescript": "^5.9.3",
     "vite": "^8.0.13",
-    "vite-plugin-dts": "^5.0.0"
+    "vite-plugin-dts": "^5.0.0",
+    "vitest": "^3.0.0"
   }
 }