@apex-inc/mcp-server 0.38.0 → 0.40.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@apex-inc/mcp-server",
-  "version": "0.38.0",
+  "version": "0.40.0",
   "description": "MCP server for Apex. Your coding agent talks to the same Apex the dashboard uses.",
   "type": "module",
   "main": "dist/index.js",

package/skills/apex-communications/SKILL.md

@@ -57,6 +57,10 @@ A comm that's live in a published journey also needs `intent`, whatever its
 `add_communication_variant`, then `publish_communication` with `intent: "compete"`.
 Rewriting what's sending is `replace`.
 
+Publishing switches every journey that sends the letter to the new version.
+When the user wants some journeys to keep today's version, pass their ids in
+`opt_out_journey_ids`.
+
 ### The two intents
 
 - **`intent: "compete"`** — *Start an experiment.* What's sending now stays
@@ -202,7 +206,7 @@ When you draft or edit a letter:
 
 - `list_communication_themes` before restyling a series.
 - `create_communication_theme` / `update_communication_theme` to save a look. Style saves do not rewrite other emails.
-- `apply_communication_theme` stamps a look onto chosen emails. Default is draft (merchant still publishes). Pass `apply=live` for the next send.
+- `apply_communication_theme` stamps a look onto chosen emails. Default is draft (merchant still publishes). Pass `apply=live` for the next send: it publishes a version with only the look, and other unpublished edits stay drafts. Add `publish_edits_ids` only when the merchant asked to publish those edits too. Emails in a running test are skipped. Emails Apex couldn't check for a running test come back as `unchecked` with nothing changed: retry them, and pass `confirm_not_in_test_ids` only when the merchant says they aren't in a test. `publish_communication` refuses the same way (`test_check_unavailable`).
 - Never group communications by `experiment-*` catalog id. A shop's "Order updates" series is the same object as Apex's own status emails.
 
 ## Exit Rules: The Quiet Half of Lifecycle Messaging

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

@@ -38,6 +38,7 @@ When a user was anonymous and then becomes known (signup, login, checkout email)
 
 - Call **`identify`** with a stable `userId` and pass **`traits.email`** when applicable.
 - **Server-side** `identify` (webhooks, API routes): pass **`traits.visitorId`** = value of the browser **`apex_vid`** cookie so the stitch links to the real marketing session. Without it, Apex may create a synthetic visitor disconnected from prior events.
+- **Sign-out**: call **`reset()`** from `@apex-inc/sdk` (or `window.apex.reset()` on snippet-only sites) in every logout handler. It starts the browser as a fresh anonymous visitor, so a shared computer does not credit the next person's visits to the last one. Without it, Apex still never merges two signed-in people; anonymous visits go to whoever signed in on that browser most recently.
 
 ## B2B accounts + groups (model the company, not just the seat)
 

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

@@ -369,3 +369,21 @@ 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.
+
+## Recipe: Buyer lists on ad platforms (MCP)
+
+A buyer list is one of the shop's segments, kept on Meta, Google or LinkedIn by Apex and refreshed every day. The shop picks it on an ad set once, to leave buyers out of prospecting or to find more people like them. Same as Attribution → Ad platforms → Who sees your ads.
+
+1. `list_audiences` shows each list, its segment, the goal it was made for, the platforms it goes to, the platforms it actually reached, and how many people it holds back.
+2. `update_audience` changes where a list goes (`platforms`) or how many people are held back (`holdout_percent`: 0, 5, 10 or 20). 0 stops holding anyone back. Dropping a platform the list already reached deletes the list there, which cannot be undone. Without `confirm_delete: true` the tool changes nothing and lists those platforms in `would_delete_from`; ask the shop, then call again with it. A platform that refuses the delete comes back in `refused`.
+3. `remove_audience` takes the list off every platform it reached. It cannot be undone and any ad set using it stops using it, so ask the shop first and pass `confirm: true` only after they say yes. A platform that refuses comes back in `refused`; tell the shop to delete it there by hand.
+
+A held-back list that belongs to an Ad holdout experiment is the experiment's. These tools refuse it; pause or archive the experiment instead.
+
+When someone asks to be deleted or opts out of ads, Apex takes them off every list right away. If a platform refuses or isn't connected, they stay on it, and `list_audience_removals` shows them: how many each list still owes per platform, why, and what the platform said. Apex retries every day for 30 days, then stops (`stopped_retrying`) and waits for the shop. Tell the shop plainly that people who asked to be removed are still being shown ads there. If `why` is `not_connected`, the shop reconnects the platform; then call `retry_audience_removals` with the list's id, which also tries the ones Apex stopped on. Its `still_owed` says who is left.
+
+To add a list, start from what the shop wants its ads to do. `list_audience_goals` returns four goals: `win_back` (bought, but not within `window_days`, which comes from the shop's kind of business), `stop_paying` (everyone who ever bought, left out of ads for new people), `interested` (added to cart or started checkout in the last 30 days and never bought; `locked` until those events arrive) and `lookalike` (everyone who bought, with what each spent, for a Meta value-based lookalike). Each says where its list can go now (`networks`) and which lists the shop already made for it (`lists`). If a goal already has a list, ask whether they want another rather than a copy. Tell the shop who goes and where, then call `add_audience` with the goal and `confirm: true`. Apex saves the goal's rule as a segment named after the list, so the shop can change who's on it in Segments, and sends the list right away unless `send_now: false`. The result's `sent` says how many people each platform took. Spend goes only to Meta: neither LinkedIn's nor Google's list upload takes it, so a list that carries spend reaches them as the same people without it. Say so rather than calling a Google or LinkedIn list value-based.
+
+Before sending one of the shop's own events (a trial start, a booked demo) to its ad platforms, call `preview_ad_platform_send` with the event name and what it means (`purchase`, `lead`, `signup`, `subscription`, `add_to_cart`, or `something_else`). Show the shop which platforms would hear it, under what name, and which can't and why, plus the `estimate`: how often it happened in the last 30 days and what a month of sends costs at the shop's price. It saves and sends nothing.
+
+When the shop says yes, call `add_ad_platform_send` with the same event and meaning and `confirm: true`. It saves the send on the shop's Conversion for that event, so experiments and goals count the same thing. If that Conversion already means something else, the tool is refused; change the meaning on Conversions first rather than picking a different meaning to get around it. For `something_else`, Apex makes the conversion on Meta itself so campaigns can optimize for it; if `couldnt_make` comes back, tell the shop Meta's reason (usually a reconnect). A platform showing `not_agreed` only hears it after the shop agrees on Attribution → Ad platforms; the tool never agrees for them. If `without_consent_answer` is `not_sent`, only events that carry a yes go out. `list_ad_platform_sends` shows what is being sent, and `remove_ad_platform_send` stops one and keeps the Conversion.

package/skills/apex-journeys/SKILL.md

@@ -121,6 +121,9 @@ The setup step in the dashboard does steps 1–5 in one click with a reach previ
    confirm_live_journey unless they picked an out.
 3. A draft that was never published cannot be archived. Only pass delete_draft:true if they said
    delete it.
+4. Letters nothing sends any more: archive_communication({ communication_id }) for each one they
+   picked. If a published journey still sends it, the tool names the journey and stops. Archive
+   or repoint that journey first. Only pass confirm_journey_refs:true if they said archive anyway.
 ```
 
 ### "Audit my journeys for missing exits"