@apex-inc/sdk 0.1.0

package/dist/index.js

@@ -0,0 +1,224 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createManagementClient = void 0;
+exports.init = init;
+exports.track = track;
+exports.identify = identify;
+exports.trackForm = trackForm;
+exports.flush = flush;
+exports.shutdown = shutdown;
+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 Promise.resolve(`${"node-fetch"}`).then(s => __importStar(require(s)));
+        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().
+ */
+function init(options) {
+    config = options;
+    queue = [];
+    log("Initialized with project:", options.projectKey);
+    startFlushTimer();
+}
+/**
+ * Track a custom event.
+ */
+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 })
+ */
+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.
+ */
+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.
+ */
+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.
+ */
+function shutdown() {
+    flush();
+    if (flushTimer) {
+        clearInterval(flushTimer);
+        flushTimer = null;
+    }
+    config = null;
+    log("Shut down");
+}
+var management_1 = require("./management");
+Object.defineProperty(exports, "createManagementClient", { enumerable: true, get: function () { return management_1.createManagementClient; } });
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/management.d.ts

@@ -0,0 +1,50 @@
+/**
+ * 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.
+ */
+export interface ManagementConfig {
+    projectKey: string;
+    apiKey: string;
+    /** Base URL of the Apex app (no trailing slash), e.g. https://app.example.com */
+    apiUrl?: string;
+}
+export interface AssignVariantResult {
+    variant: string;
+    experimentId: string;
+    visitorId?: string;
+}
+/**
+ * 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 declare function createManagementClient(cfg: ManagementConfig): {
+    listExperiments(): Promise<unknown[]>;
+    assignVariant(experimentId: string, visitorId: string): Promise<AssignVariantResult>;
+    recommendCommunications(): Promise<unknown>;
+    generateCommunications(catalogEntryIds: string[]): Promise<unknown[]>;
+    listCommunications(): Promise<unknown[]>;
+    getCommunication(id: string): Promise<unknown>;
+    updateCommunication(id: string, updates: Record<string, unknown>): Promise<unknown>;
+    deleteCommunication(id: string): Promise<void>;
+    previewCommunication(id: string): Promise<{
+        subject: string;
+        html: string;
+    }>;
+    sendTestCommunication(id: string): Promise<void>;
+    triggerCommunication(id: string, opts: {
+        recipientEmail: string;
+        mergeData?: Record<string, string>;
+    }): Promise<void>;
+    listCommExperiments(): Promise<unknown[]>;
+    createCommExperiment(params: {
+        communicationId: string;
+        splitLevel: string;
+        funnelGoal: string;
+        variants: unknown[];
+    }): Promise<unknown>;
+    startCommExperiment(id: string): Promise<void>;
+    promoteCommExperimentWinner(id: string): Promise<void>;
+    getEventTaxonomy(): Promise<unknown[]>;
+    getEventIntegrationStatus(): Promise<unknown[]>;
+};
+//# sourceMappingURL=management.d.ts.map

package/dist/management.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"management.d.ts","sourceRoot":"","sources":["../src/management.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,MAAM,WAAW,gBAAgB;IAC/B,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,iFAAiF;IACjF,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAcD,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,gBAAgB;uBAK/B,OAAO,CAAC,OAAO,EAAE,CAAC;gCAST,MAAM,aAAa,MAAM,GAAG,OAAO,CAAC,mBAAmB,CAAC;+BAoBzD,OAAO,CAAC,OAAO,CAAC;4CAMH,MAAM,EAAE,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC;0BAQ/C,OAAO,CAAC,OAAO,EAAE,CAAC;yBAMnB,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;4BAMtB,MAAM,WAAW,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,OAAO,CAAC;4BAQ3D,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;6BAOrB,MAAM,GAAG,OAAO,CAAC;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;8BAQlD,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;6BAOvB,MAAM,QAAQ;QAAE,cAAc,EAAE,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC;2BAS9F,OAAO,CAAC,OAAO,EAAE,CAAC;iCAMZ;QACjC,eAAe,EAAE,MAAM,CAAC;QACxB,UAAU,EAAE,MAAM,CAAC;QACnB,UAAU,EAAE,MAAM,CAAC;QACnB,QAAQ,EAAE,OAAO,EAAE,CAAC;KACrB,GAAG,OAAO,CAAC,OAAO,CAAC;4BAQU,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;oCAOd,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;wBASlC,OAAO,CAAC,OAAO,EAAE,CAAC;iCAMT,OAAO,CAAC,OAAO,EAAE,CAAC;EAMxD"}

package/dist/management.js

@@ -0,0 +1,156 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createManagementClient = createManagementClient;
+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.
+ */
+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();
+        },
+    };
+}
+//# sourceMappingURL=management.js.map

