zinkee 0.1.32 → 0.1.34

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zinkee",
-  "version": "0.1.32",
+  "version": "0.1.34",
   "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"),
     );
   }
 
@@ -123,13 +133,13 @@ export class RecordsApi {
     );
   }
 
-  deleteRecord(
+  deleteRecords(
     schema: NormalizedUuidOrSlug,
-    record: NormalizedUuidOrSlug,
+    recordIds: string[],
   ): Promise<Record<string, unknown>> {
     return this.client.requestJson<Record<string, unknown>>(
-      `/api/v2/schemas/${selectorValue(schema)}/records/${selectorValue(record)}`,
-      { method: "DELETE" },
+      `/api/v2/schemas/${selectorValue(schema)}/records:delete`,
+      jsonOptions({ recordIds }, "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();
@@ -567,13 +659,147 @@ describe("records commands", () => {
         "records",
         "delete",
         "contacts",
-        "record-1",
+        "--record",
+        "550e8400-e29b-41d4-a716-446655440000",
       ]),
     ).rejects.toThrowError('Command "records delete" is not allowed in read-only mode.');
 
     expect(fetchMock).not.toHaveBeenCalled();
   });
 
+  it("deletes multiple records via repeatable --record flags and de-duplicates", async () => {
+    const configPath = createApiConfig();
+    const output = createStdoutBuffer();
+    const fetchMock = createFetchMock();
+    mockSchemaLookup(fetchMock);
+    fetchMock.mockResolvedValueOnce(
+      jsonResponse({
+        recordIds: [
+          "550e8400-e29b-41d4-a716-446655440000",
+          "550e8400-e29b-41d4-a716-446655440001",
+        ],
+        deleted: true,
+      }),
+    );
+    const program = buildProgram({ configPath, stdout: output.stdout });
+
+    await program.parseAsync([
+      "node",
+      "zinkee",
+      "--json",
+      "records",
+      "delete",
+      "contacts",
+      "--record",
+      "550e8400-e29b-41d4-a716-446655440000",
+      "--record",
+      "550e8400-e29b-41d4-a716-446655440001",
+      "--record",
+      "550e8400-e29b-41d4-a716-446655440000",
+    ]);
+
+    expect(fetchMock.mock.calls[1]?.[0]).toBe(
+      "https://api.zinkee.test/api/v2/schemas/schema-1/records:delete",
+    );
+
+    const init = fetchMock.mock.calls[1]?.[1];
+
+    expect(init?.method).toBe("POST");
+    expect(JSON.parse(String(init?.body))).toEqual({
+      recordIds: [
+        "550e8400-e29b-41d4-a716-446655440000",
+        "550e8400-e29b-41d4-a716-446655440001",
+      ],
+    });
+
+    const payload = JSON.parse(output.read());
+
+    expect(payload.data).toEqual({
+      recordIds: [
+        "550e8400-e29b-41d4-a716-446655440000",
+        "550e8400-e29b-41d4-a716-446655440001",
+      ],
+      deleted: true,
+    });
+  });
+
+  it("loads record ids from a file and merges them with --record", async () => {
+    const configPath = createApiConfig();
+    const idsFile = createTempConfig(
+      "550e8400-e29b-41d4-a716-446655440000\n  550e8400-e29b-41d4-a716-446655440002  \n\n",
+    );
+    const output = createStdoutBuffer();
+    const fetchMock = createFetchMock();
+    mockSchemaLookup(fetchMock);
+    fetchMock.mockResolvedValueOnce(
+      jsonResponse({
+        recordIds: [
+          "550e8400-e29b-41d4-a716-446655440000",
+          "550e8400-e29b-41d4-a716-446655440002",
+        ],
+        deleted: true,
+      }),
+    );
+    const program = buildProgram({ configPath, stdout: output.stdout });
+
+    await program.parseAsync([
+      "node",
+      "zinkee",
+      "--json",
+      "records",
+      "delete",
+      "contacts",
+      "--record",
+      "550e8400-e29b-41d4-a716-446655440000",
+      "--records-file",
+      idsFile,
+    ]);
+
+    const init = fetchMock.mock.calls[1]?.[1];
+
+    expect(init?.method).toBe("POST");
+    expect(JSON.parse(String(init?.body))).toEqual({
+      recordIds: [
+        "550e8400-e29b-41d4-a716-446655440000",
+        "550e8400-e29b-41d4-a716-446655440002",
+      ],
+    });
+  });
+
+  it("requires at least one record id for delete", async () => {
+    const configPath = createApiConfig();
+    const output = createStdoutBuffer();
+    const fetchMock = createFetchMock();
+    const program = buildProgram({ configPath, stdout: output.stdout });
+
+    await expect(
+      program.parseAsync(["node", "zinkee", "records", "delete", "contacts"]),
+    ).rejects.toThrowError(/at least one record id/);
+
+    expect(fetchMock).not.toHaveBeenCalled();
+  });
+
+  it("rejects a non-uuid record id for delete", async () => {
+    const configPath = createApiConfig();
+    const output = createStdoutBuffer();
+    const fetchMock = createFetchMock();
+    const program = buildProgram({ configPath, stdout: output.stdout });
+
+    await expect(
+      program.parseAsync([
+        "node",
+        "zinkee",
+        "records",
+        "delete",
+        "contacts",
+        "--record",
+        "not-a-uuid",
+      ]),
+    ).rejects.toThrow();
+
+    expect(fetchMock).not.toHaveBeenCalled();
+  });
+
   it("clears all records in a schema", 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,12 +66,18 @@ interface RecordsCreateCommandOptions {
   setJson?: JsonKeyValueAssignment[];
   raw?: string;
   rawFile?: string;
+  recordsFile?: string;
 }
 
 interface RecordsUpdateCommandOptions extends RecordsCreateCommandOptions {
   unset?: string[];
 }
 
+interface RecordsDeleteCommandOptions {
+  record?: string[];
+  recordsFile?: string;
+}
+
 function getCommandIo(stdout: CommandIo | undefined): CommandIo {
   return stdout ?? (process.stdout as Writable);
 }
@@ -237,6 +243,71 @@ function dedupeStrings(values: string[]): string[] {
   return [...new Set(values)];
 }
 
+function toRecordUuid(value: string): string | null {
+  try {
+    const normalized = normalizeUuidOrSlug(value);
+    return normalized.kind === "uuid" ? normalized.value : null;
+  } catch {
+    return null;
+  }
+}
+
+function collectRecordIds(value: string, previous: string[] = []): string[] {
+  const uuid = toRecordUuid(value.trim());
+  if (!uuid) {
+    throw new InvalidArgumentError(`Expected a record UUID, received "${value}".`);
+  }
+  return [...previous, uuid];
+}
+
+function readRecordIdsFromFile(path: string): string[] {
+  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 record ids from ${path}: ${message}`,
+    );
+  }
+
+  const ids: string[] = [];
+
+  contents.split(/\r?\n/).forEach((line, index) => {
+    const value = line.trim();
+    if (!value) {
+      return;
+    }
+    const uuid = toRecordUuid(value);
+    if (!uuid) {
+      throw new CliError(
+        "invalid_cli_usage",
+        `Invalid record UUID "${value}" at ${path}:${index + 1}.`,
+      );
+    }
+    ids.push(uuid);
+  });
+
+  return ids;
+}
+
+function resolveDeleteRecordIds(options: RecordsDeleteCommandOptions): string[] {
+  const flagIds = options.record ?? [];
+  const fileIds = options.recordsFile ? readRecordIdsFromFile(options.recordsFile) : [];
+  const recordIds = dedupeStrings([...flagIds, ...fileIds]);
+
+  if (recordIds.length === 0) {
+    throw new CliError(
+      "invalid_cli_usage",
+      'Provide at least one record id via "--record <uuid>" (repeatable) or "--records-file <path>".',
+    );
+  }
+
+  return recordIds;
+}
+
 function collectStringValues(value: string, previous: string[] = []): string[] {
   return [...previous, value];
 }
@@ -403,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),
@@ -414,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(
@@ -614,12 +748,16 @@ 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-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,
@@ -627,19 +765,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
@@ -678,31 +821,35 @@ export function registerRecordsCommands(
 
   records
     .command("delete")
-    .description("Delete a record")
+    .description("Delete one or more records")
     .argument("<schema>", "schema uuid or slug", parseUuidOrSlugSelector)
-    .argument("<record>", "record uuid or slug", parseUuidOrSlugSelector)
+    .option("--record <uuid>", "record uuid to delete (repeatable)", collectRecordIds, [])
+    .option(
+      "--records-file <path>",
+      "path to a file with one record uuid per line (merged with --record)",
+    )
     .action(async function action(
       this: Command,
       schema: NormalizedUuidOrSlug,
-      record: NormalizedUuidOrSlug,
+      commandOptions: RecordsDeleteCommandOptions,
     ) {
       const { api, schemasApi, json, readOnly } = createRecordsApi(this, filePath);
       ensureWritable("records delete", readOnly, "destructive");
+
+      const recordIds = resolveDeleteRecordIds(commandOptions);
       const resolvedSchema = await resolveSchemaSelector(schemasApi, schema);
 
-      await api.deleteRecord(resolvedSchema, record);
-      const data = {
-        schema: resolvedSchema.value,
-        record: record.value,
-        deleted: true,
-      };
+      const data = await api.deleteRecords(resolvedSchema, recordIds);
 
       if (json) {
         emitJson(stdout, "records delete", data, filePath);
         return;
       }
 
-      writeLine(stdout, `Deleted record "${record.value}" from schema "${schema.value}".`);
+      writeLine(
+        stdout,
+        `Deleted ${recordIds.length} record(s) from schema "${schema.value}".`,
+      );
     });
 
   records