@natrave/facility-service-types

Tipos e contratos compartilhados do facility-service da plataforma NaTrave. Centraliza as interfaces de domínio (estabelecimentos e endereços) e os contratos de request/response usados pelo serviço e por seus consumidores (ex.: tournaments-service), para que servidor e clientes falem exatamente o mesmo shape.

É um pacote types-first: quase tudo é interface (apagada na compilação). A única exportação de runtime é o enum FacilityResolution.

Requisitos

• Node.js 20+
• pnpm como gerenciador de pacotes

Instalação

Publicado no npm sob o escopo @natrave (always-auth habilitado). Configure um token antes de instalar — crie um .npmrc no projeto consumidor:

@natrave:registry=https://registry.npmjs.org
always-auth=true
//registry.npmjs.org/:_authToken=${NPM_TOKEN}

Em seguida:

pnpm add @natrave/facility-service-types

Uso

O src/index.ts reexporta tudo:

import {
  IFacility,
  ICreateFacilityDto,
  IResolveFacilitiesDto,
  IResolveFacilitiesResponse,
  FacilityResolution,
} from '@natrave/facility-service-types';

Conteúdo

Entidades (visão de tipo)

• IFacility — estabelecimento. Inclui googlePlaceId: string | null, a identidade canônica do lugar (Google Place ID). null em registros legados/manuais ainda não resolvidos. O endereço é dado de atributo, não identidade.
• IAddress — endereço completo (logradouro, número, bairro, cidade, UF, CEP, país, lat/long).

Criação direta

• ICreateAddressDto, ICreateFacilityDto, ICreateFacilitiesDto e as respostas ICreateFacilityResponse / ICreateFacilitiesResponse — usados pelo fluxo de create-or-fetch em lote (POST /facilities/batch).

Resolução de estabelecimentos

Contrato preferido para vincular um lugar a um serviço. Resolução é responsabilidade única do facility-service (Place ID → geocoding → chave natural); o chamador correlaciona por ref e nunca re-casa por endereço.

// request → POST /facilities/resolve
const body: IResolveFacilitiesDto = {
  items: [
    {
      ref: 'tmp-1', // id opaco do chamador, devolvido intacto
      name: 'Hammer Futebol Society',
      placeId: 'ChIJ...', // identidade canônica (quando vem do Maps)
      // address?: ICreateAddressDto  → hint p/ geocoding manual / fallback
    },
  ],
};

// response
const res: IResolveFacilitiesResponse = {
  items: [
    {
      ref: 'tmp-1', // mesmo ref → correlação
      facilityId: 482,
      googlePlaceId: 'ChIJ...',
      resolution: FacilityResolution.MATCHED_BY_PLACE_ID,
      facility: {
        /* ICreateFacilityResponse: snapshot canônico */
      },
    },
  ],
};

FacilityResolution:

| valor | significado | | ------------------------ | ------------------------------------------------- | | matched_by_place_id | casou por Google Place ID | | matched_by_natural_key | sem Place ID; casou por name + CEP normalizados | | created | não existia; criado agora |

Build & release

pnpm build          # tsc (declarations) + esbuild (ESM, extensões .js)
pnpm check:types    # tsc --noEmit
pnpm lint

Versionamento via changesets: adicione um .changeset/*.md na PR; ao mergear na main, o workflow release.yml roda changeset version e publica no npm.