zinkee 0.1.23 → 0.1.25

package/package.json

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

package/src/api/automations.ts

@@ -180,7 +180,7 @@ export class AutomationsApi {
 
   moveAutomation(input: MoveAutomationInput): Promise<Record<string, unknown>> {
     return this.client.requestJson<Record<string, unknown>>(
-      `/api/v2/automation-folders/${segment(input.targetFolderId)}/automations:move`,
+      "/api/v2/automation-folders/automations:move",
       jsonOptions(input, "POST"),
     );
   }

package/src/api/displays.ts

@@ -45,6 +45,19 @@ export interface ApiDisplayNavigationTarget {
   label?: string;
 }
 
+export interface ApiDisplayFolder {
+  [key: string]: unknown;
+  id?: string;
+  name?: string | null;
+  isRoot?: boolean;
+  displayCount?: number;
+}
+
+export interface MoveDisplayInput {
+  displayId: string;
+  targetFolderId: string;
+}
+
 export type DisplaySummary = ApiDisplay;
 export type DisplayResource = ApiDisplay;
 
@@ -273,4 +286,39 @@ export class DisplaysApi {
       { method: "DELETE" },
     );
   }
+
+  listFolders(): Promise<ApiDisplayFolder[]> {
+    return this.client.getJson<ApiDisplayFolder[]>("/api/v2/display-folders");
+  }
+
+  createFolder(body: Record<string, unknown>): Promise<ApiDisplayFolder> {
+    return this.client.requestJson<ApiDisplayFolder>(
+      "/api/v2/display-folders",
+      jsonOptions(body, "POST"),
+    );
+  }
+
+  updateFolder(
+    folder: NormalizedUuidOrSlug,
+    body: Record<string, unknown>,
+  ): Promise<ApiDisplayFolder> {
+    return this.client.requestJson<ApiDisplayFolder>(
+      `/api/v2/display-folders/${selectorValue(folder)}`,
+      jsonOptions(body, "PATCH"),
+    );
+  }
+
+  deleteFolder(folder: NormalizedUuidOrSlug): Promise<Record<string, unknown>> {
+    return this.client.requestJson<Record<string, unknown>>(
+      `/api/v2/display-folders/${selectorValue(folder)}`,
+      { method: "DELETE" },
+    );
+  }
+
+  moveDisplay(input: MoveDisplayInput): Promise<Record<string, unknown>> {
+    return this.client.requestJson<Record<string, unknown>>(
+      "/api/v2/display-folders/displays:move",
+      jsonOptions(input, "POST"),
+    );
+  }
 }

package/src/api/document-templates.ts

