@apex-inc/sdk 0.1.1 → 0.6.0

package/dist/esm/management.js

@@ -1,6 +1,6 @@
 /**
  * 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.
+ * Intended for Node.js backends; sends x-api-key and x-apex-workspace on each request.
  */
 function baseUrl(cfg) {
     return (cfg.apiUrl ?? "http://localhost:3000").replace(/\/$/, "");
@@ -9,7 +9,7 @@ function keyHeaders(cfg) {
     return {
         "Content-Type": "application/json",
         "x-api-key": cfg.apiKey,
-        "x-apex-project": cfg.projectKey,
+        "x-apex-workspace": cfg.workspaceKey,
     };
 }
 /**
@@ -31,7 +31,7 @@ export function createManagementClient(cfg) {
         async assignVariant(experimentId, visitorId) {
             const cookie = [
                 `apex_vid=${encodeURIComponent(visitorId)}`,
-                `apex_project=${encodeURIComponent(cfg.projectKey)}`,
+                `apex_project=${encodeURIComponent(cfg.workspaceKey)}`,
             ].join("; ");
             const res = await fetch(`${root}/api/experiments/${encodeURIComponent(experimentId)}/assign`, {
                 headers: { ...headers, Cookie: cookie },
@@ -42,7 +42,49 @@ export function createManagementClient(cfg) {
             }
             return res.json();
         },
+        /** Fetch a single experiment (unified shape). */
+        async getExperiment(id) {
+            const res = await fetch(`${root}/api/experiments/${encodeURIComponent(id)}?unified=true`, { headers });
+            if (!res.ok)
+                throw new Error(`Apex getExperiment failed (${res.status}): ${await res.text().catch(() => "")}`);
+            return res.json();
+        },
+        /**
+         * Computed results + the shared readiness verdict
+         * (collecting | decisive | inconclusive | guardrail) for any surface.
+         */
+        async getExperimentResults(id) {
+            const res = await fetch(`${root}/api/experiments/${encodeURIComponent(id)}/results`, { headers });
+            if (!res.ok)
+                throw new Error(`Apex getExperimentResults failed (${res.status}): ${await res.text().catch(() => "")}`);
+            return res.json();
+        },
+        /**
+         * Promote the experiment's winner (re-verifies the readiness gate
+         * server-side; pass `force` to override). Winner content is written into
+         * the canonical communication as a new version.
+         */
+        async promoteExperiment(id, opts) {
+            const res = await fetch(`${root}/api/experiments/${encodeURIComponent(id)}/promote`, { method: "POST", headers, body: JSON.stringify(opts ?? {}) });
+            if (!res.ok)
+                throw new Error(`Apex promoteExperiment failed (${res.status}): ${await res.text().catch(() => "")}`);
+            return res.json();
+        },
         // ─── Communications ───────────────────────────────────────────────
+        /** Append a content variant to a communication (composer-columns model; an experiment arm). */
+        async createCommVariant(commId, opts) {
+            const res = await fetch(`${root}/api/communications/${encodeURIComponent(commId)}/variants`, { method: "POST", headers, body: JSON.stringify(opts ?? {}) });
+            if (!res.ok)
+                throw new Error(`Apex createCommVariant failed (${res.status}): ${await res.text().catch(() => "")}`);
+            return res.json();
+        },
+        /** List the content variants (`content.variants[]`) of a communication. */
+        async listCommVariants(commId) {
+            const res = await fetch(`${root}/api/communications/${encodeURIComponent(commId)}/variants`, { headers });
+            if (!res.ok)
+                throw new Error(`Apex listCommVariants failed (${res.status}): ${await res.text().catch(() => "")}`);
+            return res.json();
+        },
         async recommendCommunications() {
             const res = await fetch(`${root}/api/communications/recommend`, { method: "POST", headers });
             if (!res.ok)
@@ -148,5 +190,355 @@ export function createManagementClient(cfg) {
                 throw new Error(`Apex getEventIntegrationStatus failed (${res.status}): ${await res.text().catch(() => "")}`);
             return res.json();
         },
+        // ─── Partner Network — Programs (MMP-161) ─────────────────────────
+        //
+        // Every method below runs under the merchant's x-apex-workspace scope.
+        // Partner-facing flows (self-signup, dashboard, Stripe Connect OAuth)
+        // are cookie-authed in the portal and not wrapped in this SDK.
+        async listPrograms() {
+            const res = await fetch(`${root}/api/mobile/affiliates/programs`, { headers });
+            if (!res.ok)
+                throw new Error(`Apex listPrograms failed (${res.status}): ${await res.text().catch(() => "")}`);
+            return res.json();
+        },
+        async createProgram(params) {
+            const res = await fetch(`${root}/api/mobile/affiliates/programs`, {
+                method: "POST",
+                headers,
+                body: JSON.stringify(params),
+            });
+            if (!res.ok)
+                throw new Error(`Apex createProgram failed (${res.status}): ${await res.text().catch(() => "")}`);
+            return res.json();
+        },
+        async updateProgram(programId, updates) {
+            const res = await fetch(`${root}/api/mobile/affiliates/programs/${encodeURIComponent(programId)}`, {
+                method: "PATCH",
+                headers,
+                body: JSON.stringify(updates),
+            });
+            if (!res.ok)
+                throw new Error(`Apex updateProgram failed (${res.status}): ${await res.text().catch(() => "")}`);
+            return res.json();
+        },
+        async listProgramMembers(programId) {
+            const res = await fetch(`${root}/api/mobile/affiliates/programs/${encodeURIComponent(programId)}/members`, { headers });
+            if (!res.ok)
+                throw new Error(`Apex listProgramMembers failed (${res.status}): ${await res.text().catch(() => "")}`);
+            return res.json();
+        },
+        /** Apply program default commission to every existing member (respects overrides). */
+        async applyProgramDefaultToMembers(programId) {
+            const res = await fetch(`${root}/api/mobile/affiliates/programs/${encodeURIComponent(programId)}/apply-to-members`, {
+                method: "POST",
+                headers,
+            });
+            if (!res.ok)
+                throw new Error(`Apex applyProgramDefaultToMembers failed (${res.status}): ${await res.text().catch(() => "")}`);
+            return res.json();
+        },
+        // ─── Partner Network — Rate overrides ─────────────────────────────
+        /** Override a single membership's commission (sticky — survives program default updates). */
+        async updateMembershipRate(profileId, params) {
+            const res = await fetch(`${root}/api/mobile/affiliates/memberships/${encodeURIComponent(profileId)}/rate`, {
+                method: "POST",
+                headers,
+                body: JSON.stringify(params),
+            });
+            if (!res.ok)
+                throw new Error(`Apex updateMembershipRate failed (${res.status}): ${await res.text().catch(() => "")}`);
+            return res.json();
+        },
+        /** Reset a membership back to its program's default commission. */
+        async resetMembershipRate(profileId, reason) {
+            const res = await fetch(`${root}/api/mobile/affiliates/memberships/${encodeURIComponent(profileId)}/rate`, {
+                method: "POST",
+                headers,
+                body: JSON.stringify({ reset: true, reason }),
+            });
+            if (!res.ok)
+                throw new Error(`Apex resetMembershipRate failed (${res.status}): ${await res.text().catch(() => "")}`);
+            return res.json();
+        },
+        // ─── Partner Network — Invitations ────────────────────────────────
+        /** Send a magic-link invite to a partner (email resolves to existing profile or creates pending). */
+        async invitePartner(params) {
+            const res = await fetch(`${root}/api/mobile/affiliates/invites`, {
+                method: "POST",
+                headers,
+                body: JSON.stringify(params),
+            });
+            if (!res.ok)
+                throw new Error(`Apex invitePartner failed (${res.status}): ${await res.text().catch(() => "")}`);
+            return res.json();
+        },
+        // ─── Partner Network — Payouts (MMP-145 + MMP-151) ────────────────
+        /** Pending payouts grouped into aging buckets (0-30, 30-60, 60+). */
+        async listPendingPayouts() {
+            const res = await fetch(`${root}/api/mobile/affiliates/payouts/pending`, { headers });
+            if (!res.ok)
+                throw new Error(`Apex listPendingPayouts failed (${res.status}): ${await res.text().catch(() => "")}`);
+            return res.json();
+        },
+        /** Approve one or more pending payouts (creates HoldbackEntry per approved conversion). */
+        async approvePayouts(conversionIds) {
+            const res = await fetch(`${root}/api/mobile/affiliates/payouts/approve`, {
+                method: "POST",
+                headers,
+                body: JSON.stringify({ conversionIds }),
+            });
+            if (!res.ok)
+                throw new Error(`Apex approvePayouts failed (${res.status}): ${await res.text().catch(() => "")}`);
+            return res.json();
+        },
+        /** Reject pending payouts (opens an audit FraudCase severity=low). */
+        async rejectPayouts(conversionIds, reason) {
+            const res = await fetch(`${root}/api/mobile/affiliates/payouts/reject`, {
+                method: "POST",
+                headers,
+                body: JSON.stringify({ conversionIds, reason }),
+            });
+            if (!res.ok)
+                throw new Error(`Apex rejectPayouts failed (${res.status}): ${await res.text().catch(() => "")}`);
+            return res.json();
+        },
+        // ─── Partner Network — Fees (MMP-158) ─────────────────────────────
+        /** Merchant-facing fee disclosure. Returns every fee kind Apex charges this merchant. */
+        async getEffectiveFees() {
+            const res = await fetch(`${root}/api/mobile/affiliates/fees`, { headers });
+            if (!res.ok)
+                throw new Error(`Apex getEffectiveFees failed (${res.status}): ${await res.text().catch(() => "")}`);
+            return res.json();
+        },
+        // ─── Partner Network — Vouch (MMP-156) ────────────────────────────
+        /**
+         * Vouch for a partner — one-tier bump for 60 days. Requires indemnity
+         * acknowledgment. Fails if the partner is already verified.
+         */
+        async vouchForPartner(profileId, params) {
+            const res = await fetch(`${root}/api/mobile/affiliates/${encodeURIComponent(profileId)}/vouch`, {
+                method: "POST",
+                headers,
+                body: JSON.stringify(params),
+            });
+            if (!res.ok)
+                throw new Error(`Apex vouchForPartner failed (${res.status}): ${await res.text().catch(() => "")}`);
+            return res.json();
+        },
+        // ─── Communications — end-user preferences (DFC-016) ─────────────────
+        //
+        // Two API-key methods for managing an end-user's communication
+        // preferences from the customer's backend. `preferences.get` and
+        // `preferences.update` proxy `/api/communications/preferences/[id]`
+        // with the org-scoped key — the route's dual-auth layer treats the
+        // API-key caller as a trusted server.
+        preferences: {
+            async get(endUserId) {
+                const res = await fetch(`${root}/api/communications/preferences/${encodeURIComponent(endUserId)}?workspaceKey=${encodeURIComponent(cfg.workspaceKey)}`, { headers });
+                if (!res.ok) {
+                    throw new Error(`Apex preferences.get failed (${res.status}): ${await res.text().catch(() => "")}`);
+                }
+                return res.json();
+            },
+            async update(endUserId, patch) {
+                const res = await fetch(`${root}/api/communications/preferences/${encodeURIComponent(endUserId)}?workspaceKey=${encodeURIComponent(cfg.workspaceKey)}`, {
+                    method: "PATCH",
+                    headers,
+                    body: JSON.stringify(patch),
+                });
+                if (!res.ok) {
+                    throw new Error(`Apex preferences.update failed (${res.status}): ${await res.text().catch(() => "")}`);
+                }
+                return res.json();
+            },
+        },
+        // ─── Communications — inbox notifications (DFC-016) ──────────────────
+        //
+        // Read + write helpers for the in-app inbox. The `mark-read` and
+        // `mark-all-read` paths target the existing PATCH route on the
+        // workspace-admin gate (the SDK's API key satisfies that gate).
+        notifications: {
+            async list(endUserId, opts) {
+                const qs = new URLSearchParams({ userId: endUserId });
+                if (opts?.limit)
+                    qs.set("limit", String(opts.limit));
+                if (opts?.unreadOnly)
+                    qs.set("unreadOnly", "true");
+                const res = await fetch(`${root}/api/communications/notifications?${qs.toString()}`, { headers });
+                if (!res.ok) {
+                    throw new Error(`Apex notifications.list failed (${res.status}): ${await res.text().catch(() => "")}`);
+                }
+                return res.json();
+            },
+            async markRead(notificationId) {
+                const res = await fetch(`${root}/api/communications/notifications`, {
+                    method: "PATCH",
+                    headers,
+                    body: JSON.stringify({ notificationId }),
+                });
+                if (!res.ok) {
+                    throw new Error(`Apex notifications.markRead failed (${res.status}): ${await res.text().catch(() => "")}`);
+                }
+            },
+            async markAllRead(endUserId) {
+                const res = await fetch(`${root}/api/communications/notifications`, {
+                    method: "PATCH",
+                    headers,
+                    body: JSON.stringify({ markAll: true, endUserId }),
+                });
+                if (!res.ok) {
+                    throw new Error(`Apex notifications.markAllRead failed (${res.status}): ${await res.text().catch(() => "")}`);
+                }
+            },
+        },
+        // ─── Communications — end-user token mint (DFC-018) ──────────────────
+        //
+        // Server-side helper that asks Apex to sign an HMAC end-user token
+        // for the customer's client. The signing key lives on Apex servers
+        // only, so this is the canonical path. Customers call this from
+        // their backend, then hand the token to <ApexPreferenceCenter>.
+        /**
+         * Set up Apex — programmatic access to per-workspace setup state.
+         *
+         * `get()` returns the current hub signal + per-step overrides
+         * (read-only). `complete(stepId)` / `skip(stepId, reason)` mirror
+         * the dashboard's write contract at
+         * POST /api/workspaces/<workspaceKey>/setup-state/<stepId>.
+         *
+         * Allowed step IDs are enforced server-side via the SetupRegistry
+         * allowlist. Unknown IDs return 400.
+         */
+        workspace: {
+            setupState: {
+                async get() {
+                    const res = await fetch(`${root}/api/workspaces/${encodeURIComponent(cfg.workspaceKey)}/setup-state`, { headers });
+                    if (!res.ok) {
+                        throw new Error(`Apex workspace.setupState.get failed (${res.status}): ${await res.text().catch(() => "")}`);
+                    }
+                    const json = (await res.json());
+                    return {
+                        overrides: json.overrides ?? [],
+                        signal: json.signal ?? {},
+                    };
+                },
+                async complete(stepId) {
+                    const res = await fetch(`${root}/api/workspaces/${encodeURIComponent(cfg.workspaceKey)}/setup-state/${encodeURIComponent(stepId)}/complete`, { method: "POST", headers });
+                    if (!res.ok) {
+                        throw new Error(`Apex workspace.setupState.complete failed (${res.status}): ${await res.text().catch(() => "")}`);
+                    }
+                },
+                async skip(stepId, reason) {
+                    const res = await fetch(`${root}/api/workspaces/${encodeURIComponent(cfg.workspaceKey)}/setup-state/${encodeURIComponent(stepId)}/skip`, {
+                        method: "POST",
+                        headers,
+                        body: JSON.stringify({ reason: reason ?? null }),
+                    });
+                    if (!res.ok) {
+                        throw new Error(`Apex workspace.setupState.skip failed (${res.status}): ${await res.text().catch(() => "")}`);
+                    }
+                },
+            },
+        },
+        /**
+         * Data Sources registry — the producers that send events into this
+         * workspace (Website, iOS / Android apps, Backend). Mirrors
+         * /api/workspaces/<workspaceKey>/data-sources. `dataSourceId` is
+         * reporting-only; these methods manage the registry, not access control.
+         */
+        dataSources: {
+            async list(opts) {
+                const qs = opts?.includeArchived ? "?includeArchived=true" : "";
+                const res = await fetch(`${root}/api/workspaces/${encodeURIComponent(cfg.workspaceKey)}/data-sources${qs}`, { headers });
+                if (!res.ok) {
+                    throw new Error(`Apex dataSources.list failed (${res.status}): ${await res.text().catch(() => "")}`);
+                }
+                const json = (await res.json());
+                return json.data ?? [];
+            },
+            async get(id) {
+                const res = await fetch(`${root}/api/workspaces/${encodeURIComponent(cfg.workspaceKey)}/data-sources/${encodeURIComponent(id)}`, { headers });
+                if (!res.ok) {
+                    throw new Error(`Apex dataSources.get failed (${res.status}): ${await res.text().catch(() => "")}`);
+                }
+                const json = (await res.json());
+                return json.data;
+            },
+            async create(params) {
+                const res = await fetch(`${root}/api/workspaces/${encodeURIComponent(cfg.workspaceKey)}/data-sources`, { method: "POST", headers, body: JSON.stringify(params) });
+                if (!res.ok) {
+                    throw new Error(`Apex dataSources.create failed (${res.status}): ${await res.text().catch(() => "")}`);
+                }
+                const json = (await res.json());
+                return json.data;
+            },
+            async update(id, patch) {
+                const res = await fetch(`${root}/api/workspaces/${encodeURIComponent(cfg.workspaceKey)}/data-sources/${encodeURIComponent(id)}`, { method: "PATCH", headers, body: JSON.stringify(patch) });
+                if (!res.ok) {
+                    throw new Error(`Apex dataSources.update failed (${res.status}): ${await res.text().catch(() => "")}`);
+                }
+                const json = (await res.json());
+                return json.data;
+            },
+            async archive(id) {
+                const res = await fetch(`${root}/api/workspaces/${encodeURIComponent(cfg.workspaceKey)}/data-sources/${encodeURIComponent(id)}`, { method: "DELETE", headers });
+                if (!res.ok) {
+                    throw new Error(`Apex dataSources.archive failed (${res.status}): ${await res.text().catch(() => "")}`);
+                }
+            },
+            async health(id) {
+                const res = await fetch(`${root}/api/workspaces/${encodeURIComponent(cfg.workspaceKey)}/data-sources/${encodeURIComponent(id)}/health`, { headers });
+                if (!res.ok) {
+                    throw new Error(`Apex dataSources.health failed (${res.status}): ${await res.text().catch(() => "")}`);
+                }
+                const json = (await res.json());
+                return json.data;
+            },
+        },
+        /**
+         * Unified analytics reads — per-source / per-platform / per-hostname
+         * breakdowns from the ingest-maintained rollups. Honors the source/
+         * platform/hostname/range filters the dashboard exposes.
+         */
+        analytics: {
+            async sources(opts) {
+                const qs = new URLSearchParams();
+                if (opts?.days)
+                    qs.set("days", String(opts.days));
+                if (opts?.source)
+                    qs.set("source", opts.source);
+                const suffix = qs.toString() ? `?${qs}` : "";
+                const res = await fetch(`${root}/api/analytics/sources${suffix}`, {
+                    headers,
+                });
+                if (!res.ok) {
+                    throw new Error(`Apex analytics.sources failed (${res.status}): ${await res.text().catch(() => "")}`);
+                }
+                const json = (await res.json());
+                return json.data;
+            },
+            async hostnames(opts) {
+                const qs = opts?.limit ? `?limit=${opts.limit}` : "";
+                const res = await fetch(`${root}/api/analytics/hostnames${qs}`, {
+                    headers,
+                });
+                if (!res.ok) {
+                    throw new Error(`Apex analytics.hostnames failed (${res.status}): ${await res.text().catch(() => "")}`);
+                }
+                const json = (await res.json());
+                return json.data ?? [];
+            },
+        },
+        async signEndUserToken(params) {
+            const res = await fetch(`${root}/api/v1/tokens/end-user`, {
+                method: "POST",
+                headers,
+                body: JSON.stringify(params),
+            });
+            if (!res.ok) {
+                throw new Error(`Apex signEndUserToken failed (${res.status}): ${await res.text().catch(() => "")}`);
+            }
+            const json = (await res.json());
+            return json.data;
+        },
     };
 }

