@drip-apex/apex-cli 0.21.0 → 0.21.1

package/README.md

@@ -742,8 +742,69 @@ Unavailable values print `–` (empty in CSV); `*` marks a denominator below 50.
 `apex forms unmerge <key> <identity>` undoes it. `apex forms detect <url>` scans a shop page without returning values.
 `apex tracking manifest [manifest]` includes the shop's form definitions in a schemaVersion 1 manifest.
 
+Read sale and no-split campaign reports with `apex experiments results <id-or-slug> --sale`.
+Use `--baseline auto|holdout|last_year|prior_period|manual` to override the saved
+reporting preference for one read, or add `--json` for the unchanged API envelope.
+This calls `/api/v1/experiments/{id}/commerce/sale-report`; ordinary results stay unchanged.
+
+The report shows current campaign and pooled sale totals, labelled archived arms,
+shop currency, launch-price markdown separately from Shopify amount-off/code allocations,
+and baseline attempts with unavailable-data reasons. Holdout comparisons use observed
+per-visitor order counts and money. Prior-period and manual comparisons are descriptive
+(`not_randomised`), with no causal interval or winner. Last year currently returns
+`last_year_unavailable` with `stored_coverage_unproven`; auto can fall back to a covered
+prior period. Unknown values print as unavailable.
+
+`--baseline` requires `--sale`. Sale reports reject `--currency`, audience segment
+filters, `--explain`, `--by-channel`, `--ad-roas`, `--goal`, `--order`, `--samples`,
+and an explicit `--wait`. Dates, environment, currency and population are fixed by
+the experiment. A manual baseline can be saved through
+`PUT /api/v1/experiments/{id}/commerce/sale-report/baseline` with the exact current
+start, assignment epoch and manual revision. For running/paused campaigns, the saved
+snapshot cutoff must be at or after start and at or before the current canonical
+minute rounded down, never future seconds. The manual report pins both actuals and
+baseline to that saved cutoff, shown in the report window, while computedAt stays
+real now. Other baselines use the current window. Completed campaigns require their
+exact completed end; refresh a running snapshot after completion. Missing/blank
+order currencies assume shop currency in current and historical totals and visitor
+moments; nonzero assumption counts are printed. Explicit foreign currencies are excluded.
+
 Flag goals: `apex flags create --key banner --name "Banner" --goal <uuid> --goal <uuid> --primary-goal <uuid>`. The same options work on `flags update <id>`; `--goal` replaces the attached set. `flags get <id>` prints goals and marks the primary goal. JSON input can clear the set with `{"goal_ids":[]}`.
 
+Flags support ordered audiences through the API and CLI. `apex flags get <flag>`
+shows each audience's order, experience, rollout, stop setting and archive state.
+
+```sh
+apex flags experiences create <flag> --file experience.json
+apex flags experiences update <flag> <experience> --file experience.json
+apex flags rules set <flag> --file rules.json --expected-updated-at <parent-version>
+apex flags rules reorder <flag> --file order.json
+apex flags experiences delete <flag> <experience>
+```
+
+An experience file contains `key`, `name`, optional typed JSON `value`,
+`mutations`, `custom_css`, `custom_js`, `reset_js`, `anti_flicker_selectors` and
+`code_delivery_mode`. Update files contain only the fields to change. Code uses
+the same validation and publication path as the flag's On version.
+
+A rules file is an array (or an object with `rules`) of audience objects with
+`id` (a stable UUID), `name`, `priority`, `order_index`, `variant_id`, `targeting`,
+`rollout_percentage` and `stop_after_match`. A reorder file contains every live
+rule's `id`, `priority` and `order_index`. The set command replaces the live set:
+omitted audiences are archived with their history. An experience referenced by
+any audience, including an archived one, cannot be deleted. The Off and On
+versions keep their identities.
+
+Every audience or experience write uses the parent `expected_updated_at`.
+Supply it in the file or with `--expected-updated-at`; otherwise the CLI reads
+the current flag version before saving. A stale version returns a conflict.
+`apex personalizations` keeps its existing request and response format and
+resolves migrated personalizations to their current flag data automatically.
+
+Experience saves return `code_save` with artifact review and publication status.
+A publication failure returns HTTP 502 with `error.details.saved: true`; the
+experience is already saved. Read the flag before retrying.
+
 ### Ready to launch notifications
 
 Use a user API key with `team:read` / `team:write` and the shop permission `members:manage`.