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.
O módulo network só está disponível em aplicações website. Refine o tipo com app.isWebsite() antes de usá-lo:
const app = await api.applications.fetch("abc123def456abc123def456");
if (!app.isWebsite()) {
throw new Error("Esta aplicação não é um site");
}
app.network; // NetworkModule
Domínio customizado
app.network.setCustomDomain(domain) define ou remove o domínio customizado vinculado ao site.
await app.network.setCustomDomain("seusite.com");
// Passe "@" para remover o domínio customizado configurado
await app.network.setCustomDomain("@");
Domínios customizados exigem o plano Senior ou superior. Registros DNS
Depois de vincular um domínio, configure o DNS no seu registrador. app.network.dns() retorna o registro de propriedade e o status do SSL.
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"
O formato mudou na v4. app.network.dns() retornava um array de registros — agora retorna um único objeto: { ownership, ssl }.
Analytics
app.network.analytics({ start, end }) retorna analytics agregados da edge. start e end aceitam strings ISO 8601 ou Date. A janela máxima de retenção é de 7 dias.
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, "buckets de tempo");
console.log("Principais países:", analytics.countries.slice(0, 5));
console.log("Principais paths:", analytics.paths.slice(0, 5));
}
Para janelas vazias (ex.: antes da aplicação ser criada) a API retorna {}. Verifique com "visits" in analytics antes de ler os dados.
A v3 chamava esse endpoint sem argumentos. A v4 exige { start, end }.
Monitoramento de erros
app.network.errors({ start, end, include4xx? }) retorna o breakdown de erros da edge. Por padrão, apenas 5xx são considerados.
const errors = await app.network.errors({
start: since,
end: new Date(),
include4xx: true, // inclui 4xx junto dos 5xx
});
if ("summary" in errors) {
console.log(`Total: ${errors.summary.total}`);
console.log("Por classe:", errors.summary.by_class);
console.log("Paths que mais falham:", errors.top_paths.slice(0, 3));
}
Logs de requisição
app.network.logs({ start, end }) retorna os logs por requisição da edge.
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 ?? "??"})`,
);
}
Logs por requisição exigem o plano Pro ou superior. Percentis de latência
app.network.performance({ start, end }) retorna as latências p50 / p95 / p99 para as camadas edge e origin.
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("Paths mais lentos:", perf.slowest_paths.slice(0, 3));
}
Métricas de performance exigem o plano Pro ou superior. Limpando o cache da edge
app.network.purgeCache() invalida o cache inteiro da edge para os domínios da aplicação.
await app.network.purgeCache();
Na v3 (e na efêmera v4.0.0) purgeCache(paths?) aceitava uma lista de paths para invalidar de forma seletiva. A partir da v4.0.1 o argumento foi removido — chamar purgeCache() sempre limpa o cache inteiro.
