@rscc/common-core 0.1.2

package/dist/index.d.cts

@@ -0,0 +1,759 @@
+/**
+ * REST 공통 응답 봉투.
+ *
+ * 원천: contracts/common-response.schema.json (수동 동기화)
+ *
+ * - 와이어 키는 `success` (Java 필드명 isSuccess 의 직렬화 결과).
+ * - `code` 는 문자열 — error-codes.yaml 의 ResultCode 코드 값 중 하나.
+ * - `data` 는 실패 응답/데이터 없는 성공 응답에서 키 자체가 생략된다(absent, null 아님).
+ */
+interface CommonResponse<T> {
+    success: boolean;
+    code: string;
+    message: string;
+    data?: T;
+}
+/**
+ * 페이지네이션 응답 페이로드 (CommonResponse 의 data 자리에 실림).
+ *
+ * 원천: contracts/pagination.md (수동 동기화)
+ *
+ * - `page` 는 **0 시작(0-based)**. 1-기점 표시 변환은 클라이언트 책임.
+ * - 빈 페이지의 `content` 는 `[]` (null 아님).
+ */
+interface PageResponse<T> {
+    content: T[];
+    totalElements: number;
+    totalPages: number;
+    page: number;
+    size: number;
+}
+/**
+ * 400 검증 실패 상세 — 검증 오류 봉투(`ValidationErrorData.errors`)의 요소.
+ *
+ * 원천: contracts/validation-errors.md (수동 동기화)
+ *
+ * - `field` 는 Java BindingResult 표기: 세그먼트 `.` 연결, 인덱스 `[N]` 접미
+ *   (예: `items[0].name`). 객체(클래스)-수준 오류는 빈 문자열 `""`.
+ * - `rejectedValue` 는 스칼라만 실리며(문자열은 서버가 최대 100자로 절단),
+ *   null·비스칼라는 키 자체가 생략된다. PII 주의 — 비밀번호류 필드가 반사될 수
+ *   있으므로 화면 로그·외부 전송에 쓰지 말 것.
+ */
+interface FieldErrorDetail {
+    field: string;
+    reason: string;
+    rejectedValue?: string | number | boolean;
+}
+/** 검증 오류 봉투 — 400 검증 실패 응답의 `CommonResponse.data` 페이로드. */
+interface ValidationErrorData {
+    errors: FieldErrorDetail[];
+}
+/**
+ * data 가 검증 오류 봉투인지 판별하는 타입 가드 — `errors` 배열 존재 + 각 요소의
+ * field/reason 이 string 인지 검사한다. rejectedValue·추가 키는 검사하지 않는다
+ * (관용적 읽기 — 서버가 선택 키를 추가해도 통과, contracts/README.md 원칙 3).
+ */
+declare function isValidationErrorData(value: unknown): value is ValidationErrorData;
+/**
+ * 결과 코드 상수.
+ *
+ * 원천: contracts/error-codes.yaml (수동 동기화) — 코드 전량.
+ * 와이어의 code 는 문자열이다 (숫자 아님).
+ */
+declare const ResultCode: {
+    readonly SUCCESS: "200";
+    readonly BAD_REQUEST: "400";
+    readonly UNAUTHORIZED: "401";
+    readonly FORBIDDEN: "403";
+    readonly NOT_FOUND: "404";
+    readonly METHOD_NOT_ALLOWED: "405";
+    readonly CONFLICT: "409";
+    readonly UNSUPPORTED_MEDIA_TYPE: "415";
+    readonly TOO_MANY_REQUESTS: "429";
+    readonly INTERNAL_SERVER_ERROR: "500";
+};
+/** ResultCode 코드 값의 유니온 타입 ("200" | "400" | ...). */
+type ResultCode = (typeof ResultCode)[keyof typeof ResultCode];
+
+/**
+ * 아웃바운드 회복탄력성 — 지수 백오프 + full jitter 재시도. 런타임 의존성 0(native 만).
+ *
+ * 일시적 실패(네트워크 오류, 5xx, 429 등)를 짧은 대기 후 재시도해 흐름을 복구한다.
+ * **per-call 타임아웃**(개별 요청의 무한 대기 차단)은 전송 계층의 책임이다 —
+ * fetch 라면 `AbortSignal.timeout(ms)` 를 요청에 넘기고, 그 signal 을 이 함수의
+ * `signal` 로도 넘겨 재시도 루프까지 함께 취소되게 한다. 이 유틸은 재시도 정책과
+ * **전체 재시도 시간 예산**(`maxElapsedMs`)을 담당한다.
+ *
+ * full jitter: 대기시간을 `[0, cap]` 에서 균등 추출한다(cap = 지수 백오프 값). 다수
+ * 클라이언트가 동시에 실패했을 때 재시도가 한 시점에 몰리는 thundering herd 를 흩뜨린다.
+ */
+interface RetryOptions {
+    /** 최대 재시도 횟수(총 시도 = retries + 1). 기본 3. */
+    retries?: number;
+    /** 백오프 base(ms). 기본 200. */
+    minDelayMs?: number;
+    /** 회당 대기 상한(ms). 기본 5000. */
+    maxDelayMs?: number;
+    /** 지수 배수. 기본 2. */
+    factor?: number;
+    /** full jitter 적용 여부. 기본 true. */
+    jitter?: boolean;
+    /** 전체 재시도 시간 예산(ms). 0이면 무제한. 다음 대기가 예산을 넘기면 재시도를 포기한다. 기본 0. */
+    maxElapsedMs?: number;
+    /** 이 오류(와 0-기점 attempt)를 재시도할지. 기본: 항상 재시도. */
+    shouldRetry?: (error: unknown, attempt: number) => boolean;
+    /**
+     * 계산된 대기(ms)를 최종 대기(ms)로 조정하는 훅 — 예: 429 응답의 Retry-After 를
+     * 하한으로 적용({@link parseRetryAfterMs} 참조). 반환값이 유한수가 아니면 무시
+     * (계산값 유지)하고, 음수는 0 으로 클램프한다. `maxDelayMs` 상한은 훅 결과에
+     * **재적용하지 않는다** — Retry-After 가 백오프 상한보다 길 수 있는 것이 목적이며,
+     * 폭주 방어는 기존 `maxElapsedMs` 예산이 담당한다.
+     */
+    overrideDelay?: (error: unknown, attempt: number, delayMs: number) => number;
+    /** 재시도 직전 콜백(로깅 등). delayMs 는 overrideDelay 적용 후의 최종값. */
+    onRetry?: (error: unknown, attempt: number, delayMs: number) => void;
+    /** 취소 신호. abort 시 대기/재시도를 즉시 중단하고 reject 한다. */
+    signal?: AbortSignal;
+}
+/** 해당 HTTP 상태가 재시도 권장 대상(408/429/500/502/503/504)인지. */
+declare function isRetryableStatus(status: number): boolean;
+/**
+ * Retry-After 헤더값(delta-seconds 또는 RFC1123 HTTP-date)을 대기 ms 로 파싱한다.
+ * 해석 불가면 null. HTTP-date 가 과거/현재 시각이면 0 (해석 불가가 아님). 요일 토큰은
+ * 검증하지 않고 무시하며(3언어 공통), 존재하지 않는 날짜·시각 범위 초과는 해석 불가다.
+ * Java `Retry.parseRetryAfterMs` / Python `parse_retry_after`(초 단위) 와 동일 규칙.
+ *
+ * @param nowMs 기준 시각(epoch ms). 기본 Date.now() — 테스트 주입용.
+ */
+declare function parseRetryAfterMs(value: string | null | undefined, nowMs?: number): number | null;
+/**
+ * `fn` 을 지수 백오프 + jitter 로 재시도한다. `fn` 이 값을 반환/resolve 하면 그 값을,
+ * 재시도가 소진되거나 `shouldRetry` 가 false 면 마지막 오류를 throw 한다.
+ *
+ * @param fn 0-기점 attempt 를 받는 작업(동기/비동기 모두 허용).
+ */
+declare function retry<T>(fn: (attempt: number) => Promise<T> | T, options?: RetryOptions): Promise<T>;
+
+/**
+ * API 호출 실패 (실패 봉투 / HTTP 에러) 시 throw 되는 에러.
+ *
+ * `traceId` 는 장애 문의 시 사용자에게 제시할 수 있는 상관관계 식별자다
+ * (contracts/trace.md). 응답 에코 헤더 값이 우선이며, 에코를 읽을 수 없으면
+ * (예: CORS 에서 Access-Control-Expose-Headers 미설정) 요청에 부착해 보낸 값을 쓴다.
+ */
+declare class ApiError extends Error {
+    /** 결과 코드 — 봉투의 code, 비봉투 응답이면 HTTP 상태 코드 문자열. */
+    readonly code: string;
+    /** HTTP 상태 코드. */
+    readonly status: number;
+    /** 이 요청의 traceId (에코 헤더 우선, 없으면 발신 값). */
+    readonly traceId: string;
+    /**
+     * 실패 봉투의 data (예: 검증 오류 봉투 — {@link import("./types").isValidationErrorData}
+     * 로 판별). 비봉투 에러/data 부재 시 undefined.
+     */
+    readonly data?: unknown;
+    /**
+     * 응답 `Retry-After` 헤더의 대기 ms — throw 시점에 {@link parseRetryAfterMs} 로
+     * 파싱한 값. 헤더 부재/해석 불가면 null.
+     */
+    readonly retryAfterMs: number | null;
+    /**
+     * JSON 파싱 실패 시(strictJson=true, code "INVALID_JSON") 원문 본문 —
+     * 진단용으로 앞 {@link MAX_RAW_TEXT_LENGTH}자까지 절단 보존. 그 외 경로는 undefined.
+     */
+    readonly rawText?: string;
+    constructor(args: {
+        code: string;
+        message: string;
+        status: number;
+        traceId: string;
+        data?: unknown;
+        retryAfterMs?: number | null;
+        rawText?: string;
+    });
+}
+/**
+ * apiClient 재시도 설정 — 요청을 core {@link retry} 로 감싼다.
+ *
+ * RetryOptions 중 shouldRetry/overrideDelay/signal 은 클라이언트가 내부 관리한다:
+ * overrideDelay 는 Retry-After 하한 적용으로 고정하고, signal 은 요청의
+ * `init.signal` 을 fetch 와 재시도 대기 양쪽에 전달한다 (abort 시 대기 즉시 중단).
+ */
+interface ApiClientRetryOptions extends Omit<RetryOptions, "shouldRetry" | "overrideDelay" | "signal"> {
+    /** 재시도 판정. 기본: (ApiError && isRetryableStatus(status)) || TypeError(네트워크 오류). */
+    shouldRetry?: (error: unknown, attempt: number) => boolean;
+    /**
+     * 재시도 허용 메서드(대문자). 기본 ["GET","HEAD","OPTIONS","PUT","DELETE"] —
+     * 비멱등 POST/PATCH 는 옵트인. 커스텀 shouldRetry 를 줘도 이 게이트는 유지된다.
+     */
+    methods?: string[];
+}
+/** 관측 훅 onRequest 인자 — 논리 호출(재시도 묶음) 시작 시점의 요청 정보. */
+interface ApiRequestInfo {
+    /** HTTP 메서드 (대문자 정규화). */
+    method: string;
+    /** 호출 시 넘긴 path 원문 (baseUrl 조인 전). */
+    path: string;
+    /** 이 논리 호출의 발신 traceId. */
+    traceId: string;
+}
+/** 관측 훅 onResponse 인자 — 최종 성공 확정 시점의 응답 정보. */
+interface ApiResponseInfo {
+    method: string;
+    path: string;
+    /** 확정 응답의 traceId (에코 헤더 우선, 없으면 발신 값). */
+    traceId: string;
+    /** 최종 HTTP 상태 코드. */
+    status: number;
+    /** onRequest 시점 → 최종 확정까지의 소요 ms (재시도 대기 포함). */
+    durationMs: number;
+}
+/** 관측 훅 onError 인자 — 최종 실패 확정 시점의 오류 정보. */
+interface ApiErrorInfo {
+    method: string;
+    path: string;
+    /** ApiError 면 그 traceId, 네트워크 오류 등이면 발신 값. */
+    traceId: string;
+    /** ApiError 면 HTTP 상태, 네트워크 오류(fetch TypeError 등)면 undefined. */
+    status?: number;
+    /** onRequest 시점 → 최종 확정까지의 소요 ms (재시도 대기 포함). */
+    durationMs: number;
+    /** 최종 확정된 오류 원본. */
+    error: unknown;
+}
+interface ApiClientConfig {
+    /**
+     * API 서버 base URL (예: "http://localhost:53002"). 끝 슬래시 유무 무관 —
+     * path 와의 경계 슬래시가 자동 단일화된다 ("http://host/" + "/v1" → "http://host/v1").
+     * 상대 baseUrl("/api")도 지원.
+     */
+    baseUrl: string;
+    /** 토큰 공급자. 지정 시 반환값이 truthy 면 `Authorization: Bearer <token>` 부착. */
+    getToken?: () => string | null | undefined;
+    /** 401 수신 시 throw 직전에 호출되는 콜백 (로그아웃/리다이렉트 등 소비자 정책 주입). */
+    onUnauthorized?: (error: ApiError) => void;
+    /** fetch 구현체 주입 (테스트용). 기본 globalThis.fetch. */
+    fetchImpl?: typeof fetch;
+    /** traceId 헤더명. 기본 "X-Trace-Id" (contracts/trace.md). */
+    traceIdHeader?: string;
+    /**
+     * 지정 시 요청을 core retry() 로 감싼다. 미지정 = 재시도 없음(현행 동작).
+     *
+     * - traceId 는 논리 호출당 1회 생성되어 전 시도에 동일 부착된다
+     *   (재시도 묶음이 서버 로그에서 단일 trace 로 조회됨).
+     * - 429/503 등의 Retry-After 헤더는 계산된 대기의 하한으로 자동 존중된다.
+     * - 1회성 body(ReadableStream/FormData)는 재전송이 불가하므로 재시도 없이 1회 실행.
+     * - onUnauthorized 는 시도마다 발화될 수 있다 (기본 판정에선 401 비재시도라 1회).
+     */
+    retry?: ApiClientRetryOptions;
+    /**
+     * true 면 성공(2xx) 응답의 본문이 유효한 JSON 이 아닐 때(본문 읽기 `text()` 실패 포함)
+     * 조용히 null 을 반환하지 않고 code "INVALID_JSON" 의 ApiError 를 throw 한다
+     * (INVALID_JSON 은 클라이언트 로컬 코드 — 서버 봉투 enum(error-codes.yaml) 밖).
+     * 원문은 확보된 경우에 한해 {@link ApiError.rawText} 에 2048자 상한으로 절단 보존
+     * (읽기 실패 경로는 원문이 없어 undefined). 빈 본문(204 등)은 본문 부재이지 파싱 실패가
+     * 아니므로 throw 하지 않고 null 을 반환한다. 비-2xx 실패 경로에는 적용되지 않는다(현행 유지).
+     * 기본 false — 비-JSON 2xx 본문은 종전대로 null 반환.
+     */
+    strictJson?: boolean;
+    /**
+     * 관측 훅 — 논리 호출(재시도 묶음) 시작 시 1회 발화 (첫 시도 fetch 직전).
+     *
+     * 훅 예외 정책 (onResponse/onError 공통): 훅이 던진 예외는 삼켜져 본 요청의
+     * 성공/실패 결과에 영향을 주지 않는다. 단 클라이언트 인스턴스당 최초 1회만
+     * console.warn 으로 알린 뒤 이후 침묵한다(로그 폭주 방지).
+     */
+    onRequest?: (info: ApiRequestInfo) => void;
+    /** 관측 훅 — 재시도 포함 최종 성공 확정 시 1회 발화. 예외 정책은 {@link onRequest} 참조. */
+    onResponse?: (info: ApiResponseInfo) => void;
+    /** 관측 훅 — 재시도 포함 최종 실패 확정 시 1회 발화. 예외 정책은 {@link onRequest} 참조. */
+    onError?: (info: ApiErrorInfo) => void;
+}
+/** 성공 결과 + 메타 (traceId 등). requestWithMeta 의 반환형. */
+interface ApiResult<T> {
+    data: T;
+    /** 이 요청의 traceId (에코 헤더 우선, 없으면 발신 값). */
+    traceId: string;
+    status: number;
+    /**
+     * 본문 미소비 원본 Response — 파싱은 `clone()` 사본으로 하므로 `text()`/`json()`
+     * 재호출이 가능하다. 단 fetchImpl 이 `clone()` 미지원(비표준 mock)이면 종전대로
+     * 소비된 상태다.
+     */
+    response: Response;
+}
+interface ApiClient {
+    /**
+     * 요청을 보내고 CommonResponse 봉투면 data 를 언랩해 반환. 비봉투 JSON 은 그대로 반환.
+     * 성공(2xx)이지만 본문이 JSON 이 아니면(text/plain, 204 등 빈 본문 포함) null 이
+     * 반환된다(종전 계약 유지) — 단 strictJson=true 면 비어 있지 않은 비-JSON 본문은
+     * 대신 INVALID_JSON ApiError 를 throw 한다(빈 본문은 본문 부재라 계속 null).
+     */
+    request<T>(path: string, init?: RequestInit): Promise<T>;
+    /** request 와 동일하되 traceId·status·원본 Response 메타를 함께 반환. */
+    requestWithMeta<T>(path: string, init?: RequestInit): Promise<ApiResult<T>>;
+}
+/**
+ * CommonResponse 봉투를 이해하는 fetch 래퍼 팩토리.
+ *
+ * 동작 (contracts/common-response.schema.json, trace.md):
+ * - 매 요청에 traceId 를 생성해 traceIdHeader(기본 X-Trace-Id)로 부착한다.
+ * - 응답이 CommonResponse 봉투면 success 검사 후 data 를 언랩한다
+ *   (data 부재 시 undefined). 비봉투 JSON 은 그대로 반환.
+ * - 실패 봉투 / HTTP 에러는 code·message·traceId 를 담은 ApiError 를 throw.
+ * - 401 은 throw 직전에 onUnauthorized 콜백을 호출한다.
+ * - retry 지정 시 요청을 core retry() 로 감싼다 ({@link ApiClientRetryOptions} —
+ *   멱등 메서드 기본, Retry-After 하한, 시도 간 동일 traceId).
+ *
+ * 저장소 접근·경로·이벤트명 하드코딩 없음 — 전부 config 주입.
+ */
+declare function createApiClient(config: ApiClientConfig): ApiClient;
+
+/**
+ * SSE 스트리밍 프레임 파서.
+ *
+ * 원천: contracts/sse-frames.md (수동 동기화)
+ *
+ * 프레임은 단일 `data:` 라인 + 빈 줄(`\n\n` 구분). 페이로드는 종료 마커
+ * `[DONE]`(리터럴) 을 제외하면 전부 키로 판별하는 단일 키 JSON 객체:
+ * conversationId / sources / delta / error.
+ *
+ * 주의: 프레임 구분자는 계약상 LF(`\n\n`) 고정 — CRLF(`\r\n\r\n`) 로 내려오는
+ * 스트림은 지원하지 않는다 (프록시 등이 개행을 CRLF 로 정규화하면 프레임이
+ * 분리되지 않아 유실됨. 서버 계약이 LF 를 보장할 때만 사용할 것).
+ */
+/** sources 프레임의 요소 (camelCase — sse-frames.md 의 웹/외부 응답 계약). */
+interface SseSource {
+    /** 문서 출처 문자열 (없으면 url 폴백, 그것도 없으면 ""). */
+    source: string;
+    /** 본문 스니펫 (서버측 길이 상한으로 절단). */
+    content: string;
+    /** 관련도 점수, 소수 4자리 반올림. 원본 부재 시 0.0. */
+    score: number;
+    dataSourceId: number | null;
+}
+/** 프레임 판별 유니온 — 모르는 키/파싱 실패는 "skip" (관용적 읽기, non-breaking 확장 허용). */
+type SseFrameEvent = {
+    type: "conversationId";
+    id: number;
+} | {
+    type: "sources";
+    sources: SseSource[];
+} | {
+    type: "delta";
+    delta: string;
+} | {
+    type: "error";
+    message: string;
+} | {
+    type: "done";
+} | {
+    type: "skip";
+};
+/**
+ * 프레임 1개(구분자 `\n\n` 제거 후의 문자열)를 파싱한다. 순수 함수.
+ *
+ * 파싱 규칙 (sse-frames.md "소비자 파싱 규칙"):
+ * - `data:` 라인 부재 → skip (에러 아님)
+ * - 페이로드 리터럴 `[DONE]` → done
+ * - 키 검사 순서: conversationId(number) → sources(array) → delta(string) → error(string)
+ * - 일치 키 없음/JSON 파싱 실패 → 조용히 skip
+ */
+declare function parseSseFrame(frame: string): SseFrameEvent;
+interface SseCallbacks {
+    /** 스트림 첫 프레임의 대화 세션 id (search-api 가 prepend). */
+    onConversationId?: (id: number) => void;
+    /** RAG 근거 문서 — delta 보다 먼저 1회. */
+    onSources?: (sources: SseSource[]) => void;
+    /** 답변 텍스트 증분 — 0회 이상 반복. */
+    onDelta?: (delta: string) => void;
+    /** in-band 오류. 이후 [DONE] 이 따라온다. error 이후의 delta 는 전달되지 않는다. */
+    onError?: (message: string) => void;
+    /** [DONE] 종료 마커 수신. */
+    onDone?: () => void;
+}
+/**
+ * fetch Response 의 body 스트림을 UTF-8 디코드 → `\n\n` 프레임 분리 → 콜백 호출.
+ *
+ * - 청크 경계가 프레임/멀티바이트 문자 중간에 걸려도 안전 (버퍼 누적 + streaming decode).
+ * - error 프레임 수신 후에도 [DONE] 까지 읽되, 이후 delta 는 무시한다 (sse-frames.md 규칙 5).
+ * - [DONE] 수신 시 즉시 resolve. 스트림이 [DONE] 없이 끝나도 남은 버퍼를 처리하고 resolve.
+ */
+declare function readSseStream(response: {
+    body: ReadableStream<Uint8Array> | null;
+}, callbacks: SseCallbacks): Promise<void>;
+
+/**
+ * JWT 페이로드 디코더 (contracts/jwt-claims.md).
+ *
+ * ⚠️ **서명을 검증하지 않는다.** base64url 디코드만 수행하므로 표시·만료 판단 등
+ * 신뢰가 필요 없는 클라이언트 용도 전용이다. 인가 판단은 반드시 서버 검증을 거칠 것.
+ */
+/**
+ * JWT 의 페이로드(두 번째 세그먼트)를 base64url 디코드해 JSON 객체로 반환한다.
+ * 세그먼트 부재·디코드/파싱 실패 시 null. 서명 검증은 하지 않는다 (모듈 주석 참조).
+ */
+declare function decodeJwtPayload(token: string): Record<string, unknown> | null;
+/**
+ * exp 클레임(NumericDate, 초)을 epoch 밀리초로 반환. 파싱 실패/클레임 부재 시 null.
+ * 서명 검증은 하지 않는다.
+ */
+declare function getTokenExpiry(token: string): number | null;
+/**
+ * 토큰 만료 여부. **디코드 불가/exp 부재도 만료로 취급**한다 (fail-closed).
+ * 서명 검증은 하지 않는다 — 위조 여부는 알 수 없고 시각만 본다.
+ *
+ * @param nowMs 비교 기준 시각 (기본 Date.now(), 테스트용 주입 가능)
+ */
+declare function isTokenExpired(token: string, nowMs?: number): boolean;
+
+/**
+ * API 키 등 시크릿 문자열 마스킹.
+ *
+ * 원천: java/rscc-common-core `MaskingUtils.maskSecret` 와 동일 규칙 (수동 동기화).
+ *
+ * 규칙:
+ * - null/undefined/blank(공백뿐) — 그대로 반환
+ * - 8자 이하 — 전량 `'*'` (앞뒤를 노출하면 원문 대부분이 드러나므로)
+ * - 9자 이상 — 앞 4자 + 뒤 4자만 노출, 가운데는 **항상 4개의 `'•'`** 로 고정
+ *   (실제 길이만큼 채우지 않는 이유: 마스킹 결과 길이에서 시크릿의 실제 길이 누설 방지)
+ */
+declare function maskSecret(secret: string): string;
+declare function maskSecret(secret: null): null;
+declare function maskSecret(secret: undefined): undefined;
+declare function maskSecret(secret: string | null | undefined): string | null | undefined;
+/**
+ * 이름 마스킹 (홍길동 → 홍*동, 김철 → 김*). 원천: Java `MaskingUtils.maskName`.
+ * null/blank/외자(1글자)는 원본 반환. 2글자는 첫 글자 + `*`, 3글자 이상은
+ * 첫·마지막 글자만 살리고 가운데를 전부 `*`.
+ */
+declare function maskName(name: string): string;
+/**
+ * 휴대폰 마스킹 (010-1234-5678 → 010-****-5678). 원천: Java `MaskingUtils.maskPhone`.
+ * 하이픈 유무와 무관하게 가운데 3~4자리를 치환. null/blank 는 원본.
+ *
+ * 주의: 정규식은 부분 문자열 단위로 매칭·치환된다(Java `replaceAll` 파리티).
+ * 형식이 보장되지 않는 값을 로그에 노출할 때 반환값을 그대로 신뢰하지 말 것.
+ */
+declare function maskPhone(phone: string): string;
+/**
+ * 이메일 마스킹 (test1234@d.com → te******@d.com). 원천: Java `MaskingUtils.maskEmail`.
+ * `@` 없으면 원본. 아이디 2글자 이하면 첫 글자만 노출. `@` 다중 시 Java 와 동일하게
+ * 첫 `@` 뒤 세그먼트를 도메인으로 취한다.
+ */
+declare function maskEmail(email: string): string;
+/**
+ * 카드번호 마스킹 (1234-5678-1234-5678 → 1234-****-****-5678).
+ * 원천: Java `MaskingUtils.maskCardNumber`. 하이픈 유무 무관, 가운데 8자리 치환.
+ * null/blank 는 원본. maskPhone 과 동일한 부분 매칭 주의사항이 적용된다.
+ */
+declare function maskCardNumber(cardNumber: string): string;
+
+/**
+ * 오프셋 없는 LocalDateTime 와이어 직렬화 헬퍼 — contracts/datetime.md.
+ *
+ * 핵심 규약: **와이어에는 시간대/오프셋을 절대 싣지 않는다.** 값은 서버 기준
+ * (운영 전제: KST) 벽시계 시각으로 해석된다.
+ *
+ * ⚠️ Z 스큐 경고(datetime.md): `new Date(x).toISOString()` 은 UTC 로 변환해 끝에
+ * `Z` 를 붙인다. 서버(`LocalDateTime`)는 그 `Z` 를 조용히 버리고 나머지를 KST 벽시계로
+ * 재해석해 **9시간 스큐**를 만든다. 이 모듈의 직렬화 함수는 오프셋을 절대 만들지 않아
+ * 그 경로를 원천 차단한다. `<input type="datetime-local">` 값은 이미 오프셋 없는
+ * 형식이므로 그대로 보내면 되고, Date 객체를 보내야 할 땐 {@link toWireDateTime} 을 쓴다.
+ */
+/**
+ * Date 의 **로컬** 필드를 `yyyy-MM-ddTHH:mm:ss`(오프셋 없음)로 직렬화한다.
+ * `toISOString()`(UTC/Z) 대신 이 함수를 쓸 것 — 그래야 스큐가 생기지 않는다.
+ */
+declare function toWireDateTime(date: Date): string;
+/** Date 의 로컬 날짜를 `yyyy-MM-dd` 로 직렬화한다. */
+declare function toWireDate(date: Date): string;
+/**
+ * 와이어 datetime 문자열(`yyyy-MM-ddTHH:mm[:ss[.fff]]`)을 **로컬 시간대**로 해석한
+ * Date 로 파싱한다(사용자·서버가 모두 KST 라는 전제). 끝의 `Z`/오프셋은 무시하고
+ * 벽시계 숫자만 취한다(Java Jackson lenient 파리티). 형식 불일치 시 throw.
+ */
+declare function parseWireDateTime(value: string): Date;
+/**
+ * 문자열 끝의 `Z` 또는 `±HH:MM`/`±HHMM` 오프셋을 제거한다(발신 전 sanitize).
+ * 시각 자체는 변환하지 않고 벽시계 부분만 남긴다. 오프셋이 없으면 원본을 그대로 반환.
+ * 날짜부(`T` 앞)의 `-` 는 오프셋으로 오인하지 않는다.
+ */
+declare function stripZone(value: string): string;
+
+/**
+ * 한글 초성 변환 — 자동완성 초성 검색용.
+ *
+ * 원천: Python `rscc_common.text.chosung` 및 r-search `Chosung.java` 와 로직 파리티
+ * (호환 자모 19자, 0xAC00 기준 음절 분해, 공백/호환 모음 스킵, 그 외 소문자화).
+ *
+ * 사용자가 키보드로 단독 자음을 입력하면 호환 자모(U+3131~U+314E, 예: ㅅ=U+3145)가
+ * 나오므로, 음절에서 추출하는 초성도 같은 호환 자모로 맞춘다(조합용 자모 U+1100대 아님).
+ *
+ * 파리티 주의: 비-한글 폴백 소문자화는 JS `String.toLowerCase`(유니코드 전체 매핑)라
+ * Java `Character.toLowerCase`(단순 매핑)와 일부 특수문자에서 결과가 다를 수 있으나,
+ * 한글 초성 검색 용도에서는 실질 영향이 없다.
+ */
+/**
+ * 텍스트를 초성 문자열로 변환한다.
+ * - 완성 음절(가~힣) → 초성 호환 자모
+ * - 이미 호환 자음(ㄱ~ㅎ) → 그대로
+ * - 공백·호환 모음 단독(조합 중 전이) → 무시
+ * - 그 외(ASCII 등) → 소문자
+ */
+declare function toChosung(s: string): string;
+/** 입력에 호환 자모 자음(ㄱ~ㅎ)이 하나라도 있으면 초성 질의로 간주한다. */
+declare function isChosungQuery(s: string): boolean;
+
+/**
+ * TTL 캐시 + single-flight. 런타임 의존성 0 (native Map/Promise 만).
+ *
+ * Java `com.rscc.common.cache.TtlCache` / Python `rscc_common.cache` 와 시맨틱 동일
+ * (3언어 공유 벡터 CS-01~08 — 각 언어 테스트에 수동 동기화):
+ *
+ * - 만료 판정: `now - createdAt >= ttl` 이면 만료 (경계 시각 도달 즉시 만료).
+ *   **lazy expiry** — 만료 항목은 접근/삽입 시점에만 제거한다 (백그라운드 타이머 없음).
+ * - 용량: 삽입 후 maxEntries 초과 시 (1) 만료 항목 전량 제거 → (2) 여전히 초과면
+ *   삽입 순서(단조 seq) 최소 항목부터 제거. 덮어쓰기(set)는 createdAt·seq 를
+ *   갱신한다(재삽입 시맨틱).
+ * - single-flight: 동일 키 동시 get 은 로더 1회 실행 후 결과 공유. **실패는 캐시하지
+ *   않음** — 대기자 전원에게 동일 오류 전파 후 다음 호출은 로더를 재실행한다.
+ * - null/undefined 는 캐시하지 않음 (로더 반환은 그대로 반환·저장 없음, 명시 set 은
+ *   TypeError — 부정 캐시 방지. Java put 의 NullPointerException 대칭).
+ * - 명시적 비범위: LRU 액세스-순 갱신, hit/miss 통계, 제거 리스너, 엔트리별 TTL.
+ */
+interface TtlCacheOptions {
+    /** 항목 생존 시간(ms). 필수 > 0 (아니면 RangeError). */
+    ttlMs: number;
+    /** 최대 엔트리 수. 필수 > 0 (아니면 RangeError). */
+    maxEntries: number;
+    /** 현재 시각(ms) 공급자. 기본 Date.now — 결정적 테스트용. */
+    now?: () => number;
+}
+interface TtlCache<K, V> {
+    /**
+     * single-flight 로더 경유 조회 — 동일 키 로딩이 진행 중이면 그 Promise 를 공유한다.
+     * 로더 실패는 캐시하지 않는다 (대기자 전원 동일 오류, 다음 호출은 로더 재실행).
+     * 로더가 null/undefined 를 반환하면 그대로 반환하되 저장하지 않는다.
+     */
+    get(key: K, loader: (key: K) => Promise<V> | V): Promise<V>;
+    /** 로더 없이 조회 — 미보유/만료 시 undefined. */
+    peek(key: K): V | undefined;
+    /**
+     * 저장 — 기존 키 덮어쓰기는 createdAt·seq 를 갱신한다 (재삽입 시맨틱).
+     * null/undefined 는 TypeError (조회 불가 유령 엔트리 방지 — 부정 캐시 방지).
+     */
+    set(key: K, value: V): void;
+    /** 제거. 항목이 있어 제거됐으면 true. */
+    delete(key: K): boolean;
+    /** 전량 제거. 진행 중 로딩(inflight)은 취소하지 않는다 — 완료 시 결과가 저장될 수 있다. */
+    clear(): void;
+    /** 현재 엔트리 수 — 만료됐지만 아직 정리되지 않은 항목 포함 (lazy expiry, 정리 전 기준). */
+    size(): number;
+}
+/** TTL 캐시 팩토리. ttlMs/maxEntries 가 양수가 아니면 RangeError 를 throw 한다. */
+declare function createTtlCache<K, V>(options: TtlCacheOptions): TtlCache<K, V>;
+
+/**
+ * 경량 서킷 브레이커. 런타임 의존성 0 (native 만).
+ *
+ * Java `com.rscc.common.util.CircuitBreaker` / Python `rscc_common.circuit_breaker` 와
+ * 시맨틱 동일 (3언어 공유 벡터 CB-01~09 — 각 언어 테스트에 수동 동기화. Python 은
+ * 시간 단위가 초 — `초 × 1000 == ms`).
+ *
+ * - **연속(consecutive) 실패 카운트**: `onFailure()` 가 failureThreshold 에 도달(`>=`)하면
+ *   OPEN. `onSuccess()` 는 카운터를 0 으로 리셋한다 (슬라이딩 윈도 비채택 — 단순성).
+ * - **lazy 전이**: OPEN → HALF_OPEN 전이는 `allowRequest()` 호출 시점에 판정한다
+ *   (백그라운드 타이머 없음 — TtlCache lazy expiry 톤). openDurationMs 경과(`>=`) 후
+ *   첫 `allowRequest()` 가 전이와 프로브 슬롯 획득을 원자적으로 한 동작으로 수행한다.
+ * - **HALF_OPEN 프로브 1개**: 프로브가 진행 중이면 나머지 `allowRequest()` 는 false.
+ *   프로브 성공 → CLOSED(카운터 0), 프로브 실패 → OPEN 재진입(openedAt 갱신 —
+ *   전체 openDurationMs 재대기).
+ * - **결과 보고 규율**: `allowRequest()==true` 를 받은 호출만 `onSuccess()`/`onFailure()`
+ *   를 **정확히 1회** 호출한다 (try/finally 로 보고 보장 권장 — 보고 누락은 아래 프로브
+ *   보류를 무기한 지속시킨다). OPEN 대기 중 늦게 도착한 보고는 상태·openedAt·카운터를
+ *   바꾸지 않고(no-op — CB-08) 미보고 그랜트 잔량만 소진한다.
+ * - **스테일 그랜트 격리**: CLOSED 시절 그랜트가 아직 보고되지 않은 동안에는
+ *   openDurationMs 가 경과해도 HALF_OPEN 전이(프로브)가 보류된다 — 스테일 보고가 프로브
+ *   결과로 오인되는 것을 막아 HALF_OPEN 중 도착하는 보고는 항상 프로브의 것이다 (CB-09).
+ *
+ * @example 서킷 + 재시도 조합 — 시도 직전 allowRequest 게이트, 결과를 브레이커에 보고.
+ * OPEN 차단 오류는 shouldRetry 에서 비재시도로 걸러 즉시 실패시킨다(빠른 실패 유지).
+ * ```ts
+ * const cb = createCircuitBreaker({ failureThreshold: 5, openDurationMs: 30_000 });
+ * const circuitOpen = new Error("서킷 OPEN — 요청 차단");
+ * await retry(
+ *   async () => {
+ *     if (!cb.allowRequest()) throw circuitOpen;
+ *     try {
+ *       const r = await call();
+ *       cb.onSuccess();
+ *       return r;
+ *     } catch (error) {
+ *       cb.onFailure();
+ *       throw error;
+ *     }
+ *   },
+ *   {
+ *     shouldRetry: (error) => error !== circuitOpen, // OPEN 차단은 즉시 실패
+ *     onRetry: (error, attempt, delayMs) => console.warn(`재시도 ${attempt} (${delayMs}ms)`),
+ *   }
+ * );
+ * ```
+ */
+type CircuitState = "CLOSED" | "OPEN" | "HALF_OPEN";
+interface CircuitBreakerOptions {
+    /** OPEN 전이 임계 — 연속 실패가 이 값에 도달(`>=`)하면 OPEN. 필수 양의 정수 (아니면 RangeError). */
+    failureThreshold: number;
+    /** OPEN 유지 시간(ms) — 경과(`>=`) 후 첫 allowRequest() 가 HALF_OPEN 전이. 필수 유한 양수 (아니면 RangeError). */
+    openDurationMs: number;
+    /** 현재 시각(ms) 공급자. 기본 Date.now — 결정적 테스트용. */
+    now?: () => number;
+}
+interface CircuitBreaker {
+    /**
+     * 요청 통과 여부 — CLOSED 는 true, OPEN 대기 중 false, openDurationMs 경과 시
+     * HALF_OPEN 전이 + 프로브 슬롯 획득(true) — 단 CLOSED 시절 미보고 그랜트가 남아 있으면
+     * 전이를 보류하고 false (CB-09). HALF_OPEN 프로브 경합 시 나머지 false.
+     * true 를 받은 호출만 결과를 onSuccess()/onFailure() 로 보고해야 한다.
+     */
+    allowRequest(): boolean;
+    /** 성공 보고 — CLOSED 카운터 리셋, HALF_OPEN 프로브 성공 시 CLOSED 복귀. OPEN 중엔 무시. */
+    onSuccess(): void;
+    /** 실패 보고 — CLOSED 연속 카운트 증가(임계 도달 시 OPEN), HALF_OPEN 프로브 실패 시 OPEN 재진입. OPEN 중엔 무시. */
+    onFailure(): void;
+    /** 현재 상태 조회 — lazy 전이 특성상 openDurationMs 경과 후에도 allowRequest() 전엔 OPEN 으로 보고된다. */
+    state(): CircuitState;
+}
+/** 서킷 브레이커 팩토리 (createTtlCache 관용). 옵션 검증 실패 시 RangeError 를 throw 한다. */
+declare function createCircuitBreaker(options: CircuitBreakerOptions): CircuitBreaker;
+
+/**
+ * 토큰버킷 레이트리미터. 런타임 의존성 0 (native 만).
+ *
+ * Java `com.rscc.common.util.TokenBucket` / Python `rscc_common.rate_limit.TokenBucket`
+ * 와 시맨틱 동일 (3언어 공유 벡터 RL-01~07 — 각 언어 테스트에 수동 동기화. Python 은
+ * 시간 단위가 초 — `초 × 1000 == ms`).
+ *
+ * - **연속(continuous) 리필**: `tokens = min(capacity, tokens + elapsed × refillPerSecond)`
+ *   — tokens 는 실수 누적(절사 없음). 리필은 접근 시점에 lazy 계산한다(타이머 없음).
+ * - **초기 토큰 = capacity**: 콜드 스타트 버스트를 허용한다.
+ * - `n > capacity` 는 **항상 false** (예외 아님 — 영원히 충족 불가한 요구는 조용히 거부).
+ * - **시계 역행 방어**: `elapsed = max(0, now - last)` — 역행 구간은 리필 0 취급.
+ */
+interface TokenBucketOptions {
+    /** 버킷 용량(최대 버스트). 필수 양의 정수 (아니면 RangeError). */
+    capacity: number;
+    /** 초당 리필 토큰 수. 필수 유한 양수 (아니면 RangeError). */
+    refillPerSecond: number;
+    /** 현재 시각(ms) 공급자. 기본 Date.now — 결정적 테스트용. */
+    now?: () => number;
+}
+interface TokenBucket {
+    /**
+     * 토큰 n개 획득 시도 — 부족하면 대기 없이 즉시 false.
+     * n 기본 1, 양의 정수가 아니면 RangeError. `n > capacity` 는 항상 false (예외 없음).
+     */
+    tryAcquire(n?: number): boolean;
+}
+/** 토큰버킷 팩토리 (createTtlCache 관용). 옵션 검증 실패 시 RangeError 를 throw 한다. */
+declare function createTokenBucket(options: TokenBucketOptions): TokenBucket;
+
+/**
+ * 동시성 제한 Bulkhead. 런타임 의존성 0 (native Promise 만).
+ *
+ * Java `com.rscc.common.util.Bulkhead` / Python `rscc_common.bulkhead` 와 시맨틱 동일
+ * (3언어 공유 벡터 BH-01~05 — 각 언어 테스트에 수동 동기화).
+ *
+ * - `maxConcurrent` 실행 슬롯 + `maxQueue`(기본 0) 대기 슬롯.
+ * - 실행 여유 → 즉시 진입, 대기 여유 → 슬롯이 빌 때까지 대기(FIFO), 둘 다 만석 →
+ *   **즉시 거부** — {@link BulkheadFullError} 로 reject 하며(동기 throw 아님) 이때
+ *   작업 함수는 **호출되지 않는다** (BH-04).
+ * - 슬롯 해제는 finally 보장 — 작업이 예외로 끝나도 반환된다 (BH-03).
+ */
+/** Bulkhead 만석 즉시 거부 오류. Java `BulkheadFullException` / Python `BulkheadFullError` 패리티. */
+declare class BulkheadFullError extends Error {
+    constructor(message: string);
+}
+interface BulkheadOptions {
+    /** 동시 실행 슬롯 수. 필수 양의 정수 (아니면 RangeError). */
+    maxConcurrent: number;
+    /** 대기 슬롯 수. 기본 0(대기 없이 즉시 거부), 0 이상 정수 (아니면 RangeError). */
+    maxQueue?: number;
+}
+interface Bulkhead {
+    /**
+     * async fn 래핑 — 획득→실행→해제(finally 보장). 거부는 reject(BulkheadFullError) —
+     * 동기 throw 아님. 거부 시 fn 은 호출되지 않는다.
+     */
+    execute<T>(fn: () => Promise<T> | T): Promise<T>;
+    /** 현재 실행 중 작업 수 — 관측·테스트용. */
+    activeCount(): number;
+    /** 현재 대기 중 작업 수 — 관측·테스트용. */
+    queuedCount(): number;
+}
+/** Bulkhead 팩토리 (createTtlCache 관용). 옵션 검증 실패 시 RangeError 를 throw 한다. */
+declare function createBulkhead(options: BulkheadOptions): Bulkhead;
+
+/**
+ * 로그 인젝션 방지 sanitize. 런타임 의존성 0 (native 만).
+ *
+ * Java `com.rscc.common.util.LogSanitizer` / Python `rscc_common.log_sanitize` 와
+ * 규칙 동일 (3언어 공유 골든 벡터 LS-01~10 — 각 언어 테스트에 수동 동기화).
+ *
+ * 외부 입력(헤더·쿼리·본문 필드)을 로그 한 줄에 실을 때 CR/LF 로 가짜 로그 라인을
+ * 위조하거나 ANSI ESC 로 터미널을 오염시키는 로그 인젝션을 차단한다.
+ *
+ * 규칙:
+ * 1. 치환 대상: `U+0000–U+001F` 전체(CR·LF·TAB 포함) + `U+007F`(DEL).
+ * 2. 각 1문자 → **공백 1자(U+0020)** 1:1 치환. 붕괴(collapse) 없음 — `\r\n` 은 공백 2개.
+ *    (U+FFFD 비채택 — 비-UTF8 로그 싱크 mojibake·grep 친화성.)
+ * 3. maxLength 생략 시 무제한(치환만). 지정 시 4 이상 정수(미만은 RangeError) —
+ *    치환 후 길이가 **초과**하면 앞 `maxLength-3` 자 + ASCII `"..."` 로 절단해
+ *    결과 총 길이 == maxLength 를 보장한다. 경계(`==`)는 절단 없음.
+ * 4. 길이 단위: JS 는 UTF-16 코드유닛 (Java 동일, Python 은 코드포인트) — 보충 평면
+ *    문자에서 절단 위치가 언어 간 1 유닛 다를 수 있다 (로그 용도 허용 오차).
+ */
+/**
+ * 로그에 싣기 전 외부 입력을 정화한다 — 제어 문자를 공백으로 치환하고,
+ * maxLength 지정 시 초과분을 `"..."` 로 절단한다(결과 총 길이 == maxLength).
+ *
+ * @param value 정화할 값 (string 만 — 런타임 null 은 계약 밖).
+ * @param maxLength 결과 최대 길이(UTF-16 코드유닛). 생략 시 무제한. 4 미만이면 RangeError.
+ */
+declare function sanitizeLogValue(value: string, maxLength?: number): string;
+
+/**
+ * 사업자등록번호(10자리)·법인등록번호(13자리) 체크섬 검증.
+ *
+ * 원천: Java `BusinessNumberUtils` / Python `bizno.py` 와 동일 규칙 (수동 동기화).
+ *
+ * **체크섬만 검증한다** — 실존 여부·구분코드 의미 검증은 범위 밖이다.
+ * 정규화는 하이픈(`-`)·스페이스(` `)·탭(`\t`)만 위치 불문 제거하고 그 외 문자는
+ * 보존한다(검증 단계에서 걸러짐). 숫자 판정은 ASCII `[0-9]` 만 — 전각 숫자
+ * (`１２３…`)는 3언어 모두 무효 처리한다.
+ */
+/**
+ * 사업자·법인번호 표기에서 하이픈(`-`)·스페이스(` `)·탭(`\t`)을 위치 불문 제거한다.
+ * 그 외 문자는 보존한다(비대상 문자는 검증 단계에서 무효 처리).
+ */
+declare function normalizeBusinessNumber(value: string): string;
+/**
+ * 사업자등록번호(10자리) 체크섬 검증. null/undefined, 정규화 후 ASCII 숫자
+ * 10자리가 아닌 값은 false.
+ *
+ * 검증식: `sum = Σ(i=0..8) dᵢ×wᵢ + (d₈×5)//10`, `check = (10 − sum%10) % 10`,
+ * 유효 ⟺ `check == d₉` (가중치 `[1,3,7,1,3,7,1,3,5]`).
+ */
+declare function isValidBusinessNumber(value: string | null | undefined): boolean;
+/**
+ * 법인등록번호(13자리) 체크섬 검증. null/undefined, 정규화 후 ASCII 숫자
+ * 13자리가 아닌 값은 false.
+ *
+ * 검증식: 가중치 `1,2` 반복 12개, `sum = Σ(i=0..11) dᵢ×wᵢ`,
+ * `check = (10 − sum%10) % 10`, 유효 ⟺ `check == d₁₂`.
+ */
+declare function isValidCorporateNumber(value: string | null | undefined): boolean;
+
+export { type ApiClient, type ApiClientConfig, type ApiClientRetryOptions, ApiError, type ApiErrorInfo, type ApiRequestInfo, type ApiResponseInfo, type ApiResult, type Bulkhead, BulkheadFullError, type BulkheadOptions, type CircuitBreaker, type CircuitBreakerOptions, type CircuitState, type CommonResponse, type FieldErrorDetail, type PageResponse, ResultCode, type RetryOptions, type SseCallbacks, type SseFrameEvent, type SseSource, type TokenBucket, type TokenBucketOptions, type TtlCache, type TtlCacheOptions, type ValidationErrorData, createApiClient, createBulkhead, createCircuitBreaker, createTokenBucket, createTtlCache, decodeJwtPayload, getTokenExpiry, isChosungQuery, isRetryableStatus, isTokenExpired, isValidBusinessNumber, isValidCorporateNumber, isValidationErrorData, maskCardNumber, maskEmail, maskName, maskPhone, maskSecret, normalizeBusinessNumber, parseRetryAfterMs, parseSseFrame, parseWireDateTime, readSseStream, retry, sanitizeLogValue, stripZone, toChosung, toWireDate, toWireDateTime };