SDK とツール

TypeScript SDK

Management API、Content Delivery API、Customer API用の型定義済みクライアントに加え、Webhook、プレビュー、SEOファイル、エッジ向けのヘルパーを提供します。

@kanorio/sdk は、3つのOpenAPIドキュメントから生成された、軽量で完全に型定義されたクライアントです。パス、パラメータ、リクエストボディ、レスポンスはコンパイル時にチェックされます。Node.js、エッジランタイム、Deno、Bun、ブラウザなど、fetch が動作するあらゆる環境で実行可能です。

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);
}

ヘルパー

インポート	機能
`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、フィードを独自のドメインから配信します。
`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`、プライマリ言語へのフォールバック）に従います。
`@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は呼び出し中の非推奨操作について警告を表示できます。バージョニングを参照してください。