@supersdk/supercli 0.5.13-staging.125 → 0.5.13-staging.127

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -33,7 +33,7 @@ var __importStar = (this && this.__importStar) || (function () {
33
33
  };
34
34
  })();
35
35
  Object.defineProperty(exports, "__esModule", { value: true });
36
- exports.defaultExperimentDeps = exports.EXPERIMENT_LIST_MAX_PAGES = void 0;
36
+ exports.METRIC_QUERY_DEFAULT_TIME_ZONE = exports.defaultExperimentDeps = exports.EXPERIMENT_LIST_MAX_PAGES = void 0;
37
37
  exports.validExperimentKey = validExperimentKey;
38
38
  exports.percentToBasisPoints = percentToBasisPoints;
39
39
  exports.parseExpectedVersion = parseExpectedVersion;
@@ -48,14 +48,32 @@ exports.runExperimentCreate = runExperimentCreate;
48
48
  exports.runExperimentUpdate = runExperimentUpdate;
49
49
  exports.runExperimentTraffic = runExperimentTraffic;
50
50
  exports.runExperimentAction = runExperimentAction;
51
+ exports.runExperimentDelete = runExperimentDelete;
51
52
  exports.runExperimentHistory = runExperimentHistory;
52
53
  exports.runExperimentOverridesGet = runExperimentOverridesGet;
53
54
  exports.parseOverrideDevices = parseOverrideDevices;
54
55
  exports.runExperimentOverridesSet = runExperimentOverridesSet;
55
56
  exports.runExperimentMetricsList = runExperimentMetricsList;
56
- exports.buildMetricInput = buildMetricInput;
57
+ exports.buildMetricSettings = buildMetricSettings;
58
+ exports.parseMetricKeys = parseMetricKeys;
59
+ exports.buildMetricsAddBody = buildMetricsAddBody;
57
60
  exports.runExperimentMetricsAdd = runExperimentMetricsAdd;
61
+ exports.runExperimentMetricsUpdate = runExperimentMetricsUpdate;
58
62
  exports.runExperimentMetricsRemove = runExperimentMetricsRemove;
63
+ exports.buildMetricDefinition = buildMetricDefinition;
64
+ exports.buildMetricDefCreateBody = buildMetricDefCreateBody;
65
+ exports.buildMetricDefUpdateBody = buildMetricDefUpdateBody;
66
+ exports.runMetricDefsList = runMetricDefsList;
67
+ exports.runMetricDefsGet = runMetricDefsGet;
68
+ exports.runMetricDefsCreate = runMetricDefsCreate;
69
+ exports.runMetricDefsUpdate = runMetricDefsUpdate;
70
+ exports.runMetricDefsSetStatus = runMetricDefsSetStatus;
71
+ exports.runMetricDefsDelete = runMetricDefsDelete;
72
+ exports.zonedMidnightMs = zonedMidnightMs;
73
+ exports.parseQueryRange = parseQueryRange;
74
+ exports.buildMetricAnalysisRequest = buildMetricAnalysisRequest;
75
+ exports.runMetricDefsQuery = runMetricDefsQuery;
76
+ exports.runExperimentMetricsQuery = runExperimentMetricsQuery;
59
77
  exports.runExperimentResults = runExperimentResults;
60
78
  exports.runExperimentLookup = runExperimentLookup;
61
79
  exports.runExperimentVids = runExperimentVids;
@@ -71,6 +89,7 @@ exports.emitExperimentOutcome = emitExperimentOutcome;
71
89
  exports.registerExperimentCommand = registerExperimentCommand;
72
90
  const fs = __importStar(require("node:fs"));
73
91
  const experimentClient_1 = require("../api/experimentClient");
92
+ const insightsClient_1 = require("../api/insightsClient");
74
93
  const tokenAuth_1 = require("../auth/tokenAuth");
75
94
  const environments_1 = require("../config/environments");
76
95
  const resultPrinter_1 = require("../output/resultPrinter");
@@ -84,6 +103,8 @@ const PERCENT_PATTERN = /^\d{1,3}(?:\.\d{1,2})?$/;
84
103
  const METRIC_KINDS = ['conversion', 'count', 'sum', 'avg', 'pct', 'retention'];
85
104
  const METRIC_ROLES = ['metric', 'guardrail'];
86
105
  const METRIC_DIRECTIONS = ['up', 'down'];
106
+ const METRIC_DEF_STATUSES = ['active', 'deprecated'];
107
+ const METRIC_DEF_NAME_MAX_CHARS = 80;
87
108
  function isOutcome(value) {
88
109
  return value !== null && typeof value === 'object' && 'ok' in value && typeof value.ok === 'boolean';
89
110
  }
@@ -107,6 +128,7 @@ exports.defaultExperimentDeps = {
107
128
  getStoredToken: storedToken,
108
129
  markNeedsLogin: accountStore_1.markAccountNeedsLogin,
109
130
  createClient: (apiOrigin) => new experimentClient_1.ExperimentClient(apiOrigin),
131
+ createInsightsClient: (apiOrigin) => new insightsClient_1.InsightsClient(apiOrigin),
110
132
  readFile: (file) => fs.readFileSync(file),
111
133
  };
