@drip-apex/apex-cli 0.19.0 → 0.20.0

package/package.json

@@ -1,8 +1,20 @@
 {
   "name": "@drip-apex/apex-cli",
-  "version": "0.19.0",
+  "version": "0.20.0",
   "license": "MIT",
-  "description": "Apex CLI for managing experiments, approved roadmap ideas, and draft workspaces.",
+  "description": "Apex by DRIP CLI: build, preview and run A/B tests on your online shop from the terminal or an AI coding agent (Claude Code, Codex, Cursor).",
+  "keywords": [
+    "a/b testing",
+    "ab testing",
+    "experimentation",
+    "split testing",
+    "shopify",
+    "mcp",
+    "cro",
+    "conversion rate optimization",
+    "cli"
+  ],
+  "homepage": "https://docs.drip-apex.com/docs/cli/install-auth",
   "private": false,
   "repository": {
     "type": "git",

package/skills/apex-cli/SKILL.md

@@ -52,6 +52,39 @@ apex experiments status <folder> --json
 
 Edit only supported experiment files. Never hand-edit `qa.json` or `launch.json`.
 
+## Checkout messages
+
+Add an A/B test arm checkout message with `[{ "action": "checkoutBlock", "checkoutBlock": { "heading": "Free returns for 30 days", "body": "Not the right fit? Send it back for free.", "tone": "info" } }]` to the arm's flat mutations.
+
+The required `heading` is trimmed and must contain visible text in 1–120 characters. Optional `eyebrow`, `body` and `disclosure` allow up to 60, 500 and 300 characters. `tone` defaults to `info`; it also accepts `success`, `warning` or `critical`. `placement` accepts only `checkout`, the default. Unknown keys are refused at both levels. Omit deprecated `enabled`; `false` hides the message.
+
+Use at most one message per arm (`duplicate_checkout_block`), in `variations/<slug>/mutations.json` for a pulled experiment or `src/mutations.json` for a workspace folder, never `url-blocks.json`. Messages cannot share a test with `commerce/post-purchase.json`, and personalizations refuse them. Omit `surface` and `checkoutBlock` from `targeting.json`; those retired keys return `409 checkout_mode_retired`.
+
+Copy cannot state a money amount: a number next to a currency symbol, ISO code or currency word, or a percent next to a discount word such as off, save, sale or Rabatt. Apply returns `422 checkout_copy_states_money` (CLI exit 3). A plain percent only warns at launch.
+
+Pause a running test before changing its message, run its QA checkout again, then resume. On paused or running tests, adding the first message to a test with no storefront change or removing the last message is refused (`checkout_exposure_owner_frozen`).
+
+Messages may share an arm with DOM mutations, CSS, JS and commerce levers other than post-purchase. Combined tests count visitors on the storefront and show their storefront change only while Apex can confirm the message is live at checkout. Tests whose arms change only messages count visitors at checkout and show messages only to buyers who allow analytics, marketing and sale-of-data processing; QA testers must grant that consent too. Apex recommends a revenue primary goal for these tests. Control may carry a message, but it does not count as treatment work.
+
+From nothing to a saved draft:
+
+1. Run `apex login`, then `apex use <org>/<shop>`. Alternatively set `APEX_API_KEY` with `DRIP_ORG`/`DRIP_SHOP` or pass `--org`/`--shop`. With only `APEX_API_KEY`, `apex use` cannot persist context; a shop-scoped key needs no selection.
+2. Run `apex experiments create --name "Checkout message" --page-url <url> --yes --json` and read `.data.experiment.id`. A fresh draft has `control` and `variation-b` arms.
+3. Run `apex experiments pull <id> --out <folder> --json`.
+4. Put the entry above in `<folder>/variations/variation-b/mutations.json`; leave `variations/control/mutations.json` as `[]`.
+5. Run `apex experiments plan <folder> --json`. Blocking issues return exit 3; plan lists the rules above except apply-only refusals.
+6. Run `apex experiments apply <folder> --json`. If the test already holds QA approval, add `--accept-qa-invalidation`; without it, exit 4 requests confirmation.
+7. Apply stores the entry with `"placement": "checkout"` added; run `apex experiments apply <folder> --sync` so the folder matches the stored bytes. `apex experiments status <folder> --json` shows the QA checklist and file state, not launch blockers; the Apex dashboard shows those. The CLI validates file names; the server validates contents. `apex schema --json` prints the contract offline.
+
+Before launch:
+
+- Use Shopify Plus (development stores with "development" or "plus" in their plan name also pass), with the Apex app connected.
+- Ask your Apex contact at Drip for the Checkout extension tests add-on and to switch on checkout tests for the store. The Apex team sets both.
+- Add the Apex Checkout Experiment block in the Shopify checkout editor, normally at the information step. Apex cannot see placement directly; an unplaced block appears as a missing QA checkout. If the store offers Shop Pay, turn on "Include block in Shop Pay" for the block.
+- Use production or the store's active environment and keep the store's checkout messages within Shopify's size budget.
+- Open each message arm's QA link in a real checkout: `apex preview <id> <variation-id> --json --no-open` prints a signed link (treat it as a secret), or use "Preview links" in the experiment's Check panel. Add a product, go to checkout, allow analytics, marketing and sale-of-data processing if the store asks, and wait for the message. The receipt must match the current message text and test epoch. A customer approval link does not count.
+- Mark QA done and launch in the dashboard. API and CLI launch are unavailable. Apex confirms delivery after launch and pauses the test if it cannot confirm the message within 30 minutes.
+
 ## Launch Policy
 
 Launch stays dashboard-only. Agents can build, apply, and collect QA evidence,
@@ -130,3 +163,13 @@ Per-shop settings use a platform user API key: `apex admin shops settings list -
 ## Import past results
 
 Run `apex results import --file <csv-or-json> --dry-run` first. Resolve missing fields with `--map 'Column=title|outcome|learning'` and source verdicts with `--outcome-value 'Value=won|lost|inconclusive'`. Review the preview, then rerun with `--yes` in non-interactive environments.
+
+## Read past test results
+
+`apex results list [--source import|native|all] [--limit <n>] [--all] [--json]` lists past results for the selected shop (default source `all`, page size 50, maximum 200). Use `--all` to follow every page. The table shows legacy ID (or UUID), title, outcome, metric, lift, sample size, dates, and source. Empty lists print `No test results.`
+
+`apex results get <legacy-id-or-id> [--json]` opens a result by legacy ID, test key, or UUID, including its full learning, confidence, dates, page, and device. Missing results exit with code 1 through the existing API failure path. Both commands use shop or user keys with `experiments:read` and verify each row belongs to the selected shop. Imports show their source name and original date range, falling back to import time; native results show source `apex` and creation time.
+
+`apex results delete <legacy-id-or-id> [--yes] [--json]` permanently removes one imported result with `experiments:write`. It first reads the result and, outside `--json`, prints its title, outcome, dates, source, and legacy ID; with `--json --yes` it removes without printing a preview, so check the ID first (for example with `apex results get`). Native results are refused locally (exit 3). Confirm the prompt or pass `--yes`; non-TTY callers without `--yes` receive exit 4 with the exact rerun hint. Removed results cannot be restored in Apex; the full record remains in the audit log. JSON output wraps the API `{ data }` response and verifies the echoed shop.
+
+JSON uses the standard CLI envelope: its `data` contains `{ data, pagination }` for lists (merged rows and final pagination with `--all`) or `{ data: result }` for a single result. Invalid `--source` or `--limit` exits 3 before an HTTP request.