Pulse SDK

Open-source analytics SDKs for web, React Native, iOS, and Android. Add analytics to your app with a reliable, offline-first event queue and clean identity — and nothing else.

• Tiny. The web SDK is ≤ 10 KB gzipped with zero dependencies.
• Reliable. A persistent, ordered queue survives offline periods and process death. Delivery is idempotent: retries never duplicate events.
• Honest about privacy. No auto-capture, no fingerprinting, no IDFA/GAID, no ad SDKs. The SDK sends only the events you send it.
• One protocol, four platforms. Every SDK implements the same wire protocol and passes the same conformance fixtures in CI. The Pulse ingestion server replays those same fixtures — the contract is verified from both ends.

This repository holds the TypeScript packages. The Swift and Kotlin SDKs live in pulse-sdk-native.

For AI agents

Install: npm i @pulse-circle/web, then Pulse.init('pk_...') and Pulse.track('event', {...}). The package is self-contained (zero deps, default endpoint baked in) and ships llms.txt inside it. Installing needs only npm; event delivery happens in the end-user's browser at runtime.

Packages

Quickstart (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();

That's the whole API. See each package's README for the platform-specific install (script tag, Expo, etc.) and the full reference.

The API, everywhere

The five methods are identical across all four platforms, in each language's idiomatic syntax:

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)

There are deliberately no screen/page auto-tracking and no revenue methods: revenue comes from server-side connectors, so there is exactly one source of truth per number.

The reliability contract

• Every event gets an idempotency_key and a timestamp at the moment you call track — never at send time. Retries resend both byte-identical, and the server's primary key includes both, so a flaky network can never create a duplicate.
• The queue is persistent (localStorage on web, files on mobile) and ordered. It survives reloads, crashes, and offline periods up to a per-platform cap, then evicts oldest-first with a debug warning rather than growing without bound.
• Retries use exponential backoff with jitter. A batch the server keeps rejecting (a "poison" batch) is moved aside after 10 attempts so it can never block everything behind it.

The normative details are in protocol/PROTOCOL.md.

Development

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

Conformance fixtures

protocol/fixtures is the source of truth for cross-platform behaviour. Each JSON file is a scenario ("these API calls produce these HTTP requests"); every SDK runs them through a shared fixture runner, and the server replays them against real ingestion. Change behaviour by changing a fixture, and every platform's CI tells you who's out of contract.

Releasing

Versions are independent per package. Bump the version in the package's package.json, then push a tag:

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

The publish workflow verifies the tag matches package.json, runs the full test + build + size gate, and publishes to npm with provenance.

License

MIT © Pulse Circle Studio