@neetru/sdk 2.3.6 → 3.0.1

package/CHANGELOG.md

@@ -5,6 +5,191 @@ 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).
 
+## [3.0.1] - 2026-05-29 — **fix: sincronizar VERSION + docstrings + contract-staging códigos de erro**
+
+### Fixed
+
+- `src/index.ts` — `VERSION` constante sincronizada com `package.json` (`'3.0.0'` → `'3.0.1'`). Consumers que fazem `import { VERSION } from '@neetru/sdk'` recebiam `'3.0.0'` enquanto `npm list` mostrava `3.0.1` (LOW-NEW-SDK-01).
+- `src/telemetry.ts` — JSDoc na linha 6 corrigido: path legacy `/api/v1/sdk/telemetry/event` → canônico `/api/sdk/v1/telemetry/event`. O código sempre usou o path correto; apenas a documentação estava stale (LOW-NEW-SDK-02).
+- `src/__tests__/telemetry.test.ts` — comentário de cabeçalho atualizado para não dizer "(legado)" (LOW-NEW-SDK-02).
+- `src/__tests__/contract-staging.test.ts` — `'http_error'` removido de todos os arrays `toContain`. `NeetruErrorCode` não inclui `'http_error'`; respostas HTTP não mapeáveis caem em `'unknown'`. Substituído por `'unknown'` em todos os 7 sites (LOW-NEW-SDK-03).
+
+### Nota
+
+Este patch corresponde ao commit `4c40f01` (inline realtime-protocol types) que não atualizou `VERSION` nem o CHANGELOG.
+
+## [3.0.0] - 2026-05-27 — **MAJOR: contract hardening + Universal runtime + paths canonical**
+
+> Major rewrite resolvendo 5 CRITICAL + 6 HIGH do review `CHEFE_SDK_REVIEW_2026-05-27`.
+> SDK 2.3.6 estava com **4 dos 11 namespaces broken** contra Core LIVE (`usage`, `webhooks`, `notifications`, `support`) — 13 endpoints batendo 404/400. Tests passavam validando contrato errado (mock fetch aceita qualquer URL).
+>
+> **Justificativa do MAJOR**: paths/body shapes mudaram em 4 namespaces; 2 métodos removidos (`usage.track`, `usage.getQuota`); `verifyWebhookSignature` virou async. Toda CLI release/SaaS inaugural depende disso primeiro.
+
+### BREAKING CHANGES
+
+#### 1. `usage` namespace 100% rewrite (CRITICAL-SDK-01)
+
+- **REMOVIDO** `usage.track(event, props)` — Core não aceitava esse shape; era vaporware testado contra mock. Use `usage.report(resource, qty, opts)`.
+- **REMOVIDO** `usage.getQuota(metric)` — endpoint `/usage/quota` nunca existiu no Core. `usage.report()` devolve `{value, limit, remaining}` inline em todo POST.
+- Paths corrigidos:
+  - `/sdk/v1/usage/record` → `/api/sdk/v1/usage/record` (canonical)
+  - `/sdk/v1/entitlements` → `/api/sdk/v1/entitlements` (canonical)
+- `usage.report()` agora envia `Idempotency-Key: <uuid v4>` header automaticamente.
+- `usage.check()` retorna novo field `behavior: "readonly" | null` (inferido de `reason === "limit_exceeded"`).
+
+#### 2. `webhooks` namespace — `productId` obrigatório (CRITICAL-SDK-03)
+
+- `RegisterWebhookInput.productId` adicionado. Default resolve do `config.productId`; lança `validation_failed` se ambos ausentes.
+- `list(options?)`, `unregister(id, options?)`, `test(id, options?)` agora aceitam `{ productId }` (Core exige query param em todos os verbos).
+- `webhooks.test()` envia `Idempotency-Key` header.
+
+#### 3. `notifications` namespace — `productId` obrigatório (CRITICAL-SDK-04)
+
+- `SendNotificationInput.productId` adicionado (Core valida via Zod `SendNotificationSchema`).
+- `ListNotificationsOptions.productId` adicionado.
+- `NotificationScopeOptions` novo type para `markRead`/`dismiss`.
+- `notifications.send()` envia `Idempotency-Key` header.
+
+#### 4. `support` namespace — endpoint canonical (CRITICAL-SDK-02)
+
+- Endpoint mudou de `/api/v1/products/{slug}/tickets` (vaporware — **nunca existiu no Core**) para `/api/sdk/v1/support/tickets` (canonical SDK path).
+- `productId` obrigatório (default `config.productId`).
+- `createTicket()` envia `Idempotency-Key` header.
+- `listMyTickets(options?)` aceita `{ productSlug }` override.
+- **Pré-requisito Core**: endpoint `/api/sdk/v1/support/tickets` precisa ser construído (vide `docs/CORE_CHANGES_REQUIRED.md` §1).
+
+#### 5. `verifyWebhookSignature` é async + Universal (HIGH-SDK-03)
+
+- **Antes (2.x)**: `(payload, sig, secret) => boolean` — usava `require('node:crypto')` que quebrava em bundle browser/Edge ESM puro. README anunciava "Universal" mas mentia.
+- **Agora (3.0)**: `(payload, sig, secret) => Promise<boolean>` via `WebCrypto.subtle.sign` HMAC-SHA-256 + constant-time XOR compare.
+- Funciona em Node ≥20, browsers modernos, Vercel Edge Functions, Cloudflare Workers.
+- Lança `NeetruError('runtime_unsupported')` se WebCrypto ausente (distingue "ambiente não suporta" de "assinatura inválida").
+
+#### 6. `telemetry.event` / `telemetry.track` path canonical (CRITICAL-SDK-05)
+
+- `POST /api/v1/sdk/telemetry/event` → `POST /api/sdk/v1/telemetry/event` (canonical SDK pattern).
+- Pré-requisito Core: alias/handler para o canonical path (vide `docs/CORE_CHANGES_REQUIRED.md` §3).
+
+#### 7. `baseUrl` allowlist fail-closed (HIGH-SDK-05)
+
+- `createNeetruClient` agora chama `validateBaseUrl` antes de aceitar `config.baseUrl`.
+- Allowlist padrão: HTTPS `*.neetru.com` + `localhost`/`127.0.0.1`/`*.test`/`*.localhost`.
+- `NeetruClientConfig.allowedHosts: string[]` novo — adicione hosts custom (suffix match).
+- Bypass: `NEETRU_ALLOW_INSECURE_BASEURL=1` (env) ou `globalThis.NEETRU_ALLOW_INSECURE_BASEURL='1'`. Warning no console quando ativo.
+- Cenário ataque fechado: dev configura `NEETRU_BASE_URL=http://attacker.example/` no `.env`, agora lança `invalid_config` em vez de vazar Bearer.
+
+#### 8. Retries default por método (HIGH-SDK-01)
+
+- **GET/HEAD**: 2 retries default (= 3 tentativas) — idempotente, seguro.
+- **POST/PUT/PATCH/DELETE**: **0 retries default** — mutations podem duplicar side effects (ex: `FieldValue.increment` no `usage/record`).
+- Caller pode override: `httpRequest(config, { method: 'POST', ..., retries: 2 })`.
+- Combinado com `Idempotency-Key` automático em mutations: dup-write rate → zero.
+
+#### 9. Cleanup de stubs deprecated
+
+- `initNeetru` (deprecated desde v0.2, no-op em v2.0) **definitivamente removido**.
+- `NeetruConfig` type alias **removido** (use `NeetruClientConfig`).
+
+#### 10. `NeetruErrorCode` ganhou `runtime_unsupported`
+
+- Lançado por `verifyWebhookSignature` quando WebCrypto ausente. Não é breaking se você usa só `instanceof NeetruError`; é breaking se você fez `switch` no union type (TS error em case missing).
+
+### ADDED
+
+- `src/idempotency.ts` — `generateIdempotencyKey()` via `crypto.randomUUID()` (Node ≥20, browsers, Edge).
+- `src/base-url-allowlist.ts` — `validateBaseUrl(url, allowedHosts)` fail-closed.
+- `HttpRequestOptions.idempotencyKey: boolean | string` — injeta header automaticamente em todo POST de mutation.
+- `client.usage.check().behavior: 'readonly' | null` — sinal para `<EntitlementGate mode='readonly'>` decidir UI.
+- `NeetruClientConfig.allowedHosts` — extension point para hosts custom (staging/proxies).
+- `MockUsage.__getReports()` substitui `__getRecords()` (legacy alias mantido).
+- Test suite: `src/__tests__/base-url-allowlist.test.ts` (16 tests), `src/__tests__/idempotency.test.ts` (9 tests).
+- `docs/CORE_CHANGES_REQUIRED.md` — catálogo de 5 endpoints Core a criar/modificar para 3.0 funcionar end-to-end.
+
+### FIXED
+
+- `<EntitlementGate>` v1.1 não morre mais em silent `allowed:false` — paths corrigidos no `usage.check` (era dependência transitiva, fixed via CRITICAL-SDK-01).
+- README v2.x prometia "Universal: browser/Node/Edge" mas `verifyWebhookSignature` só funcionava em Node. 3.0 cumpre.
+
+### Migration guide v2.x → v3.0
+
+```ts
+// ❌ Antes (v2.x)
+await client.usage.track('api_call', { route: '/x' });
+const quota = await client.usage.getQuota('api_calls');
+
+await client.webhooks.register({
+  url: 'https://x.com/h',
+  events: ['subscription.activated'],
+});
+
+await client.notifications.send({
+  userId: 'u1',
+  kind: 'order.received',
+  title: 'Pedido',
+});
+
+await client.support.createTicket({
+  subject: 'help',
+  message: 'x',
+});
+
+// ✅ Depois (v3.0)
+const client = createNeetruClient({
+  apiKey: 'nrt_...',
+  productId: 'gestovendas',  // 🆕 default p/ todos os namespaces
+  tenantId: 't-acme',         // 🆕 default p/ usage
+});
+
+const result = await client.usage.report('api_call', 1);
+// result.value, result.limit, result.remaining inline — não precisa getQuota separado.
+
+const allowed = await client.usage.check('api_call');
+// allowed.behavior === 'readonly' quando over limit (use em <EntitlementGate>)
+
+await client.webhooks.register({
+  // productId default config.productId, ou explícito:
+  url: 'https://x.com/h',
+  events: ['subscription.activated'],
+});
+
+await client.notifications.send({
+  userId: 'u1',
+  kind: 'order.received',
+  title: 'Pedido',
+});
+
+await client.support.createTicket({
+  subject: 'help',
+  message: 'x',
+});
+```
+
+### Verificação de assinatura de webhook — agora async
+
+```ts
+// ❌ Antes (v2.x) — sync, quebrava em Edge
+import { verifyWebhookSignature } from '@neetru/sdk/webhooks';
+const ok = verifyWebhookSignature(rawPayload, sigHeader, secret);
+
+// ✅ Depois (v3.0) — async, Universal
+const ok = await verifyWebhookSignature(rawPayload, sigHeader, secret);
+```
+
+### Endpoints Core que precisam ser criados/modificados antes do publish 3.0
+
+Vide `docs/CORE_CHANGES_REQUIRED.md` completo:
+
+1. **CRITICAL** — `POST/GET /api/sdk/v1/support/tickets` (customer-facing) — 3-4h.
+2. **HIGH** — Idempotency-Key dedup em endpoints de mutation — 4-6h.
+3. **HIGH** — `POST /api/sdk/v1/telemetry/event` (canonical) — 1-2h ou alias middleware.
+4. **LOW** — `behavior` field em `/api/sdk/v1/entitlements` response — 30min.
+5. **LOW** — Verificar envelope `/api/sdk/v1/datastore/{collection}` — 30min check.
+
+### Tests
+
+- **719 tests passing** (era 668 em 2.3.6). Tsc clean. Build clean.
+- Contract tests reescritos para validar paths canonical + body shapes + headers (Idempotency-Key UUID v4 regex match).
+
 ## [2.3.6] - 2026-05-26 — **fix(bundle): webpackIgnore em TODOS os dynamic imports node-only — bug_168368ae [CRITICAL]**
 
 ### Corrigido

