@shipeasy/openapi 3.2.0 → 3.3.0

package/dist/client.d.ts

@@ -1 +1 @@
-export { w as Client, y as Config, B as ConfigureOptions, Z as CreateClientConfig, jl as Options, jY as RequestResult, o0 as ackOpsItem, o1 as addToGateWhitelist, o2 as approveEvent, o3 as client, o4 as configure, o5 as createAlertRule, o6 as createAttribute, o7 as createClient, o8 as createClientConfig, o9 as createConfig, oa as createConnector, ob as createEvent, oc as createExperiment, od as createExperimentReadout, oe as createGate, of as createGateTemplate, og as createI18nDraft, oh as createI18nProfile, oi as createKey, oj as createKillswitch, ok as createMetric, ol as createOpsComment, om as createOpsInvestigation, on as createOpsItem, oo as createPublicBug, op as createPublicFeatureRequest, oq as createTriggerConnector, or as createUniverse, os as deleteAlertRule, ot as deleteAttribute, ou as deleteConfig, ov as deleteConnector, ow as deleteEvent, ox as deleteExperiment, oy as deleteGate, oz as deleteGateTemplate, oA as deleteI18nDraft, oB as deleteI18nKey, oC as deleteI18nProfile, oD as deleteKillswitch, oE as deleteMetric, oF as deleteOpsItem, oG as deleteUniverse, oH as disableGate, oI as discardConfigDraft, oJ as enableGate, oK as fileErrorTicket, oL as fireConnector, oM as getAttribute, oN as getConfig, oO as getConnector, oP as getCurrentProject, oQ as getError, oR as getErrorSeries, oS as getEvent, oT as getExperiment, oU as getExperimentReadout, oV as getExperimentResults, oW as getExperimentTimeseries, oX as getGate, oY as getGateTemplate, oZ as getGateWhitelist, o_ as getKillswitch, o$ as getMetric, p0 as getMetricSeries, p1 as getOpsItem, p2 as getProject, p3 as linkPrToOpsItem, p4 as listAlertRules, p5 as listAlerts, p6 as listAttributes, p7 as listConfigActivity, p8 as listConfigVersions, p9 as listConfigs, pa as listConnectors, pb as listErrors, pc as listEvents, pd as listExperiments, pe as listGateActivity, pf as listGateTemplates, pg as listGates, ph as listI18nDraftKeys, pi as listI18nDrafts, pj as listI18nKeys, pk as listI18nProfiles, pl as listKeys, pm as listKillswitches, pn as listMetricExperiments, po as listMetrics, pp as listOpsAgents, pq as listOpsComments, pr as listOpsInvestigations, ps as listOpsItems, pt as listSlackChannels, pu as listUniverses, pv as notifyOps, pw as publishConfigDraft, px as publishI18nProfile, py as pushI18nKeys, pz as reanalyzeExperiment, pA as removeFromGateWhitelist, pB as resolveError, pC as revokeKey, pD as saveConfigDraft, pE as searchResources, pF as setExperimentMetrics, pG as setExperimentStatus, pH as setGateWhitelist, pI as setI18nLabel, pJ as setKillswitchSwitch, pK as setKillswitchValue, pL as testConnector, pM as toggleKillswitch, pN as unarchiveMetric, pO as unsetKillswitchSwitch, pP as updateAlert, pQ as updateAlertRule, pR as updateAttribute, pS as updateConfig, pT as updateConfigSchema, pU as updateConnector, pV as updateErrorStatus, pW as updateEvent, pX as updateExperiment, pY as updateGate, pZ as updateGateTemplate, p_ as updateI18nDraft, p$ as updateI18nKey, q0 as updateKillswitch, q1 as updateMetric, q2 as updateOpsInvestigation, q3 as updateOpsItem, q4 as updateProject, q5 as updateTriggerConnector, q6 as updateUniverse, q7 as upsertI18nDraftKey, q8 as upsertI18nKeys, q9 as upsertProject } from './client-BPVn4hMC.js';
+export { T as Client, V as Config, X as ConfigureOptions, ai as CreateClientConfig, k4 as Options, kH as RequestResult, p4 as ackOpsItem, p5 as addToGateWhitelist, p6 as answerOpsQuestion, p7 as approveEvent, p8 as askOpsQuestions, p9 as cancelOpsQuestion, pa as client, pb as configure, pc as createAlertRule, pd as createAttribute, pe as createClient, pf as createClientConfig, pg as createConfig, ph as createConnector, pi as createEvent, pj as createExperiment, pk as createExperimentReadout, pl as createGate, pm as createGateTemplate, pn as createI18nDraft, po as createI18nProfile, pp as createKey, pq as createKillswitch, pr as createMetric, ps as createOpsComment, pt as createOpsInvestigation, pu as createOpsItem, pv as createPublicBug, pw as createPublicFeatureRequest, px as createTriggerConnector, py as createUniverse, pz as deleteAlertRule, pA as deleteAttribute, pB as deleteConfig, pC as deleteConnector, pD as deleteEvent, pE as deleteExperiment, pF as deleteGate, pG as deleteGateTemplate, pH as deleteI18nDraft, pI as deleteI18nKey, pJ as deleteI18nProfile, pK as deleteKillswitch, pL as deleteMetric, pM as deleteOpsItem, pN as deleteUniverse, pO as disableGate, pP as discardConfigDraft, pQ as enableGate, pR as fileErrorTicket, pS as fireConnector, pT as getAttribute, pU as getConfig, pV as getConnector, pW as getCurrentProject, pX as getEntityTags, pY as getError, pZ as getErrorSeries, p_ as getEvent, p$ as getExperiment, q0 as getExperimentReadout, q1 as getExperimentResults, q2 as getExperimentTimeseries, q3 as getGate, q4 as getGateTemplate, q5 as getGateWhitelist, q6 as getKillswitch, q7 as getMetric, q8 as getMetricSeries, q9 as getOpsItem, qa as getProject, qb as linkPrToOpsItem, qc as listAlertRules, qd as listAlerts, qe as listAttributes, qf as listConfigActivity, qg as listConfigVersions, qh as listConfigs, qi as listConnectors, qj as listErrors, qk as listEvents, ql as listExperiments, qm as listGateActivity, qn as listGateTemplates, qo as listGates, qp as listI18nDraftKeys, qq as listI18nDrafts, qr as listI18nKeys, qs as listI18nProfiles, qt as listKeys, qu as listKillswitches, qv as listMetricExperiments, qw as listMetrics, qx as listOpsAgents, qy as listOpsComments, qz as listOpsInvestigations, qA as listOpsItems, qB as listOpsQuestions, qC as listSlackChannels, qD as listTags, qE as listUniverses, qF as notifyOps, qG as publishConfigDraft, qH as publishI18nProfile, qI as pushI18nKeys, qJ as reanalyzeExperiment, qK as removeFromGateWhitelist, qL as resolveError, qM as revokeKey, qN as saveConfigDraft, qO as searchResources, qP as setEntityTags, qQ as setExperimentMetrics, qR as setExperimentStatus, qS as setGateWhitelist, qT as setI18nLabel, qU as setKillswitchSwitch, qV as setKillswitchValue, qW as testConnector, qX as toggleKillswitch, qY as unarchiveMetric, qZ as unsetKillswitchSwitch, q_ as updateAlert, q$ as updateAlertRule, r0 as updateAttribute, r1 as updateConfig, r2 as updateConfigSchema, r3 as updateConnector, r4 as updateEntityTags, r5 as updateErrorStatus, r6 as updateEvent, r7 as updateExperiment, r8 as updateGate, r9 as updateGateTemplate, ra as updateI18nDraft, rb as updateI18nKey, rc as updateKey, rd as updateKillswitch, re as updateMetric, rf as updateOpsInvestigation, rg as updateOpsItem, rh as updateProject, ri as updateTriggerConnector, rj as updateUniverse, rk as upsertI18nDraftKey, rl as upsertI18nKeys, rm as upsertProject } from './client-DAGqRpF1.js';

