zinkee 0.1.31 → 0.1.33

package/package.json

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

package/src/api/records.ts

@@ -123,13 +123,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

@@ -567,13 +567,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

@@ -72,6 +72,11 @@ 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 +242,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];
 }
@@ -678,31 +748,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

package/src/commands/schemas.ts

@@ -64,6 +64,16 @@ interface SetUniqueFieldsCommandOptions {
   clear?: boolean;
 }
 
+const 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.
+`;
+
 interface FieldCreateCommandOptions {
   type?: string;
   slug?: string;
@@ -583,7 +593,7 @@ export function registerSchemasCommands(
     .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)",
       parseUuidOrSlugSelector,
     )
     .action(async function action(
@@ -621,7 +631,8 @@ export function registerSchemasCommands(
       }
 
       writeLine(stdout, `Updated schema "${data.slug ?? schema.value}".`);
-    });
+    })
+    .addHelpText("after", HIGHLIGHTED_FIELD_HELP);
 
   schemas
     .command("set-unique-fields")

package/src/utils/examples.ts

@@ -264,7 +264,8 @@ const specificExamples: Record<string, readonly CommandExample[]> = {
 }`,
     },
     {
-      description: "Set the highlighted (main) field of a schema.",
+      description:
+        "Set the schema's highlighted (main) field — 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: `{
@@ -2460,10 +2461,25 @@ const specificExamples: Record<string, readonly CommandExample[]> = {
   ]),
   "records delete": buildCommandExamples([
     {
-      description: "Delete a record.",
-      command: `zinkee --json records delete contacts ${SAMPLE_UUID}`,
+      description: "Delete one or more records by id (--record is repeatable).",
+      command: `zinkee --json records delete contacts --record 550e8400-e29b-41d4-a716-446655440000 --record 6c8a3e0d-4e5f-4a1b-9c2d-3e4f5a6b7c8d`,
       response: `{
-  "recordId": "550e8400-e29b-41d4-a716-446655440000",
+  "recordIds": [
+    "550e8400-e29b-41d4-a716-446655440000",
+    "6c8a3e0d-4e5f-4a1b-9c2d-3e4f5a6b7c8d"
+  ],
+  "deleted": true
+}`,
+    },
+    {
+      description:
+        "Delete many records listing one uuid per line in a file (merged with any --record flags and de-duplicated).",
+      command: `zinkee --json records delete contacts --records-file ./record-ids.txt`,
+      response: `{
+  "recordIds": [
+    "550e8400-e29b-41d4-a716-446655440000",
+    "6c8a3e0d-4e5f-4a1b-9c2d-3e4f5a6b7c8d"
+  ],
   "deleted": true
 }`,
     },