Comportamento padrão
Quando seu handler retorna um objeto simples, a plataforma responde com 200 OK e Content-Type: application/json:
handler: async (input) => {
return { nome: "Maria", saldo: 150.00 };
}
// → 200 OK
Response builder
Importe response de @jelou/functions:
import { define, response, z } from "@jelou/functions";
Status code personalizado
export default define({
description: "Cria um usuário",
input: z.object({ nome: z.string(), email: z.string().email() }),
output: z.object({ id: z.string(), nome: z.string() }),
handler: async (input) => {
const usuario = await criarUsuario(input);
return response
.status(201)
.json({ id: usuario.id, nome: usuario.nome });
},
});
handler: async (input) => {
return response
.header("X-Request-Id", crypto.randomUUID())
.header("Cache-Control", "max-age=300")
.json({ dados: [] });
}
handler: async (input) => {
return response
.headers({
"X-Request-Id": crypto.randomUUID(),
"Cache-Control": "no-store",
})
.json({ ok: true });
}
Encadeamento completo
O builder é imutável — cada método retorna uma nova instância:
handler: async (input) => {
return response
.status(201)
.header("Location", `/usuarios/${input.id}`)
.json({ id: input.id, nome: input.nome });
}
// → 201 Created
// → Location: /usuarios/abc123
API
| Método | Descrição |
|---|
response.status(code) | Define o status HTTP (padrão: 200) |
response.header(name, value) | Adiciona um header |
response.headers(init) | Adiciona múltiplos headers |
response.json(body) | Finaliza e retorna JsonResponse |
.json() é o método terminal — depois de chamá-lo você obtém um JsonResponse, não um builder.
Exemplos práticos
201 Created
404 Not Found
handler: async (input) => {
const ticket = await criarTicket(input);
return response
.status(201)
.header("Location", `/tickets/${ticket.id}`)
.json({ ticketId: ticket.id, estado: "aberto" });
}
handler: async (input) => {
const cliente = await buscarCliente(input.telefone);
if (!cliente) {
return response
.status(404)
.json({ error: "not_found", message: "Cliente não encontrado" });
}
return { nome: cliente.nome, saldo: cliente.saldo };
}
Validação de output
Quando usa response.json(body) com schema output, a validação se aplica ao body. A validação nunca bloqueia a resposta.
Comportamento em MCP
Quando invocado via MCP (agentes IA no Brain Studio):
- O body é emitido como
structuredContent
- Status code e headers são ignorados
- O body também é enviado como texto JSON para compatibilidade
Não precisa condicionar seu código para HTTP vs MCP — use o response builder normalmente.
Limitações
| Limitação | Detalhe |
|---|
| Apenas JSON | .json() é o único método terminal |
| Sem Web Response nativo | Retornar new Response() de define()/app() não funciona |
| Content-Type fixo | Sempre application/json |
| OpenAPI | Spec em /openapi.json documenta apenas resposta 200 por enquanto |
