@neetru/sdk 3.5.0 → 3.7.0

package/CHANGELOG.md

@@ -5,6 +5,77 @@ 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.7.0] - 2026-09-29 — **feat(support): identidade do usuário final (`X-Neetru-End-User-Token`) nos tickets**
+
+Release **minor** (capacidade nova; nenhuma API pública removida ou renomeada — ver "Mudança de comportamento" abaixo).
+
+### Contexto
+
+Auditoria das APIs públicas do Core (2026-09-29, HIGH-2): a chave `nrt_` do produto identifica o **produto**, não a pessoa — e roda no browser. Os tickets de suporte eram "possuídos" pelo dono da chave, igual pra todos os usuários finais, e `GET /api/sdk/v1/support/tickets` listava os tickets de **todo mundo** do produto (screenshots, console logs, URLs). Contrato final do Core (Neetru/neetru-core#513):
+
+- `X-Neetru-End-User-Token: <id_token>` (aceita também `Bearer <id_token>`), sempre junto do `Authorization` da chave do produto. **Só id_token**: token com `jti` (access token) → `401 invalid_end_user_token`.
+- **Obrigatório** em `GET /api/sdk/v1/support/tickets` (sem header → `403 end_user_token_required`) e nas mutações `/{id}/contest|satisfaction|satisfaction-attempt|resolved-seen`.
+- **Opcional** no `POST` de criação: com header o ticket fica amarrado ao `endUserId` (= `sub`); sem header nasce sem dono e **não aceita** contest/satisfaction.
+- id_token de client OIDC de **outro produto** → `403 end_user_token_product_mismatch`.
+- Token expirado / usuário inativo → `401 invalid_end_user_token`.
+- A listagem não traz mais `attachments`/`consoleLogs`: `screenshotUrl` vem `null` na lista e `screenshotAttached` diz se há print. `limit` padrão 20, máximo 50.
+
+**Dependência de deploy:** esta versão precisa estar publicada **junto/antes** do deploy do Core #513; senão a aba "Meus tickets" dos produtos (ex.: pdv) passa a receber 403.
+
+### Adicionado
+
+- `client.support.*` envia **automaticamente** `X-Neetru-End-User-Token` com o **id_token** do usuário logado (`client.auth.getIdToken()`, lido a cada chamada — nunca o access token). Login feito depois de criar o client já vale; `getIdToken` que lança é tratado como "sem usuário".
+- **Renovação automática 1x:** num `401 invalid_end_user_token`, o SDK chama `client.auth.refreshTokens()` (refresh_token rotation) UMA vez e repete a chamada com o id_token novo; se não renovar (ou falhar de novo), lança `NeetruAuthRequiredError`. Numa operação obrigatória sem id_token (expirado localmente), também tenta o refresh 1x antes de desistir.
+- `AuthNamespace.refreshTokens?(): Promise<boolean>` — agora exposto pelo auth OIDC web (já existia internamente e no `@neetru/sdk/mobile`). Opcional no tipo: mocks/implementações próprias podem omitir.
+- **`NeetruAuthRequiredError`** (exportado de `@neetru/sdk`, subclasse de `NeetruError`, `code: 'auth_required'`), com `reason`:
+  - `no_signed_in_user` — `listMyTickets`, `contestTicket`, `submitSatisfaction`, `recordSatisfactionAttempt` e `markResolvedSeen` **sem usuário logado** falham ANTES do request, com mensagem clara (em vez do 403 opaco do Core);
+  - `end_user_token_required` — o Core respondeu 403 exigindo a identidade;
+  - `invalid_end_user_token` — o Core recusou o token e o refresh não resolveu → refazer login.
+- `403 end_user_token_product_mismatch` → `NeetruError` com `code: 'forbidden'` e `reason: 'end_user_token_product_mismatch'`, mensagem explicando que o login é de outro produto (config: `oidcClientId` × `apiKey`/`productId`). Não tenta refresh.
+- `SupportTicket.screenshotAttached?: boolean` (da listagem do Core; fallback: há `screenshotUrl`). `listMyTickets({ limit })` — inteiro 1-50 (omitido = 20 do Core); fora disso `validation_failed` sem request.
+- Novos códigos em `NeetruErrorCode`: `auth_required` e `gone`.
+- **HTTP 410** (`statusToCode(410) === 'gone'`): mensagem útil ("endpoint removido do Core") + o substituto do header `X-Neetru-Replacement` — cobre o legado `/api/v1/sdk/entitlements/check`, que o Core agora responde 410. (O `client.entitlements.check()` do SDK já lançava localmente desde a 3.4.x; o 410 protege quem ainda chama a rota direto.)
+
+### Mudança de comportamento (ler antes de atualizar)
+
+- **Mutações de ticket exigem usuário logado no SDK.** `contestTicket`/`submitSatisfaction`/`recordSatisfactionAttempt`/`markResolvedSeen` sem id_token lançam `NeetruAuthRequiredError` sem chamar o Core. Quem chamava isso **server-side só com a chave do produto** (sem usuário final) passa a receber o erro.
+- **Tickets legados sem dono** (criados antes do corte de 2026-09-29, sem `endUserId`): o Core mantém a regra antiga pra eles (posse pela chave do produto) e ignora o header nesse caso — então **continuam mutáveis pelo SDK desde que haja QUALQUER usuário logado** no app (o id_token vai, o Core aplica a regra legada). Não há caminho no SDK pra mutá-los sem usuário logado.
+- **Tickets criados a partir de 2026-09-29 sem header** (sem dono) não aceitam contest/satisfaction no Core — pra o usuário acompanhar o ticket, crie-o com o usuário logado.
+- `listMyTickets()` passa a devolver `screenshotUrl: null` (a lista do Core não traz mais o anexo); use `screenshotAttached`.
+
+### Mantido (compatível)
+
+- `createTicket` **sem** usuário logado continua funcionando, sem o header e sem tentar refresh (fluxo de report anônimo / server-side).
+- Outros 403 (`forbidden_product`, `forbidden` de ticket de outro usuário) seguem como `NeetruError` comum.
+- `MockSupport` (env `dev`) mantém o comportamento (ganha `screenshotAttached`).
+
+### Também entra nesta versão (mesclado no #34, ainda não publicado)
+
+- Batch de quick-wins do Labs: bundle publicado minificado e sem sourcemap (~6x menor), `@deprecated` do namespace `entitlements` no index, e opt-in `deadlineMs` em `httpRequest` (orçamento total de tempo com retries).
+- **Corrigido junto (regressão do #34, nunca publicada):** o `minify: true` apagava os magic comments `/* webpackIgnore: true */` dos `import("pg")`/`import("drizzle-orm/node-postgres")` dinâmicos → o webpack/Next do produto voltaria a tentar empacotar `pg` no bundle do browser (bug_0f836014; o teste `no-node-deps-in-browser-bundle` falhava 4/13 com `dist/` presente, inclusive na `main`). Agora minifica identificadores+sintaxe sem apagar whitespace/comentários: dist ~2,1 MB (vs 1,5 MB full; 8,5 MB antes do #34).
+
+## [3.6.0] - 2026-09-24 — **feat(mobile): `@neetru/sdk/mobile` — namespace de auth OIDC+PKCE para React Native/Expo**
+
+Release **minor** (capacidade nova, aditiva — subpath novo, nenhuma API existente muda).
+
+### Contexto
+
+O namespace `auth` existente (`createNeetruClient(...).auth`) é hardcoded em três APIs que não existem em React Native: `globalThis.location.assign(url)` pra iniciar o redirect do `signIn`, e `sessionStorage`/`localStorage` pra persistir a transação PKCE e os tokens. Não havia seam de injeção pra nenhum dos três, então nenhum app RN conseguia usar login Neetru via o SDK — cada squad de app mobile reimplementaria PKCE do zero (risco de bug criptográfico duplicado).
+
+### Adicionado (aditivo, novo subpath — não muda nada em `.`/`./auth`)
+
+- **`@neetru/sdk/mobile`** — `createMobileAuthNamespace(config)`, com `config.storage` (`MobileAuthStorage` assíncrono — o app injeta `expo-secure-store`/Keychain/etc) e `config.openAuthUrl` (o app injeta `expo-web-browser`/`Linking.openURL` — **browser externo, nunca WebView embutida**, requisito de segurança RFC 8252 §8.12, documentado no JSDoc do módulo).
+- Namespace expõe `signIn(options)`, `completeSignIn(callbackUrl)` (recebe a URL do deep link explicitamente — mobile não tem `location.href` implícito), `getIdToken()`/`getUser()` (**assíncronos** — contrato diferente do `auth` web, porque `config.storage` é sempre `Promise`), `onAuthStateChanged(listener)`, `refreshTokens()`, `signOut()`.
+- **`src/auth-pkce-shared.ts`** (interno, não exportado publicamente) — a lógica criptográfica PKCE (WebCrypto, geração `state`/`nonce`/`code_verifier`/`code_challenge` S256, parsing/validação de `id_token`) foi extraída do `auth.ts` web pra ser reaproveitada 1:1 por `mobile.ts`, em vez de duplicada por copy-paste. `auth.ts` foi refatorado pra importar dali — comportamento idêntico, coberto pelos 78 testes pré-existentes de `client.auth`, que continuam verdes sem alteração.
+
+### Requisitos do app consumidor (documentados no JSDoc do módulo)
+
+- Polyfill de WebCrypto (`react-native-get-random-values` + `react-native-quick-crypto` ou equivalente) — Hermes não tem `crypto.subtle` nativo. Sem o polyfill, `signIn`/`completeSignIn` lançam `NeetruError('runtime_unsupported', ...)` com mensagem clara — o SDK não tenta poliflar sozinho nem gera PKCE fraco.
+- `config.openAuthUrl` deve abrir um browser externo (`ASWebAuthenticationSession`/Custom Tabs via `expo-web-browser`, ou `Linking.openURL`) — nunca uma WebView in-app.
+- `client.db` (offline-first, IndexedDB) **não tem storage persistente equivalente em React Native ainda** — cai no `MemoryStore` in-memory (não sobrevive a restart do app). Limitação conhecida e aceita de v1, não resolvida por este subpath.
+
+Nenhuma remoção de API, nenhuma mudança de wire nos namespaces existentes.
+
 ## [3.5.0] - 2026-09-19 — **feat(http): header `X-Neetru-Sdk-Version` em toda request**
 
 Release **minor** (capacidade nova, sem quebra de contrato existente).
@@ -28,7 +99,6 @@ Nenhuma remoção de API, nenhuma mudança de wire nos endpoints existentes —
 - **Remoção de código morto** — deletado `src/db.ts` legado (namespace v0.3.1 Sprint 8, sem nenhum import; o namespace `db` público vive em `src/db/client-db.ts`).
 - Doc: exemplo do JSDoc em `auth.ts` corrigido de `usage.track(...)` (API inexistente) para `usage.report(...)`.
 - Tooling: script `test:coverage` + devDeps `@testing-library/dom` e `@vitest/coverage-v8`.
-
 ## [3.4.7] - 2026-09-19 — **fix(a11y): NeetruLoginButton — foco de teclado visível (bug_62edcfb0)**
 
 Release **patch** (correção de bug de acessibilidade — publica o fix já mesclado no PR #28).