@neetru/sdk 1.1.0 → 1.2.0

package/CHANGELOG.md

@@ -7,11 +7,41 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
-### Planned (post-1.1)
-- Telemetry batching + flush on unload.
-- LRU cache em entitlements.check (TTL configurável).
+### 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**
 

package/README.md

@@ -1,218 +1,194 @@
 # @neetru/sdk
 
-Biblioteca runtime para consumir o ecossistema Neetru — catálogo público de
-produtos, entitlements de tenant e telemetria — de qualquer
-JavaScript/TypeScript moderno (browser, Node ≥20, Edge runtimes).
+> Biblioteca runtime oficial pra consumir o ecossistema Neetru a partir de produtos SaaS (Next.js, Node, browser, Edge runtimes).
 
-> **Status:** `1.0.0` GA — superfície pública estabilizada (2026-05-06).
-> Namespaces `auth`/`catalog`/`entitlements`/`telemetry`/`usage`/`support`/`db`.
-> A partir de v1.0, breaking changes só em majors. CDN distribution segue
-> roadmap pós-1.0 — vide [`docs/PLAN_SDK_NEETRU.md`](../docs/PLAN_SDK_NEETRU.md).
+<p>
+  <img alt="npm" src="https://img.shields.io/npm/v/@neetru/sdk?logo=npm">
+  <img alt="downloads" src="https://img.shields.io/npm/dm/@neetru/sdk?logo=npm">
+  <img alt="bundle size" src="https://img.shields.io/bundlephobia/minzip/@neetru/sdk">
+  <img alt="Node" src="https://img.shields.io/badge/node-%3E%3D18-339933?logo=node.js&logoColor=white">
+  <img alt="license" src="https://img.shields.io/badge/license-MIT-22c55e">
+</p>
 
----
-
-## Princípios
-
-- **Vendor-neutral** — apesar do Core usar Firebase, a superfície pública do
-  SDK não vaza isso (sem `firebase/app` exposto).
-- **TypeScript-first** — `.d.ts` shipped, JSDoc em toda função pública.
-- **Tree-shakable** — ESM-first, `"sideEffects": false`. Subpath imports
-  permitidos (`@neetru/sdk/catalog`, `@neetru/sdk/telemetry`, etc).
-- **Universal** — usa `fetch` global. Sem `node:` builtins no core.
-- **Erros tipados** — todos erros são `NeetruError` com `.code`, `.status`,
-  `.requestId`.
-- **Semver estrito** — pós v1.0, breaking changes só em majors.
-
-## Install
+## Instalação
 
 ```bash
 npm install @neetru/sdk
 ```
 
-> Pacote ainda **privado** (`private: true`) e não publicado no npm.
-> Reservar é responsabilidade do owner em Sprint 6 do plano.
-
-## Quick start
+## Hello world
 
 ```ts
-import { createNeetruClient, NeetruError } from '@neetru/sdk';
+import { createNeetruClient } from '@neetru/sdk';
 
-const client = createNeetruClient({
-  apiKey: process.env.NEETRU_API_KEY, // ou deixe undefined que ele lê do env
-  baseUrl: 'https://api.neetru.com',  // default
+const neetru = createNeetruClient({
+  apiKey: process.env.NEETRU_API_KEY,    // nrt_<keyId>_<secret>
+  env: 'prod',                           // 'dev' = mocks in-memory
 });
 
-// 1. Catálogo público de produtos
-const { products } = await client.catalog.list();
-console.log(products.map((p) => p.slug));
-
-const product = await client.catalog.get('neetru-pulse');
-
-// 2. Entitlements — pode o caller usar a feature `export-pdf` do produto?
-const allowed = await client.entitlements.check('neetru-pulse', 'export-pdf');
-if (!allowed) showUpgradeBanner();
+// Auth
+const user = await neetru.auth.signIn();
+console.log('logado como:', user?.email);
 
-// 3. Telemetria — emite evento de uso
-await client.telemetry.event({
-  name: 'report_exported',
-  properties: { format: 'pdf', plan: 'pro' },
-});
-```
-
-Discriminação de erro:
-
-```ts
-try {
-  await client.catalog.list();
-} catch (err) {
-  if (err instanceof NeetruError) {
-    if (err.code === 'rate_limited') retry();
-    if (err.code === 'unauthorized') promptLogin();
-    console.error(err.code, err.message, err.status, err.requestId);
-  }
-}
+// Entitlement check
+const canAi = await neetru.entitlements.check('gestovendas', 'ai_recommendations');
+if (canAi) { /* mostrar feature */ }
 ```
 
