SDK JavaScript: migrazione da v5 a v6

La v6 è una riscrittura: un unico client piatto, dati semplici invece di classi, id come primo argomento e un’unica classe di errore. La maggior parte delle modifiche è meccanica.

In sintesi

v5	v6
Classi con metodi (`app.start()`)	Dati semplici; metodi sul client (`api.apps.start(appId)`)
`Collection`	`Array`
Campi delle classi in camelCase con `Date` (`createdAt`, `modifiedAt`, `uptime`)	I campi e i valori dell’API (`created_at` e `modified` come stringhe ISO, `uptime` in ms)
`Buffer`	`Uint8Array` (un `Buffer` è ancora accettato come input)
Le mutazioni restituiscono `Promise<boolean>` (sempre `true`)	`Promise<void>`, oppure i dati restituiti dall’API (`envs.*` → `EnvVars`, `deploys.setWebhook` → URL, `deploys.linkGithubApp` → `LinkedRepository`, `resetCredentials` → la password)
`SquareCloudAPIError extends TypeError` con solo `code`	`extends Error` con `status`, `code`, `message` (quello del server), `method`, `path`, `cause`
Eventi (`userUpdate`, `statusUpdate`, `logsUpdate`, `snapshotsUpdate`) e `api.cache`/`app.cache`	Rimossi: gestisci tu il tuo stato
`api.api.request()` (l’`APIService` grezzo)	Rimosso: ogni operazione ha un metodo
Nessun timeout, nessun retry	Timeout di 30 s per tentativo, retry solo per i fallimenti sicuri (vedi Cambiamenti di comportamento)
Node.js >= 20	Node.js >= 22, Deno, Bun, edge
`@squarecloud/api-types`	I tipi sono inclusi nell’SDK (`import type { App } from "@squarecloud/api"`)

Costruzione e opzioni

v5	v6	Note
`new SquareCloudAPI(key)`	`new SquareCloudAPI(key, { baseUrl?, timeoutMs?, maxRetries?, userAgent?, fetch? })`	Una chiave vuota o composta solo da spazi lancia un `TypeError`.
`SquareCloudAPI.apiInfo`	`BASE_URL` e `{ baseUrl }`	`BASE_URL` = `https://api.squarecloud.app/v2`.
(nessuno)	`timeoutMs` (30000)	Per tentativo; le chiamate tenute aperte e `ai.chat` attendono almeno 120 s. `<= 0`, `Infinity` o `>= 2^31` disattiva tutti i timeout, soglie minime comprese.
(nessuno)	`maxRetries` (2)	Solo errori di rete su GET e i codici 503 elencati; mai 429.
(nessuno)	`userAgent`	Sostituisce l’intero header (predefinito `squarecloud-sdk-js/<version>`).
(nessuno)	`fetch`	`fetch` personalizzato (proxy, tracing, test).

Metodo per metodo

