zinkee 0.1.42 → 0.1.43

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zinkee",
-  "version": "0.1.42",
+  "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/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/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/schemas.test.ts

@@ -381,6 +381,48 @@ describe("schemas commands", () => {
     });
   });
 
+  it("creates fields with a description from the dedicated flag", async () => {
+    const configPath = createApiConfig();
+    const output = createStdoutBuffer();
+    const fetchMock = createFetchMock();
+    mockSchemaLookup(fetchMock);
+    fetchMock.mockResolvedValueOnce(
+      jsonResponse({
+        id: "field-1",
+        type: "TextField",
+        slug: "email",
+        label: "Email",
+        description: "Primary contact email",
+      }),
+    );
+    const program = buildProgram({ configPath, stdout: output.stdout });
+
+    await program.parseAsync([
+      "node",
+      "zinkee",
+      "--json",
+      "schemas",
+      "fields",
+      "create",
+      "contacts",
+      "--type",
+      "text",
+      "--slug",
+      "email",
+      "--label",
+      "Email",
+      "--description",
+      "Primary contact email",
+    ]);
+
+    expect(JSON.parse(String(fetchMock.mock.calls[1]?.[1]?.body))).toEqual({
+      type: "TextField",
+      slug: "email",
+      label: "Email",
+      description: "Primary contact email",
+    });
+  });
+
   it("creates fields with a default value flag", async () => {
     const configPath = createApiConfig();
     const output = createStdoutBuffer();
@@ -589,6 +631,53 @@ describe("schemas commands", () => {
     });
   });
 
