apick-api 3.4.1 → 3.6.0

package/CHANGELOG.md

@@ -1,13 +1,31 @@
-# Changelog
-
-## 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
+# Changelog
+
+## 3.6.0 — 2026-10-02
+
+- Skills 메서드 8종을 추가했습니다: `searchSkills()`, `getSkill()`, `quoteSkill()`, `runSkill()`, `getSkillRun()`, `getSkillRunResult()`, `cancelSkillRun()`, `skillUsage()`. 요청·응답이 JSON 이며 응답은 봉투 없이 `data` 에 담깁니다.
+- Add eight Skills methods to search, inspect, quote, run, read, fetch the result of, cancel and list Skill runs. Requests and responses are JSON; responses are returned as-is in `data`.
+- `runSkill()` 은 `idempotencyKey` 가 필수이며 `Idempotency-Key` 헤더로 보냅니다. 결과가 약속한 형식으로 반환된 실행만 차감됩니다.
+- 생성형 AI 를 쓰는 Skill 은 실행마다 실제 사용량만큼 금액이 달라집니다. `quoteSkill()` 이 예상 금액(`estimated_points`)과 최대 금액(`max_points`)을 돌려주며, `maxCostPoints` 에는 `max_points` 를 넘기세요.
+- For Skills that use generative AI the charge varies per run with actual usage. `quoteSkill()` returns `estimated_points` and `max_points`; pass `max_points` as `maxCostPoints`.
+- `runSkill()` requires `idempotencyKey`, sent as the `Idempotency-Key` header. Only runs that return a result in the promised format are charged.
+- `ApickApiError` 에 선택적 `details` 를 추가했습니다. Skills 오류 코드는 `serviceCode` 로 전달됩니다. `SKILL_CATEGORIES` 상수와 Skills 타입(`SkillSummary`, `SkillDetail`, `SkillQuote`, `SkillRun` 등)을 공개했습니다.
+- Add optional `details` to `ApickApiError`; Skills error codes are surfaced through `serviceCode`. Export `SKILL_CATEGORIES` and the Skills types.
+
+## 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*()`로 상태·결과를 폴링합니다.
 - 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*()`.

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,42 @@ 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 |
+| `searchSkills(options)` / `getSkill(skillId)` | Skill 검색·상세 / Search and inspect Skills | JSON |
+| `quoteSkill(skillId, input, options)` | Skill 견적(무료) / Quote a run (free) | JSON |
+| `runSkill(skillId, input, options)` | Skill 실행 / Run a Skill | JSON |
+| `getSkillRun(runId)` / `getSkillRunResult(runId)` / `cancelSkillRun(runId)` | 실행 조회·결과·취소 / Read, fetch result, cancel | JSON |
+| `skillUsage(options)` | 내 Skill 실행 내역 / My Skill runs | JSON |
+
+## Skills
+
+검수를 거친 Skill 을 검색하고 실행합니다. 결과가 약속한 형식으로 반환된 실행만 포인트가 차감되고, 실패·시간초과·취소는 차감되지 않습니다. 생성형 AI 를 쓰는 Skill 은 실행마다 실제 사용량만큼 금액이 달라지므로, 실행 전에 `quoteSkill()` 로 예상 금액(`estimated_points`)과 최대 금액(`max_points`)을 확인하세요. 1회 이상 결제한 계정에서 실행할 수 있습니다.
+Search and run reviewed Skills. Points are charged only when a result in the promised format is returned; failures, timeouts and cancellations are not charged. For Skills that use generative AI the amount varies per run with actual usage, so call `quoteSkill()` first to get the estimated (`estimated_points`) and maximum (`max_points`) amount. Running requires an account with at least one payment.
+
+```js
+import { randomUUID } from 'node:crypto';
+
+const found = await apick.searchSkills({ query: '상품명', limit: 5 });
+const skillId = found.data.items[0].skill_id;
+const detail = await apick.getSkill(skillId);          // input_schema, output_schema, price_points, estimated_points
+const input = { product_name: '튼튼한 접이식 우산' };
+const quote = (await apick.quoteSkill(skillId, input)).data; // 무료 / free: estimated_points, max_points
+
+const idempotencyKey = randomUUID();                    // 재시도할 때 같은 값을 다시 씁니다 / reuse on retry
+let run = (await apick.runSkill(skillId, input, { idempotencyKey, quoteId: quote.quote_id, maxCostPoints: quote.max_points })).data;
+while (!['succeeded', 'failed', 'timed_out', 'cancelled'].includes(run.status)) {
+  await new Promise(resolve => setTimeout(resolve, 2000));
+  run = (await apick.getSkillRun(run.run_id)).data;
+}
+console.log(run.status, run.billing, run.result);
+```
+
+Skills 응답은 다른 API 와 달리 봉투 없이 그대로 `data` 에 담깁니다. 과금 상태는 `data.billing`(`reserved`·`captured`·`released`…)에서 확인하며 `meta.cost` 는 채워지지 않습니다. 응답을 받지 못했을 때는 **같은 `idempotencyKey`** 로 다시 호출하세요. 포인트는 한 번만 차감됩니다. 같은 키에 다른 입력을 보내면 `IDEMPOTENCY_CONFLICT` 로 거부됩니다.
+Skills responses are returned as-is in `data`. Read the charge from `data.billing`; `meta.cost` is not populated. If a response is lost, call again with the **same `idempotencyKey`** — points are charged once. The same key with a different input is rejected with `IDEMPOTENCY_CONFLICT`.
+
+접수 전에 거절된 요청은 `ApickApiError` 로 던져지며 `serviceCode` 에 `INVALID_INPUT`·`INSUFFICIENT_POINTS`·`PRICE_EXCEEDS_LIMIT`·`RATE_LIMITED` 같은 코드가, `details` 에 부가 정보가 담깁니다. 접수된 뒤 실패한 실행은 예외가 아니라 `status` 와 `failure_code` 로 확인합니다.
+Requests rejected before acceptance throw `ApickApiError` with the code in `serviceCode` and extra information in `details`. A run that fails after acceptance is reported through `status` and `failure_code`, not an exception.
 
 ## JSON 결과 / JSON results
 
@@ -237,86 +277,86 @@ The four document-specific methods return JSON. `maskResidentNumber` returns PNG
 
 ## 간편인증 기반 데이터 조회 / Simple-auth data lookups
 
-본인 간편인증이 필요한 조회 상품(재직·소득·연금·면허·건강검진)은 접수(`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.
-
-아래 함수는 5종 모두에 공통으로 사용합니다. 같은 `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 five 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',
-  insuranceYears: 3
-});
-
-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)
+본인 간편인증이 필요한 조회 상품(재직·소득·연금·면허·건강검진·현금영수증·국세 신고내역)은 접수(`request*`)와 결과 조회(`get*`)가 분리되어 있습니다. 접수 응답의 `transactionId`로 결과를 폴링하세요.
+
+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',
+  insuranceYears: 3
+});
+
+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`.
@@ -331,6 +371,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,81 +194,123 @@ 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*`).
-
-Use this helper for all five 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',
-  birthDate: '19900101',
-  phone: '01011112222',
-  authProvider: 'kakao'
-});
-
-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`.
+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',
+  birthDate: '19900101',
+  phone: '01011112222',
+  authProvider: 'kakao'
+});
+
+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`). `requestCashReceiptDeduction` takes optional `incomeYears` (1-3) and `requestTaxReturnHistory` takes optional `years` (1-10). The remaining products are `requestDrivingLicense` and `requestHealthCheckup`.
+
+## Skills
+
+Search and run reviewed Skills. Each Skill fixes its input format (`input_schema`), output format (`output_schema`) and base amount (`price_points`). A run is charged only when a result in the promised format is returned.
+
+For Skills that use generative AI (`usage_priced: true`) the actual usage of each run is added to the base amount, so the charge varies per run. `quoteSkill()` returns the estimated amount (`estimated_points`) and the maximum amount (`max_points`). The maximum is reserved when the run is accepted; when it finishes only the actual amount is charged and the rest is returned. Read the actual charge from `run.billing.charged_points`.
+
+```js
+import { randomUUID } from 'node:crypto';
+
+const found = await client.searchSkills({ query: 'product name', limit: 5 });
+const skillId = found.data.items[0].skill_id;
+const detail = await client.getSkill(skillId);
+const input = { product_name: 'Sturdy folding umbrella' };
+
+const quote = await client.quoteSkill(skillId, input);   // free, valid for 5 minutes
+const idempotencyKey = randomUUID();                      // reuse the same value when retrying
+let run = (await client.runSkill(skillId, input, {
+  idempotencyKey, quoteId: quote.data.quote_id, maxCostPoints: quote.data.max_points
+})).data;
+while (!['succeeded', 'failed', 'timed_out', 'cancelled'].includes(run.status)) {
+  await new Promise(resolve => setTimeout(resolve, 2000));
+  run = (await client.getSkillRun(run.run_id)).data;
+}
+console.log(run.status, run.billing, run.result);
+```
+
+| Method | Description |
+| --- | --- |
+| `searchSkills({ query, category, cursor, limit })` | Search. `limit` 1-20; `category` is one of `SKILL_CATEGORIES` |
+| `getSkill(skillId)` | Input and output formats, price, limits, examples |
+| `quoteSkill(skillId, input, { version })` | Validates the input and reports the points to be charged. Does not run |
+| `runSkill(skillId, input, { idempotencyKey, quoteId, maxCostPoints, version, waitSeconds })` | Run. `idempotencyKey` is required; `waitSeconds` 0-20 (default 20) |
+| `getSkillRun(runId)` / `getSkillRunResult(runId)` | Run status (with the result once succeeded) / result only. Results are kept for 7 days |
+| `cancelSkillRun(runId)` | Cancel an unfinished run. Cancelled runs are not charged |
+| `skillUsage({ cursor, limit })` | Your runs. `limit` 1-50 |
+
+- Skills responses are returned as-is in `data`. Read the charge from `data.billing.status` (`reserved`, `captured`, `released`, `partially_refunded`, `refunded`); `meta.cost` is not populated.
+- If a run does not finish within 20 seconds it comes back as `queued` or `running`; poll `getSkillRun`.
+- If a response is lost, call again with the same `idempotencyKey`. Points are charged once. The same key with a different input is rejected with `IDEMPOTENCY_CONFLICT`.
+- Rejections before acceptance throw `ApickApiError` (`serviceCode` such as `INVALID_INPUT`, `INSUFFICIENT_POINTS`, `PAYMENT_REQUIRED`, `PRICE_EXCEEDS_LIMIT`, `RATE_LIMITED`; extra information in `details`). Failures after acceptance are reported through `status` and `failure_code` (`EXECUTION_FAILED`, `OUTPUT_INVALID`, `TIMED_OUT`, `CANCELLED`, `UPSTREAM_UNAVAILABLE`).
+- Skills with `uses_generative_ai: true` produce results with generative AI. Verify them before relying on them.
 
 ## 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,81 +196,123 @@ console.log(result.data.result.fields);
 
 ## 간편인증 데이터 조회
 
-재직·소득·연금·면허·건강검진 조회는 본인 간편인증이 필요해 접수(`request*`)와 결과 조회(`get*`)가 나뉩니다.
-
-아래 함수는 5종 모두에 공통으로 사용합니다. 같은 `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: '홍길동',
-  birthDate: '19900101',
-  phone: '01011112222',
-  authProvider: 'kakao'
-});
-
-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`입니다.
+재직·소득·연금·면허·건강검진·현금영수증·국세 신고내역 조회는 본인 간편인증이 필요해 접수(`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: '홍길동',
+  birthDate: '19900101',
+  phone: '01011112222',
+  authProvider: 'kakao'
+});
+
+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`) 선택 입력을 받습니다. `requestCashReceiptDeduction`은 `incomeYears`(1~3), `requestTaxReturnHistory`는 `years`(1~10) 선택 입력을 받습니다. 나머지 상품은 `requestDrivingLicense`, `requestHealthCheckup`입니다.
+
+## Skills
+
+검수를 거친 Skill 을 검색하고 실행합니다. Skill 마다 입력 형식(`input_schema`)·결과 형식(`output_schema`)·기본 금액(`price_points`)이 정해져 있으며, 결과가 약속한 형식으로 반환된 실행만 차감됩니다.
+
+생성형 AI 를 쓰는 Skill(`usage_priced: true`)은 기본 금액에 그 실행의 실제 사용량이 더해져 실행마다 금액이 달라집니다. `quoteSkill()` 은 예상 금액(`estimated_points`)과 최대 금액(`max_points`)을 돌려줍니다. 실행을 접수할 때 최대 금액을 예약하고, 끝나면 실제 금액만 차감한 뒤 나머지를 돌려줍니다. 실제 차감액은 `run.billing.charged_points` 에서 확인합니다.
+
+```js
+import { randomUUID } from 'node:crypto';
+
+const found = await client.searchSkills({ query: '상품명', limit: 5 });
+const skillId = found.data.items[0].skill_id;
+const detail = await client.getSkill(skillId);
+const input = { product_name: '튼튼한 접이식 우산' };
+
+const quote = await client.quoteSkill(skillId, input);   // 무료. 5분 동안 유효
+const idempotencyKey = randomUUID();                      // 재시도할 때 같은 값을 다시 씁니다
+let run = (await client.runSkill(skillId, input, {
+  idempotencyKey, quoteId: quote.data.quote_id, maxCostPoints: quote.data.max_points
+})).data;
+while (!['succeeded', 'failed', 'timed_out', 'cancelled'].includes(run.status)) {
+  await new Promise(resolve => setTimeout(resolve, 2000));
+  run = (await client.getSkillRun(run.run_id)).data;
+}
+console.log(run.status, run.billing, run.result);
+```
+
+| 메서드 | 설명 |
+| --- | --- |
+| `searchSkills({ query, category, cursor, limit })` | 검색. `limit` 1~20, `category` 는 `SKILL_CATEGORIES` 중 하나 |
+| `getSkill(skillId)` | 입력·결과 형식, 가격, 처리 상한, 예제 |
+| `quoteSkill(skillId, input, { version })` | 입력 검사와 차감될 포인트 확인. 실행하지 않습니다 |
+| `runSkill(skillId, input, { idempotencyKey, quoteId, maxCostPoints, version, waitSeconds })` | 실행. `idempotencyKey` 필수, `waitSeconds` 0~20(기본 20) |
+| `getSkillRun(runId)` / `getSkillRunResult(runId)` | 실행 상태(성공하면 결과 포함) / 결과만 조회. 결과는 7일 동안 보관 |
+| `cancelSkillRun(runId)` | 끝나지 않은 실행 취소. 취소된 실행은 차감되지 않습니다 |
+| `skillUsage({ cursor, limit })` | 내 실행 내역. `limit` 1~50 |
+
+- Skills 응답은 봉투 없이 `data` 에 그대로 담기며, 과금 상태는 `data.billing.status`(`reserved`·`captured`·`released`·`partially_refunded`·`refunded`)로 확인합니다. `meta.cost` 는 채워지지 않습니다.
+- 20초 안에 끝나지 않으면 `status` 가 `queued`·`running` 인 채로 돌아오므로 `getSkillRun` 으로 확인하세요.
+- 응답을 받지 못했을 때는 같은 `idempotencyKey` 로 다시 호출하세요. 포인트는 한 번만 차감됩니다. 같은 키에 다른 입력을 보내면 `IDEMPOTENCY_CONFLICT` 입니다.
+- 접수 전 거절은 `ApickApiError`(`serviceCode`: `INVALID_INPUT`·`INSUFFICIENT_POINTS`·`PAYMENT_REQUIRED`·`PRICE_EXCEEDS_LIMIT`·`RATE_LIMITED` 등, `details` 에 부가 정보)로, 접수 뒤 실패는 `status` 와 `failure_code`(`EXECUTION_FAILED`·`OUTPUT_INVALID`·`TIMED_OUT`·`CANCELLED`·`UPSTREAM_UNAVAILABLE`)로 확인합니다.
+- `uses_generative_ai` 가 true 인 Skill 은 생성형 AI 로 결과를 만듭니다. 중요한 판단에 쓰기 전에 확인하세요.
 
 ## 오류와 재시도
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "apick-api",
-  "version": "3.4.1",
+  "version": "3.6.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(
@@ -169,6 +175,27 @@ function dataRequestInput(input) {
 	};
 }
 
+const SKILL_CATEGORIES = Object.freeze(['data', 'ai', 'dev', 'document', 'marketing', 'finance', 'productivity', 'video', 'etc']);
+const SKILL_CATEGORY_SET = new Set(SKILL_CATEGORIES);
+
+function normalizeSkillId(value) {
+	return encodeURIComponent(requiredString('skillId', value, 80));
+}
+
+function normalizeSkillRunId(value) {
+	return encodeURIComponent(requiredString('runId', value, 64));
+}
+
+function skillInput(value) {
+	if (!value || typeof value !== 'object' || Array.isArray(value)) throw new TypeError('input must be a plain object matching the Skill input_schema.');
+	return value;
+}
+
+function optionalSkillText(name, value, maxLength) {
+	if (value === undefined || value === null || value === '') return undefined;
+	return requiredString(name, String(value), maxLength);
+}
+
 function numberOrNull(value) {
 	if (value === undefined || value === null || value === '') return null;
 	const number = Number(value);
@@ -262,6 +289,7 @@ class ApickApiError extends Error {
 		this.status = options && options.status || 0;
 		this.code = options && options.code || 'APICK_API_ERROR';
 		this.serviceCode = options && options.serviceCode || undefined;
+		if (options && options.details !== undefined) this.details = options.details;
 	}
 
 	toJSON() {
@@ -524,6 +552,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 +847,150 @@ 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' });
+	}
+
+	// Skills: 요청·응답이 모두 JSON 이고 data·api 봉투 없이 응답 항목이 최상위에 온다.
+	// 오류는 { error: { code, message, details } } 형식이며 code 를 serviceCode 로 돌려준다.
+	async _skills(method, path, options) {
+		const config = options || {};
+		const controller = new AbortController();
+		const timeoutMs = this.#timeoutMs || config.timeoutMs || DEFAULT_TIMEOUT_MS;
+		const timer = setTimeout(() => controller.abort(), timeoutMs);
+		const headers = { Accept: 'application/json', Authorization: `Bearer ${this.#apiKey}` };
+		const request = { method, headers, signal: controller.signal, redirect: 'error' };
+		if (config.idempotencyKey) headers['Idempotency-Key'] = config.idempotencyKey;
+		if (method !== 'GET') {
+			headers['Content-Type'] = 'application/json';
+			request.body = JSON.stringify(config.body || {});
+		}
+		let url = this.#baseUrl + path;
+		const query = new URLSearchParams(config.query || {}).toString();
+		if (query) url += '?' + query;
+
+		let response;
+		try {
+			response = await this.#fetch(url, request);
+		} catch (error) {
+			const timedOut = controller.signal.aborted || error && error.name === 'AbortError';
+			throw new ApickApiError(
+				timedOut ? `APICK request timed out after ${timeoutMs} ms.` : redact(error && error.message || 'APICK network request failed.', this.#apiKey),
+				{ code: timedOut ? 'APICK_TIMEOUT' : 'APICK_NETWORK_ERROR' }
+			);
+		} finally {
+			clearTimeout(timer);
+		}
+
+		const raw = await response.text();
+		let body;
+		try {
+			body = raw ? JSON.parse(raw) : null;
+		} catch {
+			body = undefined;
+		}
+		const failure = body && typeof body === 'object' && body.error && typeof body.error === 'object' ? body.error : null;
+		if (!response.ok || failure) {
+			throw new ApickApiError(failure && typeof failure.message === 'string' && failure.message || publicErrorMessage(body, 'APICK request failed.'), {
+				status: response.status,
+				code: response.status === 401 ? 'APICK_AUTH_ERROR' : 'APICK_API_ERROR',
+				serviceCode: failure && typeof failure.code === 'string' ? failure.code : undefined,
+				details: failure && failure.details && typeof failure.details === 'object' ? failure.details : undefined
+			});
+		}
+		if (!body || typeof body !== 'object') {
+			throw new ApickApiError(`APICK returned an unexpected response (HTTP ${response.status}).`, {
+				status: response.status,
+				code: 'APICK_INVALID_RESPONSE'
+			});
+		}
+		return Object.freeze({ data: body, meta: responseMeta(null, response.headers) });
+	}
+
+	searchSkills(options) {
+		const config = options || {};
+		const query = {};
+		if (config.query !== undefined && config.query !== null && config.query !== '') query.query = requiredString('query', config.query, 60);
+		if (config.category !== undefined && config.category !== null && config.category !== '') {
+			const category = requiredString('category', config.category);
+			if (!SKILL_CATEGORY_SET.has(category)) throw new RangeError('category must be one of the supported Skill categories.');
+			query.category = category;
+		}
+		if (config.cursor !== undefined && config.cursor !== null && config.cursor !== '') query.cursor = requiredString('cursor', String(config.cursor), 20);
+		const limit = optionalRangeInteger('limit', config.limit, 1, 20);
+		if (limit !== undefined) query.limit = String(limit);
+		return this._skills('GET', '/rest/skills', { query });
+	}
+
+	getSkill(skillId) {
+		return this._skills('GET', '/rest/skills/' + normalizeSkillId(skillId));
+	}
+
+	quoteSkill(skillId, input, options) {
+		const body = { input: skillInput(input) };
+		const version = optionalSkillText('version', (options || {}).version, 16);
+		if (version !== undefined) body.version = version;
+		return this._skills('POST', '/rest/skills/' + normalizeSkillId(skillId) + '/quotes', { body });
+	}
+
+	// 같은 idempotencyKey 로 다시 보내면 새로 실행하지 않고 처음 실행을 돌려준다. 응답을 못 받았을 때는 같은 키로 재시도한다.
+	runSkill(skillId, input, options) {
+		const config = options || {};
+		const idempotencyKey = requiredString('idempotencyKey', config.idempotencyKey);
+		if (!/^[A-Za-z0-9._:-]{1,128}$/.test(idempotencyKey)) {
+			throw new TypeError('idempotencyKey must be 1-128 characters of letters, digits, and . _ : -');
+		}
+		const body = { input: skillInput(input) };
+		const version = optionalSkillText('version', config.version, 16);
+		const quoteId = optionalSkillText('quoteId', config.quoteId, 40);
+		const maxCostPoints = config.maxCostPoints === undefined || config.maxCostPoints === null ? undefined : positiveInteger('maxCostPoints', config.maxCostPoints);
+		const waitSeconds = optionalRangeInteger('waitSeconds', config.waitSeconds, 0, 20);
+		if (version !== undefined) body.version = version;
+		if (quoteId !== undefined) body.quote_id = quoteId;
+		if (maxCostPoints !== undefined) body.max_cost_points = maxCostPoints;
+		if (waitSeconds !== undefined) body.wait_seconds = waitSeconds;
+		return this._skills('POST', '/rest/skills/' + normalizeSkillId(skillId) + '/runs', { body, idempotencyKey, timeoutMs: 40_000 });
+	}
+
+	getSkillRun(runId) {
+		return this._skills('GET', '/rest/skills/runs/' + normalizeSkillRunId(runId));
+	}
+
+	getSkillRunResult(runId) {
+		return this._skills('GET', '/rest/skills/runs/' + normalizeSkillRunId(runId) + '/result');
+	}
+
+	cancelSkillRun(runId) {
+		return this._skills('POST', '/rest/skills/runs/' + normalizeSkillRunId(runId) + '/cancel', { body: {} });
+	}
+
+	skillUsage(options) {
+		const config = options || {};
+		const query = {};
+		if (config.cursor !== undefined && config.cursor !== null && config.cursor !== '') query.cursor = requiredString('cursor', String(config.cursor), 20);
+		const limit = optionalRangeInteger('limit', config.limit, 1, 50);
+		if (limit !== undefined) query.limit = String(limit);
+		return this._skills('GET', '/rest/skills/usage', { query });
+	}
 }
 
 module.exports = {
@@ -801,5 +1000,6 @@ module.exports = {
 	SERVICES,
 	TTS_VOICE_IDS,
 	AUTH_PROVIDERS,
+	SKILL_CATEGORIES,
 	DEFAULT_BASE_URL
 };

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'
 ];