package/README.md

@@ -1,62 +1,79 @@
 # @neetru/sdk
 
-> Biblioteca runtime oficial pra consumir o ecossistema Neetru a partir de produtos SaaS (Next.js, Node, browser, Edge runtimes).
+> Biblioteca runtime oficial pra consumir o ecossistema Neetru a partir de produtos SaaS (Next.js, Node ≥20, browser, Edge runtimes).
 
 <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="Node" src="https://img.shields.io/badge/node-%3E%3D20-339933?logo=node.js&logoColor=white">
   <img alt="license" src="https://img.shields.io/badge/license-MIT-22c55e">
 </p>
 
+> ## ⚠ 3.0 é breaking — leia o [CHANGELOG](./CHANGELOG.md) antes de upgrade
+>
+> SDK 2.x estava com 4 namespaces broken contra Core LIVE. 3.0 corrige paths canonical, exige `productId` em mutations, adiciona `Idempotency-Key` automático, `baseUrl` allowlist fail-closed, e `verifyWebhookSignature` virou Universal async via WebCrypto.
+>
+> **Métodos removidos**: `usage.track`, `usage.getQuota` (use `usage.report` / `usage.check`).
+>
+> **Migration guide completo no CHANGELOG.md**.
+
 ## Instalação
 
 ```bash
 npm install @neetru/sdk
 ```
 
