> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pagamentos.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Criar um adaptador

> Como integrar o **pagamentos.dev** com frameworks web

## Visão geral

Adaptadores permitem que o handler de webhooks do **pagamentos.dev** funcione
com diferentes frameworks web (Hono, Express, Fastify, etc.). Cada adaptador
converte o handler genérico `(request: Request) => Promise<Response>` para o
formato esperado pelo framework.

## Quando criar um adaptador?

Crie um adaptador quando:

* O framework não tiver um adaptador oficial ainda
* Você quiser publicar um adaptador para a comunidade
* Precisar de comportamento customizado (ex: validação extra, logging)

## Estrutura

```
pagamentos-adapter-nome/
├── package.json
├── src/
│   └── index.ts
└── README.md
```

## Como funciona

O handler de webhooks do **pagamentos.dev** tem uma assinatura universal:

```ts theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
type WebhookHandler = (request: Request) => Promise<Response>
```

Ele recebe um objeto `Request` padrão do JavaScript (Web API) e retorna uma
`Response`. Um adaptador simplesmente conecta essa assinatura ao sistema de
request/response do framework alvo.

## Exemplo: adaptador para Hono

O adaptador oficial do Hono é um dos mais simples possíveis:

```ts theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
import type { WebhookHandler } from 'pagamentos'

export function toHono(handler: WebhookHandler) {
  return (c: { req: { raw: Request } }) => {
    return handler(c.req.raw)
  }
}
```

Uso:

```ts theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
import { Hono } from 'hono'
import { toHono } from 'pagamentos/hono'
import { pg } from './pagamentos'

const app = new Hono()
app.post('/webhook', toHono(pg.webhooks.handler))
export default app
```

## Exemplo: adaptador para Express

O adaptador do Express precisa extrair o `body` e as headers da requisição
para montar um objeto `Request` compatível:

```ts theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
import type { WebhookHandler } from 'pagamentos'
import type { Request, Response } from 'express'

export function toExpress(handler: WebhookHandler) {
  return async (req: Request, res: Response) => {
    // Constrói um Request padrão a partir do req do Express
    const request = new Request(
      `${req.protocol}://${req.get('host')}${req.originalUrl}`,
      {
        method: req.method,
        headers: Object.entries(req.headers).reduce(
          (acc, [key, value]) => {
            if (value) acc[key] = Array.isArray(value) ? value.join(', ') : value
            return acc
          },
          {} as Record<string, string>
        ),
        body: req.method !== 'GET' ? JSON.stringify(req.body) : undefined
      }
    )

    const response = await handler(request)

    // Traduz a Response de volta para o formato do Express
    res.status(response.status)
    response.headers.forEach((value, key) => res.setHeader(key, value))
    const text = await response.text()
    res.send(text)
  }
}
```

Uso:

```ts theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
import express from 'express'
import { toExpress } from 'pagamentos/express'
import { pg } from './pagamentos'

const app = express()
app.post('/webhook', toExpress(pg.webhooks.handler))
app.listen(3000)
```

## Publicando um adaptador

1. Crie um pacote npm com o nome `pagamentos-adapter-nome`
2. Declare `pagamentos` como `peerDependency`

```json theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
{
  "name": "pagamentos-adapter-nome-do-framework",
  "peerDependencies": {
    "pagamentos": "^0.x"
  }
}
```

3. Exporte uma única função com nome descritivo (ex: `toExpress`, `toFastify`)
4. Documente o uso com exemplos

## Adaptadores existentes

Consulte os adaptadores oficiais como referência:

| Framework                                                                                                    | Import                      |
| ------------------------------------------------------------------------------------------------------------ | --------------------------- |
| [Hono](https://github.com/pagamentosdev/pagamentos/blob/main/src/hono/hono.ts)                               | `pagamentos/hono`           |
| [Express](https://github.com/pagamentosdev/pagamentos/blob/main/src/express/express.ts)                      | `pagamentos/express`        |
| [Fastify](https://github.com/pagamentosdev/pagamentos/blob/main/src/fastify/fastify.ts)                      | `pagamentos/fastify`        |
| [Next.js](https://github.com/pagamentosdev/pagamentos/blob/main/src/nextjs/nextjs.ts)                        | `pagamentos/nextjs`         |
| [Astro](https://github.com/pagamentosdev/pagamentos/blob/main/src/astro/astro.ts)                            | `pagamentos/astro`          |
| [Elysia](https://github.com/pagamentosdev/pagamentos/blob/main/src/elysia/elysia.ts)                         | `pagamentos/elysia`         |
| [Convex](https://github.com/pagamentosdev/pagamentos/blob/main/src/convex/convex.ts)                         | `pagamentos/convex`         |
| [TanStack Start](https://github.com/pagamentosdev/pagamentos/blob/main/src/tanstack-start/tanstack-start.ts) | `pagamentos/tanstack-start` |