@@ -192,6 +232,8 @@ export class ApickApiError extends Error {
 	readonly status: number;
 	readonly code: string;
 	readonly serviceCode?: string;
+	/** Skills 오류의 부가 정보. 예: INVALID_INPUT 의 `errors` 목록 */
+	readonly details?: Record<string, unknown>;
 	toJSON(): {
 		name: string;
 		message: string;
@@ -244,6 +286,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 +319,82 @@ 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>>>;
+	searchSkills(options?: SkillSearchOptions): Promise<ApickResult<SkillPage<SkillSummary>>>;
+	getSkill(skillId: string): Promise<ApickResult<SkillDetail>>;
+	quoteSkill(skillId: string, input: Record<string, unknown>, options?: { version?: string }): Promise<ApickResult<SkillQuote>>;
+	runSkill<T = Record<string, unknown>>(skillId: string, input: Record<string, unknown>, options: SkillRunOptions): Promise<ApickResult<SkillRun<T>>>;
+	getSkillRun<T = Record<string, unknown>>(runId: string): Promise<ApickResult<SkillRun<T>>>;
+	getSkillRunResult<T = Record<string, unknown>>(runId: string): Promise<ApickResult<SkillRunResult<T>>>;
+	cancelSkillRun(runId: string): Promise<ApickResult<SkillRun>>;
+	skillUsage(options?: { cursor?: string; limit?: number }): Promise<ApickResult<SkillPage<SkillRun>>>;
+}
+
+export const SKILL_CATEGORIES: readonly ['data', 'ai', 'dev', 'document', 'marketing', 'finance', 'productivity', 'video', 'etc'];
+export type SkillCategory = typeof SKILL_CATEGORIES[number];
+export type SkillRunStatus = 'queued' | 'running' | 'completing' | 'succeeded' | 'failed' | 'timed_out' | 'cancelled';
+export type SkillBillingStatus = 'reserved' | 'captured' | 'released' | 'partially_refunded' | 'refunded';
+export type SkillFailureCode = 'EXECUTION_FAILED' | 'OUTPUT_INVALID' | 'TIMED_OUT' | 'CANCELLED' | 'UPSTREAM_UNAVAILABLE';
+/** `ApickApiError.serviceCode` 로 돌아오는 Skills 오류 코드 */
+export type SkillErrorCode =
+	| 'INVALID_INPUT' | 'AUTH_REQUIRED' | 'NOT_ALLOWED' | 'PAYMENT_REQUIRED' | 'SKILL_OR_RUN_NOT_FOUND'
+	| 'IDEMPOTENCY_KEY_REQUIRED' | 'IDEMPOTENCY_CONFLICT' | 'QUOTE_EXPIRED' | 'VERSION_UNAVAILABLE'
+	| 'PRICE_EXCEEDS_LIMIT' | 'RUN_NOT_CANCELLABLE' | 'RESULT_NOT_READY' | 'RESULT_EXPIRED'
+	| 'INSUFFICIENT_POINTS' | 'RATE_LIMITED' | 'BUDGET_EXCEEDED' | 'TEMPORARILY_UNAVAILABLE';
+export interface SkillSearchOptions { query?: string; category?: SkillCategory; cursor?: string; limit?: number; }
+export interface SkillRunOptions {
+	/** 이 실행을 구분하는 고유 값. 재시도할 때 같은 값을 씁니다. 영문·숫자와 `. _ : -` 1~128자 */
+	idempotencyKey: string;
+	version?: string;
+	quoteId?: string;
+	/** 가격이 이 값보다 높으면 실행하지 않습니다 */
+	maxCostPoints?: number;
+	/** 결과를 기다릴 시간(0~20초, 기본 20) */
+	waitSeconds?: number;
+}
+export interface SkillPage<T> { items: T[]; next_cursor: string | null; }
+export interface SkillLimits { max_input_chars: number; timeout_seconds: number; }
+export interface SkillSummary {
+	skill_id: string; slug: string; title: string; summary: string;
+	category: SkillCategory; category_label: string; version: string;
+	/** 실행마다 같은 기본 금액 / base amount charged on every run */
+	price_points: number;
+	/** 사용량까지 더한 예상 금액 / estimated amount including usage */
+	estimated_points: number;
+	/** true 면 실행마다 실제 사용량만큼 금액이 달라집니다 / amount varies per run with actual usage */
+	usage_priced: boolean;
+	seller: { name: string }; uses_generative_ai: boolean;
+}
+export interface SkillDetail extends SkillSummary {
+	description: string; billing_rule: 'validated_result'; limits: SkillLimits;
+	input_schema: Record<string, unknown>; output_schema: Record<string, unknown>;
+	examples: unknown[]; stats: Record<string, unknown> | null; published_at: string | null;
+}
+export interface SkillQuote {
+	quote_id: string; skill_id: string; version: string; price_points: number;
+	/** 이 입력의 예상 금액 / estimated amount for this input */
+	estimated_points: number;
+	/** 예약되는 최대 금액. 실제 차감액은 이 값을 넘지 않습니다 / maximum amount reserved; the charge never exceeds it */
+	max_points: number;
+	usage_priced: boolean;
+	expires_at: string; limits: SkillLimits; billing_rule: 'validated_result';
+}
+export interface SkillBilling { status: SkillBillingStatus; reserved_points: number; charged_points: number; refunded_points: number; }
+export interface SkillRun<T = Record<string, unknown>> {
+	run_id: string; status: SkillRunStatus;
+	skill: { id: string; version: string; title?: string };
+	billing: SkillBilling; created_at: string | null; completed_at: string | null;
+	links: { self: string; result?: string };
+	failure_code?: SkillFailureCode; result_expires_at?: string | null;
+	/** status 가 succeeded 일 때만 */
+	result?: T;
+}
+export interface SkillRunResult<T = Record<string, unknown>> {
+	run_id: string; skill: { id: string; version: string; title?: string };
+	result: T; result_expires_at: string | null;
 }
 
 export default ApickClient;

package/src/index.js

@@ -7,6 +7,7 @@ export const {
 	SERVICES,
 	TTS_VOICE_IDS,
 	AUTH_PROVIDERS,
+	SKILL_CATEGORIES,
 	DEFAULT_BASE_URL
 } = sdk;