> ## Documentation Index
> Fetch the complete documentation index at: https://docs.squarecloud.app/llms.txt
> Use this file to discover all available pages before exploring further.

# v4 への移行

> @squarecloud/api の v3 と v4 の間で変更された点。破壊的変更、リネーム、アップグレードに必要な最小限のパッチ。

<Info>
  ここでカバーする最新パッチ：**v4.0.1**（2026-05-30 リリース）。
</Info>

## 要件

* **Node.js 20.0.0** 以降（v3 は Node 18 をサポートしていました）

## 破壊的変更の概要

| v3.x                                            | v4.x                                                                     |
| ----------------------------------------------- | ------------------------------------------------------------------------ |
| `client.users.*`                                | `client.user.*`                                                          |
| `app.backup` / `app.backups`                    | `app.snapshots`                                                          |
| `Backup` エクスポート                                 | `Snapshot` エクスポート                                                        |
| `app.deploys.list()` はフラットな `Deployment[]` を返す  | `Deployment[][]` を返す（以前の形式は `.flat()` を呼ぶ）                               |
| `Deployment.id` は `` `git-${string}` `` 形式      | 単なるコミットの SHA-1（40 桁の 16 進数）                                              |
| `app.network.dns()` は配列を返す                      | `{ ownership, ssl }` を返す                                                 |
| `app.network.analytics()` は引数を取らない              | `{ start, end }`（ISO 文字列または `Date`）が必要                                   |
| `app.network.purgeCache(paths?)`                | `purgeCache()` — 引数は **v4.0.1** で削除され、常にキャッシュ全体をパージする                    |
| `app.custom === undefined`                      | `app.custom === null`                                                    |
| `workspace.members` / `.applications` はデータ配列を保持 | `workspace.memberList` / `.applicationList` にリネーム。元の名前は現在**モジュール**になっている |
| `app.commit(file, name, restart)`               | `app.commit(file, name)` — 第 3 引数は削除                                     |
| `app.files.create(content, fullPath)`           | `app.files.create(content, fileName, path)`                              |

## リネーム

### `client.users` → `client.user`

```typescript theme={null}
// v3
await api.users.get();

// v4
await api.user.get();
```

`api.users` は `api.user` へプロキシする非推奨のゲッターとして引き続きエクスポートされますが、実行時に警告を出力します。

### Backups → Snapshots

```typescript theme={null}
// v3
await app.backups.create();
await app.backup.list();

// v4
await app.snapshots.create();
await app.snapshots.list();
```

`Backup` エクスポートは現在、`Snapshot` の非推奨エイリアスです。

## Application

### `Application.custom`

カスタムドメインがバインドされていない場合、`app.custom` は現在 `null` になりました（v3 では `undefined` でした）。

### `app.commit(file, fileName, restart)`

第 3 引数の `restart` は削除されました。commit 後は手動で再起動してください。

```typescript theme={null}
// v3
await app.commit(buffer, "index.js", true);

// v4
await app.commit(buffer, "index.js");
await app.restart();
```

### `app.files.create(content, path)`

シグネチャは現在 `create(content, fileName, path = "/")` です。移行方法：

```typescript theme={null}
// v3 — single combined path
await app.files.create(content, "./folder/test_file.txt");

// v4 — separate file name and directory
await app.files.create(content, "test_file.txt", "/folder");
```

## Deploys

### `app.deploys.list()` の形式

```typescript theme={null}
// v3
const events: Deployment[] = await app.deploys.list();

// v4
const timelines: Deployment[][] = await app.deploys.list();
const events = timelines.flat(); // same shape as v3
```

### `Deployment.id`

`` `git-…` `` 形式の文字列ではなく、単なるコミットの SHA-1（40 桁の 16 進数）になりました。

## Network

### `app.network.dns()`

```typescript theme={null}
// v3
const records: DnsRecord[] = await app.network.dns();

// v4
const { ownership, ssl } = await app.network.dns();
```

### `app.network.analytics()`

```typescript theme={null}
// v3
const data = await app.network.analytics();

// v4 — { start, end } is now required (ISO string or Date)
const data = await app.network.analytics({
    start: new Date(Date.now() - 24 * 60 * 60 * 1000),
    end:   new Date(),
});
```

### `app.network.purgeCache()`

```typescript theme={null}
// v3 and v4.0.0
await app.network.purgeCache(["/static/old.js"]);

// v4.0.1 and later — selective purge removed
await app.network.purgeCache();
```

## Workspaces

```typescript theme={null}
// v3
workspace.members;      // raw member data
workspace.applications; // raw application data

// v4
workspace.memberList;        // raw member data
workspace.applicationList;   // raw application data
workspace.members.add(...);  // members module
workspace.applications.add(...); // applications module
```

## v4 の新機能

上記のリネームやシグネチャ変更に加えて、v4 では大幅な機能セットが追加されています。

* **Databases** — 完全なライフサイクル、認証情報、snapshot、メトリクス（[Databases](/ja/sdks/js/databases)）
* **Workspaces** — 招待コードとロールによるチームコラボレーション（[Workspaces](/ja/sdks/js/workspaces)）
* **環境変数** — list / set / replace / delete（[環境変数](/ja/sdks/js/environment_variables)）
* **アプリケーションメトリクス** — 24 時間分の CPU/RAM/ネットワークサンプル（[アプリケーションの管理](/ja/sdks/js/managing_application)）
* **リアルタイム SSE ストリーム** — `app.realtime()`（[Realtime](/ja/sdks/js/realtime)）
* **エッジ分析** — analytics、errors、logs、latency のパーセンタイル（[Network](/ja/sdks/js/network)）
* **GitHub App 連携** — `app.deploys.linkGithubApp({ ... })`（[Deploys](/ja/sdks/js/deploys)）
* **snapshot の復元** — `app.snapshots.restore({ snapshotId, versionId })` と `db.snapshots.restore(snapshotId, versionId)`
* **status-all エンドポイント** — `api.applications.statusAll()`、`api.databases.statusAll()`
* **サービスステータス** — `api.service.status()`
* **ユーザースコープの snapshot** — `api.user.snapshots(scope)`
* **新しい User フィールド** — `User.locale`、`User.createdAt`、`User.databases`
* **新しい BaseApplication フィールド** — `domain`、`custom`、`createdAt`
* **`SquareCloudAPIError.code`** — `switch` ベースのエラーハンドリング用に公開