SDK 与工具

TypeScript SDK

提供 Management API、Content Delivery API 与 Customer API 的类型化客户端，以及针对 Webhooks、预览、SEO 文件与 Edge 的辅助工具。

@kanorio/sdk 是一个轻量且完全类型化的客户端，由三个 OpenAPI 文档生成。路径、参数、请求体与响应皆会在编译时进行检查。它可在任何支持 fetch 的环境运行：Node.js、Edge Runtime、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 的响应会抛出 KanorioApiError，包含 code、status、message 与 details。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);
}

辅助工具

导入	功能说明
`verifyWebhookSignature`, `createRevalidateHandler`	验证 `X-Kanorio-Signature` 并重新验证 `data.cacheTags`（前缀为 `kanorio:`）。请参阅 Webhooks。
`cacheTag`, `localizeCacheTags`, `prefixCacheTags`	构建请求应携带的缓存标签（`cacheTag.collection("blog")`、`cacheTag.item(id)`、`localizeCacheTags(tags, "fr-FR")`），并加上 Webhook 处理程序重新验证时使用的 `kanorio:` 前缀
`seoRewrites({ siteUrl, framework })`	从您自己的域名提供网站的 sitemap、robots.txt、llms.txt 和 feeds
`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 遵循语义化版本控制。其版本信息会随每次请求发送，以便 Kanorio 在您调用已弃用的操作时发出警告。请参阅版本控制。