zinkee 0.1.41 → 0.1.43

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zinkee",
-  "version": "0.1.41",
+  "version": "0.1.43",
   "description": "CLI for Zinkee API v2",
   "repository": {
     "type": "git",

package/src/api/displays.ts

@@ -5,6 +5,7 @@ export interface ApiDisplay {
   [key: string]: unknown;
   id?: string;
   name?: string;
+  description?: string;
   layoutTemplate?: string;
   layout?: {
     template?: string;
@@ -62,6 +63,17 @@ export interface MoveDisplayInput {
 export type DisplaySummary = ApiDisplay;
 export type DisplayResource = ApiDisplay;
 
+export interface CreateDisplayInput {
+  name: string;
+  description?: string;
+  layout: Record<string, unknown>;
+}
+
+export interface UpdateDisplayInput {
+  name?: string;
+  description?: string;
+}
+
 function jsonOptions(body: unknown, method: string): RequestInit {
   return {
     method,
@@ -91,13 +103,13 @@ export class DisplaysApi {
     return this.client.getJson<ApiDisplay>(`/api/v2/displays/${selectorValue(display)}`);
   }
 
-  createDisplay(body: Record<string, unknown>): Promise<ApiDisplay> {
+  createDisplay(body: CreateDisplayInput): Promise<ApiDisplay> {
     return this.client.requestJson<ApiDisplay>("/api/v2/displays", jsonOptions(body, "POST"));
   }
 
   updateDisplay(
     display: NormalizedUuidOrSlug,
-    body: Record<string, unknown>,
+    body: UpdateDisplayInput,
   ): Promise<ApiDisplay> {
     return this.client.requestJson<ApiDisplay>(
       `/api/v2/displays/${selectorValue(display)}`,

package/src/api/formulas.test.ts

@@ -0,0 +1,65 @@
+import { describe, expect, it, vi } from "vitest";
+
+import { normalizeUuidOrSlug } from "../parsers/selectors.js";
+import { ApiClient } from "../client.js";
+import { FormulasApi } from "./formulas.js";
+
+function jsonResponse(body: unknown): Response {
+  return new Response(JSON.stringify(body), {
+    status: 202,
+    headers: { "content-type": "application/json" },
+  });
+}
+
+describe("FormulasApi", () => {
+  it.each([
+    {
+      input: {
+        scope: "FIELD" as const,
+        schema: normalizeUuidOrSlug("invoices"),
+        field: normalizeUuidOrSlug("total"),
+      },
+      body: { scope: "FIELD", schema: "invoices", field: "total" },
+    },
+    {
+      input: {
+        scope: "SCHEMA" as const,
+        schema: normalizeUuidOrSlug("550e8400-e29b-41d4-a716-446655440001"),
+      },
+      body: {
+        scope: "SCHEMA",
+        schema: "550e8400-e29b-41d4-a716-446655440001",
+      },
+    },
+    {
+      input: { scope: "WORKSPACE" as const },
+      body: { scope: "WORKSPACE" },
+    },
+  ])("posts the $input.scope payload to the recompute endpoint", async ({ input, body }) => {
+    const fetchMock = vi.fn<typeof fetch>().mockResolvedValue(
+      jsonResponse({
+        requestId: "request-1",
+        scope: input.scope,
+        formulaCount: 1,
+        skippedFormulaCount: 0,
+        eventsQueued: 1,
+        status: "QUEUED",
+      }),
+    );
+    const api = new FormulasApi(
+      new ApiClient({
+        baseUrl: "https://api.zinkee.test",
+        apiKey: "test-token",
+        fetch: fetchMock,
+      }),
+    );
+
+    await api.recompute(input);
+
+    expect(fetchMock).toHaveBeenCalledOnce();
+    const [url, init] = fetchMock.mock.calls[0]!;
+    expect(url).toBe("https://api.zinkee.test/api/v2/formulas:recompute");
+    expect(init?.method).toBe("POST");
+    expect(JSON.parse(String(init?.body))).toEqual(body);
+  });
+});

package/src/api/formulas.ts

@@ -0,0 +1,67 @@
+import { ApiClient } from "../client.js";
+import type { NormalizedUuidOrSlug } from "../parsers/selectors.js";
+
+export type FormulaRecomputeScope = "FIELD" | "SCHEMA" | "WORKSPACE";
+
+export interface FormulaRecomputeResponse {
+  requestId: string;
+  scope: FormulaRecomputeScope;
+  formulaCount: number;
+  skippedFormulaCount: number;
+  eventsQueued: number;
+  status: "QUEUED";
+}
+
+export type FormulaRecomputeInput =
+  | {
+      scope: "FIELD";
+      schema: NormalizedUuidOrSlug;
+      field: NormalizedUuidOrSlug;
+    }
+  | {
+      scope: "SCHEMA";
+      schema: NormalizedUuidOrSlug;
+    }
+  | {
+      scope: "WORKSPACE";
+    };
+
+function selectorValue(selector: NormalizedUuidOrSlug): string {
+  return selector.value;
+}
+
+function toRequestBody(input: FormulaRecomputeInput): Record<string, string> {
+  if (input.scope === "FIELD") {
+    return {
+      scope: input.scope,
+      schema: selectorValue(input.schema),
+      field: selectorValue(input.field),
+    };
+  }
+
+  if (input.scope === "SCHEMA") {
+    return {
+      scope: input.scope,
+      schema: selectorValue(input.schema),
+    };
+  }
+
+  return { scope: input.scope };
+}
+
+export class FormulasApi {
+  constructor(private readonly client: ApiClient) {}
+
+  recompute(input: FormulaRecomputeInput): Promise<FormulaRecomputeResponse> {
+    return this.client.requestJson<FormulaRecomputeResponse>(
+      "/api/v2/formulas:recompute",
+      {
+        method: "POST",
+        headers: {
+          "content-type": "application/json",
+        },
+        body: JSON.stringify(toRequestBody(input)),
+      },
+    );
+  }
+}

package/src/api/schemas.ts

@@ -7,6 +7,7 @@ export interface ApiSchemaField {
   type?: string;
   slug?: string;
   label?: string;
+  description?: string;
   required?: boolean;
 }
 
@@ -47,12 +48,14 @@ export interface CreateSchemaFieldInput {
   type: string;
   slug: string;
   label: string;
+  description?: string;
   required?: boolean;
 }
 
 export interface UpdateSchemaFieldInput {
   [key: string]: unknown;
   label?: string;
+  description?: string;
   required?: boolean;
 }
 

package/src/command-registry.ts

@@ -14,6 +14,27 @@ const readOutput: CommandOutputCapability = "table-json";
 const writeOutput: CommandOutputCapability = "json-only";
 
 export const commandRegistry = {
+  "formulas recompute field": {
+    command: "formulas recompute field",
+    accessLevel: "write",
+    supportsExample: true,
+    supportsRaw: false,
+    output: writeOutput,
+  },
+  "formulas recompute schema": {
+    command: "formulas recompute schema",
+    accessLevel: "write",
+    supportsExample: true,
+    supportsRaw: false,
+    output: writeOutput,
+  },
+  "formulas recompute workspace": {
+    command: "formulas recompute workspace",
+    accessLevel: "write",
+    supportsExample: true,
+    supportsRaw: false,
+    output: writeOutput,
+  },
   "config path": {
     command: "config path",
     accessLevel: "read",

package/src/commands/displays.test.ts

@@ -94,6 +94,80 @@ describe("displays commands", () => {
     });
   });
 
+  it("creates displays with a description", 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",
+      "create",
+      "--name",
+      "Pipeline",
+      "--description",
+      "Sales pipeline overview",
+      "--template",
+      "widget_row_tabs",
+    ]);
+
+    expect(JSON.parse(String(fetchMock.mock.calls[0]?.[1]?.body))).toEqual({
+      name: "Pipeline",
+      description: "Sales pipeline overview",
+      layout: { template: "widget_row_tabs" },
+    });
+  });
+
+  it.each([
+    ["sets", "Sales pipeline overview"],
+    ["clears", ""],
+  ])("%s a display description without renaming it", async (_action, description) => {
+    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",
+      "update",
+      "display-1",
+      "--description",
+      description,
+    ]);
+
+    expect(fetchMock.mock.calls[0]?.[1]?.method).toBe("PATCH");
+    expect(JSON.parse(String(fetchMock.mock.calls[0]?.[1]?.body))).toEqual({ description });
+  });
+
+  it.each(["", "   "])("rejects an empty display name", async (name) => {
+    const configPath = createApiConfig();
+    const output = createStdoutBuffer();
+    const fetchMock = createFetchMock();
+    const program = buildProgram({ configPath, stdout: output.stdout });
+
+    await expect(
+      program.parseAsync([
+        "node",
+        "zinkee",
+        "--json",
+        "displays",
+        "update",
+        "display-1",
+        "--name",
+        name,
+      ]),
+    ).rejects.toThrow("Display name cannot be empty.");
+    expect(fetchMock).not.toHaveBeenCalled();
+  });
+
   it("creates freeform displays with nested freeform layouts", async () => {
     const configPath = createApiConfig();
     const output = createStdoutBuffer();
@@ -167,6 +241,31 @@ describe("displays commands", () => {
     });
   });
 
+  it("keeps the widget description flag in presentation and sends an empty clear value", async () => {
+    const configPath = createApiConfig();
+    const output = createStdoutBuffer();
+    const fetchMock = createFetchMock();
+    fetchMock.mockResolvedValueOnce(jsonResponse({ displayId: "display-1", widgetId: "widget-1" }));
+    const program = buildProgram({ configPath, stdout: output.stdout });
+
+    await program.parseAsync([
+      "node",
+      "zinkee",
+      "--json",
+      "displays",
+      "widgets",
+      "update",
+      "display-1",
+      "widget-1",
+      "--description",
+      "",
+    ]);
+
+    expect(JSON.parse(String(fetchMock.mock.calls[0]?.[1]?.body))).toEqual({
+      presentation: { description: "" },
+    });
+  });
+
   it("deep merges chart flags with chart data from --raw", async () => {
     const configPath = createApiConfig();
     const output = createStdoutBuffer();

package/src/commands/displays.ts

@@ -38,6 +38,7 @@ interface GlobalOptions extends RuntimeOverrides {}
 
 interface DisplayCreateOptions {
   name: string;
+  description?: string;
   template: string;
   freeformLayouts?: string;
   freeformLayoutsFile?: string;
@@ -45,6 +46,7 @@ interface DisplayCreateOptions {
 
 interface DisplayUpdateOptions {
   name?: string;
+  description?: string;
 }
 
 interface LayoutUpdateOptions {
@@ -979,6 +981,7 @@ export function registerDisplaysCommands(
     .command("create")
     .description("Create a display")
     .requiredOption("--name <name>", "display name")
+    .option("--description <text>", "display description")
     .requiredOption("--template <template>", "layout template")
     .option("--freeform-layouts <json>", "freeform layouts JSON")
     .option("--freeform-layouts-file <path>", "freeform layouts JSON file")
@@ -993,7 +996,11 @@ export function registerDisplaysCommands(
         "--freeform-layouts-file",
       );
       if (freeformLayouts !== undefined) layout.freeformLayouts = freeformLayouts;
-      const data = await api.createDisplay({ name: commandOptions.name, layout });
+      const data = await api.createDisplay({
+        name: commandOptions.name,
+        description: commandOptions.description,
+        layout,
+      });
       if (json) {
         emitJson(stdout, "displays create", data);
         return;
@@ -1006,11 +1013,20 @@ export function registerDisplaysCommands(
     .description("Update a display")
     .argument("<display>", "display uuid or slug", parseUuidOrSlugSelector)
     .option("--name <name>", "display name")
+    .option("--description <text>", 'display description (use "" to clear)')
     .action(async function action(this: Command, display: NormalizedUuidOrSlug, commandOptions: DisplayUpdateOptions) {
       const { api, json, readOnly } = createDisplaysApi(this, filePath);
       ensureWritable("displays update", readOnly, "write");
-      if (!commandOptions.name) throw new CliError("invalid_cli_usage", "Nothing to update.");
-      const data = await api.updateDisplay(display, { name: commandOptions.name });
+      if (commandOptions.name === undefined && commandOptions.description === undefined) {
+        throw new CliError("invalid_cli_usage", "Nothing to update.");
+      }
+      if (commandOptions.name !== undefined && commandOptions.name.trim().length === 0) {
+        throw new CliError("invalid_cli_usage", "Display name cannot be empty.");
+      }
+      const data = await api.updateDisplay(display, {
+        name: commandOptions.name,
+        description: commandOptions.description,
+      });
       if (json) {
         emitJson(stdout, "displays update", data);
         return;

package/src/commands/formulas.test.ts

@@ -0,0 +1,194 @@
+import { mkdtempSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { Command } from "commander";
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+import { registerFormulasCommands } from "./formulas.js";
+
+function createConfig(): string {
+  const dir = mkdtempSync(join(tmpdir(), "zinkee-formulas-"));
+  const filePath = join(dir, "config.toml");
+  writeFileSync(
+    filePath,
+    `default_profile = "test"\n\n[profiles.test]\napi_key = "token"\nbase_url = "https://api.zinkee.test"\n`,
+    "utf8",
+  );
+  return filePath;
+}
+
+function createStdoutBuffer() {
+  let output = "";
+  return {
+    stdout: {
+      write(chunk: string) {
+        output += chunk;
+        return true;
+      },
+    },
+    read: () => output,
+  };
+}
+
+function buildProgram(options: { configPath: string; stdout: { write(chunk: string): unknown } }): Command {
+  const program = new Command();
+  program
+    .name("zinkee")
+    .enablePositionalOptions()
+    .option("--read-only")
+    .option("--json");
+  registerFormulasCommands(program, options);
+  return program;
+}
+
+function queuedResponse(scope: "FIELD" | "SCHEMA" | "WORKSPACE", eventsQueued = 1): Response {
+  return new Response(
+    JSON.stringify({
+      requestId: "request-1",
+      scope,
+      formulaCount: eventsQueued,
+      skippedFormulaCount: 0,
+      eventsQueued,
+      status: "QUEUED",
+    }),
+    { status: 202, headers: { "content-type": "application/json" } },
+  );
+}
+
+afterEach(() => {
+  vi.unstubAllGlobals();
+  vi.restoreAllMocks();
+});
+
+describe("formulas commands", () => {
+  it("registers the formulas command group", () => {
+    const output = createStdoutBuffer();
+    const program = buildProgram({ configPath: createConfig(), stdout: output.stdout });
+
+    expect(program.commands.some((command) => command.name() === "formulas")).toBe(true);
+  });
+
+  it("queues one field by slug and emits the JSON envelope", async () => {
+    const fetchMock = vi.fn<typeof fetch>().mockResolvedValue(queuedResponse("FIELD"));
+    vi.stubGlobal("fetch", fetchMock);
+    const configPath = createConfig();
+    const output = createStdoutBuffer();
+    const program = buildProgram({ configPath, stdout: output.stdout });
+
+    await program.parseAsync([
+      "node",
+      "zinkee",
+      "--json",
+      "formulas",
+      "recompute",
+      "field",
+      "invoices",
+      "total",
+    ]);
+
+    const [, init] = fetchMock.mock.calls[0]!;
+    expect(JSON.parse(String(init?.body))).toEqual({
+      scope: "FIELD",
+      schema: "invoices",
+      field: "total",
+    });
+    expect(JSON.parse(output.read())).toEqual({
+      data: {
+        requestId: "request-1",
+        scope: "FIELD",
+        formulaCount: 1,
+        skippedFormulaCount: 0,
+        eventsQueued: 1,
+        status: "QUEUED",
+      },
+      meta: { command: "formulas recompute field", configPath },
+    });
+  });
+
+  it.each([
+    ["schema", ["invoices"]],
+    ["workspace", []],
+  ])("requires --yes before the %s request", async (scope, args) => {
+    const fetchMock = vi.fn<typeof fetch>();
+    vi.stubGlobal("fetch", fetchMock);
+    const output = createStdoutBuffer();
+    const program = buildProgram({ configPath: createConfig(), stdout: output.stdout });
+
+    await expect(
+      program.parseAsync([
+        "node",
+        "zinkee",
+        "formulas",
+        "recompute",
+        scope,
+        ...args,
+      ]),
+    ).rejects.toThrow("requires --yes");
+    expect(fetchMock).not.toHaveBeenCalled();
+  });
+
+  it("queues every schema formula after confirmation", async () => {
+    const fetchMock = vi.fn<typeof fetch>().mockResolvedValue(queuedResponse("SCHEMA", 3));
+    vi.stubGlobal("fetch", fetchMock);
+    const output = createStdoutBuffer();
+    const program = buildProgram({ configPath: createConfig(), stdout: output.stdout });
+
+    await program.parseAsync([
+      "node",
+      "zinkee",
+      "formulas",
+      "recompute",
+      "schema",
+      "invoices",
+      "--yes",
+    ]);
+
+    expect(output.read()).toContain("Queued 3 formula recalculation event(s)");
+    expect(output.read()).not.toContain("completed");
+  });
+
+  it("queues the workspace payload after confirmation", async () => {
+    const fetchMock = vi.fn<typeof fetch>().mockResolvedValue(queuedResponse("WORKSPACE", 5));
+    vi.stubGlobal("fetch", fetchMock);
+    const output = createStdoutBuffer();
+    const program = buildProgram({ configPath: createConfig(), stdout: output.stdout });
+
+    await program.parseAsync([
+      "node",
+      "zinkee",
+      "--json",
+      "formulas",
+      "recompute",
+      "workspace",
+      "--yes",
+    ]);
+
+    const [, init] = fetchMock.mock.calls[0]!;
+    expect(JSON.parse(String(init?.body))).toEqual({ scope: "WORKSPACE" });
+  });
+
+  it.each([
+    ["field", ["invoices", "total"]],
+    ["schema", ["invoices", "--yes"]],
+    ["workspace", ["--yes"]],
+  ])("blocks %s in read-only mode before any network request", async (scope, args) => {
+    const fetchMock = vi.fn<typeof fetch>();
+    vi.stubGlobal("fetch", fetchMock);
+    const output = createStdoutBuffer();
+    const program = buildProgram({ configPath: createConfig(), stdout: output.stdout });
+
+    await expect(
+      program.parseAsync([
+        "node",
+        "zinkee",
+        "--read-only",
+        "formulas",
+        "recompute",
+        scope,
+        ...args,
+      ]),
+    ).rejects.toThrow("not allowed in read-only mode");
+    expect(fetchMock).not.toHaveBeenCalled();
+  });
+});