v5	v6	Note
`api.user.get()` → `User`	`api.account.me()`	Restituisce `{ user, applications, databases }`.
`user.plan.expiresIn`	`new Date(user.plan.duration)`	Un timestamp; `null` non scade mai.
`api.user.snapshots(scope)`	`api.account.snapshots({ scope })`
`api.service.status()`	`api.service.status()`	Nuova struttura: `status`, `message`, `services`, `dependencies`…
`api.applications.get()`	`(await api.account.me()).applications`
`api.applications.get(id)` / `fetch(id)` / `app.fetch()`	`api.apps.get(id)`	Trova anche le app condivise tramite workspace.
`app.isWebsite()`	`Boolean((await api.apps.get(id)).domain)`
`api.applications.create(file)`	`api.apps.create(file, { signal })`	Un percorso, `Blob`/`File` o `Uint8Array`; nessun timeout.
`api.applications.statusAll()`	`api.apps.statusAll({ workspaceId? })`	Oggetti semplici `{ id, running, cpu?, ram? }` (la v5 annidava `cpu`/`ram` sotto `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` e `network` sono al primo livello (la v5 li annidava sotto `usage`); `uptime` è il timestamp di avvio in ms (`null` quando arrestata), non un `Date`.
`app.getLogs()`	`api.apps.logs(id)`
`app.getMetrics()`	`api.apps.metrics(id)`	Punto più recente per primo.
`app.realtime()` → `Response` grezzo	`api.apps.realtime(id, { signal })`	Un async iterable di eventi già analizzati.
`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?)`	Una directory mancante lancia 404 `FILE_NOT_FOUND` (prima era un elenco vuoto).
`app.files.read(path)` → `Buffer \| undefined`	`api.apps.files.read(id, path)` → `Uint8Array`	Richiesto in base64 e decodificato (la v5 leggeva un array di byte). Byte vuoti, mai `undefined`, quando l’API non invia contenuto.
`app.files.create(file, fileName, dir)`	api.apps.files.write(id, `${dir}/${fileName}`, content)	Una stringa è il contenuto (inviato come testo semplice); la v5 la interpretava come percorso locale. I byte vengono inviati in base64. Un contenuto vuoto crea un file vuoto.
`app.files.edit(file, path)`	`api.apps.files.write(id, path, content)`	Stesso formato di trasmissione di `write`: testo per le stringhe, base64 per i byte.
`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)`	Ognuno restituisce le variabili risultanti.
`app.snapshots.list()`	`api.apps.snapshots.list(id)`	Gli elementi acquisiscono `name`, `runtime`, `origin`, `version_id` e un `url` di download firmato, tutti come li invia l’API.
`app.snapshots.create()`	`api.apps.snapshots.create(id)`	`{ pending: true }` in caso di 202 (la v5 lanciava un errore), altrimenti `{ pending: false, url, key }`.
`app.snapshots.download()` → `Buffer`	`const s = await api.apps.snapshots.create(id)`, poi `if (!s.pending) await api.downloadSnapshot(s.url)`	Un `ReadableStream`, nulla bufferizzato. Uno snapshot in sospeso (202) non ha ancora un URL: la v5 lanciava un errore.
`snapshot.url` / `snapshot.download()`	`snapshot.url` / `api.downloadSnapshot(snapshot.url)`	L’URL firmato dell’API (la v5 ne costruiva uno sbagliato a partire dall’id del chiamante).
`app.snapshots.restore({ snapshotId, versionId })`	`api.apps.snapshots.restore(id, name, versionId)`	Passa `name` e `version_id` di uno snapshot presente nell’elenco. Vedi Snapshot per gli errori.
`app.deploys.integrateGithubWebhook(token)`	`api.apps.deploys.setWebhook(id, token)`	Restituisce l’URL del webhook (`""` quando viene rimosso con `"@"`).
`app.deploys.linkGithubApp({ repositoryName, repositoryBranch })`	`api.apps.deploys.linkGithubApp(id, repository, branch)`	Posizionale. Restituisce `{ id, full_name, branch }`. Ora sono accettate le chiavi API (scope `apps:deploy`); la v5 richiedeva un JWT di sessione.
`app.deploys.unlinkGithubApp()` → `boolean`	`api.apps.deploys.unlinkGithubApp(id)`	Si risolve in `void` (prima `boolean`). `400 GIT_NOT_CONFIGURED` quando non c’è nulla di collegato.
`app.deploys.list()` → `Deployment[][]`	`api.apps.deploys.list(id)` → `DeployEvent[][]`	Un deploy fallito termina con `state: "error"` e `code` (e `message` quando ci sono dettagli); `source` è sempre `"git"`.
`app.deploys.current()`	`api.apps.deploys.current(id)` → `DeployCurrent`	`{}` quando non c’è nulla di configurato.
`app.deploys.webhookURL()`	`(await api.apps.deploys.current(id)).webhook`
`app.network` (solo su `WebsiteApplication`)	`api.apps.network`	Qualsiasi id di app; l’API rifiuta le app non web.
`network.setCustomDomain(domain)`	`api.apps.network.setDomain(id, domain)`
`network.analytics({ start, end, contentType, ... })`	`api.apps.network.analytics(id, start, end, { content_type, ... })`	`null` per una finestra vuota.
`network.errors({ start, end, include4xx })`	`api.apps.network.errors(id, start, end, { include_4xx })`	`null` per una finestra vuota.
`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()`	invariato	`statusAll()` restituisce oggetti semplici `{ id, running, cpu?, ram? }`.
`db.getStatus()` / `getMetrics()`	`api.databases.status(id, { raw? })` / `metrics(id)`	`ram` è la RAM in uso, ad es. `"120.4MB"` (un numero con `raw`). Le metriche arrivano dalla più recente.
`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)`	La nuova password (`""` per `"certificate"`).
`db.snapshots.list()` / `create()` / `download()`	`api.databases.snapshots.list(id)` / `create(id)` / `api.downloadSnapshot(url)`	`download()` come per le app: `create(id)`, poi `downloadSnapshot(s.url)` quando non è in sospeso.
`db.snapshots.restore(snapshotId, versionId)`	`api.databases.snapshots.restore(id, name, versionId)`	Passa `name` e `version_id` di uno snapshot presente nell’elenco.
`api.workspaces.list()` / `fetch(id)` / `workspace.fetch()`	`api.workspaces.list()` / `get(id)`
`api.workspaces.create({ name })`	`api.workspaces.create(name)`	Restituisce `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)`
(nessuno)	`api.ai.chat(request)`, `api.downloadSnapshot(url)`, `BASE_URL`	Nuovo.

Tipi

I tipi sono inclusi nell’SDK e rispecchiano i nomi dei campi dell’API. Le principali ridenominazioni rispetto a @squarecloud/api-types e alle classi della v5:

v5	v6
`Application`, `WebsiteApplication`, `BaseApplication`	`App` (`api.apps.get()`), `AppSummary` (`account.me()`), `AppCreated`
`ApplicationStatus`, `SimpleApplicationStatus`, `SimpleDatabaseStatus`	`RuntimeStats` (`RuntimeStats<true>` con `{ raw: true }`), `StatusListItem`
`User`	`Account` (`{ user, applications, databases }`), `User`, `Plan`
`Snapshot`, `DatabaseSnapshot`	`Snapshot`, `SnapshotCreated`
`Deployment`, `DeploymentState`	`DeployEvent`, `DeployCurrent` (con `DeployRepository`), `LinkedRepository`
Oggetti di query di rete	`AnalyticsFilters` (i filtri opzionali; `start` ed `end` sono argomenti)
`Workspace`	`Workspace`, `WorkspaceCreated`, `WorkspaceGroup`
`APIErrorCode` (oggetto a runtime)	`ErrorCode` (solo tipo, nessun costo a runtime; ogni codice del contratto dell’API)
`APIEndpoint`, `APIEndpoints`, `APIMethod`, `APIRequestArgs`, `APIRequestOptions`, `APIResponse`, `QueryOrBody`, `ClientEvents`, `TypedEventEmitter`, `CollectionConstructor`	Rimossi (infrastruttura delle richieste, eventi e `Collection`)

Errori

// 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
  }
}

