zinkee 0.1.20 → 0.1.22

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zinkee",
-  "version": "0.1.20",
+  "version": "0.1.22",
   "description": "CLI for Zinkee API v2",
   "type": "module",
   "bin": {

package/src/commands/displays.ts

@@ -17,6 +17,9 @@ import type { RuntimeOverrides } from "../types.js";
 import { CliError } from "../utils/errors.js";
 import { buildJsonSuccess, printTable } from "../utils/output.js";
 
+const DATE_DYNAMIC_OPTIONS =
+  "today, thisWeek, thisMonth, thisQuarter, thisSemester, thisYear, next7Days, next30Days, next6Months, next12Months, last12Months";
+
 interface CommandIo {
   write(chunk: string): unknown;
 }
@@ -674,7 +677,7 @@ export function registerDisplaysCommands(
     .option("--type <type>").option("--name <name>").option("--allow-multiple").option("--static")
     .option("--default <value>").option("--default-value <value>", "repeatable default value", (v, p: string[] = []) => [...p, v], [])
     .option("--source-schema <id>").option("--source-field <id>").option("--filter <expr>", "repeatable filter", collectFilters, [])
-    .option("--date-mode <mode>").option("--date-dynamic-option <option>").option("--date-specific <iso>").option("--date-range-start <iso>").option("--date-range-end <iso>")
+    .option("--date-mode <mode>").option("--date-dynamic-option <option>", `dynamic date period (${DATE_DYNAMIC_OPTIONS})`).option("--date-specific <iso>").option("--date-range-start <iso>").option("--date-range-end <iso>")
     .option("--raw <json>").option("--raw-file <path>")
     .action(async function action(this: Command, display: NormalizedUuidOrSlug, commandOptions: VariableMutationOptions) {
       const { api, json, readOnly } = createDisplaysApi(this, filePath); ensureWritable("displays variables create", readOnly, "write");
@@ -686,7 +689,7 @@ export function registerDisplaysCommands(
     .option("--type <type>").option("--name <name>").option("--allow-multiple").option("--static")
     .option("--default <value>").option("--default-value <value>", "repeatable default value", (v, p: string[] = []) => [...p, v], [])
     .option("--source-schema <id>").option("--source-field <id>").option("--filter <expr>", "repeatable filter", collectFilters, [])
-    .option("--date-mode <mode>").option("--date-dynamic-option <option>").option("--date-specific <iso>").option("--date-range-start <iso>").option("--date-range-end <iso>")
+    .option("--date-mode <mode>").option("--date-dynamic-option <option>", `dynamic date period (${DATE_DYNAMIC_OPTIONS})`).option("--date-specific <iso>").option("--date-range-start <iso>").option("--date-range-end <iso>")
     .option("--raw <json>").option("--raw-file <path>")
     .action(async function action(this: Command, display: NormalizedUuidOrSlug, variableId: string, commandOptions: VariableMutationOptions) {
       const { api, json, readOnly } = createDisplaysApi(this, filePath); ensureWritable("displays variables update", readOnly, "write");
@@ -720,7 +723,7 @@ export function registerDisplaysCommands(
     .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("--calc <type>").option("--calc-field <uuid>").option("--kpi-config <json>")
-    .option("--chart-type <type>").option("--x-axis-field <uuid>").option("--x-axis-date-format <granularity>").option("--x-axis-time-series")
+    .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: string[] = []) => [...p, v], [])
     .option("--legend <json>").option("--raw <json>").option("--raw-file <path>")
     .action(async function action(this: Command, display: NormalizedUuidOrSlug, commandOptions: WidgetMutationOptions) {
@@ -738,7 +741,7 @@ export function registerDisplaysCommands(
     .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("--calc <type>").option("--calc-field <uuid>").option("--kpi-config <json>")
-    .option("--chart-type <type>").option("--x-axis-field <uuid>").option("--x-axis-date-format <granularity>").option("--x-axis-time-series")
+    .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: string[] = []) => [...p, v], [])
     .option("--legend <json>").option("--raw <json>").option("--raw-file <path>")
     .action(async function action(this: Command, display: NormalizedUuidOrSlug, widgetId: string, commandOptions: WidgetMutationOptions) {

package/src/utils/examples.ts

@@ -1298,13 +1298,13 @@ const specificExamples: Record<string, readonly CommandExample[]> = {
 }`,
     },
     {
-      description: "Change a DATE variable to use lastWeek.",
+      description: "Change a DATE variable to use last12Months.",
       command:
-        'zinkee --json displays variables update 0f6f062f-1478-4df2-96a1-c495d037d260 bbbbbbbb-2222-4222-a222-222222222222 --date-mode dynamic --date-dynamic-option lastWeek',
+        'zinkee --json displays variables update 0f6f062f-1478-4df2-96a1-c495d037d260 bbbbbbbb-2222-4222-a222-222222222222 --date-mode dynamic --date-dynamic-option last12Months',
       raw: `{
   "date": {
     "mode": "dynamic",
-    "dynamicOption": "lastWeek"
+    "dynamicOption": "last12Months"
   }
 }`,
     },
@@ -1385,9 +1385,40 @@ const specificExamples: Record<string, readonly CommandExample[]> = {
 }`,
     },
     {
-      description: "Create a bars CHART widget with a time-serie x-axis and two y-axis series.",
+      description: "Create a CHART widget with a daily time-serie x-axis.",
       command:
-        `zinkee --json displays widgets create 0f6f062f-1478-4df2-96a1-c495d037d260 --type CHART --name "Revenue by month" --origin-resource 2eb8bdcf-6d9c-4fbb-9018-7fa8180f4c5e --layout '{"x":0,"y":0,"w":8,"h":6}' --chart-type bars --x-axis-field due-date --x-axis-date-format MONTH --x-axis-time-series --y-axis-serie '{"typeCalc":"SUM","fieldCalc":"amount","color":"#4B9CD3","axisType":"PRIMARY"}' --y-axis-serie '{"typeCalc":"COUNT","fieldCalc":"id","color":"#E57373","axisType":"SECONDARY"}' --legend '{"position":"bottom"}'`,
+        `zinkee --json displays widgets create 0f6f062f-1478-4df2-96a1-c495d037d260 --type CHART --name "Revenue by day" --origin-resource 2eb8bdcf-6d9c-4fbb-9018-7fa8180f4c5e --layout '{"x":0,"y":0,"w":8,"h":6}' --chart-type lines --x-axis-field due-date --x-axis-date-format DATE --x-axis-time-series --y-axis-serie '{"typeCalc":"SUM","fieldCalc":"amount","color":"#4B9CD3","axisType":"PRIMARY"}' --legend '{"position":"bottom"}'`,
+      raw: `{
+  "type": "CHART",
+  "source": {
+    "originResourceId": "2eb8bdcf-6d9c-4fbb-9018-7fa8180f4c5e",
+    "isOriginSubSchema": false
+  },
+  "placement": {
+    "layout": { "x": 0, "y": 0, "w": 8, "h": 6 }
+  },
+  "presentation": { "name": "Revenue by day" },
+  "chart": {
+    "chartType": "lines",
+    "xAxisFieldId": "due-date",
+    "xAxisDateFormat": "DATE",
+    "xAxisAsTimeSerie": true,
+    "yAxisSeries": [
+      {
+        "typeCalc": "SUM",
+        "fieldCalc": "amount",
+        "color": "#4B9CD3",
+        "axisType": "PRIMARY"
+      }
+    ],
+    "legend": { "position": "bottom" }
+  }
+}`,
+    },
+    {
+      description: "Create a bars CHART widget with a monthly time-serie x-axis and two y-axis series.",
+      command:
+        `zinkee --json displays widgets create 0f6f062f-1478-4df2-96a1-c495d037d260 --type CHART --name "Revenue by month" --origin-resource 2eb8bdcf-6d9c-4fbb-9018-7fa8180f4c5e --layout '{"x":0,"y":0,"w":8,"h":6}' --chart-type bars --x-axis-field due-date --x-axis-date-format MONTH_YEAR --x-axis-time-series --y-axis-serie '{"typeCalc":"SUM","fieldCalc":"amount","color":"#4B9CD3","axisType":"PRIMARY"}' --y-axis-serie '{"typeCalc":"COUNT","fieldCalc":"id","color":"#E57373","axisType":"SECONDARY"}' --legend '{"position":"bottom"}'`,
       raw: `{
   "type": "CHART",
   "source": {
@@ -1401,7 +1432,7 @@ const specificExamples: Record<string, readonly CommandExample[]> = {
   "chart": {
     "chartType": "bars",
     "xAxisFieldId": "due-date",
-    "xAxisDateFormat": "MONTH",
+    "xAxisDateFormat": "MONTH_YEAR",
     "xAxisAsTimeSerie": true,
     "yAxisSeries": [
       {
@@ -1419,6 +1450,68 @@ const specificExamples: Record<string, readonly CommandExample[]> = {
     ],
     "legend": { "position": "bottom" }
   }
+}`,
+    },
+    {
+      description: "Create a bars CHART widget with a quarterly time-serie x-axis.",
+      command:
+        `zinkee --json displays widgets create 0f6f062f-1478-4df2-96a1-c495d037d260 --type CHART --name "Revenue by quarter" --origin-resource 2eb8bdcf-6d9c-4fbb-9018-7fa8180f4c5e --layout '{"x":0,"y":0,"w":8,"h":6}' --chart-type bars --x-axis-field due-date --x-axis-date-format QUARTER_YEAR --x-axis-time-series --y-axis-serie '{"typeCalc":"SUM","fieldCalc":"amount","color":"#4B9CD3","axisType":"PRIMARY"}' --legend '{"position":"bottom"}'`,
+      raw: `{
+  "type": "CHART",
+  "source": {
+    "originResourceId": "2eb8bdcf-6d9c-4fbb-9018-7fa8180f4c5e",
+    "isOriginSubSchema": false
+  },
+  "placement": {
+    "layout": { "x": 0, "y": 0, "w": 8, "h": 6 }
+  },
+  "presentation": { "name": "Revenue by quarter" },
+  "chart": {
+    "chartType": "bars",
+    "xAxisFieldId": "due-date",
+    "xAxisDateFormat": "QUARTER_YEAR",
+    "xAxisAsTimeSerie": true,
+    "yAxisSeries": [
+      {
+        "typeCalc": "SUM",
+        "fieldCalc": "amount",
+        "color": "#4B9CD3",
+        "axisType": "PRIMARY"
+      }
+    ],
+    "legend": { "position": "bottom" }
+  }
+}`,
+    },
+    {
+      description: "Create a CHART widget with a yearly time-serie x-axis.",
+      command:
+        `zinkee --json displays widgets create 0f6f062f-1478-4df2-96a1-c495d037d260 --type CHART --name "Revenue by year" --origin-resource 2eb8bdcf-6d9c-4fbb-9018-7fa8180f4c5e --layout '{"x":0,"y":0,"w":8,"h":6}' --chart-type lines --x-axis-field due-date --x-axis-date-format YEAR --x-axis-time-series --y-axis-serie '{"typeCalc":"SUM","fieldCalc":"amount","color":"#4B9CD3","axisType":"PRIMARY"}' --legend '{"position":"bottom"}'`,
+      raw: `{
+  "type": "CHART",
+  "source": {
+    "originResourceId": "2eb8bdcf-6d9c-4fbb-9018-7fa8180f4c5e",
+    "isOriginSubSchema": false
+  },
+  "placement": {
+    "layout": { "x": 0, "y": 0, "w": 8, "h": 6 }
+  },
+  "presentation": { "name": "Revenue by year" },
+  "chart": {
+    "chartType": "lines",
+    "xAxisFieldId": "due-date",
+    "xAxisDateFormat": "YEAR",
+    "xAxisAsTimeSerie": true,
+    "yAxisSeries": [
+      {
+        "typeCalc": "SUM",
+        "fieldCalc": "amount",
+        "color": "#4B9CD3",
+        "axisType": "PRIMARY"
+      }
+    ],
+    "legend": { "position": "bottom" }
+  }
 }`,
     },
     {
@@ -1580,14 +1673,14 @@ const specificExamples: Record<string, readonly CommandExample[]> = {
 }`,
     },
     {
-      description: "Replace the chart series with weekly lines.",
+      description: "Replace the chart series with quarterly lines.",
       command:
-        `zinkee --json displays widgets update 0f6f062f-1478-4df2-96a1-c495d037d260 22222222-2222-4222-a222-222222222222 --chart-type lines --x-axis-field due-date --x-axis-date-format WEEK --x-axis-time-series --y-axis-serie '{"typeCalc":"SUM","fieldCalc":"amount","color":"#2E7D32","axisType":"PRIMARY"}'`,
+        `zinkee --json displays widgets update 0f6f062f-1478-4df2-96a1-c495d037d260 22222222-2222-4222-a222-222222222222 --chart-type lines --x-axis-field due-date --x-axis-date-format QUARTER_YEAR --x-axis-time-series --y-axis-serie '{"typeCalc":"SUM","fieldCalc":"amount","color":"#2E7D32","axisType":"PRIMARY"}'`,
       raw: `{
   "chart": {
     "chartType": "lines",
     "xAxisFieldId": "due-date",
-    "xAxisDateFormat": "WEEK",
+    "xAxisDateFormat": "QUARTER_YEAR",
     "xAxisAsTimeSerie": true,
     "yAxisSeries": [
       {