cloudcannon-sdk

CloudCannon SDK

@cloudcannon/sdk は、CloudCannon CLI の基盤となる REST API クライアントです。API を操作するサブクライアントの階層に加えて、サブクライアントでラップされていないエンドポイントにアクセスできる、型付きの fetch を提供します。

プログラムから操作する場合は SDK を使ってください。シェルコマンドで操作する場合は CLI を使ってください。

使用する場面

• スクリプト、ビルドステップ、サービスから CloudCannon API を呼び出す
• 多数のサイトや組織を一度に操作する
• CLI では利用できない機能にアクセスする — DAM、バックアップ、同期履歴とプル、サイトスキャン、スクリーンショット、プロバイダーの接続／切断、site.copy、site.delete
• 終了コードではなく、型に基づいて API の失敗を処理する
• 利用可能なメソッドと、その引数を確認する

使用しない場面

• シェルから一度だけ操作する場合 — その場合は cloudcannon-cli を使います。すでに目的を果たすコマンドがあるなら、それを使ってください。サイト名を解決して JSON を出力でき、クライアントの設定も不要です。
• CloudCannon でサイトをローカル実行する場合 — cloudcannon dev の全手順は cloudcannon-dev-server で説明しています。SDK とは関係ありません。
• cloudcannon.config.yml に何を設定するか決める場合 — その場合は cloudcannon-configuration を使います。SDK はファイルをバイト列として読み書きするだけで、内容には関与しません。
• 編集可能な領域やスニペットを作成する場合 — cloudcannon-visual-editing と cloudcannon-snippets を参照してください。

最も重要なルール

ホストされたサイトに書き込みを行う呼び出しの前には、必ずユーザーに確認してください。 これは CLI にも適用されるルールで、理由も同じです。正式な説明については、cloudcannon-cli § 最も重要なルールを参照してください。

コマンドラインよりも、ここでは次の理由でルールに違反しやすくなります。

• 警告として読み取れるコマンド名がありません。site.delete() は、引数もフラグも確認プロンプトもないメソッド呼び出しです。
• SDK は、CLI には対応するコマンドがない破壊的なエンドポイントにもアクセスできます — site.delete()、site.copy()、disconnectSourceProvider()、disconnectOutputProvider()。

この確認ルールは client.fetch にも適用されます。エスケープハッチ経由の POST も書き込みです。

要件

パッケージの engines フィールドに従い、Node 20 以降が必要です。CLI の Node 24 より低いバージョンです。パッケージは ESM（"type": "module"）で、デフォルトエクスポートはクライアントクラスです。

import CloudCannonClient from "@cloudcannon/sdk";

クイックスタート

サブクライアントに必要なのは UUID だけなので、ほとんどのタスクは UUID を見つけるところから始まります。

import CloudCannonClient from "@cloudcannon/sdk";

// The SDK reads no credentials of its own — you supply them.
const client = new CloudCannonClient({
  userAccessKey: {
    id: process.env.CC_ACCESS_KEY_ID,
    secret: process.env.CC_ACCESS_KEY_SECRET,
  },
});

const { items: orgs } = await client.orgs();
const { items: sites } = await client.org(orgs[0].uuid).sites({ filters: { search: "my-site" } });

const site = await client.site(sites[0].uuid).get();

目次

ファイル	内容
SKILL.md（このファイル）	振り分け、書き込みの確認ルール、要件
client.md	クライアントの構築、設定の形式、認証情報を自ら読み込まない理由
resources.md	サブクライアントの階層、UUID による指定、ページネーション、戻り値の型
api-surface.md	正式なメソッド一覧の確認方法と、生の client.fetch エスケープハッチ
editing-sessions.md	SDK を通じたホストサイトへのファイルの書き込み
troubleshooting.md	症状 → 原因 → 解決策

よくある間違い

言い分	実際
「サイト名を client.site() に渡せばよい。」	サブクライアントが受け取るのは UUID のみです。まず解決してください — resources.md § リソースの指定。
「client.sites() ですべての閲覧可能なサイトが一覧表示される。」	そのようなメソッドはありません。サイトは組織ごとに一覧表示されます。resources.md をご覧ください。
「SDK が cloudcannon login の認証情報を取得してくれる。」	ディスクや環境から何も読み取りません。この一連の処理は CLI の機能です — client.md。
「メソッドのシグネチャを記憶に頼って書けばよい。」	シグネチャはリリースごとに変更されます。インストール済みパッケージから確認してください — api-surface.md。
「await site.getFile(path) でファイルの内容が得られる。」	得られるのは Response です。これを返すメソッドはいくつかあります — resources.md § メソッドの戻り値。
「一覧が返ってきたので、これですべてだ。」	ページネーションされたエンドポイントは 1 ページ分を返します。total_pages を確認してください — resources.md § ページネーション。
「client.fetch は低レベル API だから、書き込み制限は CLI の機能だ。」	制限の対象はラッパーではなくエンドポイントです。fetch 経由の POST は、名前付きメソッドと同じように稼働中のサイトへ書き込みます。