@apex-inc/sdk 0.1.0 → 0.5.0

package/README.md

@@ -1,6 +1,14 @@
 # @apex-inc/sdk
 
-Lightweight SDK for sending events and user data to Apex Growth Intelligence. Works in **Node.js** (18+) and **browser** environments. Zero runtime dependencies.
+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 `projectKey` and `apiUrl`. Full API documentation is available in-app once your account is active.
+
+Not in the beta yet? Request access at [apex.inc](https://apex.inc) (coming soon).
 
 ## Install
 
@@ -13,152 +21,82 @@ npm install @apex-inc/sdk
 ```typescript
 import { init, track, identify } from "@apex-inc/sdk";
 
-// Initialize (once, at app startup)
 init({
   projectKey: "your-project-key",
   apiUrl: "https://your-apex-instance.com",
 });
 
-// Identify a user
-identify("user_123", {
-  email: "jane@example.com",
-  plan: "starter",
-});
-
-// Track events
+identify("user_123", { email: "jane@example.com" });
 track("page_viewed", { path: "/pricing" });
-track("button_clicked", { label: "Start Trial", section: "hero" });
-track("form_submitted", { formId: "signup", fields: 3 });
 ```
 
-## API
-
-### `init(config)`
+## PLG primitives
 
-| Option          | Type     | Default                  | Description                       |
-|-----------------|----------|--------------------------|-----------------------------------|
-| `projectKey`    | string   | **required**             | Your Apex project key             |
-| `apiUrl`        | string   | `window.location.origin` | Apex API URL                      |
-| `flushInterval` | number   | `5000`                   | Auto-flush interval (ms)         |
-| `flushAt`       | number   | `20`                     | Max queued events before flush   |
-| `debug`         | boolean  | `false`                  | Log SDK activity to console      |
-
-### `track(event, properties?)`
-
-Send a named event with optional properties.
+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:
 
 ```typescript
-track("page_viewed", { path: "/pricing", referrer: "google" });
-```
-
-### `identify(userId, traits?)`
+import { init, identify, group, feature, track } from "@apex-inc/sdk";
+import { EVENTS, type ActivatedEvent } from "@apex-inc/sdk/plg-events";
 
-Associate subsequent events with a user. Also performs **identity stitching** — linking an anonymous visitor to a known email address.
-
-```typescript
-identify("jane@example.com", {
-  name: "Jane Smith",
-  plan: "growth",
-  company: "Acme Inc",
-});
-```
+init({ projectKey: "your-project-key", apiUrl: "https://app.apex.inc" });
 
-#### Identity Stitching
+// Identify the authenticated user.
+identify("chris@acme.com", { visitorId: "apex_vid_from_cookie" });
 
-When the `userId` contains `@` (or `traits.email` is set), the SDK automatically calls the `/api/identity/stitch` endpoint to link the email to a visitor profile. This connects anonymous browsing behavior (from the Apex snippet) to a known user.
+// Group them into their account / team (B2B).
+group("acct_acme", { plan: "growth", arr: 120_000 });
 
-For **server-side** identify calls (e.g., from a webhook handler), pass the browser's `apex_vid` cookie as `traits.visitorId` to ensure the stitch connects to the real browser session:
+// Track feature usage. Include experiment variant if you have one.
+feature("cohort-builder", { variant: "new-editor", enabled: true });
 
-```typescript
-identify("jane@example.com", {
-  visitorId: req.cookies.apex_vid,  // From the browser cookie
-  plan: "growth",
-});
+// Emit curated PLG lifecycle events with compile-time-typed payloads.
+track(EVENTS.ACTIVATED, {
+  daysToActivation: 3,
+  milestone: "first-experiment-shipped",
+} satisfies ActivatedEvent);
 ```
 
-Without `visitorId`, a synthetic visitor ID is created that won't connect to marketing touchpoints.
-
-### `trackForm(formData)`
-
-Track a form submission and identify the user in one call. Combines `track("form_submit", ...)` with `identify(email, ...)`.
-
-```typescript
-trackForm({
-  email: "jane@example.com",
-  formId: "signup-form",
-  action: "/api/register",
-  fields: { name: "Jane", company: "Acme" },
-});
+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](https://app.apex.inc/docs/plg-event-catalog) 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.
+
+```ts
+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()
+);
 ```
 
-| Option   | Type   | Required | Description                      |
-|----------|--------|----------|----------------------------------|
-| `email`  | string | Yes      | User's email address             |
-| `formId` | string | No       | Form identifier                  |
-| `action` | string | No       | Form action URL                  |
-| `fields` | object | No       | Additional form field data       |
-
-### `flush()`
-
-Immediately send all queued events.
-
-### `shutdown()`
-
-Flush remaining events and stop the background timer.
-
-## Node.js Usage
-
-The SDK works in Node.js 18+ (which includes global `fetch`). For older Node.js versions, install `node-fetch`:
-
-```bash
-npm install node-fetch
-```
-
-```typescript
-import { init, track, identify, shutdown } from "@apex-inc/sdk";
-
-init({
-  projectKey: "your-project-key",
-  apiUrl: "https://your-apex-instance.com",
-});
-
-// In your webhook handler or API route:
-identify("new-signup@example.com", { source: "stripe_webhook" });
-track("subscription_created", { plan: "growth", mrr: 99 });
-
-// On process exit:
-shutdown();
-```
-
-## Management API (API key)
-
-For **server-side** access to experiments (same auth model as the Apex MCP server), use `createManagementClient` with your **`APEX_API_KEY`** and project key. The client sends **`x-api-key`** and **`x-apex-project`** so routes resolve the tenant without a browser session.
-
-```typescript
-import { createManagementClient, init, track } from "@apex-inc/sdk";
-
-const apex = createManagementClient({
-  projectKey: "your-project-key",
-  apiKey: process.env.APEX_API_KEY!,
-  apiUrl: "https://your-apex-instance.com",
-});
-
-const experiments = await apex.listExperiments();
-const { variant } = await apex.assignVariant("experiment-id-123", "stable-visitor-id-per-user");
-
-init({ projectKey: "your-project-key", apiUrl: "https://your-apex-instance.com" });
-track("notification_sent", { experimentId: "experiment-id-123", variant });
-```
-
-`assignVariant` uses a stable **visitor id** per end user (e.g. hashed internal user id) so variant assignment stays deterministic. Pass the same id on every call for that user and experiment.
-
-## Shipped skills (AI assistants)
-
-Cursor-style skills live in **`skills/apex-growth-tracking/SKILL.md`**. Copy that folder into `.cursor/skills/` so your AI assistant gets Apex tracking conventions in context.
+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.
 
-## How It Works
+## Multi-workspace orgs
 
-Events are queued in memory and flushed in batches to `POST /api/events`. The SDK auto-flushes on a timer, when the queue hits `flushAt`, and on `beforeunload` / `visibilitychange` in browsers.
+If your organization runs more than one workspace (e.g. a SaaS product
+plus a partner marketplace), each workspace has its own `projectKey`.
+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
 

package/dist/esm/index.js

@@ -17,6 +17,11 @@ async function sendBatch(events) {
         projectKey: config.projectKey,
         userId,
         events,
+        // MMP-070 — propagate the SDK-level environment override (when
+        // set by `apex.init({ environment })`). The server prefers this
+        // over auto-detection from the Referer/Origin host. Mobile SDKs
+        // don't send this field; they set `mobile.releaseChannel` instead.
+        ...(config.environment ? { webEnvironment: config.environment } : {}),
     });
     try {
         const fetchFn = typeof fetch !== "undefined" ? fetch : await loadNodeFetch();
@@ -89,6 +94,9 @@ export function track(event, properties) {
  * Identify a user with traits (email, name, plan, etc.).
  * Also performs identity stitching if the userId looks like an email.
  *
+ * Prefer canonical snake_case trait names (see `CanonicalUserTraits`) so
+ * templates resolve them cleanly.
+ *
  * Pass `traits.visitorId` (the browser's `apex_vid` cookie value) to stitch
  * server-side identify calls to the real browser session. Without it, the SDK
  * creates a synthetic visitor ID that is disconnected from marketing touchpoints.
@@ -111,10 +119,16 @@ export function identify(userId_, traits) {
     const email = userId_.includes("@") ? userId_ : traits?.email;
     if (email) {
         const browserVisitorId = traits?.visitorId;
-        stitchIdentity(email, browserVisitorId, traits);
+        // Forward the caller's stable user id as `userId` whenever it is NOT
+        // itself an email — this becomes the highest-precedence
+        // `internal_user_id` identifier server-side, which is what makes
+        // anonymous→known reconciliation deterministic. Always identify with
+        // your own user id (e.g. Cognito sub / DB id), not just an email.
+        const stableUserId = userId_.includes("@") ? undefined : userId_;
+        stitchIdentity(email, browserVisitorId, traits, stableUserId);
     }
 }
-async function stitchIdentity(email, browserVisitorId, metadata) {
+async function stitchIdentity(email, browserVisitorId, metadata, stableUserId) {
     if (!config)
         return;
     const apiUrl = config.apiUrl ?? DEFAULT_API_URL;
@@ -129,6 +143,7 @@ async function stitchIdentity(email, browserVisitorId, metadata) {
                 visitorId: effectiveVisitorId,
                 email,
                 projectKey: config.projectKey,
+                ...(stableUserId ? { userId: stableUserId } : {}),
                 metadata: metadata ?? {},
             }),
         });
@@ -138,6 +153,56 @@ async function stitchIdentity(email, browserVisitorId, metadata) {
         log("Identity stitch failed:", err);
     }
 }
+/**
+ * MWO-009 — Group a user into an account / company / team so B2B
+ * PQA rollups can be derived. Calling `group("acme-inc")` stamps
+ * every subsequent `track`/`feature` event with `groupId`.
+ */
+let groupId = null;
+export function group(groupId_, traits) {
+    if (!config) {
+        console.warn("[apex-sdk] Call init() before group()");
+        return;
+    }
+    groupId = groupId_;
+    log("Group:", groupId_, traits);
+    enqueue({
+        type: "group",
+        payload: { groupId: groupId_, traits },
+        timestamp: new Date().toISOString(),
+    });
+}
+/**
+ * MWO-009 — Feature usage. Fire from your app whenever a user
+ * touches a named feature. Variant + enabled support wiring to
+ * Apex experiment payloads — if Phase 8's experiment engine served
+ * a variant, pass it through here to close the loop between
+ * assignment and adoption.
+ */
+export function feature(featureKey, opts = {}) {
+    if (!config) {
+        console.warn("[apex-sdk] Call init() before feature()");
+        return;
+    }
+    log("Feature:", featureKey, opts);
+    enqueue({
+        type: "feature",
+        payload: {
+            featureKey,
+            enabled: opts.enabled,
+            variant: opts.variant,
+            properties: opts.properties,
+        },
+        timestamp: new Date().toISOString(),
+    });
+}
+/**
+ * Returns the most recently set groupId (if any). Callers can use
+ * this to decorate their own payloads or assert in tests.
+ */
+export function currentGroupId() {
+    return groupId;
+}
 /**
  * Track a form submission event with the email for identity stitching.
  */
@@ -165,6 +230,34 @@ export function flush() {
     const batch = queue.splice(0, queue.length);
     sendBatch(batch);
 }
+/**
+ * Helpers grouped under `trackCart.*` so call sites read naturally
+ * (`apex.trackCart.add({...})`). The implementation just delegates to
+ * `track()` with the canonical event names.
+ */
+export const trackCart = {
+    /** Fired when a user adds an item to their cart. */
+    add(line) {
+        track("add_to_cart", { ...line });
+    },
+    /** Fired when a user removes an item from their cart. */
+    remove(opts) {
+        track("remove_from_cart", { ...opts });
+    },
+    /**
+     * Full-cart reconciliation snapshot. Use whenever the canonical
+     * cart state is loaded (login restore, app foreground, cart screen
+     * mount). The server-side rollup replaces all stored lines wholesale
+     * — this is the "source of truth" event when deltas drift.
+     */
+    snapshot(opts) {
+        track("cart_snapshot", { ...opts });
+    },
+    /** Fired on checkout success; clears the rolled-up cart. */
+    checkout(opts) {
+        track("checkout_completed", { ...opts });
+    },
+};
 /**
  * Shut down the SDK — flush remaining events and stop the timer.
  */
@@ -178,3 +271,73 @@ export function shutdown() {
     log("Shut down");
 }
 export { createManagementClient, } from "./management";
+/**
+ * Generate a stable idempotency key. Prefers `crypto.randomUUID()`
+ * when available (Node 19+, modern browsers). Falls back to a
+ * timestamp + random suffix that's good enough to avoid collisions
+ * within a single process.
+ */
+export function newIdempotencyKey() {
+    const c = globalThis.crypto;
+    if (c?.randomUUID)
+        return c.randomUUID();
+    return `idk_${Date.now()}_${Math.random().toString(36).slice(2, 12)}`;
+}
+/**
+ * Send a single event server-to-server. Useful for Stripe webhooks,
+ * CRM-driven conversions, and any backend signal that should land in
+ * Apex without going through the browser snippet.
+ *
+ * @example
+ * await sendServerEvent(
+ *   { apiKey: process.env.APEX_API_KEY! },
+ *   {
+ *     type: "purchase_completed",
+ *     email: "user@example.com",
+ *     data: { value: 99, currency: "USD", order_id: "order_42" },
+ *   },
+ *   { idempotencyKey: stripeEvent.id }
+ * );
+ */
+export async function sendServerEvent(config, event, options = {}) {
+    return sendServerEvents(config, [event], options);
+}
+/**
+ * Send up to 100 events server-to-server in one request. Larger
+ * batches must be sharded by the caller (the API returns 400
+ * `batch_too_large` otherwise).
+ */
+export async function sendServerEvents(config, events, options = {}) {
+    if (!config.apiKey) {
+        throw new Error("apex-sdk: sendServerEvent requires apiKey");
+    }
+    if (events.length === 0) {
+        throw new Error("apex-sdk: sendServerEvent requires at least one event");
+    }
+    if (events.length > 100) {
+        throw new Error("apex-sdk: sendServerEvents batch_too_large — max 100 events; shard yourself");
+    }
+    const apiUrl = (config.apiUrl ?? "https://app.apex.inc").replace(/\/$/, "");
+    const url = `${apiUrl}/api/v1/events`;
+    const idempotencyKey = options.idempotencyKey ?? newIdempotencyKey();
+    const headers = {
+        "content-type": "application/json",
+        "x-api-key": config.apiKey,
+        "idempotency-key": idempotencyKey,
+    };
+    if (config.projectKey)
+        headers["x-apex-project"] = config.projectKey;
+    const fetchFn = typeof fetch !== "undefined" ? fetch : await loadNodeFetch();
+    const res = await fetchFn(url, {
+        method: "POST",
+        headers,
+        body: JSON.stringify({ events }),
+    });
+    const json = (await res.json().catch(() => ({})));
+    if (!res.ok) {
+        const code = json.error?.code ?? `http_${res.status}`;
+        const message = json.error?.message ?? `HTTP ${res.status}`;
+        throw new Error(`apex-sdk: sendServerEvent failed (${code}): ${message}`);
+    }
+    return json;
+}