@iyulab/enterprise 0.13.0 → 0.15.0

package/dist/index.d.ts

@@ -1,11 +1,660 @@
-/**
- * @iyulab/enterprise
- * Enterprise utilities and components for iyulab framework
- */
-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';
+import { CSSProperties } from 'react';
+import { HttpResponse } from '@iyulab/http-client';
+import { JSX } from 'react';
+import { LocaleNamespace } from '@iyulab/components/dist/utilities/Locale.js';
+import { ReactNode } from 'react';
+
+export declare class ApiConfig {
+    private static _baseUrl;
+    private static _odataPrefix;
+    private static _apiPrefix;
+    private static _isDevelopment;
+    /**
+     * Initialize API configuration
+     * @param options Configuration options
+     */
+    static initialize(options?: ApiConfigOptions): void;
+    /**
+     * API Base URL (always relative path by default)
+     */
+    static get baseUrl(): string;
+    /**
+     * Manually set Base URL (for testing or custom configurations)
+     */
+    static setBaseUrl(url: string): void;
+    /**
+     * OData endpoint prefix
+     */
+    static get odataPrefix(): string;
+    /**
+     * REST API endpoint prefix
+     */
+    static get apiPrefix(): string;
+    /**
+     * Generate OData endpoint URL
+     * @param entityName Entity name for OData endpoint
+     */
+    static getODataUrl(entityName: string): string;
+    /**
+     * Generate REST API endpoint URL
+     * @param endpoint API endpoint path
+     */
+    static getApiUrl(endpoint: string): string;
+    /**
+     * Generate full URL with query parameters
+     * @param endpoint Endpoint path
+     * @param params Query parameters
+     */
+    static getUrlWithParams(endpoint: string, params: Record<string, string | number | boolean | undefined>): string;
+    /**
+     * Check if running in development environment
+     * Tries to detect from various bundler environments
+     */
+    static get isDevelopment(): boolean;
+    /**
+     * Check if running in production environment
+     */
+    static get isProduction(): boolean;
+    /**
+     * Reset configuration to defaults
+     */
+    static reset(): void;
+}
+
+/**
+ * API configuration and environment-based endpoint management
+ *
+ * Supports both development (proxy) and production (same-origin) deployments
+ */
+export declare interface ApiConfigOptions {
+    /** Base URL for all API requests (default: '') */
+    baseUrl?: string;
+    /** OData endpoint prefix (default: '$data') */
+    odataPrefix?: string;
+    /** REST API endpoint prefix (default: 'api') */
+    apiPrefix?: string;
+    /** Force development mode detection */
+    isDevelopment?: boolean;
+}
+
+/**
+ * API 호출 실패 에러 — HTTP status 를 실어 호출부가 상태별 분기(예: 404 도메인 문구)를 할 수 있게 한다.
+ * `Error` 를 상속하므로 기존 `e instanceof Error`/`e.message` 소비처는 그대로 동작한다.
+ */
+export declare class ApiError extends Error {
+    readonly status: number;
+    /** OData v4 오류 봉투의 `error.details`(필드별 검증 상세) — 서버 응답에 없거나 파싱 실패면 undefined. */
+    readonly details?: ApiErrorDetail[];
+    constructor(message: string, status: number, details?: ApiErrorDetail[]);
+}
+
+/**
+ * OData v4 오류 봉투의 `error.details` 항목 — 필드별 검증 실패 상세.
+ *
+ * 규격(OData JSON Format v4.0)상 각 항목은 `code`/`message` 를 **반드시** 갖고
+ * `target`(오류가 난 속성 이름)은 **선택**이다 — 필수로 선언하면 target 을 생략한
+ * 서버 응답에서 타입이 거짓말을 하게 된다.
+ */
+export declare interface ApiErrorDetail {
+    code: string;
+    message: string;
+    target?: string;
+}
+
+export declare 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 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 declare interface AuthClientMessages {
+    /** 401 로그인 실패 */
+    invalidCredentials: string;
+    /** 기타 로그인 실패(non-401) 폴백 */
+    loginFailed: string;
+    /** 네트워크/예외 */
+    networkError: string;
+}
+
+/** 기본 store 권한을 비운다. */
+export declare const clearPermissions: () => void;
+
+export declare function createAuthClient<TUser, TCredentials = Record<string, unknown>>(config: AuthClientConfig<TUser>): AuthClient<TUser, TCredentials>;
+
+/**
+ * OData v4 + custom REST 서비스를 생성한다.
+ * 반환된 서비스는 상태를 공유하지 않는 순수 클로저이므로 여러 개를 만들어도 안전하다(테스트 격리에도 유리).
+ */
+export declare function createODataService(config: ODataServiceConfig): ODataService;
+
+/** 독립적인 권한 store 를 생성한다(테스트 격리·다중 컨텍스트에 유리). */
+export declare function createPermissionStore(initial?: Iterable<string>): PermissionStore;
+
+/**
+ * Currency formatting utility class.
+ *
+ * @deprecated The formatting logic now lives in `@iyulab/components`' `formatCurrency`
+ * (framework-neutral, lower in the dependency stack so `@iyulab/modern-app` can consume it
+ * too). This class is kept as a thin, behavior-preserving wrapper for existing callers —
+ * new code should import `formatCurrency`/`formatNumber`/`formatDate` from
+ * `@iyulab/components` directly.
+ */
+export declare class CurrencyHelper {
+    /**
+     * Format amount as currency string.
+     * @param amount - Amount to format
+     * @param currency - Currency code (default: 'KRW')
+     * @param locale - Locale for formatting (default: 'ko-KR')
+     */
+    static formatCurrency(amount: number | null | undefined, currency?: string, locale?: string): string;
+    /** Format amount as Korean Won (KRW) */
+    static formatKRW(amount: number | null | undefined): string;
+    /** Format amount as US Dollar (USD) */
+    static formatUSD(amount: number | null | undefined): string;
+    /** Format amount as Euro (EUR) */
+    static formatEUR(amount: number | null | undefined): string;
+    /** Format amount as Japanese Yen (JPY) */
+    static formatJPY(amount: number | null | undefined): string;
+    /** Format amount as Chinese Yuan (CNY) */
+    static formatCNY(amount: number | null | undefined): string;
+    /**
+     * Parse currency string to number.
+     * @param value - Currency string to parse
+     */
+    static parseCurrency(value: string): number;
+}
+
+/**
+ * Date manipulation and formatting utility class
+ */
+export declare class DateHelper {
+    /**
+     * Format date to YYYY-MM-DD string
+     * @param date - Date to format (Date object or ISO string)
+     */
+    static formatDate(date: Date | string | null | undefined): string;
+    /**
+     * Format date to localized string
+     * @param date - Date to format
+     * @param locale - Locale for formatting (default: 'ko-KR')
+     * @param options - Intl.DateTimeFormat options
+     */
+    static formatLocalDate(date: Date | string | null | undefined, locale?: string, options?: Intl.DateTimeFormatOptions): string;
+    /**
+     * Format datetime to YYYY-MM-DD HH:mm string
+     * @param date - Date to format
+     */
+    static formatDateTime(date: Date | string | null | undefined): string;
+    /**
+     * Calculate days difference between two dates
+     * @param startDate - Start date
+     * @param endDate - End date
+     * @returns Number of days (positive if endDate > startDate)
+     */
+    static getDaysDifference(startDate: Date | string, endDate: Date | string): number;
+    /**
+     * Calculate days from now to target date
+     * @param targetDate - Target date
+     * @returns Days remaining (negative if overdue)
+     */
+    static getDaysFromNow(targetDate: Date | string): number;
+    /**
+     * Check if date is today
+     */
+    static isToday(date: Date | string): boolean;
+    /**
+     * Check if date is in the past
+     */
+    static isPast(date: Date | string): boolean;
+    /**
+     * Check if date is in the future
+     */
+    static isFuture(date: Date | string): boolean;
+    /**
+     * Add days to date
+     * @param date - Base date
+     * @param days - Number of days to add (can be negative)
+     */
+    static addDays(date: Date | string, days: number): Date;
+    /**
+     * Get start of day (00:00:00)
+     */
+    static startOfDay(date: Date | string): Date;
+    /**
+     * Get end of day (23:59:59.999)
+     */
+    static endOfDay(date: Date | string): Date;
+}
+
+/**
+ * 기본 싱글톤 권한 store. 앱 전역에서 `hasPermission(code)` 를 어디서나 호출하는
+ * 흔한 패턴을 위해 free 함수로 바인딩해 노출한다. 격리가 필요하면 `createPermissionStore()` 를 쓴다.
+ */
+export declare const defaultPermissionStore: PermissionStore;
+
+/**
+ * Display string for an absent value (`null`/`undefined`/unparsable), shared by every
+ * formatting helper in this package so "no value" renders identically everywhere and
+ * never collides with a real `0`.
+ */
+export declare const EMPTY_VALUE_DISPLAY = "\u2014";
+
+/**
+ * `@iyulab/enterprise` 의 화면 문자열 — **영어 기본 + 로케일 레지스트리**.
+ *
+ * ## 왜 이 파일이 생겼나
+ *
+ * 헬퍼들이 라벨을 **한국어 리터럴로** 들고 있었다(실측 14건). 이 리포는 이미 로케일 표준을
+ * 채택했지만(영어 기본 + 레지스트리) **강제하는 장치가 없어서** 채택 이후에 들어온 코드가
+ * 한국어 기본값을 갖고 있었다.
+ *
+ * ⚠**「의견 있음」이 정당화하는 것은 스타일 값의 의견이지 언어가 아니다**(2026-08-04 결정).
+ *
+ * ## 왜 자체 레지스트리를 만들지 않았나
+ *
+ * `@iyulab/components` 의 `Locale.namespace()`(1.23.0~)를 쓴다. 자체 구현은 이 조직의
+ * **네 번째 레지스트리**가 됐을 것이고, 그러면 소비자가 앱 하나에서 로케일을 **두 번**
+ * 전환해야 한다. `Locale.set()` 한 번으로 검증 메시지·이 라벨이 함께 따라온다.
+ *
+ * ## 동작 변화
+ *
+ * ⚠기본 로케일은 브라우저 언어에서 감지된다 — **한국어 브라우저는 종전과 같은 문구**를 본다
+ * (`ko-KR` → `ko`). 그 밖의 환경은 한국어 대신 **영어**를 본다. 그것이 이 이주의 목적이다.
+ */
+export declare type EnterpriseMessageKey = 'progressNotStarted' | 'progressEarly' | 'progressInProgress' | 'progressPastMid' | 'progressAlmost' | 'progressDone' | 'urgencyOverdue' | 'urgencyCritical' | 'urgencyUrgent' | 'urgencySoon' | 'urgencyNormal' | 'daysOverdue' | 'daysToday' | 'daysRemaining';
+
+/**
+ * L2 폼 행 — 기본 2열, `full` 이면 1열.
+ *
+ * 오버라이드 계약(docs/lob-layers.md §2)에 따라 `className`·`style` 을 받아 병합한다.
+ * `columns` 는 2열 고정이 맞지 않는 소비자가 **컴포넌트를 복제하지 않고** 조정하는 경로다
+ * — 복제가 시작되면 이 계층은 쓰기 전보다 나쁜 상태를 만든다.
+ *
+ * 🔴**트랙은 `minmax(0, 1fr)` 이지 `1fr` 이 아니다 — 순수 `1fr` 은 «균등» 을 약속하고**
+ * **지키지 않는다.** 그리드 아이템의 기본 `min-width: auto` 는 내용의 min-content 아래로
+ * 줄어들기를 거부하므로, 한 칸에 긴 내용이 들어오면 그 칸만 부풀고 나머지가 찌그러진다.
+ * 실측(400px 컨테이너 · 한 칸에 긴 불가분 문자열): 2열이 **425/8**, 3열이 **425/8/8** 이었고
+ * 행 자체가 컨테이너를 넘쳤다. `minmax(0, 1fr)` 은 트랙의 최소를 0 으로 만들어 **자식을**
+ * **건드리지 않고** 이를 고친다 — 같은 실측에서 **196/196** · **128/128/128**.
+ *
+ * ⚠**긴 불가분 내용 자체의 넘침은 별개 축이고 이 컴포넌트의 몫이 아니다.** 칸이 균등해져도
+ * 그 안의 긴 문자열은 여전히 자기 칸을 넘는다 — 그것은 셀의 `overflow-wrap` 이 답이다
+ * (`@iyulab/components` 의 엘리먼트는 이미 그 값을 갖는다). 같은 실측에서 `overflow-wrap` 을
+ * 주면 행의 넘침이 0 이 됐다.
+ *
+ * 계약은 `tests/form-layout-contract.test.ts` 가 고정한다 — 다만 그 파일은 **«선언» 을 재지**
+ * **«배치» 를 재지 않는다**(이 패키지엔 레이아웃을 계산하는 테스트 자리가 없다). 위 수치는
+ * 형제 패키지의 브라우저 프로젝트를 계측기로 빌린 일회성 탐침으로 쟀다.
+ */
+export declare function FormRow({ children, full, columns, className, style, }: {
+    children: ReactNode;
+    /** 한 행 전체를 한 칸으로 쓴다. `columns` 보다 우선한다. */
+    full?: boolean;
+    /** 열 수. 기본 2. */
+    columns?: number;
+    className?: string;
+    style?: CSSProperties;
+}): JSX.Element;
+
+/**
+ * L2 폼 블록 — 제목이 붙은 필드 묶음.
+ *
+ * 🔴**제목에 `text-transform: uppercase` 와 `letter-spacing` 을 걸지 않는다**(0.7.0 에서 제거).
+ *   ⑴ 한글에는 대문자가 없어 `uppercase` 가 **아무 효과가 없고**, 제목에 영문이 섞이면
+ *      그것만 커져 오히려 어수선해진다.
+ *   ⑵ 양수 `letter-spacing` 은 **한글 가독성을 떨어뜨린다** — 라틴 소문자 조판 관례를
+ *      그대로 옮기면 안 되는 자리다.
+ *   ⇒ 위계는 **크기·굵기·색** 세 신호로만 만든다(타입 스케일의 `label` 단).
+ *   영문 전용 UI 에서 눈썹 텍스트 느낌이 필요하면 `titleStyle` 로 `--u-text-overline-*`
+ *   단을 직접 지정한다 — 그 단은 영문·숫자 라벨을 전제하고 양수 자간을 갖는다.
+ *
+ * 오버라이드 계약(docs/lob-layers.md §2): 구조는 두고 **children 치환 + prop** 으로 바꾼다.
+ * ⚠기본 스타일은 병합 가능한 형태로만 둔다 — 호출자의 `style` 이 뒤에 오므로 필요한
+ * 항목만 골라 덮을 수 있다. 인라인으로 굳혀 두면 소비자 CSS 가 이길 수 없어(`!important`
+ * 외) 계약이 원천적으로 무효가 된다.
+ */
+export declare function FormSection({ title, children, className, style, titleStyle, }: {
+    title: ReactNode;
+    children: ReactNode;
+    className?: string;
+    style?: CSSProperties;
+    /** 제목 줄만 따로 조정할 때. 블록을 통째로 갈아엎지 않기 위한 훅이다. */
+    titleStyle?: CSSProperties;
+}): JSX.Element;
+
+/** 기본 store 의 현재 권한 집합. */
+export declare const getPermissions: () => ReadonlySet<string>;
+
+/** 기본 store 기준 모두 보유. */
+export declare const hasAllPermissions: (codes: Iterable<string>) => boolean;
+
+/** 기본 store 기준 하나라도 보유. */
+export declare const hasAnyPermission: (codes: Iterable<string>) => boolean;
+
+/** 기본 store 기준 단일 권한 보유 여부. */
+export declare const hasPermission: (code: string) => boolean;
+
+export declare interface LoginResult<TUser> {
+    ok: boolean;
+    user?: TUser;
+    message?: string;
+}
+
+/** 이 패키지의 문자열 묶음. 소비자는 `messages.register(locale, table)` 로 덮거나 언어를 더한다. */
+export declare const messages: LocaleNamespace<EnterpriseMessageKey>;
+
+/**
+ * 한 호출에만 적용되는 요청 옵션 — 서비스 전역 정책(`ODataServiceConfig`)의 호출 단위 예외.
+ *
+ * 🔴**전역 정책을 «끄는» 축만 둔다.** 새 동작을 켜는 스위치가 아니라, config 가 세운 기본
+ * 정책이 *그 호출에서만* 틀린 경우를 위한 탈출구다 — 그래서 기본값은 항상 «config 그대로» 이고,
+ * 옵션을 생략한 호출은 이 타입이 생기기 전과 **한 글자도 다르게 동작하지 않는다.**
+ */
+export declare interface ODataRequestOptions {
+    /**
+     * `false` → 이 호출의 401 을 «세션 만료» 로 취급하지 않는다: 전역 `onUnauthorized` 를
+     * 부르지 않고, `messages.sessionExpired` 로 덮어쓰지도 않으며, **서버가 준 메시지**로
+     * `ApiError(…, 401)` 을 던진다. 기본값(생략 시)은 전역 정책 그대로다.
+     *
+     * ⚠**로그인 자체가 이 옵션이 태어난 자리다** — 401 이 「세션이 끊겼다」가 아니라
+     * 「자격 증명이 틀렸다」를 뜻하는 유일한 호출이라, 전역 훅이 발화하면 로그인 화면에서
+     * 로그인 화면으로 리다이렉트되고 화면이 실패 사유를 **지어내야** 한다.
+     *
+     * ⚠**`authenticate()` 같은 이름 있는 프리미티브를 두지 않은 이유**: 그것은 엔드포인트
+     * 경로·바디 모양·토큰 처리 규약을 이 라이브러리가 안다고 가정하는 **도메인 이름**이다.
+     * 그 규약은 앱마다 다르므로 adapter 에 남기고, 라이브러리는 범용 축만 연다.
+     */
+    onUnauthorized?: false;
+}
+
+export declare 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>, opts?: ODataRequestOptions): Promise<T[]>;
+    /** OData GET(단건, key). */
+    odataGetById<T>(entity: string, id: string, opts?: ODataRequestOptions): Promise<T>;
+    /** `$count=true&$top=0` — 데이터 없이 총 건수만. */
+    odataCount(entity: string, filter?: Record<string, unknown>, opts?: ODataRequestOptions): Promise<number>;
+    /** OData POST(생성) — 토스트 없이 결과만(일괄 처리에서 토스트 폭주 방지). */
+    odataPostQuiet<T>(entity: string, body: Partial<T>, opts?: ODataRequestOptions): Promise<T>;
+    /** OData POST(생성) — 성공 시 `saved` 토스트. */
+    odataPost<T>(entity: string, body: Partial<T>, opts?: ODataRequestOptions): Promise<T>;
+    /** OData PATCH(수정) — 토스트 없이 결과만(자식 컬렉션 편집 후 부모의 파생 필드를
+     *  함께 동기화하는 등, 한 사용자 액션이 여러 mutation을 낼 때 토스트 폭주 방지). */
+    odataPatchQuiet<T>(entity: string, id: string, body: Partial<T>, opts?: ODataRequestOptions): Promise<void>;
+    /** OData PATCH(수정) — 성공 시 `updated` 토스트. */
+    odataPatch<T>(entity: string, id: string, body: Partial<T>, opts?: ODataRequestOptions): Promise<void>;
+    /** OData DELETE — 토스트 없이(`odataPatchQuiet`와 같은 이유). */
+    odataDeleteQuiet(entity: string, id: string, opts?: ODataRequestOptions): Promise<void>;
+    /** OData DELETE — 성공 시 `deleted` 토스트. */
+    odataDelete(entity: string, id: string, opts?: ODataRequestOptions): Promise<void>;
+    /** custom REST GET — 204 등 빈 바디를 안전 파싱. */
+    apiGet<T>(path: string, opts?: ODataRequestOptions): Promise<T>;
+    /** custom REST POST — 실패 시 `error` 토스트 후 rethrow(401 제외). `body`가 `FormData`
+     *  인스턴스면 그대로(직렬화 없이) 멀티파트로 전송된다 — `@iyulab/http-client`가
+     *  Content-Type을 브라우저 자동 설정에 맡기고 JSON 직렬화 분기를 타지 않는다.
+     *  `apiPut`/`apiPatch`도 동일하게 동작한다. */
+    apiPost<T>(path: string, body?: unknown, opts?: ODataRequestOptions): Promise<T>;
+    /** custom REST POST — 토스트 없이 결과만(`odataPostQuiet`와 같은 이유: 한 사용자 액션이
+     *  여러 요청을 내거나, 소비자가 자기 래퍼로 이미 통지할 때). */
+    apiPostQuiet<T>(path: string, body?: unknown, opts?: ODataRequestOptions): Promise<T>;
+    /** custom REST PUT(리소스 전체 교체/생성) — 실패 시 `error` 토스트 후 rethrow(401 제외).
+     *  `body`의 `FormData` 처리는 `apiPost` 참조. */
+    apiPut<T>(path: string, body?: unknown, opts?: ODataRequestOptions): Promise<T>;
+    /** custom REST PUT — 토스트 없이 결과만. */
+    apiPutQuiet<T>(path: string, body?: unknown, opts?: ODataRequestOptions): Promise<T>;
+    /** custom REST PATCH — 실패 시 `error` 토스트 후 rethrow(401 제외). `body`의 `FormData`
+     *  처리는 `apiPost` 참조. */
+    apiPatch<T>(path: string, body?: unknown, opts?: ODataRequestOptions): Promise<T>;
+    /** custom REST PATCH — 토스트 없이 결과만. */
+    apiPatchQuiet<T>(path: string, body?: unknown, opts?: ODataRequestOptions): Promise<T>;
+    /** custom REST DELETE — 실패 시 `error` 토스트 후 rethrow(401 제외). 대부분 204 No Content. */
+    apiDelete<T = void>(path: string, opts?: ODataRequestOptions): Promise<T>;
+    /** custom REST DELETE — 토스트 없이 결과만. */
+    apiDeleteQuiet<T = void>(path: string, opts?: ODataRequestOptions): Promise<T>;
+    /**
+     * URL 을 직접 조립한 커스텀 조회(csv-export·연결 프로브 등)를 위해 응답을 **그대로** 반환한다.
+     *
+     * 🔴**비-2xx 에도 던지지 않고 `onUnauthorized` 도 부르지 않는다 — 판단은 호출부가 한다.**
+     * 「raw」는 정책을 태우지 않는다는 뜻이고, 이 메서드가 존재하는 이유가 그것이다.
+     * 상태에 따라 예외·토스트·세션 처리를 원하면 `apiGet` 을 쓴다.
+     *
+     * ⚠**0.15.0 이전에는 선언이 이렇게 적혀 있으면서 실제로는 비-2xx 에 던졌다**(`throwIfError`
+     * 를 거쳤다). 그 어긋남 때문에 *"응답이 왔는가"* 만 묻는 연결 프로브가 401 을 「끊김」으로
+     * 세었다 — 서버가 살아서 거절한 것인데도. 선언이 옳고 구현이 틀렸던 자리라 구현을 고쳤다.
+     */
+    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;
+}
+
+export declare 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;
+        /** OData v4 `error.details` — 검증을 마친 항목만 실린다(`ApiError.details` 와 같은 값). */
+        details?: ApiErrorDetail[];
+        body?: unknown;
+    }) => string | undefined;
+}
+
+/** 서비스가 토스트/에러에 쓰는 사용자 대면 문구. 기본값은 영어 — 앱이 로케일별로 오버라이드한다. */
+export declare interface ODataServiceMessages {
+    /** POST 성공 토스트 */
+    saved: string;
+    /** PATCH 성공 토스트 */
+    updated: string;
+    /** DELETE 성공 토스트 */
+    deleted: string;
+    /** 401 세션 만료 시 throw 되는 에러 메시지 */
+    sessionExpired: string;
+    /** status별 매핑이 없을 때의 폴백 */
+    requestFailed: string;
+    /** 서버 raw 메시지가 없거나 너무 길 때 status → 친화 메시지 */
+    http: Record<number, string>;
+}
+
+/**
+ * 권한 스냅샷 store — 부팅 시점의 현재 사용자 권한 코드 집합을 보관하고
+ * `hasPermission`/`hasAny`/`hasAll` 판정을 제공한다. 프레임워크 무관(React·Lit 공통)이며
+ * 권한 코드는 **불투명 문자열**로만 다룬다(도메인 의미는 앱이 소유).
+ *
+ * 부팅 시점 스냅샷 모델 — 권한 변경은 다음 로그인(재-set)까지 반영되지 않는다. 단일 운영자
+ * 모델에 충분하며, 실시간 권한 회수/멀티테넌트가 필요하면 `subscribe` 로 반응형 확장 가능.
+ */
+export declare 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;
+}
+
+/**
+ * Progress bar and percentage utility class
+ */
+export declare class ProgressHelper {
+    /**
+     * Get color based on progress percentage
+     * @param progress - Progress value (0-100)
+     * @param thresholds - Custom thresholds { high, medium }
+     */
+    static getProgressColor(progress: number, thresholds?: {
+        high?: number;
+        medium?: number;
+    }): string;
+    /**
+     * Validate and clamp progress to 0-100 range.
+     *
+     * Returns `null` for a missing/unparsable input rather than `0` — "no progress value yet"
+     * and "0% progress" are different facts and must not render identically.
+     * @param progress - Raw progress value
+     * @param round - Whether to round to integer (default: true)
+     */
+    static validateProgress(progress: number, round?: boolean): number;
+    static validateProgress(progress: number | null | undefined, round?: boolean): number | null;
+    /**
+     * Convert decimal ratio to percentage.
+     *
+     * Returns `null` for a missing/unparsable input — see {@link validateProgress}.
+     * @param ratio - Decimal ratio (0-1)
+     * @param round - Whether to round to integer
+     */
+    static ratioToPercent(ratio: number | null | undefined, round?: boolean): number | null;
+    /**
+     * Get progress label text
+     * @param progress - Progress value (0-100)
+     */
+    static getProgressLabel(progress: number): string;
+    /**
+     * Calculate progress from current and total values
+     * @param current - Current value
+     * @param total - Total value
+     */
+    static calculateProgress(current: number, total: number): number;
+    /**
+     * Get CSS gradient for progress bar
+     * @param progress - Progress value (0-100)
+     */
+    static getProgressGradient(progress: number): string;
+}
+
+/** 기본 store 의 권한을 교체한다(부팅 시 `setPermissions(user.Permissions)`). */
+export declare const setPermissions: (codes: Iterable<string>) => void;
+
+/**
+ * Urgency configuration
+ */
+export declare interface UrgencyConfig {
+    /** Days threshold for critical urgency (default: 1) */
+    critical?: number;
+    /** Days threshold for urgent level (default: 3) */
+    urgent?: number;
+    /** Days threshold for soon level (default: 7) */
+    soon?: number;
+}
+
+/**
+ * Urgency calculation and display utility class
+ */
+export declare class UrgencyHelper {
+    private static defaultConfig;
+    /**
+     * Get urgency color based on days remaining
+     * @param daysRemaining - Days until deadline (negative if overdue)
+     * @param config - Custom urgency thresholds
+     */
+    static getUrgencyColor(daysRemaining: number | null | undefined, config?: UrgencyConfig): string;
+    /**
+     * Get urgency level based on days remaining
+     * @param daysRemaining - Days until deadline
+     * @param config - Custom urgency thresholds
+     */
+    static getUrgencyLevel(daysRemaining: number | null | undefined, config?: UrgencyConfig): UrgencyLevel;
+    /**
+     * Get urgency text label
+     * @param daysRemaining - Days until deadline
+     * @param config - Custom urgency thresholds
+     * @param labels - Custom label text
+     */
+    static getUrgencyText(daysRemaining: number | null | undefined, config?: UrgencyConfig, labels?: Partial<Record<UrgencyLevel, string>>): string;
+    /**
+     * Get background and text color for urgency badge
+     * @param daysRemaining - Days until deadline
+     * @param config - Custom urgency thresholds
+     */
+    static getUrgencyBadgeColors(daysRemaining: number | null | undefined, config?: UrgencyConfig): {
+        bg: string;
+        text: string;
+    };
+    /**
+     * Format days remaining as display text
+     * @param daysRemaining - Days until deadline
+     */
+    static formatDaysRemaining(daysRemaining: number | null | undefined): string;
+    /**
+     * Check if deadline is overdue
+     */
+    static isOverdue(daysRemaining: number | null | undefined): boolean;
+    /**
+     * Check if deadline requires attention
+     */
+    static needsAttention(daysRemaining: number | null | undefined, config?: UrgencyConfig): boolean;
+}
+
+/**
+ * Urgency level types
+ */
+export declare type UrgencyLevel = 'overdue' | 'critical' | 'urgent' | 'soon' | 'normal';
+
+export { }