@@ -0,0 +1,110 @@
+import { ApiClient } from "../client.js";
+import type { NormalizedUuidOrSlug } from "../parsers/selectors.js";
+
+export interface ApiDocumentTemplateAsset {
+  [key: string]: unknown;
+  id?: string;
+  name?: string;
+  link?: string;
+}
+
+export interface ApiDocumentTemplate {
+  [key: string]: unknown;
+  id?: string;
+  name?: string;
+  assets?: ApiDocumentTemplateAsset[];
+  createdAt?: string;
+  updatedAt?: string;
+  createdBy?: string;
+  updatedBy?: string;
+}
+
+export interface CreateDocumentTemplateInput {
+  [key: string]: unknown;
+  name: string;
+  assets?: ApiDocumentTemplateAsset[];
+}
+
+export interface UpdateDocumentTemplateInput {
+  [key: string]: unknown;
+  name?: string;
+}
+
+function jsonOptions(body: unknown, method: string): RequestInit {
+  return {
+    method,
+    headers: {
+      "content-type": "application/json",
+    },
+    body: JSON.stringify(body),
+  };
+}
+
+function selectorValue(selector: NormalizedUuidOrSlug): string {
+  return encodeURIComponent(selector.value);
+}
+
+function segment(value: string): string {
+  return encodeURIComponent(value);
+}
+
+export class DocumentTemplatesApi {
+  constructor(private readonly client: ApiClient) {}
+
+  listTemplates(): Promise<ApiDocumentTemplate[]> {
+    return this.client.getJson<ApiDocumentTemplate[]>("/api/v2/document-templates");
+  }
+
+  createTemplate(input: CreateDocumentTemplateInput): Promise<ApiDocumentTemplate> {
+    return this.client.requestJson<ApiDocumentTemplate>(
+      "/api/v2/document-templates",
+      jsonOptions(input, "POST"),
+    );
+  }
+
+  updateTemplate(
+    template: NormalizedUuidOrSlug,
+    input: UpdateDocumentTemplateInput,
+  ): Promise<ApiDocumentTemplate> {
+    return this.client.requestJson<ApiDocumentTemplate>(
+      `/api/v2/document-templates/${selectorValue(template)}`,
+      jsonOptions(input, "PATCH"),
+    );
+  }
+
+  deleteTemplate(template: NormalizedUuidOrSlug): Promise<Record<string, unknown>> {
+    return this.client.requestJson<Record<string, unknown>>(
+      `/api/v2/document-templates/${selectorValue(template)}`,
+      { method: "DELETE" },
+    );
+  }
+
+  addAsset(
+    template: NormalizedUuidOrSlug,
+    input: FormData,
+  ): Promise<ApiDocumentTemplate> {
+    return this.client.requestJson<ApiDocumentTemplate>(
+      `/api/v2/document-templates/${selectorValue(template)}/assets`,
+      { method: "POST", body: input },
+    );
+  }
+
+  deleteAsset(
+    template: NormalizedUuidOrSlug,
+    assetId: string,
+  ): Promise<Record<string, unknown>> {
+    return this.client.requestJson<Record<string, unknown>>(
+      `/api/v2/document-templates/${selectorValue(template)}/assets/${segment(assetId)}`,
+      { method: "DELETE" },
+    );
+  }
+
+  downloadAsset(
+    template: NormalizedUuidOrSlug,
+    assetId: string,
+  ): Promise<ArrayBuffer> {
+    return this.client.requestBinary(
+      `/api/v2/document-templates/${selectorValue(template)}/assets/${segment(assetId)}/download`,
+    );
+  }
+}

package/src/api/navigation.ts

