@apex-inc/sdk 0.1.1 → 0.6.0

package/README.md

@@ -6,7 +6,7 @@ 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.
+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](https://apex.inc) (coming soon).
 
@@ -22,7 +22,7 @@ npm install @apex-inc/sdk
 import { init, track, identify } from "@apex-inc/sdk";
 
 init({
-  projectKey: "your-project-key",
+  workspaceKey: "your-workspace-key",
   apiUrl: "https://your-apex-instance.com",
 });
 
@@ -30,6 +30,74 @@ identify("user_123", { email: "jane@example.com" });
 track("page_viewed", { path: "/pricing" });
 ```
 
+## 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:
+
+```typescript
+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("chris@acme.com", { 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](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()
+);
+```
+
+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](./LICENSE)

package/dist/esm/index.js

@@ -14,9 +14,14 @@ async function sendBatch(events) {
     const apiUrl = config.apiUrl ?? DEFAULT_API_URL;
     const url = `${apiUrl.replace(/\/$/, "")}/api/events`;
     const body = JSON.stringify({
-        projectKey: config.projectKey,
+        workspaceKey: config.workspaceKey,
         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();
@@ -63,11 +68,16 @@ function enqueue(event) {
 // ─── Public API ──────────────────────────────────────────────────────────────
 /**
  * Initialize the Apex SDK. Must be called before track() or identify().
+ * Accepts `workspaceKey` (canonical) or the deprecated `projectKey`.
  */
 export function init(options) {
-    config = options;
+    const workspaceKey = options.workspaceKey ?? options.projectKey;
+    if (!workspaceKey) {
+        throw new Error("apex.init: `workspaceKey` is required");
+    }
+    config = { ...options, workspaceKey };
     queue = [];
-    log("Initialized with project:", options.projectKey);
+    log("Initialized with workspace:", workspaceKey);
     startFlushTimer();
 }
 /**
@@ -89,6 +99,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,15 +124,21 @@ 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;
     const url = `${apiUrl.replace(/\/$/, "")}/api/identity/stitch`;
-    const effectiveVisitorId = browserVisitorId || `sdk-${config.projectKey}-${email}`;
+    const effectiveVisitorId = browserVisitorId || `sdk-${config.workspaceKey}-${email}`;
     try {
         const fetchFn = typeof fetch !== "undefined" ? fetch : await loadNodeFetch();
         await fetchFn(url, {
@@ -128,7 +147,8 @@ async function stitchIdentity(email, browserVisitorId, metadata) {
             body: JSON.stringify({
                 visitorId: effectiveVisitorId,
                 email,
-                projectKey: config.projectKey,
+                workspaceKey: config.workspaceKey,
+                ...(stableUserId ? { userId: stableUserId } : {}),
                 metadata: metadata ?? {},
             }),
         });
@@ -138,6 +158,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 +235,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 +276,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.workspaceKey)
+        headers["x-apex-workspace"] = config.workspaceKey;
+    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;
+}