apick-api 3.4.0 → 3.5.0

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## 3.5.0 — 2026-09-30
+
+- 간편인증 조회 상품 2종을 추가했습니다. `requestCashReceiptDeduction()`/`getCashReceiptDeduction()`은 현금영수증 소득공제 내역을 `incomeYears`(1~3)로, `requestTaxReturnHistory()`/`getTaxReturnHistory()`는 국세 신고내역을 `years`(1~10)로 조회합니다.
+- Add two simple-auth data products: cash receipt income deductions (`incomeYears` 1-3) and national tax return history (`years` 1-10), each with a `request*()`/`get*()` pair and result payload types.
+- 유튜브 공개 영상 API 4종을 추가했습니다: `youtubeMetadata()`, `youtubeThumbnail()`(JPG), `youtubeSubtitleList()`, `youtubeSubtitle()`(VTT·SRT·TXT).
+- Add four public YouTube video methods: metadata, thumbnail (JPG), subtitle language list, and subtitle download (VTT/SRT/TXT).
+
+## 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*()`로 상태·결과를 폴링합니다.

package/README.md

@@ -71,6 +71,10 @@ Leave the allowed-IP list blank for unrestricted access. To restrict access, reg
 | `googleSearch(keyword, options)` | 웹 검색 / Web search | JSON |
 | `googleImageSearch(keyword, options)` | 이미지 검색 / Image search | JSON |
 | `screenshot(url)` | 웹페이지 화면캡처 / Web screenshot | Binary |
+| `youtubeMetadata(url)` | 유튜브 영상 정보 / YouTube video metadata | JSON |
+| `youtubeThumbnail(url)` | 유튜브 썸네일 / YouTube thumbnail | JPG |
+| `youtubeSubtitleList(url)` | 유튜브 자막 언어 목록 / YouTube subtitle languages | JSON |
+| `youtubeSubtitle(url, lang, options)` | 유튜브 자막 다운로드 / YouTube subtitles | VTT·SRT·TXT |
 | `createTtsJob(text, options)` | 한국어 내레이션 작업 접수 / Create TTS job | JSON |
 | `getTtsJob(jobId)` | TTS 작업 상태 / TTS job status | JSON |
 | `cancelTtsJob(jobId)` | 대기·생성 중 TTS 작업 취소 / Cancel waiting or processing TTS job | JSON |
@@ -95,6 +99,8 @@ Leave the allowed-IP list blank for unrestricted access. To restrict access, reg
 | `requestNpsJoinHistory(input)` / `getNpsJoinHistory(transactionId)` | 국민연금 가입내역조회 / National Pension join history | JSON |
 | `requestDrivingLicense(input)` / `getDrivingLicense(transactionId)` | 운전면허 조회 / Driver's license check | JSON |
 | `requestHealthCheckup(input)` / `getHealthCheckup(transactionId)` | 국가 건강검진 결과 조회 / National health checkup results | JSON |
+| `requestCashReceiptDeduction(input)` / `getCashReceiptDeduction(transactionId)` | 현금영수증 소득공제 내역 / Cash receipt income deductions | JSON |
+| `requestTaxReturnHistory(input)` / `getTaxReturnHistory(transactionId)` | 국세 신고내역 조회 / National tax return history | JSON |
 
 ## JSON 결과 / JSON results
 
@@ -237,32 +243,86 @@ The four document-specific methods return JSON. `maskResidentNumber` returns PNG
 
 ## 간편인증 기반 데이터 조회 / Simple-auth data lookups
 
-본인 간편인증이 필요한 조회 상품(재직·소득·연금·면허·건강검진)은 접수(`request*`)와 결과 조회(`get*`)가 분리되어 있습니다. 접수 응답의 `transactionId`로 결과를 폴링하세요.
+본인 간편인증이 필요한 조회 상품(재직·소득·연금·면허·건강검진·현금영수증·국세 신고내역)은 접수(`request*`)와 결과 조회(`get*`)가 분리되어 있습니다. 접수 응답의 `transactionId`로 결과를 폴링하세요.
 
-Products that require the user's own simple-auth verification (employment, income, pension, driver's license, health checkup) split the call into a `request*()` acceptance and a `get*()` poll. Use the `transactionId` from the accepted response to poll for the result.
+Products that require the user's own simple-auth verification (employment, income, pension, driver's license, health checkup, cash receipts, tax returns) split the call into a `request*()` acceptance and a `get*()` poll. Use the `transactionId` from the accepted response to poll for the result.
 
