@supersdk/supercli 0.5.12 → 0.5.13-staging.126

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