@neetru/sdk 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,183 @@
+# 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.0)
+- Telemetry batching + flush on unload.
+- LRU cache em entitlements.check (TTL configurável).
+- size-limit budget no CI (<12KB gz core com db namespace).
+- CDN distribution (`cdn.neetru.com/sdk/v1/`).
+
+## [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.

package/README.md

@@ -0,0 +1,218 @@
+# @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).
+
+> **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).
+
+---
+
+## 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
+
+```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
+
+```ts
+import { createNeetruClient, NeetruError } 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
+});
+
+// 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();
+
+// 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);
+  }
+}
+```
+
+## API reference (v0.2)
+
+### `createNeetruClient(config?)`
+
+| 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. |
+
+Retorna `NeetruClient` com `.config`, `.auth`, `.catalog`, `.entitlements`, `.telemetry`, `.usage`, `.support`.
+
+### `client.auth` (v0.2)
+
+| 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. |
+
+### `client.catalog`
+
+| 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`. |
+
+### `client.entitlements`
+
+| Método | Descrição |
+|---|---|
+| `check(slug, feature)` | `boolean`. Atalho do `checkDetailed`. |
+| `checkDetailed(slug, feature)` | `EntitlementCheck` com `allowed`, `reason`. |
+
+### `client.telemetry`
+
+| Método | Descrição |
+|---|---|
+| `event({ name, properties?, timestamp? })` | `POST /api/v1/sdk/telemetry/event`. Retorna `{ ok, eventId }`. |
+
+### `client.usage` (v0.2)
+
+| 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? }`. |
+
+### `client.support` (v0.2)
+
+| Método | Descrição |
+|---|---|
+| `createTicket({subject, message, severity?, productSlug?})` | `POST /api/v1/products/{slug}/tickets`. |
+| `listMyTickets()` | `GET /api/v1/products/_default/tickets`. |
+
+### Mocks (`@neetru/sdk/mocks`)
+
+Use em tests do consumer ou ative globalmente com `NEETRU_ENV=dev`:
+
+```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(),
+  },
+});
+```
+
+### Códigos de erro estáveis (`NeetruError.code`)
+
+`invalid_config` · `missing_api_key` · `unauthorized` · `forbidden` ·
+`not_found` · `rate_limited` · `validation_failed` · `network_error` ·
+`invalid_response` · `server_error` · `unknown`.
+
+## Subpath imports (tree-shaking)
+
+```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';
+```
+
+## Build
+
+```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+)
+```
+
+Tooling: [tsup](https://tsup.egoist.dev) (esbuild backend, dual ESM+CJS,
+auto `.d.ts`).
+
+## 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.**
+  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.
+
+## 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.
+
+## Generate API docs
+
+```bash
+npm install --include=dev    # garante typedoc
+npm run docs:gen             # → sdk/docs-html/index.html
+```
+
+## Roadmap
+
+- ✅ **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.
+
+Detalhes em
+[`docs/PLAN_SDK_NEETRU.md`](../docs/PLAN_SDK_NEETRU.md) +
+[`docs/PLAN_SDK_CLI_CDN.md`](../docs/PLAN_SDK_CLI_CDN.md).
+
+## License
+
+UNLICENSED — uso interno Neetru. License pública será definida em release
+público (npm publish).