@neetru/sdk

Biblioteca runtime oficial pra consumir o ecossistema Neetru a partir de produtos SaaS (Next.js, Node, browser, Edge runtimes).

Instalação

npm install @neetru/sdk

Hello world

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)

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)

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

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

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

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)

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

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)

const neetru = createNeetruClient({ env: 'dev' });
// auth retorna DEV_FIXTURE_USER, usage/db/webhooks/notifications são in-memory

Override pra testes determinísticos:

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
• CLI complementar: npm install -g @neetru/cli

Licença

MIT © Neetru