+아래 함수는 7종 모두에 공통으로 사용합니다. 같은 `transactionId`로 순차 조회하며 5→10→20→30초 간격으로 늘린 뒤 30초를 유지합니다. `resultAvailable === true`이면 즉시 결과를 반환합니다. `SUCCESS`는 전체 성공, `PARTIAL_SUCCESS`는 부분 성공이므로 `sources`에서 누락·실패 항목을 확인하세요. `AUTH_REJECTED`·`AUTH_EXPIRED`·`FAILED`는 실패 종료이며, `errorCode: 'RESULT_EXPIRED'`는 결과 보관 기간 만료입니다. 실패·만료 시 자동으로 재접수하지 않습니다.
+
+Use this helper for all seven products. Poll sequentially with the same `transactionId`, waiting 5→10→20→30 seconds and then keeping the 30-second interval. Return the result immediately when `resultAvailable === true`. `SUCCESS` means full success; `PARTIAL_SUCCESS` means partial success, so inspect `sources` for missing or failed items. `AUTH_REJECTED`, `AUTH_EXPIRED`, and `FAILED` are terminal failures; `errorCode: 'RESULT_EXPIRED'` means the retained result has expired. Never resubmit automatically after failure or expiry.
+
+<!-- simple-auth-polling:start -->
+```js
+async function pollDataResult(getResult, accepted, { timeoutMs = 600_000 } = {}) {
+  const pending = new Set([
+    'AUTH_REQUESTED', 'AUTH_WAITING', 'AUTH_COMPLETED', 'COLLECTING', 'COLLECTED'
+  ]);
+  const failed = new Set(['AUTH_REJECTED', 'AUTH_EXPIRED', 'FAILED']);
+  const completed = new Set(['SUCCESS', 'PARTIAL_SUCCESS']);
+  const delays = [5_000, 10_000, 20_000, 30_000];
+  const deadline = Date.now() + timeoutMs;
+  const transactionId = accepted.data.transactionId;
+  const stop = code => { throw Object.assign(new Error(code), { code }); };
+  let response = accepted;
+  let attempt = 0;
+
+  for (;;) {
+    const data = response.data;
+    if (data.errorCode === 'RESULT_EXPIRED') stop('RESULT_EXPIRED');
+    if (failed.has(data.status)) stop(data.errorCode || data.status);
+    if (data.resultAvailable === true) {
+      if (data.result == null) stop('INVALID_RESULT');
+      return response;
+    }
+    if (completed.has(data.status)) stop('RESULT_NOT_AVAILABLE');
+    if (!pending.has(data.status)) stop('UNKNOWN_STATUS');
+
+    const awaitingApproval = ['AUTH_REQUESTED', 'AUTH_WAITING'].includes(data.status);
+    const authDeadline = Date.parse(data.expiresAt || accepted.data.expiresAt);
+    const limit = awaitingApproval && Number.isFinite(authDeadline)
+      ? Math.min(deadline, authDeadline) : deadline;
+    const timeoutCode = awaitingApproval && limit === authDeadline
+      ? 'AUTH_WAIT_TIMEOUT' : 'CLIENT_POLL_TIMEOUT';
+    const remaining = limit - Date.now();
+    if (remaining <= 0) stop(timeoutCode);
+    await new Promise(resolve => setTimeout(resolve,
+      Math.min(delays[Math.min(attempt++, delays.length - 1)], remaining)));
+    if (Date.now() >= limit) stop(timeoutCode);
+    response = await getResult(transactionId);
+  }
+}
+```
+<!-- simple-auth-polling:end -->
+
+`AUTH_REQUESTED`·`AUTH_WAITING`은 사용자 승인을 기다리고, `AUTH_COMPLETED`·`COLLECTING`·`COLLECTED`는 결과가 준비될 때까지 계속 조회합니다. 과금 여부(`charged`, `success`)는 완료 기준이 아닙니다. 인증 대기에만 `expiresAt`을 적용하고 승인 후에는 전체 대기 한도를 적용합니다. 예제의 10분 한도는 클라이언트 정책이며, 진행 중인 호출의 제한 시간은 SDK의 `timeoutMs`로 별도 설정하세요. `AUTH_WAIT_TIMEOUT`·`CLIENT_POLL_TIMEOUT`·`RESULT_NOT_AVAILABLE`·`INVALID_RESULT`·`UNKNOWN_STATUS`는 예제에서 만드는 로컬 오류로, 응답 모순이나 알 수 없는 상태에서 무한 반복하지 않습니다. 통신 오류도 재시도 없이 호출자에게 전달합니다.
+
+`AUTH_REQUESTED` and `AUTH_WAITING` wait for the user's approval; `AUTH_COMPLETED`, `COLLECTING`, and `COLLECTED` keep polling until a result is available. Billing fields (`charged`, `success`) do not indicate completion. Apply `expiresAt` only while awaiting approval, then use the overall waiting limit. The example's 10-minute limit is a client policy; configure the SDK's `timeoutMs` separately to bound each in-flight call. `AUTH_WAIT_TIMEOUT`, `CLIENT_POLL_TIMEOUT`, `RESULT_NOT_AVAILABLE`, `INVALID_RESULT`, and `UNKNOWN_STATUS` are local example errors that prevent endless polling on inconsistent responses or unknown states. Transport errors propagate without retries.
+
+<!-- simple-auth-usage:start -->
 ```js
 const accepted = await apick.requestEmployment({
   name: '홍길동',
   birthDate: '19900101',
   phone: '01011112222',
-  authProvider: 'kakao', // AUTH_PROVIDERS 참고 / see AUTH_PROVIDERS
+  authProvider: 'kakao',
   insuranceYears: 3
 });
-const transactionId = accepted.data.transactionId;
-
-let result;
-do {
-  await new Promise(resolve => setTimeout(resolve, 3000));
-  result = await apick.getEmployment(transactionId);
-} while (result.data.status === 'AUTH_WAITING' || result.data.status === 'COLLECTING');
 
-if (result.data.status === 'SUCCESS' || result.data.status === 'PARTIAL_SUCCESS') {
-  console.log(result.data.result.employment);
-} else {
-  console.log(result.data.errorCode); // AUTH_EXPIRED | AUTH_REJECTED | COLLECT_FAILED
+try {
+  const result = await pollDataResult(id => apick.getEmployment(id), accepted);
+  if (result.data.status === 'PARTIAL_SUCCESS') console.warn(result.data.sources);
+  console.log(result.data.result);
+} catch (error) {
+  if ((error.serviceCode || error.code) === 'RESULT_EXPIRED') {
+    console.error('결과 보관 기간 만료: 사용자 확인 후 새 인증을 요청하세요.');
+  } else {
+    throw error;
+  }
 }
 ```
