@apex-inc/sdk

Event tracking and identity SDK for Apex — currently in private beta.

Works in Node.js 18+ and browser environments. Zero runtime dependencies.

Access

Apex is invite-only during the private-beta period. If you received an invite, your onboarding email contains your workspaceKey and apiUrl. Full API documentation is available in-app once your account is active.

Not in the beta yet? Request access at apex.inc (coming soon).

Install

npm install @apex-inc/sdk

Quick Start

import { init, track, identify } from "@apex-inc/sdk";

init({
  workspaceKey: "your-workspace-key",
  apiUrl: "https://your-apex-instance.com",
});

identify("user_123", { email: "[email protected]" });
track("page_viewed", { path: "/pricing" });

Profile photos (avatar_url)

Pass avatar_url in traits to show end-user photos across Apex — the Customers list, customer detail pages, and the Live Customers widget. It's a canonical attribute, so photoUrl / image / profile_image map to it too. Apex validates on write (https only) and falls back to colored initials when absent.

identify("user_123", {
  email: "[email protected]",
  avatar_url: user.photoURL, // OIDC `picture` claim works the same way
});

PLG primitives

In addition to track / identify the SDK exposes three PLG-specific primitives. Use them when you want Apex to derive activation, expansion, and retention rollups automatically:

import { init, identify, group, feature, track } from "@apex-inc/sdk";
import { EVENTS, type ActivatedEvent } from "@apex-inc/sdk/plg-events";

init({ workspaceKey: "your-workspace-key", apiUrl: "https://app.apex.inc" });

// Identify the authenticated user.
identify("[email protected]", { visitorId: "apex_vid_from_cookie" });

// Group them into their account / team (B2B).
group("acct_acme", { plan: "growth", arr: 120_000 });

// Track feature usage. Include experiment variant if you have one.
feature("cohort-builder", { variant: "new-editor", enabled: true });

// Emit curated PLG lifecycle events with compile-time-typed payloads.
track(EVENTS.ACTIVATED, {
  daysToActivation: 3,
  milestone: "first-experiment-shipped",
} satisfies ActivatedEvent);

The PLG catalog ships eight curated events: signup, activated, feature_first_use, aha_moment, expansion, contraction, reactivation, churn. Each has a typed interface so your IDE catches missing fields at build time. See the PLG event catalog docs for the full schema.

Server Events API (server-to-server events)

For backend workflows that don't have a browser session — Stripe webhooks, CRM events, scheduled jobs — use sendServerEvent / sendServerEvents. These hit the /api/v1/events endpoint with API-key auth and idempotency-key support.

import { sendServerEvent, newIdempotencyKey } from "@apex-inc/sdk";

await sendServerEvent(
  { apiKey: process.env.APEX_API_KEY! }, // apex_sk_…
  {
    type: "purchase_completed",
    email: customer.email,
    data: { value: invoice.amount_paid / 100, currency: "USD", order_id: invoice.id },
  },
  { idempotencyKey: stripeEvent.id }, // or newIdempotencyKey()
);

Batches of up to 100 events go through sendServerEvents. Use the same visitorId / email you'd use in the browser snippet so cross-channel stitching just works.

Multi-workspace orgs

If your organization runs more than one workspace (e.g. a SaaS product plus a partner marketplace), each workspace has its own workspaceKey. Initialize one SDK instance per workspace; event identity stitches at the org level via OrgPerson so a single human tracked in both shows up as one person in cross-workspace cohorts and reports.

License

MIT — see LICENSE