@neetru/sdk 1.2.0 → 2.1.0

package/README.md

@@ -1,194 +1,194 @@
-# @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
+# @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