@neetru/sdk 1.1.1 → 2.1.0

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).
-
-> **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).
+# @neetru/sdk
+
+> Biblioteca runtime oficial pra consumir o ecossistema Neetru a partir de produtos SaaS (Next.js, Node, 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="license" src="https://img.shields.io/badge/license-MIT-22c55e">
+</p>
+
+## Instalação
+
+```bash
+npm install @neetru/sdk
+```
+
+## Hello world
+
+```ts
+import { createNeetruClient } from '@neetru/sdk';
+
+const neetru = createNeetruClient({
+  apiKey: process.env.NEETRU_API_KEY,    // nrt_<keyId>_<secret>
+  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 */ }
+```
+
+## 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.
+- **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) |
+
+## Exemplos por namespace
+
+### Webhooks outbound (v1.2)
+
+```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',
+});
+
+const endpoints = await neetru.webhooks.list();
+const test = await neetru.webhooks.test(endpoints[0].id);
+console.log(test.statusCode, test.durationMs);
+```
+
+Eventos recebidos no seu endpoint chegam com:
+- `X-Neetru-Signature: sha256=<hmac>` (se `secret` registrado)
+- `X-Neetru-Timestamp: <ms>` (replay protection — rejeitar > 5min skew)
+
+### Notifications produto → user (v1.2)
+
+```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
+});
+
+const notifs = await neetru.notifications.list('usr_xyz', { onlyUnread: true });
+await neetru.notifications.markRead(notifs[0].id);
+```
+
+### Entitlements
+
+```ts
+const ok = await neetru.entitlements.check('gestovendas', 'ai_recommendations');
+const detailed = await neetru.entitlements.detailed('gestovendas', 'ai_recommendations');
+// → { allowed, planId, remaining?, limit?, reason }
+```
+
+### Usage tracking
+
+```ts
+await neetru.usage.track('report_generated', { count: 42, format: 'pdf' });
+
+const quota = await neetru.usage.getQuota('reports_per_month');
+// → { used: 15, limit: 100, resetsAt: '...', plan: 'starter' }
+```
+
+### Support
+
+```ts
+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' });
+```
+
+### DB (tenant-scoped, vendor-neutral)
+
+```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,
+});
+```
+
+### Checkout
+
+```ts
+const intent = await neetru.checkout.start({
+  productId: 'gestovendas',
+  planId: 'pro',
+  tenantType: 'company',
+  tenantId: 'company_xyz',
+});
+window.location.href = intent.checkoutUrl;
+```
+
+## Modo dev (mocks automáticos)
+
+```ts
+const neetru = createNeetruClient({ env: 'dev' });
+// auth retorna DEV_FIXTURE_USER, usage/db/webhooks/notifications são in-memory
+```
+
+Override pra testes determinísticos:
+
+```ts
+import { MockAuth, MockUsage } from '@neetru/sdk';
+
+const neetru = createNeetruClient({
+  apiKey: 'nrt_test',
+  env: 'prod',
+  mocks: {
+    auth: new MockAuth({ user: { uid: 'test', email: 'a@b' } }),
+    usage: new MockUsage(),
+  },
+});
+```
+
+## Versionamento
+
+- **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
+
+`initNeetru` (API v0.0.1) está deprecated desde v0.2 — funciona até v2.0.
+
+## Stack
+
+- TypeScript 5 ESM-first
+- Zero dependências runtime (usa `fetch` global)
+- Bundle minzip <10KB (todos namespaces somados, tree-shake-friendly)
+
+## Mais info
+
+- **Repo:** [github.com/Neetru/neetru-core](https://github.com/Neetru/neetru-core)
+- **CLI complementar:** `npm install -g @neetru/cli`
+
+## Licença
+
+MIT © Neetru