DesperateAnalytics TypeScript SDK

TypeScript-first event client for Desperate analytics and notification thresholds.

Install

npm install pings-js-sdk

Configure

import { createAnalyticsClient } from "pings-js-sdk";

const analytics = createAnalyticsClient({
  apiKey: "ak_live_xxx",
  maxBatchSize: 25,
  notification: {
    title: "New product activity",
    body: "{project_name} reached {threshold_total} {event_name} events",
    soundName: "checkout_complete",
  },
});

By default the SDK uses the current hosted app URL: https://pings-chi.vercel.app/api/v1/events.

Override it with a base URL:

const analytics = createAnalyticsClient({
  apiKey: "ak_live_xxx",
  baseUrl: "https://your-production-app.com",
});

Or pass the full ingest route:

const analytics = createAnalyticsClient({
  apiKey: "ak_live_xxx",
  endpoint: "https://your-production-app.com/api/v1/events",
});

Track Events

await analytics.track("checkout_completed", {
  userAnonId: "user_123",
  sessionId: "session_abc",
  dedupeKey: "checkout_123",
  notificationTitle: "Checkout is heating up",
  notificationBody: "{project_name} reached {threshold_total} checkout events",
  soundName: "checkout_complete",
  properties: {
    plan: "pro",
    amount: 25,
    is_trial: false,
  },
});

await analytics.flush();

For deterministic tests, use sendBatch() with explicit dedupe keys:

await analytics.sendBatch([
  {
    event_name: "checkout_started",
    dedupe_key: "run-123-checkout-started-1",
    properties: { source: "integration-test" },
  },
]);

Generate Event Type Definitions

Users can create event types in the dashboard. To make TypeScript know those event names, run:

npx pings-js-sdk gen types \
  --api-key ak_live_xxx \
  --out src/desperate-event-types.d.ts

By default the generator reads from https://pings-chi.vercel.app. Override that with your own base URL or the full ingest route:

npx pings-js-sdk gen types \
  --base-url https://your-production-app.com \
  --api-key ak_live_xxx

The generator calls GET /api/v1/event-types with the project API key and writes a declaration file that augments this package:

import "pings-js-sdk";
import type { AnalyticsProperties } from "pings-js-sdk";

declare module "pings-js-sdk" {
  interface AnalyticsEventMap {
    "checkout_completed": AnalyticsProperties;
    "signup_completed": AnalyticsProperties;
  }
}

After that file is included by the user's tsconfig.json, calls like analytics.track("checkout_completed", ...) are typed against dashboard event names.

Options:

• --include-inactive: include inactive event types
• --base-url <url> / --app-url <url>: use a different hosted app URL
• --endpoint <url>: use a full /api/v1/events or /api/v1/event-types URL
• --module <name>: override the package name to augment
• --print: print the declaration instead of writing a file

Build Locally

npm run build
npm test