apick-api 3.6.0 → 3.7.0

package/CHANGELOG.md

@@ -1,4 +1,26 @@
-# Changelog
+# Changelog
+
+## 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.
 
 ## 3.6.0 — 2026-10-02
 

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`.
 
@@ -231,9 +237,9 @@ await excel.save('./scores.xlsx');
 
 The legacy synchronous TTS API has retired. Create a Korean narration job, poll every 2–5 seconds until it is `completed`, then download the MP3 result once.
 
-TTS supports 16 voice IDs. Use `TTS_VOICE_IDS` and the developer guide for the current list.
+TTS supports 14 voice IDs. Use `TTS_VOICE_IDS` and the developer guide for the current list.
 
-`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`
+`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`
 
 ```js
 const created = await apick.createTtsJob('오늘의 이야기를 시작합니다.', {
@@ -259,6 +265,10 @@ 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 자막은 보낸 원문 표기로 제공됩니다. 정규화에 실패하면 원문으로 음성을 생성합니다.
+
+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
 
 ```js

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

@@ -86,9 +86,11 @@ await client.ocr(bytes, {
 
 ## Generated files
 
-TTS supports 16 voice IDs. Use `TTS_VOICE_IDS` and the developer guide for the current list.
+TTS supports 14 voice IDs. Use `TTS_VOICE_IDS` and the developer guide for the current list.
 
-`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`
+`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.
 
 ```js
 const screenshot = await client.screenshot('https://example.com');
@@ -298,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) |
@@ -306,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`.

package/docs/guide.ko.md

@@ -86,9 +86,11 @@ await client.ocr(bytes, {
 
 ## 파일 생성
 
-TTS는 16개 목소리 ID를 지원합니다. 정확한 목록은 `TTS_VOICE_IDS` 상수와 개발가이드에서 확인합니다.
+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_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`
+`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 자막은 보낸 원문 표기로 제공됩니다. 정규화에 실패하면 원문으로 음성을 생성합니다.
 
 ```js
 const screenshot = await client.screenshot('https://example.com');
@@ -300,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) |
@@ -308,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` 입니다.

package/package.json

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

@@ -7,7 +7,7 @@ const MAX_IMAGE_AI_BYTES = 50 * 1024 * 1024;
 const IMAGE_AI_SIZES = Object.freeze(['1024x1024', '1536x1024', '1024x1536', '1152x864', '864x1152']);
 const IMAGE_AI_SIZE_SET = new Set(IMAGE_AI_SIZES);
 const TTS_VOICE_IDS = Object.freeze([
-	'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'
+	'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'
 ]);
 const TTS_VOICE_ID_SET = new Set(TTS_VOICE_IDS);
 const AUTH_PROVIDERS = Object.freeze([
@@ -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);
@@ -1001,5 +1008,6 @@ module.exports = {
 	TTS_VOICE_IDS,
 	AUTH_PROVIDERS,
 	SKILL_CATEGORIES,
+	SKILL_SORTS,
 	DEFAULT_BASE_URL
 };

package/src/index.d.ts

@@ -200,7 +200,7 @@ export interface YoutubeSubtitleList {
 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'
+	'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'
 ];
 export type TtsVoiceId = typeof TTS_VOICE_IDS[number];
 
@@ -335,6 +335,9 @@ export class ApickClient {
 
 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 +347,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;
@@ -367,6 +375,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;

package/src/index.js

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