zinkee 0.1.19 → 0.1.20

package/package.json

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

package/src/commands/displays.test.ts

@@ -252,6 +252,229 @@ describe("displays commands", () => {
     });
   });
 
+  it("translates --filter into the structured display filter contract", async () => {
+    const configPath = createApiConfig();
+    const output = createStdoutBuffer();
+    const fetchMock = createFetchMock();
+    fetchMock.mockResolvedValueOnce(jsonResponse({ displayId: "display-1", widgetId: "widget-f1" }));
+    const program = buildProgram({ configPath, stdout: output.stdout });
+
+    await program.parseAsync([
+      "node",
+      "zinkee",
+      "--json",
+      "displays",
+      "widgets",
+      "create",
+      "display-1",
+      "--type",
+      "table",
+      "--origin-resource",
+      "schema-1",
+      "--filter",
+      "edad:gt:30",
+    ]);
+
+    const init = fetchMock.mock.calls[0]?.[1];
+    expect(JSON.parse(String(init?.body))).toMatchObject({
+      type: "TABLE_OR_SUBTABLE",
+      query: {
+        filters: [
+          {
+            origin: { fieldId: "edad" },
+            comparisonOperator: "GREATER",
+            values: ["30"],
+          },
+        ],
+      },
+    });
+  });
+
+  it("maps the `in` comparator to ANY_OF with a list of values", async () => {
+    const configPath = createApiConfig();
+    const fetchMock = createFetchMock();
+    fetchMock.mockResolvedValueOnce(jsonResponse({ widgetId: "widget-f2" }));
+    const program = buildProgram({ configPath });
+
+    await program.parseAsync([
+      "node",
+      "zinkee",
+      "--json",
+      "displays",
+      "widgets",
+      "create",
+      "display-1",
+      "--type",
+      "table",
+      "--filter",
+      "status:in:1,2,3",
+    ]);
+
+    const init = fetchMock.mock.calls[0]?.[1];
+    expect(JSON.parse(String(init?.body)).query.filters).toEqual([
+      {
+        origin: { fieldId: "status" },
+        comparisonOperator: "ANY_OF",
+        values: ["1", "2", "3"],
+      },
+    ]);
+  });
+
+  it("maps the `is_not_empty` comparator with empty values array", async () => {
+    const configPath = createApiConfig();
+    const fetchMock = createFetchMock();
+    fetchMock.mockResolvedValueOnce(jsonResponse({ widgetId: "widget-f3" }));
+    const program = buildProgram({ configPath });
+
+    await program.parseAsync([
+      "node",
+      "zinkee",
+      "--json",
+      "displays",
+      "widgets",
+      "create",
+      "display-1",
+      "--type",
+      "table",
+      "--filter",
+      "email:is_not_empty",
+    ]);
+
+    const init = fetchMock.mock.calls[0]?.[1];
+    expect(JSON.parse(String(init?.body)).query.filters).toEqual([
+      {
+        origin: { fieldId: "email" },
+        comparisonOperator: "IS_NOT_EMPTY",
+        values: [],
+      },
+    ]);
+  });
+
+  it("accumulates multiple --filter flags in order", async () => {
+    const configPath = createApiConfig();
+    const fetchMock = createFetchMock();
+    fetchMock.mockResolvedValueOnce(jsonResponse({ widgetId: "widget-f4" }));
+    const program = buildProgram({ configPath });
+
+    await program.parseAsync([
+      "node",
+      "zinkee",
+      "--json",
+      "displays",
+      "widgets",
+      "create",
+      "display-1",
+      "--type",
+      "table",
+      "--filter",
+      "status:eq:2",
+      "--filter",
+      "amount:gte:500",
+    ]);
+
+    const init = fetchMock.mock.calls[0]?.[1];
+    expect(JSON.parse(String(init?.body)).query.filters).toEqual([
+      { origin: { fieldId: "status" }, comparisonOperator: "EQUAL", values: ["2"] },
+      { origin: { fieldId: "amount" }, comparisonOperator: "GREATER_OR_EQUAL", values: ["500"] },
+    ]);
+  });
+
+  it("rejects --filter with an unsupported comparator before issuing a request", async () => {
+    const configPath = createApiConfig();
+    const fetchMock = createFetchMock();
+    const program = buildProgram({ configPath });
+    const stderrSpy = vi.spyOn(process.stderr, "write").mockImplementation(() => true);
+
+    await expect(
+      program.parseAsync([
+        "node",
+        "zinkee",
+        "--json",
+        "displays",
+        "widgets",
+        "create",
+        "display-1",
+        "--type",
+        "table",
+        "--filter",
+        "edad:invalido:30",
+      ]),
+    ).rejects.toThrow();
+
+    expect(fetchMock).not.toHaveBeenCalled();
+    expect(stderrSpy.mock.calls.map(([chunk]) => String(chunk)).join("")).toMatch(/Unsupported comparator/);
+    stderrSpy.mockRestore();
+  });
+
+  it("preserves --raw query.filters when only --field is passed (no --filter)", async () => {
+    const configPath = createApiConfig();
+    const fetchMock = createFetchMock();
+    fetchMock.mockResolvedValueOnce(jsonResponse({ widgetId: "widget-f6" }));
+    const program = buildProgram({ configPath });
+
+    await program.parseAsync([
+      "node",
+      "zinkee",
+      "--json",
+      "displays",
+      "widgets",
+      "create",
+      "display-1",
+      "--type",
+      "table",
+      "--field",
+      "foo",
+      "--raw",
+      '{"query":{"filters":[{"origin":{"fieldId":"status"},"comparisonOperator":"EQUAL","values":["2"]}]}}',
+    ]);
+
+    const init = fetchMock.mock.calls[0]?.[1];
+    expect(JSON.parse(String(init?.body))).toMatchObject({
+      view: { fields: ["foo"] },
+      query: {
+        filters: [
+          { origin: { fieldId: "status" }, comparisonOperator: "EQUAL", values: ["2"] },
+        ],
+      },
+    });
+  });
+
+  it("translates --filter for variable mutations into the structured filter contract", async () => {
+    const configPath = createApiConfig();
+    const fetchMock = createFetchMock();
+    fetchMock.mockResolvedValueOnce(jsonResponse({ variableId: "var-1" }));
+    const program = buildProgram({ configPath });
+
+    await program.parseAsync([
+      "node",
+      "zinkee",
+      "--json",
+      "displays",
+      "variables",
+      "create",
+      "display-1",
+      "--type",
+      "reference",
+      "--name",
+      "Activos",
+      "--filter",
+      "estado:eq:activo",
+    ]);
+
+    const init = fetchMock.mock.calls[0]?.[1];
+    expect(JSON.parse(String(init?.body))).toMatchObject({
+      type: "reference",
+      name: "Activos",
+      filters: [
+        {
+          origin: { fieldId: "estado" },
+          comparisonOperator: "EQUAL",
+          values: ["activo"],
+        },
+      ],
+    });
+  });
+
   it("blocks destructive display commands in read-only mode", async () => {
     const configPath = createApiConfig();
     const fetchMock = createFetchMock();

package/src/commands/displays.ts

@@ -6,6 +6,11 @@ import { Command, InvalidArgumentError } from "commander";
 import { DisplaysApi, type DisplayResource, type DisplaySummary } from "../api/displays.js";
 import { ApiClient } from "../client.js";
 import { defaultConfigPath, readRuntimeConfig } from "../config.js";
+import {
+  parseExpression,
+  type ExpressionComparator,
+  type ParsedExpression,
+} from "../parsers/expressions.js";
 import { normalizeUuidOrSlug, type NormalizedUuidOrSlug } from "../parsers/selectors.js";
 import { resolveRuntimeContext } from "../runtime-context.js";
 import type { RuntimeOverrides } from "../types.js";
@@ -54,7 +59,7 @@ interface VariableMutationOptions {
   defaultValue?: string[];
   sourceSchema?: string;
   sourceField?: string;
-  filter?: string[];
+  filter?: ParsedExpression[];
   dateMode?: string;
   dateDynamicOption?: string;
   dateSpecific?: string;
@@ -78,7 +83,7 @@ interface WidgetMutationOptions {
   layoutFile?: string;
   field?: string[];
   sort?: string[];
-  filter?: string[];
+  filter?: ParsedExpression[];
   widgetReadOnly?: boolean;
   hideAddButton?: boolean;
   hideDeleteButton?: boolean;
@@ -189,6 +194,46 @@ function parseUuidOrSlugSelector(input: string): NormalizedUuidOrSlug {
   }
 }
 
+const COMPARATOR_TO_DISPLAY_OPERATOR: Record<ExpressionComparator, string> = {
+  eq: "EQUAL",
+  neq: "NOT_EQUAL",
+  gt: "GREATER",
+  gte: "GREATER_OR_EQUAL",
+  lt: "LESS",
+  lte: "LESS_OR_EQUAL",
+  contains: "CONTAINS",
+  in: "ANY_OF",
+  is_empty: "IS_EMPTY",
+  is_not_empty: "IS_NOT_EMPTY",
+};
+
+function toDisplayFilter(parsed: ParsedExpression): Record<string, unknown> {
+  const values =
+    parsed.value === null
+      ? []
+      : Array.isArray(parsed.value)
+        ? [...parsed.value]
+        : [parsed.value];
+  return {
+    origin: { fieldId: parsed.field },
+    comparisonOperator: COMPARATOR_TO_DISPLAY_OPERATOR[parsed.comparator],
+    values,
+  };
+}
+
+function parseFilterExpression(input: string): ParsedExpression {
+  try {
+    return parseExpression(input);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : "Invalid filter expression.";
+    throw new InvalidArgumentError(message);
+  }
+}
+
+function collectFilters(value: string, previous: ParsedExpression[] = []): ParsedExpression[] {
+  return [...previous, parseFilterExpression(value)];
+}
+
 function parseBooleanFlag(input: string): boolean {
   const normalized = input.trim().toLowerCase();
   if (["true", "1", "yes", "y", "on"].includes(normalized)) return true;
@@ -278,7 +323,7 @@ function buildVariableBody(options: VariableMutationOptions): Record<string, unk
     };
   }
   if (options.filter && options.filter.length > 0) {
-    body.filters = options.filter.map((entry) => ({ raw: entry }));
+    body.filters = options.filter.map(toDisplayFilter);
   }
   if (
     options.dateMode ||
@@ -348,15 +393,19 @@ function buildWidgetBody(options: WidgetMutationOptions): Record<string, unknown
     };
   }
 
-  if (options.field?.length || options.sort?.length || options.filter?.length) {
+  if (options.field && options.field.length > 0) {
     body.view = {
       ...(typeof body.view === "object" && body.view ? body.view as Record<string, unknown> : {}),
       fields: options.field,
     };
+  }
+  const queryMerge: Record<string, unknown> = {};
+  if (options.sort && options.sort.length > 0) queryMerge.sorts = options.sort;
+  if (options.filter && options.filter.length > 0) queryMerge.filters = options.filter.map(toDisplayFilter);
+  if (Object.keys(queryMerge).length > 0) {
     body.query = {
       ...(typeof body.query === "object" && body.query ? body.query as Record<string, unknown> : {}),
-      sorts: options.sort,
-      filters: options.filter?.map((entry) => ({ raw: entry })),
+      ...queryMerge,
     };
   }
 
@@ -624,7 +673,7 @@ export function registerDisplaysCommands(
   variables.command("create").description("Create variable").argument("<display>", "display uuid or slug", parseUuidOrSlugSelector)
     .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", (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("--raw <json>").option("--raw-file <path>")
     .action(async function action(this: Command, display: NormalizedUuidOrSlug, commandOptions: VariableMutationOptions) {
@@ -636,7 +685,7 @@ export function registerDisplaysCommands(
   variables.command("update").description("Update variable").argument("<display>", "display uuid or slug", parseUuidOrSlugSelector).argument("<variable>", "variable id")
     .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", (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("--raw <json>").option("--raw-file <path>")
     .action(async function action(this: Command, display: NormalizedUuidOrSlug, variableId: string, commandOptions: VariableMutationOptions) {
@@ -668,7 +717,7 @@ export function registerDisplaysCommands(
     .option("--tab <tabId>").option("--slot <slotId>").option("--layout <json>").option("--layout-file <path>")
     .option("--field <field>", "repeatable field", (v, p: string[] = []) => [...p, v], [])
     .option("--sort <sort>", "repeatable sort", (v, p: string[] = []) => [...p, v], [])
-    .option("--filter <expr>", "repeatable filter", (v, p: string[] = []) => [...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("--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")
@@ -686,7 +735,7 @@ export function registerDisplaysCommands(
     .option("--tab <tabId>").option("--slot <slotId>").option("--layout <json>").option("--layout-file <path>")
     .option("--field <field>", "repeatable field", (v, p: string[] = []) => [...p, v], [])
     .option("--sort <sort>", "repeatable sort", (v, p: string[] = []) => [...p, v], [])
-    .option("--filter <expr>", "repeatable filter", (v, p: string[] = []) => [...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("--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")

package/src/utils/examples.ts

@@ -1518,30 +1518,41 @@ const specificExamples: Record<string, readonly CommandExample[]> = {
     },
     {
       description:
-        "Add query filters that match the full comparisonOperator contract (requires --raw because --filter only accepts free-form expressions).",
+        "Add query filters with --filter. The CLI parses the expression and emits the structured comparisonOperator payload the API expects.",
       command:
-        `zinkee --json displays widgets update 0f6f062f-1478-4df2-96a1-c495d037d260 11111111-1111-4111-a111-111111111111 --raw '{"query":{"filters":[{"origin":{"schemaId":"contacts","fieldId":"status"},"comparisonOperator":"EQUAL","values":["2"]},{"origin":{"schemaId":"contacts","fieldId":"amount"},"comparisonOperator":"GREATER_OR_EQUAL","values":["500"]}]}}'`,
+        `zinkee --json displays widgets update 0f6f062f-1478-4df2-96a1-c495d037d260 11111111-1111-4111-a111-111111111111 --filter "status:eq:2" --filter "amount:gte:500"`,
       raw: `{
   "query": {
     "filters": [
       {
-        "origin": {
-          "schemaId": "contacts",
-          "fieldId": "status"
-        },
+        "origin": { "fieldId": "status" },
         "comparisonOperator": "EQUAL",
         "values": ["2"]
       },
       {
-        "origin": {
-          "schemaId": "contacts",
-          "fieldId": "amount"
-        },
+        "origin": { "fieldId": "amount" },
         "comparisonOperator": "GREATER_OR_EQUAL",
         "values": ["500"]
       }
     ]
   }
+}`,
+    },
+    {
+      description:
+        "Fall back to --raw for comparators the parser does not cover yet (e.g. NOT_CONTAINS, RANGE).",
+      command:
+        `zinkee --json displays widgets update 0f6f062f-1478-4df2-96a1-c495d037d260 11111111-1111-4111-a111-111111111111 --raw '{"query":{"filters":[{"origin":{"fieldId":"due-date"},"comparisonOperator":"RANGE","values":["2025-01-01","2025-12-31"]}]}}'`,
+      raw: `{
+  "query": {
+    "filters": [
+      {
+        "origin": { "fieldId": "due-date" },
+        "comparisonOperator": "RANGE",
+        "values": ["2025-01-01", "2025-12-31"]
+      }
+    ]
+  }
 }`,
     },
     {