@@ -16,7 +16,6 @@ export interface NavigationFolderMutation {
 
 export interface NavigationMoveResourceInput {
   resourceId: string;
-  resourceType: string;
   targetFolderId: string;
 }
 

package/src/command-registry.ts

@@ -280,6 +280,41 @@ export const commandRegistry = {
     supportsRaw: false,
     output: writeOutput,
   },
+  "displays folders list": {
+    command: "displays folders list",
+    accessLevel: "read",
+    supportsExample: true,
+    supportsRaw: false,
+    output: readOutput,
+  },
+  "displays folders create": {
+    command: "displays folders create",
+    accessLevel: "write",
+    supportsExample: true,
+    supportsRaw: false,
+    output: writeOutput,
+  },
+  "displays folders update": {
+    command: "displays folders update",
+    accessLevel: "write",
+    supportsExample: true,
+    supportsRaw: false,
+    output: writeOutput,
+  },
+  "displays folders delete": {
+    command: "displays folders delete",
+    accessLevel: "destructive",
+    supportsExample: true,
+    supportsRaw: false,
+    output: writeOutput,
+  },
+  "displays folders move": {
+    command: "displays folders move",
+    accessLevel: "write",
+    supportsExample: true,
+    supportsRaw: false,
+    output: writeOutput,
+  },
   "displays layout get": {
     command: "displays layout get",
     accessLevel: "read",
@@ -441,6 +476,62 @@ export const commandRegistry = {
     supportsRaw: false,
     output: writeOutput,
   },
+  "document-templates list": {
+    command: "document-templates list",
+    accessLevel: "read",
+    supportsExample: true,
+    supportsRaw: false,
+    output: readOutput,
+  },
+  "document-templates get": {
+    command: "document-templates get",
+    accessLevel: "read",
+    supportsExample: true,
+    supportsRaw: false,
+    output: readOutput,
+  },
+  "document-templates create": {
+    command: "document-templates create",
+    accessLevel: "write",
+    supportsExample: true,
+    supportsRaw: true,
+    output: writeOutput,
+  },
+  "document-templates update": {
+    command: "document-templates update",
+    accessLevel: "write",
+    supportsExample: true,
+    supportsRaw: false,
+    output: writeOutput,
+  },
+  "document-templates delete": {
+    command: "document-templates delete",
+    accessLevel: "destructive",
+    supportsExample: true,
+    supportsRaw: false,
+    output: writeOutput,
+  },
+  "document-templates assets add": {
+    command: "document-templates assets add",
+    accessLevel: "write",
+    supportsExample: true,
+    supportsRaw: false,
+    output: writeOutput,
+  },
+  "document-templates assets delete": {
+    command: "document-templates assets delete",
+    accessLevel: "destructive",
+    supportsExample: true,
+    supportsRaw: false,
+    output: writeOutput,
+  },
+  "document-templates assets download": {
+    command: "document-templates assets download",
+    accessLevel: "read",
+    supportsExample: true,
+    supportsRaw: false,
+    output: "binary",
+  },
   "files upload": {
     command: "files upload",
     accessLevel: "write",

package/src/commands/automations.test.ts

@@ -87,6 +87,38 @@ describe("automations commands", () => {
     expect(program.commands.some((command) => command.name() === "automations")).toBe(true);
   });
 
+  it("moves an automation with the folder id in the body, not the path", async () => {
+    const configPath = createApiConfig();
+    const output = createStdoutBuffer();
+    const fetchMock = createFetchMock();
+    fetchMock.mockResolvedValueOnce(
+      jsonResponse({ id: "folder-1", name: "Ops", isRoot: false }),
+    );
+    const program = buildAutomationsProgram({ configPath, stdout: output.stdout });
+
+    await program.parseAsync([
+      "node",
+      "zinkee",
+      "--json",
+      "automations",
+      "folders",
+      "move",
+      "11111111-1111-4111-a111-111111111111",
+      "--to",
+      "22222222-2222-4222-a222-222222222222",
+    ]);
+
+    expect(fetchMock.mock.calls[0]?.[0]).toBe(
+      "https://api.zinkee.test/api/v2/automation-folders/automations:move",
+    );
+    const init = fetchMock.mock.calls[0]?.[1];
+    expect(init?.method).toBe("POST");
+    expect(JSON.parse(String(init?.body))).toEqual({
+      automationId: "11111111-1111-4111-a111-111111111111",
+      targetFolderId: "22222222-2222-4222-a222-222222222222",
+    });
+  });
+
   it("sets trigger payloads through the generic trigger flags", async () => {
     const configPath = createApiConfig();
     const output = createStdoutBuffer();

package/src/commands/automations.ts

@@ -1408,11 +1408,13 @@ export function registerAutomationsCommands(
     .command("automations")
     .description("Manage automations, triggers, actions, and connections");
 
-  const folders = automations.command("folders").description("Manage automation folders");
+  const folders = automations
+    .command("folders")
+    .description("Manage automation folders (flat: a folder only has a name, no order or properties)");
 
   folders
     .command("list")
-    .description("List automation folders")
+    .description("List automation folders (non-root folders plus the root bucket, whose name is null)")
     .action(async function action(this: Command) {
       const { api, json } = createAutomationsApi(this, filePath);
       const data = await api.listFolders();
@@ -1500,7 +1502,11 @@ export function registerAutomationsCommands(
     .command("move")
     .description("Move an automation into a folder")
     .argument("<automation>", "automation UUID", parseUuidOrSlugSelector)
-    .requiredOption("--to <folder>", "target folder UUID or exact name", parseUuidOrSlugSelector)
+    .requiredOption(
+      "--to <folder>",
+      "target folder UUID or exact name (use the root folder to move it out of any folder)",
+      parseUuidOrSlugSelector,
+    )
     .action(async function action(
       this: Command,
       automation: NormalizedUuidOrSlug,

package/src/commands/displays.test.ts

@@ -486,4 +486,78 @@ describe("displays commands", () => {
 
     expect(fetchMock).not.toHaveBeenCalled();
   });
+
+  it("creates a display folder with just a name", async () => {
+    const configPath = createApiConfig();
+    const output = createStdoutBuffer();
+    const fetchMock = createFetchMock();
+    fetchMock.mockResolvedValueOnce(
+      jsonResponse({ id: "folder-1", name: "Executive Dashboards", isRoot: false, displayCount: 0 }),
+    );
+    const program = buildProgram({ configPath, stdout: output.stdout });
+
+    await program.parseAsync([
+      "node",
+      "zinkee",
+      "--json",
+      "displays",
+      "folders",
+      "create",
+      "--name",
+      "Executive Dashboards",
+    ]);
+
+    expect(fetchMock.mock.calls[0]?.[0]).toBe("https://api.zinkee.test/api/v2/display-folders");
+    const init = fetchMock.mock.calls[0]?.[1];
+    expect(init?.method).toBe("POST");
+    expect(JSON.parse(String(init?.body))).toEqual({ name: "Executive Dashboards" });
+  });
+
+  it("moves a display into a folder resolved by name", async () => {
+    const configPath = createApiConfig();
+    const output = createStdoutBuffer();
+    const fetchMock = createFetchMock();
+    fetchMock.mockResolvedValueOnce(
+      jsonResponse([{ id: "folder-1", name: "Executive Dashboards", isRoot: false, displayCount: 2 }]),
+    );
+    fetchMock.mockResolvedValueOnce(
+      jsonResponse({ id: "folder-1", name: "Executive Dashboards", isRoot: false }),
+    );
+    const program = buildProgram({ configPath, stdout: output.stdout });
+
+    await program.parseAsync([
+      "node",
+      "zinkee",
+      "--json",
+      "displays",
+      "folders",
+      "move",
+      "0f6f062f-1478-4df2-96a1-c495d037d260",
+      "--to",
+      "Executive Dashboards",
+    ]);
+
+    expect(fetchMock.mock.calls[0]?.[0]).toBe("https://api.zinkee.test/api/v2/display-folders");
+    expect(fetchMock.mock.calls[1]?.[0]).toBe(
+      "https://api.zinkee.test/api/v2/display-folders/displays:move",
+    );
+    const moveInit = fetchMock.mock.calls[1]?.[1];
+    expect(moveInit?.method).toBe("POST");
+    expect(JSON.parse(String(moveInit?.body))).toEqual({
+      displayId: "0f6f062f-1478-4df2-96a1-c495d037d260",
+      targetFolderId: "folder-1",
+    });
+  });
+
+  it("blocks destructive display folder commands in read-only mode", async () => {
+    const configPath = createApiConfig();
+    const fetchMock = createFetchMock();
+    const program = buildProgram({ configPath });
+
+    await expect(
+      program.parseAsync(["node", "zinkee", "--read-only", "displays", "folders", "delete", "folder-1"]),
+    ).rejects.toThrowError('Command "displays folders delete" is not allowed in read-only mode.');
+
+    expect(fetchMock).not.toHaveBeenCalled();
+  });
 });

package/src/commands/displays.ts

@@ -3,7 +3,12 @@ import type { Writable } from "node:stream";
 
 import { Command, InvalidArgumentError } from "commander";
 
-import { DisplaysApi, type DisplayResource, type DisplaySummary } from "../api/displays.js";
+import {
+  DisplaysApi,
+  type ApiDisplayFolder,
+  type DisplayResource,
+  type DisplaySummary,
+} from "../api/displays.js";
 import { ApiClient } from "../client.js";
 import { defaultConfigPath, readRuntimeConfig } from "../config.js";
 import {
@@ -308,6 +313,40 @@ function getDisplaySubresource(value: unknown): Record<string, unknown>[] {
   return value.filter((entry): entry is Record<string, unknown> => Boolean(entry) && typeof entry === "object");
 }
 
+function displayFolderRows(folders: readonly ApiDisplayFolder[]): Record<string, unknown>[] {
+  return folders.map((folder) => ({
+    id: folder.id ?? "",
+    name: folder.name ?? "",
+    isRoot: folder.isRoot ?? "",
+    displayCount: folder.displayCount ?? "",
+  }));
+}
+
+async function resolveDisplayFolderId(
+  api: DisplaysApi,
+  selector: NormalizedUuidOrSlug,
+): Promise<string> {
+  if (selector.kind === "uuid") {
+    return selector.value;
+  }
+
+  const folders = await api.listFolders();
+  const matches = folders.filter((folder) => folder.name === selector.value);
+
+  if (matches.length === 1 && typeof matches[0]?.id === "string" && matches[0].id.length > 0) {
+    return matches[0].id;
+  }
+
+  if (matches.length > 1) {
+    throw new CliError(
+      "invalid_cli_usage",
+      `Folder "${selector.value}" is ambiguous. Found ${matches.length} matches.`,
+    );
+  }
+
+  throw new CliError("invalid_cli_usage", `Folder "${selector.value}" was not found.`);
+}
+
 function buildVariableBody(options: VariableMutationOptions): Record<string, unknown> {
   const body = {
     ...readRawObject(options.raw, options.rawFile),
@@ -590,6 +629,109 @@ export function registerDisplaysCommands(
       writeLine(stdout, `Deleted display "${display.value}".`);
     });
 
+  const folders = displays
+    .command("folders")
+    .description("Manage display folders (flat: a folder only has a name, no order or properties)");
+
+  folders
+    .command("list")
+    .description("List display folders (non-root folders plus the root bucket, whose name is null)")
+    .action(async function action(this: Command) {
+      const { api, json } = createDisplaysApi(this, filePath);
+      const data = await api.listFolders();
+      if (json) {
+        emitJson(stdout, "displays folders list", data);
+        return;
+      }
+      printTable(displayFolderRows(data), ["id", "name", "isRoot", "displayCount"], stdout);
+    });
+
+  folders
+    .command("create")
+    .description("Create a display folder")
+    .requiredOption("--name <name>", "folder name")
+    .action(async function action(this: Command, commandOptions: { name?: string }) {
+      const { api, json, readOnly } = createDisplaysApi(this, filePath);
+      ensureWritable("displays folders create", readOnly, "write");
+      if (commandOptions.name === undefined) {
+        throw new CliError("invalid_cli_usage", 'Provide folder name via "--name".');
+      }
+      const data = await api.createFolder({ name: commandOptions.name });
+      if (json) {
+        emitJson(stdout, "displays folders create", data);
+        return;
+      }
+      writeLine(stdout, `Created display folder "${String(data.name ?? commandOptions.name)}".`);
+    });
+
+  folders
+    .command("update")
+    .description("Rename a display folder")
+    .argument("<folder>", "folder UUID or exact name", parseUuidOrSlugSelector)
+    .requiredOption("--name <name>", "folder name")
+    .action(async function action(
+      this: Command,
+      folder: NormalizedUuidOrSlug,
+      commandOptions: { name?: string },
+    ) {
+      const { api, json, readOnly } = createDisplaysApi(this, filePath);
+      ensureWritable("displays folders update", readOnly, "write");
+      if (commandOptions.name === undefined) {
+        throw new CliError("invalid_cli_usage", 'Provide folder name via "--name".');
+      }
+      const folderId = await resolveDisplayFolderId(api, folder);
+      const data = await api.updateFolder({ kind: "uuid", value: folderId }, { name: commandOptions.name });
+      if (json) {
+        emitJson(stdout, "displays folders update", data);
+        return;
+      }
+      writeLine(stdout, `Updated display folder "${String(data.name ?? folder.value)}".`);
+    });
+
+  folders
+    .command("delete")
+    .description("Delete a display folder (its displays move back to the root folder)")
+    .argument("<folder>", "folder UUID or exact name", parseUuidOrSlugSelector)
+    .action(async function action(this: Command, folder: NormalizedUuidOrSlug) {
+      const { api, json, readOnly } = createDisplaysApi(this, filePath);
+      ensureWritable("displays folders delete", readOnly, "destructive");
+      const folderId = await resolveDisplayFolderId(api, folder);
+      const data = await api.deleteFolder({ kind: "uuid", value: folderId });
+      if (json) {
+        emitJson(stdout, "displays folders delete", data);
+        return;
+      }
+      writeLine(stdout, `Deleted display folder "${folder.value}".`);
+    });
+
+  folders
+    .command("move")
+    .description("Move a display into a folder")
+    .argument("<display>", "display UUID", parseUuidOrSlugSelector)
+    .requiredOption(
+      "--to <folder>",
+      "target folder UUID or exact name (use the root folder to move it out of any folder)",
+      parseUuidOrSlugSelector,
+    )
+    .action(async function action(
+      this: Command,
+      display: NormalizedUuidOrSlug,
+      commandOptions: { to?: NormalizedUuidOrSlug },
+    ) {
+      const { api, json, readOnly } = createDisplaysApi(this, filePath);
+      ensureWritable("displays folders move", readOnly, "write");
+      if (!commandOptions.to) {
+        throw new CliError("invalid_cli_usage", 'Provide target folder via "--to".');
+      }
+      const targetFolderId = await resolveDisplayFolderId(api, commandOptions.to);
+      const data = await api.moveDisplay({ displayId: display.value, targetFolderId });
+      if (json) {
+        emitJson(stdout, "displays folders move", data);
+        return;
+      }
+      writeLine(stdout, `Moved display "${display.value}" to folder "${targetFolderId}".`);
+    });
+
   const layout = displays.command("layout").description("Manage display layout");
   layout
     .command("get")