SDK JavaScript: quickstart e client

Questa pagina documenta @squarecloud/api v6, una riscrittura dell’SDK. Arrivi dalla v5? Leggi la guida alla migrazione v5 → v6.

Requisiti

Node.js 22 o più recente, Deno, Bun o un runtime edge. All’SDK servono solo fetch, FormData, Blob e i web stream.
Una chiave API (vedi Chiave API e scope).

Il pacchetto include build ESM e CommonJS, non ha dipendenze a runtime e contiene i propri tipi TypeScript: non ti serve più @squarecloud/api-types.

Installazione

npm
pnpm
yarn
bun
deno

npm install @squarecloud/api

pnpm add @squarecloud/api

yarn add @squarecloud/api

bun add @squarecloud/api

deno add npm:@squarecloud/api

Chiave API e scope

Crea una chiave su squarecloud.app/account/security. L’SDK la invia così com’è nell’header Authorization (senza prefisso Bearer). Una chiave può essere limitata a determinati scope (apps:read, apps:deploy, apps:control, ai:chat, …) e ad app o database specifici:

Una chiamata al di fuori di questi limiti lancia un SquareCloudAPIError con 403 MISSING_SCOPE o RESOURCE_NOT_ALLOWED.
I metodi di elenco (account.me(), apps.statusAll(), …) restituiscono solo le risorse che la chiave può vedere.
Una chiave sconosciuta, revocata o scaduta produce 401 ACCESS_DENIED.

Tieni la chiave sul server. L’SDK funziona anche nel browser, ma in quel caso la chiave sarebbe esposta a ogni visitatore.

Gli esempi leggono la chiave dalla variabile d’ambiente SQUARECLOUD_API_KEY. Impostala nel terminale in cui li esegui:

macOS / Linux
Windows (PowerShell)

export SQUARECLOUD_API_KEY="your-api-key"

$env:SQUARECLOUD_API_KEY = "your-api-key"

Creare il client

TypeScript / ESM
CommonJS

import { SquareCloudAPI } from "@squarecloud/api";

const api = new SquareCloudAPI(process.env.SQUARECLOUD_API_KEY!);

const { user, applications } = await api.account.me();
console.log(`Hi ${user.name}, you have ${applications.length} apps`);

const { SquareCloudAPI } = require("@squarecloud/api");

const api = new SquareCloudAPI(process.env.SQUARECLOUD_API_KEY);

Il primo esempio stampa il nome del tuo account e il numero di app che la chiave può vedere:

Hi Jane, you have 3 apps

Una chiave vuota o composta solo da spazi lancia un TypeError nel costruttore, prima di qualsiasi richiesta.

Opzioni

import { BASE_URL, SquareCloudAPI } from "@squarecloud/api";

const api = new SquareCloudAPI(process.env.SQUARECLOUD_API_KEY!, {
    baseUrl: BASE_URL, // "https://api.squarecloud.app/v2" (default)
    timeoutMs: 30_000,
    maxRetries: 2,
    userAgent: "my-bot/1.0",
    fetch, // any fetch-compatible function (proxy, tracing, tests)
});

Opzione	Predefinito	Descrizione
`baseUrl`	`https://api.squarecloud.app/v2`	URL base dell’API. Una `/` finale viene rimossa. Esportato anche come `BASE_URL`.
`timeoutMs`	`30000`	Timeout per tentativo, che copre l’intera risposta. Vedi Timeout.
`maxRetries`	`2`	Retry solo dei fallimenti sicuri (fino a 3 tentativi). Un valore negativo conta come `0`. Vedi Retry.
`userAgent`	`squarecloud-sdk-js/<version>`	Sostituisce l’intero header `User-Agent`.
`fetch`	il `fetch` globale	Un `fetch` personalizzato per proxy, tracing o test.

La chiave API è memorizzata come normale proprietà dell’oggetto client. Non fare console.log né serializzare il client.

Moduli

Proprietà	Copre	Pagina
`api.account`	`me()`, `snapshots({ scope })`	Account e Snapshot
`api.service`	`status()`	Stato della piattaforma
`api.apps`	Recupero, eliminazione, stato, ciclo di vita, log, metriche, domini, load balancer	Gestire le applicazioni
`api.apps.create` / `commit`	Upload	Commit e upload
`api.apps.files`	File manager	Gestire i file
`api.apps.envs`	Variabili d’ambiente	Variabili d’ambiente
`api.apps.deploys`	Deploy tramite webhook e GitHub App	Deploy
`api.apps.network`	Analytics, log, DNS, dominio personalizzato, cache	Rete
`api.apps.realtime`	Log e stato in tempo reale	Realtime
`api.apps.snapshots` / `api.databases.snapshots` / `api.downloadSnapshot`	Backup	Snapshot
`api.databases`	Database gestiti	Database
`api.workspaces`	Workspace, membri e app condivise	Workspace
`api.ai`	`chat()`	AI

Gli unici export a runtime sono SquareCloudAPI, SquareCloudAPIError e BASE_URL. Ogni altro export (App, RuntimeStats, ErrorCode, …) è un tipo:

import type { App, Snapshot } from "@squarecloud/api";

Convenzioni

Prima gli id, in risposta dati semplici

Ogni metodo accetta l’id della risorsa come primo argomento e restituisce dati semplici (niente classi, niente cache). I nomi dei campi sono quelli dell’API (created_at, version_id, lastModified, joinedAt, netIO, …), quindi il riferimento API si applica così com’è.