112
134
  function resolveAuth(deps) {
@@ -292,6 +314,16 @@ function failureResult(code, extra) {
292
314
  result.current_version = record.version;
293
315
  return result;
294
316
  }
317
+ const METRIC_ERROR_HINTS = {
318
+ EXP_METRIC_IN_USE: 'an experiment uses this library metric; create a new one with `experiment metric-defs create` and deprecate this one',
319
+ EXP_METRIC_LOCKED: 'the experiment has started (only --core / --no-core can change), and definitions never change through an experiment',
320
+ EXP_METRIC_DEPRECATED: 'the library metric is deprecated; `experiment metric-defs activate` it or pick another',
321
+ EXP_METRIC_LIBRARY_REQUIRED: 'add metrics with --metric <library key>; create them with `experiment metric-defs create`',
322
+ };
323
+ /** Hints for experiment-level rejections that depend on the command. */
324
+ const ACTION_ERROR_HINTS = {
325
+ delete: { EXP_INVALID_STATE: 'only a never-started draft can be deleted; end a started experiment and archive it instead' },
326
+ };
295
327
  function experimentFailure(outcome, action, key) {
296
328
  switch (outcome.kind) {
297
329
  case 'business_error': {
@@ -309,6 +341,9 @@ function experimentFailure(outcome, action, key) {
309
341
  // (held + free in the layer; for reopen continue = reclaimable width).
310
342
  message += ` (layer ${str(capacity.layer_key)}: at most ${pct(capacity.available_bp)} available, ${pct(capacity.requested_bp)} requested)`;
311
343
  }
344
+ const hint = ACTION_ERROR_HINTS[action]?.[outcome.code] ?? METRIC_ERROR_HINTS[outcome.code];
345
+ if (hint)
346
+ message += ` — ${hint}`;
312
347
  const base = { ok: false, kind: 'business_error', publicCode: outcome.code, message };
313
348
  return extra ? { ...base, result: extra } : base;
314
349
  }
@@ -723,6 +758,30 @@ async function runExperimentAction(action, keyRaw, opts, requestId, deps = expor
723
758
  return handleFailure(outcome, ctx.auth, deps, label, key);
724
759
  return ok(withScope(scope, { experiment: outcome.data }), `${ACTION_VERB[action]}\n${experimentSummary(outcome.data)}`);
725
760
  }
761
+ /**
762
+ * Delete a never-started draft (experiment-metric-library-spec §4.1): the experiment, its
763
+ * variants, override list, metrics and change history are removed and the key can be reused.
764
+ * A started experiment is rejected with EXP_INVALID_STATE (end it, then archive it).
765
+ */
766
+ async function runExperimentDelete(keyRaw, opts, requestId, deps = exports.defaultExperimentDeps) {
767
+ const key = validExperimentKey(keyRaw);
768
+ if (isOutcome(key))
769
+ return key;
770
+ const version = parseExpectedVersion(opts.expectedVersion);
771
+ if (isOutcome(version))
772
+ return version;
773
+ const scope = resolveEnvScope(opts);
774
+ if (isOutcome(scope))
775
+ return scope;
776
+ const ctx = begin(deps, requestId);
777
+ if (isOutcome(ctx))
778
+ return ctx;
779
+ const outcome = await ctx.client.delete(ctx.token, scope, key, version);
780
+ if (outcome.kind !== 'success')
781
+ return handleFailure(outcome, ctx.auth, deps, 'delete', key);
782
+ const record = asRecord(outcome.data);
783
+ return ok(withScope(scope, record ?? { deleted: true, key }), `deleted ${str(record?.key ?? key)}`);
784
+ }
726
785
  async function runExperimentHistory(keyRaw, opts, deps = exports.defaultExperimentDeps) {
727
786
  const key = validExperimentKey(keyRaw);
728
787
  if (isOutcome(key))
@@ -816,7 +875,12 @@ async function runExperimentOverridesSet(keyRaw, opts, requestId, deps = exports
816
875
  const count = Array.isArray(data?.overrides) ? data.overrides.length : devices.length;
817
876
  return ok(withScope(scope, { key, overrides: outcome.data }), `overrides replaced: ${count} device(s) · version ${str(data?.version)}`);
818
877
  }
819
- // ── metrics ──────────────────────────────────────────────────────────────────────────────
878
+ // ── metrics (experiment side: selected from the project metric library) ──────────────────
879
+ function metricsResult(key, data) {
880
+ // Pass the server body through (`metrics`, `locked`, …); `key` names the experiment.
881
+ const record = asRecord(data);
882
+ return record ? { ...record, key } : { key, metrics: data };
883
+ }
820
884
  async function runExperimentMetricsList(keyRaw, opts, deps = exports.defaultExperimentDeps) {
821
885
  const key = validExperimentKey(keyRaw);
822
886
  if (isOutcome(key))
@@ -830,20 +894,25 @@ async function runExperimentMetricsList(keyRaw, opts, deps = exports.defaultExpe
830
894
  const outcome = await ctx.client.listMetrics(ctx.token, scope, key);
831
895
  if (outcome.kind !== 'success')
832
896
  return handleFailure(outcome, ctx.auth, deps, 'metrics list', key);
833
- return ok(withScope(scope, { key, metrics: asRecord(outcome.data)?.metrics ?? outcome.data }), metricsSummary(outcome.data));
897
+ return ok(withScope(scope, metricsResult(key, outcome.data)), metricsSummary(outcome.data));
834
898
  }
835
899
  function metricsSummary(data) {
836
- const metrics = asRecord(data)?.metrics;
900
+ const record = asRecord(data);
901
+ const metrics = record?.metrics;
837
902
  if (!Array.isArray(metrics))
838
903
  return JSON.stringify(data, null, 2);
839
- if (metrics.length === 0)
840
- return 'no metrics';
841
- return metrics.map((raw) => {
904
+ const lines = metrics.map((raw) => {
842
905
  const metric = asRecord(raw) ?? {};
843
906
  const core = metric.is_core === true ? ' core' : '';
844
907
  const tolerance = typeof metric.tolerance_pct === 'number' ? ` tolerance ${metric.tolerance_pct}%` : '';
845
- return `${str(metric.metric_key)}\t${str(metric.role)}${core}\t${str(metric.kind)}\t${str(metric.event_name)}\t${str(metric.direction)}${tolerance}`;
846
- }).join('\n');
908
+ const library = `library ${str(metric.library_key)}${metric.library_status === 'deprecated' ? ' (deprecated)' : ''}`;
909
+ return `${str(metric.metric_key)}\t${str(metric.role)}${core}\t${str(metric.kind)}\t${str(metric.event_name)}\t${str(metric.direction)}${tolerance}\t${library}`;
910
+ });
911
+ if (lines.length === 0)
912
+ lines.push('no metrics');
913
+ if (record?.locked === true)
914
+ lines.push('locked: the experiment has started; only the core flag can change');
915
+ return lines.join('\n');
847
916
  }
848
917
  function pickEnum(raw, allowed, flag) {
849
918
  if (raw === undefined)
@@ -853,58 +922,165 @@ function pickEnum(raw, allowed, flag) {
853
922
  return usage(`${flag} must be one of ${allowed.join(', ')}`);
854
923
  return value;
855
924
  }
856
- function buildMetricInput(opts, deps) {
857
- const kind = pickEnum(opts.kind, METRIC_KINDS, '--kind');
858
- if (isOutcome(kind))
859
- return kind;
860
- if (!kind)
861
- return usage(`--kind is required (${METRIC_KINDS.join(', ')})`);
862
- const event = opts.event?.trim();
863
- if (!event)
864
- return usage('--event is required');
925
+ function validMetricKey(raw, label = 'metric key') {
926
+ const key = raw?.trim() ?? '';
927
+ if (!experimentClient_1.EXPERIMENT_METRIC_KEY_PATTERN.test(key))
928
+ return usage(`${label} must match ^[a-z][a-z0-9_]{1,39}$`);
929
+ return key;
930
+ }
931
+ /** Per-experiment settings shared by `metrics add` (applied to every --metric) and `metrics update`. */
932
+ function buildMetricSettings(opts) {
865
933
  const role = pickEnum(opts.role, METRIC_ROLES, '--role');
866
934
  if (isOutcome(role))
867
935
  return role;
868
936
  const direction = pickEnum(opts.direction, METRIC_DIRECTIONS, '--direction');
869
937
  if (isOutcome(direction))
870
938
  return direction;
871
- const metric = { kind, event_name: event };
872
- if (opts.metricKey !== undefined) {
873
- const metricKey = validExperimentKey(opts.metricKey, '--metric-key');
874
- if (isOutcome(metricKey))
875
- return metricKey;
876
- metric.metric_key = metricKey;
877
- }
939
+ const settings = {};
878
940
  if (role)
879
- metric.role = role;
880
- if (opts.core === true)
881
- metric.is_core = true;
941
+ settings.role = role;
882
942
  if (direction)
883
- metric.direction = direction;
884
- if (opts.tolerance !== undefined) {
885
- const tolerance = Number(opts.tolerance.trim());
886
- if (!/^\d+(?:\.\d+)?$/.test(opts.tolerance.trim()) || !Number.isFinite(tolerance)) {
887
- return usage('--tolerance must be a non-negative percentage, e.g. 5 or 2.5');
888
- }
889
- metric.tolerance_pct = tolerance;
890
- }
943
+ settings.direction = direction;
891
944
  const window = parseBoundedInt(opts.windowDays, '--window-days', 1, 60);
892
945
  if (isOutcome(window))
893
946
  return window;
894
947
  if (window !== undefined)
895
- metric.window_days = window;
948
+ settings.window_days = window;
949
+ if (opts.tolerance !== undefined) {
950
+ const raw = opts.tolerance.trim();
951
+ const tolerance = Number(raw);
952
+ if (!/^\d+(?:\.\d+)?$/.test(raw) || !Number.isFinite(tolerance)) {
953
+ return usage('--tolerance must be a non-negative percentage, e.g. 5 or 2.5');
954
+ }
955
+ settings.tolerance_pct = tolerance;
956
+ }
957
+ if (opts.core !== undefined)
958
+ settings.is_core = opts.core;
959
+ return settings;
960
+ }
961
+ /** `--metric a --metric b,c` → [a, b, c]; duplicates are a usage error. */
962
+ function parseMetricKeys(raw) {
963
+ const keys = [];
964
+ for (const item of raw ?? []) {
965
+ for (const part of item.split(',')) {
966
+ const key = validMetricKey(part, '--metric');
967
+ if (isOutcome(key))
968
+ return key;
969
+ if (keys.includes(key))
970
+ return usage(`duplicate --metric ${key}`);
971
+ keys.push(key);
972
+ }
973
+ }
974
+ if (keys.length === 0)
975
+ return usage('--metric <library key> is required (repeatable or comma-separated); see `supercli experiment metric-defs list`');
976
+ return keys;
977
+ }
978
+ function buildMetricsAddBody(opts) {
979
+ const keys = parseMetricKeys(opts.metric);
980
+ if (isOutcome(keys))
981
+ return keys;
982
+ // `--core` on add only ever sets the flag; `false` is the server default.
983
+ const settings = buildMetricSettings({ ...opts, core: opts.core === true ? true : undefined });
984
+ if (isOutcome(settings))
985
+ return settings;
986
+ return { metrics: keys.map((library_key) => ({ library_key, ...settings })) };
987
+ }
988
+ async function runExperimentMetricsAdd(keyRaw, opts, requestId, deps = exports.defaultExperimentDeps) {
989
+ const key = validExperimentKey(keyRaw);
990
+ if (isOutcome(key))
991
+ return key;
992
+ const body = buildMetricsAddBody(opts);
993
+ if (isOutcome(body))
994
+ return body;
995
+ const scope = resolveEnvScope(opts);
996
+ if (isOutcome(scope))
997
+ return scope;
998
+ const ctx = begin(deps, requestId);
999
+ if (isOutcome(ctx))
1000
+ return ctx;
1001
+ const outcome = await ctx.client.addMetrics(ctx.token, scope, key, body);
1002
+ if (outcome.kind !== 'success')
1003
+ return handleFailure(outcome, ctx.auth, deps, 'metrics add', key);
1004
+ return ok(withScope(scope, metricsResult(key, outcome.data)), metricsSummary(outcome.data));
1005
+ }
1006
+ async function runExperimentMetricsUpdate(keyRaw, metricKeyRaw, opts, requestId, deps = exports.defaultExperimentDeps) {
1007
+ const key = validExperimentKey(keyRaw);
1008
+ if (isOutcome(key))
1009
+ return key;
1010
+ const metricKey = validMetricKey(metricKeyRaw);
1011
+ if (isOutcome(metricKey))
1012
+ return metricKey;
1013
+ const body = buildMetricSettings(opts);
1014
+ if (isOutcome(body))
1015
+ return body;
1016
+ if (Object.keys(body).length === 0) {
1017
+ return usage('nothing to update — pass at least one of --role, --direction, --window-days, --tolerance, --core, --no-core');
1018
+ }
1019
+ const scope = resolveEnvScope(opts);
1020
+ if (isOutcome(scope))
1021
+ return scope;
1022
+ const ctx = begin(deps, requestId);
1023
+ if (isOutcome(ctx))
1024
+ return ctx;
1025
+ const outcome = await ctx.client.patchMetric(ctx.token, scope, key, metricKey, body);
1026
+ if (outcome.kind !== 'success')
1027
+ return handleFailure(outcome, ctx.auth, deps, 'metrics update', key);
1028
+ return ok(withScope(scope, metricsResult(key, outcome.data)), `updated ${metricKey}\n${metricsSummary(outcome.data)}`);
1029
+ }
1030
+ async function runExperimentMetricsRemove(keyRaw, metricKeyRaw, opts, requestId, deps = exports.defaultExperimentDeps) {
1031
+ const key = validExperimentKey(keyRaw);
1032
+ if (isOutcome(key))
1033
+ return key;
1034
+ const metricKey = validMetricKey(metricKeyRaw);
1035
+ if (isOutcome(metricKey))
1036
+ return metricKey;
1037
+ const scope = resolveEnvScope(opts);
1038
+ if (isOutcome(scope))
1039
+ return scope;
1040
+ const ctx = begin(deps, requestId);
1041
+ if (isOutcome(ctx))
1042
+ return ctx;
1043
+ const outcome = await ctx.client.removeMetric(ctx.token, scope, key, metricKey);
1044
+ if (outcome.kind !== 'success')
1045
+ return handleFailure(outcome, ctx.auth, deps, 'metrics remove', key);
1046
+ return ok(withScope(scope, { ...metricsResult(key, outcome.data), removed: metricKey }), `removed ${metricKey}\n${metricsSummary(outcome.data)}`);
1047
+ }
1048
+ /**
1049
+ * Definition fields of a library metric. On create `--kind` / `--event` are required and the
1050
+ * kind-specific fields are checked; on update every field is optional (the server merges and
1051
+ * re-validates, and rejects definition changes on a used metric with EXP_METRIC_IN_USE).
1052
+ */
1053
+ function buildMetricDefinition(opts, deps, mode) {
1054
+ const kind = pickEnum(opts.kind, METRIC_KINDS, '--kind');
1055
+ if (isOutcome(kind))
1056
+ return kind;
1057
+ if (mode === 'create' && !kind)
1058
+ return usage(`--kind is required (${METRIC_KINDS.join(', ')})`);
1059
+ const def = {};
1060
+ if (kind)
1061
+ def.kind = kind;
1062
+ if (opts.event !== undefined || mode === 'create') {
1063
+ const event = opts.event?.trim();
1064
+ if (!event)
1065
+ return usage('--event is required and must not be empty');
1066
+ def.event_name = event;
1067
+ }
896
1068
  const retentionDay = parseBoundedInt(opts.retentionDay, '--retention-day', 1, 30);
897
1069
  if (isOutcome(retentionDay))
898
1070
  return retentionDay;
899
1071
  if (retentionDay !== undefined)
900
- metric.retention_day = retentionDay;
901
- if (kind === 'retention' && retentionDay === undefined)
1072
+ def.retention_day = retentionDay;
1073
+ if (mode === 'create' && kind === 'retention' && retentionDay === undefined) {
902
1074
  return usage('--retention-day is required for --kind retention (1-30)');
1075
+ }
903
1076
  const percentile = parseBoundedInt(opts.percentile, '--percentile', 1, 99);
904
1077
  if (isOutcome(percentile))
905
1078
  return percentile;
906
1079
  if (percentile !== undefined)
907
- metric.percentile = percentile;
1080
+ def.percentile = percentile;
1081
+ if (mode === 'create' && kind === 'pct' && percentile === undefined) {
1082
+ return usage('--percentile is required for --kind pct (1-99)');
1083
+ }
908
1084
  if (opts.property !== undefined) {
909
1085
  const name = opts.property.trim();
910
1086
  const valueType = opts.propertyType?.trim() ?? 'float';
@@ -912,10 +1088,17 @@ function buildMetricInput(opts, deps) {
912
1088
  return usage('--property must name a numeric event property');
913
1089
  if (valueType !== 'int' && valueType !== 'float')
914
1090
  return usage('--property-type must be int or float');
915
- metric.property = { name, value_type: valueType };
1091
+ const columnKind = opts.propertyColumn?.trim();
1092
+ if (columnKind !== undefined && columnKind !== 'dynamic' && columnKind !== 'fixed') {
1093
+ return usage('--property-column must be dynamic or fixed');
1094
+ }
1095
+ def.property = { name, value_type: valueType, ...(columnKind ? { column_kind: columnKind } : {}) };
1096
+ }
1097
+ else if (opts.propertyType !== undefined || opts.propertyColumn !== undefined) {
1098
+ return usage('--property-type / --property-column need --property');
916
1099
  }
917
- if ((kind === 'sum' || kind === 'avg' || kind === 'pct') && metric.property === undefined) {
918
- return usage(`--property is required for --kind ${kind}`);
1100
+ if (mode === 'create' && (kind === 'sum' || kind === 'avg' || kind === 'pct') && def.property === undefined) {
1101
+ return usage(`--property is required for --kind ${String(kind)}`);
919
1102
  }
920
1103
  if (opts.filters !== undefined) {
921
1104
  const filters = readJsonSource(opts.filters, '--filters', deps);
@@ -923,45 +1106,323 @@ function buildMetricInput(opts, deps) {
923
1106
  return filters;
924
1107
  if (!Array.isArray(filters.value))
925
1108
  return usage('--filters must be a JSON array of {name, value_type, operator, values}');
926
- metric.filters = filters.value;
1109
+ def.filters = filters.value;
927
1110
  }
928
- return metric;
1111
+ return def;
929
1112
  }
930
- async function runExperimentMetricsAdd(keyRaw, opts, requestId, deps = exports.defaultExperimentDeps) {
931
- const key = validExperimentKey(keyRaw);
932
- if (isOutcome(key))
933
- return key;
934
- const metric = buildMetricInput(opts, deps);
935
- if (isOutcome(metric))
936
- return metric;
937
- const scope = resolveEnvScope(opts);
938
- if (isOutcome(scope))
939
- return scope;
1113
+ function metricDefText(opts, body) {
1114
+ if (opts.name !== undefined) {
1115
+ const name = opts.name.trim();
1116
+ if (!name)
1117
+ return usage('--name must not be empty');
1118
+ if ([...name].length > METRIC_DEF_NAME_MAX_CHARS)
1119
+ return usage(`--name must be at most ${METRIC_DEF_NAME_MAX_CHARS} characters`);
1120
+ body.name = name;
1121
+ }
1122
+ const description = validDescription(opts.description, false);
1123
+ if (isOutcome(description))
1124
+ return description;
1125
+ if (description !== undefined)
1126
+ body.description = description;
1127
+ const direction = pickEnum(opts.direction, METRIC_DIRECTIONS, '--direction');
1128
+ if (isOutcome(direction))
1129
+ return direction;
1130
+ if (direction)
1131
+ body.direction = direction;
1132
+ return undefined;
1133
+ }
1134
+ function buildMetricDefCreateBody(opts, deps) {
1135
+ const body = {};
1136
+ if (opts.key !== undefined) {
1137
+ const key = validMetricKey(opts.key, '--key');
1138
+ if (isOutcome(key))
1139
+ return key;
1140
+ body.metric_key = key;
1141
+ }
1142
+ const text = metricDefText(opts, body);
1143
+ if (text)
1144
+ return text;
1145
+ const def = buildMetricDefinition(opts, deps, 'create');
1146
+ if (isOutcome(def))
1147
+ return def;
1148
+ return { ...body, ...def };
1149
+ }
1150
+ function buildMetricDefUpdateBody(opts, deps) {
1151
+ const body = {};
1152
+ const text = metricDefText(opts, body);
1153
+ if (text)
1154
+ return text;
1155
+ const def = buildMetricDefinition(opts, deps, 'update');
1156
+ if (isOutcome(def))
1157
+ return def;
1158
+ const merged = { ...body, ...def };
1159
+ if (Object.keys(merged).length === 0) {
1160
+ return usage('nothing to update — pass at least one of --name, --description, --direction, --kind, --event, --property, --percentile, --retention-day, --filters');
1161
+ }
1162
+ return merged;
1163
+ }
1164
+ function metricDefLine(raw) {
1165
+ const metric = asRecord(raw) ?? {};
1166
+ return `${str(metric.metric_key)}\t${str(metric.status)}\t${str(metric.kind)}\t${str(metric.event_name)}\t${str(metric.direction)}\tused by ${str(metric.usage_count)}\t${str(metric.name)}`;
1167
+ }
1168
+ function metricDefDetail(raw) {
1169
+ const lines = [metricDefLine(raw)];
1170
+ const usedBy = asRecord(raw)?.used_by;
1171
+ if (Array.isArray(usedBy)) {
1172
+ for (const item of usedBy) {
1173
+ const row = asRecord(item) ?? {};
1174
+ lines.push(` - ${str(row.env)} ${str(row.experiment_key)} (${str(row.status)}) ${str(row.experiment_name)}`);
1175
+ }
1176
+ }
1177
+ return lines.join('\n');
1178
+ }
1179
+ function metricDefsSummary(data) {
1180
+ const metrics = asRecord(data)?.metrics;
1181
+ if (!Array.isArray(metrics))
1182
+ return JSON.stringify(data, null, 2);
1183
+ return metrics.map(metricDefLine).join('\n') || 'no library metrics';
1184
+ }
1185
+ async function runMetricDefsList(opts, deps = exports.defaultExperimentDeps) {
1186
+ const status = pickEnum(opts.status, METRIC_DEF_STATUSES, '--status');
1187
+ if (isOutcome(status))
1188
+ return status;
1189
+ const project = resolveProject(opts);
1190
+ if (isOutcome(project))
1191
+ return project;
1192
+ const ctx = begin(deps);
1193
+ if (isOutcome(ctx))
1194
+ return ctx;
1195
+ const outcome = await ctx.client.listMetricDefs(ctx.token, project, status);
1196
+ if (outcome.kind !== 'success')
1197
+ return handleFailure(outcome, ctx.auth, deps, 'metric-defs list');
1198
+ const record = asRecord(outcome.data);
1199
+ return ok(withScope(project, record ? { ...record } : { metrics: outcome.data }), metricDefsSummary(outcome.data));
1200
+ }
1201
+ async function runMetricDefsGet(metricKeyRaw, opts, deps = exports.defaultExperimentDeps) {
1202
+ const metricKey = validMetricKey(metricKeyRaw);
1203
+ if (isOutcome(metricKey))
1204
+ return metricKey;
1205
+ const project = resolveProject(opts);
1206
+ if (isOutcome(project))
1207
+ return project;
1208
+ const ctx = begin(deps);
1209
+ if (isOutcome(ctx))
1210
+ return ctx;
1211
+ const outcome = await ctx.client.getMetricDef(ctx.token, project, metricKey);
1212
+ if (outcome.kind !== 'success')
1213
+ return handleFailure(outcome, ctx.auth, deps, 'metric-defs get');
1214
+ return ok(withScope(project, { metric: outcome.data }), metricDefDetail(outcome.data));
1215
+ }
1216
+ async function runMetricDefsCreate(opts, requestId, deps = exports.defaultExperimentDeps) {
1217
+ const body = buildMetricDefCreateBody(opts, deps);
1218
+ if (isOutcome(body))
1219
+ return body;
1220
+ const project = resolveProject(opts);
1221
+ if (isOutcome(project))
1222
+ return project;
940
1223
  const ctx = begin(deps, requestId);
941
1224
  if (isOutcome(ctx))
942
1225
  return ctx;
943
- const outcome = await ctx.client.addMetrics(ctx.token, scope, key, { metrics: [metric] });
1226
+ const outcome = await ctx.client.createMetricDef(ctx.token, project, body);
944
1227
  if (outcome.kind !== 'success')
945
- return handleFailure(outcome, ctx.auth, deps, 'metrics add', key);
946
- return ok(withScope(scope, { key, metrics: asRecord(outcome.data)?.metrics ?? outcome.data }), metricsSummary(outcome.data));
1228
+ return handleFailure(outcome, ctx.auth, deps, 'metric-defs create');
1229
+ return ok(withScope(project, { metric: outcome.data }), `created library metric\n${metricDefLine(outcome.data)}`);
947
1230
  }
948
- async function runExperimentMetricsRemove(keyRaw, metricKeyRaw, opts, requestId, deps = exports.defaultExperimentDeps) {
1231
+ async function patchMetricDef(metricKeyRaw, opts, body, action, verb, requestId, deps) {
1232
+ const metricKey = validMetricKey(metricKeyRaw);
1233
+ if (isOutcome(metricKey))
1234
+ return metricKey;
1235
+ if (isOutcome(body))
1236
+ return body;
1237
+ const project = resolveProject(opts);
1238
+ if (isOutcome(project))
1239
+ return project;
1240
+ const ctx = begin(deps, requestId);
1241
+ if (isOutcome(ctx))
1242
+ return ctx;
1243
+ const outcome = await ctx.client.updateMetricDef(ctx.token, project, metricKey, body);
1244
+ if (outcome.kind !== 'success')
1245
+ return handleFailure(outcome, ctx.auth, deps, action);
1246
+ return ok(withScope(project, { metric: outcome.data }), `${verb}\n${metricDefLine(outcome.data)}`);
1247
+ }
1248
+ function runMetricDefsUpdate(metricKeyRaw, opts, requestId, deps = exports.defaultExperimentDeps) {
1249
+ return patchMetricDef(metricKeyRaw, opts, buildMetricDefUpdateBody(opts, deps), 'metric-defs update', 'updated library metric', requestId, deps);
1250
+ }
1251
+ function runMetricDefsSetStatus(status, metricKeyRaw, opts, requestId, deps = exports.defaultExperimentDeps) {
1252
+ const action = status === 'deprecated' ? 'deprecate' : 'activate';
1253
+ return patchMetricDef(metricKeyRaw, opts, { status }, `metric-defs ${action}`, `${action}d library metric`, requestId, deps);
1254
+ }
1255
+ async function runMetricDefsDelete(metricKeyRaw, opts, requestId, deps = exports.defaultExperimentDeps) {
1256
+ const metricKey = validMetricKey(metricKeyRaw);
1257
+ if (isOutcome(metricKey))
1258
+ return metricKey;
1259
+ const project = resolveProject(opts);
1260
+ if (isOutcome(project))
1261
+ return project;
1262
+ const ctx = begin(deps, requestId);
1263
+ if (isOutcome(ctx))
1264
+ return ctx;
1265
+ const outcome = await ctx.client.deleteMetricDef(ctx.token, project, metricKey);
1266
+ if (outcome.kind !== 'success')
1267
+ return handleFailure(outcome, ctx.auth, deps, 'metric-defs delete');
1268
+ // DELETE returns the remaining `{ metrics, limit }`; passed through.
1269
+ const record = asRecord(outcome.data);
1270
+ return ok(withScope(project, { ...(record ?? { metrics: outcome.data }), deleted: true, metric_key: metricKey }), `deleted library metric ${metricKey}`);
1271
+ }
1272
+ // ── metric → analysis query (reuses the console analytics routes behind `analytics events-query` / `retention`) ──
1273
+ const DATE_PATTERN = /^(\d{4})-(\d{2})-(\d{2})$/;
1274
+ const DAY_MS = 86_400_000;
1275
+ exports.METRIC_QUERY_DEFAULT_TIME_ZONE = 'Asia/Shanghai';
1276
+ /** Experiment metric kind → event-analysis algorithm (same mapping as the console). */
1277
+ const ANALYTICS_KIND = { conversion: 'uv', count: 'pv', sum: 'sum', avg: 'avg', pct: 'pct' };
1278
+ function zoneOffsetMs(timeZone, utcMs) {
1279
+ const parts = new Intl.DateTimeFormat('en-US', {
1280
+ timeZone, hourCycle: 'h23', year: 'numeric', month: '2-digit', day: '2-digit', hour: '2-digit', minute: '2-digit', second: '2-digit',
1281
+ }).formatToParts(new Date(utcMs));
1282
+ const get = (type) => Number(parts.find((part) => part.type === type)?.value);
1283
+ return Date.UTC(get('year'), get('month') - 1, get('day'), get('hour'), get('minute'), get('second')) - utcMs;
1284
+ }
1285
+ /** Midnight of a calendar day in an IANA zone, as epoch ms. */
1286
+ function zonedMidnightMs(year, month, day, timeZone) {
1287
+ const wall = Date.UTC(year, month - 1, day);
1288
+ const first = wall - zoneOffsetMs(timeZone, wall);
1289
+ return wall - zoneOffsetMs(timeZone, first);
1290
+ }
1291
+ /** `--from` / `--to` are inclusive calendar days in `--time-zone`; the end is the next midnight (exclusive). */
1292
+ function parseQueryRange(opts) {
1293
+ const timeZone = opts.timeZone?.trim() || exports.METRIC_QUERY_DEFAULT_TIME_ZONE;
1294
+ try {
1295
+ new Intl.DateTimeFormat('en-US', { timeZone });
1296
+ }
1297
+ catch {
1298
+ return usage(`--time-zone ${JSON.stringify(timeZone)} is not an IANA time zone`);
1299
+ }
1300
+ const days = [];
1301
+ for (const [flag, raw] of [['--from', opts.from], ['--to', opts.to]]) {
1302
+ const match = DATE_PATTERN.exec(raw?.trim() ?? '');
1303
+ const parts = match ? [Number(match[1]), Number(match[2]), Number(match[3])] : [];
1304
+ const check = match ? new Date(Date.UTC(parts[0], parts[1] - 1, parts[2])) : undefined;
1305
+ if (!check || check.getUTCMonth() !== parts[1] - 1 || check.getUTCDate() !== parts[2]) {
1306
+ return usage(`${flag} is required and must be a date YYYY-MM-DD`);
1307
+ }
1308
+ days.push(parts);
1309
+ }
1310
+ const start = zonedMidnightMs(days[0][0], days[0][1], days[0][2], timeZone);
1311
+ const next = new Date(Date.UTC(days[1][0], days[1][1] - 1, days[1][2]) + DAY_MS);
1312
+ const end = zonedMidnightMs(next.getUTCFullYear(), next.getUTCMonth() + 1, next.getUTCDate(), timeZone);
1313
+ if (end <= start)
1314
+ return usage('--to must not be before --from');
1315
+ return { start_time_ms: start, end_time_ms: end, time_zone: timeZone };
1316
+ }
1317
+ /**
1318
+ * Build the analytics request body for a metric definition (library or experiment copy):
1319
+ * retention → `/analytics/retention` (n_days = retention_day, all users); every other kind →
1320
+ * one event with one algorithm in `/analytics/events/query`, filters attached to the event.
1321
+ * `spid` / `env` are filled in when the query is sent.
1322
+ */
1323
+ function buildMetricAnalysisRequest(definition, range) {
1324
+ const def = asRecord(definition);
1325
+ const kind = typeof def?.kind === 'string' ? def.kind : '';
1326
+ const eventName = typeof def?.event_name === 'string' ? def.event_name : '';
1327
+ if (!def || !eventName)
1328
+ return { ok: false, kind: 'infra_error', message: 'metric definition is missing kind / event_name' };
1329
+ const filters = Array.isArray(def.filters) ? def.filters : [];
1330
+ if (kind === 'retention') {
1331
+ return {
1332
+ command: 'retention',
1333
+ request: {
1334
+ event_name: eventName,
1335
+ user_type: 'all',
1336
+ n_days: typeof def.retention_day === 'number' ? def.retention_day : 7,
1337
+ filters,
1338
+ ...range,
1339
+ },
1340
+ };
1341
+ }
1342
+ const analyticsKind = ANALYTICS_KIND[kind];
1343
+ if (!analyticsKind)
1344
+ return { ok: false, kind: 'infra_error', message: `metric kind ${JSON.stringify(kind)} has no analysis mapping` };
1345
+ const metric = { kind: analyticsKind };
1346
+ if (analyticsKind === 'sum' || analyticsKind === 'avg' || analyticsKind === 'pct')
1347
+ metric.property = def.property ?? null;
1348
+ if (analyticsKind === 'pct')
1349
+ metric.percentile = def.percentile ?? null;
1350
+ return {
1351
+ command: 'events-query',
1352
+ request: { level: 'day', ...range, events: [{ event_name: eventName, metrics: [metric], filters }] },
1353
+ };
1354
+ }
1355
+ async function runMetricAnalysis(ctx, deps, scope, label, definition, range, printSpec, action) {
1356
+ const built = buildMetricAnalysisRequest(definition, range);
1357
+ if (isOutcome(built))
1358
+ return built;
1359
+ if (printSpec) {
1360
+ return ok(withScope(scope, { ...label, analysis: built.command, request: built.request }), `${JSON.stringify(built.request, null, 2)}\n\nsave it as a file and run: supercli analytics ${built.command} --config <super.json> --env <env> --file <file>`);
1361
+ }
1362
+ const insights = (deps.createInsightsClient ?? ((origin) => new insightsClient_1.InsightsClient(origin)))(ctx.auth.apiOrigin);
1363
+ const payload = { ...built.request, spid: scope.spid, ...(scope.env ? { env: scope.env } : {}) };
1364
+ const outcome = built.command === 'retention'
1365
+ ? await insights.retention({ token: ctx.auth.token }, payload)
1366
+ : await insights.eventsQuery({ token: ctx.auth.token }, payload);
1367
+ if (outcome.kind !== 'success')
1368
+ return handleFailure(outcome, ctx.auth, deps, action);
1369
+ const resultKey = built.command === 'retention' ? 'retention' : 'query';
1370
+ return ok(withScope(scope, { ...label, analysis: built.command, request: built.request, [resultKey]: outcome.data }), JSON.stringify(outcome.data, null, 2));
1371
+ }
1372
+ function optionalEnv(raw) {
1373
+ if (raw === undefined)
1374
+ return undefined;
1375
+ const env = raw.trim();
1376
+ if (!ENV_NAME_PATTERN.test(env))
1377
+ return usage('--env must be 1-10 lowercase letters or digits');
1378
+ return env;
1379
+ }
1380
+ async function runMetricDefsQuery(metricKeyRaw, opts, deps = exports.defaultExperimentDeps) {
1381
+ const metricKey = validMetricKey(metricKeyRaw);
1382
+ if (isOutcome(metricKey))
1383
+ return metricKey;
1384
+ const range = parseQueryRange(opts);
1385
+ if (isOutcome(range))
1386
+ return range;
1387
+ const env = optionalEnv(opts.env);
1388
+ if (isOutcome(env))
1389
+ return env;
1390
+ const project = resolveProject(opts);
1391
+ if (isOutcome(project))
1392
+ return project;
1393
+ const ctx = begin(deps);
1394
+ if (isOutcome(ctx))
1395
+ return ctx;
1396
+ const outcome = await ctx.client.getMetricDef(ctx.token, project, metricKey);
1397
+ if (outcome.kind !== 'success')
1398
+ return handleFailure(outcome, ctx.auth, deps, 'metric-defs query');
1399
+ return runMetricAnalysis(ctx, deps, { ...project, ...(env ? { env } : {}) }, { metric_key: metricKey }, outcome.data, range, opts.printSpec === true, 'metric-defs query');
1400
+ }
1401
+ async function runExperimentMetricsQuery(keyRaw, metricKeyRaw, opts, deps = exports.defaultExperimentDeps) {
949
1402
  const key = validExperimentKey(keyRaw);
950
1403
  if (isOutcome(key))
951
1404
  return key;
952
- const metricKey = metricKeyRaw?.trim() ?? '';
953
- if (!experimentClient_1.EXPERIMENT_METRIC_KEY_PATTERN.test(metricKey))
954
- return usage('metric key must match ^[a-z][a-z0-9_]{1,39}$');
1405
+ const metricKey = validMetricKey(metricKeyRaw);
1406
+ if (isOutcome(metricKey))
1407
+ return metricKey;
1408
+ const range = parseQueryRange(opts);
1409
+ if (isOutcome(range))
1410
+ return range;
955
1411
  const scope = resolveEnvScope(opts);
956
1412
  if (isOutcome(scope))
957
1413
  return scope;
958
- const ctx = begin(deps, requestId);
1414
+ const ctx = begin(deps);
959
1415
  if (isOutcome(ctx))
960
1416
  return ctx;
961
- const outcome = await ctx.client.removeMetric(ctx.token, scope, key, metricKey);
1417
+ const outcome = await ctx.client.listMetrics(ctx.token, scope, key);
962
1418
  if (outcome.kind !== 'success')
963
- return handleFailure(outcome, ctx.auth, deps, 'metrics remove', key);
964
- return ok(withScope(scope, { key, removed: metricKey, metrics: asRecord(outcome.data)?.metrics ?? outcome.data }), `removed ${metricKey}\n${metricsSummary(outcome.data)}`);
1419
+ return handleFailure(outcome, ctx.auth, deps, 'metrics query', key);
1420
+ const metrics = asRecord(outcome.data)?.metrics;
1421
+ const found = Array.isArray(metrics) ? metrics.find((raw) => asRecord(raw)?.metric_key === metricKey) : undefined;
1422
+ if (!found) {
1423
+ return { ok: false, kind: 'business_error', publicCode: 'EXP_METRIC_NOT_FOUND', message: `experiment ${key} has no metric ${metricKey} — see \`supercli experiment metrics list ${key}\`` };
1424
+ }
1425
+ return runMetricAnalysis(ctx, deps, scope, { key, metric_key: metricKey }, found, range, opts.printSpec === true, 'metrics query');
965
1426
  }
966
1427
  async function runExperimentResults(keyRaw, opts, deps = exports.defaultExperimentDeps) {
967
1428
  const key = validExperimentKey(keyRaw);
@@ -1269,6 +1730,8 @@ function registerExperimentCommand(program, deps = exports.defaultExperimentDeps
1269
1730
  writeLeaf(experiment, `${name} <key>`, description)
1270
1731
  .action(act((printer, key, opts) => runExperimentAction(name, key, opts, printer.requestId, deps)));
1271
1732
  }
1733
+ writeLeaf(experiment, 'delete <key>', 'Delete a draft that was never started (variants, overrides, metrics and history go with it; the key can be reused).')
1734
+ .action(act((printer, key, opts) => runExperimentDelete(key, opts, printer.requestId, deps)));
1272
1735
  writeLeaf(experiment, 'traffic <key> <percent>', 'Change the traffic percentage (0-100).')
1273
1736
  .action(act((printer, key, percent, opts) => runExperimentTraffic(key, percent, opts, printer.requestId, deps)));
1274
1737
  writeLeaf(experiment, 'extend <key>', 'Extend the validity of a running or paused experiment.')
@@ -1298,23 +1761,74 @@ function registerExperimentCommand(program, deps = exports.defaultExperimentDeps
1298
1761
  const metrics = experiment.command('metrics').description('Experiment metrics and guardrails.');
1299
1762
  envLeaf(metrics, 'list <key>', 'List metrics and guardrails.')
1300
1763
  .action(act((_p, key, opts) => runExperimentMetricsList(key, opts, deps)));
1301
- envLeaf(metrics, 'add <key>', 'Add one metric or guardrail (does not change the experiment version).')
1302
- .requiredOption('--kind <kind>', 'conversion | count | sum | avg | pct | retention')
1303
- .requiredOption('--event <name>', 'event name')
1304
- .option('--metric-key <key>', 'metric key (derived from kind + event when omitted)')
1764
+ envLeaf(metrics, 'add <key>', 'Add metrics or guardrails from the project metric library (does not change the experiment version).')
1765
+ .option('--metric <libraryKey>', 'library metric key (repeatable or comma-separated); see `experiment metric-defs list`', collect, [])
1305
1766
  .option('--role <role>', 'metric (default) | guardrail')
1306
1767
  .option('--core', 'mark as the core metric')
1307
- .option('--direction <dir>', 'up | down: which direction is better')
1768
+ .option('--direction <dir>', 'up | down (default: the library metric direction)')
1308
1769
  .option('--tolerance <percent>', 'guardrail tolerance in percent')
1309
1770
  .option('--window-days <n>', 'observation window after exposure, 1-60 (default 7)')
1310
- .option('--retention-day <n>', 'retention day N for --kind retention, 1-30')
1311
- .option('--property <name>', 'numeric property for sum / avg / pct')
1312
- .option('--property-type <type>', 'int | float (default float)')
1313
- .option('--percentile <n>', 'percentile for --kind pct, 1-99')
1314
- .option('--filters <json|@file>', 'JSON array of event filters {name, value_type, operator, values}')
1315
1771
  .action(act((printer, key, opts) => runExperimentMetricsAdd(key, opts, printer.requestId, deps)));
1772
+ envLeaf(metrics, 'update <key> <metricKey>', 'Change role / direction / window / tolerance (draft only) or the core flag (any time).')
1773
+ .option('--role <role>', 'metric | guardrail')
1774
+ .option('--core', 'mark as the core metric')
1775
+ .option('--no-core', 'clear the core mark')
1776
+ .option('--direction <dir>', 'up | down')
1777
+ .option('--tolerance <percent>', 'guardrail tolerance in percent')
1778
+ .option('--window-days <n>', 'observation window after exposure, 1-60')
1779
+ .action(act((printer, key, metricKey, opts) => runExperimentMetricsUpdate(key, metricKey, opts, printer.requestId, deps)));
1780
+ envLeaf(metrics, 'query <key> <metricKey>', 'Run the experiment\'s copy of a metric definition as an analysis query (or --print-spec).')
1781
+ .requiredOption('--from <date>', 'first day, YYYY-MM-DD (inclusive, in --time-zone)')
1782
+ .requiredOption('--to <date>', 'last day, YYYY-MM-DD (inclusive, in --time-zone)')
1783
+ .option('--time-zone <iana>', `IANA time zone (default ${exports.METRIC_QUERY_DEFAULT_TIME_ZONE})`)
1784
+ .option('--print-spec', 'only print the analytics request body (for `supercli analytics events-query|retention --file`)')
1785
+ .action(act((_p, key, metricKey, opts) => runExperimentMetricsQuery(key, metricKey, opts, deps)));
1316
1786
  envLeaf(metrics, 'remove <key> <metricKey>', 'Remove one metric or guardrail.')
1317
1787
  .action(act((printer, key, metricKey, opts) => runExperimentMetricsRemove(key, metricKey, opts, printer.requestId, deps)));
1788
+ const defs = experiment.command('metric-defs')
1789
+ .description('Project-level metric library (shared by every environment); experiments add metrics from it.');
1790
+ const projectLeaf = (spec, description) => defs.command(spec)
1791
+ .description(description)
1792
+ .option('--config <path>', 'explicit super.json path');
1793
+ const definitionFlags = (cmd) => cmd
1794
+ .option('--direction <dir>', 'up | down: which direction is better (default up)')
1795
+ .option('--property <name>', 'numeric property for sum / avg / pct')
1796
+ .option('--property-type <type>', 'int | float (default float)')
1797
+ .option('--property-column <kind>', 'dynamic (default) | fixed (preset column)')
1798
+ .option('--percentile <n>', 'percentile for --kind pct, 1-99')
1799
+ .option('--retention-day <n>', 'retention day N for --kind retention, 1-30')
1800
+ .option('--filters <json|@file>', 'JSON array of event filters {name, value_type, operator, values}');
1801
+ projectLeaf('list', 'List library metrics.')
1802
+ .option('--status <status>', 'active | deprecated')
1803
+ .action(act((_p, opts) => runMetricDefsList(opts, deps)));
1804
+ projectLeaf('get <metricKey>', 'Show one library metric and the experiments using it.')
1805
+ .action(act((_p, metricKey, opts) => runMetricDefsGet(metricKey, opts, deps)));
1806
+ definitionFlags(projectLeaf('create', 'Create a library metric (source: api).')
1807
+ .requiredOption('--kind <kind>', 'conversion | count | sum | avg | pct | retention')
1808
+ .requiredOption('--event <name>', 'event name')
1809
+ .option('--key <metricKey>', 'library key (derived from kind + event when omitted)')
1810
+ .option('--name <text>', 'display name (default: the key; at most 80 characters)')
1811
+ .option('--description <text>', 'description (at most 200 characters)'))
1812
+ .action(act((printer, opts) => runMetricDefsCreate(opts, printer.requestId, deps)));
1813
+ definitionFlags(projectLeaf('update <metricKey>', 'Edit a library metric. Definition and direction are frozen once any experiment uses it.')
1814
+ .option('--name <text>', 'display name (at most 80 characters)')
1815
+ .option('--description <text>', 'description (at most 200 characters; empty string clears it)')
1816
+ .option('--kind <kind>', 'conversion | count | sum | avg | pct | retention')
1817
+ .option('--event <name>', 'event name'))
1818
+ .action(act((printer, metricKey, opts) => runMetricDefsUpdate(metricKey, opts, printer.requestId, deps)));
1819
+ projectLeaf('query <metricKey>', 'Run a library metric definition as an analysis query (or --print-spec).')
1820
+ .option('--env <env>', 'project environment to query (server default: prod)')
1821
+ .requiredOption('--from <date>', 'first day, YYYY-MM-DD (inclusive, in --time-zone)')
1822
+ .requiredOption('--to <date>', 'last day, YYYY-MM-DD (inclusive, in --time-zone)')
1823
+ .option('--time-zone <iana>', `IANA time zone (default ${exports.METRIC_QUERY_DEFAULT_TIME_ZONE})`)
1824
+ .option('--print-spec', 'only print the analytics request body (for `supercli analytics events-query|retention --file`)')
1825
+ .action(act((_p, metricKey, opts) => runMetricDefsQuery(metricKey, opts, deps)));
1826
+ projectLeaf('deprecate <metricKey>', 'Deprecate a library metric: no new experiment can add it; existing ones keep it.')
1827
+ .action(act((printer, metricKey, opts) => runMetricDefsSetStatus('deprecated', metricKey, opts, printer.requestId, deps)));
1828
+ projectLeaf('activate <metricKey>', 'Re-activate a deprecated library metric.')
1829
+ .action(act((printer, metricKey, opts) => runMetricDefsSetStatus('active', metricKey, opts, printer.requestId, deps)));
1830
+ projectLeaf('delete <metricKey>', 'Delete a library metric no experiment uses.')
1831
+ .action(act((printer, metricKey, opts) => runMetricDefsDelete(metricKey, opts, printer.requestId, deps)));
1318
1832
  envLeaf(experiment, 'results <key>', 'Show experiment results (may recompute on the server; waits up to 150 s).')
1319
1833
  .option('--refresh', 'ask the server to recompute (throttled to once a minute)')
1320
1834
  .option('--time-zone <iana>', 'IANA time zone, only used the first time results are computed')