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

> Gestiona dominios personalizados, DNS, analíticas de edge, seguimiento de errores, logs de solicitudes, percentiles de latencia e invalidación de caché para aplicaciones de tipo sitio web.

El módulo `network` solo está disponible en **aplicaciones de tipo sitio web**. Restringe el tipo con `app.isWebsite()` primero:

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

## Dominio personalizado

`app.network.setCustomDomain(domain)` define o elimina el dominio personalizado vinculado al sitio web.

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

// Pasa "@" para eliminar el dominio personalizado configurado
await app.network.setCustomDomain("@");
```

<Note>
  Los dominios personalizados requieren un [plan Senior](https://squarecloud.app/plans) o superior.
</Note>

## Registros DNS

Después de asociar un dominio personalizado necesitas configurar el DNS en tu registrador. `app.network.dns()` devuelve el registro de propiedad y el estado del 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 forma cambió en v4. `app.network.dns()` anteriormente devolvía un array de registros — ahora devuelve un único objeto: `{ ownership, ssl }`.
</Warning>

## Analíticas

`app.network.analytics({ start, end })` devuelve analíticas de edge agregadas. `start` y `end` aceptan tanto strings ISO 8601 como objetos `Date`. La ventana máxima de retención es de **7 días**.

```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>
  Para ventanas vacías (p. ej. antes de que se creara la aplicación) la API devuelve `{}`. Protégelo con `"visits" in analytics` antes de leer.
</Warning>

<Warning>
  En v3 este endpoint se llamaba sin argumentos. **v4 requiere `{ start, end }`.**
</Warning>

## Seguimiento de errores

`app.network.errors({ start, end, include4xx? })` devuelve el desglose de errores del edge. Por defecto solo se incluyen los errores 5xx.

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

`app.network.logs({ start, end })` devuelve los logs de edge por solicitud.

```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>
  Los logs por solicitud requieren un [plan Pro](https://squarecloud.app/plans) o superior.
</Note>

## Percentiles de latencia

`app.network.performance({ start, end })` devuelve las latencias p50 / p95 / p99 para las capas de edge y origen.

```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>
  Las métricas de rendimiento requieren un [plan Pro](https://squarecloud.app/plans) o superior.
</Note>

## Purga de la caché de edge

`app.network.purgeCache()` invalida toda la caché de edge para los dominios de la aplicación.

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

<Warning>
  En v3 (y en la efímera v4.0.0) `purgeCache(paths?)` aceptaba una lista de rutas para purgar de forma selectiva. **A partir de v4.0.1 el argumento fue eliminado** — llamar a `purgeCache()` siempre purga toda la caché.
</Warning>