-## Hello world
+## Hello world (3.0)
 
 ```ts
 import { createNeetruClient } from '@neetru/sdk';
 
 const neetru = createNeetruClient({
   apiKey: process.env.NEETRU_API_KEY,    // nrt_<keyId>_<secret>
+  productId: 'gestovendas',              // 3.0: default p/ todos namespaces
+  tenantId: 't-acme',                    // 3.0: default p/ usage
   env: 'prod',                           // 'dev' = mocks in-memory
 });
 
 // Auth
 const user = await neetru.auth.signIn();
-console.log('logado como:', user?.email);
 
-// Entitlement check
-const canAi = await neetru.entitlements.check('gestovendas', 'ai_recommendations');
-if (canAi) { /* mostrar feature */ }
+// Meter consumo (canonical /api/sdk/v1/usage/record)
+const r = await neetru.usage.report('api_call', 1);
+console.log(r.value, '/', r.limit, '— restam', r.remaining);
+
+// Entitlement check com behavior=readonly
+const check = await neetru.usage.check('api_call');
+if (!check.allowed && check.behavior === 'readonly') {
+  // UI degradada — read-only sem quebrar engajamento
+}
 ```
 
 ## Princípios
 
 - **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.
+- **Universal** — browser, Node ≥20, Edge runtimes (Vercel Edge, Cloudflare Workers). Usa `fetch` global + WebCrypto.
+- **Fail-closed segurança** — `baseUrl` allowlist (`*.neetru.com` + localhost) rejeita phishing/MITM. Bypass: `NEETRU_ALLOW_INSECURE_BASEURL=1`.
+- **Idempotency-Key automático** — mutations (`usage.report`, `webhooks.test`, `notifications.send`, `support.createTicket`) injetam UUID v4 header. `retries: 0` default em POSTs para defesa em camada.
 - **Tipado** — erros via `NeetruError` com `.code`, `.status`, `.requestId`.
 - **Dev mode** — `NEETRU_ENV=dev` ativa mocks automáticos — zero rede em testes locais.
 
