zinkee 0.1.36 → 0.1.38

package/package.json

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

package/src/api/displays.ts

@@ -15,7 +15,7 @@ export interface ApiDisplay {
   variables?: Array<Record<string, unknown>>;
   widgets?: Array<Record<string, unknown>>;
   navigationTargets?: Array<Record<string, unknown>>;
-  crossWidgetFilter?: Record<string, unknown> | null;
+  crossWidgetFilter?: Array<Record<string, unknown>> | null;
 }
 
 export interface ApiDisplayTab {
@@ -272,7 +272,7 @@ export class DisplaysApi {
 
   setCrossWidgetFilter(
     display: NormalizedUuidOrSlug,
-    body: Record<string, unknown>,
+    body: unknown[],
   ): Promise<Record<string, unknown>> {
     return this.client.requestJson<Record<string, unknown>>(
       `/api/v2/displays/${selectorValue(display)}/cross-widget-filter`,

package/src/command-registry.ts

@@ -466,7 +466,7 @@ export const commandRegistry = {
     command: "displays cross-widget-filter set",
     accessLevel: "write",
     supportsExample: true,
-    supportsRaw: false,
+    supportsRaw: true,
     output: writeOutput,
   },
   "displays cross-widget-filter delete": {

package/src/commands/displays.test.ts

@@ -797,4 +797,69 @@ describe("displays commands", () => {
 
     expect(fetchMock).not.toHaveBeenCalled();
   });
+
+  it("wraps a flag-built cross widget filter configuration in an array", async () => {
+    const configPath = createApiConfig();
+    const output = createStdoutBuffer();
+    const fetchMock = createFetchMock();
+    fetchMock.mockResolvedValueOnce(jsonResponse({ displayId: "display-1" }));
+    const program = buildProgram({ configPath, stdout: output.stdout });
+
+    await program.parseAsync([
+      "node",
+      "zinkee",
+      "--json",
+      "displays",
+      "cross-widget-filter",
+      "set",
+      "display-1",
+      "--source-widget",
+      "w-source",
+      "--source-field",
+      "f-source",
+      "--target",
+      "w-target:f-target",
+    ]);
+
+    const init = fetchMock.mock.calls[0]?.[1];
+    expect(fetchMock.mock.calls[0]?.[0]).toBe(
+      "https://api.zinkee.test/api/v2/displays/display-1/cross-widget-filter",
+    );
+    expect(init?.method).toBe("PUT");
+    expect(JSON.parse(String(init?.body))).toEqual([
+      {
+        source: { widgetId: "w-source", fieldId: "f-source" },
+        targets: [{ widgetId: "w-target", fieldId: "f-target" }],
+      },
+    ]);
+  });
+
+  it("sends the raw array of cross widget filter configurations verbatim", async () => {
+    const configPath = createApiConfig();
+    const output = createStdoutBuffer();
+    const fetchMock = createFetchMock();
+    fetchMock.mockResolvedValueOnce(jsonResponse({ displayId: "display-1" }));
+    const program = buildProgram({ configPath, stdout: output.stdout });
+
+    const rawArray = [
+      { source: { widgetId: "w1", fieldId: "f1" }, targets: [{ widgetId: "t1", fieldId: "f1" }] },
+      { source: { widgetId: "w2", fieldId: "f2" }, targets: [{ widgetId: "t2", fieldId: "f2" }] },
+    ];
+
+    await program.parseAsync([
+      "node",
+      "zinkee",
+      "--json",
+      "displays",
+      "cross-widget-filter",
+      "set",
+      "display-1",
+      "--raw",
+      JSON.stringify(rawArray),
+    ]);
+
+    const init = fetchMock.mock.calls[0]?.[1];
+    expect(init?.method).toBe("PUT");
+    expect(JSON.parse(String(init?.body))).toEqual(rawArray);
+  });
 });

package/src/commands/displays.ts

@@ -149,9 +149,12 @@ interface NavigationTargetMutationOptions {
 }
 
 interface CrossWidgetFilterSetOptions {
-  sourceWidget: string;
-  sourceField: string;
-  target: string[];
+  sourceWidget?: string;
+  sourceField?: string;
+  sourceSchema?: string;
+  target?: string[];
+  raw?: string;
+  rawFile?: string;
 }
 
 function getCommandIo(stdout: CommandIo | undefined): CommandIo {
@@ -744,20 +747,60 @@ function buildNavigationTargetBody(options: NavigationTargetMutationOptions): Re
   return body;
 }
 
-function buildCrossWidgetFilterBody(options: CrossWidgetFilterSetOptions): Record<string, unknown> {
-  return {
-    source: {
-      widgetId: options.sourceWidget,
-      fieldId: options.sourceField,
-    },
-    targets: options.target.map((entry) => {
-      const [widgetId, fieldId] = entry.split(":");
-      if (!widgetId || !fieldId) {
-        throw new CliError("invalid_cli_usage", `Invalid --target entry "${entry}". Use <widgetId:fieldId>.`);
-      }
-      return { widgetId, fieldId };
-    }),
+function readRawArray(raw?: string, rawFile?: string): unknown[] {
+  if (raw && rawFile) {
+    throw new CliError("invalid_cli_usage", 'Use either "--raw" or "--raw-file", not both.');
+  }
+  const source = rawFile ? readFileSync(rawFile, "utf8") : raw;
+  if (!source) {
+    return [];
+  }
+  try {
+    const parsed = JSON.parse(source) as unknown;
+    if (!Array.isArray(parsed)) {
+      throw new CliError("invalid_cli_usage", "Raw cross widget filter payload must be a JSON array of configurations.");
+    }
+    return parsed;
+  } catch (error) {
+    if (error instanceof CliError) throw error;
+    throw new CliError("invalid_cli_usage", "Raw JSON payload is invalid.");
+  }
+}
+
+// The endpoint replaces the whole array of configurations. With flags a single configuration is
+// built and wrapped in an array; use --raw/--raw-file to send several configurations at once.
+function buildCrossWidgetFilterBody(options: CrossWidgetFilterSetOptions): unknown[] {
+  if (options.raw !== undefined || options.rawFile !== undefined) {
+    return readRawArray(options.raw, options.rawFile);
+  }
+
+  if (!options.sourceWidget || !options.sourceField) {
+    throw new CliError(
+      "invalid_cli_usage",
+      "Provide --source-widget and --source-field, or --raw/--raw-file with the full configuration array.",
+    );
+  }
+
+  const source: Record<string, unknown> = {
+    widgetId: options.sourceWidget,
+    fieldId: options.sourceField,
   };
+  if (options.sourceSchema) {
+    source.schemaId = options.sourceSchema;
+  }
+
+  return [
+    {
+      source,
+      targets: (options.target ?? []).map((entry) => {
+        const [widgetId, fieldId] = entry.split(":");
+        if (!widgetId || !fieldId) {
+          throw new CliError("invalid_cli_usage", `Invalid --target entry "${entry}". Use <widgetId:fieldId>.`);
+        }
+        return { widgetId, fieldId };
+      }),
+    },
+  ];
 }
 
 export function registerDisplaysCommands(
@@ -1212,10 +1255,15 @@ export function registerDisplaysCommands(
   const cross = displays.command("cross-widget-filter").description("Manage cross widget filter");
   cross.command("get").description("Get cross widget filter").argument("<display>", "display uuid or slug", parseUuidOrSlugSelector).action(async function action(this: Command, display: NormalizedUuidOrSlug) {
     const { api, json } = createDisplaysApi(this, filePath); const data = await api.getDisplay(display); const item = data.crossWidgetFilter ?? null;
-    if (json) { emitJson(stdout, "displays cross-widget-filter get", item); return; } printTable(item ? [item] : [], undefined, stdout);
+    if (json) { emitJson(stdout, "displays cross-widget-filter get", item); return; } printTable(item ?? [], undefined, stdout);
   });
-  cross.command("set").description("Set cross widget filter").argument("<display>", "display uuid or slug", parseUuidOrSlugSelector)
-    .requiredOption("--source-widget <id>").requiredOption("--source-field <id>").requiredOption("--target <widget:field>", "repeatable target", (v, p: string[] = []) => [...p, v], [])
+  cross.command("set").description("Set cross widget filter (replaces the whole array of configurations)").argument("<display>", "display uuid or slug", parseUuidOrSlugSelector)
+    .option("--source-widget <id>", "source widget id (single-configuration mode)")
+    .option("--source-field <id>", "source field id (single-configuration mode)")
+    .option("--source-schema <id>", "source schema id, only for HIERARCHY source widgets")
+    .option("--target <widget:field>", "repeatable target (single-configuration mode)", (v, p: string[] = []) => [...p, v], [])
+    .option("--raw <json>", "full array of configurations as JSON (for several configurations)")
+    .option("--raw-file <path>", "path to a JSON file with the full array of configurations")
     .action(async function action(this: Command, display: NormalizedUuidOrSlug, commandOptions: CrossWidgetFilterSetOptions) {
       const { api, json, readOnly } = createDisplaysApi(this, filePath); ensureWritable("displays cross-widget-filter set", readOnly, "write");
       const data = await api.setCrossWidgetFilter(display, buildCrossWidgetFilterBody(commandOptions));

package/src/utils/examples.ts

@@ -1967,42 +1967,92 @@ const specificExamples: Record<string, readonly CommandExample[]> = {
   ]),
   "displays cross-widget-filter set": buildCommandExamples([
     {
-      description: "Link one source widget/field to several target widgets through the same field.",
+      description:
+        "Single configuration with flags: link one source widget/field to several targets. The whole array is replaced.",
       command:
         'zinkee --json displays cross-widget-filter set 0f6f062f-1478-4df2-96a1-c495d037d260 --source-widget 11111111-1111-4111-a111-111111111111 --source-field c60b8526-5835-4c9f-aecd-9a16c7704a34 --target 22222222-2222-4222-a222-222222222222:c60b8526-5835-4c9f-aecd-9a16c7704a34 --target 33333333-3333-4333-a333-333333333333:c60b8526-5835-4c9f-aecd-9a16c7704a34',
-      raw: `{
-  "source": {
-    "widgetId": "11111111-1111-4111-a111-111111111111",
-    "fieldId": "c60b8526-5835-4c9f-aecd-9a16c7704a34"
-  },
-  "targets": [
-    {
-      "widgetId": "22222222-2222-4222-a222-222222222222",
+      raw: `[
+  {
+    "source": {
+      "widgetId": "11111111-1111-4111-a111-111111111111",
       "fieldId": "c60b8526-5835-4c9f-aecd-9a16c7704a34"
     },
+    "targets": [
+      {
+        "widgetId": "22222222-2222-4222-a222-222222222222",
+        "fieldId": "c60b8526-5835-4c9f-aecd-9a16c7704a34"
+      },
+      {
+        "widgetId": "33333333-3333-4333-a333-333333333333",
+        "fieldId": "c60b8526-5835-4c9f-aecd-9a16c7704a34"
+      }
+    ]
+  }
+]`,
+    },
     {
-      "widgetId": "33333333-3333-4333-a333-333333333333",
+      description:
+        "Several independent configurations with --raw (each source filters its own targets). A widget cannot be a target of two configurations.",
+      command:
+        "zinkee --json displays cross-widget-filter set 0f6f062f-1478-4df2-96a1-c495d037d260 --raw '[{\"source\":{\"widgetId\":\"11111111-1111-4111-a111-111111111111\",\"fieldId\":\"c60b8526-5835-4c9f-aecd-9a16c7704a34\"},\"targets\":[{\"widgetId\":\"22222222-2222-4222-a222-222222222222\",\"fieldId\":\"c60b8526-5835-4c9f-aecd-9a16c7704a34\"}]},{\"source\":{\"widgetId\":\"44444444-4444-4444-a444-444444444444\",\"fieldId\":\"a8f1d7e3-2b5c-4d9e-8a1b-3c4d5e6f7890\"},\"targets\":[{\"widgetId\":\"55555555-5555-4555-a555-555555555555\",\"fieldId\":\"a8f1d7e3-2b5c-4d9e-8a1b-3c4d5e6f7890\"}]}]'",
+      raw: `[
+  {
+    "source": {
+      "widgetId": "11111111-1111-4111-a111-111111111111",
       "fieldId": "c60b8526-5835-4c9f-aecd-9a16c7704a34"
-    }
-  ]
-}`,
+    },
+    "targets": [
+      {
+        "widgetId": "22222222-2222-4222-a222-222222222222",
+        "fieldId": "c60b8526-5835-4c9f-aecd-9a16c7704a34"
+      }
+    ]
+  },
+  {
+    "source": {
+      "widgetId": "44444444-4444-4444-a444-444444444444",
+      "fieldId": "a8f1d7e3-2b5c-4d9e-8a1b-3c4d5e6f7890"
+    },
+    "targets": [
+      {
+        "widgetId": "55555555-5555-4555-a555-555555555555",
+        "fieldId": "a8f1d7e3-2b5c-4d9e-8a1b-3c4d5e6f7890"
+      }
+    ]
+  }
+]`,
     },
     {
-      description: "Filter one target widget by the status field of the source.",
+      description:
+        "Hierarchy chain with --raw-file: a target of one configuration is the source of the next (click Parent → filters Child, click Child → filters Grandchild).",
       command:
-        'zinkee --json displays cross-widget-filter set 0f6f062f-1478-4df2-96a1-c495d037d260 --source-widget 11111111-1111-4111-a111-111111111111 --source-field a8f1d7e3-2b5c-4d9e-8a1b-3c4d5e6f7890 --target 66666666-6666-4666-a666-666666666666:a8f1d7e3-2b5c-4d9e-8a1b-3c4d5e6f7890',
-      raw: `{
-  "source": {
-    "widgetId": "11111111-1111-4111-a111-111111111111",
-    "fieldId": "a8f1d7e3-2b5c-4d9e-8a1b-3c4d5e6f7890"
+        "zinkee --json displays cross-widget-filter set 0f6f062f-1478-4df2-96a1-c495d037d260 --raw-file cross-widget-filter.json",
+      raw: `[
+  {
+    "source": {
+      "widgetId": "11111111-1111-4111-a111-111111111111",
+      "fieldId": "c60b8526-5835-4c9f-aecd-9a16c7704a34"
+    },
+    "targets": [
+      {
+        "widgetId": "22222222-2222-4222-a222-222222222222",
+        "fieldId": "c60b8526-5835-4c9f-aecd-9a16c7704a34"
+      }
+    ]
   },
-  "targets": [
-    {
-      "widgetId": "66666666-6666-4666-a666-666666666666",
+  {
+    "source": {
+      "widgetId": "22222222-2222-4222-a222-222222222222",
       "fieldId": "a8f1d7e3-2b5c-4d9e-8a1b-3c4d5e6f7890"
-    }
-  ]
-}`,
+    },
+    "targets": [
+      {
+        "widgetId": "33333333-3333-4333-a333-333333333333",
+        "fieldId": "a8f1d7e3-2b5c-4d9e-8a1b-3c4d5e6f7890"
+      }
+    ]
+  }
+]`,
     },
   ]),
   "schemas list": buildCommandExamples([
@@ -2900,18 +2950,20 @@ const specificExamples: Record<string, readonly CommandExample[]> = {
       }
     }
   ],
-  "crossWidgetFilter": {
-    "source": {
-      "widgetId": "11111111-1111-4111-a111-111111111111",
-      "fieldId": "c60b8526-5835-4c9f-aecd-9a16c7704a34"
-    },
-    "targets": [
-      {
-        "widgetId": "22222222-2222-4222-a222-222222222222",
+  "crossWidgetFilter": [
+    {
+      "sourceWidget": {
+        "widgetId": "11111111-1111-4111-a111-111111111111",
         "fieldId": "c60b8526-5835-4c9f-aecd-9a16c7704a34"
-      }
-    ]
-  },
+      },
+      "targetWidgets": [
+        {
+          "widgetId": "22222222-2222-4222-a222-222222222222",
+          "fieldId": "c60b8526-5835-4c9f-aecd-9a16c7704a34"
+        }
+      ]
+    }
+  ],
   "navigationTargets": [
     {
       "id": "nav-target-customer",