@rscc/common-core 0.1.2 → 0.2.0

package/dist/index.d.cts

@@ -247,6 +247,22 @@ interface ApiClientConfig {
      * - onUnauthorized 는 시도마다 발화될 수 있다 (기본 판정에선 401 비재시도라 1회).
      */
     retry?: ApiClientRetryOptions;
+    /**
+     * 지정 시 대상 메서드 요청에 멱등성 키 헤더를 자동 부착한다 (contracts/idempotency.md).
+     * 미지정 = 미부착(현행 동작).
+     *
+     * - 키는 {@link generateIdempotencyKey} 로 **논리 호출당 1회** 생성된다 —
+     *   sentTraceId 와 같은 위치(재시도 클로저 밖)라 재시도 전 시도에 동일 키가
+     *   부착된다 ("같은 논리 작업 = 같은 키" 계약의 자동화).
+     * - 호출자가 이미 같은 이름의 헤더를 실었으면 덮어쓰지 않는다 (호출자 우선).
+     * - 새 논리 호출(새 request)은 새 키를 생성한다.
+     */
+    idempotency?: {
+        /** 멱등성 키 헤더명. 기본 "Idempotency-Key". */
+        header?: string;
+        /** 부착 대상 메서드(대문자). 기본 ["POST","PATCH"] — 비멱등 메서드만. */
+        methods?: string[];
+    };
     /**
      * true 면 성공(2xx) 응답의 본문이 유효한 JSON 이 아닐 때(본문 읽기 `text()` 실패 포함)
      * 조용히 null 을 반환하지 않고 code "INVALID_JSON" 의 ApiError 를 throw 한다
@@ -756,4 +772,539 @@ declare function isValidBusinessNumber(value: string | null | undefined): boolea
  */
 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 };
