JavaScript SDK: v5 から v6 への移行

v6 は全面的な書き直しです。フラットな単一のクライアント、クラスの代わりにプレーンなデータ、第 1 引数に ID、そして単一のエラークラス。変更のほとんどは機械的に置き換えられます。

概要

v5	v6
メソッドを持つクラス (`app.start()`)	プレーンなデータ。メソッドはクライアント上にある (`api.apps.start(appId)`)
`Collection`	`Array`
`Date` を使った camelCase のクラスフィールド (`createdAt`、`modifiedAt`、`uptime`)	API のフィールドと値そのまま (`created_at` と `modified` は ISO 文字列、`uptime` はミリ秒)
`Buffer`	`Uint8Array` (入力としては引き続き `Buffer` も受け付けます)
変更系は `Promise<boolean>` を返す (常に `true`)	`Promise<void>`、または API が返すデータ (`envs.*` → `EnvVars`、`deploys.setWebhook` → URL、`deploys.linkGithubApp` → `LinkedRepository`、`resetCredentials` → パスワード)
`code` のみを持つ `SquareCloudAPIError extends TypeError`	`status`、`code`、`message` (サーバーのもの)、`method`、`path`、`cause` を持つ `extends Error`
イベント (`userUpdate`、`statusUpdate`、`logsUpdate`、`snapshotsUpdate`) と `api.cache`/`app.cache`	削除: 状態は自分で保持してください
`api.api.request()` (生の `APIService`)	削除: すべての操作にメソッドがあります
タイムアウトなし、リトライなし	試行ごとに 30 秒のタイムアウト、安全な失敗のみリトライ (動作の変更を参照)
Node.js >= 20	Node.js >= 22、Deno、Bun、エッジ
`@squarecloud/api-types`	型は SDK に同梱 (`import type { App } from "@squarecloud/api"`)

初期化とオプション

v5	v6	備考
`new SquareCloudAPI(key)`	`new SquareCloudAPI(key, { baseUrl?, timeoutMs?, maxRetries?, userAgent?, fetch? })`	空のキーや空白だけのキーは `TypeError` をスローします。
`SquareCloudAPI.apiInfo`	`BASE_URL` と `{ baseUrl }`	`BASE_URL` = `https://api.squarecloud.app/v2`。
(なし)	`timeoutMs` (30000)	試行ごと。保持される呼び出しと `ai.chat` は最低 120 秒待機します。`<= 0`、`Infinity`、`>= 2^31` を指定すると、下限も含めてすべてのタイムアウトが無効になります。
(なし)	`maxRetries` (2)	GET でのネットワークエラーと、記載された 503 コードのみ。429 は決してリトライしません。
(なし)	`userAgent`	ヘッダー全体を置き換えます (デフォルトは `squarecloud-sdk-js/<version>`)。
(なし)	`fetch`	カスタム `fetch` (プロキシ、トレーシング、テスト)。

メソッドごとの対応