package/dist/client.js

@@ -1,7 +1,10 @@
 import {
   ackOpsItem,
   addToGateWhitelist,
+  answerOpsQuestion,
   approveEvent,
+  askOpsQuestions,
+  cancelOpsQuestion,
   client,
   configure,
   createAlertRule,
@@ -51,6 +54,7 @@ import {
   getConfig,
   getConnector,
   getCurrentProject,
+  getEntityTags,
   getError,
   getErrorSeries,
   getEvent,
@@ -92,7 +96,9 @@ import {
   listOpsComments,
   listOpsInvestigations,
   listOpsItems,
+  listOpsQuestions,
   listSlackChannels,
+  listTags,
   listUniverses,
   notifyOps,
   publishConfigDraft,
@@ -104,6 +110,7 @@ import {
   revokeKey,
   saveConfigDraft,
   searchResources,
+  setEntityTags,
   setExperimentMetrics,
   setExperimentStatus,
   setGateWhitelist,
@@ -120,6 +127,7 @@ import {
   updateConfig,
   updateConfigSchema,
   updateConnector,
+  updateEntityTags,
   updateErrorStatus,
   updateEvent,
   updateExperiment,
@@ -127,6 +135,7 @@ import {
   updateGateTemplate,
   updateI18nDraft,
   updateI18nKey,
+  updateKey,
   updateKillswitch,
   updateMetric,
   updateOpsInvestigation,
@@ -137,11 +146,14 @@ import {
   upsertI18nDraftKey,
   upsertI18nKeys,
   upsertProject
-} from "./chunk-RTN572TI.js";
+} from "./chunk-75Z4SQOM.js";
 export {
   ackOpsItem,
   addToGateWhitelist,
+  answerOpsQuestion,
   approveEvent,
+  askOpsQuestions,
+  cancelOpsQuestion,
   client,
   configure,
   createAlertRule,
@@ -191,6 +203,7 @@ export {
   getConfig,
   getConnector,
   getCurrentProject,
+  getEntityTags,
   getError,
   getErrorSeries,
   getEvent,
@@ -232,7 +245,9 @@ export {
   listOpsComments,
   listOpsInvestigations,
   listOpsItems,
+  listOpsQuestions,
   listSlackChannels,
+  listTags,
   listUniverses,
   notifyOps,
   publishConfigDraft,
@@ -244,6 +259,7 @@ export {
   revokeKey,
   saveConfigDraft,
   searchResources,
+  setEntityTags,
   setExperimentMetrics,
   setExperimentStatus,
   setGateWhitelist,
@@ -260,6 +276,7 @@ export {
   updateConfig,
   updateConfigSchema,
   updateConnector,
+  updateEntityTags,
   updateErrorStatus,
   updateEvent,
   updateExperiment,
@@ -267,6 +284,7 @@ export {
   updateGateTemplate,
   updateI18nDraft,
   updateI18nKey,
+  updateKey,
   updateKillswitch,
   updateMetric,
   updateOpsInvestigation,

package/dist/custom.d.ts

@@ -68,12 +68,12 @@ declare const opId: (op: CustomOp) => string;
  * examples.
  *
  * Source of truth for semantics is the RUNTIME parser + IR that the server
- * actually runs: the main repo's `packages/query-dsl` (`parse.ts` / `ir.ts`).
- * The vendored `cli/src/query-dsl` copy is a lagging subset (no `ratio` yet) and
- * is NOT on the create path — the CLI forwards the raw `--query` string to the
- * server, which parses it. Keep this text in sync with `packages/query-dsl`.
+ * actually runs: the main repo's `packages/query-dsl` (`parse-expr.ts` /
+ * `expr.ts`). The CLI forwards the raw `--query` string to the server, which
+ * parses it — there is no second parser here to keep in step, only this text,
+ * which has to stay in sync with `packages/query-dsl`.
  */
-declare const METRIC_GRAMMAR = "SHIPEASY METRIC QUERY DSL\n=========================\n\nA metric is an aggregation over an event stream. Almost always that is ONE\naggregation over ONE event; the single exception is the binary `ratio(...)`\nform, which divides one count-style arm by another (each arm its own event and\nfilters) in one pass. This DSL is the string you pass to\n`metrics create --query \"...\"` (equivalently the typed `query_ir`). There is\nno general arithmetic, no free-form formulas, and no subqueries \u2014 `ratio` is\nthe only division / two-event form.\n\n\nGRAMMAR (BNF)\n-------------\n  Query         := Agg | Ratio\n  Agg           := AggFunc \"(\" Selector (\",\" Identifier)? \")\" GroupBy?\n  Ratio         := \"ratio\" \"(\" RatioArm \",\" RatioArm \")\"\n  RatioArm      := (\"count_users\" | \"count\") \"(\" Selector \")\"\n  AggFunc       := \"count_users\" | \"count\" | \"sum\" | \"avg\" | \"min\" | \"max\"\n                 | \"unique\" | \"p50\" | \"p75\" | \"p90\" | \"p95\" | \"p99\" | \"p999\"\n                 | \"retention_\" <N> \"d\"                       (N = 1..90)\n  Selector      := Identifier (\"{\" Filter (\",\" Filter)* \",\"? \"}\")?\n  Filter        := Identifier MatchOp StringLiteral\n  MatchOp       := \"=\" | \"!=\" | \"=~\" | \"!~\"\n  GroupBy       := (\"by\" | \"without\") \"(\" Identifier (\",\" Identifier)* \",\"? \")\"\n  StringLiteral := double-quoted; \\\" is a literal quote, \\\\ is a backslash\n  Identifier    := [A-Za-z_][A-Za-z0-9_]*                     (case-sensitive)\n\n  The trailing Identifier after the selector \u2014 \"(\" Selector \",\" Identifier \")\" \u2014\n  is the VALUE LABEL: the numeric event label the aggregation reduces. Whether it\n  is required, optional, or forbidden depends on the aggregation (see below).\n\n\nAGGREGATIONS\n------------\n  Function        Value label   Meaning                         In experiments\n  --------------  ------------  ------------------------------  ---------------\n  count_users     forbidden     distinct users who fired it     exact\n  count           forbidden     number of events (rows)         exact\n  sum(e, v)       required      \u03A3 of numeric label v            exact\n  avg(e, v)       required      mean of label v                 exact\n  retention_Nd(e) forbidden     % of users who returned         exact\n                                within N days (N = 1..90)\n  min(e, v)       required      minimum of label v              approx \u2192 avg *\n  max(e, v)       required      maximum of label v              approx \u2192 avg *\n  unique(e, v)    required      distinct values of label v      approx \u2192 avg *\n  p50 \u2026 p999(e,v) required      quantile of v (50/75/90/        approx \u2192 avg *\n                                95/99/99.9th percentile)\n  ratio(a, b)     forbidden     a \u00F7 b (see RATIO below)         proportion **\n\n  * Display-only aggregations. The experiment t-test needs a per-user mean and\n    variance, so min/max/unique/quantile are computed exactly on dashboards but\n    collapse to a per-user `avg` when used as an experiment metric. If you need\n    an exact experiment metric, pick count_users / count / sum / avg / retention.\n\n  ** In an experiment a ratio collapses to a per-user 0/1 outcome (a proportion),\n    not a ratio-of-sums \u2014 see RATIO.\n\n  \"count\" is the DSL spelling of the internal count_events (one per matching\n  row); \"count_users\" is unique-by-user. Getting these two confused is the most\n  common mistake \u2014 count double-counts a user who fired the event twice.\n\n\nSELECTOR & FILTERS\n------------------\n  The selector is the event name plus an optional `{ ... }` filter set that\n  narrows which events count. Each filter compares an event LABEL to a quoted\n  string:\n\n    =   equal            !=   not equal\n    =~  regex match      !~   regex NOT match\n\n  - Values are ALWAYS double-quoted strings, even for numeric labels \u2014 they are\n    coerced on the server (`amount=~\"^1[0-9]$\"`, `status=\"200\"`).\n  - Multiple filters are AND-ed: `{country=\"US\", tier!=\"free\"}`.\n  - Every filter label AND the value label must be a label DECLARED on the source\n    event. Undeclared labels are a validation error, not a silent no-match.\n\n\nGROUP-BY\n--------\n  Splits the result into one series per label combination.\n    by (a, b)       one series per distinct (a, b) \u2014 keep only these labels\n    without (a, b)  group by all declared labels EXCEPT a, b\n\n  NOTE: group-by is a DASHBOARD-only feature. In an experiment the group-by is\n  ignored \u2014 a per-user reducer is applied across the whole arm instead. Group-by\n  is NOT allowed on a `ratio` query.\n\n\nRATIO  (success rate, conversion, failure %, \u2026)\n-----------------------------------------------\n  `ratio(numerator, denominator)` divides one count-style arm by another. Each\n  arm is an independent selector with its OWN event and filters, so the two arms\n  can be different events:\n\n    ratio(count(checkout_completed), count(checkout_started))\n    ratio(count_users(paid), count_users(signed_up))\n    ratio(count(payment{ok=\"1\"}), count(payment))     one event, filtered arm\n\n  Rules:\n  - Arms are limited to `count` and `count_users` \u2014 no sum/avg/quantile arm.\n  - `count` arms divide event counts; `count_users` arms divide distinct-user\n    counts. Pick one shape and use it on both arms unless you mean to mix them.\n  - A zero denominator yields 0, not an error.\n  - No `by (...)` / `without (...)`, and no retention arm, on a ratio.\n  - It is a COHORT RATE over the window \u2014 numerator events \u00F7 denominator events \u2014\n    NOT a per-id join. It never matches an individual attempt to its outcome by a\n    correlation id; it counts each side over the window and divides. If you need a\n    matched pair, resolve the outcome in your own code and emit ONE event carrying\n    the result (e.g. an `ok` label), then use `ratio(count(e{ok=\"1\"}), count(e))`\n    or `avg(e, ok)`.\n  - In an experiment a per-user ratio is a 0/1 outcome \u2014 did the numerator happen,\n    among denominator-eligible users \u2014 i.e. a proportion, not a ratio-of-sums.\n  - When creating with `--event-name`, pass the NUMERATOR's event name.\n\n\nNOT SUPPORTED (will fail to parse)\n----------------------------------\n  - general arithmetic / free-form formulas: `count(a) + count(b)`, `2 * sum(x)`,\n    `avg(a) / avg(b)` \u2014 the ONLY division form is the fixed binary\n    `ratio(arm, arm)` with count-style arms (see RATIO)\n  - a ratio arm that isn't `count` / `count_users`: `ratio(sum(a, v), count(b))`\n  - more than two events in one query\n  - `by (...)` / `without (...)` on a ratio\n  - arbitrary quantiles (only the fixed p50/p75/p90/p95/p99/p999)\n  - unquoted or numeric filter values: `{status=200}`  \u2192 must be `\"200\"`\n  - trailing tokens after the query\n\n\nEXAMPLES  (query  \u2014  what it measures)\n--------------------------------------\n  count_users(checkout_completed)\n      distinct users who completed checkout.\n\n  count(add_to_cart{country=\"US\"})\n      number of US add-to-cart events (a user can count many times).\n\n  sum(purchase{country=\"US\"}, amount)\n      total purchase amount from US purchase events.\n\n  avg(req_dur{tier!=\"free\"}, ms) without (region)\n      mean request duration for non-free tiers, one series per region-excluded\n      label combination.\n\n  p99(req_dur{route=~\"/api/.*\"}, ms) by (route, status)\n      99th-percentile latency of /api/* requests, split by route and status.\n\n  unique(login{method=\"sso\"}, device_id)\n      distinct SSO devices seen (display-only; an experiment would use per-user avg).\n\n  retention_7d(session_start)\n      share of users who started a new session within 7 days.\n\n  ratio(count(checkout_completed), count(checkout_started))\n      checkout conversion rate \u2014 completions \u00F7 starts over the window.\n\n  ratio(count(payment{ok=\"0\"}), count(payment))\n      payment failure rate from a single event's outcome label.\n";
+declare const METRIC_GRAMMAR = "SHIPEASY METRIC QUERY DSL\n=========================\n\nA metric is an EXPRESSION over an event stream. An aggregation over one event\nis a leaf; leaves compose with `+ - * /`, parentheses group, and a metric may\nend with `by (...)` or `without (...)` to split it into one series per label\ncombination. This DSL is the string you pass to `metrics create --query \"...\"`\n(equivalently the typed `query_ir`).\n\nSo `count(a) / count(b)` is a rate, `count(a) / count(b) * 100` is a\npercentage, and `(count(a) - count(b)) / count(c)` is as ordinary as it looks.\n`ratio(a, b)` still parses and means exactly `a / b`.\n\n\nGRAMMAR (BNF)\n-------------\n  Query         := Expression GroupBy?\n  Expression    := Term ((\"+\" | \"-\") Term)*\n  Term          := Factor ((\"*\" | \"/\") Factor)*\n  Factor        := \"-\"? Primary\n  Primary       := Number | \"(\" Expression \")\" | Aggregate | Function\n  Selector      := Identifier (\"{\" Predicate ((\",\"|\"and\"|\"or\") Predicate)* \",\"? \"}\")?\n  Predicate     := \"not\"? ( Identifier (\"=\" | \"=~\") StringLiteral\n                          | Identifier (\">\" | \">=\" | \"<\" | \"<=\") Number\n                          | Identifier \"not\"? \"in\" \"(\" StringLiteral (\",\" ...)* \")\"\n                          | Identifier \":\" \"*\"\n                          | \"(\" Predicate \")\" )\n  GroupBy       := (\"by\" | \"without\") \"(\" Identifier (\",\" Identifier)* \",\"? \")\"\n  StringLiteral := double-quoted; \\\" is a literal quote, \\\\ is a backslash\n  Identifier    := [A-Za-z_][A-Za-z0-9_]*                     (case-sensitive)\n\n  There is ONE negation and it goes in front of a predicate: `not status=\"ok\"`.\n  `!=` and `!~` are refused by name.\n\n  The trailing Identifier after the selector \u2014 \"(\" Selector \",\" Identifier \")\" \u2014\n  is the VALUE LABEL: the numeric event label the aggregation reduces. Whether it\n  is allowed, and whether it is needed, is per aggregation (see below).\n\n<aggregate> ::=\n    {   count ( <selector> )\n      | sum ( <selector> [ , <value-label> ] )\n      | avg ( <selector> [ , <value-label> ] )\n      | min ( <selector> [ , <value-label> ] )\n      | max ( <selector> [ , <value-label> ] )\n      | stddev ( <selector> [ , <value-label> ] )\n      | p ( <percentile> , <selector> [ , <value-label> ] )\n    }\n\n\nAGGREGATIONS\n------------\n| Aggregation | Measures | Value label |\n| --- | --- | --- |\n| `count` | how many matching events happened | not allowed |\n| `sum` | total of a numeric label | optional \u2014 defaults to the event's own value |\n| `avg` | mean of a numeric label | optional \u2014 defaults to the event's own value |\n| `min` | smallest value of a numeric label | optional \u2014 defaults to the event's own value |\n| `max` | largest value of a numeric label | optional \u2014 defaults to the event's own value |\n| `stddev` | spread of a numeric label around its mean | optional \u2014 defaults to the event's own value |\n| `p` | a percentile of a numeric label \u2014 `p(95, req, ms)` | optional \u2014 defaults to the event's own value |\n\n  A value label is optional wherever it is allowed: omitted, the aggregation\n  reduces the event's own default numeric value. `count` takes the event alone.\n\n  `count` is one per matching ROW, so a user who fired the event twice counts\n  twice.\n\n  In an experiment, `min`, `max` and `p` collapse to a per-user `avg`: the\n  t-test needs a per-user mean and variance, and those three have neither. They\n  are exact on a dashboard. For an exact experiment metric pick count / sum /\n  avg, or a rate \u2014 a rate collapses to a per-user 0/1 outcome (a proportion),\n  not a ratio-of-sums.\n\n\nSELECTOR & FILTERS\n------------------\n  The selector is the event name plus an optional `{ ... }` filter set that\n  narrows which events count. Each filter compares an event LABEL to a quoted\n  string:\n\n    =   equal                    =~  glob match\n    >  >=  <  <=  order, NUMERIC labels only, value written BARE\n    in (\"a\", \"b\")  a value set     label:*  the label is set at all\n    not <predicate>  negation, in FRONT of the predicate\n\n  There is no `!=` and no `!~`. One negation, one place it goes:\n  `{not tier=\"free\"}`. Predicates join with `and` / `or` (a comma is another\n  `and`) and parenthesise.\n\n  - `=~` takes a GLOB, NOT a regex. Two wildcards, and a glob matches the\n    WHOLE value \u2014 there are no anchors because there is nothing to anchor:\n\n      *  any sequence of characters       ?  exactly one character\n\n      route=~\"/api*\"          starts with /api\n      route=~\"*checkout\"      ends with checkout\n      route=~\"*admin*\"        contains admin\n      route=~\"/v?/users\"      /v1/users, /v2/users \u2026\n      route=~\"/health\"        EXACTLY /health \u2014 same as `route=\"/health\"`\n\n    Every other character is a LITERAL, dots included, so `host=~\"*.acme.com\"`\n    works as written. Regex syntax \u2014 `^` `$` `.*` `|` `[]` `()` `+` `{}` `\\\\` \u2014 is\n    REJECTED at save time rather than reinterpreted: `^/api` would be a glob for\n    a value that literally starts with a caret, and `/api/.*` would match\n    `/api/.x` but not `/api/x`. Write `/api*` instead.\n  - Values are ALWAYS double-quoted strings, even for numeric labels \u2014 they are\n    coerced on the server (`status=\"200\"`) \u2014 EXCEPT the order comparisons,\n    whose value is written bare (`ms > 500`). A glob on a numeric or boolean\n    label is a validation error.\n  - Multiple predicates are AND-ed: `{country=\"US\", not tier=\"free\"}`.\n  - Every filter label AND the value label must be a label DECLARED on the source\n    event. Undeclared labels are a validation error, not a silent no-match.\n\n\nGROUP-BY\n--------\n  Splits the result into one series per label combination.\n    by (a, b)       one series per distinct (a, b) \u2014 keep only these labels\n    without (a, b)  group by all declared labels EXCEPT a, b\n\n  NOTE: group-by is a DASHBOARD-only feature. In an experiment the group-by is\n  ignored \u2014 a per-user reducer is applied across the whole arm instead.\n\n\nRATES  (success rate, conversion, failure %, \u2026)\n----------------------------------------------\n  Division is ordinary: `a / b`. Each side is its own expression with its own\n  event and filters, so the two sides can be different events. `ratio(a, b)` is\n  the same thing spelled as a function.\n\n    count(checkout_completed) / count(checkout_started)\n    count(paid) / count(signed_up)\n    count(payment{ok=\"1\"}) / count(payment)           one event, filtered side\n    count(errors) / count(requests) * 100             as a percentage\n\n  Rules:\n  - A zero denominator yields 0, not an error.\n  - `by (...)` / `without (...)` applies to the whole rate, and works.\n  - AS AN EXPERIMENT METRIC both sides must be `count`. That is the one real\n    restriction, and it is about the per-user collapse rather than the query:\n    a rate becomes \"did the numerator happen, among the users eligible for the\n    denominator\", which is a 0/1 outcome per user. `sum(a, v) / count(b)`\n    charts fine and is refused when attached to an experiment.\n  - It is a COHORT RATE over the window \u2014 numerator events \u00F7 denominator events \u2014\n    NOT a per-id join. It never matches an individual attempt to its outcome by a\n    correlation id; it counts each side over the window and divides. If you need a\n    matched pair, resolve the outcome in your own code and emit ONE event carrying\n    the result (e.g. an `ok` label), then use `ratio(count(e{ok=\"1\"}), count(e))`\n    or `avg(e, ok)`.\n  - In an experiment a per-user ratio is a 0/1 outcome \u2014 did the numerator happen,\n    among denominator-eligible users \u2014 i.e. a proportion, not a ratio-of-sums.\n  - When creating with `--event-name`, pass the NUMERATOR's event name.\n\n\nREFUSED BY NAME\n---------------\n  Each of these is recognised in order to be refused, with a message saying what\n  to write instead. They are not gaps.\n\n| Spelling | Why it is refused |\n| --- | --- |\n| `count_users(\u2026)` | removed \u2014 Analytics Engine samples rows and weights the survivors, and a distinct count cannot be reweighted (sampling reweights rows, not sets), so it under-reports by the sample interval. Use count() |\n| `unique(\u2026)` | removed from the language \u2014 count(DISTINCT \u2026) takes no sample weight, has no conditional form and cannot merge across groups. Stored metrics using it still render; no new one can be authored. Use count() |\n| `retention_Nd(\u2026)` | has no time-series form; retention lives in the experiment analyzer |\n| `anomalies(\u2026)` | detection is a property of the alert rule now, not of the metric: create an alert with kind 'anomaly' and set its sigma. The metric stays what it measures, and the same seasonal baseline can be drawn on its chart by turning the band on |\n| `deviation(\u2026)` | detection is a property of the alert rule now, not of the metric: an alert with kind 'anomaly' compares this metric against its own seasonal baseline in sigmas, at a sigma and a direction you set on the rule \u2014 so one metric can back rules of different sensitivity |\n| `outliers(\u2026)` | detection is a property of the alert rule now, not of the metric: an alert with kind 'outliers' on a metric grouped by() compares each group against its peers in the same bucket, at a sigma you set on the rule |\n| `expected(\u2026)` | the seasonal band is a display property of the metric now, not a function: turn the band on and every chart of this metric draws it \u2014 at the same sigma an anomaly alert would fire at |\n| `forecast(\u2026)` | the projection is a display property of the metric now, not a function: set the metric's forecast method and horizon, and every chart of it projects forward without changing what the metric measures |\n\n  Also refused: `!=` and `!~` (write `not label=\"v\"`), a regex inside `=~`\n  (globs only), an order comparison on a text label, a quoted comparison value\n  (`ms > \"500\"`), and trailing tokens after the query.\n\n\nEXAMPLES  (query  \u2014  what it measures)\n--------------------------------------\n  count(checkout_completed)\n      number of completed checkouts.\n\n  count(add_to_cart{country=\"US\"})\n      number of US add-to-cart events (a user can count many times).\n\n  sum(purchase{country=\"US\"}, amount)\n      total purchase amount from US purchase events.\n\n  avg(req_dur{not tier=\"free\"}, ms) without (region)\n      mean request duration for non-free tiers, one series per region-excluded\n      label combination.\n\n  p99(req_dur{route=~\"/api*\"}, ms) by (route, status)\n      99th-percentile latency of /api requests, split by route and status.\n\n  ratio(count(checkout_completed), count(checkout_started))\n      checkout conversion rate \u2014 completions \u00F7 starts over the window.\n\n  ratio(count(payment{ok=\"0\"}), count(payment))\n      payment failure rate from a single event's outcome label.\n";
 
 /**
  * Every custom (non-spec) operation, in surface order. The CLI and MCP each

package/dist/custom.js

@@ -1,65 +1,90 @@
+// src/custom/grammar.generated.ts
+var AGGREGATES_BLOCK = `<aggregate> ::=
+    {   count ( <selector> )
+      | sum ( <selector> [ , <value-label> ] )
+      | avg ( <selector> [ , <value-label> ] )
+      | min ( <selector> [ , <value-label> ] )
+      | max ( <selector> [ , <value-label> ] )
+      | stddev ( <selector> [ , <value-label> ] )
+      | p ( <percentile> , <selector> [ , <value-label> ] )
+    }`;
+var AGGREGATIONS_BLOCK = `| Aggregation | Measures | Value label |
+| --- | --- | --- |
+| \`count\` | how many matching events happened | not allowed |
+| \`sum\` | total of a numeric label | optional \u2014 defaults to the event's own value |
+| \`avg\` | mean of a numeric label | optional \u2014 defaults to the event's own value |
+| \`min\` | smallest value of a numeric label | optional \u2014 defaults to the event's own value |
+| \`max\` | largest value of a numeric label | optional \u2014 defaults to the event's own value |
+| \`stddev\` | spread of a numeric label around its mean | optional \u2014 defaults to the event's own value |
+| \`p\` | a percentile of a numeric label \u2014 \`p(95, req, ms)\` | optional \u2014 defaults to the event's own value |`;
+var REFUSALS_BLOCK = `| Spelling | Why it is refused |
+| --- | --- |
+| \`count_users(\u2026)\` | removed \u2014 Analytics Engine samples rows and weights the survivors, and a distinct count cannot be reweighted (sampling reweights rows, not sets), so it under-reports by the sample interval. Use count() |
+| \`unique(\u2026)\` | removed from the language \u2014 count(DISTINCT \u2026) takes no sample weight, has no conditional form and cannot merge across groups. Stored metrics using it still render; no new one can be authored. Use count() |
+| \`retention_Nd(\u2026)\` | has no time-series form; retention lives in the experiment analyzer |
+| \`anomalies(\u2026)\` | detection is a property of the alert rule now, not of the metric: create an alert with kind 'anomaly' and set its sigma. The metric stays what it measures, and the same seasonal baseline can be drawn on its chart by turning the band on |
+| \`deviation(\u2026)\` | detection is a property of the alert rule now, not of the metric: an alert with kind 'anomaly' compares this metric against its own seasonal baseline in sigmas, at a sigma and a direction you set on the rule \u2014 so one metric can back rules of different sensitivity |
+| \`outliers(\u2026)\` | detection is a property of the alert rule now, not of the metric: an alert with kind 'outliers' on a metric grouped by() compares each group against its peers in the same bucket, at a sigma you set on the rule |
+| \`expected(\u2026)\` | the seasonal band is a display property of the metric now, not a function: turn the band on and every chart of this metric draws it \u2014 at the same sigma an anomaly alert would fire at |
+| \`forecast(\u2026)\` | the projection is a display property of the metric now, not a function: set the metric's forecast method and horizon, and every chart of it projects forward without changing what the metric measures |`;
+
 // src/custom/grammar.ts
 var METRIC_GRAMMAR = `SHIPEASY METRIC QUERY DSL
 =========================
 
-A metric is an aggregation over an event stream. Almost always that is ONE
-aggregation over ONE event; the single exception is the binary \`ratio(...)\`
-form, which divides one count-style arm by another (each arm its own event and
-filters) in one pass. This DSL is the string you pass to
-\`metrics create --query "..."\` (equivalently the typed \`query_ir\`). There is
-no general arithmetic, no free-form formulas, and no subqueries \u2014 \`ratio\` is
-the only division / two-event form.
+A metric is an EXPRESSION over an event stream. An aggregation over one event
+is a leaf; leaves compose with \`+ - * /\`, parentheses group, and a metric may
+end with \`by (...)\` or \`without (...)\` to split it into one series per label
+combination. This DSL is the string you pass to \`metrics create --query "..."\`
+(equivalently the typed \`query_ir\`).
+
+So \`count(a) / count(b)\` is a rate, \`count(a) / count(b) * 100\` is a
+percentage, and \`(count(a) - count(b)) / count(c)\` is as ordinary as it looks.
+\`ratio(a, b)\` still parses and means exactly \`a / b\`.
 
 
 GRAMMAR (BNF)
 -------------
-  Query         := Agg | Ratio
-  Agg           := AggFunc "(" Selector ("," Identifier)? ")" GroupBy?
-  Ratio         := "ratio" "(" RatioArm "," RatioArm ")"
-  RatioArm      := ("count_users" | "count") "(" Selector ")"
-  AggFunc       := "count_users" | "count" | "sum" | "avg" | "min" | "max"
-                 | "unique" | "p50" | "p75" | "p90" | "p95" | "p99" | "p999"
-                 | "retention_" <N> "d"                       (N = 1..90)
-  Selector      := Identifier ("{" Filter ("," Filter)* ","? "}")?
-  Filter        := Identifier MatchOp StringLiteral
-  MatchOp       := "=" | "!=" | "=~" | "!~"
+  Query         := Expression GroupBy?
+  Expression    := Term (("+" | "-") Term)*
+  Term          := Factor (("*" | "/") Factor)*
+  Factor        := "-"? Primary
+  Primary       := Number | "(" Expression ")" | Aggregate | Function
+  Selector      := Identifier ("{" Predicate ((","|"and"|"or") Predicate)* ","? "}")?
+  Predicate     := "not"? ( Identifier ("=" | "=~") StringLiteral
+                          | Identifier (">" | ">=" | "<" | "<=") Number
+                          | Identifier "not"? "in" "(" StringLiteral ("," ...)* ")"
+                          | Identifier ":" "*"
+                          | "(" Predicate ")" )
   GroupBy       := ("by" | "without") "(" Identifier ("," Identifier)* ","? ")"
   StringLiteral := double-quoted; \\" is a literal quote, \\\\ is a backslash
   Identifier    := [A-Za-z_][A-Za-z0-9_]*                     (case-sensitive)
 
+  There is ONE negation and it goes in front of a predicate: \`not status="ok"\`.
+  \`!=\` and \`!~\` are refused by name.
+
   The trailing Identifier after the selector \u2014 "(" Selector "," Identifier ")" \u2014
   is the VALUE LABEL: the numeric event label the aggregation reduces. Whether it
-  is required, optional, or forbidden depends on the aggregation (see below).
+  is allowed, and whether it is needed, is per aggregation (see below).
+
+${AGGREGATES_BLOCK}
 
 
 AGGREGATIONS
 ------------
-  Function        Value label   Meaning                         In experiments
-  --------------  ------------  ------------------------------  ---------------
-  count_users     forbidden     distinct users who fired it     exact
-  count           forbidden     number of events (rows)         exact
-  sum(e, v)       required      \u03A3 of numeric label v            exact
-  avg(e, v)       required      mean of label v                 exact
-  retention_Nd(e) forbidden     % of users who returned         exact
-                                within N days (N = 1..90)
-  min(e, v)       required      minimum of label v              approx \u2192 avg *
-  max(e, v)       required      maximum of label v              approx \u2192 avg *
-  unique(e, v)    required      distinct values of label v      approx \u2192 avg *
-  p50 \u2026 p999(e,v) required      quantile of v (50/75/90/        approx \u2192 avg *
-                                95/99/99.9th percentile)
-  ratio(a, b)     forbidden     a \xF7 b (see RATIO below)         proportion **
-
-  * Display-only aggregations. The experiment t-test needs a per-user mean and
-    variance, so min/max/unique/quantile are computed exactly on dashboards but
-    collapse to a per-user \`avg\` when used as an experiment metric. If you need
-    an exact experiment metric, pick count_users / count / sum / avg / retention.
-
-  ** In an experiment a ratio collapses to a per-user 0/1 outcome (a proportion),
-    not a ratio-of-sums \u2014 see RATIO.
-
-  "count" is the DSL spelling of the internal count_events (one per matching
-  row); "count_users" is unique-by-user. Getting these two confused is the most
-  common mistake \u2014 count double-counts a user who fired the event twice.
+${AGGREGATIONS_BLOCK}
+
+  A value label is optional wherever it is allowed: omitted, the aggregation
+  reduces the event's own default numeric value. \`count\` takes the event alone.
+
+  \`count\` is one per matching ROW, so a user who fired the event twice counts
+  twice.
+
+  In an experiment, \`min\`, \`max\` and \`p\` collapse to a per-user \`avg\`: the
+  t-test needs a per-user mean and variance, and those three have neither. They
+  are exact on a dashboard. For an exact experiment metric pick count / sum /
+  avg, or a rate \u2014 a rate collapses to a per-user 0/1 outcome (a proportion),
+  not a ratio-of-sums.
 
 
 SELECTOR & FILTERS
@@ -68,12 +93,36 @@ SELECTOR & FILTERS
   narrows which events count. Each filter compares an event LABEL to a quoted
   string:
 
-    =   equal            !=   not equal
-    =~  regex match      !~   regex NOT match
+    =   equal                    =~  glob match
+    >  >=  <  <=  order, NUMERIC labels only, value written BARE
+    in ("a", "b")  a value set     label:*  the label is set at all
+    not <predicate>  negation, in FRONT of the predicate
+
+  There is no \`!=\` and no \`!~\`. One negation, one place it goes:
+  \`{not tier="free"}\`. Predicates join with \`and\` / \`or\` (a comma is another
+  \`and\`) and parenthesise.
 
+  - \`=~\` takes a GLOB, NOT a regex. Two wildcards, and a glob matches the
+    WHOLE value \u2014 there are no anchors because there is nothing to anchor:
+
+      *  any sequence of characters       ?  exactly one character
+
+      route=~"/api*"          starts with /api
+      route=~"*checkout"      ends with checkout
+      route=~"*admin*"        contains admin
+      route=~"/v?/users"      /v1/users, /v2/users \u2026
+      route=~"/health"        EXACTLY /health \u2014 same as \`route="/health"\`
+
+    Every other character is a LITERAL, dots included, so \`host=~"*.acme.com"\`
+    works as written. Regex syntax \u2014 \`^\` \`$\` \`.*\` \`|\` \`[]\` \`()\` \`+\` \`{}\` \`\\\\\` \u2014 is
+    REJECTED at save time rather than reinterpreted: \`^/api\` would be a glob for
+    a value that literally starts with a caret, and \`/api/.*\` would match
+    \`/api/.x\` but not \`/api/x\`. Write \`/api*\` instead.
   - Values are ALWAYS double-quoted strings, even for numeric labels \u2014 they are
-    coerced on the server (\`amount=~"^1[0-9]$"\`, \`status="200"\`).
-  - Multiple filters are AND-ed: \`{country="US", tier!="free"}\`.
+    coerced on the server (\`status="200"\`) \u2014 EXCEPT the order comparisons,
+    whose value is written bare (\`ms > 500\`). A glob on a numeric or boolean
+    label is a validation error.
+  - Multiple predicates are AND-ed: \`{country="US", not tier="free"}\`.
   - Every filter label AND the value label must be a label DECLARED on the source
     event. Undeclared labels are a validation error, not a silent no-match.
 
@@ -85,26 +134,28 @@ GROUP-BY
     without (a, b)  group by all declared labels EXCEPT a, b
 
   NOTE: group-by is a DASHBOARD-only feature. In an experiment the group-by is
-  ignored \u2014 a per-user reducer is applied across the whole arm instead. Group-by
-  is NOT allowed on a \`ratio\` query.
+  ignored \u2014 a per-user reducer is applied across the whole arm instead.
 
 
-RATIO  (success rate, conversion, failure %, \u2026)
------------------------------------------------
-  \`ratio(numerator, denominator)\` divides one count-style arm by another. Each
-  arm is an independent selector with its OWN event and filters, so the two arms
-  can be different events:
+RATES  (success rate, conversion, failure %, \u2026)
+----------------------------------------------
+  Division is ordinary: \`a / b\`. Each side is its own expression with its own
+  event and filters, so the two sides can be different events. \`ratio(a, b)\` is
+  the same thing spelled as a function.
 
-    ratio(count(checkout_completed), count(checkout_started))
-    ratio(count_users(paid), count_users(signed_up))
-    ratio(count(payment{ok="1"}), count(payment))     one event, filtered arm
+    count(checkout_completed) / count(checkout_started)
+    count(paid) / count(signed_up)
+    count(payment{ok="1"}) / count(payment)           one event, filtered side
+    count(errors) / count(requests) * 100             as a percentage
 
   Rules:
-  - Arms are limited to \`count\` and \`count_users\` \u2014 no sum/avg/quantile arm.
-  - \`count\` arms divide event counts; \`count_users\` arms divide distinct-user
-    counts. Pick one shape and use it on both arms unless you mean to mix them.
   - A zero denominator yields 0, not an error.
-  - No \`by (...)\` / \`without (...)\`, and no retention arm, on a ratio.
+  - \`by (...)\` / \`without (...)\` applies to the whole rate, and works.
+  - AS AN EXPERIMENT METRIC both sides must be \`count\`. That is the one real
+    restriction, and it is about the per-user collapse rather than the query:
+    a rate becomes "did the numerator happen, among the users eligible for the
+    denominator", which is a 0/1 outcome per user. \`sum(a, v) / count(b)\`
+    charts fine and is refused when attached to an experiment.
   - It is a COHORT RATE over the window \u2014 numerator events \xF7 denominator events \u2014
     NOT a per-id join. It never matches an individual attempt to its outcome by a
     correlation id; it counts each side over the window and divides. If you need a
@@ -116,23 +167,22 @@ RATIO  (success rate, conversion, failure %, \u2026)
   - When creating with \`--event-name\`, pass the NUMERATOR's event name.
 
 
-NOT SUPPORTED (will fail to parse)
-----------------------------------
-  - general arithmetic / free-form formulas: \`count(a) + count(b)\`, \`2 * sum(x)\`,
-    \`avg(a) / avg(b)\` \u2014 the ONLY division form is the fixed binary
-    \`ratio(arm, arm)\` with count-style arms (see RATIO)
-  - a ratio arm that isn't \`count\` / \`count_users\`: \`ratio(sum(a, v), count(b))\`
-  - more than two events in one query
-  - \`by (...)\` / \`without (...)\` on a ratio
-  - arbitrary quantiles (only the fixed p50/p75/p90/p95/p99/p999)
-  - unquoted or numeric filter values: \`{status=200}\`  \u2192 must be \`"200"\`
-  - trailing tokens after the query
+REFUSED BY NAME
+---------------
+  Each of these is recognised in order to be refused, with a message saying what
+  to write instead. They are not gaps.
+
+${REFUSALS_BLOCK}
+
+  Also refused: \`!=\` and \`!~\` (write \`not label="v"\`), a regex inside \`=~\`
+  (globs only), an order comparison on a text label, a quoted comparison value
+  (\`ms > "500"\`), and trailing tokens after the query.
 
 
 EXAMPLES  (query  \u2014  what it measures)
 --------------------------------------
-  count_users(checkout_completed)
-      distinct users who completed checkout.
+  count(checkout_completed)
+      number of completed checkouts.
 
   count(add_to_cart{country="US"})
       number of US add-to-cart events (a user can count many times).
@@ -140,18 +190,12 @@ EXAMPLES  (query  \u2014  what it measures)
   sum(purchase{country="US"}, amount)
       total purchase amount from US purchase events.
 
-  avg(req_dur{tier!="free"}, ms) without (region)
+  avg(req_dur{not tier="free"}, ms) without (region)
       mean request duration for non-free tiers, one series per region-excluded
       label combination.
 
-  p99(req_dur{route=~"/api/.*"}, ms) by (route, status)
-      99th-percentile latency of /api/* requests, split by route and status.
-
-  unique(login{method="sso"}, device_id)
-      distinct SSO devices seen (display-only; an experiment would use per-user avg).
-
-  retention_7d(session_start)
-      share of users who started a new session within 7 days.
+  p99(req_dur{route=~"/api*"}, ms) by (route, status)
+      99th-percentile latency of /api requests, split by route and status.
 
   ratio(count(checkout_completed), count(checkout_started))
       checkout conversion rate \u2014 completions \xF7 starts over the window.