zinkee 0.1.30 → 0.1.32

package/package.json

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

package/src/api/schemas.ts

@@ -19,6 +19,7 @@ export interface ApiSchema {
   commentable?: boolean;
   highlightedField?: string;
   fields?: ApiSchemaField[];
+  uniqueFields?: string[];
 }
 
 export interface CreateSchemaInput {
@@ -36,6 +37,10 @@ export interface UpdateSchemaInput {
   highlightedField?: string;
 }
 
+export interface SetUniqueFieldsInput {
+  fieldIds: string[];
+}
+
 export interface CreateSchemaFieldInput {
   [key: string]: unknown;
   type: string;
@@ -86,6 +91,13 @@ export class SchemasApi {
     );
   }
 
+  setUniqueFields(schema: NormalizedUuidOrSlug, input: SetUniqueFieldsInput): Promise<ApiSchema> {
+    return this.client.requestJson<ApiSchema>(
+      `/api/v2/schemas/${selectorValue(schema)}/unique-fields`,
+      jsonOptions(input, "PUT"),
+    );
+  }
+
   deleteSchema(schema: NormalizedUuidOrSlug): Promise<Record<string, unknown>> {
     return this.client.requestJson<Record<string, unknown>>(
       `/api/v2/schemas/${selectorValue(schema)}`,

package/src/command-registry.ts

@@ -672,6 +672,13 @@ export const commandRegistry = {
     supportsRaw: false,
     output: writeOutput,
   },
+  "schemas set-unique-fields": {
+    command: "schemas set-unique-fields",
+    accessLevel: "write",
+    supportsExample: true,
+    supportsRaw: false,
+    output: writeOutput,
+  },
   "schemas delete": {
     command: "schemas delete",
     accessLevel: "destructive",

package/src/commands/schemas.test.ts

@@ -213,6 +213,118 @@ describe("schemas commands", () => {
     expect(fetchMock).not.toHaveBeenCalled();
   });
 
+  it("sets unique fields through PUT /unique-fields with the expected body", async () => {
+    const configPath = createApiConfig();
+    const output = createStdoutBuffer();
+    const fetchMock = createFetchMock();
+    fetchMock.mockResolvedValueOnce(
+      jsonResponse({
+        id: "2eb8bdcf-6d9c-4fbb-9018-7fa8180f4c5e",
+        uniqueFields: [
+          "c60b8526-5835-4c9f-aecd-9a16c7704a34",
+          "1d2e3f4a-5b6c-7d8e-9f01-23456789abcd",
+        ],
+      }),
+    );
+    const program = buildProgram({ configPath, stdout: output.stdout });
+
+    await program.parseAsync([
+      "node",
+      "zinkee",
+      "--json",
+      "schemas",
+      "set-unique-fields",
+      "2eb8bdcf-6d9c-4fbb-9018-7fa8180f4c5e",
+      "--field",
+      "c60b8526-5835-4c9f-aecd-9a16c7704a34",
+      "--field",
+      "1d2e3f4a-5b6c-7d8e-9f01-23456789abcd",
+    ]);
+
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+    expect(fetchMock.mock.calls[0]?.[0]).toBe(
+      "https://api.zinkee.test/api/v2/schemas/2eb8bdcf-6d9c-4fbb-9018-7fa8180f4c5e/unique-fields",
+    );
+
+    const init = fetchMock.mock.calls[0]?.[1];
+    expect(init?.method).toBe("PUT");
+    expect(new Headers(init?.headers).get("content-type")).toBe("application/json");
+    expect(JSON.parse(String(init?.body))).toEqual({
+      fieldIds: [
+        "c60b8526-5835-4c9f-aecd-9a16c7704a34",
+        "1d2e3f4a-5b6c-7d8e-9f01-23456789abcd",
+      ],
+    });
+  });
+
+  it("clears the unique constraint with --clear", async () => {
+    const configPath = createApiConfig();
+    const output = createStdoutBuffer();
+    const fetchMock = createFetchMock();
+    fetchMock.mockResolvedValueOnce(
+      jsonResponse({ id: "550e8400-e29b-41d4-a716-446655440000", uniqueFields: [] }),
+    );
+    const program = buildProgram({ configPath, stdout: output.stdout });
+
+    await program.parseAsync([
+      "node",
+      "zinkee",
+      "--json",
+      "schemas",
+      "set-unique-fields",
+      "550e8400-e29b-41d4-a716-446655440000",
+      "--clear",
+    ]);
+
+    const init = fetchMock.mock.calls[0]?.[1];
+    expect(init?.method).toBe("PUT");
+    expect(JSON.parse(String(init?.body))).toEqual({ fieldIds: [] });
+  });
+
+  it("rejects set-unique-fields without fields or --clear", async () => {
+    const configPath = createApiConfig();
+    const output = createStdoutBuffer();
+    const fetchMock = createFetchMock();
+    const program = buildProgram({ configPath, stdout: output.stdout });
+
+    await expect(
+      program.parseAsync([
+        "node",
+        "zinkee",
+        "schemas",
+        "set-unique-fields",
+        "550e8400-e29b-41d4-a716-446655440000",
+      ]),
+    ).rejects.toThrowError(
+      'Provide at least one field via "--field", or pass "--clear" to remove the unique constraint.',
+    );
+
+    expect(fetchMock).not.toHaveBeenCalled();
+  });
+
+  it("blocks set-unique-fields in read-only mode", async () => {
+    const configPath = createApiConfig();
+    const output = createStdoutBuffer();
+    const fetchMock = createFetchMock();
+    const program = buildProgram({ configPath, stdout: output.stdout });
+
+    await expect(
+      program.parseAsync([
+        "node",
+        "zinkee",
+        "--read-only",
+        "schemas",
+        "set-unique-fields",
+        "550e8400-e29b-41d4-a716-446655440000",
+        "--clear",
+      ]),
+    ).rejects.toThrowError(
+      'Command "schemas set-unique-fields" is not allowed in read-only mode.',
+    );
+
+    expect(fetchMock).not.toHaveBeenCalled();
+  });
+
   it("creates fields by merging raw JSON with explicit flags", async () => {
     const configPath = createApiConfig();
     const output = createStdoutBuffer();

package/src/commands/schemas.ts

@@ -9,11 +9,11 @@ import {
   type ApiSchemaField,
   type CreateSchemaFieldInput,
   type CreateSchemaInput,
+  type SetUniqueFieldsInput,
   type UpdateSchemaFieldInput,
   type UpdateSchemaInput,
 } from "../api/schemas.js";
-import { ApiClientError } from "../client.js";
-import { ApiClient } from "../client.js";
+import { ApiClientError, ApiClient } from "../client.js";
 import { defaultConfigPath, readRuntimeConfig } from "../config.js";
 import {
   normalizeUuidOrSlug,
@@ -59,6 +59,21 @@ interface SchemaUpdateCommandOptions {
   highlightedField?: NormalizedUuidOrSlug;
 }
 
+interface SetUniqueFieldsCommandOptions {
+  field?: NormalizedUuidOrSlug[];
+  clear?: boolean;
+}
+
+const HIGHLIGHTED_FIELD_HELP = `
+Highlighted field:
+  The schema's "main" field. The frontend uses its value as each record's
+  display name, in two places:
+    - Activity panel: the record's title in the activity side panel
+      (the panel with the record's logs and comments).
+    - Detail view: the record's name in the left-hand record list you
+      browse to open each record's form.
+`;
+
 interface FieldCreateCommandOptions {
   type?: string;
   slug?: string;
@@ -179,6 +194,13 @@ function parseUuidOrSlugSelector(input: string): NormalizedUuidOrSlug {
   }
 }
 
+function collectFieldSelectors(
+  value: string,
+  previous: NormalizedUuidOrSlug[] = [],
+): NormalizedUuidOrSlug[] {
+  return [...previous, parseUuidOrSlugSelector(value)];
+}
+
 function parseBooleanFlag(input: string): boolean {
   const normalized = input.trim().toLowerCase();
 
@@ -571,7 +593,7 @@ export function registerSchemasCommands(
     .option("--commentable <bool>", "commentable flag", parseBooleanFlag)
     .option(
       "--highlighted-field <field>",
-      "highlighted (main) field uuid or slug",
+      "its value is used as each record's display name in the UI (field uuid or slug)",
       parseUuidOrSlugSelector,
     )
     .action(async function action(
@@ -609,6 +631,69 @@ export function registerSchemasCommands(
       }
 
       writeLine(stdout, `Updated schema "${data.slug ?? schema.value}".`);
+    })
+    .addHelpText("after", HIGHLIGHTED_FIELD_HELP);
+
+  schemas
+    .command("set-unique-fields")
+    .description("Set or clear the composite unique-field constraint on a schema")
+    .argument("<schema>", "schema uuid or slug", parseUuidOrSlugSelector)
+    .option(
+      "--field <field>",
+      "field uuid or slug to include in the unique constraint (repeatable)",
+      collectFieldSelectors,
+      [],
+    )
+    .option("--clear", "clear the unique constraint (sends an empty field list)")
+    .action(async function action(
+      this: Command,
+      schema: NormalizedUuidOrSlug,
+      commandOptions: SetUniqueFieldsCommandOptions,
+    ) {
+      const { api, json, readOnly } = createSchemasApi(this, filePath);
+      ensureWritable("schemas set-unique-fields", readOnly, "write");
+
+      const selectors = commandOptions.field ?? [];
+
+      if (commandOptions.clear && selectors.length > 0) {
+        throw new CliError(
+          "invalid_cli_usage",
+          'Use either "--field" or "--clear", not both.',
+        );
+      }
+
+      if (!commandOptions.clear && selectors.length === 0) {
+        throw new CliError(
+          "invalid_cli_usage",
+          'Provide at least one field via "--field", or pass "--clear" to remove the unique constraint.',
+        );
+      }
+
+      const resolvedSchema = await resolveSchemaSelector(api, schema);
+      const resolvedFields = await Promise.all(
+        selectors.map((selector) => resolveFieldSelector(api, resolvedSchema, selector)),
+      );
+      const input: SetUniqueFieldsInput = {
+        fieldIds: resolvedFields.map((field) => field.value),
+      };
+
+      const data = await api.setUniqueFields(resolvedSchema, input);
+
+      if (json) {
+        emitJson(stdout, "schemas set-unique-fields", data, filePath);
+        return;
+      }
+
+      if (input.fieldIds.length === 0) {
+        writeLine(stdout, `Cleared unique fields on schema "${schema.value}".`);
+        return;
+      }
+
+      const count = input.fieldIds.length;
+      writeLine(
+        stdout,
+        `Set unique fields on schema "${schema.value}" (${count} field${count === 1 ? "" : "s"}).`,
+      );
     });
 
   schemas

package/src/utils/examples.ts

@@ -243,7 +243,8 @@ const specificExamples: Record<string, readonly CommandExample[]> = {
         "conditionalFormatting": []
       }
     }
-  ]
+  ],
+  "uniqueFields": []
 }`,
     },
     {
@@ -263,11 +264,87 @@ const specificExamples: Record<string, readonly CommandExample[]> = {
 }`,
     },
     {
-      description: "Set the highlighted (main) field of a schema.",
+      description:
+        "Set the schema's highlighted (main) field — the field whose value names each record in the UI (activity-panel title and detail-view record list).",
       command:
         'zinkee --json schemas update contacts --highlighted-field contact-name',
       raw: `{
   "highlightedField": "c60b8526-5835-4c9f-aecd-9a16c7704a34"
+}`,
+    },
+  ]),
+  "schemas set-unique-fields": buildCommandExamples([
+    {
+      description:
+        "Set a composite unique constraint: the listed fields must be unique together across records.",
+      command:
+        "zinkee --json schemas set-unique-fields contacts --field contact-name --field notes",
+      raw: `{
+  "fieldIds": [
+    "c60b8526-5835-4c9f-aecd-9a16c7704a34",
+    "1d2e3f4a-5b6c-7d8e-9f01-23456789abcd"
+  ]
+}`,
+      response: `{
+  "id": "2eb8bdcf-6d9c-4fbb-9018-7fa8180f4c5e",
+  "name": "Contacts",
+  "slug": "contacts",
+  "folder": {
+    "id": "7f4e7c25-d8b2-4c1a-9f3e-6a7b5c8d9e1f",
+    "name": "Customers",
+    "isRoot": false
+  },
+  "auditable": true,
+  "commentable": true,
+  "highlightedField": "c60b8526-5835-4c9f-aecd-9a16c7704a34",
+  "fields": [
+    {
+      "id": "c60b8526-5835-4c9f-aecd-9a16c7704a34",
+      "type": "TextField",
+      "slug": "contact-name",
+      "label": "Customer Name",
+      "required": true,
+      "system": false,
+      "config": {
+        "textType": "NORMAL",
+        "defaultValue": "Unknown",
+        "conditionalFormatting": []
+      }
+    },
+    {
+      "id": "1d2e3f4a-5b6c-7d8e-9f01-23456789abcd",
+      "type": "TextField",
+      "slug": "notes",
+      "label": "Notes",
+      "required": false,
+      "system": false,
+      "config": {
+        "textType": "LONG",
+        "defaultValue": null,
+        "conditionalFormatting": []
+      }
+    }
+  ],
+  "uniqueFields": [
+    "c60b8526-5835-4c9f-aecd-9a16c7704a34",
+    "1d2e3f4a-5b6c-7d8e-9f01-23456789abcd"
+  ]
+}`,
+    },
+    {
+      description: "Set a single-field unique constraint.",
+      command: "zinkee --json schemas set-unique-fields contacts --field contact-name",
+      raw: `{
+  "fieldIds": [
+    "c60b8526-5835-4c9f-aecd-9a16c7704a34"
+  ]
+}`,
+    },
+    {
+      description: "Clear the unique constraint (no field must be unique anymore).",
+      command: "zinkee --json schemas set-unique-fields contacts --clear",
+      raw: `{
+  "fieldIds": []
 }`,
     },
   ]),
@@ -2222,6 +2299,10 @@ const specificExamples: Record<string, readonly CommandExample[]> = {
         "conditionalFormatting": []
       }
     }
+  ],
+  "uniqueFields": [
+    "c60b8526-5835-4c9f-aecd-9a16c7704a34",
+    "1d2e3f4a-5b6c-7d8e-9f01-23456789abcd"
   ]
 }`,
     },