I codici sintetici sono stati rimossi (RATE_LIMIT_EXCEEDED, PAYLOAD_TOO_LARGE, SERVER_UNAVAILABLE, UNKNOWN_ERROR_<status>): emerge il codice reale dell’API (RATE_LIMITED, KEEP_CALM, DAILY_SNAPSHOTS_LIMIT_REACHED, FILE_TOO_LARGE…).
Nessuna risposta: status: 0 con NETWORK_ERROR (la causa in cause) o TIMEOUT. Un body senza codice è UNKNOWN_ERROR con lo status reale e il messaggio HTTP <status>.
instanceof TypeError non è più vero per gli errori dell’API.
Una chiave scaduta produce 401 ACCESS_DENIED, come una sconosciuta.
Gli errori di ai.chat(), compresi autenticazione e rate limit, riportano il codice minuscolo di OpenAI (access_denied, rate_limit_exceeded, …).
Uno start/stop/restart rifiutato è un 409 con solo un codice: CONTAINER_ALREADY_STARTED, CONTAINER_ALREADY_STOPPED, CONTAINER_TEMPORARILY_SUSPENDED, CONTAINER_NOT_FOUND, CONTAINER_INSUFFICIENT_DISK_SPACE, CONTAINER_NETWORK_CONFLICT o ACTION_FAILED.

Cambiamenti di comportamento

Le chiamate vanno in timeout: 30 s per tentativo per impostazione predefinita (la v5 non aveva timeout), almeno 120 s per le chiamate che il server tiene aperte. Imposta timeoutMs: 0 per non averne.
files.write() tratta una stringa come contenuto e la invia come testo semplice; i byte vengono inviati in base64, in modo sicuro per i binari, e un contenuto vuoto crea un file vuoto (stesso formato di trasmissione degli SDK Python e Go). files.read() richiede base64 e lo decodifica.
files.list() su una directory mancante lancia 404 FILE_NOT_FOUND invece di restituire [].
snapshots.create() restituisce { pending: true } in caso di 202 invece di lanciare un errore.
I risultati stringa non sono mai undefined: setWebhook e resetCredentials("certificate") restituiscono "" quando l’API non ne invia; deploys.current() restituisce {}.
realtime() si riconnette in caso di connessioni interrotte e di REALTIME_RECONNECT (fino a 3 volte di fila, al massimo un’apertura ogni 5,5 s).
Retry: errori di rete su GET e 503 UPLOAD_BUSY/ANALYTICS_BUSY (più DATABASE_UNAVAILABLE su GET), con backoff. Un 429 non viene mai ripetuto. DATABASE_UNAVAILABLE può arrivare dopo che una mutazione è stata applicata: ripeti tu le tue mutazioni idempotenti.
Gli id vuoti, . e .. falliscono localmente con INVALID_ID.
I valori di query undefined, "" o false non vengono inviati.

CLI

VS Code

SDKs

SDK JavaScript: migrazione da v5 a v6

In sintesi

Costruzione e opzioni

Metodo per metodo

Tipi

Errori

Cambiamenti di comportamento

Prossimi passi

Client

Errori

​In sintesi

​Costruzione e opzioni

​Metodo per metodo

​Tipi

​Errori

​Cambiamenti di comportamento

​Prossimi passi

Client

Errori

In sintesi

Costruzione e opzioni

Metodo per metodo

Tipi

Errori

Cambiamenti di comportamento

Prossimi passi