zinkee 0.1.33 → 0.1.35

package/package.json

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

package/src/api/records.ts

@@ -33,8 +33,18 @@ export interface RecordQueryInput {
   offset?: number;
 }
 
-export interface CreateRecordInput {
-  [key: string]: unknown;
+export type CreateRecordValues = Record<string, unknown>;
+
+export interface CreateRecordError {
+  index: number;
+  reason: string;
+  message: string;
+  action: string;
+}
+
+export interface CreateRecordsResult {
+  created: string[];
+  errors: CreateRecordError[];
 }
 
 export interface UpdateRecordInput {
@@ -102,13 +112,13 @@ export class RecordsApi {
     );
   }
 
-  createRecord(
+  createRecords(
     schema: NormalizedUuidOrSlug,
-    input: CreateRecordInput,
-  ): Promise<ApiRecord> {
-    return this.client.requestJson<ApiRecord>(
+    records: CreateRecordValues[],
+  ): Promise<CreateRecordsResult> {
+    return this.client.requestJson<CreateRecordsResult>(
       `/api/v2/schemas/${selectorValue(schema)}/records`,
-      jsonOptions(input, "POST"),
+      jsonOptions({ records }, "POST"),
     );
   }
 

package/src/commands/records.test.ts

@@ -367,15 +367,15 @@ describe("records commands", () => {
     );
   });
 
-  it("creates records by merging raw JSON with set and set-json assignments", async () => {
+  it("creates a single record by merging raw JSON with set and set-json assignments", async () => {
     const configPath = createApiConfig();
     const output = createStdoutBuffer();
     const fetchMock = createFetchMock();
     mockSchemaLookup(fetchMock);
     fetchMock.mockResolvedValueOnce(
       jsonResponse({
-        id: "record-1",
-        name: "Ana",
+        created: ["record-1"],
+        errors: [],
       }),
     );
     const program = buildProgram({ configPath, stdout: output.stdout });
@@ -402,16 +402,108 @@ describe("records commands", () => {
     );
     expect(init?.method).toBe("POST");
     expect(JSON.parse(String(init?.body))).toEqual({
-      values: {
-        name: "Ana",
-        status: "active",
-        profile: {
-          tier: "gold",
+      records: [
+        {
+          name: "Ana",
+          status: "active",
+          profile: {
+            tier: "gold",
+          },
         },
-      },
+      ],
+    });
+  });
+
+  it("creates multiple records from a --records-file", async () => {
+    const configPath = createApiConfig();
+    const recordsFile = createTempConfig(
+      JSON.stringify([
+        { "contact-name": "Ada", status: 2 },
+        { "contact-name": "Grace", tags: ["a", "b"] },
+      ]),
+    );
+    const output = createStdoutBuffer();
+    const fetchMock = createFetchMock();
+    mockSchemaLookup(fetchMock);
+    fetchMock.mockResolvedValueOnce(
+      jsonResponse({
+        created: ["record-1", "record-2"],
+        errors: [],
+      }),
+    );
+    const program = buildProgram({ configPath, stdout: output.stdout });
+
+    await program.parseAsync([
+      "node",
+      "zinkee",
+      "--json",
+      "records",
+      "create",
+      "contacts",
+      "--records-file",
+      recordsFile,
+    ]);
+
+    const init = fetchMock.mock.calls[1]?.[1];
+
+    expect(fetchMock.mock.calls[1]?.[0]).toBe(
+      "https://api.zinkee.test/api/v2/schemas/schema-1/records",
+    );
+    expect(init?.method).toBe("POST");
+    expect(JSON.parse(String(init?.body))).toEqual({
+      records: [
+        { "contact-name": "Ada", status: 2 },
+        { "contact-name": "Grace", tags: ["a", "b"] },
+      ],
     });
   });
 
+  it("rejects combining --records-file with single-record flags", async () => {
+    const configPath = createApiConfig();
+    const recordsFile = createTempConfig(JSON.stringify([{ "contact-name": "Ada" }]));
+    const output = createStdoutBuffer();
+    const fetchMock = createFetchMock();
+    const program = buildProgram({ configPath, stdout: output.stdout });
+
+    await expect(
+      program.parseAsync([
+        "node",
+        "zinkee",
+        "records",
+        "create",
+        "contacts",
+        "--records-file",
+        recordsFile,
+        "--set",
+        "contact-name=Grace",
+      ]),
+    ).rejects.toThrowError(/not both/);
+
+    expect(fetchMock).not.toHaveBeenCalled();
+  });
+
+  it("rejects a --records-file that is not a JSON array", async () => {
+    const configPath = createApiConfig();
+    const recordsFile = createTempConfig(JSON.stringify({ "contact-name": "Ada" }));
+    const output = createStdoutBuffer();
+    const fetchMock = createFetchMock();
+    const program = buildProgram({ configPath, stdout: output.stdout });
+
+    await expect(
+      program.parseAsync([
+        "node",
+        "zinkee",
+        "records",
+        "create",
+        "contacts",
+        "--records-file",
+        recordsFile,
+      ]),
+    ).rejects.toThrowError(/JSON array/);
+
+    expect(fetchMock).not.toHaveBeenCalled();
+  });
+
   it("wraps raw-file fields into the set payload", async () => {
     const configPath = createApiConfig();
     const output = createStdoutBuffer();

package/src/commands/records.ts

@@ -5,7 +5,7 @@ import { Command, InvalidArgumentError } from "commander";
 
 import {
   type ApiRecord,
-  type CreateRecordInput,
+  type CreateRecordValues,
   type RecordQueryExpression,
   type RecordQueryInput,
   type RecordQueryResult,
@@ -66,6 +66,7 @@ interface RecordsCreateCommandOptions {
   setJson?: JsonKeyValueAssignment[];
   raw?: string;
   rawFile?: string;
+  recordsFile?: string;
 }
 
 interface RecordsUpdateCommandOptions extends RecordsCreateCommandOptions {
@@ -473,9 +474,72 @@ function buildRecordQueryInput(
   return input;
 }
 
-function buildRecordCreateInput(
-  options: RecordsCreateCommandOptions,
-): CreateRecordInput {
+function readRecordsFromFile(path: string): CreateRecordValues[] {
+  let contents: string;
+
+  try {
+    contents = readFileSync(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: unknown;
+  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 (!isJsonObject(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: RecordsCreateCommandOptions): CreateRecordValues[] {
+  const hasSingleRecordFlags =
+    (options.set?.length ?? 0) > 0 ||
+    (options.setJson?.length ?? 0) > 0 ||
+    options.raw !== undefined ||
+    options.rawFile !== undefined;
+
+  if (options.recordsFile !== undefined) {
+    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 = {
     ...readRawObject(options.raw, options.rawFile),
     ...buildAssignmentObject(options.set, options.setJson),
@@ -484,11 +548,11 @@ function buildRecordCreateInput(
   if (isEmptyObject(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(
@@ -684,12 +748,21 @@ export function registerRecordsCommands(
 
   records
     .command("create")
-    .description("Create a record")
+    .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")
+    .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(
       this: Command,
       schema: NormalizedUuidOrSlug,
@@ -697,19 +770,24 @@ export function registerRecordsCommands(
     ) {
       const { api, schemasApi, json, readOnly } = createRecordsApi(this, filePath);
       ensureWritable("records create", readOnly, "write");
+
+      const records = buildCreateRecords(commandOptions);
       const resolvedSchema = await resolveSchemaSelector(schemasApi, schema);
 
-      const data = await api.createRecord(
-        resolvedSchema,
-        buildRecordCreateInput(commandOptions),
-      );
+      const data = await api.createRecords(resolvedSchema, records);
 
       if (json) {
         emitJson(stdout, "records create", data, filePath);
         return;
       }
 
-      writeLine(stdout, `Created record "${getRecordIdentifier(data)}".`);
+      writeLine(stdout, `Created ${data.created.length} record(s) in schema "${schema.value}".`);
+      if (data.errors.length > 0) {
+        writeLine(stdout, `${data.errors.length} record(s) rejected:`);
+        for (const error of data.errors) {
+          writeLine(stdout, `  - index ${error.index}: ${error.message}`);
+        }
+      }
     });
 
   records
@@ -717,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

@@ -677,38 +677,83 @@ const specificExamples: Record<string, readonly CommandExample[]> = {
   ]),
   "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 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": [
+    {
+      "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:
-        "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).",
+        "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 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`,
+        `zinkee --json records create deals --set deal-name="Acme renewal" --set customer-ref=00000000-0000-0000-0000-000000000000`,
       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": [
+    {
+      "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."
+    }
+  ]
 }`,
     },
   ]),
@@ -753,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"
+  }
 }`,
     },
   ]),