+<!-- simple-auth-usage:end -->
+
+근거: [APICK 개발가이드](https://apick.app/dev_guide/data_health_checkup) · [MCP 3.5.0 상태 계약](https://github.com/lead788/apick-mcp/blob/a803abcb81d07377c85f49bb0b670baf0c17ed04/TOOLS.md)
 
 지원 간편인증 방식(`authProvider`) 13종은 `AUTH_PROVIDERS`로 제공됩니다: `kakao`, `naver`, `toss`, `pass`, `samsung`, `kb`, `shinhan`, `hana`, `woori`, `ibk`, `nh`, `kakaobank`, `banksalad`.
 The 13 supported `authProvider` values are exported as `AUTH_PROVIDERS`: `kakao`, `naver`, `toss`, `pass`, `samsung`, `kb`, `shinhan`, `hana`, `woori`, `ibk`, `nh`, `kakaobank`, `banksalad`.
@@ -277,6 +337,8 @@ Acceptance is billed at a flat rate; the result is billed only on its first succ
 | 국민연금 가입내역 / NPS join history | `requestNpsJoinHistory` / `getNpsJoinHistory` | `from`, `to` (`YYYY-MM`) |
 | 운전면허 조회 / Driver's license | `requestDrivingLicense` / `getDrivingLicense` | — |
 | 국가 건강검진 결과 / Health checkup | `requestHealthCheckup` / `getHealthCheckup` | — |
+| 현금영수증 소득공제 내역 / Cash receipt deductions | `requestCashReceiptDeduction` / `getCashReceiptDeduction` | `incomeYears` (1–3) |
+| 국세 신고내역 조회 / Tax return history | `requestTaxReturnHistory` / `getTaxReturnHistory` | `years` (1–10) |
 
 ## 오류 처리 / Error handling
 

package/docs/guide.en.md

@@ -94,6 +94,13 @@ TTS supports 16 voice IDs. Use `TTS_VOICE_IDS` and the developer guide for the c
 const screenshot = await client.screenshot('https://example.com');
 await screenshot.save('./example.jpeg');
 
+// Public YouTube videos: a video URL or the 11-character video ID
+const video = await client.youtubeMetadata('https://www.youtube.com/watch?v=dQw4w9WgXcQ');
+const tracks = await client.youtubeSubtitleList(video.data.video_id);
+const subtitle = await client.youtubeSubtitle(video.data.video_id, 'en', { format: 'srt' });
+await subtitle.save('./' + subtitle.filename);
+await (await client.youtubeThumbnail(video.data.video_id)).save('./thumbnail.jpg');
+
 const created = await client.createTtsJob('오늘의 이야기를 시작합니다.', { voiceId: 'v2_ann_m_30s_01' });
 const jobId = created.data.job_id;
 let job = await client.getTtsJob(jobId);
@@ -187,8 +194,56 @@ The document-specific methods are `maskResidenceCard`, `maskPassport`, `maskIdCa
 
 ## Simple-auth data lookups
 
-Employment, income, pension, driver's license, and health checkup lookups require the user's own simple-auth verification, so the call is split into acceptance (`request*`) and result polling (`get*`).
+Employment, income, pension, driver's license, health checkup, cash receipt deduction, and tax return history lookups require the user's own simple-auth verification, so the call is split into acceptance (`request*`) and result polling (`get*`).
+
+Use this helper for all seven products. Poll sequentially with the same `transactionId`, waiting 5→10→20→30 seconds and then keeping the 30-second interval. Return the result immediately when `resultAvailable === true`. `SUCCESS` means full success; `PARTIAL_SUCCESS` means partial success, so inspect `sources` for missing or failed items. `AUTH_REJECTED`, `AUTH_EXPIRED`, and `FAILED` are terminal failures; `errorCode: 'RESULT_EXPIRED'` means the retained result has expired. Never resubmit automatically after failure or expiry.
+
+<!-- simple-auth-polling:start -->
+```js
+async function pollDataResult(getResult, accepted, { timeoutMs = 600_000 } = {}) {
+  const pending = new Set([
+    'AUTH_REQUESTED', 'AUTH_WAITING', 'AUTH_COMPLETED', 'COLLECTING', 'COLLECTED'
+  ]);
+  const failed = new Set(['AUTH_REJECTED', 'AUTH_EXPIRED', 'FAILED']);
+  const completed = new Set(['SUCCESS', 'PARTIAL_SUCCESS']);
+  const delays = [5_000, 10_000, 20_000, 30_000];
+  const deadline = Date.now() + timeoutMs;
+  const transactionId = accepted.data.transactionId;
+  const stop = code => { throw Object.assign(new Error(code), { code }); };
+  let response = accepted;
+  let attempt = 0;
+
+  for (;;) {
+    const data = response.data;
+    if (data.errorCode === 'RESULT_EXPIRED') stop('RESULT_EXPIRED');
+    if (failed.has(data.status)) stop(data.errorCode || data.status);
+    if (data.resultAvailable === true) {
+      if (data.result == null) stop('INVALID_RESULT');
+      return response;
+    }
+    if (completed.has(data.status)) stop('RESULT_NOT_AVAILABLE');
+    if (!pending.has(data.status)) stop('UNKNOWN_STATUS');
+
+    const awaitingApproval = ['AUTH_REQUESTED', 'AUTH_WAITING'].includes(data.status);
+    const authDeadline = Date.parse(data.expiresAt || accepted.data.expiresAt);
+    const limit = awaitingApproval && Number.isFinite(authDeadline)
+      ? Math.min(deadline, authDeadline) : deadline;
+    const timeoutCode = awaitingApproval && limit === authDeadline
+      ? 'AUTH_WAIT_TIMEOUT' : 'CLIENT_POLL_TIMEOUT';
+    const remaining = limit - Date.now();
+    if (remaining <= 0) stop(timeoutCode);
+    await new Promise(resolve => setTimeout(resolve,
+      Math.min(delays[Math.min(attempt++, delays.length - 1)], remaining)));
+    if (Date.now() >= limit) stop(timeoutCode);
+    response = await getResult(transactionId);
+  }
+}
+```
+<!-- simple-auth-polling:end -->
+
+`AUTH_REQUESTED` and `AUTH_WAITING` wait for the user's approval; `AUTH_COMPLETED`, `COLLECTING`, and `COLLECTED` keep polling until a result is available. Billing fields (`charged`, `success`) do not indicate completion. Apply `expiresAt` only while awaiting approval, then use the overall waiting limit. The example's 10-minute limit is a client policy; configure the SDK's `timeoutMs` separately to bound each in-flight call. `AUTH_WAIT_TIMEOUT`, `CLIENT_POLL_TIMEOUT`, `RESULT_NOT_AVAILABLE`, `INVALID_RESULT`, and `UNKNOWN_STATUS` are local example errors that prevent endless polling on inconsistent responses or unknown states. Transport errors propagate without retries.
 
+<!-- simple-auth-usage:start -->
 ```js
 const accepted = await client.requestDrivingLicense({
   name: 'Hong Gildong',
@@ -197,14 +252,23 @@ const accepted = await client.requestDrivingLicense({
   authProvider: 'kakao'
 });
 
-let result;
-do {
-  await new Promise(resolve => setTimeout(resolve, 3000));
-  result = await client.getDrivingLicense(accepted.data.transactionId);
-} while (result.data.status === 'AUTH_WAITING' || result.data.status === 'COLLECTING');
+try {
+  const result = await pollDataResult(id => client.getDrivingLicense(id), accepted);
+  if (result.data.status === 'PARTIAL_SUCCESS') console.warn(result.data.sources);
+  console.log(result.data.result);
+} catch (error) {
+  if ((error.serviceCode || error.code) === 'RESULT_EXPIRED') {
+    console.error('Result expired. Ask the user before starting a new authentication request.');
+  } else {
+    throw error;
+  }
+}
 ```
+<!-- simple-auth-usage:end -->
+
+Sources: [APICK development guide](https://apick.app/dev_guide/data_health_checkup) · [MCP 3.5.0 status contract](https://github.com/lead788/apick-mcp/blob/a803abcb81d07377c85f49bb0b670baf0c17ed04/TOOLS.md)
 
-`authProvider` is one of the 13 values in `AUTH_PROVIDERS` (kakao, naver, toss, pass, samsung, kb, shinhan, hana, woori, ibk, nh, kakaobank, banksalad). Acceptance is billed at a flat rate; the result is billed only on its first return and free to re-poll afterward. `requestEmployment` takes an optional `insuranceYears` (1-3), `requestPersonalIncome` takes `incomeYears` (1-5), and `requestNpsJoinHistory` takes optional `from`/`to` (`YYYY-MM`). The remaining products are `requestDrivingLicense` and `requestHealthCheckup`.
+`authProvider` is one of the 13 values in `AUTH_PROVIDERS` (kakao, naver, toss, pass, samsung, kb, shinhan, hana, woori, ibk, nh, kakaobank, banksalad). Acceptance is billed at a flat rate; the result is billed only on its first return and free to re-poll afterward. `requestEmployment` takes an optional `insuranceYears` (1-3), `requestPersonalIncome` takes `incomeYears` (1-5), and `requestNpsJoinHistory` takes optional `from`/`to` (`YYYY-MM`). `requestCashReceiptDeduction` takes optional `incomeYears` (1-3) and `requestTaxReturnHistory` takes optional `years` (1-10). The remaining products are `requestDrivingLicense` and `requestHealthCheckup`.
 
 ## Errors and retries
 

package/docs/guide.ko.md

@@ -94,6 +94,13 @@ TTS는 16개 목소리 ID를 지원합니다. 정확한 목록은 `TTS_VOICE_IDS
 const screenshot = await client.screenshot('https://example.com');
 await screenshot.save('./example.jpeg');
 
+// 유튜브 공개 영상: 영상 주소 또는 11자리 영상 ID
+const video = await client.youtubeMetadata('https://www.youtube.com/watch?v=dQw4w9WgXcQ');
+const tracks = await client.youtubeSubtitleList(video.data.video_id);
+const subtitle = await client.youtubeSubtitle(video.data.video_id, 'en', { format: 'srt' });
+await subtitle.save('./' + subtitle.filename);
+await (await client.youtubeThumbnail(video.data.video_id)).save('./thumbnail.jpg');
+
 const created = await client.createTtsJob('오늘의 이야기를 시작합니다.', { voiceId: 'v2_ann_m_30s_01' });
 const jobId = created.data.job_id;
 let job = await client.getTtsJob(jobId);
@@ -189,8 +196,56 @@ console.log(result.data.result.fields);
 
 ## 간편인증 데이터 조회
 
-재직·소득·연금·면허·건강검진 조회는 본인 간편인증이 필요해 접수(`request*`)와 결과 조회(`get*`)가 나뉩니다.
+재직·소득·연금·면허·건강검진·현금영수증·국세 신고내역 조회는 본인 간편인증이 필요해 접수(`request*`)와 결과 조회(`get*`)가 나뉩니다.
+
+아래 함수는 7종 모두에 공통으로 사용합니다. 같은 `transactionId`로 순차 조회하며 5→10→20→30초 간격으로 늘린 뒤 30초를 유지합니다. `resultAvailable === true`이면 즉시 결과를 반환합니다. `SUCCESS`는 전체 성공, `PARTIAL_SUCCESS`는 부분 성공이므로 `sources`에서 누락·실패 항목을 확인하세요. `AUTH_REJECTED`·`AUTH_EXPIRED`·`FAILED`는 실패 종료이며, `errorCode: 'RESULT_EXPIRED'`는 결과 보관 기간 만료입니다. 실패·만료 시 자동으로 재접수하지 않습니다.
+
+<!-- simple-auth-polling:start -->
+```js
+async function pollDataResult(getResult, accepted, { timeoutMs = 600_000 } = {}) {
+  const pending = new Set([
+    'AUTH_REQUESTED', 'AUTH_WAITING', 'AUTH_COMPLETED', 'COLLECTING', 'COLLECTED'
+  ]);
+  const failed = new Set(['AUTH_REJECTED', 'AUTH_EXPIRED', 'FAILED']);
+  const completed = new Set(['SUCCESS', 'PARTIAL_SUCCESS']);
+  const delays = [5_000, 10_000, 20_000, 30_000];
+  const deadline = Date.now() + timeoutMs;
+  const transactionId = accepted.data.transactionId;
+  const stop = code => { throw Object.assign(new Error(code), { code }); };
+  let response = accepted;
+  let attempt = 0;
+
+  for (;;) {
+    const data = response.data;
+    if (data.errorCode === 'RESULT_EXPIRED') stop('RESULT_EXPIRED');
+    if (failed.has(data.status)) stop(data.errorCode || data.status);
+    if (data.resultAvailable === true) {
+      if (data.result == null) stop('INVALID_RESULT');
+      return response;
+    }
+    if (completed.has(data.status)) stop('RESULT_NOT_AVAILABLE');
+    if (!pending.has(data.status)) stop('UNKNOWN_STATUS');
+
+    const awaitingApproval = ['AUTH_REQUESTED', 'AUTH_WAITING'].includes(data.status);
+    const authDeadline = Date.parse(data.expiresAt || accepted.data.expiresAt);
+    const limit = awaitingApproval && Number.isFinite(authDeadline)
+      ? Math.min(deadline, authDeadline) : deadline;
+    const timeoutCode = awaitingApproval && limit === authDeadline
+      ? 'AUTH_WAIT_TIMEOUT' : 'CLIENT_POLL_TIMEOUT';
+    const remaining = limit - Date.now();
+    if (remaining <= 0) stop(timeoutCode);
+    await new Promise(resolve => setTimeout(resolve,
+      Math.min(delays[Math.min(attempt++, delays.length - 1)], remaining)));
+    if (Date.now() >= limit) stop(timeoutCode);
+    response = await getResult(transactionId);
+  }
+}
+```
+<!-- simple-auth-polling:end -->
+
+`AUTH_REQUESTED`·`AUTH_WAITING`은 사용자 승인을 기다리고, `AUTH_COMPLETED`·`COLLECTING`·`COLLECTED`는 결과가 준비될 때까지 계속 조회합니다. 과금 여부(`charged`, `success`)는 완료 기준이 아닙니다. 인증 대기에만 `expiresAt`을 적용하고 승인 후에는 전체 대기 한도를 적용합니다. 예제의 10분 한도는 클라이언트 정책이며, 진행 중인 호출의 제한 시간은 SDK의 `timeoutMs`로 별도 설정하세요. `AUTH_WAIT_TIMEOUT`·`CLIENT_POLL_TIMEOUT`·`RESULT_NOT_AVAILABLE`·`INVALID_RESULT`·`UNKNOWN_STATUS`는 예제에서 만드는 로컬 오류로, 응답 모순이나 알 수 없는 상태에서 무한 반복하지 않습니다. 통신 오류도 재시도 없이 호출자에게 전달합니다.
 
+<!-- simple-auth-usage:start -->
 ```js
 const accepted = await client.requestDrivingLicense({
   name: '홍길동',
@@ -199,14 +254,23 @@ const accepted = await client.requestDrivingLicense({
   authProvider: 'kakao'
 });
 
-let result;
-do {
-  await new Promise(resolve => setTimeout(resolve, 3000));
-  result = await client.getDrivingLicense(accepted.data.transactionId);
-} while (result.data.status === 'AUTH_WAITING' || result.data.status === 'COLLECTING');
+try {
+  const result = await pollDataResult(id => client.getDrivingLicense(id), accepted);
+  if (result.data.status === 'PARTIAL_SUCCESS') console.warn(result.data.sources);
+  console.log(result.data.result);
+} catch (error) {
+  if ((error.serviceCode || error.code) === 'RESULT_EXPIRED') {
+    console.error('결과 보관 기간 만료: 사용자 확인 후 새 인증을 요청하세요.');
+  } else {
+    throw error;
+  }
+}
 ```
+<!-- simple-auth-usage:end -->
+
+근거: [APICK 개발가이드](https://apick.app/dev_guide/data_health_checkup) · [MCP 3.5.0 상태 계약](https://github.com/lead788/apick-mcp/blob/a803abcb81d07377c85f49bb0b670baf0c17ed04/TOOLS.md)
 
-`authProvider`는 `AUTH_PROVIDERS`(13종: kakao, naver, toss, pass, samsung, kb, shinhan, hana, woori, ibk, nh, kakaobank, banksalad) 중 하나입니다. 접수는 정액 과금, 결과는 최초 반환에서만 과금되며 재조회는 무료입니다. `requestEmployment`는 `insuranceYears`(1~3), `requestPersonalIncome`은 `incomeYears`(1~5), `requestNpsJoinHistory`는 `from`/`to`(`YYYY-MM`) 선택 입력을 받습니다. 나머지 상품은 `requestDrivingLicense`, `requestHealthCheckup`입니다.
+`authProvider`는 `AUTH_PROVIDERS`(13종: kakao, naver, toss, pass, samsung, kb, shinhan, hana, woori, ibk, nh, kakaobank, banksalad) 중 하나입니다. 접수는 정액 과금, 결과는 최초 반환에서만 과금되며 재조회는 무료입니다. `requestEmployment`는 `insuranceYears`(1~3), `requestPersonalIncome`은 `incomeYears`(1~5), `requestNpsJoinHistory`는 `from`/`to`(`YYYY-MM`) 선택 입력을 받습니다. `requestCashReceiptDeduction`은 `incomeYears`(1~3), `requestTaxReturnHistory`는 `years`(1~10) 선택 입력을 받습니다. 나머지 상품은 `requestDrivingLicense`, `requestHealthCheckup`입니다.
 
 ## 오류와 재시도
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "apick-api",
-  "version": "3.4.0",
+  "version": "3.5.0",
   "description": "Official zero-dependency Node.js client for APICK data, AI, and image APIs. 에이픽 데이터·AI·이미지 API 공식 Node.js SDK.",
   "type": "module",
   "main": "./src/index.cjs",

package/src/index.cjs

@@ -36,6 +36,10 @@ const SERVICE_DEFINITIONS = Object.freeze({
 	googleSearch: { endpoint: '/rest/google_search', timeoutMs: 35_000, output: 'json' },
 	googleImageSearch: { endpoint: '/rest/google_image_search', timeoutMs: 35_000, output: 'json' },
 	screenshot: { endpoint: '/rest/url_screenshot', timeoutMs: 75_000, output: 'binary', filename: 'screenshot.jpeg' },
+	youtubeMetadata: { endpoint: '/rest/youtube_metadata', timeoutMs: 60_000, output: 'json' },
+	youtubeThumbnail: { endpoint: '/rest/youtube_thumbnail', timeoutMs: 60_000, output: 'binary', filename: 'thumbnail.jpg' },
+	youtubeSubtitleList: { endpoint: '/rest/youtube_subtitle_list', timeoutMs: 60_000, output: 'json' },
+	youtubeSubtitle: { endpoint: '/rest/youtube_subtitle', timeoutMs: 60_000, output: 'binary', filename: 'subtitle.vtt' },
 	createTtsJob: { endpoint: '/rest/tts/jobs', timeoutMs: 35_000, output: 'json' },
 	createVideoJob: { endpoint: '/rest/seedance/jobs', timeoutMs: 60_000, output: 'json' },
 	htmlToPdf: { endpoint: '/rest/html_to_pdf', timeoutMs: 25_000, output: 'binary', filename: 'document.pdf' },
@@ -47,7 +51,9 @@ const SERVICE_DEFINITIONS = Object.freeze({
 	requestPersonalIncome: { endpoint: '/rest/req_personal_income', timeoutMs: 35_000, output: 'json' },
 	requestNpsJoinHistory: { endpoint: '/rest/req_nps_join_history', timeoutMs: 35_000, output: 'json' },
 	requestDrivingLicense: { endpoint: '/rest/req_driving_license', timeoutMs: 35_000, output: 'json' },
-	requestHealthCheckup: { endpoint: '/rest/req_health_checkup', timeoutMs: 35_000, output: 'json' }
+	requestHealthCheckup: { endpoint: '/rest/req_health_checkup', timeoutMs: 35_000, output: 'json' },
+	requestCashReceiptDeduction: { endpoint: '/rest/req_cash_receipt_deduction', timeoutMs: 35_000, output: 'json' },
+	requestTaxReturnHistory: { endpoint: '/rest/req_tax_return_history', timeoutMs: 35_000, output: 'json' }
 });
 
 const SERVICES = Object.freeze(Object.fromEntries(
@@ -524,6 +530,33 @@ class ApickClient {
 		return this._call('screenshot', { url: normalizeUrl(url) });
 	}
 
+	// 유튜브 공개 영상. url 은 영상 주소(watch·youtu.be·shorts) 또는 11자리 영상 ID를 받는다.
+	youtubeMetadata(url) {
+		return this._call('youtubeMetadata', { url: requiredString('url', url, 2048) });
+	}
+
+	youtubeThumbnail(url) {
+		return this._call('youtubeThumbnail', { url: requiredString('url', url, 2048) });
+	}
+
+	youtubeSubtitleList(url) {
+		return this._call('youtubeSubtitleList', { url: requiredString('url', url, 2048) });
+	}
+
+	youtubeSubtitle(url, lang, options) {
+		const config = options || {};
+		const payload = { url: requiredString('url', url, 2048), lang: requiredString('lang', lang, 32) };
+		if (config.format !== undefined) {
+			if (!['vtt', 'srt', 'txt'].includes(config.format)) throw new RangeError('format must be vtt, srt or txt.');
+			payload.format = config.format;
+		}
+		if (config.type !== undefined) {
+			if (!['any', 'manual', 'auto'].includes(config.type)) throw new RangeError('type must be any, manual or auto.');
+			payload.type = config.type;
+		}
+		return this._call('youtubeSubtitle', payload, null, { filename: 'subtitle.' + (payload.format || 'vtt') });
+	}
+
 	async createVideoJob(model, prompt, options) {
 		if (!['seedance', 'veo', 'kling'].includes(model)) throw new RangeError('model must be seedance, veo or kling.');
 		const config = options || {};
@@ -792,6 +825,28 @@ class ApickClient {
 	getHealthCheckup(transactionId) {
 		return this._call('requestHealthCheckup', { transactionId: normalizeTransactionId(transactionId) }, null, { endpoint: '/rest/get_health_checkup' });
 	}
+
+	requestCashReceiptDeduction(input) {
+		const payload = dataRequestInput(input);
+		const incomeYears = optionalRangeInteger('incomeYears', (input || {}).incomeYears, 1, 3);
+		if (incomeYears !== undefined) payload.incomeYears = incomeYears;
+		return this._call('requestCashReceiptDeduction', payload);
+	}
+
+	getCashReceiptDeduction(transactionId) {
+		return this._call('requestCashReceiptDeduction', { transactionId: normalizeTransactionId(transactionId) }, null, { endpoint: '/rest/get_cash_receipt_deduction' });
+	}
+
+	requestTaxReturnHistory(input) {
+		const payload = dataRequestInput(input);
+		const years = optionalRangeInteger('years', (input || {}).years, 1, 10);
+		if (years !== undefined) payload.years = years;
+		return this._call('requestTaxReturnHistory', payload);
+	}
+
+	getTaxReturnHistory(transactionId) {
+		return this._call('requestTaxReturnHistory', { transactionId: normalizeTransactionId(transactionId) }, null, { endpoint: '/rest/get_tax_return_history' });
+	}
 }
 
 module.exports = {

package/src/index.d.ts

@@ -61,6 +61,8 @@ export interface RequestPersonalIncomeInput extends DataRequestInput { incomeYea
 export interface RequestNpsJoinHistoryInput extends DataRequestInput { from?: string; to?: string; }
 export interface RequestDrivingLicenseInput extends DataRequestInput {}
 export interface RequestHealthCheckupInput extends DataRequestInput {}
+export interface RequestCashReceiptDeductionInput extends DataRequestInput { incomeYears?: number; }
+export interface RequestTaxReturnHistoryInput extends DataRequestInput { years?: number; }
 
 export type DataRequestStatus =
 	| 'AUTH_REQUESTED' | 'AUTH_WAITING' | 'AUTH_COMPLETED' | 'AUTH_REJECTED' | 'AUTH_EXPIRED'
@@ -159,6 +161,44 @@ export interface HealthCheckupEntry { 검진연도: string; 검진종류: string
 export interface HealthCheckupInfo { 이름: string; 건수: number; 검진내역: HealthCheckupEntry[]; }
 export interface HealthCheckupResultPayload { healthCheckup: HealthCheckupInfo; }
 
+export interface CashReceiptTotals { 건수: number; 사용금액: number; 소득공제건수: number; 소득공제금액: number; }
+export interface CashReceiptEntry {
+	거래일시: string; 가맹점: string; 금액: number; 승인번호: string;
+	거래구분: string; 거래상태: string; 소득공제대상: boolean; 소득공제반영: boolean;
+}
+export interface CashReceiptYear { 귀속연도: string; 합계: CashReceiptTotals; 사용내역: CashReceiptEntry[]; }
+export interface CashReceiptDeductionInfo { 조회연도: string[]; 전체합계: CashReceiptTotals; 연도별: CashReceiptYear[]; }
+export interface CashReceiptDeductionResultPayload { cashReceiptDeduction: CashReceiptDeductionInfo; }
+
+export interface TaxReturnEntry {
+	신고일: string; 과세기간: string; 신고서: string; 신고구분: string; 신고상세: string;
+	세목: string; 작성방법: string; 납부년월: string; 납부금액: number; 고지금액: number;
+}
+export interface TaxReturnHistoryInfo {
+	조회기간: { 시작: string; 끝: string };
+	합계: { 건수: number; 납부금액: number; 고지금액: number };
+	신고내역: TaxReturnEntry[];
+}
+export interface TaxReturnHistoryResultPayload { taxReturnHistory: TaxReturnHistoryInfo; }
+
+export interface YoutubeThumbnail { url: string; width: number; height: number; }
+export interface YoutubeChapter { title: string; start_time: number | null; end_time: number | null; }
+export interface YoutubeMetadata {
+	video_id: string; url: string; title: string | null; description: string;
+	channel: { id: string | null; name: string | null; url: string | null; handle: string | null; follower_count: number | null; is_verified: boolean };
+	upload_date: string | null; duration: number | null; view_count: number | null; like_count: number | null; comment_count: number | null;
+	categories: string[]; tags: string[]; language: string | null; live_status: string | null; availability: string | null;
+	age_limit: number | null; chapters: YoutubeChapter[]; thumbnail: string | null; thumbnails: YoutubeThumbnail[];
+	subtitle_languages: string[]; automatic_caption_count: number;
+}
+export interface YoutubeSubtitleTrack { lang: string; name: string | null; auto: boolean; formats: string[]; translated?: boolean; }
+export interface YoutubeSubtitleList {
+	video_id: string; title: string | null; original_language: string | null;
+	subtitle_count: number; automatic_caption_count: number;
+	subtitles: YoutubeSubtitleTrack[]; automatic_captions: YoutubeSubtitleTrack[];
+}
+export interface YoutubeSubtitleOptions { format?: 'vtt' | 'srt' | 'txt'; type?: 'any' | 'manual' | 'auto'; }
+
 export const TTS_VOICE_IDS: readonly [
 	'v2_ann_m_30s_01', 'v2_ann_m_30s_02', 'v2_ann_m_30s_04', 'v2_ann_m_30s_05', 'v2_ann_f_30s_01', 'v2_ann_f_30s_02', 'v2_ann_f_30s_03', 'v2_ann_f_30s_04', 'v2_ann_f_30s_05', 'v2_m_teen_01', 'v2_m_young_01', 'v2_m_mid_01', 'v2_m_senior_01', 'v2_f_teen_01', 'v2_f_young_01', 'v2_f_senior_01'
 ];
@@ -244,6 +284,10 @@ export class ApickClient {
 	googleSearch(keyword: string, options?: { page?: number }): Promise<ApickResult>;
 	googleImageSearch(keyword: string, options?: { page?: number }): Promise<ApickResult>;
 	screenshot(url: string): Promise<ApickBinaryResult>;
+	youtubeMetadata(url: string): Promise<ApickResult<YoutubeMetadata>>;
+	youtubeThumbnail(url: string): Promise<ApickBinaryResult>;
+	youtubeSubtitleList(url: string): Promise<ApickResult<YoutubeSubtitleList>>;
+	youtubeSubtitle(url: string, lang: string, options?: YoutubeSubtitleOptions): Promise<ApickBinaryResult>;
 	createTtsJob(text: string, options?: { voiceId?: TtsVoiceId }): Promise<ApickResult<TtsJobData>>;
 	getTtsJob(jobId: string): Promise<ApickResult<TtsJobData>>;
 	cancelTtsJob(jobId: string): Promise<ApickResult<TtsJobData>>;
@@ -273,6 +317,10 @@ export class ApickClient {
 	getDrivingLicense(transactionId: string): Promise<ApickResult<DataRequestResult<DrivingLicenseResultPayload>>>;
 	requestHealthCheckup(input: RequestHealthCheckupInput): Promise<ApickResult<DataRequestAcceptedData>>;
 	getHealthCheckup(transactionId: string): Promise<ApickResult<DataRequestResult<HealthCheckupResultPayload>>>;
+	requestCashReceiptDeduction(input: RequestCashReceiptDeductionInput): Promise<ApickResult<DataRequestAcceptedData>>;
+	getCashReceiptDeduction(transactionId: string): Promise<ApickResult<DataRequestResult<CashReceiptDeductionResultPayload>>>;
+	requestTaxReturnHistory(input: RequestTaxReturnHistoryInput): Promise<ApickResult<DataRequestAcceptedData>>;
+	getTaxReturnHistory(transactionId: string): Promise<ApickResult<DataRequestResult<TaxReturnHistoryResultPayload>>>;
 }
 
 export default ApickClient;