Pulse

SDK Pulse

SDKs de análise de código aberto para web, React Native, iOS e Android. Adicione análise ao seu aplicativo com uma fila de eventos confiável e offline-first e identidade limpa — e nada mais.

• Minúsculo. O SDK web tem ≤ 10 KB gzip com zero dependências.
• Confiável. Uma fila persistente e ordenada sobrevive a períodos offline e à morte do processo. A entrega é idempotente: novas tentativas nunca duplicam eventos.
• Honesto sobre privacidade. Sem captura automática, sem fingerprinting, sem IDFA/GAID, sem SDKs de anúncios. O SDK envia apenas os eventos que você envia a ele.
• Um protocolo, quatro plataformas. Cada SDK implementa o mesmo protocolo de rede e passa nos mesmos fixtures de conformidade no CI. O servidor de ingestão do Pulse reproduz esses mesmos fixtures — o contrato é verificado de ambas as extremidades.

Este repositório contém os pacotes TypeScript. Os SDKs Swift e Kotlin estão em pulse-sdk-native.

Para agentes de IA

Instale: npm i @pulse-circle/web, depois Pulse.init('pk_...') e Pulse.track('event', {...}). O pacote é autocontido (zero dependências, endpoint padrão embutido) e inclui llms.txt dentro dele. A instalação requer apenas npm; a entrega de eventos acontece no navegador do usuário final em tempo de execução.

Pacotes

Pacote	Para que serve	Instalação
@pulse-circle/web	Navegador / qualquer aplicativo web	npm i @pulse-circle/web
@pulse-circle/react-native	React Native e Expo	npm i @pulse-circle/react-native
@pulse-circle/core	Motor agnóstico de plataforma (usado pelos acima)	npm i @pulse-circle/core
@pulse-circle/mcp	Servidor MCP local (stdio) — guias de configuração/conexão offline para agentes de IA	claude mcp add pulse -- npx -y @pulse-circle/mcp

Início rápido (web)

npm install @pulse-circle/web

import { Pulse } from '@pulse-circle/web';

Pulse.init('pk_your_api_key');

// Track product events — the SDK batches, persists, and retries for you.
Pulse.track('subscription_started', { plan: 'pro' });

// Tie events to a user after login.
Pulse.identify('user_42');

// On logout, start a fresh anonymous identity.
Pulse.reset();

Essa é toda a API. Consulte o README de cada pacote para a instalação específica da plataforma (tag de script, Expo, etc.) e a referência completa.

A API, em todos os lugares

Os cinco métodos são idênticos em todas as quatro plataformas, na sintaxe idiomática de cada linguagem:

init(apiKey, options?)      // configure once
track(event, properties?)   // queue an event
identify(userId)            // associate the current identity with a user id
reset()                     // logout: new anonymous identity
flush()                     // force-send the queue (tests, critical moments)

Não há deliberadamente rastreamento automático de tela/página e nenhum método de receita: a receita vem de conectores do lado do servidor, então há exatamente uma fonte de verdade por número.

O contrato de confiabilidade

• Cada evento recebe um idempotency_key e um timestamp no momento em que você chama track — nunca no momento do envio. As novas tentativas reenviam ambos byte-idênticos, e a chave primária do servidor inclui ambos, então uma rede instável nunca pode criar uma duplicata.
• A fila é persistente (localStorage na web, arquivos no celular) e ordenada. Ela sobrevive a recarregamentos, travamentos e períodos offline até um limite por plataforma, então remove os mais antigos primeiro com um aviso de depuração em vez de crescer sem limites.
• As novas tentativas usam backoff exponencial com jitter. Um lote que o servidor continua rejeitando (um lote "venenoso") é movido para o lado após 10 tentativas para que nunca possa bloquear tudo atrás dele.

Os detalhes normativos estão em protocol/PROTOCOL.md.

Desenvolvimento

npm install
npm test          # conformance fixtures + unit tests (vitest)
npm run lint
npm run typecheck
npm run build     # tsup builds for every package
npm run size -w @pulse-circle/web   # enforce the 10 KB budget

Fixtures de conformidade

protocol/fixtures é a fonte da verdade para o comportamento entre plataformas. Cada arquivo JSON é um cenário ("essas chamadas de API produzem essas solicitações HTTP"); cada SDK os executa por meio de um executor de fixtures compartilhado, e o servidor os reproduz contra a ingestão real. Mude o comportamento alterando um fixture, e o CI de cada plataforma informa quem está fora do contrato.

Lançamento

As versões são independentes por pacote. Aumente a versão no package.json do pacote e envie uma tag:

core-v0.1.0 | web-v0.1.0 | react-native-v0.1.0

O fluxo de publicação verifica se a tag corresponde a package.json, executa o teste completo + build + limite de tamanho, e publica no npm com proveniência.

Licença

MIT © Pulse Circle Studio