# TypeScript SDK

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

> Markdown version of https://kanorio.com/ja/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ドキュメントから生成された、軽量で完全に型定義されたクライアントです。パス、パラメータ、リクエストボディ、レスポンスはコンパイル時にチェックされます。Node.js、エッジランタイム、Deno、Bun、ブラウザなど、`fetch` が動作するあらゆる環境で実行可能です。

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

## ヘルパー

| インポート | 機能 |
|---|---|
| `verifyWebhookSignature`, `createRevalidateHandler` | `X-Kanorio-Signature` を検証し、`data.cacheTags`（`kanorio:` プレフィックス付き）を再検証します。[Webhooks](https://kanorio.com/ja/developers/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](https://kanorio.com/ja/developers/cli) を使用して生成してください：

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

## バージョニング

SDKはセマンティックバージョニングに従います。SDKのバージョンは各リクエストとともに送信されるため、Kanorioは呼び出し中の非推奨操作について警告を表示できます。[バージョニング](https://kanorio.com/ja/developers/basics/versioning) を参照してください。