Skip to main content
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

Costruzione e opzioni

Metodo per metodo

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:

Errori

  • 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.