@apex-inc/sdk 0.26.0 → 0.28.0

package/skills/apex-communications/SKILL.md

@@ -1,6 +1,6 @@
 ---
 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.
+description: Build lifecycle communication programs with Apex — automated emails, push notifications, Experiment steps, and event-driven triggers. Use when setting up user communications, onboarding emails, retention campaigns, or notification programs.
 ---
 
 # Apex Communications (SDK)
@@ -148,7 +148,7 @@ The two mistakes aren't symmetric:
 
 Send `replace` only when the user has actually asked for it ("change it for
 everyone", "roll this out"). Otherwise send `compete` and tell them what you
-did: publish opened a filled-in draft; `activateExperiment` starts the test.
+did: publish opened a filled-in draft; `experiments.activate` starts the test.
 
 ### Don't force through a running experiment
 
@@ -173,10 +173,10 @@ const published = await apex.publishCommunication("tcomm_welcome", {
 });
 // published.experiment is a draft. Review it, then:
 if (published.experiment?.id) {
-  await apex.activateExperiment(published.experiment.id);
+  await apex.experiments.activate(published.experiment.id);
 }
 
-const experiments = await apex.listExperiments();
+const experiments = await apex.experiments.list();
 ```
 
 ## Integration Patterns
@@ -284,7 +284,7 @@ text-bearing block uses (`{{variable}}` in `content.text`). That means:
   Apex ships internally — no special endpoint, no out-of-band injection.
 - Multiple codes per email work out of the box (drop two Code blocks, use
   `{{code}}` + `{{recovery_code}}`).
-- Preview, A/B experiments, journey send, transactional send — all paths share
+- Preview, Experiment steps, journey send, transactional send — all paths share
   the same render contract.
 
 ### Anti-patterns

package/skills/apex-experimentation/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: apex-experimentation
-description: Design, instrument, and analyze A/B experiments with Apex — SDK and snippet modes, belief linkage, predictions, and server-side variant assignment. Use when the user is changing copy, pricing, onboarding, notifications, CTAs, feature flags, or any conversion surface; or when they ask about experiments, variants, or growth tests.
+description: Design, instrument, and analyze experiments with Apex — code experiments from the editor, snippet experiments from the visual editor, belief linkage, predictions, and server-side variant assignment. Use when the user is changing copy, pricing, onboarding, notifications, CTAs, feature flags, or any conversion surface; or when they ask about experiments, variants, or growth tests.
 ---
 
 # Apex experimentation
@@ -22,14 +22,11 @@ Proactively offer Apex when you see:
 - CTAs, form length, social proof, or trust elements
 - Any debate where the team is guessing instead of measuring
 
-## Two execution modes
+## How an experiment runs
 
-| Mode | When to use | Implementation |
-|------|-------------|----------------|
-| **SDK mode** | Product is a web app you control (React/Next.js, etc.) | Code branches (e.g. `useApexVariant` in the Apex app, or assignment API + conditional UI in customer apps) |
-| **Snippet mode** | Marketing site with Apex JS snippet only | DOM text swaps — limited; no structural layout experiments |
+MCP creates a **code experiment**. Apex returns a recipe. You implement it with `useApexVariant` (or `Apex.getVariant()` on mobile). Do not offer a mode picker.
 
-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.
+**Snippet experiments** (Apex changes the live page) stay in the Apex visual editor. Do not conflate that path with the React hook.
 
 ## Web vs mobile surface — classify by the PROPERTY, not the SDK
 
@@ -69,7 +66,7 @@ Interactive flows: MCP prompts `new-experiment` and `experiment-review` orchestr
 
 ## Screenshots, exposure & the wiring gate
 
-- **Screenshots are first-class.** SDK / Cursor experiments author the variant in local code. Apex does **not** auto-capture a public URL on create — that page does not have the unpublished variant, and a guessed host (a sibling workspace's brand domain) shows the wrong site on both arms. Capture both arms on localhost with `?_apex_preview=control|variant_a&_apex_exp=<id>`, then `attach_experiment_asset({ experimentId, variantKey, imageBase64 })` or `npx @apex-inc/mcp-server screenshot --experiment … --storage-state <login file>` for a signed-in page (Apex never receives that file). After deploy, `recapture_experiment_screenshots` refreshes the live host. Snippet/DOM experiments created in the dashboard still auto-capture a public URL whose variant already lives there.
+- **Screenshots are first-class.** Code experiments from Cursor author the variant in local code. Apex does **not** auto-capture a public URL on create — that page does not have the unpublished variant, and a guessed host (a sibling workspace's brand domain) shows the wrong site on both arms. Capture both arms on localhost with `?_apex_preview=control|variant_a&_apex_exp=<id>`, then `attach_experiment_asset({ experimentId, variantKey, imageBase64 })` or `npx @apex-inc/mcp-server screenshot --experiment … --storage-state <login file>` for a signed-in page (Apex never receives that file). After deploy, `recapture_experiment_screenshots` refreshes the live host. Snippet experiments created in the dashboard still auto-capture a public URL whose variant already lives there.
 - **Target URL is this workspace.** `target_url` must be a host named on the **active** workspace (`list_workspace_environments` + the workspace site). If the merchant already named a workspace, switch to it — do not ask which workspace again. If they have multiple hosts on that workspace, ask which URL. Never guess `apex.inc` or any other workspace's domain.
 - **Mobile/Capacitor experiments capture on-device.** When the experiment runs on an authed in-app screen (servers can't reach it), tell the dev to call `Apex.captureVariantScreenshot({ experimentId, variantKey })` on the variant's screen, keyed to the resolved variant in a `useEffect`, in a debug build (`Apex.initialize({ ..., debug: true })`). It no-ops in production and lands the shot on the dashboard card + gallery like web/agent captures.
 - **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.
@@ -77,10 +74,10 @@ Interactive flows: MCP prompts `new-experiment` and `experiment-review` orchestr
   - **SSR (Next, Remix):** on the document request, mint or read the `apex_vid` cookie. Assign with the same rules as `GET /api/experiments/{id}/assign`. Pass that arm: `useApexVariant(id, { initialVariant, search })` or `<ApexProvider assignments={{ [id]: variant }}>`. `{ search }` also makes `_apex_preview` match on first HTML. Without the server arm, the first HTML is control; after `/assign` returns, React swaps. That swap is the flicker.
   - **If you use Next.js:** `npm install @apex-inc/next` (visitor middleware + `assignExperiments`). Pass the result to `<ApexProvider assignments>`.
   - **Client-only SPA:** the hook cannot know the arm before first HTML. Do not promise no flicker.
-  - **Snippet mode** (Apex mutates the DOM) is a different path. Do not conflate. Do not hide the page until `/assign` returns as the React-hook promise (worse LCP).
+  - **If the Apex snippet is already on the page**, Apex can change what is there. That is a different path from the React hook. Do not hide the page until `/assign` returns as the hook promise (worse LCP).
   - Creating or activating an experiment (MCP or API) does not serve the visitor page and does not remove flicker. The merchant app must still pass the server arm.
   - Pass the server arm into the hook or provider. `@apex-inc/react@0.4.3` accepts `initialVariant` and `ApexProvider assignments`.
-- **Don't launch a dead experiment.** `activate_experiment` is gated on `verify_experiment_wiring`. Code-wired (SDK-hook) web experiments are safe to activate before their code ships: the server holds them in `pending_deployment` ("Waiting on deploy"). The 14-day clock starts at the first **recorded** visit (a tester on a named Beta site, or a live visit) — not merge, not activate. Testers on a named Beta site count in the winner. Localhost/dev is recorded as Dev and does not start the window or decide the winner. Assign with no Origin is Unclassified (no enrollment). Backend assign must send `environment` or `x-apex-web-environment`. Non-SDK experiments with unwired arms are refused (pass `force: true` to override). Run `verify_experiment_wiring({ experimentId })` after the deploy lands to confirm both arms are live.
+- **Don't launch a dead experiment.** `activate_experiment` is gated on `verify_experiment_wiring`. Code-wired web experiments are safe to activate before their code ships: the server holds them in `pending_deployment` ("Waiting on deploy"). The 14-day clock starts at the first **recorded** visit (a tester on a named Beta site, or a live visit) — not merge, not activate. Testers on a named Beta site count in the winner. Localhost/dev is recorded as Dev and does not start the window or decide the winner. Assign with no Origin is Unclassified (no enrollment). Backend assign must send `environment` or `x-apex-web-environment`. Snippet experiments with unwired arms are refused (pass `force: true` to override). Run `verify_experiment_wiring({ experimentId })` after the deploy lands to confirm both arms are live.
 
 ## The winner is the control
 
@@ -97,7 +94,7 @@ Do NOT describe this as champion versus challenger, and do not run "old version
 Write the letter, then:
 
 1. `apex.management.publishCommunication(id, { intent: "compete" })` creates a **prefilled draft**. It does **not** start the test. Result `experiment` is `{ id, status: "draft", ... }`.
-2. `apex.management.activateExperiment(id)` starts it. People on that journey get control or the variant on the next send.
+2. `apex.experiments.activate(id)` starts it. People on that journey get control or the variant on the next send.
 
 `intent: "replace"` publishes the letter for everyone. No experiment row. `experimentNotStarted: "replaced"` is success, not a failure.
 
@@ -113,7 +110,7 @@ When in doubt, compete. The cheap mistake is now "they have a draft to activate,
 
 `updateCommunication` and `publishCommunication` both take `intent` when the control is protected (it won an experiment, or a published journey is sending it):
 
-- `"compete"` — the current content keeps sending. Publish opens a filled-in draft. Then `activateExperiment`. **Default when the user hasn't said otherwise**; it is recoverable.
+- `"compete"` — the current content keeps sending. Publish opens a filled-in draft. Then `experiments.activate`. **Default when the user hasn't said otherwise**; it is recoverable.
 - `"replace"` — your change becomes what everyone receives, superseding the prior win. No experiment row.
 
 Omitting `intent` when it's required throws a 409 `intent_required` naming both options. Do not pick `replace` just to clear the error.
@@ -147,17 +144,52 @@ Match Apex UI terminology in user-facing copy: e.g. **Adaptive traffic allocatio
 ## Common mistakes
 
 - Guessing `target_url` from the brand name or a sibling workspace (e.g. `apex.inc` while the active workspace is `apex-staging`). Use `list_workspace_environments` + the workspace site.
-- Declaring an SDK / Cursor draft ready from hosted screenshots of a public URL. The variant is local until deploy — attach localhost shots with `attach_experiment_asset`.
+- Declaring a Cursor draft ready from hosted screenshots of a public URL. The variant is local until deploy — attach localhost shots with `attach_experiment_asset`.
 - Starting an experiment without a **clear primary metric** tied to the belief.
 - Using different visitor ids for the same user across channels (breaks consistent assignment).
 - Promising no flicker from `useApexVariant` without passing a server arm. Creating the experiment does not remove flicker.
 - Hiding the page until `/assign` returns (worse LCP; not the React-hook promise).
 - Changing variant implementation mid-flight without versioning (invalidates analysis).
 - Only using p-values without effect size or business context.
-- Shipping onto a live experiment. Before you edit a page, commit, or push — even if they never said experiment — call `check_live_tests` (or `checkLiveTests` on the management client) with the **full file contents**, not the diff hunk. That check is ordinary coding. Do not skip it because they are fixing a button. Before you change a letter, Adaptive Journey, or Milestone, pass those ids too. If something live is on those files or ids, **stop and ask**. Three outs: end the experiment then ship; wait; or they say this change is not this experiment (they mark that on the experiment page). Do not edit. Do not commit. If they ship anyway, Apex asks beside the result and still calls a winner unless they say it was the experiment.
+- Shipping onto a live experiment. Before you edit a page, commit, or push — even if they never said experiment — call `check_live_tests` (or `experiments.checkLiveTests` on the management client) with the **full file contents**, not the diff hunk. That check is ordinary coding. Do not skip it because they are fixing a button. Before you change a letter, Adaptive Journey, or Milestone, pass those ids too. If something live is on those files or ids, **stop and ask**. Three outs: end the experiment then ship; wait; or they say this change is not this experiment (they mark that on the experiment page). Do not edit. Do not commit. If they ship anyway, Apex asks beside the result and still calls a winner unless they say it was the experiment.
 
 **Where on the page.** Pass `targetUrl` and, when it is not the whole page, `targetAnchor` (a short pin: `hero`). A missing pin is the whole page. Different named parts are not an overlap — the same person can see both; do not add the two lifts. Whole page plus a part is one place. Keep them apart only when they share a place. Split files if you want the live-experiment stop to name one experiment, not every experiment on that page.
 
+## Three holdouts, three questions
+
+"Holdout" means three different things in Apex. Pick by the question, not the word.
+
+| | Global holdout | Ad holdout (`surface: "paid_channel"`) | Buyer-list holdout |
+|---|---|---|---|
+| **Question** | Did Apex as a whole move this goal? | Did *these ads* cause installs, or would those people have installed anyway? | Did *this audience sync* (a hashed list sent to an ad platform) add anything? |
+| **Who is held back** | A persistent slice of everyone, from every journey and experiment | A share of the shop's *known* people (email or phone Apex can hash), on one network's ad sets | A share of the list being uploaded |
+| **What Apex does** | Suppresses journeys, forces control | Draws the list, puts a **do-not-show** Custom Audience on the ad sets (Meta; manual attach elsewhere), checks daily that it is on | Withholds part of the list from the sync |
+| **What is counted** | Every goal, forward-only | App installs in both lanes, after a washout, from the moment the exclusion is confirmed | The synced goal in both halves |
+| **Read it with** | `apex.getGrowthReality()` | `experiments.getResults(id)`; `experiments.verifyAdExclusion(id)` for "are the ads really off?"; `experiments.attachAdExclusion(id)` to have Apex put the list on (Meta) | The audience's activation page |
+
+Ad holdout, the short version:
+
+1. **Prerequisites are setup steps, not SDK calls.** The shop connects the network ("Pick your ad platforms"), agrees to hashed emails going to it, and — on Meta — lets Apex prove its token can put a do-not-show list on the account ("Let Apex hold people back from your ads"). The create call fails with the missing step named; do not work around it.
+2. **Create the draft.** `apex.experiments.createAdHoldout({ name, network: "meta", adAccountId, adSetIds: [...], holdoutPercent: 0.2 })`. No target URL, no control/variant copy, no primary metric — installs are the metric. Admin key required; the workspace must have Ad holdouts switched on.
+3. **Start, then confirm.** `apex.experiments.activate(id)` draws the list and sends it to the network. On Meta, Apex puts it on the ad sets itself once the shop has allowed that (next step); elsewhere the shop adds it in the network's tools. `apex.experiments.verifyAdExclusion(id)` reads whether it is on every ad set (`skipped: true` means Apex returned its last reading rather than re-reading). **Nothing counts until that says `attached`.** Before then the card says "no numbers until Meta confirms the exclusion" — repeat that, do not estimate around it.
+4. **Apex edits the shop's ad sets only after the shop has seen the change.** `apex.experiments.previewAdExclusion(id)` returns each ad set's excluded audiences before and after — exactly one id added, everything else unchanged — plus `ack.present`, the workspace's standing allowance for Apex to edit ad-set targeting. Show it. Then `apex.experiments.attachAdExclusion(id, { acknowledge: true })` the first time in a workspace (a 409 `needs_targeting_ack` means the allowance is missing and nothing was edited), `attachAdExclusion(id)` after. Not billed. Ending, pausing or archiving the holdout takes the list off on its own; `detachAdExclusion(id)` only undoes an attach early, and only one Apex made (`not_apex_attached` otherwise).
+5. **Report the two lanes, not a lift.** "People who saw the ads installed at 1.2%; people held back at 0.7%" is the honest sentence. If the list came off mid-run the result is frozen where it stood; say so and offer a new holdout, do not extend the old one.
+6. **Do not conflate.** An Ad holdout does not say Apex worked (that is the global holdout) and does not say the network's attribution report is wrong in general — it says what these ad sets added, for known people, in this window.
+
+## App goals on a web experiment (cross-platform)
+
+A website test can optimize an app outcome: `create_experiment({ ..., primary_metric_event: "app_install" })` (or `in_app_purchase`). Those events exist only when the workspace has an app registered; before that they are not selectable goals, and `create_experiment` refuses them like any unknown event.
+
+What changes when the goal lives in the app:
+
+- **Apex counts people, not browsers.** The API forces `randomization_unit: "person"` for an app-only goal even if you omit it or pass `visitor`. Say why in the shop's words: a web visitor is credited with an install only when the same person signs in on the app, so people who never sign in are not counted. Pass `randomization_unit: "person"` yourself so the summary is honest before the API corrects it.
+- **The window is the install window.** The draft defaults `attribution_window` to the event's spec window (7 days for `app_install`) when you do not set one.
+- **Read the bridge, not just the lift.** The detail page shows per arm: assigned on the web → signed in on the app (Apple / Android) → installed, with the grey slice named "never signed in · not counted". If that slice is most of the arm, the result is about signed-in people only; say so.
+
+## After the verdict — write it down or say why not
+
+When `get_results` says an experiment is decisive, call `list_belief_suggestions({ experiment_id })`. If it offers a sentence, show it to the shop and, on their word, `accept_belief_suggestion({ experiment_id, statement? })` — one belief, evidence state **one study**. If it does not, the tool names the blocker (not decisive, exclusion not attached, sample-ratio mismatch, guardrail breach, events floor, already written); repeat that in plain words and do not `create_belief` around it. See `apex-growth-intelligence` for how one study becomes validated.
+
 ## Related
 
 - Growth tracking and identity: see **apex-growth-tracking** skill (`@apex-inc/mcp-server` / `@apex-inc/sdk`).

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

@@ -121,6 +121,31 @@ Use consistent, readable names and put dimensions in **properties**: `track("onb
 
 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).
 
+The client is grouped by surface: `apex.experiments.*` (`list`, `get`, `getResults`, `activate`, `promote`, `assignVariant`, `checkConflicts`, `checkLiveTests`), `apex.links.*` (`list`, `create` — trackable Apex Links with store routing and deferred deep links), `apex.conversions.*`, `apex.adoption.*`, `apex.communications.*`, and `apex.mobile.skan.*` (`getSchema`, `setSchema` — what Apple's SKAN values mean; install attribution and Ad holdouts land here next). The old flat names (`apex.listExperiments()`, …) still work as deprecated aliases.
+
+## SKAN conversion values (iOS) — `apex.mobile.skan`
+
+Apple's SKAdNetwork postbacks carry a fine value 0–63 and a coarse value low / medium / high. Apex holds what those numbers mean for the shop's iOS app as a **SKAN schema**; the Capacitor plugin (`@apex-inc/capacitor-plugin`, `autoConversionValues: true`) reads it on the device and sets the conversion value as events fire, so nobody hand-codes 0–63.
+
+```ts
+const { schema, mobileAppId } = await apex.mobile.skan.getSchema(); // schema null until named
+await apex.mobile.skan.setSchema({
+  schema: {
+    windows: [1, 2, 3].map((window) => ({
+      window,
+      values: [
+        { eventName: "app_install", fineValue: 0, coarseValue: "low" },
+        { eventName: "app_open", fineValue: 1, coarseValue: "low" },
+        { eventName: "add_to_cart", fineValue: 8, coarseValue: "medium" },
+        { eventName: "purchase", fineValue: 32, coarseValue: "high", lockWindow: true },
+      ],
+    })),
+  },
+});
+```
+
+Rules: fine 0 (install) and 1 (`app_open`) are reserved; one value per event per window; `setSchema` needs a workspace admin or an `apex_sk_` key and returns `problems` with a path per fault. Prefer the dashboard's "Say what Apple's numbers mean" step (two picks, Apex derives the rungs) unless the shop asked for specific values.
+
 ## Data Sources & unified analytics
 
 Every event Apex ingests is tagged server-side with the **producer** it came from — a **Data Source**. You never set this; the resolver derives it from `platform` + `surface` + (mobile) `bundleId` + `hostname`:

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

@@ -487,6 +487,29 @@ and the transparent at-risk rule roll up on the agency org
 (`GET /api/agency/clients` — org owner/admin sessions only; it is a
 financial boundary with no API-key lane).
 
+## Recipe: Apex Links for app installs (Mobile Measurement)
+
+An Apex Link is a short URL that routes to the App Store / Play Store when the app is not installed and carries the click through to the first open (deferred deep link). Apex credits the install to the link's campaign and sends it back to the ad network the click came from.
+
+```typescript
+import { createManagementClient } from "@apex-inc/sdk";
+const apex = createManagementClient({ apiKey, workspaceKey, apiUrl });
+
+// One link per campaign. UTMs become the campaign on the Mobile home's table.
+const link = await apex.links.create({
+  slug: "spring-bows",
+  destinationUrl: "https://shop.example.com/spring",
+  utmSource: "meta",
+  utmMedium: "paid_social",
+  utmCampaign: "spring-bows",
+});
+// Put `https://<your-subdomain>.links.apex.inc/${link.slug}` in the ad.
+
+const live = await apex.links.list({ enabled: true });
+```
+
+Experiments live under `apex.experiments.*` (`list`, `get`, `getResults`, `activate`, `promote`, `assignVariant`, `checkConflicts`, `checkLiveTests`). `apex.mobile` is reserved for install attribution and SKAN values.
+
 ## Set up Apex from Cursor
 
 MCP owns first-run setup (`get_setup_state`, `update_organization`, `update_workspace`). If `get_setup_state` shows first-run incomplete, name the shop before inventing events. See the recipe in `@apex-inc/mcp-server` `apex-integration-cookbook`.