zinkee 0.1.33 → 0.1.35

package/README.md

@@ -279,13 +279,16 @@ Notes:
 ### CRUD operations
 
 ```bash
-# Create
+# Create a single record (--set/--set-json/--raw/--raw-file build one record)
 zinkee records create projects \
   --set name="Website Redesign" \
   --set budget=25000 \
   --set start-date="2026-01-15T00:00:00.000Z" \
   --set status=1
 
+# Create many records from a JSON array file (one object per record; mutually exclusive with the single-record flags)
+zinkee --json records create projects --records-file ./projects.json
+
 # List and query
 zinkee --json records list projects --limit 50
 zinkee --json records query projects --limit 10 --sort "_id:desc"
@@ -299,6 +302,11 @@ zinkee --json records get projects <record-uuid>
 # Update
 zinkee records update projects <record-uuid> --set status=2
 
+# Reference fields: pass the target record id (bare UUID or "recordId::label" — the label is
+# ignored) or an exact display value. The server stores the canonical "recordId::displayValue"
+# and rejects unknown references (reason "data_field_reference_not_found").
+zinkee records create deals --set deal-name="Acme renewal" --set customer-ref=<target-record-uuid>
+
 # Delete one or more records (--record is repeatable)
 zinkee records delete projects --record <record-uuid> --record <record-uuid>
 

package/dist/index.js

@@ -2832,35 +2832,78 @@ var specificExamples = {
   ]),
   "records create": buildCommandExamples([
     {
-      description: "Minimal create using just two plain string fields.",
+      description: "Create a single record with --set/--set-json (the single-record flags build one record, sent as a one-element 'records' array).",
       command: `zinkee --json records create contacts --set contact-name="Ada Lovelace" --set contact-email=ada@example.com`,
       raw: `{
-  "values": {
-    "contact-name": "Ada Lovelace",
-    "contact-email": "ada@example.com"
-  }
+  "records": [
+    {
+      "contact-name": "Ada Lovelace",
+      "contact-email": "ada@example.com"
+    }
+  ]
 }`,
       response: `{
-  "recordId": "550e8400-e29b-41d4-a716-446655440000",
-  "values": {
-    "contact-name": "Ada Lovelace",
-    "contact-email": "ada@example.com"
-  }
+  "created": [
+    "550e8400-e29b-41d4-a716-446655440000"
+  ],
+  "errors": []
 }`
     },
     {
-      description: "Create a record mixing text, option, number, date, reference and member fields. ReferenceField values must match the target's current targetDisplayField (read it from the target record before writing).",
-      command: `zinkee --json records create contacts --set contact-name="Grace Hopper" --set contact-email=grace@example.com --set status=2 --set amount=1999.99 --set due-date=2026-06-01T09:00:00Z --set customer-ref="CUST-12" --set owner=6c8a3e0d-4e5f-4a1b-9c2d-3e4f5a6b7c8d`,
+      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 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: `{
-  "values": {
-    "contact-name": "Grace Hopper",
-    "contact-email": "grace@example.com",
-    "status": 2,
-    "amount": 1999.99,
-    "due-date": "2026-06-01T09:00:00Z",
-    "customer-ref": "CUST-12",
-    "owner": "6c8a3e0d-4e5f-4a1b-9c2d-3e4f5a6b7c8d"
-  }
+  "records": [
+    {
+      "contact-name": "Ada Lovelace",
+      "contact-email": "ada@example.com"
+    },
+    {
+      "contact-name": "Grace Hopper",
+      "contact-email": "grace@example.com",
+      "status": 2,
+      "amount": 1999.99,
+      "due-date": "2026-06-01T09:00:00Z",
+      "customer-ref": "8ad602a1-f6e3-43f6-9ab2-f1c5afc99621",
+      "owner": "6c8a3e0d-4e5f-4a1b-9c2d-3e4f5a6b7c8d"
+    }
+  ]
+}`,
+      response: `{
+  "created": [
+    "550e8400-e29b-41d4-a716-446655440000"
+  ],
+  "errors": [
+    {
+      "index": 1,
+      "reason": "record_field_not_found",
+      "message": "Field 'contact-emial' was not found in schema '2eb8bdcf-6d9c-4fbb-9018-7fa8180f4c5e'.",
+      "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."
+    }
+  ]
 }`
     }
   ]),
@@ -2902,6 +2945,22 @@ var specificExamples = {
       command: "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"
+  }
 }`
     }
   ]),
@@ -10735,10 +10794,10 @@ var RecordsApi = class {
       `/api/v2/schemas/${selectorValue8(schema)}/records/${selectorValue8(record)}`
     );
   }
