apick-api 3.8.1 → 3.9.0

package/CHANGELOG.md

@@ -1,9 +1,14 @@
-# Changelog
+# Changelog
 
-## 3.8.1 — 2026-10-03
+## 3.9.0 — 2026-10-04
 
-- 상품별 조회 안내와 공통 인증 가이드 링크를 보강했습니다. API 계약 변경은 없습니다.
-- Document product-specific data guides and shared authentication; API contracts are unchanged.
+- `getSkillPerformance()`와 공개 성능표 타입을 추가했습니다. 시험 방식·표본 수·평가일·성공률 구간·미검증 상태를 확인할 수 있습니다.
+- Add `getSkillPerformance()` and report types for methods, sample sizes, evaluation dates, success-rate intervals and untested states.
+
+## 3.8.1 — 2026-10-03
+
+- 상품별 조회 안내와 공통 인증 가이드 링크를 보강했습니다. API 계약 변경은 없습니다.
+- Document product-specific data guides and shared authentication; API contracts are unchanged.
 
 ## 3.8.0 — 2026-10-03
 

package/README.md

@@ -101,7 +101,8 @@ 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 |
+| `searchSkills(options)` / `getSkill(skillId)` | Skill 검색·상세 / Search and inspect Skills | JSON |
+| `getSkillPerformance()` | 시험 방법·표본 수·기계 검사·품질 점수 / Measured results and methods | 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 |
@@ -115,7 +116,7 @@ Search and run reviewed Skills. Points are charged only when a result in the pro
 ```js
 import { randomUUID } from 'node:crypto';
 
-const found = await apick.searchSkills({ query: '상품명', limit: 5 });
+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: '튼튼한 접이식 우산' };
@@ -130,7 +131,11 @@ 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 을 비교할 수 있습니다.
+검증 결과는 [스킬 성능표](https://apick.app/skills/performance) 또는 `const { data } = await apick.getSkillPerformance()`로 확인합니다. 표본 수·시험일·방법·기계 검사 통과율과 모델 평가 점수를 함께 읽으세요. 미검증 값은 `null`이며, 과거의 다른 조건에서 얻은 점수는 `legacy`로 구분합니다. 모델 점수는 객관적 정확도나 판매 성과 보장이 아닙니다.
+
+See the [Skill performance report](https://apick.app/skills/performance) or call `const { data } = await apick.getSkillPerformance()`. Read sample sizes, dates, methods, machine checks and model scores together. Unmeasured values are `null`; historical results under different conditions are in `legacy`. Model scores are not objective accuracy or sales guarantees.
+
+`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 을 비교할 수 있습니다.

package/docs/guide.en.md

@@ -1,5 +1,9 @@
 # apick-api English guide
 
