# @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`](#resolução-de-estabelecimentos).

## Requisitos

- Node.js 20+
- [`pnpm`](https://pnpm.io) 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:

```bash
pnpm add @natrave/facility-service-types
```

## Uso

O `src/index.ts` reexporta tudo:

```ts
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.

```ts
// 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

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

Versionamento via [changesets](https://github.com/changesets/changesets): adicione um
`.changeset/*.md` na PR; ao mergear na `main`, o workflow `release.yml` roda `changeset version` e
publica no npm.