@horizon-js/api-nextjs

Core do backend Horizon — query engine, arquitetura de módulos, sync API, protocolos e padrões.

O que contém

1. Query Engine (motor de queries avançadas)

Motor genérico para APIs que combina numa única request:

• Search — full-text search (FTS via tsvector do PostgreSQL)
• List — paginação offset + cursor, sort, select
• Map — busca geoespacial (PostGIS — bbox, circle, polygon)
• Facets — filtros dinâmicos com contagem (terms, range, histogram)
• Meta — totais e estatísticas

Funciona com qualquer entidade (Property, Broker, Product, etc.). Zero hardcoded.

2. Documentação

Cobre o backend Horizon de ponta a ponta. Uma IA que ler essas docs entende a plataforma inteira.

| Doc | Cobre | |---|---| | ARQUITETURA.md | Visão geral: módulos, rotas, controllers, services, mappers, pipeline de dados | | QUERY_ENGINE_API.md | Especificação completa do query engine | | SYNC_API_PATTERN.md | Padrão de sync (GET/PUT/DELETE) com validação Zod | | BANCO_DADOS.md | PostgreSQL + PostGIS + Prisma, relações, triggers, FTS | | MODULE_CREATION_PATTERN.md | Como criar módulos novos (entity-schema, controllers, services) | | PROTOCOLOS.md | Passo-a-passo de mudanças (adicionar campo, trocar CRM, deploy, debug) |

Docs externas referenciadas:

• SSOT Spec → @horizon-js/domain-schema-core/docs/DOMAIN_DATA_SCHEMA_SPEC.md
• Fluxo ponta a ponta → @horizon-js/domain-schema-core/docs/DOMINIO_ENTIDADES.md (é transversal, não só backend)

Instalação

pnpm add @horizon-js/api-nextjs

Requisitos:

• Prisma (>=5.0.0) — passado como instância pelo consumidor
• PostgreSQL com PostGIS — para busca geoespacial e FTS com tsvector

Uso rápido

import { advancedSearch } from "@horizon-js/api-nextjs"
import { Prisma, PrismaClient } from "@prisma/client"
import { propertyEntitySchema } from "./entity-schema"

const prisma = new PrismaClient()

const PROPERTY_CONFIG = {
  modelName: "Property",
  searchColumn: "fts_vector",
  locationColumn: "geom",
  prismaModule: Prisma,  // necessário pra introspecção DMMF
}

// Request universal
const result = await advancedSearch(
  prisma,
  {
    filters: { tipo: "Apartamento", operacao: ["venda"] },
    fts: { value: "jardins 3 quartos" },
    list: { page: 1, limit: 20, sort: { valor_venda: "desc" } },
    facets: {
      fields: [
        { type: "terms", field: "tipo" },
        { type: "range", field: "valor_venda", bucketCount: 4 },
      ],
    },
    meta: { total: true },
  },
  PROPERTY_CONFIG,
  propertyEntitySchema
)

// result.list    → { data: [...], meta: { page, limit, total, totalPages } }
// result.map     → { data: [...], meta: { totalWithCoordinates } }
// result.facets  → { data: { tipo: [...], valor_venda: [...] } }
// result.meta    → { total: 573 }

Exports principais

import {
  // Query Engine — motor principal
  advancedSearch,
  advancedSearchService,

  // Executores individuais
  executeList,
  executeMap,
  executeTotal,
  executeFacets,

  // Helpers
  removeNullFields,
  setupDmmf,

  // Tipos
  type SearchRequest,
  type SearchResponse,
  type ListResult,
  type MapResult,
  type MetaResult,
  type FacetsResult,
  type AdvancedSearchConfig,
  type FacetValue,
  type FilterValue,
  type LocationFilter,
} from "@horizon-js/api-nextjs"

Roadmap

Este pacote hoje contém o query engine e documentação. A evolução pode seguir dois caminhos:

1. Evolução incremental — a cada versão da Horizon, mais lógica repetitiva dos módulos (controllers factories, sync pipeline, validação) migra pra dentro deste pacote, reduzindo boilerplate nos projetos
2. Migração pra CMS — descontinuação futura em favor de um CMS headless especializado (ex: Directus) que forneceria sync, CRUD, auth e admin UI out-of-the-box, mantendo apenas o query engine como lib complementar

A decisão será tomada conforme a plataforma evolui. Ver análise completa em @horizon-js/ai-dev-guide ou nas docs de reorganização do Horizon 2.3.