+## Skill performance report
+
+Use `const { data } = await apick.getSkillPerformance()` to read the [public measurements](https://apick.app/skills/performance). Review sample sizes, dates, methods and failure reasons together. Model scores are not objective accuracy; unmeasured values are `null`. Reading the report does not execute a paid Skill.
+
 ## Request and response formats
 
 All SDK requests with a body use `multipart/form-data`. Arrays use separate indexed fields such as `utterance_ids[0]`; let the SDK set the Content-Type boundary. GET requests have no body. The server continues accepting older JSON requests for compatibility.
@@ -349,7 +353,7 @@ if (status.data.status === "completed") {
 ## 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.
+
+## 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

@@ -1,5 +1,9 @@
 # apick-api 한국어 가이드
 
+## 스킬 성능표
+
+`const { data } = await apick.getSkillPerformance()`로 [공개 측정표](https://apick.app/skills/performance)를 조회합니다. 표본 수·시험일·검사 방법·실패 사유를 함께 확인하세요. 모델 점수는 객관적 정확도가 아니며 미검증 값은 `null`입니다. 조회 자체에는 유료 실행이 필요하지 않습니다.
+
 ## 요청과 응답 형식
 
 SDK의 본문 요청은 모두 `multipart/form-data`입니다. `utterance_ids[0]`처럼 배열을 개별 필드로 전송하며 `Content-Type` 헤더를 직접 지정할 필요가 없습니다. GET 조회는 본문을 보내지 않습니다. 기존 JSON 요청도 서버에서 호환용으로 계속 처리합니다.
@@ -357,7 +361,7 @@ if (status.data.status === "completed") {
 ## 스킬 결과 파일과 실행 예상
 
 스킬 상세·견적은 가격과 시간 범위, 도구별 예상 호출 수를 제공합니다. 실행 전 최대 예약액을 확인하고, 성공 결과의 파일은 인증이 적용되는 getSkillArtifact(runId, fileId)로 내려받으세요. 자세한 필드와 예시는 [스킬 결과 파일 안내](skill-artifacts.md)를 참고하세요.
-
-## 상품별 조회 가이드
-
-상품별 간편인증 조회 가이드에는 조회 데이터, 출처 기관, 활용 사례와 자주 묻는 질문이 있습니다. 인증 요청은 해당 상품의 자료를 조회하기 위한 단계이며 결과 조회용 transactionId를 반환합니다. 요청·응답 계약과 인증 방식은 동일합니다. [공통 인증 흐름](https://apick.app/dev_guide/data)에서 절차와 오류 처리를 확인하세요.
+
+## 상품별 조회 가이드
+
+상품별 간편인증 조회 가이드에는 조회 데이터, 출처 기관, 활용 사례와 자주 묻는 질문이 있습니다. 인증 요청은 해당 상품의 자료를 조회하기 위한 단계이며 결과 조회용 transactionId를 반환합니다. 요청·응답 계약과 인증 방식은 동일합니다. [공통 인증 흐름](https://apick.app/dev_guide/data)에서 절차와 오류 처리를 확인하세요.

package/package.json

@@ -1,71 +1,71 @@
-{
-  "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"
-  ]
-}
+{
+  "name": "apick-api",
+  "version": "3.9.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",
+  "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

@@ -948,7 +948,11 @@ class ApickClient {
 		return this._skills('GET', '/rest/skills', { query });
 	}
 
-	getSkill(skillId) {
+	getSkillPerformance() {
+		return this._skills('GET', '/skills/performance/data.json');
+	}
+
+	getSkill(skillId) {
 		return this._skills('GET', '/rest/skills/' + normalizeSkillId(skillId));
 	}
 

package/src/index.d.ts

@@ -323,7 +323,9 @@ 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>>>;
+	searchSkills(options?: SkillSearchOptions): Promise<ApickResult<SkillPage<SkillSummary>>>;
+	/** Public measured results and methods; model scores are not accuracy guarantees. */
+	getSkillPerformance(): Promise<ApickResult<SkillPerformanceReport>>;
 	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>>>;
@@ -339,7 +341,38 @@ export const SKILL_CATEGORIES: readonly ['data', 'ai', 'dev', 'document', 'marke
 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 SkillSort = typeof SKILL_SORTS[number];
+export interface SkillPerformanceRate {
+	passed: number; total: number; percent: number; interval95: [number, number];
+}
+export interface SkillPerformanceReport {
+	schema_version: 1;
+	updated_at: string;
+	inventory_verified: boolean;
+	method: { minimum_cases: number; min_score: number; mean_score: number; min_improvement: number; critical_failures: number; description: string; limitations: string[]; interval_note: string; split: { normal: number; boundary: number; adversarial: number } };
+	calibration: { at: string; cases: number; true_positive: number; false_negative: number; false_positive: number; true_negative: number; automatic_release_allowed: boolean } | null;
+	additional_calibrations: Array<{ label: string; at: string; cases: number; detected: number; missed: number; false_positive: number; uncertain: number; automatic_release_allowed: boolean; scope: string }>;
+	skills: Array<{
+		key: string; title: string; group: string; origin: 'new' | 'existing'; published: boolean | null; url: string | null;
+		current: {
+			state: 'not_tested' | 'partial' | 'held' | 'passed' | 'stale'; at?: string;
+			cases: number; planned_cases: number; score: number | null; baseline_score: number | null;
+			score_samples?: number; evaluation_errors?: number;
+			delivery: SkillPerformanceRate | null; machine: SkillPerformanceRate | null;
+			median_seconds: number | null; p95_seconds: number | null; timing_samples?: number;
+			reasons: string[]; method?: string; sample_type?: string;
+			baseline_format_valid?: boolean;
+			evaluation_stage?: 'preliminary' | 'holdout';
+			dataset_composition?: { normal: number; boundary: number; adversarial: number; misplaced_rejections: number; valid: boolean };
+			min_score?: number | null; critical_cases?: number | null;
+			case_split?: { standard: number; boundary: number; adversarial: number };
+			extra_checks?: Array<{ name: string; passed: number; total: number }>;
+			tool_calls?: Array<{ label: string; samples: number; total: number | null; median: number | null; p95: number | null }>;
+			case_results?: Array<{ index: number; name: string; kind: 'standard' | 'boundary' | 'adversarial'; status: 'tested' | 'evaluation_error' | 'machine_only' | 'not_tested'; expected: 'success' | 'reject' | null; machine_pass: boolean; score: number | null; baseline_score: number | null; failed_checks: string[]; reason: string | null }>;
+		};
+		legacy: { cases: number; score: number; baseline_score: number; method: string; independent_holdout: false; at?: string } | null;
+	}>;
+}
 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';