apick-api 3.2.0 → 3.4.1

package/CHANGELOG.md

@@ -1,77 +1,104 @@
 # Changelog
 
-## 3.2.0 — 2026-09-14
-
-- Seedance 참조 영상 작업에 `referenceAudios`(MP3·WAV) 입력을 추가했습니다.
-- Add video generation version selection documentation and compatibility tests.
-- 영상 생성 버전 선택, 버전별 옵션·요금 안내와 호환 검증을 추가했습니다.
-- Add createVideoJob, getVideoJob, downloadVideoResult and public TypeScript types.
-- Document and verify Seedance 2.0 Fast and Mini tier pass-through.
-
-## 3.1.0 - 2026-09-08
-
-- TTS 발화별 검수 이력, 후보 WAV 조회, 멱등 키를 사용하는 같은 작업 재개 메서드를 추가했습니다.
-- Added TTS quality history, candidate WAV downloads, and idempotent job recovery methods.
-
-## 3.0.0 - 2026-09-05
-
-- 이미지 프롬프트 허용 길이를 최대 28,000자로 확대했습니다.
-- 작업 접수 시 전체 포인트를 먼저 차감하고 실패한 이미지의 포인트를 즉시 환급하는 계약을 반영했습니다.
-- 접수된 이미지 작업은 취소할 수 없도록 `cancelImageJob` 메서드와 `cancelled` 상태를 제거했습니다.
-
-## 2.4.0 - 2026-09-05
-
-- 이미지 장수 옵션을 의미가 분명한 `imageCount`로 바꾸고 압축 조정 옵션을 제거했습니다.
-- 이미지 크기를 5개 표준 크기 중에서만 선택하도록 타입과 런타임 검증을 강화했습니다.
-- 생성 요청에 선택적 `referenceImage`를 더해 참고 이미지와 텍스트를 함께 사용할 수 있습니다.
-
-## 2.3.1 - 2026-09-05
-
-- 이미지 편집 입력에서 마스크 파일을 제거하고 원본 이미지와 프롬프트만 받도록 계약을 단순화했습니다.
-
-## 2.3.0 - 2026-09-05
-
-- 이미지 생성·편집과 최대 50장 비동기 작업 메서드 8종을 추가했습니다.
-- 이미지당 25포인트, 성공분 과금, 멱등 키, 24시간 결과 보관 계약을 문서화했습니다.
-
-## 2.2.0 - 2026-09-03
-
-- `maskResidenceCard()`의 개인정보 마스킹 대상을 외국인등록증·영주증·외국국적동포 국내거소신고증으로 확대했습니다.
-- 요청·응답 형식과 `document_type: residence_card` 계약은 유지합니다.
-- 진위확인 API의 지원 범위는 기존 외국인등록증으로 유지됩니다.
-
-## 2.1.0 - 2026-09-01
-
-- `downloadTtsSubtitles(jobId)`로 발화 타이밍 ASS 자막을 별도 1회 다운로드할 수 있습니다.
-- TTS 상태 타입에 `subtitles_available`을 추가했습니다.
-- 허용 IP 공란, 단일 IPv4·CIDR 등록, 즉시 반영 규칙을 한영 문서에 추가했습니다.
-
-## 2.0.1 - 2026-08-31
-
-- TTS 작업 취소 범위를 `waiting`과 `processing` 상태로 확장했습니다.
-- 실행 중 취소도 접수 시 과금된 금액을 환불하지 않는 계약을 한영 문서에 반영했습니다.
-- 17개 TTS `voice_id`의 사용자 표시 이름을 공개 문서에 추가했습니다.
-
-## 2.0.0 - 2026-08-30
-
-- 종료된 동기 `textToSpeech()` 계약을 제거했습니다.
-- `createTtsJob()`, `getTtsJob()`, `cancelTtsJob()`, `downloadTtsResult()`로 비동기 한국어 TTS Jobs 계약을 제공합니다.
-- 지원 목소리, 최대 800자, 상태 조회, 대기 중 취소, 결과 MP3(`audio/mpeg`) 1회 다운로드를 문서화했습니다.
-- 정식 게시 전 지원 목소리를 17개 중립 내레이션 음성으로 확장하고 `TTS_VOICE_IDS`를 추가했습니다.
-
-## 1.1.1 - 2026-08-30
-
-- 공개된 25개 API 계약에 종료 대상 이미지 생성 기능이 포함되지 않았음을 재검증했습니다.
-- 기능 및 메서드 호환성 변경 없이 릴리스 메타데이터를 갱신했습니다.
-
-## 1.1.0 - 2026-08-29
-
-- 주민등록번호, 외국인등록증, 여권, 주민등록증, 운전면허증 마스킹 메서드 5종을 추가했습니다.
-- 신분증 처리 오류 코드를 `ApickApiError.serviceCode`로 제공합니다.
-
-## 1.0.0
-
-- Initial public release.
-- Added 20 focused APICK service methods.
-- Added JSON, multipart image upload, and binary file response support.
-- Added ESM, CommonJS, and TypeScript declarations.
+## 3.4.1 — 2026-09-28
+
+- README와 한국어·영어 가이드의 간편인증 5종 예제에 모든 진행 상태와 `resultAvailable` 종료 기준을 적용했습니다. 전체·부분 성공, 인증 거부·만료·실패와 `RESULT_EXPIRED`를 구분합니다.
+- Align all five simple-auth polling examples in the README and Korean/English guides with every progress state and the `resultAvailable` completion criterion. Distinguish full/partial success, rejected/expired authentication, failure, and `RESULT_EXPIRED`.
+- 순차 폴링 간격을 5→10→20→30초로 늘린 뒤 30초를 유지하며, 인증·전체 대기시간 제한과 자동 재접수 방지를 안내합니다. 문서 코드를 직접 실행하는 회귀 테스트를 추가했습니다.
+- Document sequential polling at 5→10→20→30 seconds, capped at 30 seconds, with authentication/overall waiting limits and no automatic resubmission. Add regression tests that execute the documentation examples.
+
+## 3.4.0 — 2026-09-27
+
+- 간편인증 기반 조회 상품 5종(재직·보험료 확인, 금융소득 조회, 국민연금 가입내역, 운전면허 조회, 국가 건강검진 결과)을 추가했습니다. 각 상품은 `request*()`로 본인 간편인증을 접수하고 `get*()`로 상태·결과를 폴링합니다.
+- Add five simple-auth-based data lookup products (employment/insurance premium check, financial income, National Pension join history, driver's license, national health checkup). Each product accepts a `request*()` call for identity verification and polls status/result with `get*()`.
+- `AUTH_PROVIDERS`(13종 간편인증 수단)와 `AuthProvider`, `DataRequestAcceptedData`, `DataRequestResult<T>` 타입, 상품별 결과 타입(`EmploymentResultPayload` 등)을 공개했습니다.
+- Export `AUTH_PROVIDERS` (13 supported simple-auth providers), the `AuthProvider` type, `DataRequestAcceptedData`/`DataRequestResult<T>` envelopes, and per-product result payload types (e.g. `EmploymentResultPayload`).
+- 재조회 만료(`RESULT_EXPIRED`)·인증 만료·거절·수집 실패는 `data.errorCode`로 구분됩니다.
+- `RESULT_EXPIRED`, `AUTH_EXPIRED`, `AUTH_REJECTED`, and `COLLECT_FAILED` are surfaced through `data.errorCode`.
+
+## 3.3.0 — 2026-09-21
+
+- 모든 REST 요청의 인증 헤더를 `CL_AUTH_KEY` 에서 표준 `Authorization: Bearer <API 키>` 로 전환했습니다. 서버가 전환 기간 동안 두 헤더를 모두 받으므로 기존 호출도 계속 동작합니다.
+- Send REST requests with the standard `Authorization: Bearer <API key>` header instead of `CL_AUTH_KEY`. Both headers are accepted during the migration window.
+- Mask bearer tokens in error output alongside the legacy header.
+- Synchronize all 16 current TTS voice IDs and masking type 4 with the public REST contract.
+
+- Send all REST request bodies as multipart/form-data, including flattened nested arrays and objects. Keep existing method signatures and JSON/file responses.
+- REST 요청을 multipart/form-data로 통일하고 중첩 입력·파일·불리언의 호환 테스트를 추가했습니다. 기존 메서드와 응답 타입은 유지합니다.
+- Document OpenAPI/Postman downloads and compatibility with older JSON callers.
+
+## 3.2.0 — 2026-09-14
+
+- Seedance 참조 영상 작업에 `referenceAudios`(MP3·WAV) 입력을 추가했습니다.
+- Add video generation version selection documentation and compatibility tests.
+- 영상 생성 버전 선택, 버전별 옵션·요금 안내와 호환 검증을 추가했습니다.
+- Add createVideoJob, getVideoJob, downloadVideoResult and public TypeScript types.
+- Document and verify Seedance 2.0 Fast and Mini tier pass-through.
+
+## 3.1.0 - 2026-09-08
+
+- TTS 발화별 검수 이력, 후보 WAV 조회, 멱등 키를 사용하는 같은 작업 재개 메서드를 추가했습니다.
+- Added TTS quality history, candidate WAV downloads, and idempotent job recovery methods.
+
+## 3.0.0 - 2026-09-05
+
+- 이미지 프롬프트 허용 길이를 최대 28,000자로 확대했습니다.
+- 작업 접수 시 전체 포인트를 먼저 차감하고 실패한 이미지의 포인트를 즉시 환급하는 계약을 반영했습니다.
+- 접수된 이미지 작업은 취소할 수 없도록 `cancelImageJob` 메서드와 `cancelled` 상태를 제거했습니다.
+
+## 2.4.0 - 2026-09-05
+
+- 이미지 장수 옵션을 의미가 분명한 `imageCount`로 바꾸고 압축 조정 옵션을 제거했습니다.
+- 이미지 크기를 5개 표준 크기 중에서만 선택하도록 타입과 런타임 검증을 강화했습니다.
+- 생성 요청에 선택적 `referenceImage`를 더해 참고 이미지와 텍스트를 함께 사용할 수 있습니다.
+
+## 2.3.1 - 2026-09-05
+
+- 이미지 편집 입력에서 마스크 파일을 제거하고 원본 이미지와 프롬프트만 받도록 계약을 단순화했습니다.
+
+## 2.3.0 - 2026-09-05
+
+- 이미지 생성·편집과 최대 50장 비동기 작업 메서드 8종을 추가했습니다.
+- 이미지당 25포인트, 성공분 과금, 멱등 키, 24시간 결과 보관 계약을 문서화했습니다.
+
+## 2.2.0 - 2026-09-03
+
+- `maskResidenceCard()`의 개인정보 마스킹 대상을 외국인등록증·영주증·외국국적동포 국내거소신고증으로 확대했습니다.
+- 요청·응답 형식과 `document_type: residence_card` 계약은 유지합니다.
+- 진위확인 API의 지원 범위는 기존 외국인등록증으로 유지됩니다.
+
+## 2.1.0 - 2026-09-01
+
+- `downloadTtsSubtitles(jobId)`로 발화 타이밍 ASS 자막을 별도 1회 다운로드할 수 있습니다.
+- TTS 상태 타입에 `subtitles_available`을 추가했습니다.
+- 허용 IP 공란, 단일 IPv4·CIDR 등록, 즉시 반영 규칙을 한영 문서에 추가했습니다.
+
+## 2.0.1 - 2026-08-31
+
+- TTS 작업 취소 범위를 `waiting`과 `processing` 상태로 확장했습니다.
+- 실행 중 취소도 접수 시 과금된 금액을 환불하지 않는 계약을 한영 문서에 반영했습니다.
+- 17개 TTS `voice_id`의 사용자 표시 이름을 공개 문서에 추가했습니다.
+
+## 2.0.0 - 2026-08-30
+
+- 종료된 동기 `textToSpeech()` 계약을 제거했습니다.
+- `createTtsJob()`, `getTtsJob()`, `cancelTtsJob()`, `downloadTtsResult()`로 비동기 한국어 TTS Jobs 계약을 제공합니다.
+- 지원 목소리, 최대 800자, 상태 조회, 대기 중 취소, 결과 MP3(`audio/mpeg`) 1회 다운로드를 문서화했습니다.
+- 정식 게시 전 지원 목소리를 17개 중립 내레이션 음성으로 확장하고 `TTS_VOICE_IDS`를 추가했습니다.
+
+## 1.1.1 - 2026-08-30
+
+- 공개된 25개 API 계약에 종료 대상 이미지 생성 기능이 포함되지 않았음을 재검증했습니다.
+- 기능 및 메서드 호환성 변경 없이 릴리스 메타데이터를 갱신했습니다.
+
+## 1.1.0 - 2026-08-29
+
+- 주민등록번호, 외국인등록증, 여권, 주민등록증, 운전면허증 마스킹 메서드 5종을 추가했습니다.
+- 신분증 처리 오류 코드를 `ApickApiError.serviceCode`로 제공합니다.
+
+## 1.0.0
+
+- Initial public release.
+- Added 20 focused APICK service methods.
+- Added JSON, multipart image upload, and binary file response support.
+- Added ESM, CommonJS, and TypeScript declarations.

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 APICK
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2026 APICK
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.