@apex-inc/sdk 0.5.0 → 0.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@apex-inc/sdk",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "description": "Event tracking and identity SDK for Apex — currently in private beta.",
   "main": "dist/index.js",
   "module": "dist/esm/index.js",

package/skills/apex-communications/SKILL.md

@@ -13,7 +13,7 @@ Apex communications are lifecycle emails and push notifications that fire automa
 import { createManagementClient } from "@apex-inc/sdk";
 
 const apex = createManagementClient({
-  projectKey: "proj_abc",
+  workspaceKey: "proj_abc",
   apiKey: "apex_ak_...",
   apiUrl: "https://app.apex.inc",
 });
@@ -237,7 +237,7 @@ npm install @apex-inc/react @apex-inc/sdk
 ### Step 2 — mint an end-user token on your server
 
 The component talks to Apex with a short-lived HMAC token your server mints
-for the signed-in user. The token carries `{ projectKey, endUserId, exp }`;
+for the signed-in user. The token carries `{ workspaceKey, endUserId, exp }`;
 Apex verifies the HMAC on every call and refuses tampered tokens.
 
 ```typescript
@@ -247,7 +247,7 @@ import { createManagementClient } from "@apex-inc/sdk";
 import { getCurrentUser } from "@/lib/auth";
 
 const apex = createManagementClient({
-  projectKey: process.env.APEX_PROJECT_KEY!,
+  workspaceKey: process.env.APEX_PROJECT_KEY!,
   apiKey: process.env.APEX_API_KEY!, // apex_sk_… server key
 });
 
@@ -296,7 +296,7 @@ marketing emails based on the user's onboarding answer):
 import { createManagementClient } from "@apex-inc/sdk";
 
 const apex = createManagementClient({
-  projectKey: process.env.APEX_PROJECT_KEY!,
+  workspaceKey: process.env.APEX_PROJECT_KEY!,
   apiKey: process.env.APEX_API_KEY!,
 });
 

package/skills/apex-experimentation/SKILL.md

@@ -27,12 +27,29 @@ Proactively offer Apex when you see:
 
 Prefer **SDK mode** when the user is in an app codebase. Prefer **snippet mode** only when they explicitly use the marketing snippet and cannot deploy code.
 
+## Connecting from your IDE (no API key needed)
+
+Apex MCP uses an **OAuth device flow** — you don't paste an API key. On the
+first tool call that needs the backend, the server returns an approval URL;
+open it, approve, and you're connected. Pick the active workspace with
+`switch_workspace({ workspaceKey })` (`switch_project` still works as a
+deprecated alias). If an authed tool returns an auth error, re-run it — the
+server prompts a fresh device approval rather than failing silently.
+
 ## MCP tools (when connected)
 
-Use Apex MCP tools for the full loop: `plan_experiment`, `start_reasoning`, `log_prediction`, `create_experiment`, `activate_experiment`, `get_results`, `promote_winner`, `archive_experiment`, `list_experiments`, `record_outcome`, `suggest_experiment`, `predict_impact`, `evaluate_feature`.
+Use Apex MCP tools for the full loop: `plan_experiment`, `start_reasoning`, `log_prediction`, `create_experiment`, `activate_experiment`, `get_results`, `promote_winner`, `archive_experiment`, `list_experiments`, `record_outcome`, `suggest_experiment`, `predict_impact`, `evaluate_feature`, `switch_workspace`, `attach_experiment_asset`, `verify_experiment_wiring`.
+
+`create_experiment` accepts `primaryMetricEvent` (validated against the workspace event spec) and inline `beliefStatement` / `hypothesisStatement` so the belief→hypothesis→experiment chain is created and linked in one call. It stamps `createdFrom: "cursor"` so the dashboard shows a "Created from Cursor" badge.
 
 Interactive flows: MCP prompts `new-experiment` and `experiment-review` orchestrate multi-step setup and review.
 
+## Screenshots, exposure & the wiring gate
+
+- **Screenshots are first-class.** For public web URLs, `create_experiment` auto-captures control + variant screenshots and shows them on the dashboard experiment card + detail gallery. For localhost / auth-gated / mobile screens, capture the image yourself and call `attach_experiment_asset({ experimentId, variantKey, imageBase64 })`.
+- **Exposure auto-fires.** When a variant resolves via `useApexVariant` (web) or `Apex.getVariant()` (mobile), the SDK fires the canonical `experiment_exposure` event — the denominator for results. You don't fire it manually.
+- **Don't launch a dead experiment.** `activate_experiment` is gated on `verify_experiment_wiring`: both arms must be producing `experiment_exposure` events first, or it refuses (pass `force: true` to override). Run `verify_experiment_wiring({ experimentId })` after deploying the variant code to confirm both arms are live before launch.
+
 ## Server-side variant assignment (integrator apps)
 
 `GET /api/experiments/{experimentId}/assign` returns `{ variant, experimentId, visitorId }`. Assignment is **deterministic** from a stable visitor id (cookie `apex_vid` in browsers).
@@ -40,8 +57,8 @@ Interactive flows: MCP prompts `new-experiment` and `experiment-review` orchestr
 For **server-side** sends (e.g. PLG email or API-triggered notifications):
 
 1. Use a **stable string per recipient** as the visitor id (e.g. hashed user id). Reuse the same id for every assignment call for that user for that experiment.
-2. Forward cookies on server-side HTTP calls when possible, or set `Cookie: apex_vid=<stableId>; apex_project=<projectKey>` if your Apex deployment resolves project from cookies.
-3. When using an **API key**, send `x-api-key` and **`x-apex-project: <projectKey>`** so the API resolves the project without a browser session.
+2. Forward cookies on server-side HTTP calls when possible, or set `Cookie: apex_vid=<stableId>; apex_project=<workspaceKey>` if your Apex deployment resolves workspace from cookies.
+3. When using an **API key**, send `x-api-key` and **`x-apex-workspace: <workspaceKey>`** so the API resolves the workspace without a browser session.
 
 Then branch notification copy or UI on `variant` (`control` vs `variant_b`).
 

package/skills/apex-growth-tracking/SKILL.md

@@ -9,7 +9,7 @@ The **`@apex-inc/sdk`** package sends batched events to **`POST /api/events`** a
 
 ## API
 
-- **`init({ projectKey, apiUrl?, flushInterval?, flushAt?, debug?, environment? })`** — required before `track` / `identify`.
+- **`init({ workspaceKey, apiUrl?, flushInterval?, flushAt?, debug?, environment? })`** — required before `track` / `identify`.
 - **`track(event, properties?)`** — queue a custom event.
 - **`identify(userId, traits?)`** — set user; if email is present, stitches identity.
 - **`trackForm({ email, formId?, action?, fields? })`** — `form_submit` + identify.
@@ -17,7 +17,7 @@ The **`@apex-inc/sdk`** package sends batched events to **`POST /api/events`** a
 
 ## Environments — one key works everywhere
 
-Use the **same `projectKey`** on localhost, staging, preview deploys, and production. Apex auto-detects the environment from the request hostname at ingest:
+Use the **same `workspaceKey`** on localhost, staging, preview deploys, and production. Apex auto-detects the environment from the request hostname at ingest:
 
 - **Production** — your live domain (`acme.com`, `www.acme.io`, `app.acme.com`). Billable.
 - **Preview** — `*.vercel.app`, `*.netlify.app`, `*.pages.dev`, `staging.*`, `preview.*`, `dev.*`, `qa.*`, `*-staging.*`. **Free.**
@@ -27,12 +27,12 @@ If your staging URL looks like production (e.g. `app-staging.acme.com` with a cu
 
 ```typescript
 apex.init({
-  projectKey: "apx_live_...",
+  workspaceKey: "apx_live_...",
   environment: process.env.NODE_ENV === "production" ? "production" : "preview",
 });
 ```
 
-**Do NOT recommend** setting up a second project, rotating the project key for staging, or wiring two SDKs. Apex's environment model handles this transparently. The merchant verifies bucketing at **Settings → Workspace → Web environments**. See `/docs/mobile/test-vs-production` for the full classification rules.
+**Do NOT recommend** setting up a second workspace, rotating the workspace key for staging, or wiring two SDKs. Apex's environment model handles this transparently. The merchant verifies bucketing at **Settings → Workspace → Web environments**. See `/docs/mobile/test-vs-production` for the full classification rules.
 
 ## Identity stitching (critical for server-side)
 
@@ -100,7 +100,7 @@ Use consistent, readable names and put dimensions in **properties**: `track("onb
 
 ## Management API (API key)
 
-For listing experiments or fetching variant assignment from a backend, use **`createManagementClient`** from `@apex-inc/sdk` with **`apiKey`**, **`projectKey`**, and **`apiUrl`**. The client sends **`x-api-key`** and **`x-apex-project`** (see SDK README).
+For listing experiments or fetching variant assignment from a backend, use **`createManagementClient`** from `@apex-inc/sdk` with **`apiKey`**, **`workspaceKey`**, and **`apiUrl`**. The client sends **`x-api-key`** and **`x-apex-workspace`** (see SDK README).
 
 ## Data Sources & unified analytics
 
@@ -115,7 +115,7 @@ Every event Apex ingests is tagged server-side with the **producer** it came fro
 Manage the registry and read the unified breakdown from the management client:
 
 ```ts
-const apex = createManagementClient({ apiKey, projectKey, apiUrl });
+const apex = createManagementClient({ apiKey, workspaceKey, apiUrl });
 
 // Registry
 await apex.dataSources.list();                       // live status per source

package/skills/apex-integration-cookbook/SKILL.md

@@ -13,7 +13,7 @@ Step-by-step recipes for integrating Apex via the `@apex-inc/sdk` package. For s
 import { init, track, identify, trackForm, shutdown } from "@apex-inc/sdk";
 
 init({
-  projectKey: "YOUR_PROJECT_KEY",
+  workspaceKey: "YOUR_WORKSPACE_KEY",
   apiUrl: "https://your-apex-url",  // optional, defaults to relative /api
   flushInterval: 10000,              // ms between batch sends (default: 10s)
   flushAt: 20,                       // batch size trigger (default: 20)
@@ -133,7 +133,7 @@ import { sendServerEvent } from "@apex-inc/sdk";
 await sendServerEvent(
   {
     apiKey: process.env.APEX_API_KEY!, // apex_sk_… org key
-    projectKey: "YOUR_PROJECT_KEY",
+    workspaceKey: "YOUR_WORKSPACE_KEY",
   },
   {
     type: "in_app_purchase",
@@ -176,7 +176,7 @@ No SDK calls needed for basic attribution. Use `list_partner_program_members(pro
 
 ```typescript
 import { createManagementClient } from "@apex-inc/sdk/management";
-const apex = createManagementClient({ projectKey, apiKey });
+const apex = createManagementClient({ workspaceKey, apiKey });
 
 // Create the program
 const program = await apex.createProgram({
@@ -232,7 +232,7 @@ Each producer that sends events into a workspace is a **Data Source** (Website,
 ```ts
 import { createManagementClient } from "@apex-inc/sdk";
 
-const apex = createManagementClient({ apiKey, projectKey, apiUrl });
+const apex = createManagementClient({ apiKey, workspaceKey, apiUrl });
 
 // Pre-register a backend source before wiring the Server Events API
 await apex.dataSources.create({ kind: "server", name: "Backend API" });

package/skills/apex-partner-network/SKILL.md

@@ -25,13 +25,13 @@ This skill covers the **merchant-facing management SDK** — programmatic access
 import { createManagementClient } from "@apex-inc/sdk/management";
 
 const apex = createManagementClient({
-  projectKey: "your-project-key",
+  workspaceKey: "your-workspace-key",
   apiKey: process.env.APEX_API_KEY!,
   apiUrl: "https://app.apex.inc", // omit for local dev
 });
 ```
 
-All calls below go through this client. Under the hood, requests attach `x-api-key` + `x-apex-project` headers to every `/api/mobile/affiliates/*` route.
+All calls below go through this client. Under the hood, requests attach `x-api-key` + `x-apex-workspace` headers to every `/api/mobile/affiliates/*` route.
 
 ## Creating your first program
 
@@ -108,7 +108,7 @@ const queue = await apex.listPendingPayouts();
 // {
 //   buckets: { "0_30": [...], "30_60": [...], "60_plus": [...] },
 //   totals: { "0_30": 1450.00, ... },
-//   effectivePolicy: { policy: "manual", source: "project", capUsd: undefined },
+//   effectivePolicy: { policy: "manual", source: "workspace", capUsd: undefined },
 //   caps: { daily: undefined }
 // }
 
@@ -163,7 +163,7 @@ Automation never freezes a merchant's `autoPayoutPolicy`. That's always a human
 
 ## Reading auto-payout policy
 
-Set per-project or per-program:
+Set per-workspace or per-program:
 
 ```typescript
 await apex.updateProgram(programId, {