> ## 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. # Migrazione a v6 > Cosa è cambiato tra @squarecloud/api v5 e v6: dati semplici invece di classi, id come primo argomento, un'unica classe di errore, timeout e retry. Una tabella metodo per metodo. 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` (sempre `true`) | `Promise`, 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](#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/`). | | (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](/it/sdks/js/snapshots#ripristinare-uno-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` 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 ```ts theme={"system"} // 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_`): 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 `. * `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.