@quickpipeaiab/sdk

JavaScript/TypeScript SDK for sending analytics events to QuickPipe. Follows standard event/analytics patterns (Segment, Mixpanel style).

Installation

npm install @quickpipeaiab/sdk
# or
yarn add @quickpipeaiab/sdk

Configuration

Set environment variables or pass config to the constructor:

| Env Variable | Config Option | Description | | ------------------------------ | --------------- | --------------------------------------------------------------------------------------------------------- | | QUICKPIPE_ANALYTICS_API_KEY | apiKey | API key for authentication (required) | | QUICKPIPE_ANALYTICS_ENDPOINT | endpoint | Base URL of the analytics API (default: https://analytics.quickpipe.ai; local: http://localhost:3002) | | QUICKPIPE_APPLICATION_ID | applicationId | Default workspace application id (Workspace.applicationId or slug) | | — | onLeadCreated | Callback after upsertLead() with leadId for storage and track() |

The API endpoint reads ANALYTICS_API_KEY from its environment and validates incoming requests against it.

Usage

Basic tracking

import { createAnalytics, STANDARD_EVENTS } from "@quickpipeaiab/analytics-sdk";

// Create/update lead first; store leadId from callback for PQL events
const analytics = createAnalytics({
  apiKey: process.env.QUICKPIPE_ANALYTICS_API_KEY,
  endpoint: "https://analytics.quickpipe.ai",
  applicationId: process.env.QUICKPIPE_APPLICATION_ID,
  onLeadCreated: ({ leadId }) => {
    // Recommended: persist `leadId` in your backend (e.g., DB) tied to the current user/session.
    // Demo only: storing in `localStorage` is convenient but not ideal (browser-only, can be cleared/modified).
    localStorage.setItem("quickpipe_lead_id", String(leadId));
  },
});

await analytics.upsertLead({
  email: "[email protected]",
  firstName: "Jane",
});

const leadId = Number(localStorage.getItem("quickpipe_lead_id"));

analytics.track(STANDARD_EVENTS.EMAIL_SENT, {
  leadId,
  eventTypes: ["email_sent", "delivered"],
  date: new Date().toISOString(),
});

// Flush immediately (otherwise batched every 5s or 10 events)
await analytics.flush();

Identify users

analytics.identify("user-123", {
  email: "[email protected]",
  name: "Jane Doe",
  applicationId: "app-456",
});

// Subsequent track() calls include userId
analytics.track(STANDARD_EVENTS.EMAIL_SENT, {
  eventTypes: ["email_sent"],
  applicationId: "app-456",
});

Convenience: track email events

analytics.trackEmail("email_sent", {
  email: "[email protected]",
  applicationId: "app-456",
  eventTypes: ["sent", "delivered"],
});

Environment-based config

// Uses QUICKPIPE_ANALYTICS_API_KEY and QUICKPIPE_ANALYTICS_ENDPOINT from env
const analytics = createAnalytics();

API

• resolveWorkspace(applicationId?) – Map application id to internal workspaceId via GET /analytics/workspaces/resolve.
• setApplicationId(id) – Set default application id for subsequent calls.
• upsertLead(payload) – Create or update a lead (email, optional per-call applicationId, leadId, pqlScore, etc.). Returns { leadId, created, updated }. Invokes onLeadCreated on success.
• setOnLeadCreated(callback) – Register or replace the lead-created callback at runtime.
• track(event, properties) – Record an event. For PQL, include leadId in properties. applicationId comes from config or per-call override. Do not use workspaceId (rejected by SDK and API).
• identify(userId, traits?) – Associate subsequent events with a user.
• setAnonymousId(id) – Set anonymous ID for unauthenticated users.
• flush() – Send queued events immediately.
• reset() – Clear identity and queue.

Event batching

Events are batched and sent every 5 seconds or when 10 events are queued (configurable via flushInterval and flushAt).