# SDK Node e API

Envio server-side com chave privada.

## SDK no monorepo

O pacote @pulsant/sdk é local ao workspace e ainda não foi anunciado como publicado no npm. Adicione dependência workspace:* ao seu consumidor local ou use HTTP. Guarde a chave apenas no servidor. Ao registrar receita, amountMinor é o valor bruto confirmado em unidades mínimas; feeMinor é opcional e só deve ser enviado quando o próprio gateway confirmar a taxa, na mesma moeda e unidade.

```
import { Pulsant } from '@pulsant/sdk';
const pulsant = new Pulsant({ baseUrl: process.env.PULSANT_API_URL, key: process.env.PULSANT_SECRET_KEY, workspaceId: 'WORKSPACE', siteId: 'SITE' });
await pulsant.track({ id: 'signup_123456', name: 'signup', url: 'https://seusite.com/cadastro', sessionId: 'session_123456' });
```

## Registrar receita e taxa conhecida

amountMinor é o valor bruto confirmado em unidades mínimas. feeMinor é opcional e aceita zero ou um inteiro não negativo; envie somente quando o gateway declarar a taxa da transação. A Pulsant preserva essa taxa, mostra quantos pagamentos têm taxa conhecida e calcula o líquido desses pagamentos como bruto menos ajustes observados e taxa informada. Esse líquido é um cálculo parcial, não o saldo ou repasse do gateway. Omitir feeMinor mantém a taxa desconhecida; nunca envie uma estimativa.

```
await pulsant.revenue({
  externalId: 'pedido_123456',
  logicalId: 'pedido_123456',
  amountMinor: '12480',
  feeMinor: '85', // omita quando o provedor não confirmar a taxa
  currency: 'BRL',
  occurredAt: new Date().toISOString(),
  status: 'paid'
});
```

## Escopos e revogação

Crie uma chave com o menor escopo necessário. Eventos exigem analytics:write; consultas exigem analytics:read. O segredo só aparece na criação. Todas as chamadas verificam workspace, sites e permissões atuais do criador.


## Referência OpenAPI

A API em execução serve /openapi e /openapi.json. As rotas ausentes não devem ser presumidas. O guia MCP descreve seu contrato próprio; importação ainda depende de implementação.