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

# Client

> Die Klasse SquareCloudAPI ist der Einstiegspunkt zum SDK. Sie wird mit einem API-Schlüssel instanziiert und stellt jedes Modul — Anwendungen, Datenbanken, Workspaces, Benutzer und Plattformdienst — über einen einzigen Client bereit.

<Info>
  Diese Seite dokumentiert **`@squarecloud/api` v4**. Wenn Sie von v3 aktualisieren, lesen Sie zuerst den [Migrationsleitfaden v3 → v4](/de/sdks/js/migrating_to_v4).
</Info>

## Voraussetzungen

* **Node.js 20.0.0** oder neuer
* Ein gültiger API-Schlüssel — fordern Sie einen im [Square Cloud Dashboard](https://squarecloud.app/de/dashboard) an

## Installation

<Tabs>
  <Tab title="npm">
    ```bash theme={null}
    npm install @squarecloud/api
    ```
  </Tab>

  <Tab title="yarn">
    ```bash theme={null}
    yarn add @squarecloud/api
    ```
  </Tab>

  <Tab title="pnpm">
    ```bash theme={null}
    pnpm add @squarecloud/api
    ```
  </Tab>
</Tabs>

## Instanziierung des Clients

<Tabs>
  <Tab title="TypeScript">
    ```typescript theme={null}
    import { SquareCloudAPI } from "@squarecloud/api";

    const api = new SquareCloudAPI(process.env.SQUARE_API_KEY!);
    ```
  </Tab>

  <Tab title="JavaScript (ESM)">
    ```javascript theme={null}
    import { SquareCloudAPI } from "@squarecloud/api";

    const api = new SquareCloudAPI(process.env.SQUARE_API_KEY);
    ```
  </Tab>

  <Tab title="JavaScript (CommonJS)">
    ```javascript theme={null}
    const { SquareCloudAPI } = require("@squarecloud/api");

    const api = new SquareCloudAPI(process.env.SQUARE_API_KEY);
    ```
  </Tab>
</Tabs>

### Konstruktor

| Parameter | Typ      | Erforderlich | Beschreibung                                                                              |
| --------- | -------- | ------------ | ----------------------------------------------------------------------------------------- |
| `apiKey`  | `string` | Ja           | Ihr Square Cloud API-Schlüssel. Der Client wirft einen Fehler, wenn dies kein String ist. |

## Module

Der Client stellt die gesamte v2-Plattform über dedizierte Module bereit. Jedes Modul ist eine Eigenschaft der `SquareCloudAPI`-Instanz.

| Eigenschaft        | Modul                                                         | Dokumentation                                             |
| ------------------ | ------------------------------------------------------------- | --------------------------------------------------------- |
| `api.user`         | Authentifizierter Benutzer, Plan, eigene Apps und Datenbanken | Diese Seite                                               |
| `api.applications` | Anwendungen auflisten, abrufen, hochladen und inspizieren     | [Anwendungen verwalten](/de/sdks/js/managing_application) |
| `api.databases`    | Datenbanken erstellen, abrufen und verwalten                  | [Datenbanken](/de/sdks/js/databases)                      |
| `api.workspaces`   | Workspaces erstellen, auflisten und verwalten                 | [Workspaces](/de/sdks/js/workspaces)                      |
| `api.service`      | Aggregierter Plattformstatus                                  | Diese Seite                                               |
| `api.cache`        | In-Memory-Cache, der durch SDK-Events befüllt wird            | Diese Seite                                               |

## Den authentifizierten Benutzer abrufen

`api.user.get()` gibt eine [`User`](https://github.com/squarecloudofc/sdk-api-js/blob/main/src/structures/user.ts)-Instanz zurück, die die Kontodetails, den aktuellen Plan, die eigenen Anwendungen und die eigenen Datenbanken enthält.

```typescript theme={null}
const user = await api.user.get();

console.log(user.id);          // "abcdef0123456789abcdef01"
console.log(user.name);        // "John Doe"
console.log(user.email);       // "john@example.com"
console.log(user.locale);      // "en-US"
console.log(user.plan.name);   // "free" | "standard" | ...
console.log(user.createdAt);   // Date

console.log(user.applications); // Collection<string, BaseApplication>
console.log(user.databases);    // Collection<string, Database>
```

`user.applications` und `user.databases` sind [`Collection`](https://github.com/squarecloudofc/sdk-api-js/blob/main/src/structures/collection.ts)-Instanzen (eine `Map`-Unterklasse). Iterieren Sie darüber wie über jede `Map`:

```typescript theme={null}
for (const [id, app] of user.applications) {
    console.log(`${app.name} (${id}) — ${app.ram}MB ${app.language}`);
}
```

## Eine einzelne Anwendung abrufen

Verwenden Sie `api.applications.fetch(id)`, um eine vollständig befüllte `Application` (oder `WebsiteApplication`, wenn die App eine Website-Domain hat) abzurufen.

```typescript theme={null}
const app = await api.applications.fetch("abc123def456abc123def456");

console.log(app.id, app.name, app.cluster, app.createdAt);

if (app.isWebsite()) {
    // eingegrenzt auf WebsiteApplication — `.network` ist verfügbar
    await app.network.purgeCache();
}
```

Die veraltete Überladung `api.applications.get(id)` existiert weiterhin, gibt aber die leichtgewichtigere `BaseApplication` zurück und wird nur aus Gründen der Abwärtskompatibilität beibehalten. **Bevorzugen Sie `.fetch()` für v4.**

## Snapshot-Verlauf auflisten (kontoweit)

```typescript theme={null}
const appSnapshots = await api.user.snapshots("applications");
const dbSnapshots  = await api.user.snapshots("databases");
```

Siehe [Snapshots](/de/sdks/js/snapshots) für Details zu Snapshot-Payloads.

## Plattformstatus

`api.service.status()` stellt den aggregierten Plattformzustand bereit (dieselben Daten, die auf der öffentlichen Statusseite angezeigt werden).

```typescript theme={null}
const status = await api.service.status();

console.log(status.status);  // "ok" | "degraded" | "down"
console.log(status.message); // menschenlesbare Zusammenfassung
```

<Note>
  Anders als die meisten v2-Endpoints kapselt diese Route ihr Payload **nicht** in den Standard-Envelope `{ status, response }`.
</Note>

## Client-Cache

Der Client unterhält einen In-Memory-Cache, den das SDK synchron hält, während Sie Aufrufe tätigen:

```typescript theme={null}
api.cache.user;   // zuletzt abgerufener User
// jede Anwendungsinstanz stellt außerdem app.cache.status / .logs / .snapshots bereit
```

Das SDK emittiert typisierte Events, die Sie abonnieren können:

```typescript theme={null}
api.on("userUpdate", (previous, current) => {
    console.log("user changed:", current.name);
});

api.on("statusUpdate", (application, previous, current) => {
    console.log(`${application.name} → ${current.status}`);
});

api.on("logsUpdate", (application, previous, current) => {
    console.log(`new logs for ${application.name}`);
});

api.on("snapshotsUpdate", (application, previous, current) => {
    console.log(`${current.length} snapshots for ${application.name}`);
});
```

## Fehlerbehandlung

Fehlgeschlagene Anfragen werfen einen `SquareCloudAPIError`. Der Fehler stellt eine stabile `code`-Eigenschaft bereit, auf die Sie verzweigen können, um Fehlermodi zu unterscheiden.

```typescript theme={null}
import { SquareCloudAPI, SquareCloudAPIError } from "@squarecloud/api";

try {
    const app = await api.applications.fetch("invalid-id");
} catch (err) {
    if (err instanceof SquareCloudAPIError) {
        console.error(err.code);    // e.g. "APP_NOT_FOUND"
        console.error(err.message);
    }
}
```