@apex-inc/sdk 0.8.0 → 0.10.0

package/README.md

@@ -30,6 +30,21 @@ identify("user_123", { email: "jane@example.com" });
 track("page_viewed", { path: "/pricing" });
 ```
 
+### Profile photos (`avatar_url`)
+
+Pass `avatar_url` in traits to show end-user photos across Apex — the
+Customers list, customer detail pages, and the Live Customers widget. It's a
+[canonical attribute](https://app.apex.inc/docs/concepts/schema), so
+`photoUrl` / `image` / `profile_image` map to it too. Apex validates on write
+(https only) and falls back to colored initials when absent.
+
+```typescript
+identify("user_123", {
+  email: "jane@example.com",
+  avatar_url: user.photoURL, // OIDC `picture` claim works the same way
+});
+```
+
 ## PLG primitives
 
 In addition to `track` / `identify` the SDK exposes three PLG-specific

package/dist/esm/generated/event-payloads.js

@@ -0,0 +1,11 @@
+/**
+ * GENERATED FILE — DO NOT EDIT BY HAND.
+ *
+ * Typed Apex event payloads, generated from the Apex Spec registries by
+ * `app/scripts/generate-spec-types.ts`. Regenerate with:
+ *
+ *   npx tsx app/scripts/generate-spec-types.ts
+ *
+ * The `codegen.test.ts` stale gate fails CI if this drifts from the spec.
+ */
+export {};

package/dist/esm/generated/trait-types.js

@@ -0,0 +1,11 @@
+/**
+ * GENERATED FILE — DO NOT EDIT BY HAND.
+ *
+ * Typed Apex identify() traits, generated from the Apex Spec attribute
+ * registry by `app/scripts/generate-spec-types.ts`. Regenerate with:
+ *
+ *   npx tsx app/scripts/generate-spec-types.ts
+ *
+ * The `codegen.test.ts` stale gate fails CI if this drifts from the spec.
+ */
+export {};

package/dist/esm/management.js

@@ -28,6 +28,136 @@ export function createManagementClient(cfg) {
             }
             return res.json();
         },
+        /**
+         * "Is our growth real?" — per-goal cumulative lift (journeys + experiments)
+         * vs the do-nothing global holdout, with 95% CIs. Forward-only; goals still
+         * collecting are flagged `isDecisive: false`. (Is Our Growth Real, Phase 4.)
+         */
+        async getGrowthReality(opts) {
+            const days = opts?.days ?? "all";
+            const res = await fetch(`${root}/api/growth/reality?days=${days}`, { headers });
+            if (!res.ok) {
+                const text = await res.text().catch(() => "");
+                throw new Error(`Apex getGrowthReality failed (${res.status}): ${text}`);
+            }
+            return res.json();
+        },
+        /**
+         * Channel Economics Cockpit (Layer 1) — gross-margin-adjusted LTV:CAC,
+         * payback, and per-channel cohort curves by acquisition channel (raw
+         * first-touch), plus a directional multi-touch lens. Reads real contacts +
+         * spend + revenue; metrics with missing inputs come back null, never
+         * fabricated. `days` defaults to all-time. Wraps GET /api/channels/economics.
+         */
+        async getChannelEconomics(opts) {
+            const days = opts?.days ?? "all";
+            const res = await fetch(`${root}/api/channels/economics?days=${days}`, { headers });
+            if (!res.ok) {
+                const text = await res.text().catch(() => "");
+                throw new Error(`Apex getChannelEconomics failed (${res.status}): ${text}`);
+            }
+            return res.json();
+        },
+        // ─── Vertical Widget Packs read surface (2026-07-02) ─────────────────
+        // Thin wrappers over the pack read APIs. Param names match the API
+        // query params exactly (shipped params ARE the SDK signature). All
+        // endpoints require the `analytics:read` API-key scope; responses
+        // apply the same small-n suppression as the dashboard widgets.
+        /**
+         * SaaS pack — MRR / ARR / monthly waterfall (new / expansion /
+         * reactivation / contraction / churn) + NRR / GRR for the last
+         * complete month, from materialized monthly snapshots (UTC calendar
+         * months; the current month is flagged `inProgress`). Wraps
+         * GET /api/saas/recurring-revenue.
+         */
+        async getSaasRecurringRevenue(opts) {
+            const q = opts?.months ? `?months=${opts.months}` : "";
+            const res = await fetch(`${root}/api/saas/recurring-revenue${q}`, { headers });
+            if (!res.ok) {
+                const text = await res.text().catch(() => "");
+                throw new Error(`Apex getSaasRecurringRevenue failed (${res.status}): ${text}`);
+            }
+            return res.json();
+        },
+        /**
+         * SaaS pack — expansion vs contraction MRR, expanded-account counts,
+         * and seat growth. Wraps GET /api/saas/expansion.
+         */
+        async getSaasExpansion(opts) {
+            const q = opts?.months ? `?months=${opts.months}` : "";
+            const res = await fetch(`${root}/api/saas/expansion${q}`, { headers });
+            if (!res.ok) {
+                const text = await res.text().catch(() => "");
+                throw new Error(`Apex getSaasExpansion failed (${res.status}): ${text}`);
+            }
+            return res.json();
+        },
+        /**
+         * DTC pack — per-product funnel (views → adds → purchases → refunds)
+         * via the shared item aggregator. Wraps GET /api/dtc/merchandising.
+         */
+        async getDtcMerchandising(opts) {
+            const q = opts?.days ? `?days=${opts.days}` : "";
+            const res = await fetch(`${root}/api/dtc/merchandising${q}`, { headers });
+            if (!res.ok) {
+                const text = await res.text().catch(() => "");
+                throw new Error(`Apex getDtcMerchandising failed (${res.status}): ${text}`);
+            }
+            return res.json();
+        },
+        /**
+         * DTC pack — refund rate (money back) and return rate (goods back —
+         * separate metrics, never summed), reasons, refund cycle time, AOV,
+         * repeat purchase. Wraps GET /api/dtc/returns.
+         */
+        async getDtcReturns(opts) {
+            const q = opts?.days ? `?days=${opts.days}` : "";
+            const res = await fetch(`${root}/api/dtc/returns${q}`, { headers });
+            if (!res.ok) {
+                const text = await res.text().catch(() => "");
+                throw new Error(`Apex getDtcReturns failed (${res.status}): ${text}`);
+            }
+            return res.json();
+        },
+        /**
+         * Marketplace pack — the six pillars (liquidity, supply & demand,
+         * economics GMV-vs-take, retention, trust, concentration), sliceable
+         * by category / geo / price_band. Low-volume slices are suppressed
+         * (k-anonymity floor). Wraps GET /api/marketplace/metrics.
+         */
+        async getMarketplaceMetrics(opts) {
+            const params = new URLSearchParams();
+            if (opts?.days)
+                params.set("days", String(opts.days));
+            if (opts?.category)
+                params.set("category", opts.category);
+            if (opts?.geo)
+                params.set("geo", opts.geo);
+            if (opts?.price_band)
+                params.set("price_band", opts.price_band);
+            const qs = params.toString();
+            const res = await fetch(`${root}/api/marketplace/metrics${qs ? `?${qs}` : ""}`, { headers });
+            if (!res.ok) {
+                const text = await res.text().catch(() => "");
+                throw new Error(`Apex getMarketplaceMetrics failed (${res.status}): ${text}`);
+            }
+            return res.json();
+        },
+        /**
+         * Agency pack — per-client (= linked workspace) spend, revenue, ROI,
+         * MoM series, and the transparent at-risk rule. NOTE: this endpoint is
+         * a FINANCIAL boundary gated to org owner/admin SESSIONS (no API-key
+         * lane yet — CISO decision 2026-07-02); calling it with an API key
+         * returns 401/403. Wraps GET /api/agency/clients.
+         */
+        async getClientPortfolio(opts) {
+            const res = await fetch(`${root}/api/agency/clients?orgId=${encodeURIComponent(opts.orgId)}`, { headers });
+            if (!res.ok) {
+                const text = await res.text().catch(() => "");
+                throw new Error(`Apex getClientPortfolio failed (${res.status}): ${text}`);
+            }
+            return res.json();
+        },
         async assignVariant(experimentId, visitorId) {
             const cookie = [
                 `apex_vid=${encodeURIComponent(visitorId)}`,
@@ -70,6 +200,99 @@ export function createManagementClient(cfg) {
                 throw new Error(`Apex promoteExperiment failed (${res.status}): ${await res.text().catch(() => "")}`);
             return res.json();
         },
+        // ─── Conversions (Goals & Conversions Convergence) ────────────────
+        //
+        // A Conversion is the merchant's owned-event definition of a valued
+        // action ("Purchase", "Signup"). One workspace registry, one
+        // `isPrimary`. Experiments and journeys reference a Conversion's
+        // owned-event source as their objective; the headline funnel and
+        // scoring use the primary one. These wrap the same `/api/conversion-goals`
+        // endpoints the dashboard + MCP server use.
+        conversions: {
+            /** List the workspace's owned-event Conversions (archived excluded by default). */
+            async list(opts) {
+                const res = await fetch(`${root}/api/conversion-goals`, { headers });
+                if (!res.ok)
+                    throw new Error(`Apex conversions.list failed (${res.status}): ${await res.text().catch(() => "")}`);
+                const json = (await res.json());
+                const all = Array.isArray(json) ? json : [];
+                return opts?.includeArchived ? all : all.filter((c) => !c.archivedAt);
+            },
+            /**
+             * Define a new owned-event Conversion. `custom_event` (with `eventName`)
+             * is the most common shape and matches an Apex Spec event sent via track.
+             * Set `isPrimary` to make it the default experiment objective + headline metric.
+             */
+            async create(params) {
+                const body = {
+                    name: params.name,
+                    type: params.type,
+                    metricType: "binary",
+                    isPrimary: params.isPrimary ?? false,
+                    ...(params.eventName ? { eventName: params.eventName } : {}),
+                    ...(params.selector ? { selector: params.selector } : {}),
+                    ...(params.targetUrl ? { targetUrl: params.targetUrl } : {}),
+                };
+                const res = await fetch(`${root}/api/conversion-goals`, {
+                    method: "POST", headers, body: JSON.stringify(body),
+                });
+                if (!res.ok)
+                    throw new Error(`Apex conversions.create failed (${res.status}): ${await res.text().catch(() => "")}`);
+                return res.json();
+            },
+            /** Promote a Conversion to primary (only one can be primary at a time). */
+            async setPrimary(conversionId) {
+                const res = await fetch(`${root}/api/conversion-goals`, {
+                    method: "PATCH", headers, body: JSON.stringify({ id: conversionId, isPrimary: true }),
+                });
+                if (!res.ok)
+                    throw new Error(`Apex conversions.setPrimary failed (${res.status}): ${await res.text().catch(() => "")}`);
+                return res.json();
+            },
+        },
+        // ─── Targets (Goals & Conversions Convergence) ────────────────────
+        //
+        // A Target is an aggregate KPI number to hit by a date (MRR, pipeline,
+        // "1,000 signups by Q3"). Bind one to a Conversion via
+        // `sourceConversionId` to auto-count progress from that conversion's
+        // owned-event completions; otherwise `current` is a manual number.
+        // `currentIsAuto` flags an auto-computed value; `sourceMissing` flags a
+        // bound Conversion that has since been archived. Wraps `/api/targets`.
+        targets: {
+            async list() {
+                const res = await fetch(`${root}/api/targets`, { headers });
+                if (!res.ok)
+                    throw new Error(`Apex targets.list failed (${res.status}): ${await res.text().catch(() => "")}`);
+                const json = (await res.json());
+                if (Array.isArray(json))
+                    return json;
+                return json.data ?? [];
+            },
+            async create(params) {
+                const res = await fetch(`${root}/api/targets`, {
+                    method: "POST", headers, body: JSON.stringify(params),
+                });
+                if (!res.ok)
+                    throw new Error(`Apex targets.create failed (${res.status}): ${await res.text().catch(() => "")}`);
+                return res.json();
+            },
+            /** Patch a Target. Pass `sourceConversionId: null` to unbind (back to manual). */
+            async update(id, patch) {
+                const res = await fetch(`${root}/api/targets`, {
+                    method: "PATCH", headers, body: JSON.stringify({ id, ...patch }),
+                });
+                if (!res.ok)
+                    throw new Error(`Apex targets.update failed (${res.status}): ${await res.text().catch(() => "")}`);
+                return res.json();
+            },
+            async delete(id) {
+                const res = await fetch(`${root}/api/targets?id=${encodeURIComponent(id)}`, {
+                    method: "DELETE", headers,
+                });
+                if (!res.ok)
+                    throw new Error(`Apex targets.delete failed (${res.status}): ${await res.text().catch(() => "")}`);
+            },
+        },
         // ─── Communications ───────────────────────────────────────────────
         /** Append a content variant to a communication (composer-columns model; an experiment arm). */
         async createCommVariant(commId, opts) {