apick-api 3.6.2 → 3.8.1

package/CHANGELOG.md

@@ -1,15 +1,33 @@
-# Changelog
+# Changelog
 
-## 3.6.2 — 2026-10-02
+## 3.8.1 — 2026-10-03
 
-- `TTS_VOICE_IDS`를 현재 지원하는 14개로 갱신했습니다. 제공이 종료된 `v2_ann_f_30s_01`, `v2_f_teen_01`을 상수·타입·문서에서 제거했으며, 이 값을 `voiceId`로 넘기면 요청 전에 `RangeError`가 발생합니다.
-- Update `TTS_VOICE_IDS` to the 14 currently supported voices. The retired `v2_ann_f_30s_01` and `v2_f_teen_01` are removed from the constant, types and docs; passing them as `voiceId` now throws a `RangeError` before the request is sent.
-- TTS 요금이 100자당 10포인트에서 "100자까지 30포인트, 이후 100자당 10포인트"로 바뀌었습니다(100자 30P, 101자 40P, 800자 100P). 한국어 읽기 자동 변환이 이 요금에 포함되며, 과금 기준은 계속 보낸 원문의 글자 수입니다.
-- TTS pricing changed from 10 points per 100 characters to 30 points for up to 100 characters plus 10 points for each additional 100 characters (100 chars 30P, 101 chars 40P, 800 chars 100P). Automatic Korean reading conversion is included, and billing is still based on the character count of the text you send.
-- 모든 TTS 요청에 한국어 읽기 전처리가 자동 적용되어 추가 옵션이나 별도 Skill 호출이 필요하지 않음을 README와 한국어·영어 가이드에 명시했습니다. 원문 기준 요금과 ASS 자막 표기는 유지되며, 정규화에 실패하면 원문으로 합성합니다. 공개 메서드와 요청·응답 형식은 변경하지 않았습니다.
-- Clarify in the README and Korean/English guides that every TTS request automatically applies Korean reading normalization, with no extra option or separate Skill call. Billing and ASS subtitle spelling remain based on the original text; failed normalization falls back to synthesis from that text. No public method or request/response format changes.
-
-## 3.6.1 — 2026-10-02
+- 상품별 조회 안내와 공통 인증 가이드 링크를 보강했습니다. API 계약 변경은 없습니다.
+- Document product-specific data guides and shared authentication; API contracts are unchanged.
+
+## 3.8.0 — 2026-10-03
+
+- 스킬 결과 파일 인증 다운로드와 예상 가격·시간·도구 호출 수 타입 추가.
+- Add authenticated Skill artifact downloads and execution estimate types.
+
+## 3.7.0 — 2026-10-02
+
+- `searchSkills()` 에 `sort` 를 추가했습니다: `recommended`(추천)·`popular`(인기)·`used`(많이 사용)·`likes`(좋아요순)·`rating`(평점순)·`new`(최신)·`mine`(내 계정이 많이 실행한 Skill)·`liked`(내 계정이 좋아요한 Skill). 생략하면 예전처럼 등록 순서입니다. 지원하지 않는 값은 요청 전에 `RangeError` 가 발생합니다. `SKILL_SORTS` 상수와 `SkillSort` 타입을 공개했습니다.
+- Add `sort` to `searchSkills()`: `recommended`, `popular`, `used`, `likes`, `rating`, `new`, `mine` and `liked` (the last two are scoped to the API key's account). Omitting it keeps registration order. Unsupported values throw a `RangeError` before the request is sent. Export `SKILL_SORTS` and the `SkillSort` type.
+- 검색·상세 응답 타입(`SkillSummary`·`SkillDetail`)에 `usage_label`(사용 건수 구간: `1,000회 미만`, `1,000+`, `1만+` …)·`like_count`·`review_count`·`rating_average` 를 추가했습니다. 검색어는 Skill 의 이름·요약·설명과 판매자 이름에서 찾습니다.
+- Add `usage_label` (a usage tier, not an exact count), `like_count`, `review_count` and `rating_average` to the search and detail response types (`SkillSummary`, `SkillDetail`). The search query now matches a Skill's name, summary, description and seller name.
+- 기존 메서드와 요청·응답 형식은 그대로입니다. / Existing methods and request/response formats are unchanged.
+
+## 3.6.2 — 2026-10-02
+
+- `TTS_VOICE_IDS`를 현재 지원하는 14개로 갱신했습니다. 제공이 종료된 `v2_ann_f_30s_01`, `v2_f_teen_01`을 상수·타입·문서에서 제거했으며, 이 값을 `voiceId`로 넘기면 요청 전에 `RangeError`가 발생합니다.
+- Update `TTS_VOICE_IDS` to the 14 currently supported voices. The retired `v2_ann_f_30s_01` and `v2_f_teen_01` are removed from the constant, types and docs; passing them as `voiceId` now throws a `RangeError` before the request is sent.
+- TTS 요금이 100자당 10포인트에서 "100자까지 30포인트, 이후 100자당 10포인트"로 바뀌었습니다(100자 30P, 101자 40P, 800자 100P). 한국어 읽기 자동 변환이 이 요금에 포함되며, 과금 기준은 계속 보낸 원문의 글자 수입니다.
+- TTS pricing changed from 10 points per 100 characters to 30 points for up to 100 characters plus 10 points for each additional 100 characters (100 chars 30P, 101 chars 40P, 800 chars 100P). Automatic Korean reading conversion is included, and billing is still based on the character count of the text you send.
+- 모든 TTS 요청에 한국어 읽기 전처리가 자동 적용되어 추가 옵션이나 별도 Skill 호출이 필요하지 않음을 README와 한국어·영어 가이드에 명시했습니다. 원문 기준 요금과 ASS 자막 표기는 유지되며, 정규화에 실패하면 원문으로 합성합니다. 공개 메서드와 요청·응답 형식은 변경하지 않았습니다.
+- Clarify in the README and Korean/English guides that every TTS request automatically applies Korean reading normalization, with no extra option or separate Skill call. Billing and ASS subtitle spelling remain based on the original text; failed normalization falls back to synthesis from that text. No public method or request/response format changes.
+
+## 3.6.1 — 2026-10-02
 
 - `createTtsJob()`으로 접수한 문장의 숫자·단위·기호·영문 약어를 문맥에 맞는 한글 읽기로 자동 변환해 합성한다는 안내를 README와 한국어·영어 가이드에 추가했습니다. 과금 글자 수와 요금은 보낸 원문 기준이고 요청·응답 형식은 그대로이며, ASS 자막은 보낸 원문 표기로 제공됩니다. 문서만 바뀌었습니다.
 - Document in the README and Korean/English guides that text passed to `createTtsJob()` has its numbers, units, symbols and English abbreviations automatically converted into context-appropriate Korean readings before synthesis. Billing is based on the text you send, request and response formats are unchanged, and ASS subtitles keep the text as you sent it. Documentation only.

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

@@ -130,6 +130,12 @@ while (!['succeeded', 'failed', 'timed_out', 'cancelled'].includes(run.status))
 console.log(run.status, run.billing, run.result);
 ```
 
+`searchSkills({ sort })` 로 추천(`recommended`)·인기(`popular`)·많이 사용(`used`)·좋아요순(`likes`)·평점순(`rating`)·최신(`new`) 순서를 고르고, 검색·상세 응답의 `usage_label`(사용 건수 구간)·`like_count`·`review_count`·`rating_average` 로 Skill 을 비교할 수 있습니다.
+Pick an order with `searchSkills({ sort })` (`recommended`, `popular`, `used`, `likes`, `rating`, `new`) and compare Skills with `usage_label` (a usage tier), `like_count`, `review_count` and `rating_average` in search and detail responses.
+
+`searchSkills({ sort })` 로 추천(`recommended`)·인기(`popular`)·많이 사용(`used`)·좋아요순(`likes`)·평점순(`rating`)·최신(`new`) 순서를 고르고, 검색·상세 응답의 `usage_label`(사용 건수 구간)·`like_count`·`review_count`·`rating_average` 로 Skill 을 비교할 수 있습니다.
+Pick an order with `searchSkills({ sort })` (`recommended`, `popular`, `used`, `likes`, `rating`, `new`) and compare Skills with `usage_label` (a usage tier), `like_count`, `review_count` and `rating_average` in search and detail responses.
+
 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`.
 
@@ -259,9 +265,9 @@ if (job.data.status === 'completed') {
 
 The charge is final when the job is accepted. Cancellation is allowed while `waiting` or `processing`. The MP3 and ASS subtitles can each be downloaded once. Starting either download immediately consumes that server copy, so an interrupted transfer cannot be downloaded again.
 
-`createTtsJob()`으로 접수한 문장의 숫자·단위·기호·영문은 문맥에 맞는 한글 읽기로 자동 변환한 뒤 음성을 생성합니다(예: `5번 버스` → 오 번 버스, `버튼을 5번` → 다섯 번, `-5℃` → 영하 오 도, `인증번호 105028` → 한 자리씩). 모든 TTS 요청에 자동 적용되므로 추가 옵션이나 별도 Skill 호출이 필요하지 않습니다. 과금 글자 수와 요금은 보낸 원문 기준이며 요청·응답 형식은 그대로입니다. 요금은 100자까지 30포인트이고 이후 100자마다 10포인트가 추가되며, 자동 변환에 따른 추가 요금은 없습니다. 읽는 법을 직접 정하려면 한글로 풀어 써서 보내세요. ASS 자막은 보낸 원문 표기로 제공됩니다. 정규화에 실패하면 원문으로 음성을 생성합니다.
+`createTtsJob()`으로 접수한 문장의 숫자·단위·기호·영문은 문맥에 맞는 한글 읽기로 자동 변환한 뒤 음성을 생성합니다(예: `5번 버스` → 오 번 버스, `버튼을 5번` → 다섯 번, `-5℃` → 영하 오 도, `인증번호 105028` → 한 자리씩). 모든 TTS 요청에 자동 적용되므로 추가 옵션이나 별도 Skill 호출이 필요하지 않습니다. 과금 글자 수와 요금은 보낸 원문 기준이며 요청·응답 형식은 그대로입니다. 요금은 100자까지 30포인트이고 이후 100자마다 10포인트가 추가되며, 자동 변환에 따른 추가 요금은 없습니다. 읽는 법을 직접 정하려면 한글로 풀어 써서 보내세요. ASS 자막은 보낸 원문 표기로 제공됩니다. 정규화에 실패하면 원문으로 음성을 생성합니다.
 
-Numbers, units, symbols and English text in the text passed to `createTtsJob()` are automatically converted into context-appropriate Korean readings before synthesis (for example, `5번 버스` is read as "오 번 버스", `버튼을 5번` as "다섯 번", `-5℃` as "영하 오 도", and `인증번호 105028` digit by digit). This applies automatically to every TTS request; no extra option or separate Skill call is needed. The billed character count and price are based on the text you send, and the request and response formats are unchanged. The price is 30 points for up to 100 characters plus 10 points for each additional 100 characters, with no extra charge for the automatic conversion. To choose a reading yourself, spell it out in Hangul. ASS subtitles keep the text as you sent it. If normalization fails, speech is generated from the original text.
+Numbers, units, symbols and English text in the text passed to `createTtsJob()` are automatically converted into context-appropriate Korean readings before synthesis (for example, `5번 버스` is read as "오 번 버스", `버튼을 5번` as "다섯 번", `-5℃` as "영하 오 도", and `인증번호 105028` digit by digit). This applies automatically to every TTS request; no extra option or separate Skill call is needed. The billed character count and price are based on the text you send, and the request and response formats are unchanged. The price is 30 points for up to 100 characters plus 10 points for each additional 100 characters, with no extra charge for the automatic conversion. To choose a reading yourself, spell it out in Hangul. ASS subtitles keep the text as you sent it. If normalization fails, speech is generated from the original text.
 
 ## 신분증 마스킹 / Identity masking
 
@@ -449,3 +455,7 @@ if (status.data.status === "completed") {
   await (await client.downloadVideoResult("kling", job.data.job_id)).save("boat.mp4");
 }
 ```
+
+### 스킬 결과 파일 / Skill result files
+
+`getSkillArtifact(runId, fileId)` returns authenticated binary artifacts. 가격·시간·호출 수 범위와 다운로드 예제: [스킬 파일 가이드 / guide](docs/skill-artifacts.md).

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

@@ -90,7 +90,7 @@ TTS supports 14 voice IDs. Use `TTS_VOICE_IDS` and the developer guide for the c
 
 `v2_ann_m_30s_01`, `v2_ann_m_30s_02`, `v2_ann_m_30s_04`, `v2_ann_m_30s_05`, `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_young_01`, `v2_f_senior_01`
 
-Numbers, units, symbols and English text in the text passed to `createTtsJob()` are automatically converted into context-appropriate Korean readings before synthesis (for example, `5번 버스` is read as "오 번 버스", `버튼을 5번` as "다섯 번", `-5℃` as "영하 오 도", and `인증번호 105028` digit by digit). This applies automatically to every TTS request; no extra option or separate Skill call is needed. The billed character count and price are based on the text you send, and the request and response formats are unchanged. The price is 30 points for up to 100 characters plus 10 points for each additional 100 characters, with no extra charge for the automatic conversion. To choose a reading yourself, spell it out in Hangul. ASS subtitles keep the text as you sent it. If normalization fails, speech is generated from the original text.
+Numbers, units, symbols and English text in the text passed to `createTtsJob()` are automatically converted into context-appropriate Korean readings before synthesis (for example, `5번 버스` is read as "오 번 버스", `버튼을 5번` as "다섯 번", `-5℃` as "영하 오 도", and `인증번호 105028` digit by digit). This applies automatically to every TTS request; no extra option or separate Skill call is needed. The billed character count and price are based on the text you send, and the request and response formats are unchanged. The price is 30 points for up to 100 characters plus 10 points for each additional 100 characters, with no extra charge for the automatic conversion. To choose a reading yourself, spell it out in Hangul. ASS subtitles keep the text as you sent it. If normalization fails, speech is generated from the original text.
 
 ```js
 const screenshot = await client.screenshot('https://example.com');
@@ -300,7 +300,7 @@ 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` |
+| `searchSkills({ query, category, sort, cursor, limit })` | Search. `limit` 1-20; `category` is one of `SKILL_CATEGORIES`, `sort` one of `SKILL_SORTS` |
 | `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) |
@@ -308,6 +308,10 @@ console.log(run.status, run.billing, run.result);
 | `cancelSkillRun(runId)` | Cancel an unfinished run. Cancelled runs are not charged |
 | `skillUsage({ cursor, limit })` | Your runs. `limit` 1-50 |
 
+- `sort` is one of `recommended`, `popular`, `used` (most run), `likes`, `rating`, `new`, `mine` (Skills your account runs most) and `liked` (Skills your account liked). Omit it for registration order.
+- Search and detail responses include `usage_label` (a usage tier such as `1,000회 미만` (under 1,000), `1,000+`, `1만+` (10,000+), not an exact count), `like_count`, `review_count` and `rating_average` (1-5, `null` without reviews). Likes and reviews are left on the Skill page of the APICK website.
+- `sort` is one of `recommended`, `popular`, `used` (most run), `likes`, `rating`, `new`, `mine` (Skills your account runs most) and `liked` (Skills your account liked). Omit it for registration order.
+- Search and detail responses include `usage_label` (a usage tier such as `1,000회 미만` (under 1,000), `1,000+`, `1만+` (10,000+), not an exact count), `like_count`, `review_count` and `rating_average` (1-5, `null` without reviews). Likes and reviews are left on the Skill page of the APICK website.
 - 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`.
@@ -341,3 +345,11 @@ if (status.data.status === "completed") {
   await (await client.downloadVideoResult("kling", job.data.job_id)).save("boat.mp4");
 }
 ```
+
+## Skill artifacts and execution estimates
+
+Skill details and quotes provide estimated price and duration ranges and tool call counts. Check the maximum reservation before execution, then use getSkillArtifact(runId, fileId) to download files with authentication. See [Skill artifacts](skill-artifacts.md) for fields and examples.
+
+## Product-specific data guides
+
+Product-specific authenticated-data guides describe returned fields, source institutions, use cases, and FAQs. An authentication request starts access to the selected product and returns a transactionId for result polling. Request and response contracts and authentication are unchanged. See the [shared authentication guide](https://apick.app/dev_guide/data) for the flow and error handling.

package/docs/guide.ko.md

@@ -90,7 +90,7 @@ TTS는 14개 목소리 ID를 지원합니다. 정확한 목록은 `TTS_VOICE_IDS
 
 `v2_ann_m_30s_01`, `v2_ann_m_30s_02`, `v2_ann_m_30s_04`, `v2_ann_m_30s_05`, `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_young_01`, `v2_f_senior_01`
 
-`createTtsJob()`으로 접수한 문장의 숫자·단위·기호·영문은 문맥에 맞는 한글 읽기로 자동 변환한 뒤 음성을 생성합니다(예: `5번 버스` → 오 번 버스, `버튼을 5번` → 다섯 번, `-5℃` → 영하 오 도, `인증번호 105028` → 한 자리씩). 모든 TTS 요청에 자동 적용되므로 추가 옵션이나 별도 Skill 호출이 필요하지 않습니다. 과금 글자 수와 요금은 보낸 원문 기준이며 요청·응답 형식은 그대로입니다. 요금은 100자까지 30포인트이고 이후 100자마다 10포인트가 추가되며, 자동 변환에 따른 추가 요금은 없습니다. 읽는 법을 직접 정하려면 한글로 풀어 써서 보내세요. ASS 자막은 보낸 원문 표기로 제공됩니다. 정규화에 실패하면 원문으로 음성을 생성합니다.
+`createTtsJob()`으로 접수한 문장의 숫자·단위·기호·영문은 문맥에 맞는 한글 읽기로 자동 변환한 뒤 음성을 생성합니다(예: `5번 버스` → 오 번 버스, `버튼을 5번` → 다섯 번, `-5℃` → 영하 오 도, `인증번호 105028` → 한 자리씩). 모든 TTS 요청에 자동 적용되므로 추가 옵션이나 별도 Skill 호출이 필요하지 않습니다. 과금 글자 수와 요금은 보낸 원문 기준이며 요청·응답 형식은 그대로입니다. 요금은 100자까지 30포인트이고 이후 100자마다 10포인트가 추가되며, 자동 변환에 따른 추가 요금은 없습니다. 읽는 법을 직접 정하려면 한글로 풀어 써서 보내세요. ASS 자막은 보낸 원문 표기로 제공됩니다. 정규화에 실패하면 원문으로 음성을 생성합니다.
 
 ```js
 const screenshot = await client.screenshot('https://example.com');
@@ -302,7 +302,7 @@ console.log(run.status, run.billing, run.result);
 
 | 메서드 | 설명 |
 | --- | --- |
-| `searchSkills({ query, category, cursor, limit })` | 검색. `limit` 1~20, `category` 는 `SKILL_CATEGORIES` 중 하나 |
+| `searchSkills({ query, category, sort, cursor, limit })` | 검색. `limit` 1~20, `category` 는 `SKILL_CATEGORIES`, `sort` 는 `SKILL_SORTS` 중 하나 |
 | `getSkill(skillId)` | 입력·결과 형식, 가격, 처리 상한, 예제 |
 | `quoteSkill(skillId, input, { version })` | 입력 검사와 차감될 포인트 확인. 실행하지 않습니다 |
 | `runSkill(skillId, input, { idempotencyKey, quoteId, maxCostPoints, version, waitSeconds })` | 실행. `idempotencyKey` 필수, `waitSeconds` 0~20(기본 20) |
@@ -310,6 +310,10 @@ console.log(run.status, run.billing, run.result);
 | `cancelSkillRun(runId)` | 끝나지 않은 실행 취소. 취소된 실행은 차감되지 않습니다 |
 | `skillUsage({ cursor, limit })` | 내 실행 내역. `limit` 1~50 |
 
+- `sort` 는 `recommended`(추천)·`popular`(인기)·`used`(많이 사용)·`likes`(좋아요순)·`rating`(평점순)·`new`(최신)·`mine`(내 계정이 많이 실행한 Skill)·`liked`(내 계정이 좋아요한 Skill) 가운데 하나입니다. 생략하면 등록 순서입니다.
+- 검색·상세 응답에는 고를 때 참고하는 `usage_label`(사용 건수 구간: `1,000회 미만`, `1,000+`, `1만+` …), `like_count`, `review_count`, `rating_average`(1~5, 리뷰가 없으면 `null`)가 있습니다. 좋아요와 리뷰는 에이픽 웹의 Skill 화면에서 남깁니다.
+- `sort` 는 `recommended`(추천)·`popular`(인기)·`used`(많이 사용)·`likes`(좋아요순)·`rating`(평점순)·`new`(최신)·`mine`(내 계정이 많이 실행한 Skill)·`liked`(내 계정이 좋아요한 Skill) 가운데 하나입니다. 생략하면 등록 순서입니다.
+- 검색·상세 응답에는 고를 때 참고하는 `usage_label`(사용 건수 구간: `1,000회 미만`, `1,000+`, `1만+` …), `like_count`, `review_count`, `rating_average`(1~5, 리뷰가 없으면 `null`)가 있습니다. 좋아요와 리뷰는 에이픽 웹의 Skill 화면에서 남깁니다.
 - Skills 응답은 봉투 없이 `data` 에 그대로 담기며, 과금 상태는 `data.billing.status`(`reserved`·`captured`·`released`·`partially_refunded`·`refunded`)로 확인합니다. `meta.cost` 는 채워지지 않습니다.
 - 20초 안에 끝나지 않으면 `status` 가 `queued`·`running` 인 채로 돌아오므로 `getSkillRun` 으로 확인하세요.
 - 응답을 받지 못했을 때는 같은 `idempotencyKey` 로 다시 호출하세요. 포인트는 한 번만 차감됩니다. 같은 키에 다른 입력을 보내면 `IDEMPOTENCY_CONFLICT` 입니다.
@@ -349,3 +353,11 @@ if (status.data.status === "completed") {
   await (await client.downloadVideoResult("kling", job.data.job_id)).save("boat.mp4");
 }
 ```
+
+## 스킬 결과 파일과 실행 예상
+
+스킬 상세·견적은 가격과 시간 범위, 도구별 예상 호출 수를 제공합니다. 실행 전 최대 예약액을 확인하고, 성공 결과의 파일은 인증이 적용되는 getSkillArtifact(runId, fileId)로 내려받으세요. 자세한 필드와 예시는 [스킬 결과 파일 안내](skill-artifacts.md)를 참고하세요.
+
+## 상품별 조회 가이드
+
+상품별 간편인증 조회 가이드에는 조회 데이터, 출처 기관, 활용 사례와 자주 묻는 질문이 있습니다. 인증 요청은 해당 상품의 자료를 조회하기 위한 단계이며 결과 조회용 transactionId를 반환합니다. 요청·응답 계약과 인증 방식은 동일합니다. [공통 인증 흐름](https://apick.app/dev_guide/data)에서 절차와 오류 처리를 확인하세요.

package/docs/skill-artifacts.md

@@ -0,0 +1,24 @@
+# 스킬 결과 파일 · Skill artifacts
+
+스킬 상세와 견적의 `execution_info`는 예상 가격 범위, 처리 시간 범위, 도구별 보통·최대 호출 수를 제공합니다. 실측 표본에 따른 예상이며 입력에 따라 달라집니다. 실행 전 견적의 `max_points`를 확인하세요.
+
+`execution_info` on Skill details and quotes describes estimated price and duration ranges and typical/maximum tool calls. These are estimates, not guarantees. Check `max_points` before running a Skill.
+
+```js
+const quote = await apick.quoteSkill(skillId, input);
+console.log(quote.data.execution_info);
+const run = await apick.runSkill(skillId, input, {
+  idempotencyKey: 'my-unique-request',
+  quoteId: quote.data.quote_id,
+  maxCostPoints: quote.data.max_points
+});
+// Poll getSkillRun until status is succeeded, then:
+const result = await apick.getSkillRunResult(run.data.run_id);
+const file = result.data.result.artifacts[0];
+const downloaded = await apick.getSkillArtifact(run.data.run_id, file.id);
+await downloaded.save('./result.png');
+```
+
+파일의 `name`, `mime_type`, `bytes`, `sha256`을 확인하고 실제 형식에 맞는 확장자로 저장하세요. 인증키 소유자의 실행 파일만 내려받을 수 있고, 실행 결과가 만료되면 파일도 만료됩니다. 실패·취소·시간 초과는 예약액을 반환하며, 가변 요금 상품은 성공 시 실제 사용료를 정산합니다. 공급자 청구서와 대조한 확정 원가를 뜻하지 않습니다.
+
+Use `name`, `mime_type`, `bytes`, and `sha256` to identify and verify each file; choose a matching extension. Downloads require the run owner's API key and expire with the result. Failed, cancelled, and timed-out runs release the reservation. Variable-price Skills settle recorded tool usage on success; calculated vendor costs are not invoice-reconciled amounts.

package/package.json

@@ -1,71 +1,71 @@
-{
-  "name": "apick-api",
-  "version": "3.6.2",
-  "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",
-  "module": "./src/index.js",
-  "types": "./src/index.d.ts",
-  "exports": {
-    ".": {
-      "types": "./src/index.d.ts",
-      "import": "./src/index.js",
-      "require": "./src/index.cjs"
-    }
-  },
-  "files": [
-    "src",
-    "docs",
-    "examples",
-    "README.md",
-    "CHANGELOG.md",
-    "SECURITY.md",
-    "LICENSE"
-  ],
-  "sideEffects": false,
-  "engines": {
-    "node": ">=18"
-  },
-  "scripts": {
-    "test": "node --test && npm run test:types",
-    "test:types": "tsc -p tsconfig.json",
-    "test:coverage": "node --test --experimental-test-coverage",
-    "prepublishOnly": "npm test"
-  },
-  "devDependencies": {
-    "typescript": "^7.0.2"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/lead788/apick-api.git"
-  },
-  "bugs": {
-    "url": "https://github.com/lead788/apick-api/issues"
-  },
-  "homepage": "https://apick.app/dev_guide",
-  "license": "MIT",
-  "author": "APICK",
-  "publishConfig": {
-    "access": "public",
-    "provenance": false
-  },
-  "keywords": [
-    "apick",
-    "api",
-    "sdk",
-    "korea",
-    "korean-api",
-    "business-registry",
-    "parcel-tracking",
-    "address",
-    "ocr",
-    "whois",
-    "dns",
-    "google-search",
-    "pdf",
-    "excel",
-    "tts-jobs",
-    "text-summary",
-    "image-generation"
-  ]
-}
+{
+  "name": "apick-api",
+  "version": "3.8.1",
+  "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",
+  "module": "./src/index.js",
+  "types": "./src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "import": "./src/index.js",
+      "require": "./src/index.cjs"
+    }
+  },
+  "files": [
+    "src",
+    "docs",
+    "examples",
+    "README.md",
+    "CHANGELOG.md",
+    "SECURITY.md",
+    "LICENSE"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "test": "node --test && npm run test:types",
+    "test:types": "tsc -p tsconfig.json",
+    "test:coverage": "node --test --experimental-test-coverage",
+    "prepublishOnly": "npm test"
+  },
+  "devDependencies": {
+    "typescript": "^7.0.2"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/lead788/apick-api.git"
+  },
+  "bugs": {
+    "url": "https://github.com/lead788/apick-api/issues"
+  },
+  "homepage": "https://apick.app/dev_guide",
+  "license": "MIT",
+  "author": "APICK",
+  "publishConfig": {
+    "access": "public",
+    "provenance": false
+  },
+  "keywords": [
+    "apick",
+    "api",
+    "sdk",
+    "korea",
+    "korean-api",
+    "business-registry",
+    "parcel-tracking",
+    "address",
+    "ocr",
+    "whois",
+    "dns",
+    "google-search",
+    "pdf",
+    "excel",
+    "tts-jobs",
+    "text-summary",
+    "image-generation"
+  ]
+}

package/src/index.cjs

@@ -177,6 +177,8 @@ 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);
+const SKILL_SORTS = Object.freeze(['recommended', 'popular', 'used', 'likes', 'rating', 'new', 'mine', 'liked']);
+const SKILL_SORT_SET = new Set(SKILL_SORTS);
 
 function normalizeSkillId(value) {
 	return encodeURIComponent(requiredString('skillId', value, 80));
@@ -935,6 +937,11 @@ class ApickClient {
 			if (!SKILL_CATEGORY_SET.has(category)) throw new RangeError('category must be one of the supported Skill categories.');
 			query.category = category;
 		}
+		if (config.sort !== undefined && config.sort !== null && config.sort !== '') {
+			const sort = requiredString('sort', config.sort);
+			if (!SKILL_SORT_SET.has(sort)) throw new RangeError('sort must be one of the supported Skill sort orders.');
+			query.sort = sort;
+		}
 		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);
@@ -979,6 +986,41 @@ class ApickClient {
 		return this._skills('GET', '/rest/skills/runs/' + normalizeSkillRunId(runId) + '/result');
 	}
 
+	/** Download a file from a completed run owned by this API key. */
+	async getSkillArtifact(runId, fileId) {
+		const run = normalizeSkillRunId(runId);
+		if (typeof fileId !== 'string' || !/^art_[a-f0-9]{24}$/.test(fileId)) throw new TypeError('fileId must be an artifact ID from a Skill result.');
+		const controller = new AbortController();
+		const timeoutMs = this.#timeoutMs || DEFAULT_TIMEOUT_MS;
+		const timer = setTimeout(() => controller.abort(), timeoutMs);
+		try {
+			const response = await this.#fetch(this.#baseUrl + '/rest/skills/runs/' + run + '/files/' + fileId + '?download=1', {
+				method: 'GET', headers: { Authorization: `Bearer ${this.#apiKey}` }, signal: controller.signal, redirect: 'error'
+			});
+			if (!response.ok) {
+				let body; try { body = await response.json(); } catch { body = null; }
+				throw new ApickApiError('APICK artifact download failed.', { status: response.status, code: response.status === 401 ? 'APICK_AUTH_ERROR' : 'APICK_API_ERROR', serviceCode: body && body.error && body.error.code });
+			}
+			const limit = 200 * 1024 * 1024;
+			if (Number(response.headers.get('content-length')) > limit) { controller.abort(); throw new ApickApiError('APICK artifact exceeds the size limit.', { code: 'APICK_INVALID_RESPONSE' }); }
+			const reader = response.body.getReader(), chunks = []; let size = 0;
+			try {
+				while (true) {
+					const item = await reader.read(); if (item.done) break;
+					size += item.value.byteLength;
+					if (size > limit) { await reader.cancel(); throw new ApickApiError('APICK artifact exceeds the size limit.', { code: 'APICK_INVALID_RESPONSE' }); }
+					chunks.push(item.value);
+				}
+			} finally { reader.releaseLock(); }
+			const bytes = new Uint8Array(size); let offset = 0;
+			for (const chunk of chunks) { bytes.set(chunk, offset); offset += chunk.byteLength; }
+			return new ApickBinaryResult(bytes, { contentType: (response.headers.get('content-type') || '').split(';')[0], filename: parseFilename(response.headers.get('content-disposition'), 'result.bin'), meta: responseMeta(null, response.headers) });
+		} catch (error) {
+			if (error instanceof ApickApiError) throw error;
+			throw new ApickApiError(controller.signal.aborted ? 'APICK artifact download timed out.' : redact(error && error.message || 'APICK download failed.', this.#apiKey), { code: controller.signal.aborted ? 'APICK_TIMEOUT' : 'APICK_NETWORK_ERROR' });
+		} finally { clearTimeout(timer); }
+	}
+
 	cancelSkillRun(runId) {
 		return this._skills('POST', '/rest/skills/runs/' + normalizeSkillRunId(runId) + '/cancel', { body: {} });
 	}
@@ -1001,5 +1043,6 @@ module.exports = {
 	TTS_VOICE_IDS,
 	AUTH_PROVIDERS,
 	SKILL_CATEGORIES,
+	SKILL_SORTS,
 	DEFAULT_BASE_URL
 };

package/src/index.d.ts

@@ -329,12 +329,17 @@ export class ApickClient {
 	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>>>;
+	/** 본인 실행의 결과 파일을 인증해 내려받습니다. / Download an artifact owned by this API key. */
+	getSkillArtifact(runId: string, fileId: string): Promise<ApickBinaryResult>;
 	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];
+/** 검색 순서. 생략하면 등록 순서 / search order; registration order when omitted */
+export const SKILL_SORTS: readonly ['recommended', 'popular', 'used', 'likes', 'rating', 'new', 'mine', 'liked'];
+export type SkillSort = typeof SKILL_SORTS[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';
@@ -344,7 +349,12 @@ export type SkillErrorCode =
 	| '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 SkillSearchOptions {
+	query?: string; category?: SkillCategory;
+	/** `mine`·`liked` 는 인증키의 계정 기준 / `mine` and `liked` are scoped to the API key's account */
+	sort?: SkillSort;
+	cursor?: string; limit?: number;
+}
 export interface SkillRunOptions {
 	/** 이 실행을 구분하는 고유 값. 재시도할 때 같은 값을 씁니다. 영문·숫자와 `. _ : -` 1~128자 */
 	idempotencyKey: string;
@@ -358,6 +368,8 @@ export interface SkillRunOptions {
 export interface SkillPage<T> { items: T[]; next_cursor: string | null; }
 export interface SkillLimits { max_input_chars: number; timeout_seconds: number; }
 export interface SkillSummary {
+	execution_info?: SkillExecutionInfo;
+	price_label?: string;
 	skill_id: string; slug: string; title: string; summary: string;
 	category: SkillCategory; category_label: string; version: string;
 	/** 실행마다 같은 기본 금액 / base amount charged on every run */
@@ -367,6 +379,12 @@ export interface SkillSummary {
 	/** true 면 실행마다 실제 사용량만큼 금액이 달라집니다 / amount varies per run with actual usage */
 	usage_priced: boolean;
 	seller: { name: string }; uses_generative_ai: boolean;
+	/** 사용 건수 구간. 예: `1,000회 미만`, `1,000+`, `1만+` / usage tier label, not an exact count */
+	usage_label: string;
+	like_count: number;
+	review_count: number;
+	/** 평점(1~5, 소수 첫째 자리). 리뷰가 없으면 null / average rating, null without reviews */
+	rating_average: number | null;
 }
 export interface SkillDetail extends SkillSummary {
 	description: string; billing_rule: 'validated_result'; limits: SkillLimits;
@@ -374,6 +392,7 @@ export interface SkillDetail extends SkillSummary {
 	examples: unknown[]; stats: Record<string, unknown> | null; published_at: string | null;
 }
 export interface SkillQuote {
+	execution_info?: SkillExecutionInfo;
 	quote_id: string; skill_id: string; version: string; price_points: number;
 	/** 이 입력의 예상 금액 / estimated amount for this input */
 	estimated_points: number;
@@ -383,6 +402,16 @@ export interface SkillQuote {
 	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 SkillExecutionInfo {
+	price_range: { min_points: number; max_points: number; variable: boolean };
+	duration: { min_seconds: number; max_seconds: number; basis: string };
+	tools: Array<{ name: string; typical_calls: number | string; max_calls: number | string; min_calls?: number }>;
+	billing_note: string;
+}
+export interface SkillArtifact {
+	id: string; name: string; mime_type: string; url: string; sha256: string; bytes: number;
+	label?: string; width?: number; height?: number; seconds?: number;
+}
 export interface SkillRun<T = Record<string, unknown>> {
 	run_id: string; status: SkillRunStatus;
 	skill: { id: string; version: string; title?: string };

package/src/index.js

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