SDK 및 도구

TypeScript SDK

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

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

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에 넣습니다.

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에서 채워집니다.

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은 모든 페이지를 배열로 수집합니다.

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를 참조하세요.
`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를 사용하여 생성하십시오:

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

버전 관리

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