-## API reference (v0.2)
+## Princípios
 
-### `createNeetruClient(config?)`
+- **Vendor-neutral** — superfície pública NÃO vaza Firebase/Stripe/etc. Backend Neetru pode mudar no futuro sem reescrever produto.
+- **Tree-shakable** — ESM-first, sem side-effects. Importe só os namespaces que usa.
+- **Universal** — browser, Node ≥18, Edge runtimes (Vercel Edge, Cloudflare Workers). Usa `fetch` global.
+- **Tipado** — erros via `NeetruError` com `.code`, `.status`, `.requestId`.
+- **Dev mode** — `NEETRU_ENV=dev` ativa mocks automáticos — zero rede em testes locais.
 
-| Campo | Tipo | Descrição |
-|---|---|---|
-| `apiKey` | `string?` | Bearer token `nrt_<keyId>_<secret>`. Default lê `process.env.NEETRU_API_KEY` em Node. |
-| `baseUrl` | `string?` | URL base. Default `https://api.neetru.com`. |
-| `fetch` | `typeof fetch?` | Implementação custom. Default `globalThis.fetch`. |
-| `env` | `'dev' \| 'workspace' \| 'prod'?` | Ativa mocks automáticos em `dev`. Default `prod` (lê `NEETRU_ENV`). |
-| `mocks` | `{ auth?, usage?, support?, entitlements? }?` | Override de namespaces — útil em tests do consumer. |
+## Namespaces v1.2
 
-Retorna `NeetruClient` com `.config`, `.auth`, `.catalog`, `.entitlements`, `.telemetry`, `.usage`, `.support`.
+| Namespace | O que oferece |
+|---|---|
+| `auth` | OIDC sign-in / sign-out + dev fixture user |
+| `catalog` | Produtos públicos (`list` / `get`) |
+| `entitlements` | Verificação `(productSlug, feature)` → boolean ou detalhado |
+| `telemetry` | `event(...)` + `log(...)` per-product |
+| `usage` | `track` / `getQuota` / `report` / `check` (metering canônico) |
+| `support` | `createTicket` / `listMyTickets` |
+| `db` | Coleções tenant-scoped (`list` / `get` / `set` / `add` / `update` / `remove`) |
+| `checkout` | Stripe Checkout intent (`start` / `get` / `cancel` + auto-redirect) |
+| `webhooks` ⭐ v1.2 | Produtos registram URL pra receber eventos Core (subscription.activated, usage.quota_exceeded, etc) |
+| `notifications` ⭐ v1.2 | Produto envia notification in-app pros SEUS usuários (distinto das staff-only do Core) |
 
-### `client.auth` (v0.2)
+## Exemplos por namespace
 
-| Método | Descrição |
-|---|---|
-| `signIn(options?)` | Redireciona pro authorize endpoint (browser) ou retorna fixture user (dev). |
-| `signOut()` | Limpa session local + revoga refresh server-side. |
-| `getUser()` | Retorna `NeetruUser` cached do id_token ou `null`. |
-| `onAuthStateChanged(listener)` | Sub a mudanças. Dispatch sync no subscribe. Retorna unsubscribe. |
+### Webhooks outbound (v1.2)
 
-### `client.catalog`
+```ts
+await neetru.webhooks.register({
+  url: 'https://meu-produto.com/webhooks/neetru',
+  events: ['subscription.activated', 'subscription.cancelled', 'usage.quota_exceeded'],
+  secret: 'chave-32-chars-pra-hmac-sha256',
+});
 
-| Método | Descrição |
-|---|---|
-| `list(opts?)` | `GET /api/v1/cli/catalog`. Retorna `{ products, fetchedAt }`. |
-| `get(slug)` | `GET /api/v1/cli/catalog/{slug}`. Retorna `Product` ou lança `not_found`. |
+const endpoints = await neetru.webhooks.list();
+const test = await neetru.webhooks.test(endpoints[0].id);
+console.log(test.statusCode, test.durationMs);
+```
 
