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

> Gérez les domaines personnalisés, le DNS, les analytics edge, le suivi des erreurs, les logs de requêtes, les percentiles de latence et l'invalidation du cache pour les applications de type site web.

Le module `network` n'est disponible que sur les **applications de type site web**. Restreignez d'abord le type avec `app.isWebsite()` :

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

## Domaine personnalisé

`app.network.setCustomDomain(domain)` définit ou supprime le domaine personnalisé associé au site web.

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

// Passez "@" pour supprimer le domaine personnalisé configuré
await app.network.setCustomDomain("@");
```

<Note>
  Les domaines personnalisés nécessitent un [plan Senior](https://squarecloud.app/plans) ou supérieur.
</Note>

## Enregistrements DNS

Après avoir associé un domaine personnalisé, vous devez configurer le DNS chez votre registrar. `app.network.dns()` renvoie l'enregistrement de propriété et le statut SSL.

```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>
  La forme a changé en v4. `app.network.dns()` renvoyait auparavant un tableau d'enregistrements — il renvoie désormais un objet unique : `{ ownership, ssl }`.
</Warning>

## Analytics

`app.network.analytics({ start, end })` renvoie les analytics edge agrégées. `start` et `end` acceptent soit des chaînes ISO 8601, soit des objets `Date`. La fenêtre de rétention maximale est de **7 jours**.

```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>
  Pour les fenêtres vides (par exemple avant la création de l'application), l'API renvoie `{}`. Protégez-vous avec `"visits" in analytics` avant toute lecture.
</Warning>

<Warning>
  La v3 appelait cet endpoint sans argument. **La v4 requiert `{ start, end }`.**
</Warning>

## Suivi des erreurs

`app.network.errors({ start, end, include4xx? })` renvoie la ventilation des erreurs edge. Par défaut, seules les erreurs 5xx sont incluses.

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

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

## Logs par requête

`app.network.logs({ start, end })` renvoie les logs edge par requête.

```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>
  Les logs par requête nécessitent un [plan Pro](https://squarecloud.app/plans) ou supérieur.
</Note>

## Percentiles de latence

`app.network.performance({ start, end })` renvoie les latences p50 / p95 / p99 pour les couches edge et origin.

```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>
  Les métriques de performance nécessitent un [plan Pro](https://squarecloud.app/plans) ou supérieur.
</Note>

## Purger le cache edge

`app.network.purgeCache()` invalide l'intégralité du cache edge pour les domaines de l'application.

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

<Warning>
  En v3 (et lors de l'éphémère v4.0.0), `purgeCache(paths?)` acceptait une liste de chemins à purger de façon sélective. **À partir de la v4.0.1, l'argument a été supprimé** — appeler `purgeCache()` purge toujours l'intégralité du cache.
</Warning>