# AbacatePay TypeBox
Schemas oficiais da API da AbacatePay usando **TypeBox** — validação runtime, contratos tipados e base para geração automática de OpenAPI.
O [`@abacatepay/typebox`](https://www.npmjs.com/package/@abacatepay/typebox) expõe **todos os schemas públicos da API**, refletindo fielmente a documentação oficial, sem abstrações extras ou invenções.
Projetado para **TypeScript-first**, integração direta com **Elysia, Fastify, Hono** e runtimes modernos como **Node.js e Bun**.
## Instalação
Use com o seu *package manager* favorito
## Estrutura e versionamento
Assim como o [`@abacatepay/types`](https://www.npmjs.com/package/@abacatepay/types), você deve importar os schemas a partir da versão da API desejada:
```ts
import { APICustomer } from '@abacatepay/typebox/v1';
import { APISubscription } from '@abacatepay/typebox/v2';
```
Schemas globais (version, utilitátios etc) são exportados sem versão
```ts
import { version } from '@abacatepay/typebox';
```
## Integração com Elysia
O TypeBox encaixa aqui perfeitamente e diretamente com o Elysia, sem abstrações
```ts
import { Elysia } from 'elysia';
import {
APIResponse,
APICheckout,
RESTPostCreateNewCheckoutBody,
} from '@abacatepay/typebox/v2';
new Elysia().post(
'/checkouts/create',
() => { ... },
{
body: RESTPostCreateNewCheckoutBody,
response: APIResponse(APICheckout),
detail: {
tags: ['Checkouts'],
summary: 'Create a new checkout',
},
},
);
```
## Uso básico
Você pode validar fácilmente um payload retornado pela API em runtime
```ts
import { Value } from '@sinclair/typebox/value';
import { APICheckout } from '@abacatepay/typebox/v2';
const data = await fetchCheckout();
if (!Value.Check(APICheckout, data)) {
throw new Error('Invalid checkout payload');
}
```
## OpenAPI
Todos os schemas são compatíveis com **OpenAPI 3.1** via JSON Schema.
Isso permite:
- SDKs tipados.
- Geração automática de documentação.
- Validação de breaking changes entre versões.
Convenções
- Prefixo `API*`
- Estruturas gerais da API (objetos retornados, modelos internos).
- Prefixo `REST*`
- Schemas usados em endpoints REST.
- Body → corpo da requisição
- QueryParams → parâmetros de query
- Data → dados retornados
- Prefixo `Webhook*`
- Payloads de eventos de webhook
Você pode ver a documentação completa da API por [aqui](https://docs.abacatepay.com/pages/typebox).
Feito com 🥑 pela equipe AbacatePay
Open source, de verdade.