+/**
+ * 멱등성 키 생성 — contracts/idempotency.md (수동 동기화).
+ *
+ * 비멱등 메서드(POST/PATCH)의 실수 재전송이 부수효과를 중복 실행하지 않도록,
+ * 클라이언트가 논리 요청당 고유 키를 `Idempotency-Key` 헤더로 보낸다.
+ * 키 형식: `^[A-Za-z0-9_-]{1,128}$` — UUIDv4(36자, 하이픈 포함) 권장.
+ *
+ * "같은 논리 작업 = 같은 키, 새 작업 = 새 키" 가 핵심이다 — 재시도 루프
+ * **바깥에서 1회 생성**해 전 시도에 동일 부착해야 한다. apiClient 의
+ * `idempotency` 옵션은 이를 자동화한다 (키가 재시도 클로저 밖에서 생성됨).
+ */
+/**
+ * 멱등성 키 신규 생성 — `crypto.randomUUID()` 우선(UUIDv4), 부재 환경에서는
+ * Math.random 기반 8-4-4-4-12 hex 폴백 (generateTraceId 관용구 — 형식 동일).
+ * 두 경로 모두 계약 형식 `[A-Za-z0-9_-]{1,128}` 을 만족한다.
+ */
+declare function generateIdempotencyKey(): string;
+
+/**
+ * 웹훅 서명 — HMAC-SHA256. contracts/webhook-signature.md (수동 동기화).
+ *
+ * Java `com.rscc.common.crypto.WebhookSignature` / Python `rscc_common.webhook`
+ * 과 동일 규칙 (3언어 공유 골든 벡터 WS-01~07).
+ *
+ * - 서명 대상: `"{t}.{rawBody}"` — 본문은 **원문 바이트 그대로**(재직렬화 금지).
+ * - 서명: HMAC-SHA256 의 lowercase hex 64자. secret 은 UTF-8 바이트.
+ * - 헤더 값: `t=<unix초>,v1=<hex>[,v1=<hex>...]` — 다중 v1 = 무중단 시크릿
+ *   로테이션(어느 하나라도 일치하면 유효). 미지 key(v0/v2 등)는 무시.
+ *
+ * [주의] 언어별 시그니처 비대칭 — 계약 문서 인용: "JS 구현은 async 다 —
+ * WebCrypto(`crypto.subtle.sign`)가 Promise 기반이라 signWebhook/verifyWebhook 은
+ * Promise<string>/Promise<boolean> 을 반환한다. Java/Python 은 동기다.
+ * 시맨틱(입력→판정)은 3언어 동일하며 반환 형태만 다르다."
+ *
+ * Node 전용 API(`timingSafeEqual` 등) 미사용 — 브라우저/Node 공용
+ * (`globalThis.crypto.subtle`, Node 18+ / 모던 브라우저).
+ */
+/** 웹훅 서명 헤더명 기본값 (contracts/webhook-signature.md). */
+declare const WEBHOOK_SIGNATURE_HEADER = "X-Rscc-Signature";
+/**
+ * 웹훅 서명 헤더 값을 생성한다 (발신측) — 반환값이 `X-Rscc-Signature` 헤더
+ * 값 전체(`t=<unix초>,v1=<hex>`)다.
+ *
+ * 시크릿 로테이션 기간에는 신·구 시크릿으로 각각 sign 한 뒤 `v1` 을 병기해
+ * 발송한다 (`t=...,v1=<신>,v1=<구>` — t 가 같으므로 두 번째 결과의 `v1=` 부분만
+ * 이어 붙이면 된다).
+ *
+ * @param secret 서명 시크릿 (UTF-8 인코딩 후 HMAC 키로 사용).
+ * @param payload 요청 본문 — **원문 그대로** (파싱·재직렬화 금지, 계약).
+ * @param timestampSeconds 발신 시각 unix 초.
+ */
+declare function signWebhook(secret: string, payload: string | Uint8Array, timestampSeconds: number): Promise<string>;
+/**
+ * 웹훅 서명을 검증한다 (수신측) — 형식 오류·스큐 초과·전 후보 불일치 모두
+ * 예외 없이 **false** 를 반환한다 (호출부 분기 단순화, 계약).
+ *
+ * 판정 절차: 헤더 파싱(t 정확히 1개·정수, v1 1개 이상) → 시계 스큐
+ * `|now - t| ≤ toleranceSeconds`(경계 포함) → 보유 시크릿 각각 × 헤더의 각 v1
+ * 상수시간 대조, 하나라도 일치 → true.
+ *
+ * @param opts.header 수신한 `X-Rscc-Signature` 헤더 값 (부재 시 null → false).
+ * @param opts.payload 수신한 요청 본문 — raw 바이트/원문 문자열.
+ * @param opts.secrets 보유 시크릿 (단일 또는 배열 — 로테이션 기간 신·구 병행).
+ * @param opts.toleranceSeconds 허용 스큐(초). 기본 300.
+ * @param opts.nowSeconds 현재 시각 unix 초 주입 (테스트용). 기본 시스템 시계.
+ */
+declare function verifyWebhook(opts: {
+    header: string | null;
+    payload: string | Uint8Array;
+    secrets: string | string[];
+    toleranceSeconds?: number;
+    nowSeconds?: number;
+}): Promise<boolean>;
+
+/**
+ * 벌크/부분 실패 봉투 — BulkResult. contracts/bulk.md (수동 동기화).
+ *
+ * Java `com.rscc.common.response.BulkResult` / Python `rscc_common.bulk` 와
+ * 동일 와이어 계약 (3언어 공유 골든 벡터 BK-01~04).
+ *
+ * - 항상 `CommonResponse` 봉투의 `data` 자리에 실린다.
+ * - **항목 성공/실패 판정은 `code` 유무다** — code 있으면 실패, 없으면 성공.
+ * - 실패 항목은 items 에 전량 필수 기재, 성공 항목은 id 전달 필요 시만 기재.
+ * - 부분 실패여도 HTTP 200 + `success: true` (벌크 연산 자체는 수행됨).
+ * - `total == succeeded + failed` 불변식.
+ */
+/**
+ * 항목별 처리 상세 — `index` 는 **요청 배열에서의 0-기점 인덱스**(필수,
+ * 원본 항목과 대응시키는 유일 키). `code` 존재 = 실패 항목.
+ */
+interface BulkResultItem {
+    /** 요청 배열에서의 0-기점 인덱스 (필수). */
+    index: number;
+    /** 실패 사유 코드 — error-codes.yaml 코드 문자열 재사용. **존재 = 실패 항목**. */
+    code?: string;
+    /** 실패 사유 한국어 메시지 (실패 항목이면 기재). */
+    message?: string;
+    /** 성공 항목이 생성/영향을 준 리소스 식별자 (전달 필요 시만). */
+    id?: string;
+}
+/** 벌크 처리 결과 페이로드 — `total == succeeded + failed` 불변식. */
+interface BulkResult {
+    /** 요청에 담긴 전체 항목 수. */
+    total: number;
+    /** 성공 항목 수. */
+    succeeded: number;
+    /** 실패 항목 수. */
+    failed: number;
+    /** 항목별 상세 — 실패 전량 필수, 성공은 선택. 전량 성공·id 없음이면 `[]`. */
+    items: BulkResultItem[];
+}
+/**
+ * 값이 BulkResult 와이어 형태인지 판별하는 타입 가드 — total/succeeded/failed 가
+ * number, items 가 배열이고 각 요소에 number `index` 가 있는지만 검사한다.
+ * 선택 키(code/message/id)·미지 키는 검사하지 않는다 (관용적 읽기 —
+ * isValidationErrorData 관용구, 새 선택 키 추가는 non-breaking).
+ */
+declare function isBulkResult(value: unknown): value is BulkResult;
+/** 실패 항목만 추출한다 — 판정 기준은 `code` 유무 (계약 규칙 1). */
+declare function bulkFailures(result: BulkResult): BulkResultItem[];
+/** BulkResult 빌더 — success/failure 를 순서대로 기록하고 build 로 확정한다. */
+interface BulkResultBuilder {
+    /** 성공 항목 기록 — `id` 를 준 경우에만 items 에 기재된다 (응답 크기 억제). */
+    success(index: number, id?: string): BulkResultBuilder;
+    /** 실패 항목 기록 — items 에 반드시 기재된다 (code·message 필수, 계약 규칙 1·2). */
+    failure(index: number, code: string, message: string): BulkResultBuilder;
+    /** total/succeeded/failed 자동 계산으로 BulkResult 를 확정한다. */
+    build(): BulkResult;
+}
+/**
+ * BulkResult 빌더 생성 — 서버/BFF 측에서 항목별 처리 결과를 순서대로 기록한다.
+ *
+ * ```ts
+ * const result = createBulkResultBuilder()
+ *   .success(0, "ord_001")
+ *   .failure(1, "400", "수량은 1 이상이어야 합니다.")
+ *   .success(2) // id 없음 — items 미기재
+ *   .build(); // { total: 3, succeeded: 2, failed: 1, items: [...] }
+ * ```
+ */
+declare function createBulkResultBuilder(): BulkResultBuilder;
+
+/**
+ * 파일 업로드 검증 — 크기·확장자·매직바이트. contracts/file-upload.md (수동 동기화).
+ *
+ * Java `com.rscc.common.util.FileSniffer` / Python `rscc_common.upload` 와
+ * 동일 계약 (3언어 공유 골든 벡터 MB-01~11).
+ *
+ * **브라우저 프리검증이다** — 업로드 전에 사용자에게 즉시 피드백을 주는 용도이며,
+ * 프리검증 통과가 서버 검증을 대체하지 않는다 (보안 경계는 항상 서버).
+ *
+ * - 판정은 **컨테이너 수준**: docx/hwpx 는 `zip`, hwp(5.0)/doc 는 `cfbf` 로
+ *   판정된다 (내부 구조 열람은 비범위).
+ * - 판정 우선순위는 계약 테이블 위→아래, 첫 일치 kind 반환.
+ */
+/** 매직바이트 판정 결과 kind — 3언어 공유 소문자 문자열 (계약 테이블 고정). */
+type FileKind = "png" | "jpeg" | "gif" | "webp" | "pdf" | "zip" | "cfbf" | "hwp3";
+/**
+ * 선두 바이트의 매직바이트를 대조해 파일 kind 를 판정한다 — 계약 테이블
+ * 위→아래 첫 일치, 전부 불일치·빈 입력·시그니처보다 짧은 head 는 null.
+ *
+ * @param head 파일 선두 바이트 (webp 판정에 최대 12바이트 필요 — File.slice
+ *   등으로 앞부분만 읽어 넘기면 된다).
+ */
+declare function sniffFile(head: ArrayBuffer | Uint8Array): FileKind | null;
+/**
+ * 확장자가 허용하는 kind 집합 — 계약 매핑표 고정. 미지 확장자는 빈 집합.
+ * 대소문자 무시, 선행 `.` 은 허용(제거 후 비교).
+ */
+declare function kindsForExtension(ext: string): ReadonlySet<FileKind>;
+/** validateUpload 결과 — ok:false 면 첫 위반 사유·계약 메시지를 담는다. */
+type UploadValidationResult = {
+    ok: true;
+} | {
+    ok: false;
+    reason: "size" | "extension" | "content-mismatch";
+    message: string;
+};
+/**
+ * 업로드 파일 3중 검증 (브라우저 프리검증) — 순서: (1) 크기 ≤ maxSizeBytes →
+ * (2) 확장자 ∈ allowedExtensions → (3) 매직바이트 kind ∈ 확장자 허용 kind.
+ * 첫 위반의 사유·메시지(계약 문구)를 결과 객체로 반환한다 (예외 없음).
+ *
+ * 계약 매핑표에 없는 확장자를 allowlist 에 넣으려면 `extraMappings` 로 확장자 →
+ * 허용 kind 배열을 주입해야 한다(주입 확장자는 기본 표를 대체 — Python
+ * `extra_mappings` / Java `extraMappings` 대응). 매핑이 없는 허용 확장자는 콘텐츠
+ * 대조가 불가능해 콘텐츠 불일치로 거부된다 (Python 과 동일 판정 — 조용한 통과 금지).
+ *
+ * @param input.fileName 파일명 (확장자는 마지막 `.` 뒤, 대소문자 무시).
+ * @param input.size 파일 크기 바이트 (File.size).
+ * @param input.head 파일 선두 바이트 (12바이트 이상 권장 — webp 최대 요구량).
+ * @param input.maxSizeBytes 크기 상한 (엔드포인트 정책).
+ * @param input.allowedExtensions 허용 확장자 allowlist (대소문자 무시).
+ * @param input.extraMappings 확장자 → 허용 kind 확장 주입 (선택). 키는 소문자·
+ *   선행 `.` 없는 확장자.
+ */
+declare function validateUpload(input: {
+    fileName: string;
+    size: number;
+    head: ArrayBuffer | Uint8Array;
+    maxSizeBytes: number;
+    allowedExtensions: readonly string[];
+    extraMappings?: Readonly<Record<string, readonly FileKind[]>>;
+}): UploadValidationResult;
+
+/**
+ * 목록 조회 쿼리 빌더 — page/size/sort. contracts/query-params.md (수동 동기화).
+ *
+ * 요청 **생성측** 빌더다 — 서버 파서(Java `SortWhitelist`/`PageParams`,
+ * Python `rscc_common.query`)와 왕복 일치하는 쿼리스트링을 만든다.
+ *
+ * - sort 문법: `sort=<field>[,<direction>]` — 같은 이름 반복으로 다중 정렬
+ *   (선언 순서 = 정렬 우선순위). direction 생략 시 서버 기본 asc.
+ * - 예약 이름 `page`/`size`/`sort` 를 필터 이름으로 재사용하면 throw (계약).
+ */
+/** 정렬 지정 1건 — direction 생략 시 값에 방향을 싣지 않는다 (서버 기본 asc). */
+interface SortParam {
+    /** 정렬 필드 — 서버 화이트리스트와 정확 일치해야 한다 (대소문자 구분). */
+    field: string;
+    /** 정렬 방향. 생략 시 asc (서버 기본). */
+    direction?: "asc" | "desc";
+}
+/** buildListQuery 입력 — 전 필드 선택 (지정한 것만 쿼리에 실린다). */
+interface ListQueryOptions {
+    /** 페이지 번호 — 0-기점 (contracts/pagination.md 와 동일 기점). */
+    page?: number;
+    /** 페이지 크기. */
+    size?: number;
+    /** 다중 정렬 — 배열 순서 = 정렬 우선순위 (순서 보존). */
+    sort?: readonly SortParam[];
+    /**
+     * 필터 파라미터 (엔드포인트 고유 스키마). 배열 값은 같은 이름으로 반복 기재,
+     * null/undefined 값은 생략. 예약 이름 page/size/sort 는 금지 — RangeError.
+     */
+    filters?: Record<string, string | number | boolean | readonly (string | number | boolean)[] | null | undefined>;
+}
+/**
+ * 목록 조회 쿼리스트링을 조립한다 — `URLSearchParams` 반환
+ * (`toString()` 하면 서버 파서와 왕복 일치: `page=2&size=50&sort=name%2Cdesc`).
+ *
+ * @throws RangeError filters 키가 예약 이름(page/size/sort)인 경우.
+ */
+declare function buildListQuery(options: ListQueryOptions): URLSearchParams;
+
+/**
+ * 피처 플래그 읽기 — boolean 파싱 통일. contracts/feature-flags.md (수동 동기화).
+ *
+ * Java `com.rscc.common.util.FeatureFlags` / Python `rscc_common.feature_flags`
+ * 와 동일 파싱 규칙 (3언어 공유 골든 벡터 FF-01~06).
+ *
+ * - 참 집합은 **정확히 `{"true","1","on","yes"}`** — 대소문자 무시·trim.
+ *   그 외 전부 false ("y"·"t"·"enabled" 불인정 — 오타는 기능 꺼짐, 안전한 쪽).
+ * - **키 부재(→default)와 값 불인식(→false)은 다르다** — 잘못 쓴 설정 값이
+ *   default 뒤로 숨지 않게 한다.
+ * - JS 는 주입된 소스 객체만 본다 — **env 폴백 없음** (브라우저엔 env 가 없다,
+ *   계약 명시). 빌드타임 치환·서버 전달 설정 객체를 소스로 주입한다.
+ */
+/**
+ * 플래그 값을 boolean 으로 파싱한다 — 문자열은 trim·소문자화 후 참 집합
+ * `{"true","1","on","yes"}` 대조, boolean 은 그대로, null/undefined 는 false.
+ */
+declare function parseFlag(value: string | boolean | null | undefined): boolean;
+/** 피처 플래그 리더 — 주입된 소스 객체에서 boolean 플래그를 읽는다. */
+interface FeatureFlagReader {
+    /**
+     * 플래그 조회 — 키 부재 시 defaultValue(기본 false), 키 존재 시
+     * {@link parseFlag} 판정 결과 (불인식 값 → false, default 미적용).
+     */
+    isEnabled(key: string, defaultValue?: boolean): boolean;
+}
+/**
+ * 피처 플래그 리더 생성 — 소스 객체(빌드타임 치환·서버 전달 설정)를 주입한다.
+ * 키는 논리 키 그대로 조회한다 (예: `"search.rerank"`).
+ *
+ * ```ts
+ * const flags = createFeatureFlags({ "search.rerank": "on" });
+ * flags.isEnabled("search.rerank"); // true
+ * flags.isEnabled("upload.hwp-preview", true); // 키 부재 → default true
+ * ```
+ */
+declare function createFeatureFlags(source: Record<string, string | boolean | undefined>): FeatureFlagReader;
+
+/**
+ * 주민등록번호·외국인등록번호(13자리) 형식 검증.
+ *
+ * **[중요] 2020-10 이후 발급분은 뒷자리(성별코드 제외 6자리)가 임의번호라서
+ * mod-11 체크섬이 성립하지 않는다** — 따라서 기본 검증({@link isValidRrn})은
+ * 체크섬을 포함하지 않고, 레거시 체크섬은 {@link rrnChecksumOkLegacy} 로 분리한다.
+ *
+ * 원천: Java `RrnUtils` / Python `rrn.py` 와 동일 규칙 (수동 동기화).
+ *
+ * 검증 범위: 13자리 형식 + 성별코드(1~8) + 생년월일 실존(윤년 포함 실제 달력).
+ * **미래 날짜 검증은 비범위** — 기준 시점이 없는 순수 함수이므로 하지 않는다.
+ * 정규화는 하이픈·스페이스·탭만 제거(bizno 파리티), 숫자 판정은 ASCII `[0-9]` 만
+ * (전각 숫자 무효).
+ *
+ * ⚠️ 수집 최소화: 주민등록번호는 법령상 처리 근거가 있을 때만 취급하고, 저장 시
+ * 암호화 의무(개인정보보호법 제24조의2)가 있으며, 검증 목적 달성 즉시 파기를
+ * 권장한다.
+ */
+/**
+ * 주민등록번호 표기에서 하이픈(`-`)·스페이스(` `)·탭(`\t`)을 위치 불문 제거한다.
+ * 그 외 문자는 보존한다(검증 단계에서 무효 처리).
+ */
+declare function normalizeRrn(value: string): string;
+/**
+ * 기본 검증 = 13자리 형식 + 성별코드 1~8 + 생년월일 실존(윤년 포함 실제 달력).
+ * **체크섬 미포함** — 2020-10 이후 발급분은 뒷자리가 임의번호라 mod-11 이 성립하지
+ * 않는다. null/undefined·형식 위반은 false (예외 없음).
+ */
+declare function isValidRrn(value: string | null | undefined): boolean;
+/**
+ * 외국인등록번호 여부 — {@link isValidRrn} 을 통과하고 성별코드가 5~8 이면 true.
+ * 무효한 값은 false.
+ */
+declare function isForeignerRrn(value: string | null | undefined): boolean;
+/**
+ * 레거시 mod-11 체크섬 검증 — **2020-10 이전 발급분 한정**. 이후 발급분은
+ * 임의번호라서 유효한 번호도 false 가 나올 수 있으므로, 유효성 판정에 쓰지 말 것.
+ *
+ * 검증식: 가중치 `[2,3,4,5,6,7,8,9,2,3,4,5]`, `check = (11 − sum%11) % 10`,
+ * **외국인(성별코드 5~8)은 `(check+2) % 10` 보정** 후 13번째 자리와 대조.
+ * 기본 검증({@link isValidRrn}) 불통과 값은 false.
+ */
+declare function rrnChecksumOkLegacy(value: string | null | undefined): boolean;
+/**
+ * 생년월일을 `"YYYY-MM-DD"` 문자열로 추출한다(타임존 함정 차단 — `Date` 미사용).
+ * 세기는 성별코드로 판정. 무효한 번호는 null.
+ */
+declare function rrnBirthDate(value: string | null | undefined): string | null;
+
+/**
+ * 한국어 조사 자동 선택 — 받침 유무에 따라 은/는·이/가 등을 고른다.
+ *
+ * 원천: Java `JosaUtils` / Python `text/josa.py` 와 동일 규칙 (수동 동기화).
+ *
+ * 판정 규칙:
+ * - 끝 공백(스페이스·탭)을 스킵한 마지막 문자로 판정
+ * - 한글 음절 → `jong = (c − 0xAC00) % 28` (0 = 받침 없음)
+ * - 숫자(ASCII 0~9) → 독음 음절(`영일이삼사오육칠팔구`)로 치환 후 동일 판정
+ * - 그 외(영문·기호·빈 문자열) → 병기형 `은(는)/이(가)/을(를)/과(와)/(으)로/아(야)`
+ * - (으)로 특례: 받침 없음 또는 ㄹ 받침(jong==8) → "로", 그 외 받침 → "으로"
+ */
+/** 지원하는 조사 쌍 — 이 6종 외 값은 런타임에서도 RangeError. */
+type JosaPair = "은/는" | "이/가" | "을/를" | "과/와" | "(으)로" | "아/야";
+/**
+ * 단어에 어울리는 조사를 고른다 (조사만 반환).
+ * 판정 불가(영문·기호·빈 문자열)면 병기형(`은(는)` 등)을 반환한다.
+ * 지원하지 않는 조사 쌍은 RangeError.
+ */
+declare function pickJosa(word: string, josa: JosaPair): string;
+/**
+ * 단어 뒤에 어울리는 조사를 붙여 반환한다 (`attachJosa("사과", "은/는")` → `"사과는"`).
+ * 판정에서 스킵한 끝 공백(스페이스·탭)은 출력에서도 제거한다
+ * (`"필드 "` → `"필드는"` — 벡터 JO-12).
+ */
+declare function attachJosa(word: string, josa: JosaPair): string;
+
+/**
+ * 한국식 나이 계산 3종 — 만 나이·연 나이·보험 나이.
+ *
+ * 원천: Java `KoreanAgeUtils` / Python `age.py` 와 동일 규칙 (수동 동기화).
+ *
+ * 입력은 **`"YYYY-MM-DD"` 문자열 고정** (`Date` 객체 금지 — JS Date 의 타임존
+ * 함정 원천 차단). 형식 위반·실존하지 않는 날짜·`기준일 < 생일` 은 RangeError.
+ */
+/**
+ * 만 나이 — 생일이 지나지 않았으면 1 을 뺀다 (민법 기준).
+ * 2/29 생은 평년 3/1 에 증가한다(월·일 튜플 비교 — Java `Period` 시맨틱과 일치).
+ */
+declare function ageMan(birth: string, on: string): number;
+/** 연 나이 — 연도 차이만 계산한다 (청소년 보호법 등의 연 나이). */
+declare function ageByYear(birth: string, on: string): number;
+/**
+ * 보험 나이 — 만 개월수 `m`(당월 일 미도달 시 −1) 기준 `⌊(m+6)/12⌋`.
+ * 생후 6개월이 지난 시점(상령일)마다 한 살씩 올라간다.
+ */
+declare function ageInsurance(birth: string, on: string): number;
+
+/**
+ * 한국 전화번호 정규화·분류·포맷·E.164 변환.
+ *
+ * 원천: Java `PhoneNumberUtils` / Python `phone.py` 와 동일 규칙 (수동 동기화).
+ *
+ * 타입 문자열(`mobile|landline|voip|safe|m2m|unknown`)은 3언어 공유 소문자
+ * 와이어 값이다.
+ *
+ * 로그·화면 노출 권장 경로: `formatPhoneNumber(normalizePhoneNumber(x))` →
+ * `maskPhone`(masking.ts) 파이프라인. maskPhone 은 부분 문자열 단위로 매칭하므로
+ * 형식이 보장되지 않은 원본을 직접 넣지 말고 이 경로로 정형화한 뒤 마스킹할 것.
+ */
+/** 전화번호 분류 — 3언어 공유 소문자 타입 문자열. */
+type PhoneType = "mobile" | "landline" | "voip" | "safe" | "m2m" | "unknown";
+/**
+ * 구분자(하이픈·스페이스·탭·괄호·점)를 제거하고, `+82` 접두는 `0` 을 보충해
+ * 국내 표기로 역변환한다 (`"+82 10-1234-5678"` → `"01012345678"`).
+ * 이미 `0` 으로 시작하는 `+82 010…` 표기는 `0` 을 중복 보충하지 않는다
+ * (Java/Python 동일 규칙). 그 외 문자는 보존한다(분류 단계에서 unknown 처리).
+ */
+declare function normalizePhoneNumber(value: string): string;
+/**
+ * 정규화 후 번호를 분류한다. 표에 없는 패턴·비숫자 포함은 `"unknown"`.
+ * - mobile: 010(11자리), 011/016/017/018/019(10~11자리)
+ * - landline: 02(9~10자리), 지역번호 표(10~11자리)
+ * - voip: 070(11자리) / safe: 050X(11~12자리) / m2m: 012(11~12자리)
+ */
+declare function classifyPhoneNumber(value: string): PhoneType;
+/**
+ * 정규화 후 표준 하이픈 그룹핑으로 포맷한다. 그룹핑 불가(unknown·비표준 길이)면
+ * **정규화 문자열을 그대로 반환**한다 (예외 없음).
+ * - 02: 2-3-4(9자리) / 2-4-4(10자리)
+ * - 3자리 식별번호(이동·지역·070·012 11자리): 3-3-4(10자리) / 3-4-4(11자리)
+ * - 050X: 4-3-4(11자리) / 4-4-4(12자리)
+ */
+declare function formatPhoneNumber(value: string): string;
+/**
+ * E.164(`+82…`) 표기로 변환한다 — 분류 성공 시 선행 `0` 을 떼고 `+82` 를 붙인다.
+ * `"unknown"` 은 null. 역변환(`+82` → `0…`)은 {@link normalizePhoneNumber} 가 담당.
+ */
+declare function toE164(value: string): string | null;
+
+/**
+ * 금액 한글 표기 3종 — 한글 수사·공문서 갖은자 표기·UI 축약.
+ *
+ * 원천: Java `KoreanAmountUtils` / Python `money.py` 와 동일 규칙 (수동 동기화).
+ *
+ * 지원 범위: `|amount| < 10^20` (만·억·조·경). 입력은 `number`(안전 정수) 또는
+ * `bigint` — 비정수·비안전 정수·범위 초과는 RangeError.
+ * 축약은 **내림**을 채택한다(금액 과대 표시 방지).
+ */
+/**
+ * 순수 한글 수사 표기 — `12345678` → `"천이백삼십사만오천육백칠십팔"`.
+ * 그룹 내 1 은 십/백/천 앞에서 생략하고, 그룹값 1 은 "일만/일억" 으로 명시한다.
+ * 0 은 `"영"`, 음수는 `"마이너스 "` 접두.
+ */
+declare function toKoreanWords(amount: number | bigint): string;
+/**
+ * 공문서 위조방지 표기 — `"금" + 전자리 명시 수사(일십·일백·일천 포함) + "원整"`.
+ * `12345678` → `"금일천이백삼십사만오천육백칠십팔원整"`, 0 → `"금영원整"`.
+ * 음수는 RangeError (공문서 금액에 음수 없음).
+ */
+declare function toFormalNotation(amount: number | bigint): string;
+/**
+ * UI 축약 표기 — 소수 1자리 **내림**(금액 과대 표시 방지), `.0` 생략, 정수부 콤마.
+ * - ≥1조 → `"X.Y조"` / ≥1억 → `"X.Y억"` / ≥1만 → 만 단위 내림 콤마 `"N,NNN만"`
+ * - <1만 → 콤마 숫자 그대로(단위·"원" 없음), 음수는 `-` 접두.
+ */
+declare function abbreviateAmount(amount: number | bigint): string;
+
+/**
+ * 영업일 계산기 — 공휴일 데이터 주입형.
+ *
+ * 원천: Java `BusinessDays` / Python `business_days.py` 와 동일 규칙 (수동 동기화).
+ *
+ * **내장 공휴일 테이블은 없다** — 한국 공휴일은 대체공휴일·임시공휴일 등으로
+ * 매년 변하므로 라이브러리에 박제하지 않고 소비자가 주입한다.
+ *
+ * 날짜는 **`"YYYY-MM-DD"` 문자열 고정** (`Date` 객체 금지 — 타임존 함정 차단).
+ * 형식 위반·실존하지 않는 날짜는 RangeError. 내부 요일·가감 연산은 UTC 기준
+ * epoch day 산술이라 실행 환경 타임존의 영향을 받지 않는다.
+ */
+/** 영업일 계산기 — {@link createBusinessDays} 로 생성한다. */
+interface BusinessDays {
+    /** 영업일 여부 — 주말(토·일) 또는 주입된 공휴일이면 false. */
+    isBusinessDay(date: string): boolean;
+    /**
+     * 영업일 n일 가감(n 음수 허용). **n=0 은 입력 날짜 그대로 반환한다(스냅 없음)** —
+     * 비영업일 입력도 그대로.
+     */
+    addBusinessDays(date: string, n: number): string;
+    /** 다음 영업일 (엄격 초과 — 입력이 영업일이어도 그다음을 찾는다). */
+    nextBusinessDay(date: string): string;
+    /** 이전 영업일 (엄격 미만). */
+    previousBusinessDay(date: string): string;
+    /** 반개구간 `[start, endExclusive)` 의 영업일 수. `start > end` 는 RangeError. */
+    countBusinessDays(start: string, endExclusive: string): number;
+}
+interface BusinessDaysOptions {
+    /** 공휴일 목록 — `"YYYY-MM-DD"` 문자열 (불변 복사). */
+    holidays: Iterable<string>;
+}
+/**
+ * 공휴일을 주입해 영업일 계산기를 만든다.
+ *
+ * ```ts
+ * const bd = createBusinessDays({ holidays: ["2026-01-01"] });
+ * bd.addBusinessDays("2025-12-31", 1); // "2026-01-02" — 1/1 스킵
+ * ```
+ */
+declare function createBusinessDays(options: BusinessDaysOptions): BusinessDays;
+
+/**
+ * 한글 자모 분해·결합 + 혼합 질의 전방일치 매처.
+ *
+ * 원천: Java `HangulUtils` / Python `text/jamo.py` 와 동일 규칙 (수동 동기화).
+ * 초성만 뽑는 기존 `chosung.ts`(무변경·하위호환)와 별개 모듈이다.
+ *
+ * 분해 정책(확정): **두벌식 키보드 자모열** — 초성·중성·종성을 호환 자모
+ * (U+3131~U+3163)로 펼치되,
+ * - 복합 모음 분해: ㅘ→ㅗㅏ, ㅙ→ㅗㅐ, ㅚ→ㅗㅣ, ㅝ→ㅜㅓ, ㅞ→ㅜㅔ, ㅟ→ㅜㅣ, ㅢ→ㅡㅣ
+ * - 겹받침 분해: ㄳ→ㄱㅅ, ㄵ→ㄴㅈ, ㄶ→ㄴㅎ, ㄺ→ㄹㄱ, ㄻ→ㄹㅁ, ㄼ→ㄹㅂ,
+ *   ㄽ→ㄹㅅ, ㄾ→ㄹㅌ, ㄿ→ㄹㅍ, ㅀ→ㄹㅎ, ㅄ→ㅂㅅ
+ * - **쌍자음(ㄲㄸㅃㅆㅉ·종성 ㄲㅆ)은 분해하지 않는다**(시프트 입력 = 단일 타건)
+ * - 완성 음절이 아닌 문자(비한글·단독 자모)는 그대로 통과 — 단독 복합 자모
+ *   (ㅘ·ㄳ 등)도 분해하지 않는다 (Java/Python 동일 정책)
+ *
+ * 결합은 역변환(왼쪽부터 탐욕) — 완성 음절 입력 기준 `compose(decompose(s)) == s`
+ * 왕복이 보장된다. 음절을 이루지 못하는 자모는 그대로 출력한다.
+ */
+/**
+ * 문자열을 두벌식 키보드 자모열로 분해한다 (`"값"` → `"ㄱㅏㅂㅅ"`).
+ * 완성 음절은 초·중·종성으로, 복합 모음·겹받침은 구성 자모로 펼친다.
+ * 쌍자음은 분해하지 않고, 완성 음절이 아닌 문자(비한글·단독 자모)는 그대로
+ * 통과한다 (Java `HangulUtils.decompose` / Python `jamo.decompose` 동일 정책).
+ */
+declare function decomposeHangul(s: string): string;
+/**
+ * 자모열을 완성 음절로 결합한다 — {@link decomposeHangul} 의 역변환(왼쪽부터 탐욕).
+ * 초성→중성(다음 모음과 복합 결합 시도)→종성(다음 문자가 모음이면 초성으로 양보,
+ * 겹받침 결합 후에도 다음이 모음이면 둘째를 양보) 순으로 채운다.
+ * 음절을 이루지 못하는 자모·비한글 문자는 그대로 출력한다.
+ */
+declare function composeHangul(s: string): string;
+/**
+ * 혼합 질의 전방일치 매처 — 완성 음절·단독 자음·진행 중 음절이 섞인 질의가
+ * 대상의 접두인지 판정한다 (`matchesHangul("ㅎ길", "홍길동")` → true).
+ *
+ * - 마지막이 아닌 질의 문자: 완성 음절은 대상과 정확 일치, 단독 자음(ㄱ~ㅎ)은
+ *   대상 음절의 초성 일치, 비한글은 소문자화 후 비교(toChosung 관례)
+ * - 마지막 질의 문자: **자모열 전방일치** — `decompose(질의)` 가
+ *   `decompose(대상)` 의 접두면 매치 (`"셔"`→`"션"`, `"ㄷ"`→`"동"` 커버)
+ * - 빈 질의는 true, 질의가 대상보다 길면 false
+ */
+declare function matchesHangul(query: string, target: string): boolean;
+
+export { type ApiClient, type ApiClientConfig, type ApiClientRetryOptions, ApiError, type ApiErrorInfo, type ApiRequestInfo, type ApiResponseInfo, type ApiResult, type BulkResult, type BulkResultBuilder, type BulkResultItem, type Bulkhead, BulkheadFullError, type BulkheadOptions, type BusinessDays, type BusinessDaysOptions, type CircuitBreaker, type CircuitBreakerOptions, type CircuitState, type CommonResponse, type FeatureFlagReader, type FieldErrorDetail, type FileKind, type JosaPair, type ListQueryOptions, type PageResponse, type PhoneType, ResultCode, type RetryOptions, type SortParam, type SseCallbacks, type SseFrameEvent, type SseSource, type TokenBucket, type TokenBucketOptions, type TtlCache, type TtlCacheOptions, type UploadValidationResult, type ValidationErrorData, WEBHOOK_SIGNATURE_HEADER, abbreviateAmount, ageByYear, ageInsurance, ageMan, attachJosa, buildListQuery, bulkFailures, classifyPhoneNumber, composeHangul, createApiClient, createBulkResultBuilder, createBulkhead, createBusinessDays, createCircuitBreaker, createFeatureFlags, createTokenBucket, createTtlCache, decodeJwtPayload, decomposeHangul, formatPhoneNumber, generateIdempotencyKey, getTokenExpiry, isBulkResult, isChosungQuery, isForeignerRrn, isRetryableStatus, isTokenExpired, isValidBusinessNumber, isValidCorporateNumber, isValidRrn, isValidationErrorData, kindsForExtension, maskCardNumber, maskEmail, maskName, maskPhone, maskSecret, matchesHangul, normalizeBusinessNumber, normalizePhoneNumber, normalizeRrn, parseFlag, parseRetryAfterMs, parseSseFrame, parseWireDateTime, pickJosa, readSseStream, retry, rrnBirthDate, rrnChecksumOkLegacy, sanitizeLogValue, signWebhook, sniffFile, stripZone, toChosung, toE164, toFormalNotation, toKoreanWords, toWireDate, toWireDateTime, validateUpload, verifyWebhook };