zinkee 0.1.34 → 0.1.35

package/package.json

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

package/src/commands/records.ts

@@ -750,7 +750,12 @@ export function registerRecordsCommands(
     .command("create")
     .description("Create one or more records")
     .argument("<schema>", "schema uuid or slug", parseUuidOrSlugSelector)
-    .option("--set <field=value>", "set a string field", collectKeyValueAssignments, [])
+    .option(
+      "--set <field=value>",
+      "set a string field (reference fields: a record id, 'recordId::label', or an exact display value)",
+      collectKeyValueAssignments,
+      [],
+    )
     .option("--set-json <field=json>", "set a structured field", collectJsonAssignments, [])
     .option("--raw <json>", "raw JSON object payload")
     .option("--raw-file <path>", "path to a raw JSON object payload")
@@ -790,7 +795,12 @@ export function registerRecordsCommands(
     .description("Update a record")
     .argument("<schema>", "schema uuid or slug", parseUuidOrSlugSelector)
     .argument("<record>", "record uuid or slug", parseUuidOrSlugSelector)
-    .option("--set <field=value>", "set a string field", collectKeyValueAssignments, [])
+    .option(
+      "--set <field=value>",
+      "set a string field (reference fields: a record id, 'recordId::label', or an exact display value)",
+      collectKeyValueAssignments,
+      [],
+    )
     .option("--set-json <field=json>", "set a structured field", collectJsonAssignments, [])
     .option("--unset <field>", "unset a field", collectStringValues, [])
     .option("--raw <json>", "raw JSON object of fields to set")

package/src/utils/examples.test.ts

@@ -177,13 +177,15 @@ describe("getCommandExamples", () => {
     }
   });
 
-  it("offers both a minimal and a multi-type records create example", () => {
+  it("offers minimal, multi-type, and reference records create examples", () => {
     const examples = getCommandExamples("records create");
 
-    expect(examples).toHaveLength(2);
+    expect(examples).toHaveLength(3);
     expect(examples[0]?.raw).toContain('"contact-name"');
     expect(examples[1]?.raw).toContain('"customer-ref"');
     expect(examples[1]?.raw).toContain('"owner"');
+    expect(examples[2]?.raw).toContain('"customer-ref"');
+    expect(examples[2]?.response).toContain("data_field_reference_not_found");
   });
 
   it("provides full/minimal/folder variants for schemas create", () => {

package/src/utils/examples.ts

@@ -698,7 +698,7 @@ const specificExamples: Record<string, readonly CommandExample[]> = {
     },
     {
       description:
-        "Create many records from a JSON array file (one object per record, slug -> value). Best-effort: valid records are created and invalid ones are reported per index in 'errors'. ReferenceField values must match the target's current targetDisplayField.",
+        "Create many records from a JSON array file (one object per record, slug -> value). Best-effort: valid records are created and invalid ones are reported per index in 'errors'. ReferenceField values accept the target record id (a bare UUID, or the compound 'recordId::anything' whose label is ignored) or an exact display value; the server stores the canonical 'recordId::displayValue'.",
       command: `zinkee --json records create contacts --records-file ./records.json`,
       raw: `{
   "records": [
@@ -729,6 +729,31 @@ const specificExamples: Record<string, readonly CommandExample[]> = {
       "action": "Use a valid field slug from the schema and retry."
     }
   ]
+}`,
+    },
+    {
+      description:
+        "Set a ReferenceField by the target record id (a bare UUID, or the compound 'recordId::anything' whose label is ignored) or by an exact display value. The server resolves and stores the canonical 'recordId::displayValue'. Unknown references are rejected per index with reason 'data_field_reference_not_found'.",
+      command:
+        `zinkee --json records create deals --set deal-name="Acme renewal" --set customer-ref=00000000-0000-0000-0000-000000000000`,
+      raw: `{
+  "records": [
+    {
+      "deal-name": "Acme renewal",
+      "customer-ref": "00000000-0000-0000-0000-000000000000"
+    }
+  ]
+}`,
+      response: `{
+  "created": [],
+  "errors": [
+    {
+      "index": 0,
+      "reason": "data_field_reference_not_found",
+      "message": "Referenced record was not found in the target schema.",
+      "action": "Use an existing record id or an existing display value for this reference field."
+    }
+  ]
 }`,
     },
   ]),
@@ -773,6 +798,24 @@ const specificExamples: Record<string, readonly CommandExample[]> = {
         'zinkee --json records update contacts 550e8400-e29b-41d4-a716-446655440000 --unset contact-email --unset due-date',
       raw: `{
   "unset": ["contact-email", "due-date"]
+}`,
+    },
+    {
+      description:
+        "Set a ReferenceField on an existing record. Pass the target record id (a bare UUID, or the compound 'recordId::anything' whose label is ignored) or an exact display value; the response shows the canonical 'recordId::displayValue' the server stored. If the reference doesn't exist the whole update is rejected with reason 'data_field_reference_not_found'.",
+      command:
+        'zinkee --json records update deals 550e8400-e29b-41d4-a716-446655440000 --set customer-ref=8ad602a1-f6e3-43f6-9ab2-f1c5afc99621',
+      raw: `{
+  "set": {
+    "customer-ref": "8ad602a1-f6e3-43f6-9ab2-f1c5afc99621"
+  }
+}`,
+      response: `{
+  "recordId": "550e8400-e29b-41d4-a716-446655440000",
+  "values": {
+    "deal-name": "Acme renewal",
+    "customer-ref": "8ad602a1-f6e3-43f6-9ab2-f1c5afc99621::Acme Corp"
+  }
 }`,
     },
   ]),