@f0rbit/pulse-client

Lightweight beacon SDK (~1 KB minified+gzipped) for analytics and observability. Ships zero runtime dependencies.

Install

npm install @f0rbit/pulse-client
# or
bun add @f0rbit/pulse-client

Usage — Browser

<script src="https://cdn.jsdelivr.net/npm/@f0rbit/pulse-client/dist/index.mjs"></script>
<script>
  const pulse = window.createPulse({
    project_id: "your_project_id",
    ingest_key: "pk_your_key",
    endpoint: "https://pulse.f0rbit.dev",
    auto_pageview: true,
  });

  // Track custom events
  pulse.event("signup_completed", { plan: "pro" });

  // Manual pageview (if auto_pageview: false)
  pulse.pageview("/dashboard");

  // Flush remaining events
  await pulse.flush();
</script>

Usage — Server (Bun/Worker/Node 18+)

import { createPulse } from "@f0rbit/pulse-client";

const pulse = createPulse({
  project_id: "your_project_id",
  ingest_key: "pk_your_key",
  endpoint: "https://pulse.f0rbit.dev",
});

// Track events
pulse.event("user_login", { user_id: "123" });
pulse.pageview("/api/dashboard");

// Flush before shutdown
await pulse.flush();

API

createPulse(options): Pulse

Initialize a pulse client.

| Option | Type | Default | Notes | |--------|------|---------|-------| | project_id | string | required | Project identifier | | ingest_key | string | required | Public ingestion key (safe for browser) | | endpoint | string | required | Pulse API URL (e.g. https://pulse.f0rbit.dev) | | auto_pageview | boolean | true | Browser only — emit pageview on init and nav | | debug | boolean | false | Log SDK activity to console | | flush_interval_ms | number | 1000 | Batch flush interval (ms) | | flush_batch_size | number | 20 | Auto-flush when queue reaches N events | | before_send | function | — | Filter/modify events before send; return null to drop |

Pulse interface

type Pulse = {
  event(name: string, properties?: Record<string, unknown>): void;
  pageview(url?: string): void;
  flush(): Promise<void>;
};

• event(name, props) — Queue a custom event with optional properties
• pageview(url?) — Queue a pageview event (defaults to current location in browser)
• flush() — Flush all queued events immediately

Privacy

• No cookies — session IDs are server-derived and stateless
• No localStorage — no client-side persistent state
• No IP storage — IP is salted, hashed, and discarded after generating a daily session ID
• Public key only — ingest keys are disposable and rotation-friendly

See pulse.md for architecture details.