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.
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:
type WebhookHandler = (request: Request) => Promise<Response>
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:
import type { WebhookHandler } from 'pagamentos'
export function toHono(handler: WebhookHandler) {
return (c: { req: { raw: Request } }) => {
return handler(c.req.raw)
}
}
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:
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)
}
}
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
- Crie um pacote npm com o nome
pagamentos-adapter-nome
- Declare
pagamentos como peerDependency
{
"name": "pagamentos-adapter-nome-do-framework",
"peerDependencies": {
"pagamentos": "^0.x"
}
}
- Exporte uma única função com nome descritivo (ex:
toExpress, toFastify)
- Documente o uso com exemplos
Adaptadores existentes
Consulte os adaptadores oficiais como referência:
| Framework | Import |
|---|
| Hono | pagamentos/hono |
| Express | pagamentos/express |
| Fastify | pagamentos/fastify |
| Next.js | pagamentos/nextjs |
| Astro | pagamentos/astro |
| Elysia | pagamentos/elysia |
| Convex | pagamentos/convex |
| TanStack Start | pagamentos/tanstack-start |
