# TypeScript SDK

> Management API, Content Delivery API, Customer API를 위한 타입 지정 클라이언트와 Webhook, 미리보기, SEO 파일, 엣지를 위한 헬퍼를 제공합니다.

> Markdown version of https://kanorio.com/ko/developers/sdk. Append `.md` to any developer docs URL for this format. Index: https://kanorio.com/llms.txt · MCP: https://app.kanorio.com/api/mcp
>
> Translated from the English original: https://kanorio.com/en/developers/sdk.md

`@kanorio/sdk`는 3개의 OpenAPI 문서에서 생성된 가볍고 완벽하게 타입이 지정된 클라이언트입니다. 경로, 매개변수, 요청 본문 및 응답은 컴파일 타임에 확인됩니다. `fetch`가 작동하는 Node.js, 엣지 런타임, Deno, Bun, 브라우저 등 모든 환경에서 실행할 수 있습니다.

```bash
npm install @kanorio/sdk
```

## 클라이언트

| 기능 | API | 자격 증명 |
|---|---|---|
| `createManagementClient({ token })` | `https://app.kanorio.com/api/v1`의 Management API | `knr_pat_` 또는 `knr_sa_`. 서버 전용. |
| `createDeliveryClient({ siteUrl, previewToken? })` | 단일 사이트의 Content Delivery API | 없음 또는 초안용 `knr_pv_` |
| `createCustomerClient({ siteUrl, token })` | 단일 사이트의 Customer API | `knr_cat_` |

각 클라이언트에는 `get`, `post`, `put`, `patch`, `delete` 메서드가 있습니다. 경로 매개변수는 `params`에, 쿼리 매개변수는 `query`에, JSON 본문은 `body`에 넣습니다.

```ts
import { createManagementClient } from "@kanorio/sdk";

const kanorio = createManagementClient({ token: process.env.KANORIO_TOKEN! });

const page = await kanorio.get("/sites/{id}/pages/{pageId}", {
  params: { id: "ws_example123", pageId: "pg_example456" },
});
```

`token`은 함수일 수 있으므로 요청할 때마다 갱신된 시크릿을 가져올 수 있습니다.

## 오류

`2xx`가 아닌 응답은 `code`, `status`, `message`, `details`를 포함하는 `KanorioApiError`를 발생시킵니다. `retryAfter`는 `Retry-After` 헤더 또는 `details.retryAfter`에서 채워집니다.

```ts
import { KanorioApiError } from "@kanorio/sdk";

try {
  await kanorio.post("/sites/{id}/posts/{postId}/publish", { params: { id, postId }, body: {} });
} catch (error) {
  if (error instanceof KanorioApiError && error.code === "SITE_NOT_PUBLISHED") {
    await kanorio.post("/sites/{id}/publish", { params: { id }, body: {} });
  } else {
    throw error;
  }
}
```

## 페이지네이션

`paginate`는 모든 리스트 엔드포인트를 `nextCursor`를 따르는 비동기 반복자로 변환합니다. `listAll`은 모든 페이지를 배열로 수집합니다.

```ts
import { createDeliveryClient, paginate } from "@kanorio/sdk";

const delivery = createDeliveryClient({ siteUrl: "https://s-xxxxxxxxxxxx.kanorio.com" });

for await (const item of paginate((cursor) =>
  delivery.get("/collections/{key}/items", { params: { key: "projects" }, query: { cursor, limit: 100 } })
)) {
  console.log(item.slug);
}
```

## 헬퍼

| 가져오기(Import) | 설명 |
|---|---|
| `verifyWebhookSignature`, `createRevalidateHandler` | `X-Kanorio-Signature`를 검증하고 `data.cacheTags`(`kanorio:` 접두사 포함)를 재검증합니다. [Webhooks](https://kanorio.com/ko/developers/webhooks)를 참조하세요. |
| `cacheTag`, `localizeCacheTags`, `prefixCacheTags` | 페치 시 포함할 캐시 태그를 생성합니다(`cacheTag.collection("blog")`, `cacheTag.item(id)`, `localizeCacheTags(tags, "fr-FR")`). 웹훅 핸들러가 재검증하는 것과 동일한 `kanorio:` 접두사를 사용합니다. |
| `seoRewrites({ siteUrl, framework })` | 사이트의 sitemap, robots.txt, llms.txt 및 피드를 자체 도메인에서 제공합니다. |
| `fetchDeliveryJsonLd({ siteUrl, path })` | 페이지를 위한 Schema.org JSON-LD를 가져옵니다. |
| `@kanorio/sdk/edge` › `createKanorioMiddleware` | 리디렉션 적용(정확히 일치, 이후 `/*` 와일드카드), 소유자가 차단한 AI 크롤러 차단, IndexNow 키 파일 제공을 수행합니다. 다국어 사이트의 경우 기본 언어 접두사를 루트로 리다이렉트하고, `/{prefix}/llms.txt` 및 `/{prefix}/rss.xml`을 제공하며, 접두사 없이 리디렉션을 매칭하고, `evaluate()`에서 요청 언어를 보고합니다. |
| `requestLocaleOf`, `localizedPath`, `languageSwitcher` | 사이트의 `locales[]`(`GET /site`)를 사용하여 경로명에서 언어를 확인하고, 다른 언어로 동일한 경로를 생성하며, 언어 메뉴를 나열합니다. |
| `buildAlternates` | 호스팅된 사이트 규칙에 따라 `resolvedLocale` / `availableLocales`를 사용하여 페이지의 Canonical 및 `hreflang`을 생성합니다(언어별 자기 참조 Canonical, 기본 언어로의 `x-default`, 기본 언어로의 폴백 페이지 Canonical). |
| `@kanorio/sdk/preview` › `createPreviewRouteHandler` | 관리 화면의 미리보기 링크를 초안 모드 세션으로 전환합니다. |
| `@kanorio/sdk/forms` › `forms.client` | 폼, 봇 방지 챌린지, 업로드 티켓을 가져온 후 제출합니다. |
| `parseDeliveryCacheTags`, `frameworkCacheTags` | Content Delivery API 응답에서 `X-Kanorio-Cache-Tags`를 읽습니다. 원본 그대로 또는 프레임워크 캐시용으로 접두사가 붙은 형태로 읽을 수 있습니다. |

## 콘텐츠 모델을 위한 타입

컬렉션은 사이트별로 정의되므로 필드 타입은 사이트 자체에서 가져옵니다. [CLI](https://kanorio.com/ko/developers/cli)를 사용하여 생성하십시오:

```bash
npx @kanorio/cli types --site https://s-xxxxxxxxxxxx.kanorio.com --out src/kanorio.d.ts
```

## 버전 관리

SDK는 시맨틱 버전을 따릅니다. SDK 버전은 각 요청과 함께 전송되므로 Kanorio는 사용 중인 더 이상 사용되지 않는 작업에 대해 경고할 수 있습니다. [버전 관리](https://kanorio.com/ko/developers/basics/versioning)를 참조하십시오.