-## Namespaces v1.2
-
-| 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) |
+## Namespaces 3.0
+
+| Namespace | O que oferece | Endpoint |
+|---|---|---|
+| `auth` | OIDC sign-in/out + verifyToken | `auth.neetru.com/api/v1/oauth/*` |
+| `catalog` | Produtos públicos (`list` / `get`) | `/api/sdk/v1/catalog` |
+| `entitlements` | Verificação boolean simples (legacy compat) | `/api/v1/sdk/entitlements/check` |
+| `telemetry` | `event(...)` + `track(...)` + `log(...)` | `/api/sdk/v1/telemetry/{event,log}` |
+| `usage` | `report` / `check` (metering + entitlement full) | `/api/sdk/v1/usage/record`, `/api/sdk/v1/entitlements` |
+| `support` | `createTicket` / `listMyTickets` | `/api/sdk/v1/support/tickets` ⭐ 3.0 |
+| `db` | Coleções tenant-scoped (offline-first v2.0) | `/api/sdk/v1/datastore/*` |
+| `checkout` | Stripe Checkout intent | `/api/v1/checkout/intents` |
+| `webhooks` | Produtos registram URL pra receber eventos | `/api/sdk/v1/webhooks` |
+| `notifications` | Produto envia notification in-app | `/api/sdk/v1/notifications` |
 
 ## Exemplos por namespace
 
