@neetru/sdk 1.2.0 → 2.1.1

package/CHANGELOG.md

@@ -1,244 +1,336 @@
-# Changelog
-
-All notable changes to `@neetru/sdk` will be documented in this file.
-
-The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
-and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
-
-## [Unreleased]
-
-### Planned (post-1.2)
-- size-limit budget no CI (<12KB gz core com db namespace).
-- CDN distribution (`cdn.neetru.com/sdk/v1/`).
-- Endpoint batch `/api/v1/sdk/telemetry/batch` (substitui drenagem N×1 do `track()` por 1 request).
-
-## [1.2.0] - 2026-05-19 — **Webhooks + Notifications + DX (cache, retry, batch)**
-
-Release de qualidade fechando 3 CRITICAL + 6 IMPORTANT do code review interno + 4 melhorias de DX. Adiciona `webhooks` + `notifications` no `NeetruClient`.
-
-### Added
-- **`client.webhooks`** — `register`/`list`/`unregister`/`test` pra endpoints HTTP do produto receberem eventos do Core (subscription.activated, usage.quota_exceeded, etc).
-- **`verifyWebhookSignature(payload, signature, secret)`** — util pura (HMAC SHA-256 constant-time compare via `node:crypto`) pra consumidor validar payloads recebidos.
-- **`client.notifications`** — `send`/`list`/`markRead`/`dismiss` pra produto integrar com a bandeja in-app do Neetru.
-- **`client.telemetry.track(input)`** + `client.telemetry.flush()` — fire-and-forget batch (500ms debounce). Ideal pra alta frequência (page-views, cliques). `event()` segue como single-shot com `eventId` ack.
-- **`client.entitlements.check(..., { cacheBust })`** — cache LRU em memória (60s TTL, 100 entries). Corta 90%+ requests em renders repetidos do `<EntitlementGate>`. `cacheBust: true` força ida ao servidor.
-- **httpRequest retry/backoff** — 2 retries default em `rate_limited` (429), `server_error` (5xx), `network_error`. Honra `Retry-After` header. Caller opt-out com `opts.retries: 0`.
-- **Subpaths novos**: `@neetru/sdk/webhooks`, `@neetru/sdk/notifications`.
-
-### Changed
-- **`client.catalog.list()` / `get()`** agora consomem `/api/sdk/v1/catalog` (público, sem Bearer) em vez de `/api/v1/cli/catalog` (staff). Consumidor não precisa mais de chave staff só pra ler catálogo. `includeDrafts` é ignorado — rascunhos só via CLI.
-- **`auth.signOut()`** revoga token em `auth.neetru.com/api/v1/oauth/revoke` (canônico), não mais `api.neetru.com/oauth/revoke` (404 em prod).
-- **`<EntitlementGate>`** passa `tenantId` (do `client.config.tenantId`) pra `usage.check`. Sem tenantId, cai pra `entitlements.check` em vez de chamar `usage.check` e travar em `validation_failed` silencioso.
-- **`engines.node`** subiu pra `>=20` (alinha com `target: node20` do tsup; Node 18 EOL).
-
-### Fixed
-- **CRITICAL** — `webhooks` e `notifications` lançavam `'invalid_input'`, código ausente da union `NeetruErrorCode`. Todas as 17 ocorrências viraram `'validation_failed'`.
-- **CRITICAL** — `telemetry.log()` chamava `/sdk/v1/telemetry/log` (404). Corrigido pra `/api/sdk/v1/telemetry/log`.
-- **CRITICAL** — `db` namespace tinha o mesmo bug em 6 paths (`/sdk/v1/datastore/...`). Corrigido em massa pra `/api/sdk/v1/datastore/...`.
-- **CRITICAL** — 8 `httpRequest` calls em `webhooks` e `notifications` não passavam `requireAuth: true` — todos hits em prod retornavam 401. Corrigido.
-- **`MockSupport.mockTicketSeq`** virou instance field (era module-level, poluía tests entre suites).
-- **`db.list()`** removeu variável `query` dead code (refactor incompleto de pre-1.1).
-
-### Internal
-- 51 testes novos (webhooks: 22, notifications: 20, react: 9). Total: 215 testes (16 files), 100% passing. tsc clean.
-- `api-surface-stability.test.ts` agora lock `webhooks` + `notifications` no `NeetruClient`.
-
-## [1.1.0] - 2026-05-08 — **Checkout namespace + React helpers**
-
-Adiciona o namespace `client.checkout` (start/get/cancel intent) com auto-redirect
-em browser. Suporte ao fluxo Sprint 13 onde produtos SaaS delegam checkout pro
-portal `minhaconta.neetru.com` via `POST /api/v1/checkout/intents`.
-
-### Added
-- **`client.checkout.start({productId, planId, callbackUrl, tenantType?, tenantId?})`** — cria
-  `checkout_intents/{intentId}` no Core e (em browser) redireciona automaticamente
-  pra `minhaconta.neetru.com/portal/checkout/{intentId}`. Em Node/SSR retorna
-  `{intentId, redirectUrl}` sem efeito colateral.
-- **`client.checkout.get(intentId)`** — lê estado atual do intent.
-- **`client.checkout.cancel(intentId)`** — marca intent como `cancelled`.
-- **Subpath `@neetru/sdk/react`** — componente `<CheckoutLink>` (wrapper de `<a>`
-  que dispara `start()` no click) + `<EntitlementGate mode="block|readonly">`
-  + hook `useEntitlementContext()` pra desabilitar escritas quando free tier
-  estoura limite (decisão CEO §5 — read-only sempre, não hard-block).
-- **`MockCheckout`** — implementação dev (`NEETRU_ENV=dev`) sem network. Retorna
-  URL fake `https://localhost:9003/portal/checkout/{intentId}` pra dev externo
-  testar UI sem provisionar conta Neetru.
-- **Peer dep `react ^18 || ^19`** marcado opcional (só carregado se import `/react`).
-
-### Changed
-- `VERSION` const bump `1.0.0 → 1.1.0`.
-- `NeetruClient.checkout` adicionado — backward-compatible (caller que não usa
-  o namespace não é afetado).
-
-### Notes
-- API stability test (`api-surface-stability.test.ts`) atualizado pra incluir
-  `checkout` no inventário canônico.
-
-## [1.0.0] - 2026-05-06 — **GA (General Availability)**
-
-Marco de estabilidade. A partir desta versão, **a superfície pública do SDK
-está congelada** — breaking changes só em majors (semver estrito).
-
-### Added
-- **API stability lock** — todos os contratos (`createNeetruClient`,
-  `NeetruClient`, namespaces `auth`/`catalog`/`entitlements`/`telemetry`/
-  `usage`/`support`/`db`, `NeetruError`) ficam estáveis em v1.x. Coberto
-  por `api-surface-stability.test.ts` que falha o build se algum método
-  muda forma.
-- **JSDoc completo** em toda função/método público — base pra `npm run docs:gen`
-  (typedoc → `sdk/docs-html/`).
-- **`docs:gen` script** + `scripts/typedoc.config.json` — gera HTML
-  navigable das APIs.
-- **`engines.node`** relaxado de `>=20` → `>=18` (suporta runtimes Node 18 LTS
-  ainda em uso por consumers).
-
-### Changed
-- `VERSION` bump `0.3.0` → `1.0.0`.
-- README atualizado com seção de migração v0.3 → v1.0 (no breaking changes —
-  upgrade transparente).
-
-### Migration v0.3 → v1.0
-- **Sem breaking changes.** Upgrade direto via `npm install @neetru/sdk@1.0.0`.
-- `initNeetru` continua deprecated mas funcional. **Será removido em v2.0.0.**
-- `NeetruConfig` continua deprecated. Use `NeetruClientConfig`.
-
-### Stability promise (v1.x)
-A partir de v1.0:
-- Métodos novos podem ser adicionados a namespaces existentes (minor bump).
-- Métodos podem ser marcados `@deprecated` em qualquer minor — só removidos
-  em major.
-- Tipos nunca ganham campos required em minor (só optional ou via union).
-- `NeetruErrorCode` é union fechado em v1.0 — qualquer novo código bumpa minor.
-
-### Notes
-- Pacote ainda **privado** (`private: true`). Publicação no npm é
-  responsabilidade do owner — gate no CHANGELOG continua trancado até decisão.
-
-## [0.3.0] - 2026-05-06
-
-### Added
-- Namespace `client.db` (v0.3) — wrapper minimalista pra coleções tenant-scoped:
-  - `client.db.collection(name).list({ limit? })`
-  - `client.db.collection(name).get(id)` (retorna null em not_found)
-  - `client.db.collection(name).set(id, data)` upsert
-  - `client.db.collection(name).remove(id)` delete
-  - Endpoints: `/sdk/v1/datastore/{collection}/{id?}` (placeholder REST — Sprint 9
-    finaliza; SDK já expõe interface estável).
-  - `MockDb` (in-memory) ativo em `NEETRU_ENV=dev`.
-- Namespace `client.usage` ganhou `report()` e `check()`:
-  - `usage.report(resource, qty?)` → `POST /sdk/v1/usage/record` canônico
-    (Sprint 7) — incrementa atomicamente `usage_counters/{tid}_{pid}_{r}_{yyyymm}`.
-  - `usage.check(resource)` → `GET /sdk/v1/entitlements?productId&tenantId&feature` —
-    retorna `{allowed, reason, remaining, limit, planId, planFeatures}`.
-- `NeetruClientConfig.productId` / `.tenantId` — defaults pra `usage.report` /
-  `usage.check` / `db.collection` quando não passado em options.
-- Mock helpers: `MockDb`, `MockUsage.report()`, `MockUsage.check()`.
-
-### Changed
-- `VERSION` bump `0.2.0` → `0.3.0`.
-- `NeetruClient` agora expõe `.db` além dos antigos.
-- `ResolvedConfig` ganhou `productId` + `tenantId` opcionais.
-
-### Backend (acompanha esta release)
-- Novos endpoints (Sprint 7):
-  - `POST /sdk/v1/usage/record` — atomic increment + 80%/100% notifications + audit.
-  - `GET  /sdk/v1/entitlements` — lookup canônico subscription→plan→counter.
-  - `POST /sdk/v1/telemetry/log` — batch logger pra `logs/{productId}/{yyyymmdd}/`.
-
-## [0.2.0] - 2026-05-06
-
-### Added
-- Namespace `client.auth` (v0.2 — OIDC + dev mocks):
-  - `signIn(options?)` — redireciona pra auth.neetru.com authorize endpoint
-    (browser) ou retorna mock user em dev (`NEETRU_ENV=dev`).
-  - `signOut()` — limpa `localStorage.neetru_id_token` + revoga refresh
-    server-side (best-effort).
-  - `getUser()` — decodifica id_token cached e retorna `NeetruUser` ou null.
-  - `onAuthStateChanged(listener)` — sub a mudanças, dispatcha sync no subscribe.
-- Namespace `client.usage` (v0.2 — meter):
-  - `track(event, props?)` → `POST /sdk/v1/usage/record` com Bearer.
-  - `getQuota(metric)` → `GET /sdk/v1/usage/quota?metric=` returns
-    `{ metric, used, limit, plan, resetsAt? }`.
-- Namespace `client.support` (v0.2 — tickets):
-  - `createTicket({subject, message, severity?, productSlug?})` →
-    `POST /api/v1/products/{slug}/tickets` (default `_default`).
-  - `listMyTickets()` → `GET ...` retorna array (aceita envelope `{tickets:[]}`).
-- `mocks` module (`@neetru/sdk/mocks`):
-  - `MockAuth`, `MockUsage`, `MockSupport`, `MockEntitlements` — overridáveis
-    via `createNeetruClient({ mocks: { auth: MockAuth(...), ... } })`.
-  - `DEV_FIXTURE_USER` constante exportada.
-- `NEETRU_ENV` resolution chain: config arg > `process.env.NEETRU_ENV` >
-  `globalThis.NEETRU_ENV` > default `prod`. `dev` ativa mocks automáticos.
-- Subpath exports adicionais: `@neetru/sdk/{auth,usage,support,mocks}`.
-- Tipos novos: `NeetruUser`, `AuthNamespace`, `UsageNamespace`,
-  `SupportNamespace`, `SignInOptions`, `SupportTicket`, `UsageQuota`,
-  `NeetruEnv`, `CreateTicketInput`.
-
-### Changed
-- `VERSION` bump `0.1.0` → `0.2.0`.
-- `NeetruClientConfig` ganhou campos `env` + `mocks`.
-- `ResolvedConfig` ganhou `env` resolved.
-- `NeetruClient` agora expõe `.auth`, `.usage`, `.support` além dos antigos.
-
-### Backend (acompanha esta release — endpoints documentados em `docs/SDK_OPENAPI.md`)
-- `POST /sdk/v1/usage/record` — record event meterado.
-- `GET  /sdk/v1/usage/quota?metric=` — ler quota atual.
-- `POST /api/v1/products/{slug}/tickets` — criar ticket.
-- `GET  /api/v1/products/{slug}/tickets` — listar meus tickets.
-- (auth) `auth.neetru.com/oauth/authorize` — já live (Sprint 1 OIDC).
-- (auth) `auth.neetru.com/oauth/revoke` — revoga refresh token.
-
-### Notes
-- Pacote ainda **privado** (`private: true`) — não publicado no npm.
-- Carry-over: integração OIDC live aguarda owner habilitar redirect_uri pro
-  domain do consumer (configurar em `oidc_clients/{client_id}.redirect_uris`).
-- TODO: `support.listMyTickets` precisa parametrizar productSlug (fixed
-  `_default` na v0.2).
-
-## [0.1.0] - 2026-05-05
-
-### Added
-- `createNeetruClient(config)` factory — entry point principal.
-  - Resolve `apiKey` (arg explícito > `NEETRU_API_KEY` env em Node).
-  - Resolve `baseUrl` (default `https://api.neetru.com`).
-  - Resolve `fetch` (arg > `globalThis.fetch`).
-- Namespace `client.catalog`:
-  - `list(opts?)` → `GET /api/v1/cli/catalog`. Aceita `includeDrafts`.
-  - `get(slug)` → `GET /api/v1/cli/catalog/{slug}`.
-- Namespace `client.entitlements`:
-  - `check(slug, feature)` → boolean.
-  - `checkDetailed(slug, feature)` → `EntitlementCheck` com `reason`.
-  - Backed por `GET /api/v1/sdk/entitlements/check`.
-- Namespace `client.telemetry`:
-  - `event({ name, properties?, timestamp? })` → `POST /api/v1/sdk/telemetry/event`.
-- Subpath exports map: `@neetru/sdk/{catalog,entitlements,telemetry,errors}`.
-- HTTP transport com mapeamento status → `NeetruError.code` estável.
-- Tipos exportados: `NeetruClient`, `NeetruClientConfig`, `Product`, `ProductPlan`,
-  `EntitlementCheck`, `TelemetryEventInput`, `TelemetryEventAck`, `NeetruErrorCode`.
-- Compat alias `initNeetru` (deprecated, será removido em v1.0).
-
-### Changed
-- `VERSION` bump `0.0.1` → `0.1.0`.
-- tsup config multi-entry pra subpath imports.
-
-### Backend (acompanha esta release)
-- `GET /api/v1/cli/catalog/{slug}` — produto único.
-- `GET /api/v1/sdk/entitlements/check?slug=&feature=` — verificação por user.
-- `POST /api/v1/sdk/telemetry/event` — persiste em `usage_events`.
-
-### Notes
-- Pacote ainda **privado** (`private: true`). Publicação no npm é
-  responsabilidade do owner em Sprint 6.
-- API instável; pré-1.0 segue regra "breaking allowed em qualquer minor".
-
-## [0.0.1] - 2026-05-04
-
-### Added
-- Scaffold inicial do pacote `@neetru/sdk` (private, não publicado no npm ainda).
-- `initNeetru(config)` com validação de `apiUrl` e injeção opcional de `fetch`.
-- `NeetruError` com `code`, `status` e `requestId` opcionais.
-- `NeetruConfig` e `NeetruClient` types públicos.
-- `VERSION` const exportada.
-- Build pipeline com tsup (dual ESM + CJS + `.d.ts`).
-- README + CHANGELOG.
-- `tsconfig.json` strict ES2022 ESNext.
+# Changelog
+
+All notable changes to `@neetru/sdk` will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Planned (post-2.1)
+- size-limit budget no CI (<12KB gz core com db namespace).
+- CDN distribution (`cdn.neetru.com/sdk/v2/`).
+- Endpoint batch `/api/v1/sdk/telemetry/batch` (substitui drenagem N×1 do `track()` por 1 request).
+
+## [2.1.1] - 2026-05-25 — **DbDocRef identity + DbBatchOp discriminated union [patch]**
+
+Dois fixes LOW reportados por pdv-agiliza (tickets `bug_97b3f0488d1c49cf8c5f94e5d544289b` + `bug_6aab9adc182640218652a65cdcb71b63`).
+Sem breaking changes — todos os usos de `doc()` existentes continuam funcionando.
+
+### Fixed
+
+- **`DbDocRef.id / .path / .collection`** (fix #13, ticket `bug_97b3f0488d1c49cf8c5f94e5d544289b`):
+  `DbDocRef` agora expõe três propriedades readonly de identidade:
+  - `id: string` — ID do documento dentro da coleção.
+  - `path: string` — Caminho completo `"colecao/docId"`.
+  - `collection: string` — Nome da coleção parent.
+  Análogo ao `DocumentReference.id/.path` do Firestore Web SDK. Elimina a necessidade
+  de adaptadores externos que reattachavam `collection + id` manualmente.
+  Implementado em `DbCollectionRefImpl.doc()` (offline), `createLazyCollectionRef.doc()`
+  (client-db) e `MockDb.doc()` (mocks).
+
+- **`DbBatchOp` discriminated union** (fix #14, ticket `bug_6aab9adc182640218652a65cdcb71b63`):
+  `DbBatchOp` foi convertido de `interface` opaca (campo `op: 'add'|'set'|'update'|'remove'`
+  com `id?`/`data?` opcionais) para **discriminated union** pelo campo `kind`:
+  ```ts
+  type DbBatchOp<T = Record<string, unknown>> =
+    | { kind: 'add';    data: Omit<T, 'id'> }
+    | { kind: 'set';    id: string; data: Omit<T, 'id'> }
+    | { kind: 'update'; id: string; data: Partial<Omit<T, 'id'>> }
+    | { kind: 'remove'; id: string };
+  ```
+  O `.d.ts` público agora expõe claramente quais campos são obrigatórios por variante.
+  O campo `collection` foi removido da operação (sempre opera na coleção do `DbCollectionRef`).
+
+### Migration (2.0.0 → 2.1.1)
+
+Callers que usavam `batch()` devem trocar `op` por `kind` e remover o campo `collection`:
+
+```ts
+// antes (2.0.0)
+col.batch([
+  { op: 'add',    collection: 'orders', data: { total: 10 } },
+  { op: 'set',    collection: 'orders', id: 'x', data: { total: 20 } },
+  { op: 'update', collection: 'orders', id: 'y', data: { total: 30 } },
+  { op: 'remove', collection: 'orders', id: 'z' },
+]);
+
+// depois (2.1.1)
+col.batch([
+  { kind: 'add',    data: { total: 10 } },
+  { kind: 'set',    id: 'x', data: { total: 20 } },
+  { kind: 'update', id: 'y', data: { total: 30 } },
+  { kind: 'remove', id: 'z' },
+]);
+```
+
+## [2.0.0] - 2026-05-22 — **client.db NeetruDb (Documentos engine-aware + SQL) [M2]**
+
+Major bump — breaking changes no namespace `db`. Liga todos os building blocks M2 na superfície pública.
+
+### Breaking Changes
+
+- **`client.db`** troca de `DbNamespace` (v0.3 REST simples) para `NeetruDb` (v2.0 offline-first engine-aware).
+  - `collection().list()` agora retorna `DbListResult<T>` (com `docs`, `nextCursor`, `fromCache`, `stale`, `hasPendingWrites`, `changes`) em vez de `T[]`.
+  - `collection().get(id)` retorna `DbGetResult<T> | null` em vez de `T | null`.
+  - `db_unavailable` não significa mais "sem rede" — só ciclo de vida do banco. Offline é transparente.
+  - Novos métodos obrigatórios na superfície: `sql()`, `syncState`, `flush()`, `clearCache()`, `getConflicts()`, `onSyncStateChanged()`, `batch()`, `onDoc()`, `onSnapshot()`, `doc()`.
+- **`db.sql(schema)` lança `NeetruDbError('db_unavailable')` em `NEETRU_ENV=dev`** — sem Postgres local, sem acesso SQL. Use `neetru dev` para subir o container.
+- **`initNeetru`** — mantido como stub funcional mas não mapeia mais `apiUrl → baseUrl`. Remover em v3.0.
+- **`MockDb`** foi atualizado para implementar `NeetruDb` (v2.0) em vez de `DbNamespace` (v0.3).
+
+### Added
+
+- **`client.db.collection<T>(name)`** — retorna `DbCollectionRef<T>` offline-first, engine-aware. Funciona sem rede. Sync automático quando conectado.
+  - CRUD: `add`, `set`, `update`, `remove`, `get`, `list` (com query, cursor, orderBy, where, limit).
+  - Batch: `batch(ops)` — operações atômicas (client-side).
+  - Realtime: `onSnapshot(query, cb)`, `onDoc(id, cb)` — subscriptions permanentes, delivery imediato do cache.
+  - Doc ref: `doc(id).get()`, `.set()`, `.update()`, `.remove()`, `.onSnapshot()`.
+- **`client.db.sql<TSchema>(schema)`** — lease SQL. Retorna `NeetruSqlClient<TSchema>` com `orm` (Drizzle `NodePgDatabase`) + `transaction()` + `close()`.
+- **`client.db.syncState`** — estado de sincronização observável (`status`, `pendingWrites`, `lastSyncedAt`, `isLeaderTab`).
+- **`client.db.onSyncStateChanged(cb)`** — subscrição de mudanças de sync state.
+- **`client.db.flush()`** — força ciclo de sync imediato.
+- **`client.db.clearCache(collections?)`** — limpa o cache local (IndexedDB).
+- **`client.db.getConflicts(collection?)`** — lista conflitos LWW pendentes.
+- **Engine detection** via `NeetruDbOptions.engine`: `'firestore'` | `'nosql-vm'` | `'rest'` (default MVP).
+- **Subpath `@neetru/sdk/db/react`** — hooks React: `useCollection`, `useDoc` (exporta via `dist/db-react.{mjs,cjs}`).
+- **Novos tipos públicos exportados**: `NeetruDb`, `NeetruDbEngine`, `NeetruDbOptions`, `NeetruSqlClient`, `DbSqlLease`, `DbCollectionRef`, `DbDocRef`, `DbQuery`, `DbDoc`, `DbListResult`, `DbGetResult`, `DbBatchOp`, `DbChangeType`, `NeetruDbError`, `NeetruDbErrorCode`.
+- **`createNeetruDb(config, opts)`** — factory async (para uso fora do `createNeetruClient`).
+- **`createNeetruDbSync(config, opts)`** — factory sync com lazy init IndexedDB (usada internamente em `createNeetruClient`).
+
+### Changed
+
+- **`NeetruClientConfig.db`** — aceita `NeetruDbOptions` (engine, dbId, collections, dbName, etc.).
+- **`client.config.mocks.db`** — agora é `NeetruDb` em vez de `DbNamespace`.
+- **`VERSION`** bumped para `'2.0.0'`.
+
+## [1.2.0] - 2026-05-19 — **Webhooks + Notifications + DX (cache, retry, batch)**
+
+Release de qualidade fechando 3 CRITICAL + 6 IMPORTANT do code review interno + 4 melhorias de DX. Adiciona `webhooks` + `notifications` no `NeetruClient`.
+
+### Added
+- **`client.webhooks`** — `register`/`list`/`unregister`/`test` pra endpoints HTTP do produto receberem eventos do Core (subscription.activated, usage.quota_exceeded, etc).
+- **`verifyWebhookSignature(payload, signature, secret)`** — util pura (HMAC SHA-256 constant-time compare via `node:crypto`) pra consumidor validar payloads recebidos.
+- **`client.notifications`** — `send`/`list`/`markRead`/`dismiss` pra produto integrar com a bandeja in-app do Neetru.
+- **`client.telemetry.track(input)`** + `client.telemetry.flush()` — fire-and-forget batch (500ms debounce). Ideal pra alta frequência (page-views, cliques). `event()` segue como single-shot com `eventId` ack.
+- **`client.entitlements.check(..., { cacheBust })`** — cache LRU em memória (60s TTL, 100 entries). Corta 90%+ requests em renders repetidos do `<EntitlementGate>`. `cacheBust: true` força ida ao servidor.
+- **httpRequest retry/backoff** — 2 retries default em `rate_limited` (429), `server_error` (5xx), `network_error`. Honra `Retry-After` header. Caller opt-out com `opts.retries: 0`.
+- **Subpaths novos**: `@neetru/sdk/webhooks`, `@neetru/sdk/notifications`.
+
+### Changed
+- **`client.catalog.list()` / `get()`** agora consomem `/api/sdk/v1/catalog` (público, sem Bearer) em vez de `/api/v1/cli/catalog` (staff). Consumidor não precisa mais de chave staff só pra ler catálogo. `includeDrafts` é ignorado — rascunhos só via CLI.
+- **`auth.signOut()`** revoga token em `auth.neetru.com/api/v1/oauth/revoke` (canônico), não mais `api.neetru.com/oauth/revoke` (404 em prod).
+- **`<EntitlementGate>`** passa `tenantId` (do `client.config.tenantId`) pra `usage.check`. Sem tenantId, cai pra `entitlements.check` em vez de chamar `usage.check` e travar em `validation_failed` silencioso.
+- **`engines.node`** subiu pra `>=20` (alinha com `target: node20` do tsup; Node 18 EOL).
+
+### Fixed
+- **CRITICAL** — `webhooks` e `notifications` lançavam `'invalid_input'`, código ausente da union `NeetruErrorCode`. Todas as 17 ocorrências viraram `'validation_failed'`.
+- **CRITICAL** — `telemetry.log()` chamava `/sdk/v1/telemetry/log` (404). Corrigido pra `/api/sdk/v1/telemetry/log`.
+- **CRITICAL** — `db` namespace tinha o mesmo bug em 6 paths (`/sdk/v1/datastore/...`). Corrigido em massa pra `/api/sdk/v1/datastore/...`.
+- **CRITICAL** — 8 `httpRequest` calls em `webhooks` e `notifications` não passavam `requireAuth: true` — todos hits em prod retornavam 401. Corrigido.
+- **`MockSupport.mockTicketSeq`** virou instance field (era module-level, poluía tests entre suites).
+- **`db.list()`** removeu variável `query` dead code (refactor incompleto de pre-1.1).
+
+### Internal
+- 51 testes novos (webhooks: 22, notifications: 20, react: 9). Total: 215 testes (16 files), 100% passing. tsc clean.
+- `api-surface-stability.test.ts` agora lock `webhooks` + `notifications` no `NeetruClient`.
+
+## [1.1.0] - 2026-05-08 — **Checkout namespace + React helpers**
+
+Adiciona o namespace `client.checkout` (start/get/cancel intent) com auto-redirect
+em browser. Suporte ao fluxo Sprint 13 onde produtos SaaS delegam checkout pro
+portal `minhaconta.neetru.com` via `POST /api/v1/checkout/intents`.
+
+### Added
+- **`client.checkout.start({productId, planId, callbackUrl, tenantType?, tenantId?})`** — cria
+  `checkout_intents/{intentId}` no Core e (em browser) redireciona automaticamente
+  pra `minhaconta.neetru.com/portal/checkout/{intentId}`. Em Node/SSR retorna
+  `{intentId, redirectUrl}` sem efeito colateral.
+- **`client.checkout.get(intentId)`** — lê estado atual do intent.
+- **`client.checkout.cancel(intentId)`** — marca intent como `cancelled`.
+- **Subpath `@neetru/sdk/react`** — componente `<CheckoutLink>` (wrapper de `<a>`
+  que dispara `start()` no click) + `<EntitlementGate mode="block|readonly">`
+  + hook `useEntitlementContext()` pra desabilitar escritas quando free tier
+  estoura limite (decisão CEO §5 — read-only sempre, não hard-block).
+- **`MockCheckout`** — implementação dev (`NEETRU_ENV=dev`) sem network. Retorna
+  URL fake `https://localhost:9003/portal/checkout/{intentId}` pra dev externo
+  testar UI sem provisionar conta Neetru.
+- **Peer dep `react ^18 || ^19`** marcado opcional (só carregado se import `/react`).
+
+### Changed
+- `VERSION` const bump `1.0.0 → 1.1.0`.
+- `NeetruClient.checkout` adicionado — backward-compatible (caller que não usa
+  o namespace não é afetado).
+
+### Notes
+- API stability test (`api-surface-stability.test.ts`) atualizado pra incluir
+  `checkout` no inventário canônico.
+
+## [1.0.0] - 2026-05-06 — **GA (General Availability)**
+
+Marco de estabilidade. A partir desta versão, **a superfície pública do SDK
+está congelada** — breaking changes só em majors (semver estrito).
+
+### Added
+- **API stability lock** — todos os contratos (`createNeetruClient`,
+  `NeetruClient`, namespaces `auth`/`catalog`/`entitlements`/`telemetry`/
+  `usage`/`support`/`db`, `NeetruError`) ficam estáveis em v1.x. Coberto
+  por `api-surface-stability.test.ts` que falha o build se algum método
+  muda forma.
+- **JSDoc completo** em toda função/método público — base pra `npm run docs:gen`
+  (typedoc → `sdk/docs-html/`).
+- **`docs:gen` script** + `scripts/typedoc.config.json` — gera HTML
+  navigable das APIs.
+- **`engines.node`** relaxado de `>=20` → `>=18` (suporta runtimes Node 18 LTS
+  ainda em uso por consumers).
+
+### Changed
+- `VERSION` bump `0.3.0` → `1.0.0`.
+- README atualizado com seção de migração v0.3 → v1.0 (no breaking changes —
+  upgrade transparente).
+
+### Migration v0.3 → v1.0
+- **Sem breaking changes.** Upgrade direto via `npm install @neetru/sdk@1.0.0`.
+- `initNeetru` continua deprecated mas funcional. **Será removido em v2.0.0.**
+- `NeetruConfig` continua deprecated. Use `NeetruClientConfig`.
+
+### Stability promise (v1.x)
+A partir de v1.0:
+- Métodos novos podem ser adicionados a namespaces existentes (minor bump).
+- Métodos podem ser marcados `@deprecated` em qualquer minor — só removidos
+  em major.
+- Tipos nunca ganham campos required em minor (só optional ou via union).
+- `NeetruErrorCode` é union fechado em v1.0 — qualquer novo código bumpa minor.
+
+### Notes
+- Pacote ainda **privado** (`private: true`). Publicação no npm é
+  responsabilidade do owner — gate no CHANGELOG continua trancado até decisão.
+
+## [0.3.0] - 2026-05-06
+
+### Added
+- Namespace `client.db` (v0.3) — wrapper minimalista pra coleções tenant-scoped:
+  - `client.db.collection(name).list({ limit? })`
+  - `client.db.collection(name).get(id)` (retorna null em not_found)
+  - `client.db.collection(name).set(id, data)` upsert
+  - `client.db.collection(name).remove(id)` delete
+  - Endpoints: `/sdk/v1/datastore/{collection}/{id?}` (placeholder REST — Sprint 9
+    finaliza; SDK já expõe interface estável).
+  - `MockDb` (in-memory) ativo em `NEETRU_ENV=dev`.
+- Namespace `client.usage` ganhou `report()` e `check()`:
+  - `usage.report(resource, qty?)` → `POST /sdk/v1/usage/record` canônico
+    (Sprint 7) — incrementa atomicamente `usage_counters/{tid}_{pid}_{r}_{yyyymm}`.
+  - `usage.check(resource)` → `GET /sdk/v1/entitlements?productId&tenantId&feature` —
+    retorna `{allowed, reason, remaining, limit, planId, planFeatures}`.
+- `NeetruClientConfig.productId` / `.tenantId` — defaults pra `usage.report` /
+  `usage.check` / `db.collection` quando não passado em options.
+- Mock helpers: `MockDb`, `MockUsage.report()`, `MockUsage.check()`.
+
+### Changed
+- `VERSION` bump `0.2.0` → `0.3.0`.
+- `NeetruClient` agora expõe `.db` além dos antigos.
+- `ResolvedConfig` ganhou `productId` + `tenantId` opcionais.
+
+### Backend (acompanha esta release)
+- Novos endpoints (Sprint 7):
+  - `POST /sdk/v1/usage/record` — atomic increment + 80%/100% notifications + audit.
+  - `GET  /sdk/v1/entitlements` — lookup canônico subscription→plan→counter.
+  - `POST /sdk/v1/telemetry/log` — batch logger pra `logs/{productId}/{yyyymmdd}/`.
+
+## [0.2.0] - 2026-05-06
+
+### Added
+- Namespace `client.auth` (v0.2 — OIDC + dev mocks):
+  - `signIn(options?)` — redireciona pra auth.neetru.com authorize endpoint
+    (browser) ou retorna mock user em dev (`NEETRU_ENV=dev`).
+  - `signOut()` — limpa `localStorage.neetru_id_token` + revoga refresh
+    server-side (best-effort).
+  - `getUser()` — decodifica id_token cached e retorna `NeetruUser` ou null.
+  - `onAuthStateChanged(listener)` — sub a mudanças, dispatcha sync no subscribe.
+- Namespace `client.usage` (v0.2 — meter):
+  - `track(event, props?)` → `POST /sdk/v1/usage/record` com Bearer.
+  - `getQuota(metric)` → `GET /sdk/v1/usage/quota?metric=` returns
+    `{ metric, used, limit, plan, resetsAt? }`.
+- Namespace `client.support` (v0.2 — tickets):
+  - `createTicket({subject, message, severity?, productSlug?})` →
+    `POST /api/v1/products/{slug}/tickets` (default `_default`).
+  - `listMyTickets()` → `GET ...` retorna array (aceita envelope `{tickets:[]}`).
+- `mocks` module (`@neetru/sdk/mocks`):
+  - `MockAuth`, `MockUsage`, `MockSupport`, `MockEntitlements` — overridáveis
+    via `createNeetruClient({ mocks: { auth: MockAuth(...), ... } })`.
+  - `DEV_FIXTURE_USER` constante exportada.
+- `NEETRU_ENV` resolution chain: config arg > `process.env.NEETRU_ENV` >
+  `globalThis.NEETRU_ENV` > default `prod`. `dev` ativa mocks automáticos.
+- Subpath exports adicionais: `@neetru/sdk/{auth,usage,support,mocks}`.
+- Tipos novos: `NeetruUser`, `AuthNamespace`, `UsageNamespace`,
+  `SupportNamespace`, `SignInOptions`, `SupportTicket`, `UsageQuota`,
+  `NeetruEnv`, `CreateTicketInput`.
+
+### Changed
+- `VERSION` bump `0.1.0` → `0.2.0`.
+- `NeetruClientConfig` ganhou campos `env` + `mocks`.
+- `ResolvedConfig` ganhou `env` resolved.
+- `NeetruClient` agora expõe `.auth`, `.usage`, `.support` além dos antigos.
+
+### Backend (acompanha esta release — endpoints documentados em `docs/SDK_OPENAPI.md`)
+- `POST /sdk/v1/usage/record` — record event meterado.
+- `GET  /sdk/v1/usage/quota?metric=` — ler quota atual.
+- `POST /api/v1/products/{slug}/tickets` — criar ticket.
+- `GET  /api/v1/products/{slug}/tickets` — listar meus tickets.
+- (auth) `auth.neetru.com/oauth/authorize` — já live (Sprint 1 OIDC).
+- (auth) `auth.neetru.com/oauth/revoke` — revoga refresh token.
+
+### Notes
+- Pacote ainda **privado** (`private: true`) — não publicado no npm.
+- Carry-over: integração OIDC live aguarda owner habilitar redirect_uri pro
+  domain do consumer (configurar em `oidc_clients/{client_id}.redirect_uris`).
+- TODO: `support.listMyTickets` precisa parametrizar productSlug (fixed
+  `_default` na v0.2).
+
+## [0.1.0] - 2026-05-05
+
+### Added
+- `createNeetruClient(config)` factory — entry point principal.
+  - Resolve `apiKey` (arg explícito > `NEETRU_API_KEY` env em Node).
+  - Resolve `baseUrl` (default `https://api.neetru.com`).
+  - Resolve `fetch` (arg > `globalThis.fetch`).
+- Namespace `client.catalog`:
+  - `list(opts?)` → `GET /api/v1/cli/catalog`. Aceita `includeDrafts`.
+  - `get(slug)` → `GET /api/v1/cli/catalog/{slug}`.
+- Namespace `client.entitlements`:
+  - `check(slug, feature)` → boolean.
+  - `checkDetailed(slug, feature)` → `EntitlementCheck` com `reason`.
+  - Backed por `GET /api/v1/sdk/entitlements/check`.
+- Namespace `client.telemetry`:
+  - `event({ name, properties?, timestamp? })` → `POST /api/v1/sdk/telemetry/event`.
+- Subpath exports map: `@neetru/sdk/{catalog,entitlements,telemetry,errors}`.
+- HTTP transport com mapeamento status → `NeetruError.code` estável.
+- Tipos exportados: `NeetruClient`, `NeetruClientConfig`, `Product`, `ProductPlan`,
+  `EntitlementCheck`, `TelemetryEventInput`, `TelemetryEventAck`, `NeetruErrorCode`.
+- Compat alias `initNeetru` (deprecated, será removido em v1.0).
+
+### Changed
+- `VERSION` bump `0.0.1` → `0.1.0`.
+- tsup config multi-entry pra subpath imports.
+
+### Backend (acompanha esta release)
+- `GET /api/v1/cli/catalog/{slug}` — produto único.
+- `GET /api/v1/sdk/entitlements/check?slug=&feature=` — verificação por user.
+- `POST /api/v1/sdk/telemetry/event` — persiste em `usage_events`.
+
+### Notes
+- Pacote ainda **privado** (`private: true`). Publicação no npm é
+  responsabilidade do owner em Sprint 6.
+- API instável; pré-1.0 segue regra "breaking allowed em qualquer minor".
+
+## [0.0.1] - 2026-05-04
+
+### Added
+- Scaffold inicial do pacote `@neetru/sdk` (private, não publicado no npm ainda).
+- `initNeetru(config)` com validação de `apiUrl` e injeção opcional de `fetch`.
+- `NeetruError` com `code`, `status` e `requestId` opcionais.
+- `NeetruConfig` e `NeetruClient` types públicos.
+- `VERSION` const exportada.
+- Build pipeline com tsup (dual ESM + CJS + `.d.ts`).
+- README + CHANGELOG.
+- `tsconfig.json` strict ES2022 ESNext.