Le mutazioni si risolvono in void, a meno che l’API non restituisca dati (envs.*, deploys.setWebhook, deploys.linkGithubApp, databases.resetCredentials e i metodi create).
Un risultato stringa non è mai undefined: è "" quando l’API non ne invia.
Gli elenchi arrivano completi in una sola chiamata: non c’è paginazione.

I metodi sono arrow function, quindi puoi destrutturarli:

const { restart, logs } = api.apps;

await restart(appId);
console.log(await logs(appId));

App dei workspace

Ogni appId accetta anche la forma composta <appId>-<workspaceId> per agire su un’app condivisa con te tramite un workspace. workspaces.get() e workspaces.list() restituiscono gli id grezzi; l’id composto lo costruisci tu:

await api.apps.restart(`${appId}-${workspaceId}`);

Gli id vengono codificati

Gli id nel percorso dell’URL sono codificati in percent-encoding. Un id vuoto, . o .. raggiungerebbe una route diversa, quindi fallisce localmente con INVALID_ID (status 0) prima che venga inviato qualsiasi cosa. Le route dei workspace invece inviano i loro id nel body: lì, INVALID_ID (400) proviene dal server.

Date

Gli argomenti start ed end (vedi Rete) accettano una stringa ISO 8601 o un Date. Le date nelle risposte restano come le invia l’API (stringhe ISO, o millisecondi Unix dove l’API li usa).

Timeout

Chiamata	Timeout
Tutte le altre chiamate	`timeoutMs` (30 s) per tentativo
Chiamate che il server tiene aperte: `start`/`stop`/`restart` delle app, `start`/`stop` dei database, `databases.create`, `create`/`restore` degli snapshot, `ai.chat`	Almeno 120 s (prevale un `timeoutMs` più grande)
Upload (`apps.create`, `apps.commit`), `files.write` oltre 1 MiB, `downloadSnapshot`	Nessuno: passa un `signal` per annullare
`apps.realtime`	Solo fino all’arrivo degli header della risposta

Un timeoutMs pari a 0 o inferiore, Infinity o >= 2^31 disattiva tutti i timeout, comprese le soglie minime di 120 s. Solo cinque metodi accettano un AbortSignal: apps.create, apps.commit, files.write, apps.realtime e downloadSnapshot.

const controller = new AbortController();
setTimeout(() => controller.abort(), 60_000);

await api.apps.commit(appId, "./build.zip", { signal: controller.signal });

Una chiamata annullata viene rifiutata con il reason del signal, non con un SquareCloudAPIError. Un ciclo realtime() annullato semplicemente termina.

Account

api.account.me() restituisce l’utente autenticato insieme alle app e ai database che la chiave può vedere.

const { user, applications, databases } = await api.account.me();

console.log(user.id, user.name, user.email, user.plan.name);
console.log(user.plan.memory); // { limit, available, used } in MB
console.log(user.plan.duration ? new Date(user.plan.duration) : "never expires");

Campo	Descrizione
`user`	`id`, `name`, `email`, `locale`, `created_at` e `plan` (`name`, `memory`, `duration`: i ms Unix in cui il piano scade, `null` se non scade mai)
`applications`	Array di `{ id, name, desc?, ram, lang, domain?, custom?, cluster, created_at }`
`databases`	Array di `{ id, name, ram, type, cluster, created_at }`

api.account.snapshots({ scope }) elenca tutti gli snapshot dell’account: vedi Snapshot.

Stato della piattaforma

api.service.status() restituisce lo stato pubblico della piattaforma. La route non richiede una chiave valida, ma il client ne richiede comunque una non vuota.

const status = await api.service.status();

console.log(status.status); // "online" | "degraded" | "unknown"
console.log(status.message);

for (const [name, service] of Object.entries(status.services ?? {})) {
    console.log(name, service.status); // "operational" | "degraded" | "outage" | "maintenance" | "unknown"
}

unknown significa che il controllo stesso non è stato possibile: non è la prova di un disservizio.

Prossimi passi

Gestire le applicazioni

Stato, ciclo di vita, log e metriche.

Errori

Classe di errore, retry e rate limit.

Introduzione all'API

URL base, autenticazione e una prima richiesta.

Quickstart della CLI

Fai il deploy e gestisci le app dal terminale.

CLI

VS Code

SDKs

SDK JavaScript: quickstart e client

Requisiti

Installazione

Chiave API e scope

Creare il client

Opzioni

Moduli

Convenzioni

Prima gli id, in risposta dati semplici

App dei workspace

Gli id vengono codificati

Date

Timeout

Account

Stato della piattaforma

Prossimi passi

Gestire le applicazioni

Errori

Introduzione all'API

Quickstart della CLI

​Requisiti

​Installazione

​Chiave API e scope

​Creare il client

​Opzioni

​Moduli

​Convenzioni

​Prima gli id, in risposta dati semplici

​App dei workspace

​Gli id vengono codificati

​Date

​Timeout

​Account

​Stato della piattaforma

​Prossimi passi

Gestire le applicazioni

Errori

Introduzione all'API

Quickstart della CLI

Requisiti

Installazione

Chiave API e scope

Creare il client

Opzioni

Moduli

Convenzioni

Prima gli id, in risposta dati semplici

App dei workspace

Gli id vengono codificati

Date

Timeout

Account

Stato della piattaforma

Prossimi passi