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

# Network & Edge

> Verwalte Custom-Domains, DNS, Edge-Analytics, Fehler-Tracking, Request-Logs, Latenz-Perzentile und Cache-Invalidierung für Website-Anwendungen.

Das `network`-Modul ist nur bei **Website-Anwendungen** verfügbar. Grenze den Typ zuerst mit `app.isWebsite()` ein:

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

if (!app.isWebsite()) {
    throw new Error("This application is not a website");
}

app.network; // NetworkModule
```

## Custom-Domain

`app.network.setCustomDomain(domain)` setzt oder entfernt die an die Website gebundene Custom-Domain.

```typescript theme={null}
await app.network.setCustomDomain("yoursite.com");

// Übergib "@", um die konfigurierte Custom-Domain zu entfernen
await app.network.setCustomDomain("@");
```

<Note>
  Custom-Domains erfordern einen [Senior-Plan](https://squarecloud.app/plans) oder höher.
</Note>

## DNS-Einträge

Nachdem du eine Custom-Domain angebunden hast, musst du DNS bei deinem Registrar konfigurieren. `app.network.dns()` liefert den Ownership-Eintrag und den SSL-Status.

```typescript theme={null}
const dns = await app.network.dns();

console.log(`${dns.ownership.type} ${dns.ownership.name} → ${dns.ownership.value}`);
console.log(`SSL: ${dns.ssl.status}`); // "pending" | "pending_validation" | "active"
```

<Warning>
  Die Form hat sich in v4 geändert. `app.network.dns()` lieferte zuvor ein Array von Einträgen — jetzt liefert es ein einzelnes Objekt: `{ ownership, ssl }`.
</Warning>

## Analytics

`app.network.analytics({ start, end })` liefert aggregierte Edge-Analytics. `start` und `end` akzeptieren entweder ISO-8601-Strings oder `Date`-Objekte. Das maximale Aufbewahrungsfenster beträgt **7 Tage**.

```typescript theme={null}
const since = new Date(Date.now() - 24 * 60 * 60 * 1000);

const analytics = await app.network.analytics({
    start: since,
    end: new Date(),
});

if ("visits" in analytics) {
    console.log(analytics.visits.length, "time buckets");
    console.log("Top countries:", analytics.countries.slice(0, 5));
    console.log("Top paths:",     analytics.paths.slice(0, 5));
}
```

<Warning>
  Für leere Fenster (z. B. vor der Erstellung der App) liefert die API `{}`. Sichere mit `"visits" in analytics` ab, bevor du liest.
</Warning>

<Warning>
  v3 rief diesen Endpoint ohne Argumente auf. **v4 erfordert `{ start, end }`.**
</Warning>

## Fehler-Tracking

`app.network.errors({ start, end, include4xx? })` liefert die Aufschlüsselung der Edge-Fehler. Standardmäßig werden nur 5xx-Fehler einbezogen.

```typescript theme={null}
const errors = await app.network.errors({
    start: since,
    end: new Date(),
    include4xx: true, // 4xx zusätzlich zu 5xx einbeziehen
});

if ("summary" in errors) {
    console.log(`Total: ${errors.summary.total}`);
    console.log("By class:",          errors.summary.by_class);
    console.log("Top failing paths:", errors.top_paths.slice(0, 3));
}
```

## Per-Request-Logs

`app.network.logs({ start, end })` liefert die Edge-Logs pro Request.

```typescript theme={null}
const logs = await app.network.logs({ start: since, end: new Date() });

for (const log of logs.slice(0, 5)) {
    console.log(
        log.timestamp,
        log.request.method, log.request.path,
        "→",
        log.response.status,
        `(${log.client.country ?? "??"})`,
    );
}
```

<Note>
  Per-Request-Logs erfordern einen [Pro-Plan](https://squarecloud.app/plans) oder höher.
</Note>

## Latenz-Perzentile

`app.network.performance({ start, end })` liefert p50-/p95-/p99-Latenzen für die Edge- und Origin-Schichten.

```typescript theme={null}
const perf = await app.network.performance({ start: since, end: new Date() });

if ("summary" in perf) {
    const { p50, p95, p99 } = perf.summary.edge;
    console.log(`Edge p50/p95/p99: ${p50}/${p95}/${p99}ms`);
    console.log("Slowest paths:", perf.slowest_paths.slice(0, 3));
}
```

<Note>
  Performance-Metriken erfordern einen [Pro-Plan](https://squarecloud.app/plans) oder höher.
</Note>

## Leeren des Edge-Caches

`app.network.purgeCache()` invalidiert den gesamten Edge-Cache für die Domains der Anwendung.

```typescript theme={null}
await app.network.purgeCache();
```

<Warning>
  In v3 (und dem kurzlebigen v4.0.0) akzeptierte `purgeCache(paths?)` eine Liste von Pfaden zum selektiven Leeren. **Ab v4.0.1 wurde das Argument entfernt** — ein Aufruf von `purgeCache()` leert immer den gesamten Cache.
</Warning>