package/dist/esm/plg-events.js

@@ -0,0 +1,45 @@
+/**
+ * MWO-009 — Apex PLG Event Catalog.
+ *
+ * Curated, typed event schemas for the eight most common PLG
+ * lifecycle moments. Customers import these interfaces directly so
+ * their `apex.track()` calls type-check end-to-end, and the Apex
+ * dashboard uses them to derive activation / expansion / retention
+ * rollups without bespoke queries per customer.
+ *
+ *   import { EVENTS, type ActivatedEvent } from "@apex-inc/sdk/plg-events";
+ *   apex.track(EVENTS.ACTIVATED, { daysToActivation: 2 } satisfies ActivatedEvent);
+ *
+ * Adding a new event:
+ *   1. Add its name to `EVENTS`.
+ *   2. Add its typed interface below.
+ *   3. Update the doc page at /docs/plg-event-catalog (Phase 10).
+ *
+ * Every event is optional. There's no requirement that a customer
+ * emit any of these — the catalog is a convention, not a gate.
+ * Archived event definitions (Phase 8 follow-up) will stop deriving
+ * new rollups but preserve their historical data.
+ */
+export const EVENTS = {
+    SIGNUP: "signup",
+    ACTIVATED: "activated",
+    FEATURE_FIRST_USE: "feature_first_use",
+    AHA_MOMENT: "aha_moment",
+    EXPANSION: "expansion",
+    CONTRACTION: "contraction",
+    REACTIVATION: "reactivation",
+    CHURN: "churn",
+};
+/**
+ * Typed `apex.track` wrapper specific to PLG events. Not a hard gate —
+ * `apex.track()` still accepts any event name — but gives customers
+ * compile-time safety on the curated set.
+ */
+export function trackPlgEvent(_apex, name, payload) {
+    _apex.track(name, payload);
+}
+/**
+ * Read-only exhaustive list of the catalog. Handy for UI surfaces
+ * that need to render "all PLG events we know about."
+ */
+export const ALL_PLG_EVENTS = Object.values(EVENTS);