@apex-inc/sdk 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Apex Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,165 @@
+# @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.
+
+## Install
+
+```bash
+npm install @apex-inc/sdk
+```
+
+## Quick Start
+
+```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
+track("page_viewed", { path: "/pricing" });
+track("button_clicked", { label: "Start Trial", section: "hero" });
+track("form_submitted", { formId: "signup", fields: 3 });
+```
+
+## API
+
+### `init(config)`
+
+| 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.
+
+```typescript
+track("page_viewed", { path: "/pricing", referrer: "google" });
+```
+
+### `identify(userId, traits?)`
+
+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",
+});
+```
+
+#### Identity Stitching
+
+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.
+
+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:
+
+```typescript
+identify("jane@example.com", {
+  visitorId: req.cookies.apex_vid,  // From the browser cookie
+  plan: "growth",
+});
+```
+
+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" },
+});
+```
+
+| 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.
+
+## How It Works
+
+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.
+
+## License
+
+MIT — see [LICENSE](./LICENSE)

package/dist/esm/index.js

@@ -0,0 +1,180 @@
+const isBrowser = typeof window !== "undefined";
+const DEFAULT_API_URL = isBrowser ? window.location.origin : "http://localhost:3000";
+let config = null;
+let queue = [];
+let flushTimer = null;
+let userId = null;
+function log(...args) {
+    if (config?.debug)
+        console.log("[apex-sdk]", ...args);
+}
+async function sendBatch(events) {
+    if (!config || events.length === 0)
+        return;
+    const apiUrl = config.apiUrl ?? DEFAULT_API_URL;
+    const url = `${apiUrl.replace(/\/$/, "")}/api/events`;
+    const body = JSON.stringify({
+        projectKey: config.projectKey,
+        userId,
+        events,
+    });
+    try {
+        const fetchFn = typeof fetch !== "undefined" ? fetch : await loadNodeFetch();
+        const res = await fetchFn(url, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body,
+        });
+        log(`Flushed ${events.length} events — ${res.status}`);
+    }
+    catch (err) {
+        log("Flush failed:", err);
+    }
+}
+async function loadNodeFetch() {
+    // Fallback for older Node.js environments without global fetch
+    try {
+        const mod = await import("node-fetch");
+        return mod.default;
+    }
+    catch {
+        throw new Error("apex-sdk: fetch is not available. Use Node.js 18+ or install node-fetch.");
+    }
+}
+function startFlushTimer() {
+    if (flushTimer)
+        return;
+    const interval = config?.flushInterval ?? 5000;
+    flushTimer = setInterval(() => flush(), interval);
+    if (isBrowser) {
+        window.addEventListener("beforeunload", () => flush());
+        document.addEventListener("visibilitychange", () => {
+            if (document.visibilityState === "hidden")
+                flush();
+        });
+    }
+}
+function enqueue(event) {
+    queue.push(event);
+    const flushAt = config?.flushAt ?? 20;
+    if (queue.length >= flushAt)
+        flush();
+}
+// ─── Public API ──────────────────────────────────────────────────────────────
+/**
+ * Initialize the Apex SDK. Must be called before track() or identify().
+ */
+export function init(options) {
+    config = options;
+    queue = [];
+    log("Initialized with project:", options.projectKey);
+    startFlushTimer();
+}
+/**
+ * Track a custom event.
+ */
+export function track(event, properties) {
+    if (!config) {
+        console.warn("[apex-sdk] Call init() before track()");
+        return;
+    }
+    log("Track:", event, properties);
+    enqueue({
+        type: "track",
+        payload: { event, properties, timestamp: new Date().toISOString() },
+        timestamp: new Date().toISOString(),
+    });
+}
+/**
+ * Identify a user with traits (email, name, plan, etc.).
+ * Also performs identity stitching if the userId looks like an email.
+ *
+ * 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.
+ *
+ * PLG integration pattern:
+ *   apex.identify('user@example.com', { visitorId: req.cookies.apex_vid })
+ */
+export function identify(userId_, traits) {
+    if (!config) {
+        console.warn("[apex-sdk] Call init() before identify()");
+        return;
+    }
+    userId = userId_;
+    log("Identify:", userId, traits);
+    enqueue({
+        type: "identify",
+        payload: { userId: userId_, traits },
+        timestamp: new Date().toISOString(),
+    });
+    const email = userId_.includes("@") ? userId_ : traits?.email;
+    if (email) {
+        const browserVisitorId = traits?.visitorId;
+        stitchIdentity(email, browserVisitorId, traits);
+    }
+}
+async function stitchIdentity(email, browserVisitorId, metadata) {
+    if (!config)
+        return;
+    const apiUrl = config.apiUrl ?? DEFAULT_API_URL;
+    const url = `${apiUrl.replace(/\/$/, "")}/api/identity/stitch`;
+    const effectiveVisitorId = browserVisitorId || `sdk-${config.projectKey}-${email}`;
+    try {
+        const fetchFn = typeof fetch !== "undefined" ? fetch : await loadNodeFetch();
+        await fetchFn(url, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({
+                visitorId: effectiveVisitorId,
+                email,
+                projectKey: config.projectKey,
+                metadata: metadata ?? {},
+            }),
+        });
+        log("Identity stitched for:", email, "visitor:", effectiveVisitorId);
+    }
+    catch (err) {
+        log("Identity stitch failed:", err);
+    }
+}
+/**
+ * Track a form submission event with the email for identity stitching.
+ */
+export function trackForm(formData) {
+    if (!config) {
+        console.warn("[apex-sdk] Call init() before trackForm()");
+        return;
+    }
+    const { email, formId, action, fields } = formData;
+    log("TrackForm:", email, formId);
+    track("form_submit", {
+        formId,
+        formAction: action,
+        email,
+        ...(fields ?? {}),
+    });
+    identify(email, { source: "form", formId });
+}
+/**
+ * Immediately flush all queued events to the server.
+ */
+export function flush() {
+    if (queue.length === 0)
+        return;
+    const batch = queue.splice(0, queue.length);
+    sendBatch(batch);
+}
+/**
+ * Shut down the SDK — flush remaining events and stop the timer.
+ */
+export function shutdown() {
+    flush();
+    if (flushTimer) {
+        clearInterval(flushTimer);
+        flushTimer = null;
+    }
+    config = null;
+    log("Shut down");
+}
+export { createManagementClient, } from "./management";