@@ -78,6 +95,26 @@ Eventos recebidos no seu endpoint chegam com:
 - `X-Neetru-Signature: sha256=<hmac>` (se `secret` registrado)
 - `X-Neetru-Timestamp: <ms>` (replay protection — rejeitar > 5min skew)
 
+#### Verificar assinatura no consumer (3.0 — async + Universal)
+
+```ts
+import { verifyWebhookSignature } from '@neetru/sdk';
+
+// Next.js Route Handler (Edge OU Node runtime — funciona em ambos)
+export async function POST(req: Request) {
+  const raw = await req.text();
+  const sig = req.headers.get('X-Neetru-Signature');
+  const ok = await verifyWebhookSignature(raw, sig, process.env.NEETRU_WEBHOOK_SECRET!);
+  if (!ok) return new Response('unauthorized', { status: 401 });
+
+  const event = JSON.parse(raw);
+  // ... handle event
+  return Response.json({ ok: true });
+}
+```
+
+> **Breaking 3.0**: era `boolean` sync usando `node:crypto`. Agora `Promise<boolean>` via WebCrypto.subtle — funciona em Cloudflare Workers, Vercel Edge, browsers e Node ≥20.
+
 ### Notifications produto → user (v1.2)
 
 ```ts
@@ -184,6 +221,31 @@ const neetru = createNeetruClient({
 - Zero dependências runtime (usa `fetch` global)
 - Bundle minzip <10KB (todos namespaces somados, tree-shake-friendly)
 
+## Testes de contrato (staging)
+
+O arquivo `src/__tests__/contract-staging.test.ts` contém testes que exercitam o HTTP real contra um ambiente de staging. Por default, todos os testes são skippados quando `NEETRU_STAGING_URL` não estiver definido.
+
+Para rodar:
+
+```bash
+NEETRU_STAGING_URL=https://api.staging.neetru.com \
+NEETRU_STAGING_API_KEY=nrt_<keyId>_<secret> \
+npx vitest run src/__tests__/contract-staging.test.ts
+```
+
+Variáveis de ambiente:
+
+| Variável | Obrigatória | Descrição |
+|---|---|---|
+| `NEETRU_STAGING_URL` | Sim | URL base da API de staging |
+| `NEETRU_STAGING_API_KEY` | Sim | API key no formato `nrt_<keyId>_<secret>` |
+| `NEETRU_STAGING_PRODUCT_ID` | Não | productId cadastrado no staging (default: `gestovendas`) |
+| `NEETRU_STAGING_TENANT_ID` | Não | tenantId válido no staging (default: `t-acme`) |
+
+Namespaces cobertos: `catalog.list`, `catalog.get`, `entitlements.check`, `entitlements.checkDetailed`, `usage.report`, `usage.check`, `telemetry.event`, `telemetry.log`, `auth.getUser`, `auth.signIn`.
+
+Os testes assertam apenas o shape/tipos da resposta, nunca valores exatos — staging pode ter dados variáveis mas o contrato de formato deve ser estável.
+
 ## Mais info
 
 - **Repo:** [github.com/Neetru/neetru-core](https://github.com/Neetru/neetru-core)