Contratos de Dados Frontend (limite de rede tipado)

Quando Usar

Use esta habilidade quando precisar de uma disciplina portátil e agnóstica de framework para segurança de tipos na borda da rede de qualquer aplicativo React ou React Native. Estabelece um cliente de API tipado como o único limite de busca, uma regra de "parse, não valide" que transforma o JSON da rede em tipos de domínio confiáveis antes que ele entre no aplicativo, análise em tempo de execução, erros normalizados e identificadores de marca.

Habilidade portátil — legível por Claude Code, OpenCode, Codex, Cursor, Windsurf e outros. Esta habilidade descreve uma disciplina na borda da rede — um cliente, um envelope, um tipo de erro único, tipos validados — não uma biblioteca de estado ou um sistema de estilização. Ela se associa à habilidade frontend-architecture (o cliente vive em shared/api-client/) e é a base sobre a qual a habilidade frontend-optimistic-mutations é construída.

O objetivo: no momento em que os dados cruzam da rede para o aplicativo, eles deixam de ser JSON da rede em formato any e se tornam um valor de domínio confiável e tipado — ou se tornam um erro único e tipado. Existe exatamente um lugar onde essa transformação acontece, e nada não tipado escapa dela.

Exemplo de contrato

Os trechos marcados como "essência" são esboços de arquitetura com dependências e métodos de projeto omitidos, não um cliente completo. Um parâmetro de tipo genérico get<Invoice> é apenas uma afirmação em tempo de compilação: ele não pode estabelecer validade em tempo de execução. Exija o parse real do esquema antes de tratar um valor como uma Fatura, normalize falhas de parser no tipo de erro do projeto e mantenha a autorização independente da validação do esquema e dos IDs de marca. Vincule o comportamento do adaptador à versão da biblioteca instalada; não assuma a existência de um callback por consulta não suportado.

0. As cinco ideias centrais

1. Um cliente é o único limite de busca. Um apiClient tipado único envolve fetch. Componentes e hooks nunca chamam fetch/axios diretamente — o limite é aplicável em revisões e lint.
2. Parse, não valide. O JSON da rede é parseado em tipos de domínio na borda. Após o retorno do cliente, o valor é confiável em qualquer lugar a jusante — sem cadeias de ?. defensivas, sem re-verificação de formas em componentes.
3. Um envelope. Toda resposta é { data } em caso de sucesso ou { error } em caso de falha. O cliente desempacota data e lança em error, então os chamadores recebem o payload diretamente ou um throw tipado.
4. Um tipo de erro normalizado. Envelope de erro do servidor, status não-2xx, corpo malformado, falha de rede e abortar se tornam um único ApiError com um código de máquina, status e erros opcionais por campo. Os chamadores lidam com uma única forma.
5. Identificadores são de marca. IDs de domínio são tipos nominais (InvoiceId, CustomerId) para que o compilador rejeite passar um onde outro é esperado — o bug silencioso mais comum em UIs com muitos dados.

1. Layout do diretório

A borda é uma pasta em shared/ (conforme a habilidade frontend-architecture).

src/shared/api-client/
├── index.ts        ← barrel: apiClient, ApiError, types
├── client.ts       ← the fetch wrapper: buildUrl, headers, parse, verbs
├── config.ts       ← base URL resolution, default headers
├── error.ts        ← the ApiError class + code→message-key mapping
├── types.ts        ← envelope types, HttpMethod, RequestOptions, field errors
└── client.test.ts  ← boundary behavior tests (envelope, errors, network)

Tipos de entidade de domínio e seus esquemas vivem com seu módulo de funcionalidade (modules/{feature}/types/) ou um pacote de contrato compartilhado; o cliente é genérico sobre T.

2. Um cliente, o único limite de busca

Cada verbo retorna o payload desempacotado data tipado pelo chamador, e lança um ApiError em qualquer falha. Componentes nunca veem envelopes ou respostas brutas.

// shared/api-client/client.ts (essence)
export const apiClient = {
  get<T>(path: string, options?: RequestOptions): Promise<T> {
    return request<T>("GET", path, undefined, options);
  },
  post<T>(path: string, body?: unknown, options?: RequestOptions): Promise<T> {
    return request<T>("POST", path, body, options);
  },
  patch<T>(path: string, body?: unknown, options?: RequestOptions): Promise<T> {
    /* … */
  },
  put<T>(path: string, body?: unknown, options?: RequestOptions): Promise<T> {
    /* … */
  },
  delete<T>(path: string, options?: RequestOptions): Promise<T> {
    /* … */
  },
} as const;

export type ApiClient = typeof apiClient;

// CORRETO — um hook de funcionalidade envolve o cliente, tipado pelo chamador

…