Respostas HTTP - Jelou AI Docs

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

Quando você precisa de um status code diferente ou headers personalizados, use o response builder.

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 });
  },
});

Headers personalizados

handler: async (input) => {
  return response
    .header("X-Request-Id", crypto.randomUUID())
    .header("Cache-Control", "max-age=300")
    .json({ dados: [] });
}

Múltiplos headers de uma vez

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 com um body JSON
`response.noContent()`	Finaliza com `204 No Content` sem body

.json() e .noContent() são os métodos terminais — depois de chamá-los você obtém uma resposta final, não um builder.

Exemplos práticos

201 Created
404 Not Found
Cache headers
204 No Content

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 };
}

handler: async (input) => {
  const produtos = await listarProdutos(input.categoria);
  return response
    .header("Cache-Control", "public, max-age=300")
    .json({ produtos, total: produtos.length });
}

handler: async (input, ctx) => {
  await deletarRecurso(input.id);
  return response.noContent();
}
// → 204 No Content (sem body)

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
JSON ou vazio	Apenas `.json()` e `.noContent()` — sem `.text()`, `.html()`
Sem Web Response nativo	Retornar `new Response()` de `define()`/`app()` não funciona
Content-Type fixo	Sempre `application/json` em `.json()`
OpenAPI	Spec em `/openapi.json` documenta apenas resposta `200` por enquanto

​Comportamento padrão

​Response builder

​Status code personalizado

​Headers personalizados

​Múltiplos headers de uma vez

​Encadeamento completo

​API

​Exemplos práticos

​Validação de output

​Comportamento em MCP

​Limitações

Comportamento padrão

Response builder

Status code personalizado

Headers personalizados

Múltiplos headers de uma vez

Encadeamento completo

API

Exemplos práticos

Validação de output

Comportamento em MCP

Limitações