apick-api 3.5.0 → 3.6.0

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # 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)로 조회합니다.

package/LICENSE

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

package/README.md

@@ -101,6 +101,40 @@ Leave the allowed-IP list blank for unrestricted access. To restrict access, reg
 | `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
 

package/SECURITY.md

@@ -1,11 +1,11 @@
-# Security
-
-## API keys
-
-Keep APICK API keys in server-side environment variables. Do not commit keys, include them in client-side browser bundles, place them in URLs, or print them in logs.
-
-If a key may have been exposed, regenerate it from your APICK account immediately.
-
-## Reporting a vulnerability
-
-Please report security issues privately through the contact channel listed at <https://apick.app>. Do not open a public issue containing credentials, personal data, or exploit details.
+# Security
+
+## API keys
+
+Keep APICK API keys in server-side environment variables. Do not commit keys, include them in client-side browser bundles, place them in URLs, or print them in logs.
+
+If a key may have been exposed, regenerate it from your APICK account immediately.
+
+## Reporting a vulnerability
+
+Please report security issues privately through the contact channel listed at <https://apick.app>. Do not open a public issue containing credentials, personal data, or exploit details.

package/docs/guide.en.md

@@ -270,6 +270,48 @@ Sources: [APICK development guide](https://apick.app/dev_guide/data_health_check
 
 `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
 
 `ApickApiError` includes public error information: `code`, optional `serviceCode`, `status`, and `message`. The SDK does not retry automatically because a retry could duplicate an API call and its charge. If your application needs retries, decide explicitly after checking the error code and whether the operation is safe to repeat.

package/docs/guide.ko.md

@@ -272,6 +272,48 @@ try {
 
 `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 로 결과를 만듭니다. 중요한 판단에 쓰기 전에 확인하세요.
+
 ## 오류와 재시도
 
 `ApickApiError`에는 공개 오류 정보인 `code`, `serviceCode`, `status`, `message`가 포함됩니다. SDK는 중복 호출과 중복 과금을 방지하기 위해 자동 재시도를 하지 않습니다. 재시도가 필요하면 작업의 멱등성과 오류 코드를 확인한 뒤 애플리케이션에서 명시적으로 결정하세요.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "apick-api",
-  "version": "3.5.0",
+  "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

@@ -175,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);
@@ -268,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() {
@@ -847,6 +869,128 @@ class ApickClient {
 	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 = {
@@ -856,5 +1000,6 @@ module.exports = {
 	SERVICES,
 	TTS_VOICE_IDS,
 	AUTH_PROVIDERS,
+	SKILL_CATEGORIES,
 	DEFAULT_BASE_URL
 };

package/src/index.d.ts

@@ -232,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;
@@ -321,6 +323,78 @@ export class ApickClient {
 	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

@@ -1,13 +1,14 @@
-import sdk from './index.cjs';
-
-export const {
-	ApickClient,
-	ApickApiError,
-	ApickBinaryResult,
-	SERVICES,
-	TTS_VOICE_IDS,
-	AUTH_PROVIDERS,
-	DEFAULT_BASE_URL
-} = sdk;
-
-export default ApickClient;
+import sdk from './index.cjs';
+
+export const {
+	ApickClient,
+	ApickApiError,
+	ApickBinaryResult,
+	SERVICES,
+	TTS_VOICE_IDS,
+	AUTH_PROVIDERS,
+	SKILL_CATEGORIES,
+	DEFAULT_BASE_URL
+} = sdk;
+
+export default ApickClient;