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

> Installiere @squarecloud/blob und erstelle einen SquareCloudBlob-Client mit einem API-Schlüssel oder einem Upload-Token. Die einzige Option ist maxRetries.

<Info>
  Diese Seite dokumentiert **`@squarecloud/blob` v4**. Du aktualisierst von v3? Lies den [Migrationsleitfaden v3 → v4](/de/sdks/blob/migrating_to_v4).
</Info>

`@squarecloud/blob` ist das offizielle JavaScript SDK für [Square Cloud Blob Storage](/de/services/blob). Es deckt jeden Endpoint der [Blob API](/de/blob-reference/authentication) sowie das [S3-Gateway](/de/blob-reference/s3-compatibility) ab.

## Voraussetzungen

* **Node.js 20** oder neuer, oder ein beliebiger moderner Browser. Das SDK verwendet nur `fetch`, `FormData` und `Blob`.
* Wird als **ESM und CommonJS** ausgeliefert, mit **null Laufzeitabhängigkeiten**.
* `@aws-sdk/client-s3` ist eine **optionale Peer-Abhängigkeit**, die nur benötigt wird, wenn du [`s3()`](/de/sdks/blob/s3) aufrufst.

## Installation

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

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

  <Tab title="pnpm">
    ```bash theme={"system"}
    pnpm add @squarecloud/blob
    ```
  </Tab>

  <Tab title="bun">
    ```bash theme={"system"}
    bun add @squarecloud/blob
    ```
  </Tab>
</Tabs>

## Client erstellen

<Tabs>
  <Tab title="ESM / TypeScript">
    ```typescript theme={"system"}
    import { SquareCloudBlob } from "@squarecloud/blob";

    const blob = new SquareCloudBlob(process.env.SQUARECLOUD_API_KEY);
    ```
  </Tab>

  <Tab title="CommonJS">
    ```javascript theme={"system"}
    const { SquareCloudBlob } = require("@squarecloud/blob");

    const blob = new SquareCloudBlob(process.env.SQUARECLOUD_API_KEY);
    ```
  </Tab>
</Tabs>

### Konstruktor

```typescript theme={"system"}
new SquareCloudBlob(credential, { maxRetries: 2 });
```

| Parameter            | Typ      | Standard     | Beschreibung                                                                                                                                                                                                                                                |
| -------------------- | -------- | ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `credential`         | `string` | erforderlich | Ein **API-Schlüssel** oder ein **Upload-Token** (`squp_...`), das nur `put()` aufrufen kann.                                                                                                                                                                |
| `options.maxRetries` | `number` | `2`          | Wie oft eine gefahrlos wiederholbare Anfrage (ein `GET` oder ein Multipart-Teil) nach einem Netzwerkfehler oder einem `5xx` wiederholt wird. `0` deaktiviert Wiederholungen. Siehe [Wiederholungsrichtlinie](/de/sdks/blob/errors#wiederholungsrichtlinie). |

## Zugangsdaten

Die Zugangsdaten werden **unverändert** im Header `Authorization` gesendet, ohne das Präfix `Bearer`.

| Zugangsdaten              | Woher sie kommen                                                                                   | Was sie können                                                                                                  |
| ------------------------- | -------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
| API-Schlüssel             | [Square Cloud Dashboard](https://squarecloud.app/account/security)                                 | Jede Methode, abhängig von ihren [Scopes](/de/blob-reference/authentication#scopes) `blob:read` / `blob:write`. |
| Upload-Token (`squp_...`) | [`blob.uploadTokens.create()`](/de/sdks/blob/uploads#hochladen-aus-dem-browser), auf deinem Server | Nur `put()`. Jede andere Methode schlägt mit `403 UPLOAD_TOKEN_NOT_ALLOWED` fehl.                               |

<Warning>
  Gib einen API-Schlüssel nie an einen Browser weiter. Erstelle auf deinem Server ein Upload-Token und übergib nur das Token an den Client.
</Warning>

## Was du nicht konfigurieren kannst

`maxRetries` ist die **einzige** Option. Der Client akzeptiert nicht:

* **Eine Basis-URL.** Sie ist fest auf `https://blob.squarecloud.app/v1/` gesetzt.
* **Ein eigenes `fetch`.** Anfragen verwenden das globale `fetch`.
* **Ein Timeout oder ein `AbortSignal`.** Ein Aufruf dauert so lange, wie `fetch` wartet, und es gibt keine Möglichkeit, ihn abzubrechen.
* **Eigene Header.**

## Methoden

Jede Methode gibt einfache Daten zurück (keine Klassen), außer `s3()`, das einen `S3Client` zurückgibt. Optionen und Ergebnisse verwenden die eigenen Feldnamen der API, meist in snake\_case (`security_hash`, `expires_at`), sodass die [Blob-API-Referenz](/de/blob-reference/authentication) unverändert gilt.

| Gruppe                | Methoden                                                                                                                                                                                        | Seite                                                      |
| --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- |
| `blob`                | `put(file, options)`                                                                                                                                                                            | [Uploads](/de/sdks/blob/uploads)                           |
| `blob.uploadTokens`   | `create(options)`                                                                                                                                                                               | [Uploads](/de/sdks/blob/uploads#hochladen-aus-dem-browser) |
| `blob`                | `list(options)`, `listPage(options)`, `info(id)`, `downloadUrl(id, options)`, `update(ids, changes)`, `delete(ids)`, `copy(source, destination, options)`, `move(source, destination, options)` | [Objekte](/de/sdks/blob/objects)                           |
| `blob.shares`         | `create(object, options)`, `list()`, `revoke(id)`                                                                                                                                               | [Freigaben](/de/sdks/blob/sharing)                         |
| `blob.rules` / `blob` | `get()`, `set(rules)` / `stats()`                                                                                                                                                               | [Regeln und Statistiken](/de/sdks/blob/rules_and_stats)    |
| `blob`                | `s3Credentials()`, `s3()`                                                                                                                                                                       | [S3](/de/sdks/blob/s3)                                     |

Das Paket exportiert außerdem `SquareCloudBlobError`, den Typ `BlobErrorCode` und jeden Options- und Ergebnistyp (`PutOptions`, `PutResult`, `ListedObject`, `ObjectInfo`, `Share`, `Rule`, ...). Siehe [Fehler](/de/sdks/blob/errors).

## Objekt-IDs

Jedes Objekt wird durch eine **opake ID** identifiziert, etwa `pub/...` für ein öffentliches oder `prv/...` für ein privates Objekt.

* **Speichere die ID genau so, wie sie zurückgegeben wird.** Baue nie eine von Hand und parse sie nie.
* **Eine Änderung von `private` oder `expire` ändert die ID.** Ersetze deine gespeicherte ID immer durch die, die [`update()`](/de/sdks/blob/objects#objekte-aktualisieren) zurückgibt.
* **Verwende die `url` aus der Antwort**, statt URLs selbst zu bauen. Private Objekte haben `url: null`: Hol dir einen Link mit [`downloadUrl()`](/de/sdks/blob/objects#download-links) oder über eine [Freigabe](/de/sdks/blob/sharing).

```typescript theme={"system"}
const { id, url } = await blob.put("./photo.png", { name: "photo", prefix: "avatars" });
// save `id` as-is; use `url` to serve the file
```