zinkee 0.1.29 → 0.1.31

package/package.json

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

package/src/api/schemas.ts

@@ -17,7 +17,9 @@ export interface ApiSchema {
   slug?: string;
   auditable?: boolean;
   commentable?: boolean;
+  highlightedField?: string;
   fields?: ApiSchemaField[];
+  uniqueFields?: string[];
 }
 
 export interface CreateSchemaInput {
@@ -32,6 +34,11 @@ export interface UpdateSchemaInput {
   slug?: string;
   auditable?: boolean;
   commentable?: boolean;
+  highlightedField?: string;
+}
+
+export interface SetUniqueFieldsInput {
+  fieldIds: string[];
 }
 
 export interface CreateSchemaFieldInput {
@@ -84,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();
@@ -968,4 +1080,84 @@ describe("schemas commands", () => {
       },
     });
   });
+
+  it("updates a schema highlighted field by slug after resolving the field id", async () => {
+    const configPath = createApiConfig();
+    const output = createStdoutBuffer();
+    const fetchMock = createFetchMock();
+    mockSchemaLookup(fetchMock);
+    fetchMock.mockResolvedValueOnce(
+      jsonResponse({
+        id: "schema-1",
+        slug: "contacts",
+        fields: [
+          {
+            id: "550e8400-e29b-41d4-a716-446655440001",
+            slug: "email",
+            type: "TextField",
+            label: "Email",
+          },
+        ],
+      }),
+    );
+    fetchMock.mockResolvedValueOnce(
+      jsonResponse({
+        id: "schema-1",
+        slug: "contacts",
+        highlightedField: "550e8400-e29b-41d4-a716-446655440001",
+      }),
+    );
+    const program = buildProgram({ configPath, stdout: output.stdout });
+
+    await program.parseAsync([
+      "node",
+      "zinkee",
+      "--json",
+      "schemas",
+      "update",
+      "contacts",
+      "--highlighted-field",
+      "email",
+    ]);
+
+    expect(fetchMock.mock.calls[2]?.[0]).toBe("https://api.zinkee.test/api/v2/schemas/schema-1");
+    expect(fetchMock.mock.calls[2]?.[1]?.method).toBe("PATCH");
+    expect(JSON.parse(String(fetchMock.mock.calls[2]?.[1]?.body))).toEqual({
+      highlightedField: "550e8400-e29b-41d4-a716-446655440001",
+    });
+  });
+
+  it("updates a schema highlighted field by uuid without extra lookups", async () => {
+    const configPath = createApiConfig();
+    const output = createStdoutBuffer();
+    const fetchMock = createFetchMock();
+    fetchMock.mockResolvedValueOnce(
+      jsonResponse({
+        id: "550e8400-e29b-41d4-a716-446655440000",
+        slug: "contacts",
+        highlightedField: "550e8400-e29b-41d4-a716-446655440001",
+      }),
+    );
+    const program = buildProgram({ configPath, stdout: output.stdout });
+
+    await program.parseAsync([
+      "node",
+      "zinkee",
+      "--json",
+      "schemas",
+      "update",
+      "550e8400-e29b-41d4-a716-446655440000",
+      "--highlighted-field",
+      "550e8400-e29b-41d4-a716-446655440001",
+    ]);
+
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+    expect(fetchMock.mock.calls[0]?.[0]).toBe(
+      "https://api.zinkee.test/api/v2/schemas/550e8400-e29b-41d4-a716-446655440000",
+    );
+    expect(fetchMock.mock.calls[0]?.[1]?.method).toBe("PATCH");
+    expect(JSON.parse(String(fetchMock.mock.calls[0]?.[1]?.body))).toEqual({
+      highlightedField: "550e8400-e29b-41d4-a716-446655440001",
+    });
+  });
 });

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,
@@ -56,6 +56,12 @@ interface SchemaUpdateCommandOptions {
   slug?: string;
   auditable?: boolean;
   commentable?: boolean;
+  highlightedField?: NormalizedUuidOrSlug;
+}
+
+interface SetUniqueFieldsCommandOptions {
+  field?: NormalizedUuidOrSlug[];
+  clear?: boolean;
 }
 
 interface FieldCreateCommandOptions {
@@ -178,6 +184,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();
 
@@ -568,6 +581,11 @@ export function registerSchemasCommands(
     .option("--slug <slug>", "schema slug")
     .option("--auditable <bool>", "auditable flag", parseBooleanFlag)
     .option("--commentable <bool>", "commentable flag", parseBooleanFlag)
+    .option(
+      "--highlighted-field <field>",
+      "highlighted (main) field uuid or slug",
+      parseUuidOrSlugSelector,
+    )
     .action(async function action(
       this: Command,
       schema: NormalizedUuidOrSlug,
@@ -579,10 +597,19 @@ export function registerSchemasCommands(
 
       const input = buildSchemaUpdateInput(commandOptions);
 
+      if (commandOptions.highlightedField !== undefined) {
+        const resolvedField = await resolveFieldSelector(
+          api,
+          resolvedSchema,
+          commandOptions.highlightedField,
+        );
+        input.highlightedField = resolvedField.value;
+      }
+
       if (isEmptyObject(input)) {
         throw new CliError(
           "invalid_cli_usage",
-          'Provide at least one schema field to update via "--name", "--slug", "--auditable", or "--commentable".',
+          'Provide at least one schema field to update via "--name", "--slug", "--auditable", "--commentable", or "--highlighted-field".',
         );
       }
 
@@ -596,6 +623,68 @@ export function registerSchemasCommands(
       writeLine(stdout, `Updated schema "${data.slug ?? schema.value}".`);
     });
 
+  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
     .command("delete")
     .description("Delete a schema")

package/src/utils/examples.ts

@@ -228,6 +228,7 @@ const specificExamples: Record<string, readonly CommandExample[]> = {
   },
   "auditable": true,
   "commentable": true,
+  "highlightedField": "c60b8526-5835-4c9f-aecd-9a16c7704a34",
   "fields": [
     {
       "id": "c60b8526-5835-4c9f-aecd-9a16c7704a34",
@@ -242,7 +243,8 @@ const specificExamples: Record<string, readonly CommandExample[]> = {
         "conditionalFormatting": []
       }
     }
-  ]
+  ],
+  "uniqueFields": []
 }`,
     },
     {
@@ -259,6 +261,89 @@ const specificExamples: Record<string, readonly CommandExample[]> = {
       command: 'zinkee --json schemas update contacts --auditable true',
       raw: `{
   "auditable": true
+}`,
+    },
+    {
+      description: "Set the highlighted (main) field of a schema.",
+      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": []
 }`,
     },
   ]),
@@ -1904,6 +1989,7 @@ const specificExamples: Record<string, readonly CommandExample[]> = {
   },
   "auditable": true,
   "commentable": true,
+  "highlightedField": "c60b8526-5835-4c9f-aecd-9a16c7704a34",
   "fields": [
     {
       "id": "c60b8526-5835-4c9f-aecd-9a16c7704a34",
@@ -2212,6 +2298,10 @@ const specificExamples: Record<string, readonly CommandExample[]> = {
         "conditionalFormatting": []
       }
     }
+  ],
+  "uniqueFields": [
+    "c60b8526-5835-4c9f-aecd-9a16c7704a34",
+    "1d2e3f4a-5b6c-7d8e-9f01-23456789abcd"
   ]
 }`,
     },