-  createRecord(schema, input) {
+  createRecords(schema, records) {
     return this.client.requestJson(
       `/api/v2/schemas/${selectorValue8(schema)}/records`,
-      jsonOptions6(input, "POST")
+      jsonOptions6({ records }, "POST")
     );
   }
   updateRecord(schema, record, input) {
@@ -11140,7 +11199,60 @@ function buildRecordQueryInput(options, allowRaw) {
   }
   return input;
 }
-function buildRecordCreateInput(options) {
+function readRecordsFromFile(path) {
+  let contents;
+  try {
+    contents = readFileSync8(path, "utf8");
+  } catch (error) {
+    const message = error instanceof Error ? error.message : "Unable to read file.";
+    throw new CliError(
+      "invalid_cli_usage",
+      `Failed to read records from ${path}: ${message}`
+    );
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(contents);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : "Invalid JSON.";
+    throw new CliError(
+      "invalid_cli_usage",
+      `Failed to parse JSON from --records-file ${path}: ${message}`
+    );
+  }
+  if (!Array.isArray(parsed)) {
+    throw new CliError(
+      "invalid_cli_usage",
+      `Expected --records-file ${path} to contain a JSON array of record objects.`
+    );
+  }
+  if (parsed.length === 0) {
+    throw new CliError(
+      "invalid_cli_usage",
+      `--records-file ${path} must contain at least one record.`
+    );
+  }
+  return parsed.map((record, index) => {
+    if (!isJsonObject6(record)) {
+      throw new CliError(
+        "invalid_cli_usage",
+        `Record at index ${index} in --records-file ${path} must be a JSON object.`
+      );
+    }
+    return record;
+  });
+}
+function buildCreateRecords(options) {
+  const hasSingleRecordFlags = (options.set?.length ?? 0) > 0 || (options.setJson?.length ?? 0) > 0 || options.raw !== void 0 || options.rawFile !== void 0;
+  if (options.recordsFile !== void 0) {
+    if (hasSingleRecordFlags) {
+      throw new CliError(
+        "invalid_cli_usage",
+        'Provide either "--records-file" or the single-record flags (--set/--set-json/--raw/--raw-file), not both.'
+      );
+    }
+    return readRecordsFromFile(options.recordsFile);
+  }
   const values = {
     ...readRawObject3(options.raw, options.rawFile),
     ...buildAssignmentObject(options.set, options.setJson)
@@ -11148,10 +11260,10 @@ function buildRecordCreateInput(options) {
   if (isEmptyObject5(values)) {
     throw new CliError(
       "invalid_cli_usage",
-      'Provide record fields via "--set", "--set-json", "--raw", or "--raw-file".'
+      'Provide record fields via "--set", "--set-json", "--raw", "--raw-file", or load multiple records with "--records-file".'
     );
   }
-  return { values };
+  return [values];
 }
 function buildRecordUpdateInput(options) {
   const raw = readRawObject3(options.raw, options.rawFile);
@@ -11274,21 +11386,38 @@ function registerRecordsCommands(program, options = {}) {
     }
     emitTable4(stdout, data);
   });
-  records.command("create").description("Create a record").argument("<schema>", "schema uuid or slug", parseUuidOrSlugSelector8).option("--set <field=value>", "set a string field", 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").action(async function action(schema, commandOptions) {
+  records.command("create").description("Create one or more records").argument("<schema>", "schema uuid or slug", parseUuidOrSlugSelector8).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").option(
+    "--records-file <path>",
+    "path to a JSON array of record objects (mutually exclusive with --set/--set-json/--raw/--raw-file)"
+  ).action(async function action(schema, commandOptions) {
     const { api, schemasApi, json, readOnly } = createRecordsApi(this, filePath);
     ensureWritable7("records create", readOnly, "write");
+    const records2 = buildCreateRecords(commandOptions);
     const resolvedSchema = await resolveSchemaSelector(schemasApi, schema);
-    const data = await api.createRecord(
-      resolvedSchema,
-      buildRecordCreateInput(commandOptions)
-    );
+    const data = await api.createRecords(resolvedSchema, records2);
     if (json) {
       emitJson10(stdout, "records create", data, filePath);
       return;
     }
-    writeLine10(stdout, `Created record "${getRecordIdentifier(data)}".`);
+    writeLine10(stdout, `Created ${data.created.length} record(s) in schema "${schema.value}".`);
+    if (data.errors.length > 0) {
+      writeLine10(stdout, `${data.errors.length} record(s) rejected:`);
+      for (const error of data.errors) {
+        writeLine10(stdout, `  - index ${error.index}: ${error.message}`);
+      }
+    }
   });
-  records.command("update").description("Update a record").argument("<schema>", "schema uuid or slug", parseUuidOrSlugSelector8).argument("<record>", "record uuid or slug", parseUuidOrSlugSelector8).option("--set <field=value>", "set a string field", 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").option("--raw-file <path>", "path to a JSON object of fields to set").action(async function action(schema, record, commandOptions) {
+  records.command("update").description("Update a record").argument("<schema>", "schema uuid or slug", parseUuidOrSlugSelector8).argument("<record>", "record uuid or slug", parseUuidOrSlugSelector8).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").option("--raw-file <path>", "path to a JSON object of fields to set").action(async function action(schema, record, commandOptions) {
     const { api, schemasApi, json, readOnly } = createRecordsApi(this, filePath);
     ensureWritable7("records update", readOnly, "write");
     const resolvedSchema = await resolveSchemaSelector(schemasApi, schema);