package/dist/esm/management.js

@@ -0,0 +1,152 @@
+/**
+ * Programmatic access to Apex APIs using an API key (same as MCP server).
+ * Intended for Node.js backends; sends x-api-key and x-apex-project on each request.
+ */
+function baseUrl(cfg) {
+    return (cfg.apiUrl ?? "http://localhost:3000").replace(/\/$/, "");
+}
+function keyHeaders(cfg) {
+    return {
+        "Content-Type": "application/json",
+        "x-api-key": cfg.apiKey,
+        "x-apex-project": cfg.projectKey,
+    };
+}
+/**
+ * Create a minimal management client for server-side experiment reads and variant assignment.
+ * Assignment uses Cookie apex_vid + apex_project so GET /api/experiments/[id]/assign resolves consistently.
+ */
+export function createManagementClient(cfg) {
+    const root = baseUrl(cfg);
+    const headers = keyHeaders(cfg);
+    return {
+        async listExperiments() {
+            const res = await fetch(`${root}/api/experiments`, { headers });
+            if (!res.ok) {
+                const text = await res.text().catch(() => "");
+                throw new Error(`Apex listExperiments failed (${res.status}): ${text}`);
+            }
+            return res.json();
+        },
+        async assignVariant(experimentId, visitorId) {
+            const cookie = [
+                `apex_vid=${encodeURIComponent(visitorId)}`,
+                `apex_project=${encodeURIComponent(cfg.projectKey)}`,
+            ].join("; ");
+            const res = await fetch(`${root}/api/experiments/${encodeURIComponent(experimentId)}/assign`, {
+                headers: { ...headers, Cookie: cookie },
+            });
+            if (!res.ok) {
+                const text = await res.text().catch(() => "");
+                throw new Error(`Apex assignVariant failed (${res.status}): ${text}`);
+            }
+            return res.json();
+        },
+        // ─── Communications ───────────────────────────────────────────────
+        async recommendCommunications() {
+            const res = await fetch(`${root}/api/communications/recommend`, { method: "POST", headers });
+            if (!res.ok)
+                throw new Error(`Apex recommendCommunications failed (${res.status}): ${await res.text().catch(() => "")}`);
+            return res.json();
+        },
+        async generateCommunications(catalogEntryIds) {
+            const res = await fetch(`${root}/api/communications/generate`, {
+                method: "POST", headers, body: JSON.stringify({ catalogEntryIds }),
+            });
+            if (!res.ok)
+                throw new Error(`Apex generateCommunications failed (${res.status}): ${await res.text().catch(() => "")}`);
+            return res.json();
+        },
+        async listCommunications() {
+            const res = await fetch(`${root}/api/communications`, { headers });
+            if (!res.ok)
+                throw new Error(`Apex listCommunications failed (${res.status}): ${await res.text().catch(() => "")}`);
+            return res.json();
+        },
+        async getCommunication(id) {
+            const res = await fetch(`${root}/api/communications/${encodeURIComponent(id)}`, { headers });
+            if (!res.ok)
+                throw new Error(`Apex getCommunication failed (${res.status}): ${await res.text().catch(() => "")}`);
+            return res.json();
+        },
+        async updateCommunication(id, updates) {
+            const res = await fetch(`${root}/api/communications/${encodeURIComponent(id)}`, {
+                method: "PATCH", headers, body: JSON.stringify(updates),
+            });
+            if (!res.ok)
+                throw new Error(`Apex updateCommunication failed (${res.status}): ${await res.text().catch(() => "")}`);
+            return res.json();
+        },
+        async deleteCommunication(id) {
+            const res = await fetch(`${root}/api/communications/${encodeURIComponent(id)}`, {
+                method: "DELETE", headers,
+            });
+            if (!res.ok)
+                throw new Error(`Apex deleteCommunication failed (${res.status}): ${await res.text().catch(() => "")}`);
+        },
+        async previewCommunication(id) {
+            const res = await fetch(`${root}/api/communications/${encodeURIComponent(id)}/preview`, {
+                method: "POST", headers,
+            });
+            if (!res.ok)
+                throw new Error(`Apex previewCommunication failed (${res.status}): ${await res.text().catch(() => "")}`);
+            return res.json();
+        },
+        async sendTestCommunication(id) {
+            const res = await fetch(`${root}/api/communications/${encodeURIComponent(id)}/test`, {
+                method: "POST", headers,
+            });
+            if (!res.ok)
+                throw new Error(`Apex sendTestCommunication failed (${res.status}): ${await res.text().catch(() => "")}`);
+        },
+        async triggerCommunication(id, opts) {
+            const res = await fetch(`${root}/api/communications/${encodeURIComponent(id)}/send`, {
+                method: "POST", headers, body: JSON.stringify(opts),
+            });
+            if (!res.ok)
+                throw new Error(`Apex triggerCommunication failed (${res.status}): ${await res.text().catch(() => "")}`);
+        },
+        // ─── Communication Experiments ────────────────────────────────────
+        async listCommExperiments() {
+            const res = await fetch(`${root}/api/communications/experiments`, { headers });
+            if (!res.ok)
+                throw new Error(`Apex listCommExperiments failed (${res.status}): ${await res.text().catch(() => "")}`);
+            return res.json();
+        },
+        async createCommExperiment(params) {
+            const res = await fetch(`${root}/api/communications/experiments`, {
+                method: "POST", headers, body: JSON.stringify(params),
+            });
+            if (!res.ok)
+                throw new Error(`Apex createCommExperiment failed (${res.status}): ${await res.text().catch(() => "")}`);
+            return res.json();
+        },
+        async startCommExperiment(id) {
+            const res = await fetch(`${root}/api/communications/experiments/${encodeURIComponent(id)}`, {
+                method: "PATCH", headers, body: JSON.stringify({ action: "start" }),
+            });
+            if (!res.ok)
+                throw new Error(`Apex startCommExperiment failed (${res.status}): ${await res.text().catch(() => "")}`);
+        },
+        async promoteCommExperimentWinner(id) {
+            const res = await fetch(`${root}/api/communications/experiments/${encodeURIComponent(id)}`, {
+                method: "PATCH", headers, body: JSON.stringify({ action: "promote" }),
+            });
+            if (!res.ok)
+                throw new Error(`Apex promoteCommExperimentWinner failed (${res.status}): ${await res.text().catch(() => "")}`);
+        },
+        // ─── Event Taxonomy ───────────────────────────────────────────────
+        async getEventTaxonomy() {
+            const res = await fetch(`${root}/api/communications/events`, { headers });
+            if (!res.ok)
+                throw new Error(`Apex getEventTaxonomy failed (${res.status}): ${await res.text().catch(() => "")}`);
+            return res.json();
+        },
+        async getEventIntegrationStatus() {
+            const res = await fetch(`${root}/api/communications/events/status`, { headers });
+            if (!res.ok)
+                throw new Error(`Apex getEventIntegrationStatus failed (${res.status}): ${await res.text().catch(() => "")}`);
+            return res.json();
+        },
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,58 @@
+export interface ApexConfig {
+    projectKey: string;
+    apiUrl?: string;
+    /** Flush interval in ms (default: 5000) */
+    flushInterval?: number;
+    /** Max events before auto-flush (default: 20) */
+    flushAt?: number;
+    /** Enable debug logging (default: false) */
+    debug?: boolean;
+}
+export interface TrackEvent {
+    event: string;
+    properties?: Record<string, unknown>;
+    timestamp?: string;
+}
+export interface IdentifyPayload {
+    userId: string;
+    traits?: Record<string, unknown>;
+}
+/**
+ * Initialize the Apex SDK. Must be called before track() or identify().
+ */
+export declare function init(options: ApexConfig): void;
+/**
+ * Track a custom event.
+ */
+export declare function track(event: string, properties?: Record<string, unknown>): void;
+/**
+ * Identify a user with traits (email, name, plan, etc.).
+ * Also performs identity stitching if the userId looks like an email.
+ *
+ * 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.
+ *
+ * PLG integration pattern:
+ *   apex.identify('user@example.com', { visitorId: req.cookies.apex_vid })
+ */
+export declare function identify(userId_: string, traits?: Record<string, unknown>): void;
+/**
+ * Track a form submission event with the email for identity stitching.
+ */
+export declare function trackForm(formData: {
+    email: string;
+    formId?: string;
+    action?: string;
+    fields?: Record<string, unknown>;
+}): void;
+/**
+ * Immediately flush all queued events to the server.
+ */
+export declare function flush(): void;
+/**
+ * Shut down the SDK — flush remaining events and stop the timer.
+ */
+export declare function shutdown(): void;
+export { createManagementClient, type ManagementConfig, type AssignVariantResult, } from "./management";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,UAAU;IACzB,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,2CAA2C;IAC3C,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,iDAAiD;IACjD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,4CAA4C;IAC5C,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED,MAAM,WAAW,UAAU;IACzB,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACrC,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAClC;AA4ED;;GAEG;AACH,wBAAgB,IAAI,CAAC,OAAO,EAAE,UAAU,GAAG,IAAI,CAK9C;AAED;;GAEG;AACH,wBAAgB,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAW/E;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,QAAQ,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAkBhF;AA+BD;;GAEG;AACH,wBAAgB,SAAS,CAAC,QAAQ,EAAE;IAClC,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAClC,GAAG,IAAI,CAgBP;AAED;;GAEG;AACH,wBAAgB,KAAK,IAAI,IAAI,CAI5B;AAED;;GAEG;AACH,wBAAgB,QAAQ,IAAI,IAAI,CAQ/B;AAED,OAAO,EACL,sBAAsB,EACtB,KAAK,gBAAgB,EACrB,KAAK,mBAAmB,GACzB,MAAM,cAAc,CAAC"}