zinkee 0.1.26 → 0.1.27

package/package.json

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

package/src/api/records.ts

@@ -27,6 +27,7 @@ export interface RecordQueryInput {
   [key: string]: unknown;
   select?: string[];
   where?: RecordQueryExpression[];
+  search?: { term: string };
   sort?: string[];
   limit?: number;
   offset?: number;

package/src/commands/records.test.ts

@@ -196,6 +196,46 @@ describe("records commands", () => {
     });
   });
 
+  it("maps --search to a search.term object in the query body", async () => {
+    const configPath = createApiConfig();
+    const output = createStdoutBuffer();
+    const fetchMock = createFetchMock();
+    mockSchemaLookup(fetchMock);
+    fetchMock.mockResolvedValueOnce(
+      jsonResponse({
+        records: [{ recordId: "record-1", values: { name: "Ana Garcia" } }],
+        page: { offset: 0, limit: 25, total: 1, count: 1, hasMore: false },
+      }),
+    );
+    const program = buildProgram({ configPath, stdout: output.stdout });
+
+    await program.parseAsync([
+      "node",
+      "zinkee",
+      "--json",
+      "records",
+      "query",
+      "contacts",
+      "--select",
+      "id,name,status",
+      "--where",
+      "status in OPEN",
+      "--search",
+      "garcia",
+      "--limit",
+      "25",
+    ]);
+
+    const init = fetchMock.mock.calls[1]?.[1];
+
+    expect(JSON.parse(String(init?.body))).toEqual({
+      select: ["id", "name", "status"],
+      where: [{ field: "status", op: "in", value: ["OPEN"] }],
+      search: { term: "garcia" },
+      page: { limit: 25 },
+    });
+  });
+
   it("normalizes UUID selectors for records get", async () => {
     const configPath = createApiConfig();
     const output = createStdoutBuffer();

package/src/commands/records.ts

@@ -48,6 +48,7 @@ interface GlobalOptions extends RuntimeOverrides {}
 interface RecordsQueryCommandOptions {
   select?: string[];
   where?: ParsedExpression[];
+  search?: string;
   sort?: string[];
   limit?: number;
   offset?: number;
@@ -375,6 +376,10 @@ function buildRecordQueryInput(
     input.where = where;
   }
 
+  if (options.search !== undefined) {
+    input.search = { term: options.search };
+  }
+
   if (options.sort && options.sort.length > 0) {
     input.sort = [...options.sort];
   }
@@ -577,6 +582,10 @@ export function registerRecordsCommands(
       parseCommaSeparatedValues(value, "--select")
     ))
     .option("--where <expression>", "where expression", collectWhereExpressions, [])
+    .option(
+      "--search <term>",
+      "free-text search term (matched across the schema's searchable fields)",
+    )
     .option("--sort <field:direction>", "sort field(s)", collectSortValues, [])
     .option("--limit <number>", "limit results", parseNonNegativeInteger)
     .option("--offset <number>", "offset results", parseNonNegativeInteger)

package/src/utils/examples.test.ts

@@ -9,6 +9,12 @@ describe("getCommandExamples", () => {
 
     expect(examples.length).toBeGreaterThan(0);
     expect(examples[0]?.command).toContain("records query");
+
+    const searchExample = examples.find((example) =>
+      example.command.includes("--search"),
+    );
+    expect(searchExample?.command).toContain("--search garcia");
+    expect(searchExample?.raw).toContain('"search": { "term": "garcia" }');
   });
 
   it("returns fallback examples for simple commands", () => {

package/src/utils/examples.ts

@@ -502,7 +502,7 @@ const specificExamples: Record<string, readonly CommandExample[]> = {
     {
       description: "Filter by status with a free-text search term.",
       command:
-        `zinkee --json records query contacts --select id,contact-name,status --where "status in OPEN" --limit 25 --raw '{"search":{"term":"garcia"}}'`,
+        `zinkee --json records query contacts --select id,contact-name,status --where "status in OPEN" --search garcia --limit 25`,
       raw: `{
   "select": ["id", "contact-name", "status"],
   "where": [