+  it.each([
+    ["sets", "Shown in customer notifications"],
+    ["clears", ""],
+  ])("%s a field description without another metadata change", async (_action, description) => {
+    const configPath = createApiConfig();
+    const output = createStdoutBuffer();
+    const fetchMock = createFetchMock();
+    mockSchemaLookup(fetchMock);
+    fetchMock.mockResolvedValueOnce(
+      jsonResponse({
+        id: "550e8400-e29b-41d4-a716-446655440003",
+        type: "TextField",
+        slug: "notes",
+        label: "Notes",
+        required: false,
+      }),
+    );
+    fetchMock.mockResolvedValueOnce(
+      jsonResponse({
+        id: "550e8400-e29b-41d4-a716-446655440003",
+        type: "TextField",
+        slug: "notes",
+        label: "Notes",
+        description,
+      }),
+    );
+    const program = buildProgram({ configPath, stdout: output.stdout });
+
+    await program.parseAsync([
+      "node",
+      "zinkee",
+      "--json",
+      "schemas",
+      "fields",
+      "update",
+      "contacts",
+      "550E8400-E29B-41D4-A716-446655440003",
+      "--description",
+      description,
+    ]);
+
+    expect(JSON.parse(String(fetchMock.mock.calls[2]?.[1]?.body))).toEqual({
+      type: "TextField",
+      description,
+    });
+  });
+
   it("strips formula status from update payloads", async () => {
     const configPath = createApiConfig();
     const output = createStdoutBuffer();

package/src/commands/schemas.ts

@@ -78,6 +78,7 @@ interface FieldCreateCommandOptions {
   type?: string;
   slug?: string;
   label?: string;
+  description?: string;
   required?: boolean;
   default?: string;
   raw?: string;
@@ -86,6 +87,7 @@ interface FieldCreateCommandOptions {
 
 interface FieldUpdateCommandOptions {
   label?: string;
+  description?: string;
   required?: boolean;
   default?: string;
   raw?: string;
@@ -386,6 +388,10 @@ function buildFieldCreateInput(
     input.required = options.required;
   }
 
+  if (options.description !== undefined) {
+    input.description = options.description;
+  }
+
   applyFieldDefaultValue(input, options.default);
 
   if ("config" in input && isJsonObject(input.config) && isEmptyObject(input.config)) {
@@ -462,6 +468,10 @@ function buildFieldUpdateInput(
     input.required = options.required;
   }
 
+  if (options.description !== undefined) {
+    input.description = options.description;
+  }
+
   applyFieldDefaultValue(input, options.default);
 
   return input;
@@ -769,6 +779,7 @@ export function registerSchemasCommands(
     .option("--type <type>", `field type (${formatSchemaFieldTypes()})`)
     .option("--slug <slug>", "field slug")
     .option("--label <label>", "field label")
+    .option("--description <text>", "field description")
     .option("--required <bool>", "required flag", parseBooleanFlag)
     .option("--default <value>", "default field value")
     .option("--raw <json>", 'raw JSON object payload (see type-specific shapes in --help)')
@@ -803,6 +814,7 @@ export function registerSchemasCommands(
     .argument("<schema>", "schema uuid or slug", parseUuidOrSlugSelector)
     .argument("<field>", "field uuid or slug", parseUuidOrSlugSelector)
     .option("--label <label>", "field label")
+    .option("--description <text>", 'field description (use "" to clear)')
     .option("--required <bool>", "required flag", parseBooleanFlag)
     .option("--default <value>", "default field value")
     .option("--raw <json>", "raw JSON object payload")
@@ -832,7 +844,7 @@ export function registerSchemasCommands(
       if (isEmptyObject(input)) {
         throw new CliError(
           "invalid_cli_usage",
-          'Provide at least one field update via "--label", "--required", "--raw", or "--raw-file".',
+          'Provide at least one field update via "--label", "--description", "--required", "--default", "--raw", or "--raw-file".',
         );
       }
 

package/src/utils/examples.ts

@@ -404,6 +404,22 @@ const specificExamples: Record<string, readonly CommandExample[]> = {
     },
   ]),
   "schemas fields update": buildCommandExamples([
+    {
+      description: "Set the field description without changing its label or configuration.",
+      command:
+        'zinkee --json schemas fields update contacts contact-name --description "Primary name shown for the customer"',
+      raw: `{
+  "description": "Primary name shown for the customer"
+}`,
+    },
+    {
+      description: "Clear the field description.",
+      command:
+        'zinkee --json schemas fields update contacts contact-name --description ""',
+      raw: `{
+  "description": ""
+}`,
+    },
     {
       description: "Rename slug and label.",
       command:
@@ -1229,11 +1245,12 @@ const specificExamples: Record<string, readonly CommandExample[]> = {
   "displays create": buildCommandExamples([
     {
       description:
-        "Create a freeform display with an initial widget layout. Freeform layouts travel through --freeform-layouts.",
+        "Create a described freeform display with an initial widget layout. Freeform layouts travel through --freeform-layouts.",
       command:
-        `zinkee --json displays create --name "Control Proyecto Freeform" --template freeform --freeform-layouts '{"lg":[{"i":"widget-1","x":0,"y":0,"w":6,"h":5}]}'`,
+        `zinkee --json displays create --name "Control Proyecto Freeform" --description "Project delivery overview" --template freeform --freeform-layouts '{"lg":[{"i":"widget-1","x":0,"y":0,"w":6,"h":5}]}'`,
       raw: `{
   "name": "Control Proyecto Freeform",
+  "description": "Project delivery overview",
   "layout": {
     "template": "freeform",
     "freeformLayouts": {
@@ -3135,6 +3152,22 @@ const specificExamples: Record<string, readonly CommandExample[]> = {
     },
   ]),
   "displays update": buildCommandExamples([
+    {
+      description: "Update only the display description.",
+      command:
+        'zinkee --json displays update 0f6f062f-1478-4df2-96a1-c495d037d260 --description "Sales pipeline overview"',
+      raw: `{
+  "description": "Sales pipeline overview"
+}`,
+    },
+    {
+      description: "Clear the display description.",
+      command:
+        'zinkee --json displays update 0f6f062f-1478-4df2-96a1-c495d037d260 --description ""',
+      raw: `{
+  "description": ""
+}`,
+    },
     {
       description: "Rename a display (patch of top-level metadata only).",
       command:
@@ -4517,8 +4550,26 @@ function buildSchemaFieldCreateExamples(type?: string): readonly CommandExample[
     definition.examplePayloads.map((example) => ({ definition, example })),
   );
 
-  return buildCommandExamples(
-    flat.map(({ example }, index) => {
+  const flagExamples: CommandExample[] =
+    selectedDefinition === undefined || selectedDefinition.key === "text"
+      ? [
+          {
+            description: "Text field with a description.",
+            command:
+              'zinkee --json schemas fields create contacts --type text --slug customer-name --label "Customer Name" --description "Primary name shown for the customer"',
+            raw: `{
+  "type": "TextField",
+  "slug": "customer-name",
+  "label": "Customer Name",
+  "description": "Primary name shown for the customer"
+}`,
+          },
+        ]
+      : [];
+
+  return buildCommandExamples([
+    ...flagExamples,
+    ...flat.map(({ example }, index) => {
       const slug =
         typeof example.payload.slug === "string" ? example.payload.slug : "field";
       const command = `zinkee --json schemas fields create contacts --raw '${JSON.stringify(example.payload)}'`;
@@ -4540,7 +4591,7 @@ function buildSchemaFieldCreateExamples(type?: string): readonly CommandExample[
         command,
       };
     }),
-  );
+  ]);
 }
 
 export function getCommandExamples(