package/dist/management.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"management.js","sourceRoot":"","sources":["../src/management.ts"],"names":[],"mappings":";AAAA;;;GAGG;;AA+BH,wDAkJC;AAxKD,SAAS,OAAO,CAAC,GAAqB;IACpC,OAAO,CAAC,GAAG,CAAC,MAAM,IAAI,uBAAuB,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;AACpE,CAAC;AAED,SAAS,UAAU,CAAC,GAAqB;IACvC,OAAO;QACL,cAAc,EAAE,kBAAkB;QAClC,WAAW,EAAE,GAAG,CAAC,MAAM;QACvB,gBAAgB,EAAE,GAAG,CAAC,UAAU;KACjC,CAAC;AACJ,CAAC;AAQD;;;GAGG;AACH,SAAgB,sBAAsB,CAAC,GAAqB;IAC1D,MAAM,IAAI,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;IAC1B,MAAM,OAAO,GAAG,UAAU,CAAC,GAAG,CAAC,CAAC;IAEhC,OAAO;QACL,KAAK,CAAC,eAAe;YACnB,MAAM,GAAG,GAAG,MAAM,KAAK,CAAC,GAAG,IAAI,kBAAkB,EAAE,EAAE,OAAO,EAAE,CAAC,CAAC;YAChE,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC;gBACZ,MAAM,IAAI,GAAG,MAAM,GAAG,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,EAAE,CAAC,CAAC;gBAC9C,MAAM,IAAI,KAAK,CAAC,gCAAgC,GAAG,CAAC,MAAM,MAAM,IAAI,EAAE,CAAC,CAAC;YAC1E,CAAC;YACD,OAAO,GAAG,CAAC,IAAI,EAAwB,CAAC;QAC1C,CAAC;QAED,KAAK,CAAC,aAAa,CAAC,YAAoB,EAAE,SAAiB;YACzD,MAAM,MAAM,GAAG;gBACb,YAAY,kBAAkB,CAAC,SAAS,CAAC,EAAE;gBAC3C,gBAAgB,kBAAkB,CAAC,GAAG,CAAC,UAAU,CAAC,EAAE;aACrD,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YACb,MAAM,GAAG,GAAG,MAAM,KAAK,CACrB,GAAG,IAAI,oBAAoB,kBAAkB,CAAC,YAAY,CAAC,SAAS,EACpE;gBACE,OAAO,EAAE,EAAE,GAAG,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE;aACxC,CACF,CAAC;YACF,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC;gBACZ,MAAM,IAAI,GAAG,MAAM,GAAG,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,EAAE,CAAC,CAAC;gBAC9C,MAAM,IAAI,KAAK,CAAC,8BAA8B,GAAG,CAAC,MAAM,MAAM,IAAI,EAAE,CAAC,CAAC;YACxE,CAAC;YACD,OAAO,GAAG,CAAC,IAAI,EAAkC,CAAC;QACpD,CAAC;QAED,qEAAqE;QAErE,KAAK,CAAC,uBAAuB;YAC3B,MAAM,GAAG,GAAG,MAAM,KAAK,CAAC,GAAG,IAAI,+BAA+B,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,CAAC;YAC7F,IAAI,CAAC,GAAG,CAAC,EAAE;gBAAE,MAAM,IAAI,KAAK,CAAC,wCAAwC,GAAG,CAAC,MAAM,MAAM,MAAM,GAAG,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;YACzH,OAAO,GAAG,CAAC,IAAI,EAAE,CAAC;QACpB,CAAC;QAED,KAAK,CAAC,sBAAsB,CAAC,eAAyB;YACpD,MAAM,GAAG,GAAG,MAAM,KAAK,CAAC,GAAG,IAAI,8BAA8B,EAAE;gBAC7D,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,EAAE,eAAe,EAAE,CAAC;aACnE,CAAC,CAAC;YACH,IAAI,CAAC,GAAG,CAAC,EAAE;gBAAE,MAAM,IAAI,KAAK,CAAC,uCAAuC,GAAG,CAAC,MAAM,MAAM,MAAM,GAAG,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;YACxH,OAAO,GAAG,CAAC,IAAI,EAAwB,CAAC;QAC1C,CAAC;QAED,KAAK,CAAC,kBAAkB;YACtB,MAAM,GAAG,GAAG,MAAM,KAAK,CAAC,GAAG,IAAI,qBAAqB,EAAE,EAAE,OAAO,EAAE,CAAC,CAAC;YACnE,IAAI,CAAC,GAAG,CAAC,EAAE;gBAAE,MAAM,IAAI,KAAK,CAAC,mCAAmC,GAAG,CAAC,MAAM,MAAM,MAAM,GAAG,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;YACpH,OAAO,GAAG,CAAC,IAAI,EAAwB,CAAC;QAC1C,CAAC;QAED,KAAK,CAAC,gBAAgB,CAAC,EAAU;YAC/B,MAAM,GAAG,GAAG,MAAM,KAAK,CAAC,GAAG,IAAI,uBAAuB,kBAAkB,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,OAAO,EAAE,CAAC,CAAC;YAC7F,IAAI,CAAC,GAAG,CAAC,EAAE;gBAAE,MAAM,IAAI,KAAK,CAAC,iCAAiC,GAAG,CAAC,MAAM,MAAM,MAAM,GAAG,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;YAClH,OAAO,GAAG,CAAC,IAAI,EAAE,CAAC;QACpB,CAAC;QAED,KAAK,CAAC,mBAAmB,CAAC,EAAU,EAAE,OAAgC;YACpE,MAAM,GAAG,GAAG,MAAM,KAAK,CAAC,GAAG,IAAI,uBAAuB,kBAAkB,CAAC,EAAE,CAAC,EAAE,EAAE;gBAC9E,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC;aACxD,CAAC,CAAC;YACH,IAAI,CAAC,GAAG,CAAC,EAAE;gBAAE,MAAM,IAAI,KAAK,CAAC,oCAAoC,GAAG,CAAC,MAAM,MAAM,MAAM,GAAG,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;YACrH,OAAO,GAAG,CAAC,IAAI,EAAE,CAAC;QACpB,CAAC;QAED,KAAK,CAAC,mBAAmB,CAAC,EAAU;YAClC,MAAM,GAAG,GAAG,MAAM,KAAK,CAAC,GAAG,IAAI,uBAAuB,kBAAkB,CAAC,EAAE,CAAC,EAAE,EAAE;gBAC9E,MAAM,EAAE,QAAQ,EAAE,OAAO;aAC1B,CAAC,CAAC;YACH,IAAI,CAAC,GAAG,CAAC,EAAE;gBAAE,MAAM,IAAI,KAAK,CAAC,oCAAoC,GAAG,CAAC,MAAM,MAAM,MAAM,GAAG,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;QACvH,CAAC;QAED,KAAK,CAAC,oBAAoB,CAAC,EAAU;YACnC,MAAM,GAAG,GAAG,MAAM,KAAK,CAAC,GAAG,IAAI,uBAAuB,kBAAkB,CAAC,EAAE,CAAC,UAAU,EAAE;gBACtF,MAAM,EAAE,MAAM,EAAE,OAAO;aACxB,CAAC,CAAC;YACH,IAAI,CAAC,GAAG,CAAC,EAAE;gBAAE,MAAM,IAAI,KAAK,CAAC,qCAAqC,GAAG,CAAC,MAAM,MAAM,MAAM,GAAG,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;YACtH,OAAO,GAAG,CAAC,IAAI,EAAgD,CAAC;QAClE,CAAC;QAED,KAAK,CAAC,qBAAqB,CAAC,EAAU;YACpC,MAAM,GAAG,GAAG,MAAM,KAAK,CAAC,GAAG,IAAI,uBAAuB,kBAAkB,CAAC,EAAE,CAAC,OAAO,EAAE;gBACnF,MAAM,EAAE,MAAM,EAAE,OAAO;aACxB,CAAC,CAAC;YACH,IAAI,CAAC,GAAG,CAAC,EAAE;gBAAE,MAAM,IAAI,KAAK,CAAC,sCAAsC,GAAG,CAAC,MAAM,MAAM,MAAM,GAAG,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;QACzH,CAAC;QAED,KAAK,CAAC,oBAAoB,CAAC,EAAU,EAAE,IAAoE;YACzG,MAAM,GAAG,GAAG,MAAM,KAAK,CAAC,GAAG,IAAI,uBAAuB,kBAAkB,CAAC,EAAE,CAAC,OAAO,EAAE;gBACnF,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC;aACpD,CAAC,CAAC;YACH,IAAI,CAAC,GAAG,CAAC,EAAE;gBAAE,MAAM,IAAI,KAAK,CAAC,qCAAqC,GAAG,CAAC,MAAM,MAAM,MAAM,GAAG,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;QACxH,CAAC;QAED,qEAAqE;QAErE,KAAK,CAAC,mBAAmB;YACvB,MAAM,GAAG,GAAG,MAAM,KAAK,CAAC,GAAG,IAAI,iCAAiC,EAAE,EAAE,OAAO,EAAE,CAAC,CAAC;YAC/E,IAAI,CAAC,GAAG,CAAC,EAAE;gBAAE,MAAM,IAAI,KAAK,CAAC,oCAAoC,GAAG,CAAC,MAAM,MAAM,MAAM,GAAG,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;YACrH,OAAO,GAAG,CAAC,IAAI,EAAwB,CAAC;QAC1C,CAAC;QAED,KAAK,CAAC,oBAAoB,CAAC,MAK1B;YACC,MAAM,GAAG,GAAG,MAAM,KAAK,CAAC,GAAG,IAAI,iCAAiC,EAAE;gBAChE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC;aACtD,CAAC,CAAC;YACH,IAAI,CAAC,GAAG,CAAC,EAAE;gBAAE,MAAM,IAAI,KAAK,CAAC,qCAAqC,GAAG,CAAC,MAAM,MAAM,MAAM,GAAG,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;YACtH,OAAO,GAAG,CAAC,IAAI,EAAE,CAAC;QACpB,CAAC;QAED,KAAK,CAAC,mBAAmB,CAAC,EAAU;YAClC,MAAM,GAAG,GAAG,MAAM,KAAK,CAAC,GAAG,IAAI,mCAAmC,kBAAkB,CAAC,EAAE,CAAC,EAAE,EAAE;gBAC1F,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC;aACpE,CAAC,CAAC;YACH,IAAI,CAAC,GAAG,CAAC,EAAE;gBAAE,MAAM,IAAI,KAAK,CAAC,oCAAoC,GAAG,CAAC,MAAM,MAAM,MAAM,GAAG,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;QACvH,CAAC;QAED,KAAK,CAAC,2BAA2B,CAAC,EAAU;YAC1C,MAAM,GAAG,GAAG,MAAM,KAAK,CAAC,GAAG,IAAI,mCAAmC,kBAAkB,CAAC,EAAE,CAAC,EAAE,EAAE;gBAC1F,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,EAAE,MAAM,EAAE,SAAS,EAAE,CAAC;aACtE,CAAC,CAAC;YACH,IAAI,CAAC,GAAG,CAAC,EAAE;gBAAE,MAAM,IAAI,KAAK,CAAC,4CAA4C,GAAG,CAAC,MAAM,MAAM,MAAM,GAAG,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;QAC/H,CAAC;QAED,qEAAqE;QAErE,KAAK,CAAC,gBAAgB;YACpB,MAAM,GAAG,GAAG,MAAM,KAAK,CAAC,GAAG,IAAI,4BAA4B,EAAE,EAAE,OAAO,EAAE,CAAC,CAAC;YAC1E,IAAI,CAAC,GAAG,CAAC,EAAE;gBAAE,MAAM,IAAI,KAAK,CAAC,iCAAiC,GAAG,CAAC,MAAM,MAAM,MAAM,GAAG,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;YAClH,OAAO,GAAG,CAAC,IAAI,EAAwB,CAAC;QAC1C,CAAC;QAED,KAAK,CAAC,yBAAyB;YAC7B,MAAM,GAAG,GAAG,MAAM,KAAK,CAAC,GAAG,IAAI,mCAAmC,EAAE,EAAE,OAAO,EAAE,CAAC,CAAC;YACjF,IAAI,CAAC,GAAG,CAAC,EAAE;gBAAE,MAAM,IAAI,KAAK,CAAC,0CAA0C,GAAG,CAAC,MAAM,MAAM,MAAM,GAAG,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;YAC3H,OAAO,GAAG,CAAC,IAAI,EAAwB,CAAC;QAC1C,CAAC;KACF,CAAC;AACJ,CAAC"}

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@apex-inc/sdk",
+  "version": "0.1.0",
+  "description": "Apex Growth Intelligence SDK — track events, identify users, and run experiments from any JavaScript runtime.",
+  "main": "dist/index.js",
+  "module": "dist/esm/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/esm/index.js",
+      "require": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": ["dist", "skills"],
+  "scripts": {
+    "build": "tsc && tsc -p tsconfig.esm.json",
+    "dev": "tsc --watch"
+  },
+  "keywords": ["apex", "growth", "analytics", "experiments", "ab-testing", "sdk"],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/apex-inc/sdk"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "typescript": "^5.7.0"
+  }
+}