-### `client.entitlements`
+Eventos recebidos no seu endpoint chegam com:
+- `X-Neetru-Signature: sha256=<hmac>` (se `secret` registrado)
+- `X-Neetru-Timestamp: <ms>` (replay protection — rejeitar > 5min skew)
 
-| Método | Descrição |
-|---|---|
-| `check(slug, feature)` | `boolean`. Atalho do `checkDetailed`. |
-| `checkDetailed(slug, feature)` | `EntitlementCheck` com `allowed`, `reason`. |
+### Notifications produto → user (v1.2)
 
-### `client.telemetry`
+```ts
+await neetru.notifications.send({
+  userId: 'usr_xyz',
+  kind: 'order.received',
+  severity: 'success',
+  title: 'Novo pedido #1234',
+  body: 'Pedido de R$ 89,90',
+  link: '/orders/1234',
+  fingerprint: 'order:1234',           // dedup < 24h
+});
 
-| Método | Descrição |
-|---|---|
-| `event({ name, properties?, timestamp? })` | `POST /api/v1/sdk/telemetry/event`. Retorna `{ ok, eventId }`. |
+const notifs = await neetru.notifications.list('usr_xyz', { onlyUnread: true });
+await neetru.notifications.markRead(notifs[0].id);
+```
 
-### `client.usage` (v0.2)
+### Entitlements
 
-| Método | Descrição |
-|---|---|
-| `track(event, props?)` | `POST /sdk/v1/usage/record`. Persiste consumo. |
-| `getQuota(metric)` | `GET /sdk/v1/usage/quota?metric=`. Retorna `{ used, limit, plan, resetsAt? }`. |
+```ts
+const ok = await neetru.entitlements.check('gestovendas', 'ai_recommendations');
+const detailed = await neetru.entitlements.detailed('gestovendas', 'ai_recommendations');
+// → { allowed, planId, remaining?, limit?, reason }
+```
 
-### `client.support` (v0.2)
+### Usage tracking
 
-| Método | Descrição |
-|---|---|
-| `createTicket({subject, message, severity?, productSlug?})` | `POST /api/v1/products/{slug}/tickets`. |
-| `listMyTickets()` | `GET /api/v1/products/_default/tickets`. |
+```ts
+await neetru.usage.track('report_generated', { count: 42, format: 'pdf' });
 
-### Mocks (`@neetru/sdk/mocks`)
+const quota = await neetru.usage.getQuota('reports_per_month');
+// → { used: 15, limit: 100, resetsAt: '...', plan: 'starter' }
+```
 
-Use em tests do consumer ou ative globalmente com `NEETRU_ENV=dev`:
+### Support
 
 ```ts
-import { createNeetruClient, MockAuth, MockUsage, MockSupport } from '@neetru/sdk';
-
-const client = createNeetruClient({
-  mocks: {
-    auth: new MockAuth({ uid: 'fake', email: 'fake@x.com' }),
-    usage: new MockUsage(),
-    support: new MockSupport(),
-  },
+await neetru.support.createTicket({
+  subject: 'Bug ao exportar CSV',
+  message: 'Quando seleciono >1000 rows o export falha',
+  severity: 'high',
 });
+
+const myTickets = await neetru.support.listMyTickets({ status: 'open' });
 ```
 
-### Códigos de erro estáveis (`NeetruError.code`)
+### DB (tenant-scoped, vendor-neutral)
 
-`invalid_config` · `missing_api_key` · `unauthorized` · `forbidden` ·
-`not_found` · `rate_limited` · `validation_failed` · `network_error` ·
-`invalid_response` · `server_error` · `unknown`.
+```ts
+await neetru.db.add('orders', { customerId: 'usr_x', total: 9990 });
+const orders = await neetru.db.list('orders', {
+  where: [['customerId', '==', 'usr_x']],
+  orderBy: 'createdAt',
+  limit: 50,
+});
+```
 
