zinkee 0.1.30 → 0.1.32

package/README.md

@@ -248,6 +248,30 @@ date_format(44b72f55-3fc3-40f4-88bb-343bb4a6270c, "AAAA-MM")
 - Functions: `concat`, `if`, `date_format`, `datetime_diff`, arithmetic (`+`,`-`,`*`,`/`)
 - Invalid formulas are created with status `DRAFT` and evaluate to `null`
 
+### Set unique fields
+
+Define a composite unique constraint: the listed fields must be unique **together**
+across the schema's records. `--field` accepts a field UUID or slug and is repeatable;
+the order you pass them is the order of the constraint.
+
+```bash
+# Single field must be unique
+zinkee schemas set-unique-fields contacts --field email
+
+# Composite: the (contact-name, notes) combination must be unique
+zinkee schemas set-unique-fields contacts --field contact-name --field notes
+
+# Remove the unique constraint
+zinkee schemas set-unique-fields contacts --clear
+```
+
+Notes:
+
+- Pass either one or more `--field`, or `--clear` — not both, and not neither.
+- Every `--field` must already exist in the schema, otherwise the command fails.
+- If existing records already violate the requested constraint, the backend rejects
+  it with `409 Conflict`.
+
 ---
 
 ## Records

package/dist/index.js

@@ -667,6 +667,13 @@ var 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",
@@ -2417,7 +2424,8 @@ var specificExamples = {
         "conditionalFormatting": []
       }
     }
-  ]
+  ],
+  "uniqueFields": []
 }`
     },
     {
@@ -2436,10 +2444,83 @@ var specificExamples = {
 }`
     },
     {
-      description: "Set the highlighted (main) field of a schema.",
+      description: "Set the schema's highlighted (main) field \u2014 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": []
 }`
     }
   ]),
@@ -4290,6 +4371,10 @@ var specificExamples = {
         "conditionalFormatting": []
       }
     }
+  ],
+  "uniqueFields": [
+    "c60b8526-5835-4c9f-aecd-9a16c7704a34",
+    "1d2e3f4a-5b6c-7d8e-9f01-23456789abcd"
   ]
 }`
     }
@@ -10720,6 +10805,12 @@ var SchemasApi = class {
       jsonOptions7(input, "PATCH")
     );
   }
+  setUniqueFields(schema, input) {
+    return this.client.requestJson(
+      `/api/v2/schemas/${selectorValue9(schema)}/unique-fields`,
+      jsonOptions7(input, "PUT")
+    );
+  }
   deleteSchema(schema) {
     return this.client.requestJson(
       `/api/v2/schemas/${selectorValue9(schema)}`,
@@ -11175,6 +11266,15 @@ function registerRecordsCommands(program, options = {}) {
 // src/commands/schemas.ts
 import { readFileSync as readFileSync9 } from "fs";
 import { InvalidArgumentError as InvalidArgumentError9 } from "commander";
+var 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.
+`;
 function getCommandIo11(stdout) {
   return stdout ?? process.stdout;
 }
@@ -11248,6 +11348,9 @@ function parseUuidOrSlugSelector9(input) {
     throw new InvalidArgumentError9(message);
   }
 }
+function collectFieldSelectors(value, previous = []) {
+  return [...previous, parseUuidOrSlugSelector9(value)];
+}
 function parseBooleanFlag(input) {
   const normalized = input.trim().toLowerCase();
   if (["true", "1", "yes", "y", "on"].includes(normalized)) {
@@ -11509,7 +11612,7 @@ function registerSchemasCommands(program, options = {}) {
   });
   schemas.command("update").description("Update a schema").argument("<schema>", "schema uuid or slug", parseUuidOrSlugSelector9).option("--name <name>", "schema name").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",
+    "its value is used as each record's display name in the UI (field uuid or slug)",
     parseUuidOrSlugSelector9
   ).action(async function action(schema, commandOptions) {
     const { api, json, readOnly } = createSchemasApi(this, filePath);
@@ -11536,6 +11639,49 @@ function registerSchemasCommands(program, options = {}) {
       return;
     }
     writeLine11(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", parseUuidOrSlugSelector9).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(schema, commandOptions) {
+    const { api, json, readOnly } = createSchemasApi(this, filePath);
+    ensureWritable8("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 resolveSchemaSelector2(api, schema);
+    const resolvedFields = await Promise.all(
+      selectors.map((selector) => resolveFieldSelector(api, resolvedSchema, selector))
+    );
+    const input = {
+      fieldIds: resolvedFields.map((field) => field.value)
+    };
+    const data = await api.setUniqueFields(resolvedSchema, input);
+    if (json) {
+      emitJson11(stdout, "schemas set-unique-fields", data, filePath);
+      return;
+    }
+    if (input.fieldIds.length === 0) {
+      writeLine11(stdout, `Cleared unique fields on schema "${schema.value}".`);
+      return;
+    }
+    const count = input.fieldIds.length;
+    writeLine11(
+      stdout,
+      `Set unique fields on schema "${schema.value}" (${count} field${count === 1 ? "" : "s"}).`
+    );
   });
   schemas.command("delete").description("Delete a schema").argument("<schema>", "schema uuid or slug", parseUuidOrSlugSelector9).action(async function action(schema) {
     const { api, json, readOnly } = createSchemasApi(this, filePath);