@neetru/sdk 2.3.2 → 2.3.4

package/CHANGELOG.md

@@ -1,474 +1,282 @@
-# 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).
-
-## [2.3.2] - 2026-05-26 — **fix(mocks): MockDb.sql() implementado in-memory via pg-mem — bug_a7f2ae25 [HIGH]**
-
-### Corrigido
-
-- **bug_a7f2ae25fda54129b52b6dd55aaa6050 (HIGH) — `MockDb.sql()` lançava `db_unavailable` em vez de implementar Drizzle in-memory.**
-  Bloqueava vitest server-side dos consumers (pdv-agiliza Fase 4 migration). Política do projeto proíbe workaround instalar `pg-mem` no consumer.
-  Fix: `MockDb.sql(schema, options)` agora carrega `pg-mem` lazy + cria `NodePgDatabase<TSchema>` Drizzle apontando pra DB in-memory. Suporta `options.initSql: string | string[]` pra rodar DDL no setup (CREATE TABLE etc).
-  `pg-mem` adicionado como `peerDependency optional` (com `peerDependenciesMeta.optional=true`) + `devDependency` interno. Consumers que querem mock SQL: `npm install -D pg-mem drizzle-orm pg`.
-  **Não-breaking:** signature `sql(schema, options?)` mantida. SqlOptions ganhou `initSql?` opcional (ignorado por lease real em produção). Comportamento default — `sql()` sem `initSql` — funciona em ambos modos.
-
-## [2.3.1] - 2026-05-26 — **fix(deps): drizzle-orm + pg como peerDependencies — bug_42ae9f80 [CRITICAL]**
-
-### Corrigido
-
-- **bug_42ae9f80b2884bd583c5246771f7730c (CRITICAL) — `drizzle-orm` em `dependencies` causava type collision com versão do consumer.**
-  Quando o projeto consumer instalava `drizzle-orm` direto e tentava `client.db.sql(schema)`, o TypeScript via 2 cópias diferentes (uma nested em `node_modules/@neetru/sdk/node_modules/drizzle-orm`, outra no consumer) e reclamava: `'Property config is protected but type Column<...> is not a class derived from Column<...>'` + `'shouldInlineParams private'`. Bloqueava Fases 2-8 da migração pdv-agiliza pra `vm-postgres-single`.
-  Fix: movidas `drizzle-orm` e `pg` de `dependencies` pra `peerDependencies` (com `peerDependenciesMeta.optional: true`). Consumer instala 1 versão, todos os tipos convergem. Devkit mantém `drizzle-orm` + `pg` em `devDependencies` pra build/test internos.
-  **Breaking expected on consumer side:** se o projeto consumer NÃO tinha `drizzle-orm` em deps mas usava `client.db.sql()`, agora precisa `npm install drizzle-orm pg`. Consumers que só usam transport REST/Firestore não são afetados (peerDeps optional).
-
-## [2.3.0] - 2026-05-25 — **feat(db-config): renomeia engine→transport com deprecation — bug_ed9da7fd [HIGH]**
-
-Fix do bug `bug_ed9da7fd11194eac87f0eb9c75e5fad9` (HIGH) — colisão de terminologia: `engine` no SDK
-configurava o transporte SDK↔Core (REST/Firestore/WebSocket), mas `engine` no admin database (CLI
-`neetru admin database create --engine=...`) configura o storage engine (firestore-instance,
-cloud-sql-postgres, vm-postgres-single…). Devs colocavam `firestore-instance` no SDK e quebravam.
-
-### Added
-
-- **`NeetruDbTransport`** — novo tipo público canônico para o campo de transporte SDK↔Core.
-  Valores: `'rest' | 'firestore' | 'nosql-vm'` (idênticos aos de `NeetruDbEngine`).
-
-- **`NeetruDbOptions.transport`** — novo campo canônico que substitui `engine`.
-  ```ts
-  // v2.3+ (preferido):
-  createNeetruClient({ db: { transport: 'rest' } });
-  createNeetruClient({ db: { transport: 'firestore' } });
-  createNeetruClient({ db: { transport: 'nosql-vm', realtimeGatewayUrl: '...' } });
-  ```
-
-### Deprecated
-
-- **`NeetruDbOptions.engine`** — depreciado em v2.3, será removido em v3.0.
-  Continua funcionando: se `transport` estiver ausente e `engine` presente, o valor de `engine`
-  é usado como transport com `console.warn` de deprecação.
-
-  ```ts
-  // v2.x (depreciado — emite console.warn):
-  createNeetruClient({ db: { engine: 'firestore' } });
-  // ⚠ [neetru/sdk] NeetruDbOptions.engine está depreciado...
-  ```
-
-- **`NeetruDbEngine`** — depreciado em v2.3, será removido em v3.0.
-  Agora é alias de `NeetruDbTransport`. Use `NeetruDbTransport` em código novo.
-
-### Behavior
-
-- `transport` e `engine` podem coexistir: `transport` sempre prevalece, sem warn.
-- Sem `transport` nem `engine`: default `'rest'`, sem warn (comportamento idêntico ao v2.x).
-- A relação 1:N entre storage engines e transports é documentada no JSDoc de `NeetruDbTransport`:
-  qualquer storage engine (cloud-sql-postgres, vm-postgres-single…) pode ser acessado com
-  `transport: 'rest'`; `transport: 'firestore'` e `transport: 'nosql-vm'` são para bancos
-  documentais com realtime nativo.
-
-### Tests
-
-- 5 testes novos em `src/__tests__/db-real.test.ts`:
-  `transport=firestore`, `transport=nosql-vm`, `transport=rest`, colisão `transport+engine`
-  (transport prevalece, sem warn), default sem campos (sem warn).
-- Testes de regressão: `engine=firestore` e `engine=nosql-vm` legados ainda passam + emitem warn.
-
-## [2.2.1] - 2026-05-25 — **fix(offline-docs): fallback MemoryStore em Node — bug_ba287a CRITICAL**
-
-Fix do bug `bug_ba287aefdf6c4327b026d588a239ad06` (CRITICAL) — `client.db.collection().set/add/update`
-lançava `ReferenceError: indexedDB is not defined` em Node.js (reportado por pdv-agiliza prod).
-
-### Fixed
-
-- **`createOfflineDocumentsNamespace` — auto-detect Node runtime e usa `MemoryStore`**.
-  A função agora verifica `typeof indexedDB === 'undefined' || typeof window === 'undefined'`
-  antes de instanciar `LocalStore` (que depende de `idb` / IndexedDB). Em Node/Bun/Edge Workers
-  sem IDB, cai automaticamente em `MemoryStore` — implementação in-process com a mesma API,
-  sem nenhuma flag explícita necessária. Ops de documentos (`set/add/update/remove/get/list`,
-  `batch`, `onSnapshot`, `onDoc`) funcionam normalmente em Node; dados não persistem entre
-  reinicializações do processo (comportamento esperado em SSR/server-side).
-
-### Added
-
-- **`src/db/offline/memory-store.ts`** — `MemoryStore`: implementação in-memory do contrato
-  público de `LocalStore`. Cobre todas as 5 stores (documents, mutations, query\_cache,
-  sync\_meta, conflict\_log) com Maps/Arrays em memória.
-
-### Tests
-
-- **`src/__tests__/offline-docs-node-compat.test.ts`** — 5 casos de regressão:
-  verifica que a stack offline não lança `ReferenceError` em ambiente sem IDB,
-  e que `set/add/update` + `get` roundtrips funcionam in-memory.
-
-## [2.2.0] - 2026-05-25 — **auth.verifyToken — validação server-side de id_token via JWKS [feature]**
-
-Fix do bug `bug_a7ef1702680044e3994b74bdccecb2ab` — resolve P0-1 audit security pdv-agiliza.
-
-### Added
-
-- **`client.auth.verifyToken(token, options?): Promise<NeetruUser>`** — valida um id_token JWT
-  emitido por `auth.neetru.com` server-side, sem round-trip de rede por request. Usa JWKS local
-  cacheado (default TTL 1h, configurável via `options.jwksCacheTtlMs`).
-
-  Erros tipados novos (`NeetruErrorCode`):
-  - `token_expired` — `exp` no passado
-  - `token_invalid_signature` — assinatura não verificada pela JWKS
-  - `token_invalid_audience` — `aud` não bate com o `clientId` extraído do `apiKey`
-  - `token_invalid_issuer` — `iss` não é `https://auth.neetru.com`
-
-  Dependência nova: `jose` (Vercel/Cloudflare-friendly, sem Node nativo).
-
-- **`MockAuth.verifyToken(token)`** — decodifica JWT sem verificar assinatura (útil em testes).
-  Aceita `__mockVerifyToken(fn)` pra injetar falhas determinísticas.
-
-- **`VerifyTokenOptions`** — exportado em `index.ts` pra consumers tiparem as options.
-
-### Usage
-
-```ts
-// Next.js route handler
-import { createNeetruClient } from '@neetru/sdk';
-const client = createNeetruClient({ apiKey: 'nrt_a1b2c3_...', env: 'prod' });
-
-export async function POST(req: Request) {
-  const token = req.cookies.get('neetru-session')?.value ?? '';
-  try {
-    const user = await client.auth.verifyToken(token);
-    // user.uid, user.email, user.isStaff, user.tenantId disponíveis
-  } catch (err) {
-    return new Response('Unauthorized', { status: 401 });
-  }
-}
-```
-
-## [Unreleased]
-
-### Planned (post-2.2)
-- 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.
+# 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).
+
+## [2.3.4] - 2026-05-26 — **fix(mocks): MockDb.sql() migra pra pglite + pg-mem fallback — bug_6bae8674 [HIGH]**
+
+### Corrigido
+
+- **bug_6bae8674461f4600809e2f9de13c6043 (HIGH) — fix anterior (2.3.3) teve efeito INVERSO em `MockDb.sql()`.**
+  O fix de 2.3.3 injetava `getTypeParser` em `pool.types` para resolver o erro "Not supported: getTypeParser is not supported".
+  Porém `pg-mem` tem um guard interno: `if (query.types?.getTypeParser) throw NotSupported`.
+  `drizzle-orm/node-postgres/session.js:113` passa `rawQuery.types = pool.types` em TODA query — ao adicionar
+  `getTypeParser` ao pool, drizzle passou-o para o pg-mem que o rejeitou imediatamente.
+  Efeito líquido: qualquer `INSERT`/`SELECT`/`UPDATE` continuava quebrando com o mesmo erro.
+
+  **Fix 2.3.4 — duas soluções em cascata:**
+
+  1. **Solução A (preferida): `@electric-sql/pglite` + `drizzle-orm/pglite`** — WASM-Postgres nativo
+     sem adapter pg-mem. Sem conflito `getTypeParser`, sem monkey-patch. `PGlite.create()` retorna
+     instância pronta, DDL via `pglite.query(ddl)`, ORM via `drizzle(pglite, { schema })`. Cast
+     `PgliteDatabase → NodePgDatabase` via `unknown` (interfaces Drizzle compatíveis em superfície
+     mas com tipos de resultado internos distintos).
+
+  2. **Solução B (fallback pg-mem)**: strip interceptor — intercepta `pool.query` e deleta
+     `types.getTypeParser` do objeto de query ANTES do pg-mem ver. Guard não dispara, query passa
+     limpa. Compatível com consumers que só têm pg-mem nas devDeps.
+
+  **`@electric-sql/pglite` adicionado como `peerDependency` optional** (`^0.4.0`) + `devDependency`
+  interno (`^0.4.6`).
+
+  **8 novos testes** em `src/__tests__/mocks-sql-pglite.test.ts`: criação sem erro, INSERT sem throw,
+  SELECT após INSERT, UPDATE, múltiplos INSERTs, sem initSql, close idempotente, transaction().
+  Todos passando.
+
+  **655 testes totais** (era 647 em 2.3.3). `tsc --noEmit` clean. Build clean.
+
+## [2.3.3] - 2026-05-26 — **fix(mocks): pool.types.getTypeParser identity parser — bug_44bcc99f [HIGH]**
+
+### Corrigido
+
+- **bug_44bcc99f9d3140d78abd8f7810d1afa4 (HIGH) — `MockDb.sql()` queries Drizzle falhavam em runtime.**
+  Followup do `bug_a7f2ae25` (SDK 2.3.2): `sql()` retornava handle Drizzle, mas qualquer query (`INSERT`, `SELECT`, etc) jogava `Error: Not supported: getTypeParser is not supported`. `pg-mem` não implementa `pool.types.getTypeParser(oid)` que `drizzle-orm/node-postgres/session.js` chama em TODA query.
+  Fix: monkey-patch identity parser no Pool retornado por `pg-mem.adapters.createPg()` antes de passar pro Drizzle. Types retornam o valor sem transformação (suficiente pra tests in-memory; produção usa `pg` real com parsers nativos).
+  3 linhas. Non-breaking. Tests E2E Drizzle in-memory destravados.
+
+## [2.3.2] - 2026-05-26 — **fix(mocks): MockDb.sql() implementado in-memory via pg-mem — bug_a7f2ae25 [HIGH]**
+
+### Corrigido
+
+- **bug_a7f2ae25fda54129b52b6dd55aaa6050 (HIGH) — `MockDb.sql()` lançava `db_unavailable` em vez de implementar Drizzle in-memory.**
+  Bloqueava vitest server-side dos consumers (pdv-agiliza Fase 4 migration). Política do projeto proíbe workaround instalar `pg-mem` no consumer.
+  Fix: `MockDb.sql(schema, options)` agora carrega `pg-mem` lazy + cria `NodePgDatabase<TSchema>` Drizzle apontando pra DB in-memory. Suporta `options.initSql: string | string[]` pra rodar DDL no setup (CREATE TABLE etc).
+  `pg-mem` adicionado como `peerDependency optional` (com `peerDependenciesMeta.optional=true`) + `devDependency` interno. Consumers que querem mock SQL: `npm install -D pg-mem drizzle-orm pg`.
+  **Não-breaking:** signature `sql(schema, options?)` mantida. SqlOptions ganhou `initSql?` opcional (ignorado por lease real em produção). Comportamento default — `sql()` sem `initSql` — funciona em ambos modos.
+
+## [2.3.1] - 2026-05-26 — **fix(deps): drizzle-orm + pg como peerDependencies — bug_42ae9f80 [CRITICAL]**
+
+### Corrigido
+
+- **bug_42ae9f80b2884bd583c5246771f7730c (CRITICAL) — `drizzle-orm` em `dependencies` causava type collision com versão do consumer.**
+  Quando o projeto consumer instalava `drizzle-orm` direto e tentava `client.db.sql(schema)`, o TypeScript via 2 cópias diferentes (uma nested em `node_modules/@neetru/sdk/node_modules/drizzle-orm`, outra no consumer) e reclamava: `'Property config is protected but type Column<...> is not a class derived from Column<...>'` + `'shouldInlineParams private'`. Bloqueava Fases 2-8 da migração pdv-agiliza pra `vm-postgres-single`.
+  Fix: movidas `drizzle-orm` e `pg` de `dependencies` pra `peerDependencies` (com `peerDependenciesMeta.optional: true`). Consumer instala 1 versão, todos os tipos convergem. Devkit mantém `drizzle-orm` + `pg` em `devDependencies` pra build/test internos.
+  **Breaking expected on consumer side:** se o projeto consumer NÃO tinha `drizzle-orm` em deps mas usava `client.db.sql()`, agora precisa `npm install drizzle-orm pg`. Consumers que só usam transport REST/Firestore não são afetados (peerDeps optional).
+
+## [2.3.0] - 2026-05-25 — **feat(db-config): renomeia engine→transport com deprecation — bug_ed9da7fd [HIGH]**
+
+Fix do bug `bug_ed9da7fd11194eac87f0eb9c75e5fad9` (HIGH) — colisão de terminologia: `engine` no SDK
+configurava o transporte SDK↔Core (REST/Firestore/WebSocket), mas `engine` no admin database (CLI
+`neetru admin database create --engine=...`) configura o storage engine (firestore-instance,
+cloud-sql-postgres, vm-postgres-single…). Devs colocavam `firestore-instance` no SDK e quebravam.
+
+### Added
+
+- **`NeetruDbTransport`** — novo tipo público canônico para o campo de transporte SDK↔Core.
+  Valores: `'rest' | 'firestore' | 'nosql-vm'` (idênticos aos de `NeetruDbEngine`).
+
+- **`NeetruDbOptions.transport`** — novo campo canônico que substitui `engine`.
+  ```ts
+  // v2.3+ (preferido):
+  createNeetruClient({ db: { transport: 'rest' } });
+  createNeetruClient({ db: { transport: 'firestore' } });
+  createNeetruClient({ db: { transport: 'nosql-vm', realtimeGatewayUrl: '...' } });
+  ```
+
+### Deprecated
+
+- **`NeetruDbOptions.engine`** — depreciado em v2.3, será removido em v3.0.
+  Continua funcionando: se `transport` estiver ausente e `engine` presente, o valor de `engine`
+  é usado como transport com `console.warn` de deprecação.
+
+  ```ts
+  // v2.x (depreciado — emite console.warn):
+  createNeetruClient({ db: { engine: 'firestore' } });
+  // ⚠ [neetru/sdk] NeetruDbOptions.engine está depreciado...
+  ```
+
+- **`NeetruDbEngine`** — depreciado em v2.3, será removido em v3.0.
+  Agora é alias de `NeetruDbTransport`. Use `NeetruDbTransport` em código novo.
+
+### Behavior
+
+- `transport` e `engine` podem coexistir: `transport` sempre prevalece, sem warn.
+- Sem `transport` nem `engine`: default `'rest'`, sem warn (comportamento idêntico ao v2.x).
+- A relação 1:N entre storage engines e transports é documentada no JSDoc de `NeetruDbTransport`:
+  qualquer storage engine (cloud-sql-postgres, vm-postgres-single…) pode ser acessado com
+  `transport: 'rest'`; `transport: 'firestore'` e `transport: 'nosql-vm'` são para bancos
+  documentais com realtime nativo.
+
+### Tests
+
+- 5 testes novos em `src/__tests__/db-real.test.ts`:
+  `transport=firestore`, `transport=nosql-vm`, `transport=rest`, colisão `transport+engine`
+  (transport prevalece, sem warn), default sem campos (sem warn).
+- Testes de regressão: `engine=firestore` e `engine=nosql-vm` legados ainda passam + emitem warn.
+
+## [2.2.1] - 2026-05-25 — **fix(offline-docs): fallback MemoryStore em Node — bug_ba287a CRITICAL**
+
+Fix do bug `bug_ba287aefdf6c4327b026d588a239ad06` (CRITICAL) — `client.db.collection().set/add/update`
+lançava `ReferenceError: indexedDB is not defined` em Node.js (reportado por pdv-agiliza prod).
+
+### Fixed
+
+- **`createOfflineDocumentsNamespace` — auto-detect Node runtime e usa `MemoryStore`**.
+  A função agora verifica `typeof indexedDB === 'undefined' || typeof window === 'undefined'`
+  antes de instanciar `LocalStore` (que depende de `idb` / IndexedDB). Em Node/Bun/Edge Workers
+  sem IDB, cai automaticamente em `MemoryStore` — implementação in-process com a mesma API,
+  sem nenhuma flag explícita necessária. Ops de documentos (`set/add/update/remove/get/list`,
+  `batch`, `onSnapshot`, `onDoc`) funcionam normalmente em Node; dados não persistem entre
+  reinicializações do processo (comportamento esperado em SSR/server-side).
+
+### Added
+
+- **`src/db/offline/memory-store.ts`** — `MemoryStore`: implementação in-memory do contrato
+  público de `LocalStore`. Cobre todas as 5 stores (documents, mutations, query\_cache,
+  sync\_meta, conflict\_log) com Maps/Arrays em memória.
+
+### Tests
+
+- **`src/__tests__/offline-docs-node-compat.test.ts`** — 5 casos de regressão:
+  verifica que a stack offline não lança `ReferenceError` em ambiente sem IDB,
+  e que `set/add/update` + `get` roundtrips funcionam in-memory.
+
+## [2.2.0] - 2026-05-25 — **auth.verifyToken — validação server-side de id_token via JWKS [feature]**
+
+Fix do bug `bug_a7ef1702680044e3994b74bdccecb2ab` — resolve P0-1 audit security pdv-agiliza.
+
+### Added
+
+- **`client.auth.verifyToken(token, options?): Promise<NeetruUser>`** — valida um id_token JWT
+  emitido por `auth.neetru.com` server-side, sem round-trip de rede por request. Usa JWKS local
+  cacheado (default TTL 1h, configurável via `options.jwksCacheTtlMs`).
+
+  Erros tipados novos (`NeetruErrorCode`):
+  - `token_expired` — `exp` no passado
+  - `token_invalid_signature` — assinatura não verificada pela JWKS
+  - `token_invalid_audience` — `aud` não bate com o `clientId` extraído do `apiKey`
+  - `token_invalid_issuer` — `iss` não é `https://auth.neetru.com`
+
+  Dependência nova: `jose` (Vercel/Cloudflare-friendly, sem Node nativo).
+
+- **`MockAuth.verifyToken(token)`** — decodifica JWT sem verificar assinatura (útil em testes).
+  Aceita `__mockVerifyToken(fn)` pra injetar falhas determinísticas.
+
+- **`VerifyTokenOptions`** — exportado em `index.ts` pra consumers tiparem as options.
+
+### Usage
+
+```ts
+// Next.js route handler
+import { createNeetruClient } from '@neetru/sdk';
+const client = createNeetruClient({ apiKey: 'nrt_a1b2c3_...', env: 'prod' });
+
+export async function POST(req: Request) {
+  const token = req.cookies.get('neetru-session')?.value ?? '';
+  try {
+    const user = await client.auth.verifyToken(token);
+    // user.uid, user.email, user.isStaff, user.tenantId disponíveis
+  } catch (err) {
+    return new Response('Unauthorized', { status: 401 });
+  }
+}
+```
+
+## [Unreleased]
+
+### Planned (post-2.2)
+- 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.).