@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.
- package/dist/api/experimentClient.js +31 -0
- package/dist/api/experimentClient.js.map +1 -1
- package/dist/commands/experiment.js +591 -77
- package/dist/commands/experiment.js.map +1 -1
- package/dist/template/android/supersdk-default.config.json +1 -1
- package/dist/template/web/scripts/web_package.py +3 -1
- package/dist/template/web/src/js/supersdk.js +1 -1
- package/dist/template/web/src/js/supersdk.provenance.json +3 -3
- package/package.json +1 -1
|
@@ -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.
|
|
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,
|
|
897
|
+
return ok(withScope(scope, metricsResult(key, outcome.data)), metricsSummary(outcome.data));
|
|
834
898
|
}
|
|
835
899
|
function metricsSummary(data) {
|
|
836
|
-
const
|
|
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
|
-
|
|
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
|
-
|
|
846
|
-
|
|
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
|
|
857
|
-
const
|
|
858
|
-
if (
|
|
859
|
-
return
|
|
860
|
-
|
|
861
|
-
|
|
862
|
-
|
|
863
|
-
|
|
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
|
|
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
|
-
|
|
880
|
-
if (opts.core === true)
|
|
881
|
-
metric.is_core = true;
|
|
941
|
+
settings.role = role;
|
|
882
942
|
if (direction)
|
|
883
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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') &&
|
|
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
|
-
|
|
1109
|
+
def.filters = filters.value;
|
|
927
1110
|
}
|
|
928
|
-
return
|
|
1111
|
+
return def;
|
|
929
1112
|
}
|
|
930
|
-
|
|
931
|
-
|
|
932
|
-
|
|
933
|
-
|
|
934
|
-
|
|
935
|
-
|
|
936
|
-
|
|
937
|
-
|
|
938
|
-
|
|
939
|
-
|
|
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.
|
|
1226
|
+
const outcome = await ctx.client.createMetricDef(ctx.token, project, body);
|
|
944
1227
|
if (outcome.kind !== 'success')
|
|
945
|
-
return handleFailure(outcome, ctx.auth, deps, '
|
|
946
|
-
return ok(withScope(
|
|
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
|
|
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
|
|
953
|
-
if (
|
|
954
|
-
return
|
|
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
|
|
1414
|
+
const ctx = begin(deps);
|
|
959
1415
|
if (isOutcome(ctx))
|
|
960
1416
|
return ctx;
|
|
961
|
-
const outcome = await ctx.client.
|
|
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
|
|
964
|
-
|
|
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
|
|
1302
|
-
.
|
|
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:
|
|
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')
|