SDK: Pulse

The Pulse client provides methods for tracking analytics events, batch ingestion, and generating reports.

Access it via client.pulse.

Events

List events

const events = await client.pulse.events.list();
// events: PulseEvent[]

Returns an array of PulseEvent objects:

interface PulseEvent {
  id: string;
  name: string;
  properties: Record<string, unknown>;
  timestamp: string;
}

Track a single event

const event = await client.pulse.events.track({
  name: "user.signup",
  properties: {
    plan: "pro",
    source: "landing-page",
  },
});

Batch ingest events

Send multiple events in a single request for better throughput:

const results = await client.pulse.events.batch([
  {
    name: "page.view",
    properties: { path: "/dashboard" },
  },
  {
    name: "page.view",
    properties: { path: "/settings" },
  },
  {
    name: "button.click",
    properties: { label: "Save", page: "/settings" },
  },
]);

Reports

Top events

Get a report of the most frequently tracked events:

const report = await client.pulse.reports.topEvents();
// report: TopEventsReport

The report includes event names ranked by count:

interface TopEventsReport {
  events: Array<{
    name: string;
    count: number;
  }>;
  total: number;
}

Full Example

import { createClient } from "@the-shift/sdk";

const client = createClient({
  gatewayUrl: "https://app.the-shift.dev",
  apiKey: process.env.SHIFT_API_KEY,
});

// Track user actions
await client.pulse.events.track({
  name: "feature.used",
  properties: {
    feature: "calendar-sync",
    userId: "user-123",
  },
});

// Batch ingest historical events
await client.pulse.events.batch([
  { name: "page.view", properties: { path: "/" } },
  { name: "page.view", properties: { path: "/calendar" } },
  { name: "booking.created", properties: { duration: 30 } },
  { name: "booking.created", properties: { duration: 60 } },
]);

// Generate a report
const report = await client.pulse.reports.topEvents();
for (const event of report.events) {
  console.log(`${event.name}: ${event.count} occurrences`);
}