zinkee 0.1.61 → 0.1.63
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/README.md +106 -5
- package/dist/{chunk-W3BI6KES.js → chunk-UAL4VMAW.js} +49 -9
- package/dist/chunk-UAL4VMAW.js.map +1 -0
- package/dist/{examples-VXDDPC3X.js → examples-MPBE5OXQ.js} +181 -12
- package/dist/examples-MPBE5OXQ.js.map +1 -0
- package/dist/index.js +223 -7
- package/dist/index.js.map +1 -1
- package/package.json +1 -1
- package/dist/chunk-W3BI6KES.js.map +0 -1
- package/dist/examples-VXDDPC3X.js.map +0 -1
package/dist/index.js
CHANGED
|
@@ -18,7 +18,7 @@ import {
|
|
|
18
18
|
normalizeSchemaFieldUpdatePayload,
|
|
19
19
|
printTable,
|
|
20
20
|
toCliError
|
|
21
|
-
} from "./chunk-
|
|
21
|
+
} from "./chunk-UAL4VMAW.js";
|
|
22
22
|
|
|
23
23
|
// src/cli-runner.ts
|
|
24
24
|
import { realpathSync } from "fs";
|
|
@@ -253,7 +253,7 @@ ${list}`
|
|
|
253
253
|
};
|
|
254
254
|
}
|
|
255
255
|
async function showExamples(commandName, json, stdout, filters = {}) {
|
|
256
|
-
const { getCommandExamples } = await import("./examples-
|
|
256
|
+
const { getCommandExamples } = await import("./examples-MPBE5OXQ.js");
|
|
257
257
|
const examples = getCommandExamples(commandName, filters);
|
|
258
258
|
if (examples.length === 0) {
|
|
259
259
|
throw new CliError("invalid_cli_usage", `No examples registered for "${commandName}".`);
|
|
@@ -822,6 +822,12 @@ function validateIdempotencyKey(key) {
|
|
|
822
822
|
}
|
|
823
823
|
return key;
|
|
824
824
|
}
|
|
825
|
+
function noteRateLimitRetry({ retryAfterSeconds, nextAttempt, maxAttempts }) {
|
|
826
|
+
process.stderr.write(
|
|
827
|
+
`Rate limit reached; retrying in ${retryAfterSeconds} s (attempt ${nextAttempt} of ${maxAttempts}).
|
|
828
|
+
`
|
|
829
|
+
);
|
|
830
|
+
}
|
|
825
831
|
function createCommandContext(command, filePath) {
|
|
826
832
|
try {
|
|
827
833
|
const overrides = command.optsWithGlobals();
|
|
@@ -836,7 +842,13 @@ function createCommandContext(command, filePath) {
|
|
|
836
842
|
}
|
|
837
843
|
const getToken = runtime.session && runtime.workspace ? createWorkspaceTokenProvider({ profile: runtime.profile, ...runtime.session }, runtime.workspace) : void 0;
|
|
838
844
|
return {
|
|
839
|
-
client: new ApiClient({
|
|
845
|
+
client: new ApiClient({
|
|
846
|
+
baseUrl: runtime.baseUrl,
|
|
847
|
+
apiKey: runtime.apiKey,
|
|
848
|
+
getToken,
|
|
849
|
+
idempotencyKey,
|
|
850
|
+
onRateLimitRetry: noteRateLimitRetry
|
|
851
|
+
}),
|
|
840
852
|
json: runtime.json,
|
|
841
853
|
profile: runtime.profile,
|
|
842
854
|
readOnly: runtime.readOnly
|
|
@@ -2902,8 +2914,20 @@ function parseLockMatchOption(input) {
|
|
|
2902
2914
|
function collectLockMatches(value, previous = []) {
|
|
2903
2915
|
return [...previous, parseLockMatchOption(value)];
|
|
2904
2916
|
}
|
|
2917
|
+
function parseLockOptionOption(input) {
|
|
2918
|
+
const separatorIndex = input.indexOf(":");
|
|
2919
|
+
const lockedField = separatorIndex > 0 ? input.slice(0, separatorIndex).trim() : "";
|
|
2920
|
+
const option = separatorIndex > 0 ? input.slice(separatorIndex + 1).trim() : "";
|
|
2921
|
+
if (!lockedField || !option) {
|
|
2922
|
+
throw new InvalidArgumentError2('Expected "<lockedField>:<option>", e.g. "status:Paid".');
|
|
2923
|
+
}
|
|
2924
|
+
return { lockedField, option };
|
|
2925
|
+
}
|
|
2926
|
+
function collectLockOptions(value, previous = []) {
|
|
2927
|
+
return [...previous, parseLockOptionOption(value)];
|
|
2928
|
+
}
|
|
2905
2929
|
function buildLockedFields(options) {
|
|
2906
|
-
const hasLockFlags = (options.lockField?.length ?? 0) > 0 || (options.lockCondition?.length ?? 0) > 0 || (options.lockMessageBefore?.length ?? 0) > 0 || (options.lockMessageAfter?.length ?? 0) > 0 || (options.lockMatch?.length ?? 0) > 0;
|
|
2930
|
+
const hasLockFlags = (options.lockField?.length ?? 0) > 0 || (options.lockCondition?.length ?? 0) > 0 || (options.lockMessageBefore?.length ?? 0) > 0 || (options.lockMessageAfter?.length ?? 0) > 0 || (options.lockMatch?.length ?? 0) > 0 || (options.lockOption?.length ?? 0) > 0;
|
|
2907
2931
|
if (options.clearLockedFields) {
|
|
2908
2932
|
if (hasLockFlags) {
|
|
2909
2933
|
throw new CliError(
|
|
@@ -2920,7 +2944,7 @@ function buildLockedFields(options) {
|
|
|
2920
2944
|
const ensureRule = (lockedField) => {
|
|
2921
2945
|
let rule = rules.get(lockedField);
|
|
2922
2946
|
if (!rule) {
|
|
2923
|
-
rule = { conditions: [] };
|
|
2947
|
+
rule = { lockedOptions: [], conditions: [] };
|
|
2924
2948
|
rules.set(lockedField, rule);
|
|
2925
2949
|
}
|
|
2926
2950
|
return rule;
|
|
@@ -2940,6 +2964,9 @@ function buildLockedFields(options) {
|
|
|
2940
2964
|
for (const { lockedField, conditionMatch } of options.lockMatch ?? []) {
|
|
2941
2965
|
ensureRule(lockedField).conditionMatch = conditionMatch;
|
|
2942
2966
|
}
|
|
2967
|
+
for (const { lockedField, option } of options.lockOption ?? []) {
|
|
2968
|
+
ensureRule(lockedField).lockedOptions.push(option);
|
|
2969
|
+
}
|
|
2943
2970
|
for (const [lockedField, rule] of rules) {
|
|
2944
2971
|
if (rule.conditionMatch !== void 0 && rule.conditions.length === 0) {
|
|
2945
2972
|
throw new CliError(
|
|
@@ -2950,6 +2977,7 @@ function buildLockedFields(options) {
|
|
|
2950
2977
|
}
|
|
2951
2978
|
return [...rules.entries()].map(([lockedField, rule]) => ({
|
|
2952
2979
|
field: { fieldId: lockedField },
|
|
2980
|
+
...rule.lockedOptions.length > 0 ? { lockedOptions: rule.lockedOptions } : {},
|
|
2953
2981
|
conditions: rule.conditions,
|
|
2954
2982
|
...rule.conditionMatch !== void 0 ? { conditionMatch: rule.conditionMatch } : {},
|
|
2955
2983
|
...rule.messageBeforeLock !== void 0 ? { messageBeforeLock: rule.messageBeforeLock } : {},
|
|
@@ -3658,7 +3686,7 @@ function registerDisplaysCommands(program, options = {}) {
|
|
|
3658
3686
|
}
|
|
3659
3687
|
printTable([data], void 0, stdout);
|
|
3660
3688
|
});
|
|
3661
|
-
widgets.command("create").description("Create widget").argument("<display>", "display uuid or slug", parseUuidOrSlugSelector).requiredOption("--type <type>", "widget type").option("--name <name>").option("--description <text>").option("--icon <icon>").option("--color <color>").option("--origin-resource <uuid>").option("--origin-subschema").option("--tab <tabId>").option("--slot <slotId>").option("--layout <json>").option("--layout-file <path>").option("--field <field>", "repeatable field", (v, p = []) => [...p, v], []).option("--sort <sort>", "repeatable sort", (v, p = []) => [...p, v], []).option("--filter <expr>", "repeatable filter", collectFilters, []).option("--widget-read-only").option("--hide-add-button").option("--hide-delete-button").option("--hide-sort-button").option("--hide-filter-button").option("--hide-see-button").option("--lock-field <field>", "lock a field permanently in this widget (repeatable; field UUID or slug)", (v, p = []) => [...p, v], []).option("--lock-condition <expr>", 'conditional lock "<lockedField>:<field>:<comparator>[:<value>]"; locks <lockedField> when all its conditions match, or any with --lock-match (repeatable)', collectLockConditions, []).option("--lock-match <field:all|any>", "how the conditions of a lock combine: all (default) or any (repeatable)", collectLockMatches, []).option("--lock-message-before <field:text>", "message shown while a conditional lock is not met yet (repeatable)", collectLockMessages, []).option("--lock-message-after <field:text>", "message shown once the field is locked (repeatable)", collectLockMessages, []).option("--clear-locked-fields", "clear the widget locked-fields configuration").option("--calc <type>").option("--calc-field <uuid>").option("--kpi-config <json>").option("--chart-type <type>", "chart type (lines, bars, stackedBars, combined)").option("--x-axis-field <uuid>").option("--x-axis-date-format <granularity>", "time granularity (DATE, MONTH_YEAR, QUARTER_YEAR, YEAR)").option("--x-axis-time-series").option("--y-axis-serie <json>", "repeatable y axis serie", (v, p = []) => [...p, v], []).option("--legend <json>").option("--column-field <uuid>", "KANBAN column field (UUID, not slug)").option("--swimlane-field <uuid>", "KANBAN swimlane field (UUID, not slug)").option("--start-date-field <uuid>", "TIMELINE start date field (UUID, not slug)").option("--end-date-field <uuid>", "TIMELINE end date field (UUID, not slug)").option("--label-field <uuid>", "TIMELINE label field (UUID, not slug)").option("--group-field <uuid>", "TIMELINE group field (UUID, not slug)").option("--subgroup-field <uuid>", "TIMELINE subgroup field (UUID, not slug)").option("--progress-field <uuid>", "TIMELINE progress field (UUID, not slug)").option("--card-title-field <uuid>", "KANBAN/TIMELINE card title field (UUID, not slug)").option("--card-category1-field <uuid>", "KANBAN/TIMELINE card category 1 field (UUID, not slug)").option("--card-category2-field <uuid>", "KANBAN/TIMELINE card category 2 field (UUID, not slug)").option("--card-category3-field <uuid>", "KANBAN card category 3 field (UUID, not slug)").option("--card-category4-field <uuid>", "TIMELINE card category 4 field (UUID, not slug)").option("--card-description-field <uuid>", "KANBAN/TIMELINE card description field (UUID, not slug)").option("--aggregation-method <method>", "KANBAN card aggregation method (e.g. sum)").option("--aggregation-field <uuid>", "KANBAN card aggregation field (UUID, not slug)").option("--view-state <json>", "KANBAN/TIMELINE viewState UI scalars (columnOrder, granularity, sidebarWidth, show* ...)").option("--view-state-file <path>", "read --view-state JSON from a file").option("--hierarchy-label <name>", "HIERARCHY label column name").option("--hierarchy-info <id:name>", "HIERARCHY info column; id is a unique opaque column id you choose (e.g. col_1779975207355_zfndknslw), not the name, and is reused as columnId in mappings (repeatable)", (v, p = []) => [...p, v], []).option("--hierarchy-number <id:name:aggregation>", "HIERARCHY number column; id is a unique opaque column id (e.g. col_1779975207355_zfndknslw), not the name; aggregation SUM|AVERAGE|MINIMUM|MAXIMUM|COUNT|COUNT_DISTINCT (repeatable)", (v, p = []) => [...p, v], []).option("--hierarchy-root-name <name>", "HIERARCHY root level name").option("--hierarchy-root-label-field <uuid>", "HIERARCHY root level label field (UUID, not slug)").option("--hierarchy-root-info <columnId:fieldId>", "HIERARCHY root info mapping; columnId must match a --hierarchy-info id (repeatable)", (v, p = []) => [...p, v], []).option("--hierarchy-root-number <columnId:fieldId>", "HIERARCHY root number mapping; columnId must match a --hierarchy-number id (repeatable)", (v, p = []) => [...p, v], []).option("--hierarchy-child <json>", "HIERARCHY child level JSON {name,schemaId,childFieldId,labelFieldId,infoMappings,numberMappings} (repeatable)", (v, p = []) => [...p, v], []).option("--hierarchy-config <json>", "HIERARCHY full hierarchyConfig JSON (escape hatch)").option("--hierarchy-config-file <path>", "read --hierarchy-config JSON from a file").option("--raw <json>").option("--raw-file <path>").action(async function action(display, commandOptions) {
|
|
3689
|
+
widgets.command("create").description("Create widget").argument("<display>", "display uuid or slug", parseUuidOrSlugSelector).requiredOption("--type <type>", "widget type").option("--name <name>").option("--description <text>").option("--icon <icon>").option("--color <color>").option("--origin-resource <uuid>").option("--origin-subschema").option("--tab <tabId>").option("--slot <slotId>").option("--layout <json>").option("--layout-file <path>").option("--field <field>", "repeatable field", (v, p = []) => [...p, v], []).option("--sort <sort>", "repeatable sort", (v, p = []) => [...p, v], []).option("--filter <expr>", "repeatable filter", collectFilters, []).option("--widget-read-only").option("--hide-add-button").option("--hide-delete-button").option("--hide-sort-button").option("--hide-filter-button").option("--hide-see-button").option("--lock-field <field>", "lock a field permanently in this widget (repeatable; field UUID or slug)", (v, p = []) => [...p, v], []).option("--lock-condition <expr>", 'conditional lock "<lockedField>:<field>:<comparator>[:<value>]"; locks <lockedField> when all its conditions match, or any with --lock-match (repeatable)', collectLockConditions, []).option("--lock-match <field:all|any>", "how the conditions of a lock combine: all (default) or any (repeatable)", collectLockMatches, []).option("--lock-option <field:option>", "lock only this option of an option field (repeatable; option name or id); its other options and leaving it empty stay allowed", collectLockOptions, []).option("--lock-message-before <field:text>", "message shown while a conditional lock is not met yet (repeatable)", collectLockMessages, []).option("--lock-message-after <field:text>", "message shown once the field is locked (repeatable)", collectLockMessages, []).option("--clear-locked-fields", "clear the widget locked-fields configuration").option("--calc <type>").option("--calc-field <uuid>").option("--kpi-config <json>").option("--chart-type <type>", "chart type (lines, bars, stackedBars, combined)").option("--x-axis-field <uuid>").option("--x-axis-date-format <granularity>", "time granularity (DATE, MONTH_YEAR, QUARTER_YEAR, YEAR)").option("--x-axis-time-series").option("--y-axis-serie <json>", "repeatable y axis serie", (v, p = []) => [...p, v], []).option("--legend <json>").option("--column-field <uuid>", "KANBAN column field (UUID, not slug)").option("--swimlane-field <uuid>", "KANBAN swimlane field (UUID, not slug)").option("--start-date-field <uuid>", "TIMELINE start date field (UUID, not slug)").option("--end-date-field <uuid>", "TIMELINE end date field (UUID, not slug)").option("--label-field <uuid>", "TIMELINE label field (UUID, not slug)").option("--group-field <uuid>", "TIMELINE group field (UUID, not slug)").option("--subgroup-field <uuid>", "TIMELINE subgroup field (UUID, not slug)").option("--progress-field <uuid>", "TIMELINE progress field (UUID, not slug)").option("--card-title-field <uuid>", "KANBAN/TIMELINE card title field (UUID, not slug)").option("--card-category1-field <uuid>", "KANBAN/TIMELINE card category 1 field (UUID, not slug)").option("--card-category2-field <uuid>", "KANBAN/TIMELINE card category 2 field (UUID, not slug)").option("--card-category3-field <uuid>", "KANBAN card category 3 field (UUID, not slug)").option("--card-category4-field <uuid>", "TIMELINE card category 4 field (UUID, not slug)").option("--card-description-field <uuid>", "KANBAN/TIMELINE card description field (UUID, not slug)").option("--aggregation-method <method>", "KANBAN card aggregation method (e.g. sum)").option("--aggregation-field <uuid>", "KANBAN card aggregation field (UUID, not slug)").option("--view-state <json>", "KANBAN/TIMELINE viewState UI scalars (columnOrder, granularity, sidebarWidth, show* ...)").option("--view-state-file <path>", "read --view-state JSON from a file").option("--hierarchy-label <name>", "HIERARCHY label column name").option("--hierarchy-info <id:name>", "HIERARCHY info column; id is a unique opaque column id you choose (e.g. col_1779975207355_zfndknslw), not the name, and is reused as columnId in mappings (repeatable)", (v, p = []) => [...p, v], []).option("--hierarchy-number <id:name:aggregation>", "HIERARCHY number column; id is a unique opaque column id (e.g. col_1779975207355_zfndknslw), not the name; aggregation SUM|AVERAGE|MINIMUM|MAXIMUM|COUNT|COUNT_DISTINCT (repeatable)", (v, p = []) => [...p, v], []).option("--hierarchy-root-name <name>", "HIERARCHY root level name").option("--hierarchy-root-label-field <uuid>", "HIERARCHY root level label field (UUID, not slug)").option("--hierarchy-root-info <columnId:fieldId>", "HIERARCHY root info mapping; columnId must match a --hierarchy-info id (repeatable)", (v, p = []) => [...p, v], []).option("--hierarchy-root-number <columnId:fieldId>", "HIERARCHY root number mapping; columnId must match a --hierarchy-number id (repeatable)", (v, p = []) => [...p, v], []).option("--hierarchy-child <json>", "HIERARCHY child level JSON {name,schemaId,childFieldId,labelFieldId,infoMappings,numberMappings} (repeatable)", (v, p = []) => [...p, v], []).option("--hierarchy-config <json>", "HIERARCHY full hierarchyConfig JSON (escape hatch)").option("--hierarchy-config-file <path>", "read --hierarchy-config JSON from a file").option("--raw <json>").option("--raw-file <path>").action(async function action(display, commandOptions) {
|
|
3662
3690
|
const { api, json, readOnly } = createDisplaysApi(this, filePath);
|
|
3663
3691
|
ensureWritable("displays widgets create", readOnly, "write");
|
|
3664
3692
|
const data = await api.createWidget(display, buildWidgetBody(commandOptions));
|
|
@@ -3668,7 +3696,7 @@ function registerDisplaysCommands(program, options = {}) {
|
|
|
3668
3696
|
}
|
|
3669
3697
|
writeLine(stdout, `Created widget on display "${display.value}".`);
|
|
3670
3698
|
});
|
|
3671
|
-
widgets.command("update").description("Update widget").argument("<display>", "display uuid or slug", parseUuidOrSlugSelector).argument("<widget>", "widget id").option("--type <type>").option("--name <name>").option("--description <text>").option("--icon <icon>").option("--color <color>").option("--origin-resource <uuid>").option("--origin-subschema").option("--tab <tabId>").option("--slot <slotId>").option("--layout <json>").option("--layout-file <path>").option("--field <field>", "visible field (repeatable); merged into the saved view: visible columns keep position/width, hidden or new ones go to the end, omitted ones are hidden", (v, p = []) => [...p, v], []).option("--sort <sort>", "repeatable sort", (v, p = []) => [...p, v], []).option("--filter <expr>", "repeatable filter", collectFilters, []).option("--widget-read-only").option("--hide-add-button").option("--hide-delete-button").option("--hide-sort-button").option("--hide-filter-button").option("--hide-see-button").option("--lock-field <field>", "lock a field permanently in this widget (repeatable; field UUID or slug)", (v, p = []) => [...p, v], []).option("--lock-condition <expr>", 'conditional lock "<lockedField>:<field>:<comparator>[:<value>]"; locks <lockedField> when all its conditions match, or any with --lock-match (repeatable)', collectLockConditions, []).option("--lock-match <field:all|any>", "how the conditions of a lock combine: all (default) or any (repeatable)", collectLockMatches, []).option("--lock-message-before <field:text>", "message shown while a conditional lock is not met yet (repeatable)", collectLockMessages, []).option("--lock-message-after <field:text>", "message shown once the field is locked (repeatable)", collectLockMessages, []).option("--clear-locked-fields", "clear the widget locked-fields configuration").option("--calc <type>").option("--calc-field <uuid>").option("--kpi-config <json>").option("--chart-type <type>", "chart type (lines, bars, stackedBars, combined)").option("--x-axis-field <uuid>").option("--x-axis-date-format <granularity>", "time granularity (DATE, MONTH_YEAR, QUARTER_YEAR, YEAR)").option("--x-axis-time-series").option("--y-axis-serie <json>", "repeatable y axis serie", (v, p = []) => [...p, v], []).option("--legend <json>").option("--column-field <uuid>", "KANBAN column field (UUID, not slug)").option("--swimlane-field <uuid>", "KANBAN swimlane field (UUID, not slug)").option("--start-date-field <uuid>", "TIMELINE start date field (UUID, not slug)").option("--end-date-field <uuid>", "TIMELINE end date field (UUID, not slug)").option("--label-field <uuid>", "TIMELINE label field (UUID, not slug)").option("--group-field <uuid>", "TIMELINE group field (UUID, not slug)").option("--subgroup-field <uuid>", "TIMELINE subgroup field (UUID, not slug)").option("--progress-field <uuid>", "TIMELINE progress field (UUID, not slug)").option("--card-title-field <uuid>", "KANBAN/TIMELINE card title field (UUID, not slug)").option("--card-category1-field <uuid>", "KANBAN/TIMELINE card category 1 field (UUID, not slug)").option("--card-category2-field <uuid>", "KANBAN/TIMELINE card category 2 field (UUID, not slug)").option("--card-category3-field <uuid>", "KANBAN card category 3 field (UUID, not slug)").option("--card-category4-field <uuid>", "TIMELINE card category 4 field (UUID, not slug)").option("--card-description-field <uuid>", "KANBAN/TIMELINE card description field (UUID, not slug)").option("--aggregation-method <method>", "KANBAN card aggregation method (e.g. sum)").option("--aggregation-field <uuid>", "KANBAN card aggregation field (UUID, not slug)").option("--view-state <json>", "KANBAN/TIMELINE viewState UI scalars (columnOrder, granularity, sidebarWidth, show* ...); merged key by key into the saved viewState").option("--view-state-file <path>", "read --view-state JSON from a file").option("--hierarchy-label <name>", "HIERARCHY label column name").option("--hierarchy-info <id:name>", "HIERARCHY info column; id is a unique opaque column id you choose (e.g. col_1779975207355_zfndknslw), not the name, and is reused as columnId in mappings (repeatable)", (v, p = []) => [...p, v], []).option("--hierarchy-number <id:name:aggregation>", "HIERARCHY number column; id is a unique opaque column id (e.g. col_1779975207355_zfndknslw), not the name; aggregation SUM|AVERAGE|MINIMUM|MAXIMUM|COUNT|COUNT_DISTINCT (repeatable)", (v, p = []) => [...p, v], []).option("--hierarchy-root-name <name>", "HIERARCHY root level name").option("--hierarchy-root-label-field <uuid>", "HIERARCHY root level label field (UUID, not slug)").option("--hierarchy-root-info <columnId:fieldId>", "HIERARCHY root info mapping; columnId must match a --hierarchy-info id (repeatable)", (v, p = []) => [...p, v], []).option("--hierarchy-root-number <columnId:fieldId>", "HIERARCHY root number mapping; columnId must match a --hierarchy-number id (repeatable)", (v, p = []) => [...p, v], []).option("--hierarchy-child <json>", "HIERARCHY child level JSON {name,schemaId,childFieldId,labelFieldId,infoMappings,numberMappings} (repeatable)", (v, p = []) => [...p, v], []).option("--hierarchy-config <json>", "HIERARCHY full hierarchyConfig JSON (escape hatch)").option("--hierarchy-config-file <path>", "read --hierarchy-config JSON from a file").option("--raw <json>").option("--raw-file <path>").action(async function action(display, widgetId, commandOptions) {
|
|
3699
|
+
widgets.command("update").description("Update widget").argument("<display>", "display uuid or slug", parseUuidOrSlugSelector).argument("<widget>", "widget id").option("--type <type>").option("--name <name>").option("--description <text>").option("--icon <icon>").option("--color <color>").option("--origin-resource <uuid>").option("--origin-subschema").option("--tab <tabId>").option("--slot <slotId>").option("--layout <json>").option("--layout-file <path>").option("--field <field>", "visible field (repeatable); merged into the saved view: visible columns keep position/width, hidden or new ones go to the end, omitted ones are hidden", (v, p = []) => [...p, v], []).option("--sort <sort>", "repeatable sort", (v, p = []) => [...p, v], []).option("--filter <expr>", "repeatable filter", collectFilters, []).option("--widget-read-only").option("--hide-add-button").option("--hide-delete-button").option("--hide-sort-button").option("--hide-filter-button").option("--hide-see-button").option("--lock-field <field>", "lock a field permanently in this widget (repeatable; field UUID or slug)", (v, p = []) => [...p, v], []).option("--lock-condition <expr>", 'conditional lock "<lockedField>:<field>:<comparator>[:<value>]"; locks <lockedField> when all its conditions match, or any with --lock-match (repeatable)', collectLockConditions, []).option("--lock-match <field:all|any>", "how the conditions of a lock combine: all (default) or any (repeatable)", collectLockMatches, []).option("--lock-option <field:option>", "lock only this option of an option field (repeatable; option name or id); its other options and leaving it empty stay allowed", collectLockOptions, []).option("--lock-message-before <field:text>", "message shown while a conditional lock is not met yet (repeatable)", collectLockMessages, []).option("--lock-message-after <field:text>", "message shown once the field is locked (repeatable)", collectLockMessages, []).option("--clear-locked-fields", "clear the widget locked-fields configuration").option("--calc <type>").option("--calc-field <uuid>").option("--kpi-config <json>").option("--chart-type <type>", "chart type (lines, bars, stackedBars, combined)").option("--x-axis-field <uuid>").option("--x-axis-date-format <granularity>", "time granularity (DATE, MONTH_YEAR, QUARTER_YEAR, YEAR)").option("--x-axis-time-series").option("--y-axis-serie <json>", "repeatable y axis serie", (v, p = []) => [...p, v], []).option("--legend <json>").option("--column-field <uuid>", "KANBAN column field (UUID, not slug)").option("--swimlane-field <uuid>", "KANBAN swimlane field (UUID, not slug)").option("--start-date-field <uuid>", "TIMELINE start date field (UUID, not slug)").option("--end-date-field <uuid>", "TIMELINE end date field (UUID, not slug)").option("--label-field <uuid>", "TIMELINE label field (UUID, not slug)").option("--group-field <uuid>", "TIMELINE group field (UUID, not slug)").option("--subgroup-field <uuid>", "TIMELINE subgroup field (UUID, not slug)").option("--progress-field <uuid>", "TIMELINE progress field (UUID, not slug)").option("--card-title-field <uuid>", "KANBAN/TIMELINE card title field (UUID, not slug)").option("--card-category1-field <uuid>", "KANBAN/TIMELINE card category 1 field (UUID, not slug)").option("--card-category2-field <uuid>", "KANBAN/TIMELINE card category 2 field (UUID, not slug)").option("--card-category3-field <uuid>", "KANBAN card category 3 field (UUID, not slug)").option("--card-category4-field <uuid>", "TIMELINE card category 4 field (UUID, not slug)").option("--card-description-field <uuid>", "KANBAN/TIMELINE card description field (UUID, not slug)").option("--aggregation-method <method>", "KANBAN card aggregation method (e.g. sum)").option("--aggregation-field <uuid>", "KANBAN card aggregation field (UUID, not slug)").option("--view-state <json>", "KANBAN/TIMELINE viewState UI scalars (columnOrder, granularity, sidebarWidth, show* ...); merged key by key into the saved viewState").option("--view-state-file <path>", "read --view-state JSON from a file").option("--hierarchy-label <name>", "HIERARCHY label column name").option("--hierarchy-info <id:name>", "HIERARCHY info column; id is a unique opaque column id you choose (e.g. col_1779975207355_zfndknslw), not the name, and is reused as columnId in mappings (repeatable)", (v, p = []) => [...p, v], []).option("--hierarchy-number <id:name:aggregation>", "HIERARCHY number column; id is a unique opaque column id (e.g. col_1779975207355_zfndknslw), not the name; aggregation SUM|AVERAGE|MINIMUM|MAXIMUM|COUNT|COUNT_DISTINCT (repeatable)", (v, p = []) => [...p, v], []).option("--hierarchy-root-name <name>", "HIERARCHY root level name").option("--hierarchy-root-label-field <uuid>", "HIERARCHY root level label field (UUID, not slug)").option("--hierarchy-root-info <columnId:fieldId>", "HIERARCHY root info mapping; columnId must match a --hierarchy-info id (repeatable)", (v, p = []) => [...p, v], []).option("--hierarchy-root-number <columnId:fieldId>", "HIERARCHY root number mapping; columnId must match a --hierarchy-number id (repeatable)", (v, p = []) => [...p, v], []).option("--hierarchy-child <json>", "HIERARCHY child level JSON {name,schemaId,childFieldId,labelFieldId,infoMappings,numberMappings} (repeatable)", (v, p = []) => [...p, v], []).option("--hierarchy-config <json>", "HIERARCHY full hierarchyConfig JSON (escape hatch)").option("--hierarchy-config-file <path>", "read --hierarchy-config JSON from a file").option("--raw <json>").option("--raw-file <path>").action(async function action(display, widgetId, commandOptions) {
|
|
3672
3700
|
const { api, json, readOnly } = createDisplaysApi(this, filePath);
|
|
3673
3701
|
ensureWritable("displays widgets update", readOnly, "write");
|
|
3674
3702
|
const data = await api.updateWidget(display, widgetId, buildWidgetBody(commandOptions));
|
|
@@ -4824,6 +4852,13 @@ var RecordsApi = class {
|
|
|
4824
4852
|
jsonOptions6(body, "POST")
|
|
4825
4853
|
);
|
|
4826
4854
|
}
|
|
4855
|
+
aggregateRecords(schema, input) {
|
|
4856
|
+
const body = Array.isArray(input.where) ? { ...input, where: input.where.map(toWhereNode) } : input;
|
|
4857
|
+
return this.client.requestJson(
|
|
4858
|
+
`/api/v2/schemas/${schema.value}/records:aggregate`,
|
|
4859
|
+
jsonOptions6(body, "POST")
|
|
4860
|
+
);
|
|
4861
|
+
}
|
|
4827
4862
|
getRecord(schema, record) {
|
|
4828
4863
|
return this.client.getJson(
|
|
4829
4864
|
`/api/v2/schemas/${schema.value}/records/${record.value}`
|
|
@@ -4944,6 +4979,31 @@ var SchemasApi = class {
|
|
|
4944
4979
|
};
|
|
4945
4980
|
|
|
4946
4981
|
// src/commands/records.ts
|
|
4982
|
+
var AGGREGATE_BUCKETS = ["day", "week", "month", "quarter", "year"];
|
|
4983
|
+
var AGGREGATE_HELP = `
|
|
4984
|
+
Group by (--group-by <field>[:<bucket>], up to 3):
|
|
4985
|
+
A field slug; date fields take a bucket: day, week, month, quarter or year
|
|
4986
|
+
(a date field without bucket groups by day). Each group key comes back as
|
|
4987
|
+
{value, label}; records with an empty value fall into one group with
|
|
4988
|
+
value/label null.
|
|
4989
|
+
|
|
4990
|
+
Metrics (--metric [<alias>=]<op>[:<field>], up to 10, default "count"):
|
|
4991
|
+
count number of records
|
|
4992
|
+
count:<field> records where <field> is not null (same rule as a
|
|
4993
|
+
panel COUNT; options skip -1)
|
|
4994
|
+
count_distinct:<field>, sum:<field>, avg:<field>, min:<field>, max:<field>
|
|
4995
|
+
The alias defaults to "count" for a bare count and to <op>_<field>
|
|
4996
|
+
otherwise (e.g. sum_amount). avg/min/max are null when no record has a
|
|
4997
|
+
value; min/max on dates return an ISO-8601 UTC instant.
|
|
4998
|
+
|
|
4999
|
+
Sort (--sort <alias|field>[:asc|desc], up to 4):
|
|
5000
|
+
By a metric alias or a group-by field. Default: group keys ascending.
|
|
5001
|
+
|
|
5002
|
+
--limit caps the groups returned (default 100, max 1000); meta.aggregate
|
|
5003
|
+
reports count, total and truncated. Date buckets use --timezone, or the
|
|
5004
|
+
workspace timezone when omitted. --where/--where-json/--search filter the
|
|
5005
|
+
records first, exactly as in "records query".
|
|
5006
|
+
`;
|
|
4947
5007
|
function createRecordsApi(command, filePath) {
|
|
4948
5008
|
const { client, ...runtime } = createCommandContext(command, filePath);
|
|
4949
5009
|
return {
|
|
@@ -5053,6 +5113,72 @@ function collectSortValues(value, previous = []) {
|
|
|
5053
5113
|
function collectWhereExpressions(value, previous = []) {
|
|
5054
5114
|
return [...previous, parseExpressionValue(value)];
|
|
5055
5115
|
}
|
|
5116
|
+
function splitKnownSuffix(input, suffixes) {
|
|
5117
|
+
const index = input.lastIndexOf(":");
|
|
5118
|
+
if (index !== -1) {
|
|
5119
|
+
const suffix = input.slice(index + 1).trim().toLowerCase();
|
|
5120
|
+
if (suffixes.includes(suffix)) {
|
|
5121
|
+
return { head: input.slice(0, index).trim(), suffix };
|
|
5122
|
+
}
|
|
5123
|
+
}
|
|
5124
|
+
return { head: input.trim() };
|
|
5125
|
+
}
|
|
5126
|
+
function parseGroupBy(input) {
|
|
5127
|
+
const { head, suffix } = splitKnownSuffix(input, AGGREGATE_BUCKETS);
|
|
5128
|
+
if (!head) {
|
|
5129
|
+
throw new CliError(
|
|
5130
|
+
"invalid_cli_usage",
|
|
5131
|
+
`Invalid --group-by "${input}": expected <field>[:<bucket>] with bucket one of ${AGGREGATE_BUCKETS.join(", ")}.`
|
|
5132
|
+
);
|
|
5133
|
+
}
|
|
5134
|
+
return suffix ? { field: head, bucket: suffix } : { field: head };
|
|
5135
|
+
}
|
|
5136
|
+
function parseMetric(input) {
|
|
5137
|
+
const usage = `Invalid --metric "${input}": expected [<alias>=]<op>[:<field>], e.g. "count", "total=sum:amount" or "count_distinct:customer".`;
|
|
5138
|
+
const aliasIndex = input.lastIndexOf("=");
|
|
5139
|
+
const alias = aliasIndex === -1 ? void 0 : input.slice(0, aliasIndex).trim();
|
|
5140
|
+
const expression = input.slice(aliasIndex + 1);
|
|
5141
|
+
const fieldIndex = expression.indexOf(":");
|
|
5142
|
+
const op = (fieldIndex === -1 ? expression : expression.slice(0, fieldIndex)).trim();
|
|
5143
|
+
const field = fieldIndex === -1 ? void 0 : expression.slice(fieldIndex + 1).trim();
|
|
5144
|
+
if (alias === "" || !/^[A-Za-z_]+$/.test(op) || field === "") {
|
|
5145
|
+
throw new CliError("invalid_cli_usage", usage);
|
|
5146
|
+
}
|
|
5147
|
+
return {
|
|
5148
|
+
op,
|
|
5149
|
+
...field !== void 0 ? { field } : {},
|
|
5150
|
+
...alias !== void 0 ? { as: alias } : {}
|
|
5151
|
+
};
|
|
5152
|
+
}
|
|
5153
|
+
function parseAggregateSort(input) {
|
|
5154
|
+
const { head, suffix } = splitKnownSuffix(input, ["asc", "desc"]);
|
|
5155
|
+
if (!head) {
|
|
5156
|
+
throw new CliError(
|
|
5157
|
+
"invalid_cli_usage",
|
|
5158
|
+
`Invalid --sort "${input}": expected <alias|field>[:asc|desc].`
|
|
5159
|
+
);
|
|
5160
|
+
}
|
|
5161
|
+
return { by: head, direction: (suffix ?? "asc").toUpperCase() };
|
|
5162
|
+
}
|
|
5163
|
+
function parseGroupLimit(input) {
|
|
5164
|
+
const limit = /^\d+$/.test(input.trim()) ? Number(input) : Number.NaN;
|
|
5165
|
+
if (!(limit >= 1 && limit <= 1e3)) {
|
|
5166
|
+
throw new CliError(
|
|
5167
|
+
"invalid_cli_usage",
|
|
5168
|
+
`Invalid --limit "${input}": expected a number of groups from 1 to 1000.`
|
|
5169
|
+
);
|
|
5170
|
+
}
|
|
5171
|
+
return limit;
|
|
5172
|
+
}
|
|
5173
|
+
function collectGroupBy(value, previous = []) {
|
|
5174
|
+
return [...previous, parseGroupBy(value)];
|
|
5175
|
+
}
|
|
5176
|
+
function collectMetrics(value, previous = []) {
|
|
5177
|
+
return [...previous, parseMetric(value)];
|
|
5178
|
+
}
|
|
5179
|
+
function collectAggregateSort(value, previous = []) {
|
|
5180
|
+
return [...previous, parseAggregateSort(value)];
|
|
5181
|
+
}
|
|
5056
5182
|
function collectKeyValueAssignments(value, previous = []) {
|
|
5057
5183
|
return [...previous, parseKeyValueAssignment(value)];
|
|
5058
5184
|
}
|
|
@@ -5134,6 +5260,44 @@ function buildRecordQueryInput(options, allowRaw) {
|
|
|
5134
5260
|
}
|
|
5135
5261
|
return input;
|
|
5136
5262
|
}
|
|
5263
|
+
function buildRecordAggregateInput(options) {
|
|
5264
|
+
const input = readRawObject(options.raw, options.rawFile);
|
|
5265
|
+
const where = resolveWhere(options);
|
|
5266
|
+
if (where !== void 0) {
|
|
5267
|
+
input.where = where;
|
|
5268
|
+
}
|
|
5269
|
+
if (options.search !== void 0) {
|
|
5270
|
+
input.search = { term: options.search };
|
|
5271
|
+
}
|
|
5272
|
+
if (options.groupBy && options.groupBy.length > 0) {
|
|
5273
|
+
input.groupBy = [...options.groupBy];
|
|
5274
|
+
}
|
|
5275
|
+
if (options.metric && options.metric.length > 0) {
|
|
5276
|
+
input.metrics = [...options.metric];
|
|
5277
|
+
}
|
|
5278
|
+
if (options.sort && options.sort.length > 0) {
|
|
5279
|
+
input.sort = [...options.sort];
|
|
5280
|
+
}
|
|
5281
|
+
if (options.limit !== void 0) {
|
|
5282
|
+
input.limit = options.limit;
|
|
5283
|
+
}
|
|
5284
|
+
if (options.timezone !== void 0) {
|
|
5285
|
+
input.timezone = options.timezone;
|
|
5286
|
+
}
|
|
5287
|
+
return input;
|
|
5288
|
+
}
|
|
5289
|
+
function toAggregateTableRows(groups) {
|
|
5290
|
+
return groups.map((group) => {
|
|
5291
|
+
const row = {};
|
|
5292
|
+
for (const [slug, key] of Object.entries(group.key ?? {})) {
|
|
5293
|
+
row[slug] = key?.label ? key.label : key?.value ?? "(empty)";
|
|
5294
|
+
}
|
|
5295
|
+
for (const [alias, value] of Object.entries(group.metrics ?? {})) {
|
|
5296
|
+
row[alias in row ? `${alias} (metric)` : alias] = value;
|
|
5297
|
+
}
|
|
5298
|
+
return row;
|
|
5299
|
+
});
|
|
5300
|
+
}
|
|
5137
5301
|
function readRecordsFromFile(path) {
|
|
5138
5302
|
let contents;
|
|
5139
5303
|
try {
|
|
@@ -5305,6 +5469,58 @@ function registerRecordsCommands(program, options = {}) {
|
|
|
5305
5469
|
}
|
|
5306
5470
|
emitTable(stdout, recordsData);
|
|
5307
5471
|
});
|
|
5472
|
+
records.command("aggregate").description(
|
|
5473
|
+
"Compute counts, sums, averages and min/max over a schema's records, optionally grouped by up to 3 fields (dates by day/week/month/quarter/year). Use it for totals and breakdowns instead of paginating records query and summing"
|
|
5474
|
+
).argument("<schema>", "schema uuid or slug", parseUuidOrSlugSelector).option(
|
|
5475
|
+
"--group-by <field[:bucket]>",
|
|
5476
|
+
"group by a field slug; date fields take a bucket day|week|month|quarter|year (repeatable, up to 3)",
|
|
5477
|
+
collectGroupBy,
|
|
5478
|
+
[]
|
|
5479
|
+
).option(
|
|
5480
|
+
"--metric <[alias=]op[:field]>",
|
|
5481
|
+
"metric count|count_distinct|sum|avg|min|max, e.g. count, total=sum:amount (repeatable, up to 10; default count)",
|
|
5482
|
+
collectMetrics,
|
|
5483
|
+
[]
|
|
5484
|
+
).option(
|
|
5485
|
+
"--where <expression>",
|
|
5486
|
+
'condition "<field> <op> [value]" (repeatable, combined with AND)',
|
|
5487
|
+
collectWhereExpressions,
|
|
5488
|
+
[]
|
|
5489
|
+
).option(
|
|
5490
|
+
"--where-json <json>",
|
|
5491
|
+
'native where as JSON: an array of conditions (AND) or one condition/{"and"|"or": [...]} group (not combinable with --where)'
|
|
5492
|
+
).option(
|
|
5493
|
+
"--search <term>",
|
|
5494
|
+
"free-text search term (matched across the schema's searchable fields)"
|
|
5495
|
+
).option(
|
|
5496
|
+
"--sort <alias|field[:direction]>",
|
|
5497
|
+
"sort groups by a metric alias or group-by field, asc|desc (repeatable, up to 4)",
|
|
5498
|
+
collectAggregateSort,
|
|
5499
|
+
[]
|
|
5500
|
+
).option("--limit <number>", "maximum groups returned (default 100, max 1000)", parseGroupLimit).option("--timezone <iana>", "timezone for date buckets, e.g. Europe/Madrid (default: workspace timezone)").option("--raw <json>", "raw JSON object payload").option("--raw-file <path>", "path to a raw JSON object payload").addHelpText("after", AGGREGATE_HELP).action(async function action(schema, commandOptions) {
|
|
5501
|
+
const { api, schemasApi, json } = createRecordsApi(this, filePath);
|
|
5502
|
+
const input = buildRecordAggregateInput(commandOptions);
|
|
5503
|
+
const resolvedSchema = await resolveSchemaSelector(schemasApi, schema);
|
|
5504
|
+
const data = await api.aggregateRecords(resolvedSchema, input);
|
|
5505
|
+
const groups = Array.isArray(data.groups) ? data.groups : [];
|
|
5506
|
+
if (json) {
|
|
5507
|
+
emitJson(
|
|
5508
|
+
stdout,
|
|
5509
|
+
"records aggregate",
|
|
5510
|
+
groups,
|
|
5511
|
+
filePath,
|
|
5512
|
+
data.meta ? { aggregate: data.meta } : {}
|
|
5513
|
+
);
|
|
5514
|
+
return;
|
|
5515
|
+
}
|
|
5516
|
+
emitTable(stdout, toAggregateTableRows(groups));
|
|
5517
|
+
if (data.meta?.truncated) {
|
|
5518
|
+
writeLine(
|
|
5519
|
+
stdout,
|
|
5520
|
+
`Showing ${data.meta.count} of ${data.meta.total} groups; raise --limit (max 1000) or narrow the filters to see the rest.`
|
|
5521
|
+
);
|
|
5522
|
+
}
|
|
5523
|
+
});
|
|
5308
5524
|
records.command("get").description("Get a record by UUID or slug").argument("<schema>", "schema uuid or slug", parseUuidOrSlugSelector).argument("<record>", "record uuid or slug", parseUuidOrSlugSelector).action(async function action(schema, record) {
|
|
5309
5525
|
const { api, schemasApi, json } = createRecordsApi(this, filePath);
|
|
5310
5526
|
const resolvedSchema = await resolveSchemaSelector(schemasApi, schema);
|