v5	v6	備考
`api.user.get()` → `User`	`api.account.me()`	`{ user, applications, databases }` を返します。
`user.plan.expiresIn`	`new Date(user.plan.duration)`	タイムスタンプ。`null` は失効しないことを意味します。
`api.user.snapshots(scope)`	`api.account.snapshots({ scope })`
`api.service.status()`	`api.service.status()`	新しい形式: `status`、`message`、`services`、`dependencies` など。
`api.applications.get()`	`(await api.account.me()).applications`
`api.applications.get(id)` / `fetch(id)` / `app.fetch()`	`api.apps.get(id)`	workspace で共有されたアプリも取得できます。
`app.isWebsite()`	`Boolean((await api.apps.get(id)).domain)`
`api.applications.create(file)`	`api.apps.create(file, { signal })`	パス、`Blob`/`File`、`Uint8Array` のいずれか。タイムアウトなし。
`api.applications.statusAll()`	`api.apps.statusAll({ workspaceId? })`	プレーンな `{ id, running, cpu?, ram? }` オブジェクト (v5 では `cpu`/`ram` が `usage` の下にネストされていました)。
`statusAll()[i].fetch()` (`SimpleApplicationStatus`、`SimpleDatabaseStatus`)	`api.apps.status(id)` / `api.databases.status(id)`
`api.applications.domains()` / `loadBalancers()`	`api.apps.domains()` / `api.apps.loadBalancers()`
`app.getStatus()`	`api.apps.status(id, { raw? })`	`cpu`、`ram`、`storage`、`network` はトップレベルにあります (v5 では `usage` の下にネスト)。`uptime` は `Date` ではなく、起動時刻のミリ秒タイムスタンプです (停止中は `null`)。
`app.getLogs()`	`api.apps.logs(id)`
`app.getMetrics()`	`api.apps.metrics(id)`	新しいポイントから順に並びます。
`app.realtime()` → 生の `Response`	`api.apps.realtime(id, { signal })`	パース済みイベントの非同期イテラブル。
`app.start()` / `stop()` / `restart()` / `delete()`	`api.apps.start(id)` / `stop(id)` / `restart(id)` / `delete(id)`
`app.commit(file, fileName)`	`api.apps.commit(id, file, { path?, filename?, signal? })`
`app.files.list(path)`	`api.apps.files.list(id, path?)`	存在しないディレクトリは 404 `FILE_NOT_FOUND` をスローします (以前は空のリストでした)。
`app.files.read(path)` → `Buffer \| undefined`	`api.apps.files.read(id, path)` → `Uint8Array`	base64 でリクエストしてデコードします (v5 はバイト配列を読み取っていました)。API が内容を送らない場合は空のバイト列になり、`undefined` にはなりません。
`app.files.create(file, fileName, dir)`	api.apps.files.write(id, `${dir}/${fileName}`, content)	文字列は内容です (プレーンテキストとして送信)。v5 ではローカルパスとして読み取っていました。バイト列は base64 で送信されます。空の内容は空のファイルを作成します。
`app.files.edit(file, path)`	`api.apps.files.write(id, path, content)`	`write` と同じ送信形式: 文字列はテキスト、バイト列は base64。
`app.files.move(path, newPath)` / `delete(path)`	`api.apps.files.move(id, path, to)` / `delete(id, path)`
`app.envs.list()`	`api.apps.envs.get(id)`
`app.envs.set(envs)` / `replace(envs)` / `delete(keys)`	`api.apps.envs.set(id, envs)` / `replace(id, envs)` / `delete(id, keys)`	それぞれ変更後の変数を返します。
`app.snapshots.list()`	`api.apps.snapshots.list(id)`	各項目に `name`、`runtime`、`origin`、`version_id`、署名付きダウンロード `url` が追加され、すべて API が送ったままの値です。
`app.snapshots.create()`	`api.apps.snapshots.create(id)`	202 の場合は `{ pending: true }` (v5 ではスローしていました)、それ以外は `{ pending: false, url, key }`。
`app.snapshots.download()` → `Buffer`	`const s = await api.apps.snapshots.create(id)` のあと `if (!s.pending) await api.downloadSnapshot(s.url)`	`ReadableStream` で、何もバッファリングされません。保留中 (202) の snapshot にはまだ URL がありません: v5 ではスローしていました。
`snapshot.url` / `snapshot.download()`	`snapshot.url` / `api.downloadSnapshot(snapshot.url)`	API 自身の署名付き URL (v5 は呼び出し元の ID から誤った URL を組み立てていました)。
`app.snapshots.restore({ snapshotId, versionId })`	`api.apps.snapshots.restore(id, name, versionId)`	一覧で取得した snapshot の `name` と `version_id` を渡します。エラーについては Snapshot を参照してください。
`app.deploys.integrateGithubWebhook(token)`	`api.apps.deploys.setWebhook(id, token)`	webhook URL を返します (`"@"` で削除した場合は `""`)。
`app.deploys.linkGithubApp({ repositoryName, repositoryBranch })`	`api.apps.deploys.linkGithubApp(id, repository, branch)`	位置引数。`{ id, full_name, branch }` を返します。API キーが使えるようになりました (スコープ `apps:deploy`)。v5 ではセッション JWT が必要でした。
`app.deploys.unlinkGithubApp()` → `boolean`	`api.apps.deploys.unlinkGithubApp(id)`	`void` で解決されます (以前は `boolean`)。何も連携されていない場合は `400 GIT_NOT_CONFIGURED`。
`app.deploys.list()` → `Deployment[][]`	`api.apps.deploys.list(id)` → `DeployEvent[][]`	失敗した deploy は `code` (詳細がある場合は `message` も) を伴う `state: "error"` で終わります。`source` は常に `"git"` です。
`app.deploys.current()`	`api.apps.deploys.current(id)` → `DeployCurrent`	何も設定されていない場合は `{}`。
`app.deploys.webhookURL()`	`(await api.apps.deploys.current(id)).webhook`
`app.network` (`WebsiteApplication` のみ)	`api.apps.network`	任意のアプリ ID を受け付けます。Web 以外のアプリは API が拒否します。
`network.setCustomDomain(domain)`	`api.apps.network.setDomain(id, domain)`
`network.analytics({ start, end, contentType, ... })`	`api.apps.network.analytics(id, start, end, { content_type, ... })`	空の期間では `null`。
`network.errors({ start, end, include4xx })`	`api.apps.network.errors(id, start, end, { include_4xx })`	空の期間では `null`。
`network.logs({ start, end })` / `performance({ start, end })`	`api.apps.network.logs(id, start, end)` / `performance(id, start, end)`
`network.dns()` / `purgeCache()`	`api.apps.network.dns(id)` / `purgeCache(id)`
`api.databases.fetch(id)` / `db.fetch()`	`api.databases.get(id)`
`api.databases.create(options)` / `statusAll()`	変更なし	`statusAll()` はプレーンな `{ id, running, cpu?, ram? }` オブジェクトを返します。
`db.getStatus()` / `getMetrics()`	`api.databases.status(id, { raw? })` / `metrics(id)`	`ram` は使用中の RAM です (例: `"120.4MB"`、`raw` の場合は数値)。メトリクスは新しい順に並びます。
`db.start()` / `stop()` / `update(changes)` / `delete()`	`api.databases.start(id)` / `stop(id)` / `update(id, changes)` / `delete(id)`
`db.credentials.certificate()`	`api.databases.certificate(id)`
`db.credentials.reset(type)`	`api.databases.resetCredentials(id, type)`	新しいパスワード (`"certificate"` の場合は `""`)。
`db.snapshots.list()` / `create()` / `download()`	`api.databases.snapshots.list(id)` / `create(id)` / `api.downloadSnapshot(url)`	`download()` はアプリと同様: `create(id)` のあと、保留中でなければ `downloadSnapshot(s.url)`。
`db.snapshots.restore(snapshotId, versionId)`	`api.databases.snapshots.restore(id, name, versionId)`	一覧で取得した snapshot の `name` と `version_id` を渡します。
`api.workspaces.list()` / `fetch(id)` / `workspace.fetch()`	`api.workspaces.list()` / `get(id)`
`api.workspaces.create({ name })`	`api.workspaces.create(name)`	`WorkspaceCreated` (`{ id, name }`) を返します。
`api.workspaces.delete(id)` / `workspace.delete()`	`api.workspaces.delete(id)`
`api.workspaces.leave(id)` / `workspace.leave()`	`api.workspaces.leave(id)`
`api.workspaces.generateInviteCode()`	`api.workspaces.members.inviteCode()`
`workspace.members.add(code, group)`	`api.workspaces.members.add(workspaceId, code, group)`
`workspace.members.update(memberId, group)` / `remove(memberId)`	`api.workspaces.members.update(workspaceId, memberId, group)` / `remove(workspaceId, memberId)`
`workspace.applications.add(appId)` / `remove(appId)`	`api.workspaces.apps.add(workspaceId, appId)` / `remove(workspaceId, appId)`
(なし)	`api.ai.chat(request)`、`api.downloadSnapshot(url)`、`BASE_URL`	新規。

