JavaScript-SDK: Schnellstart und Client

Diese Seite dokumentiert @squarecloud/api v6, eine Neuentwicklung des SDK. Du kommst von v5? Lies den Migrationsleitfaden v5 → v6.

Voraussetzungen

Node.js 22 oder neuer, Deno, Bun oder eine Edge-Runtime. Das SDK benötigt nur fetch, FormData, Blob und Web Streams.
Ein API-Schlüssel (siehe API-Schlüssel und Scopes).

Das Paket enthält ESM- und CommonJS-Builds, hat keine Laufzeitabhängigkeiten und bringt seine eigenen TypeScript-Typen mit: @squarecloud/api-types brauchst du nicht mehr.

Installation

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

API-Schlüssel und Scopes

Erstelle einen Schlüssel unter squarecloud.app/account/security. Das SDK sendet ihn unverändert im Header Authorization (ohne das Präfix Bearer). Ein Schlüssel kann auf Scopes (apps:read, apps:deploy, apps:control, ai:chat, …) und auf bestimmte Apps oder Datenbanken beschränkt werden:

Ein Aufruf außerhalb dieser Grenzen wirft einen SquareCloudAPIError mit 403 MISSING_SCOPE oder RESOURCE_NOT_ALLOWED.
Listenmethoden (account.me(), apps.statusAll(), …) geben nur die Ressourcen zurück, die der Schlüssel sehen kann.
Ein unbekannter, widerrufener oder abgelaufener Schlüssel ergibt 401 ACCESS_DENIED.

Behalte den Schlüssel auf dem Server. Das SDK läuft zwar auch im Browser, aber dort wäre der Schlüssel für jeden Besucher sichtbar.

Die Beispiele lesen den Schlüssel aus der Umgebungsvariable SQUARECLOUD_API_KEY. Setze sie in dem Terminal, in dem du sie ausführst:

macOS / Linux
Windows (PowerShell)

export SQUARECLOUD_API_KEY="your-api-key"

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

Client erstellen

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);

Das erste Beispiel gibt deinen Kontonamen und die Anzahl der Apps aus, die der Schlüssel sehen kann:

Hi Jane, you have 3 apps

Ein leerer oder nur aus Leerzeichen bestehender Schlüssel wirft im Konstruktor einen TypeError, noch vor jeder Anfrage.

Optionen

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)
});

Option	Standard	Beschreibung
`baseUrl`	`https://api.squarecloud.app/v2`	Basis-URL der API. Ein abschließendes `/` wird entfernt. Wird auch als `BASE_URL` exportiert.
`timeoutMs`	`30000`	Timeout pro Versuch, der die gesamte Antwort abdeckt. Siehe Timeouts.
`maxRetries`	`2`	Wiederholungen nur bei sicheren Fehlern (bis zu 3 Versuche). Ein negativer Wert zählt als `0`. Siehe Wiederholungen.
`userAgent`	`squarecloud-sdk-js/<version>`	Ersetzt den gesamten `User-Agent`-Header.
`fetch`	das globale `fetch`	Ein eigenes `fetch` für Proxys, Tracing oder Tests.

Der API-Schlüssel wird als normale Eigenschaft des Client-Objekts gespeichert. Gib den Client nicht mit console.log aus und serialisiere ihn nicht.

Module

Eigenschaft	Umfang	Seite
`api.account`	`me()`, `snapshots({ scope })`	Konto und Snapshots
`api.service`	`status()`	Plattformstatus
`api.apps`	Abrufen, Löschen, Status, Lebenszyklus, Logs, Metriken, Domains, Load Balancer	Anwendungen verwalten
`api.apps.create` / `commit`	Uploads	Commit und Upload
`api.apps.files`	Dateimanager	Dateien verwalten
`api.apps.envs`	Umgebungsvariablen	Umgebungsvariablen
`api.apps.deploys`	Deploys per Webhook und GitHub App	Deploys
`api.apps.network`	Analytics, Logs, DNS, eigene Domain, Cache	Netzwerk
`api.apps.realtime`	Live-Logs und -Status	Realtime
`api.apps.snapshots` / `api.databases.snapshots` / `api.downloadSnapshot`	Backups	Snapshots
`api.databases`	Verwaltete Datenbanken	Datenbanken
`api.workspaces`	Workspaces, Mitglieder und geteilte Apps	Workspaces
`api.ai`	`chat()`	KI

Die einzigen Laufzeit-Exporte sind SquareCloudAPI, SquareCloudAPIError und BASE_URL. Jeder andere Export (App, RuntimeStats, ErrorCode, …) ist ein Typ:

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

Konventionen

Zuerst die ID, zurück kommen einfache Daten

Jede Methode nimmt die ID der Ressource als erstes Argument und gibt einfache Daten zurück (keine Klassen, kein Cache). Die Feldnamen sind die der API (created_at, version_id, lastModified, joinedAt, netIO, …), daher gilt die API-Referenz unverändert.