package/skills/apex-communications/SKILL.md

@@ -0,0 +1,135 @@
+---
+name: apex-communications
+description: Build lifecycle communication programs with Apex — automated emails, push notifications, A/B experiments, and event-driven triggers. Use when setting up user communications, onboarding emails, retention campaigns, or notification programs.
+---
+
+# Apex Communications (SDK)
+
+Apex communications are lifecycle emails and push notifications that fire automatically when users hit key moments — signup, onboarding stall, trial expiring, feature discovery, churn risk. They're auto-generated for your vertical and conversion model, then customizable.
+
+## Quick Start
+
+```typescript
+import { createManagementClient } from "@apex-inc/sdk";
+
+const apex = createManagementClient({
+  projectKey: "proj_abc",
+  apiKey: "apex_ak_...",
+  apiUrl: "https://app.apex.inc",
+});
+
+// 1. Get recommendations for your vertical
+const recs = await apex.recommendCommunications();
+
+// 2. Generate communications from recommendations
+const comms = await apex.generateCommunications(["welcome", "onboarding_reminder", "trial_expiring"]);
+
+// 3. See what events you need to track
+const events = await apex.getEventTaxonomy();
+
+// 4. Preview a communication
+const preview = await apex.previewCommunication("tcomm_welcome");
+```
+
+## The Event Taxonomy
+
+Each vertical has a standard set of events that power communications. After generating your communication program, call `getEventTaxonomy()` to see what events to instrument:
+
+```typescript
+const events = await apex.getEventTaxonomy();
+// Returns: [{ id: "user_signup", name: "User Signup", sdkExample: "apex.track('user_signup', { ... })" }, ...]
+```
+
+Add `apex.track()` calls at each trigger point in your app. Communications fire automatically when the matching event arrives.
+
+## Managing Communications
+
+```typescript
+// List all communications
+const comms = await apex.listCommunications();
+
+// Update copy, channels, or status
+await apex.updateCommunication("tcomm_welcome", {
+  content: { subject: "Welcome to Acme!", slots: { headline: "Let's get started" } },
+  channels: ["email", "in_app_push"],
+  status: "active",
+});
+
+// Send a test
+await apex.sendTestCommunication("tcomm_welcome");
+
+// Trigger for a specific user
+await apex.triggerCommunication("tcomm_welcome", {
+  recipientEmail: "user@example.com",
+  mergeData: { user_name: "Alice" },
+});
+
+// Delete
+await apex.deleteCommunication("tcomm_unused");
+```
+
+## Running Experiments
+
+A/B test any communication's subject, body, CTA, or full content with Thompson Sampling:
+
+```typescript
+// Create an experiment
+const exp = await apex.createCommExperiment({
+  communicationId: "tcomm_welcome",
+  splitLevel: "subject",
+  funnelGoal: "onboarding_complete",
+  variants: [
+    { name: "Control", subjectOverride: "Welcome to Acme" },
+    { name: "Personal", subjectOverride: "Alice, welcome to Acme" },
+  ],
+});
+
+// Start it
+await apex.startCommExperiment(exp.id);
+
+// Check results
+const experiments = await apex.listCommExperiments();
+
+// Promote the winner
+await apex.promoteCommExperimentWinner(exp.id);
+```
+
+## Integration Patterns
+
+### Next.js (App Router)
+
+```typescript
+// app/api/auth/signup/route.ts
+import { apex } from "@/lib/apex";
+
+export async function POST(req) {
+  const user = await createUser(req);
+  apex.track("user_signup", { userId: user.id, email: user.email });
+  apex.identify(user.email, { name: user.name });
+  return Response.json(user);
+}
+```
+
+### Express
+
+```typescript
+app.post("/api/purchase", async (req, res) => {
+  const order = await processOrder(req.body);
+  apex.track("purchase_complete", {
+    orderId: order.id,
+    amount: order.total,
+    userId: req.user.id,
+  });
+  res.json(order);
+});
+```
+
+### Event Checklist
+
+After setting up communications, verify these events are tracked:
+
+1. `user_signup` — fires once per new user
+2. `onboarding_complete` — fires when the user finishes setup
+3. `feature_used` — fires on first or repeated feature interaction
+4. `purchase_complete` — fires on conversion
+5. Check `getEventIntegrationStatus()` to see which events Apex has received