型

型は SDK に同梱され、API のフィールド名を反映しています。@squarecloud/api-types と v5 のクラスからの主な名称変更:

v5	v6
`Application`、`WebsiteApplication`、`BaseApplication`	`App` (`api.apps.get()`)、`AppSummary` (`account.me()`)、`AppCreated`
`ApplicationStatus`、`SimpleApplicationStatus`、`SimpleDatabaseStatus`	`RuntimeStats` (`{ raw: true }` の場合は `RuntimeStats<true>`)、`StatusListItem`
`User`	`Account` (`{ user, applications, databases }`)、`User`、`Plan`
`Snapshot`、`DatabaseSnapshot`	`Snapshot`、`SnapshotCreated`
`Deployment`、`DeploymentState`	`DeployEvent`、`DeployCurrent` (`DeployRepository` を含む)、`LinkedRepository`
ネットワークのクエリオブジェクト	`AnalyticsFilters` (オプションのフィルター。`start` と `end` は引数)
`Workspace`	`Workspace`、`WorkspaceCreated`、`WorkspaceGroup`
`APIErrorCode` (ランタイムオブジェクト)	`ErrorCode` (型のみでランタイムコストなし。API の契約に含まれるすべてのコード)
`APIEndpoint`、`APIEndpoints`、`APIMethod`、`APIRequestArgs`、`APIRequestOptions`、`APIResponse`、`QueryOrBody`、`ClientEvents`、`TypedEventEmitter`、`CollectionConstructor`	削除 (リクエストの内部処理、イベント、`Collection`)