Mutationen werden zu void aufgelöst, sofern die API keine Daten zurückgibt (envs.*, deploys.setWebhook, deploys.linkGithubApp, databases.resetCredentials und die create-Methoden).
Ein String-Ergebnis ist nie undefined: Es ist "", wenn die API keines sendet.
Listen kommen vollständig in einem Aufruf: Es gibt keine Paginierung.

Die Methoden sind Arrow Functions, du kannst sie also destrukturieren:

const { restart, logs } = api.apps;

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

Workspace-Apps

Jede appId akzeptiert auch die zusammengesetzte Form <appId>-<workspaceId>, um auf eine App zuzugreifen, die über einen Workspace mit dir geteilt wird. workspaces.get() und workspaces.list() geben die reinen IDs zurück; die zusammengesetzte ID baust du selbst:

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

IDs werden kodiert

IDs im URL-Pfad werden prozentkodiert. Eine ID, die leer, . oder .. ist, würde eine andere Route erreichen und schlägt daher lokal mit INVALID_ID (Status 0) fehl, bevor etwas gesendet wird. Workspace-Routen senden ihre IDs stattdessen im Body: Dort kommt INVALID_ID (400) vom Server.

Datumsangaben

Die Argumente start und end (siehe Netzwerk) akzeptieren einen ISO-8601-String oder ein Date. Datumsangaben in Antworten bleiben so, wie die API sie sendet (ISO-Strings oder Unix-Millisekunden, wo die API diese verwendet).

Timeouts

Aufruf	Timeout
Jeder andere Aufruf	`timeoutMs` (30 s) pro Versuch
Aufrufe, die der Server offen hält: `start`/`stop`/`restart` von Apps, `start`/`stop` von Datenbanken, `databases.create`, Snapshot-`create`/`restore`, `ai.chat`	Mindestens 120 s (ein größeres `timeoutMs` hat Vorrang)
Uploads (`apps.create`, `apps.commit`), `files.write` über 1 MiB, `downloadSnapshot`	Keiner: Übergib ein `signal`, um abzubrechen
`apps.realtime`	Nur bis die Antwort-Header eintreffen

Ein timeoutMs von 0 oder weniger, Infinity oder >= 2^31 deaktiviert jedes Timeout, einschließlich der Mindestwerte von 120 s. Nur fünf Methoden akzeptieren ein AbortSignal: apps.create, apps.commit, files.write, apps.realtime und downloadSnapshot.

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

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

Ein abgebrochener Aufruf wird mit dem reason des Signals abgelehnt, nicht mit einem SquareCloudAPIError. Eine abgebrochene realtime()-Schleife endet einfach.

Konto

api.account.me() gibt den authentifizierten Benutzer sowie die Apps und Datenbanken zurück, die der Schlüssel sehen kann.

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");

Feld	Beschreibung
`user`	`id`, `name`, `email`, `locale`, `created_at` und `plan` (`name`, `memory`, `duration`: der Unix-ms-Zeitpunkt, zu dem der Plan abläuft, `null`, wenn er nie abläuft)
`applications`	Array von `{ id, name, desc?, ram, lang, domain?, custom?, cluster, created_at }`
`databases`	Array von `{ id, name, ram, type, cluster, created_at }`

api.account.snapshots({ scope }) listet jeden Snapshot des Kontos auf: siehe Snapshots.

Plattformstatus

api.service.status() gibt den öffentlichen Plattformstatus zurück. Die Route benötigt keinen gültigen Schlüssel, der Client verlangt aber trotzdem einen nicht leeren.

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 bedeutet, dass die Prüfung selbst nicht ausgeführt werden konnte: Es ist kein Beleg für einen Ausfall.

Nächste Schritte

Anwendungen verwalten

Status, Lebenszyklus, Logs und Metriken.

Fehler

Fehlerklasse, Wiederholungen und Rate Limits.

Einführung in die API

Basis-URL, Authentifizierung und eine erste Anfrage.

CLI-Schnellstart

Apps im Terminal deployen und verwalten.

CLI

VS Code

SDKs

JavaScript-SDK: Schnellstart und Client

Voraussetzungen

Installation

API-Schlüssel und Scopes

Client erstellen

Optionen

Module

Konventionen

Zuerst die ID, zurück kommen einfache Daten

Workspace-Apps

IDs werden kodiert

Datumsangaben

Timeouts

Konto

Plattformstatus

Nächste Schritte

Anwendungen verwalten

Fehler

Einführung in die API

CLI-Schnellstart

​Voraussetzungen

​Installation

​API-Schlüssel und Scopes

​Client erstellen

​Optionen

​Module

​Konventionen

​Zuerst die ID, zurück kommen einfache Daten

​Workspace-Apps

​IDs werden kodiert

​Datumsangaben

​Timeouts

​Konto

​Plattformstatus

​Nächste Schritte

Anwendungen verwalten

Fehler

Einführung in die API

CLI-Schnellstart

Voraussetzungen

Installation

API-Schlüssel und Scopes

Client erstellen

Optionen

Module

Konventionen

Zuerst die ID, zurück kommen einfache Daten

Workspace-Apps

IDs werden kodiert

Datumsangaben

Timeouts

Konto

Plattformstatus

Nächste Schritte