zinkee 0.1.37 → 0.1.39

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zinkee",
-  "version": "0.1.37",
+  "version": "0.1.39",
   "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

@@ -489,6 +489,147 @@ describe("displays commands", () => {
     expect(fetchMock).not.toHaveBeenCalled();
   });
 
+  it("translates --lock-* flags into behavior.lockedFields", async () => {
+    const configPath = createApiConfig();
+    const output = createStdoutBuffer();
+    const fetchMock = createFetchMock();
+    fetchMock.mockResolvedValueOnce(jsonResponse({ displayId: "display-1", widgetId: "widget-l1" }));
+    const program = buildProgram({ configPath, stdout: output.stdout });
+
+    await program.parseAsync([
+      "node",
+      "zinkee",
+      "--json",
+      "displays",
+      "widgets",
+      "create",
+      "display-1",
+      "--type",
+      "table",
+      "--origin-resource",
+      "schema-1",
+      "--lock-field",
+      "contact-name",
+      "--lock-condition",
+      "status:invoice-number:is_empty",
+      "--lock-condition",
+      "status:amount:gte:500",
+      "--lock-message-before",
+      "status:Status locks until the invoice number is set.",
+      "--lock-message-after",
+      "status:Status is locked because the invoice number is missing.",
+    ]);
+
+    const init = fetchMock.mock.calls[0]?.[1];
+    expect(JSON.parse(String(init?.body))).toMatchObject({
+      type: "TABLE_OR_SUBTABLE",
+      behavior: {
+        lockedFields: [
+          {
+            field: { fieldId: "contact-name" },
+            conditions: [],
+          },
+          {
+            field: { fieldId: "status" },
+            conditions: [
+              {
+                origin: { fieldId: "invoice-number" },
+                comparisonOperator: "IS_EMPTY",
+                values: [],
+              },
+              {
+                origin: { fieldId: "amount" },
+                comparisonOperator: "GREATER_OR_EQUAL",
+                values: ["500"],
+              },
+            ],
+            messageBeforeLock: "Status locks until the invoice number is set.",
+            messageAfterLock: "Status is locked because the invoice number is missing.",
+          },
+        ],
+      },
+    });
+  });
+
+  it("clears locked fields with --clear-locked-fields", async () => {
+    const configPath = createApiConfig();
+    const output = createStdoutBuffer();
+    const fetchMock = createFetchMock();
+    fetchMock.mockResolvedValueOnce(jsonResponse({ displayId: "display-1", widgetId: "widget-l2" }));
+    const program = buildProgram({ configPath, stdout: output.stdout });
+
+    await program.parseAsync([
+      "node",
+      "zinkee",
+      "--json",
+      "displays",
+      "widgets",
+      "update",
+      "display-1",
+      "widget-l2",
+      "--clear-locked-fields",
+    ]);
+
+    const init = fetchMock.mock.calls[0]?.[1];
+    expect(init?.method).toBe("PATCH");
+    expect(JSON.parse(String(init?.body))).toEqual({
+      behavior: { lockedFields: [] },
+    });
+  });
+
+  it("rejects --clear-locked-fields combined with --lock-* flags", async () => {
+    const configPath = createApiConfig();
+    const output = createStdoutBuffer();
+    const fetchMock = createFetchMock();
+    const program = buildProgram({ configPath, stdout: output.stdout });
+
+    await expect(
+      program.parseAsync([
+        "node",
+        "zinkee",
+        "--json",
+        "displays",
+        "widgets",
+        "update",
+        "display-1",
+        "widget-l3",
+        "--clear-locked-fields",
+        "--lock-field",
+        "status",
+      ]),
+    ).rejects.toThrow(/not both/i);
+    expect(fetchMock).not.toHaveBeenCalled();
+  });
+
+  it("rejects a --lock-condition without an expression", async () => {
+    const configPath = createApiConfig();
+    const output = createStdoutBuffer();
+    const fetchMock = createFetchMock();
+    const errorSpy = vi.spyOn(process.stderr, "write").mockImplementation(() => true);
+    const program = buildProgram({ configPath, stdout: output.stdout });
+
+    // Option arg parser errors are handled by commander, which prints the
+    // InvalidArgumentError message to stderr and exits with code 1 (same
+    // behavior as an invalid --filter expression).
+    await expect(
+      program.parseAsync([
+        "node",
+        "zinkee",
+        "--json",
+        "displays",
+        "widgets",
+        "create",
+        "display-1",
+        "--type",
+        "table",
+        "--lock-condition",
+        "status",
+      ]),
+    ).rejects.toThrow(/process.exit/);
+    expect(errorSpy.mock.calls.flat().join("\n")).toMatch(/lockedField/i);
+    expect(fetchMock).not.toHaveBeenCalled();
+  });
+
   it("translates --filter into the structured display filter contract", async () => {
     const configPath = createApiConfig();
     const output = createStdoutBuffer();
@@ -797,4 +938,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

@@ -98,6 +98,11 @@ interface WidgetMutationOptions {
   hideSortButton?: boolean;
   hideFilterButton?: boolean;
   hideSeeButton?: boolean;
+  lockField?: string[];
+  lockCondition?: LockConditionOption[];
+  lockMessageBefore?: LockMessageOption[];
+  lockMessageAfter?: LockMessageOption[];
+  clearLockedFields?: boolean;
   calc?: string;
   calcField?: string;
   kpiConfig?: string;
@@ -141,6 +146,16 @@ interface WidgetMutationOptions {
   rawFile?: string;
 }
 
+interface LockConditionOption {
+  lockedField: string;
+  expression: ParsedExpression;
+}
+
+interface LockMessageOption {
+  lockedField: string;
+  message: string;
+}
+
 interface NavigationTargetMutationOptions {
   sourceWidget?: string;
   targetDisplay?: string;
@@ -149,9 +164,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 {
@@ -272,6 +290,115 @@ function collectFilters(value: string, previous: ParsedExpression[] = []): Parse
   return [...previous, parseFilterExpression(value)];
 }
 
+function parseLockConditionOption(input: string): LockConditionOption {
+  const trimmed = input.trim();
+  let lockedField: string;
+  let expressionText: string;
+
+  if (trimmed.includes(":") && !trimmed.includes(" ")) {
+    const separatorIndex = trimmed.indexOf(":");
+    lockedField = trimmed.slice(0, separatorIndex).trim();
+    expressionText = trimmed.slice(separatorIndex + 1).trim();
+  } else {
+    const parts = trimmed.split(/\s+/);
+    lockedField = parts[0]?.trim() ?? "";
+    expressionText = parts.slice(1).join(" ").trim();
+  }
+
+  if (!lockedField || !expressionText) {
+    throw new InvalidArgumentError(
+      'Expected "<lockedField>:<field>:<comparator>[:<value>]" (or space-separated), e.g. "status:invoice-number:is_empty".',
+    );
+  }
+
+  return { lockedField, expression: parseFilterExpression(expressionText) };
+}
+
+function collectLockConditions(value: string, previous: LockConditionOption[] = []): LockConditionOption[] {
+  return [...previous, parseLockConditionOption(value)];
+}
+
+function parseLockMessageOption(input: string): LockMessageOption {
+  const separatorIndex = input.indexOf(":");
+  const lockedField = separatorIndex > 0 ? input.slice(0, separatorIndex).trim() : "";
+  const message = separatorIndex > 0 ? input.slice(separatorIndex + 1).trim() : "";
+
+  if (!lockedField || !message) {
+    throw new InvalidArgumentError('Expected "<lockedField>:<message>", e.g. "status:Locked once approved.".');
+  }
+
+  return { lockedField, message };
+}
+
+function collectLockMessages(value: string, previous: LockMessageOption[] = []): LockMessageOption[] {
+  return [...previous, parseLockMessageOption(value)];
+}
+
+/**
+ * Builds behavior.lockedFields from the --lock-* flags. Every flag names its
+ * locked field explicitly, so ordering between flags never matters. A field
+ * with no conditions is locked permanently; with conditions it locks when all
+ * of them match (AND). Returns [] for --clear-locked-fields and undefined when
+ * no lock flag was used.
+ */
+function buildLockedFields(options: WidgetMutationOptions): Array<Record<string, unknown>> | undefined {
+  const hasLockFlags =
+    (options.lockField?.length ?? 0) > 0 ||
+    (options.lockCondition?.length ?? 0) > 0 ||
+    (options.lockMessageBefore?.length ?? 0) > 0 ||
+    (options.lockMessageAfter?.length ?? 0) > 0;
+
+  if (options.clearLockedFields) {
+    if (hasLockFlags) {
+      throw new CliError(
+        "invalid_cli_usage",
+        'Use either "--clear-locked-fields" or the "--lock-*" flags, not both.',
+      );
+    }
+    return [];
+  }
+
+  if (!hasLockFlags) {
+    return undefined;
+  }
+
+  interface LockRule {
+    conditions: Array<Record<string, unknown>>;
+    messageBeforeLock?: string;
+    messageAfterLock?: string;
+  }
+
+  const rules = new Map<string, LockRule>();
+  const ensureRule = (lockedField: string): LockRule => {
+    let rule = rules.get(lockedField);
+    if (!rule) {
+      rule = { conditions: [] };
+      rules.set(lockedField, rule);
+    }
+    return rule;
+  };
+
+  for (const lockedField of options.lockField ?? []) {
+    ensureRule(lockedField);
+  }
+  for (const { lockedField, expression } of options.lockCondition ?? []) {
+    ensureRule(lockedField).conditions.push(toDisplayFilter(expression));
+  }
+  for (const { lockedField, message } of options.lockMessageBefore ?? []) {
+    ensureRule(lockedField).messageBeforeLock = message;
+  }
+  for (const { lockedField, message } of options.lockMessageAfter ?? []) {
+    ensureRule(lockedField).messageAfterLock = message;
+  }
+
+  return [...rules.entries()].map(([lockedField, rule]) => ({
+    field: { fieldId: lockedField },
+    conditions: rule.conditions,
+    ...(rule.messageBeforeLock !== undefined ? { messageBeforeLock: rule.messageBeforeLock } : {}),
+    ...(rule.messageAfterLock !== undefined ? { messageAfterLock: rule.messageAfterLock } : {}),
+  }));
+}
+
 function parseBooleanFlag(input: string): boolean {
   const normalized = input.trim().toLowerCase();
   if (["true", "1", "yes", "y", "on"].includes(normalized)) return true;
@@ -694,6 +821,14 @@ function buildWidgetBody(options: WidgetMutationOptions): Record<string, unknown
     };
   }
 
+  const lockedFields = buildLockedFields(options);
+  if (lockedFields !== undefined) {
+    body.behavior = {
+      ...(typeof body.behavior === "object" && body.behavior ? body.behavior as Record<string, unknown> : {}),
+      lockedFields,
+    };
+  }
+
   if (options.calc || options.calcField || options.kpiConfig) {
     body.kpi = {
       ...(typeof body.kpi === "object" && body.kpi ? body.kpi as Record<string, unknown> : {}),
@@ -744,20 +879,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(
@@ -1088,6 +1263,11 @@ export function registerDisplaysCommands(
     .option("--sort <sort>", "repeatable sort", (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("--lock-field <field>", "lock a field permanently in this widget (repeatable; field UUID or slug)", (v, p: string[] = []) => [...p, v], [])
+    .option("--lock-condition <expr>", 'conditional lock "<lockedField>:<field>:<comparator>[:<value>]"; locks <lockedField> when all its conditions match (AND, repeatable)', collectLockConditions, [])
+    .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: string[] = []) => [...p, v], [])
@@ -1135,6 +1315,11 @@ export function registerDisplaysCommands(
     .option("--sort <sort>", "repeatable sort", (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("--lock-field <field>", "lock a field permanently in this widget (repeatable; field UUID or slug)", (v, p: string[] = []) => [...p, v], [])
+    .option("--lock-condition <expr>", 'conditional lock "<lockedField>:<field>:<comparator>[:<value>]"; locks <lockedField> when all its conditions match (AND, repeatable)', collectLockConditions, [])
+    .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: string[] = []) => [...p, v], [])
@@ -1212,10 +1397,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));