-## Subpath imports (tree-shaking)
+### Checkout
 
 ```ts
-// Importa só o tipo de erro (zero deps de transport)
-import { NeetruError } from '@neetru/sdk/errors';
-
-// Bundlers podem fazer code-split por namespace
-import { createCatalogNamespace } from '@neetru/sdk/catalog';
+const intent = await neetru.checkout.start({
+  productId: 'gestovendas',
+  planId: 'pro',
+  tenantType: 'company',
+  tenantId: 'company_xyz',
+});
+window.location.href = intent.checkoutUrl;
 ```
 
-## Build
+## Modo dev (mocks automáticos)
 
-```bash
-npm run build   # tsup → dist/{index,catalog,entitlements,telemetry,errors}.{mjs,cjs,d.ts}
-npm run dev     # watch mode
-npm run lint    # tsc --noEmit
-npm run test    # vitest run (Sprint 2+)
+```ts
+const neetru = createNeetruClient({ env: 'dev' });
+// auth retorna DEV_FIXTURE_USER, usage/db/webhooks/notifications são in-memory
 ```
 
-Tooling: [tsup](https://tsup.egoist.dev) (esbuild backend, dual ESM+CJS,
-auto `.d.ts`).
+Override pra testes determinísticos:
 
-## Migration v0.3 → v1.0
-
-**Sem breaking changes.** Upgrade direto via `npm install @neetru/sdk@1.0.0`.
+```ts
+import { MockAuth, MockUsage } from '@neetru/sdk';
 
-- `initNeetru` continua deprecated mas funcional. **Será removido em v2.0.0.**
-  Use `createNeetruClient` em código novo.
-- `NeetruConfig` continua deprecated — use `NeetruClientConfig`.
-- Tipos exportados continuam idênticos.
-- Comportamento runtime idêntico — apenas estabilização de contratos.
+const neetru = createNeetruClient({
+  apiKey: 'nrt_test',
+  env: 'prod',
+  mocks: {
+    auth: new MockAuth({ user: { uid: 'test', email: 'a@b' } }),
+    usage: new MockUsage(),
+  },
+});
+```
 
-## Stability promise (v1.x)
+## Versionamento
 
-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.
+- **SemVer estrito** — breaking changes só em major.
+- v1.0 GA (2026-05-06) — superfície estável de 7 namespaces
+- v1.1 (2026-05) — checkout namespace
+- v1.2 (2026-05) — webhooks + notifications namespaces
 
-## Generate API docs
+`initNeetru` (API v0.0.1) está deprecated desde v0.2 — funciona até v2.0.
 
-```bash
-npm install --include=dev    # garante typedoc
-npm run docs:gen             # → sdk/docs-html/index.html
-```
+## Stack
 
-## Roadmap
+- TypeScript 5 ESM-first
+- Zero dependências runtime (usa `fetch` global)
+- Bundle minzip <10KB (todos namespaces somados, tree-shake-friendly)
 
-- ✅ **v1.0** — API stability + GA. JSDoc completo + typedoc.
-- **v1.1** — Telemetry batching + flush on unload.
-- **v1.2** — LRU cache em entitlements.check (TTL configurável).
-- **v1.x** — CDN release (`cdn.neetru.com/sdk/v1/`), SRI integrity.json,
-  UMD/IIFE bundle.
+## Mais info
 
-Detalhes em
-[`docs/PLAN_SDK_NEETRU.md`](../docs/PLAN_SDK_NEETRU.md) +
-[`docs/PLAN_SDK_CLI_CDN.md`](../docs/PLAN_SDK_CLI_CDN.md).
+- **Repo:** [github.com/Neetru/neetru-core](https://github.com/Neetru/neetru-core)
+- **CLI complementar:** `npm install -g @neetru/cli`
 
-## License
+## Licença
 
-UNLICENSED — uso interno Neetru. License pública será definida em release
-público (npm publish).
+MIT © Neetru