エラー

// v5
catch (e) { if (e.code === "RATE_LIMIT_EXCEEDED") ... }

// v6
catch (e) {
  if (e instanceof SquareCloudAPIError && e.status === 429) {
    console.log(e.code, e.message); // KEEP_CALM "Please wait 5 seconds..." or RATE_LIMITED
  }
}

合成コード (RATE_LIMIT_EXCEEDED、PAYLOAD_TOO_LARGE、SERVER_UNAVAILABLE、UNKNOWN_ERROR_<status>) は廃止されました。API の実際のコード (RATE_LIMITED、KEEP_CALM、DAILY_SNAPSHOTS_LIMIT_REACHED、FILE_TOO_LARGE など) がそのまま表れます。
レスポンスがない場合: NETWORK_ERROR (原因は cause に入ります) または TIMEOUT で、status: 0。コードのないボディは、実際の status とメッセージ HTTP <status> を持つ UNKNOWN_ERROR になります。
API のエラーに対して instanceof TypeError は true ではなくなりました。
期限切れのキーは、不明なキーと同様に 401 ACCESS_DENIED になります。
ai.chat() のエラーは、認証とレート制限も含めて、小文字の OpenAI コード (access_denied、rate_limit_exceeded など) を持ちます。
拒否された start/stop/restart は、コードのみを持つ 409 です: CONTAINER_ALREADY_STARTED、CONTAINER_ALREADY_STOPPED、CONTAINER_TEMPORARILY_SUSPENDED、CONTAINER_NOT_FOUND、CONTAINER_INSUFFICIENT_DISK_SPACE、CONTAINER_NETWORK_CONFLICT、ACTION_FAILED。

動作の変更

呼び出しがタイムアウトするようになりました: デフォルトで試行ごとに 30 秒 (v5 にはタイムアウトがありませんでした)、サーバーが接続を保持する呼び出しでは最低 120 秒。無効にするには timeoutMs: 0 を設定します。
files.write() は文字列を内容として扱い、プレーンテキストとして送信します。バイト列は base64 でバイナリセーフに送信され、空の内容は空のファイルを作成します (Python SDK および Go SDK と同じ送信形式)。files.read() は base64 をリクエストしてデコードします。
存在しないディレクトリに対する files.list() は、[] を返す代わりに 404 FILE_NOT_FOUND をスローします。
snapshots.create() は、202 の場合にスローする代わりに { pending: true } を返します。
文字列の結果が undefined になることはありません: API が何も送らない場合、setWebhook と resetCredentials("certificate") は "" を返し、deploys.current() は {} を返します。
realtime() は、接続が切れた場合と REALTIME_RECONNECT の場合に再接続します (連続 3 回まで、オープンは 5.5 秒に最大 1 回)。
リトライ: GET でのネットワークエラーと 503 UPLOAD_BUSY/ANALYTICS_BUSY (および GET での DATABASE_UNAVAILABLE) を、バックオフ付きでリトライします。429 は決してリトライしません。DATABASE_UNAVAILABLE は変更が適用された後に返されることがあるため、冪等な変更は自分でリトライしてください。
空、.、.. の ID はローカルで INVALID_ID として失敗します。
undefined、""、false のクエリ値は送信されません。

CLI

VS Code

SDKs

JavaScript SDK: v5 から v6 への移行

概要

初期化とオプション

メソッドごとの対応

型

エラー

動作の変更

次のステップ

クライアント

エラー

​概要

​初期化とオプション

​メソッドごとの対応

​型

​エラー

​動作の変更

​次のステップ

クライアント

エラー

概要

初期化とオプション

メソッドごとの対応

型

エラー

動作の変更

次のステップ