# @monitor-sefaz/contracts

> Schemas Zod e DTOs compartilhados do Monitor SEFAZ: status, histórico (compacto), resumo, incidentes e eventos de notificação.

Latest version **0.1.1** (published 2026-09-23) · MIT license · 0 weekly downloads

## Install

```sh
npm install @monitor-sefaz/contracts
pnpm add @monitor-sefaz/contracts
yarn add @monitor-sefaz/contracts
bun add @monitor-sefaz/contracts
```

## Health

**Score 75/100 (B)** — status: active.

Positive: has types; esm support; no vulnerabilities; has provenance; recently updated; high maintenance score; high quality score.

Warnings: low downloads; pre 1.0.

## Facts

| | |
|---|---|
| Version | 0.1.1 |
| Published | 2026-09-23 |
| First published | 2026-09-10 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Node | >=20 |
| Dependencies | 2 |
| Unpacked size | 78.8 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| GitHub stars | 10 |
| Author | Felipe Sauer |
| Maintainers | felipesauer |
| Keywords | sefaz, nfe, nfce, cte, mdfe, dce, nota-fiscal-eletronica, brasil, typescript, zod, schema, dto, contracts |

## Links

- npm: https://www.npmjs.com/package/@monitor-sefaz/contracts
- Repository: https://github.com/felipesauer/monitor-sefaz
- Homepage: https://github.com/felipesauer/monitor-sefaz/tree/main/packages/contracts#readme
- Issues: https://github.com/felipesauer/monitor-sefaz/issues
- npm.io page: https://npm.io/package/@monitor-sefaz/contracts

## Dependencies (2)

- [zod](https://npm.io/package/zod.md) ^3.25.76
- [@monitor-sefaz/catalog](https://npm.io/package/@monitor-sefaz/catalog.md) 0.2.0

## Alternatives

- [@regle/core](https://npm.io/package/@regle/core.md) — 47.0K weekly downloads
- [typeof-arguments](https://npm.io/package/typeof-arguments.md) — 12.5K weekly downloads
- [@lokalise/projects-engine-contracts](https://npm.io/package/@lokalise/projects-engine-contracts.md) — 978 weekly downloads
- [@osjwnpm/nam-laboriosam-quibusdam](https://npm.io/package/@osjwnpm/nam-laboriosam-quibusdam.md) — 70 weekly downloads
- [@oridune/validator](https://npm.io/package/@oridune/validator.md) — 16 weekly downloads

## Recent versions

- 0.1.1 (latest) — 2026-09-23
- 0.1.0 — 2026-09-10

## README

# @monitor-sefaz/contracts

Schemas [Zod](https://zod.dev) e DTOs compartilhados do
[Monitor SEFAZ](https://github.com/felipesauer/monitor-sefaz): status de
serviço, resumo agregado, histórico, incidentes e eventos de notificação.

É o contrato entre o coletor, a API, o Cloudflare Worker e o dashboard — quem
consome a API pública do monitor pode validar as respostas com os mesmos
schemas que o servidor usa para produzi-las.

## Instalação

    npm i @monitor-sefaz/contracts

## Uso

```ts
import { statusSnapshotSchema, summarySchema, isUp } from '@monitor-sefaz/contracts';

const snapshot = statusSnapshotSchema.parse(await res.json());

// "No ar" inclui contingência: a SEFAZ responde e ainda dá para emitir.
const noAr = snapshot.services.filter((s) => isUp(s.state));
```

Estados possíveis: `OPERATIONAL`, `CONTINGENCY`, `SLOWDOWN`, `DOWN`, `ERROR`.

### Validação resiliente

Para um painel, uma resposta parcialmente inválida é melhor que uma tela de
erro. O schema resiliente descarta os itens ruins e mantém o resto:

```ts
import { resilientStatusSnapshotSchema } from '@monitor-sefaz/contracts';

const snapshot = resilientStatusSnapshotSchema.parse(data); // serviços inválidos são omitidos
```

### Histórico compacto

O histórico acumulado pelo Worker não é um ponto por checagem: o estado é
guardado como _run-length_ (segmento novo só quando muda) e a latência é
agregada por hora. Isso mantém 72h de 135 serviços em ~230 KB em vez de
megabytes, sem perder o instante exato de cada queda.

```ts
import {
  compactHistorySchema,
  expandCompactHistory,
  LATENCY_BUCKET_MS,
} from '@monitor-sefaz/contracts';

const history = compactHistorySchema.parse(await res.json());

// Expande de volta para pontos, na resolução que você precisa.
const detalhe = expandCompactHistory(history, 'NFe:SP');
const grosso = expandCompactHistory(history, 'NFe:SP', { stepMs: LATENCY_BUCKET_MS });
```

Como a grade de saída é regular, "operacionais / total de pontos" já é a fração
de **tempo** no ar — o uptime sai correto por construção.

## Licença

[MIT](LICENSE) © Felipe Sauer

---
_Source: https://npm.io/package/@monitor-sefaz/contracts · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._