zinkee 0.1.4 → 0.1.8

package/src/commands/schemas.test.ts

@@ -590,6 +590,94 @@ describe("schemas commands", () => {
     });
   });
 
+  it("normalizes schedule field shorthand payloads into the backend shape", async () => {
+    const configPath = createApiConfig();
+    const output = createStdoutBuffer();
+    const fetchMock = createFetchMock();
+    mockSchemaLookup(fetchMock);
+    fetchMock.mockResolvedValueOnce(
+      jsonResponse({
+        id: "field-5",
+        type: "ScheduleField",
+        slug: "monthly-recurrence",
+        label: "Monthly Recurrence",
+      }),
+    );
+    const program = buildProgram({ configPath, stdout: output.stdout });
+
+    await program.parseAsync([
+      "node",
+      "zinkee",
+      "--json",
+      "schemas",
+      "fields",
+      "create",
+      "contacts",
+      "--raw",
+      '{"type":"schedule","slug":"monthly-recurrence","label":"Monthly Recurrence","referenceField":"c52efe3f-2825-4c60-a7e3-34dd4c1ce043","beginningPeriodField":"d4e5f6a7-b8c9-0d1e-2f3a-4b5c6d7e8f90","endingPeriodField":"d4e5f6a7-b8c9-0d1e-2f3a-4b5c6d7e8f90","frequency":"monthly"}',
+    ]);
+
+    expect(JSON.parse(String(fetchMock.mock.calls[1]?.[1]?.body))).toEqual({
+      type: "ScheduleField",
+      slug: "monthly-recurrence",
+      label: "Monthly Recurrence",
+      config: {
+        referenceField: "c52efe3f-2825-4c60-a7e3-34dd4c1ce043",
+        beginningPeriodField: "d4e5f6a7-b8c9-0d1e-2f3a-4b5c6d7e8f90",
+        endingPeriodField: "d4e5f6a7-b8c9-0d1e-2f3a-4b5c6d7e8f90",
+        frequency: "monthly",
+      },
+    });
+  });
+
+  it("rejects schedule fields with invalid frequency before hitting the backend", async () => {
+    const configPath = createApiConfig();
+    const output = createStdoutBuffer();
+    const fetchMock = createFetchMock();
+    const program = buildProgram({ configPath, stdout: output.stdout });
+
+    await expect(
+      program.parseAsync([
+        "node",
+        "zinkee",
+        "schemas",
+        "fields",
+        "create",
+        "contacts",
+        "--raw",
+        '{"type":"ScheduleField","slug":"weekly","label":"Weekly","config":{"referenceField":"c52efe3f-2825-4c60-a7e3-34dd4c1ce043","beginningPeriodField":"d4e5f6a7-b8c9-0d1e-2f3a-4b5c6d7e8f90","endingPeriodField":"d4e5f6a7-b8c9-0d1e-2f3a-4b5c6d7e8f90","frequency":"weekly"}}',
+      ]),
+    ).rejects.toThrowError(
+      'Schedule "frequency" must be "monthly" or "daily" (received "weekly").',
+    );
+
+    expect(fetchMock).not.toHaveBeenCalled();
+  });
+
+  it("rejects schedule fields missing required config fields", async () => {
+    const configPath = createApiConfig();
+    const output = createStdoutBuffer();
+    const fetchMock = createFetchMock();
+    const program = buildProgram({ configPath, stdout: output.stdout });
+
+    await expect(
+      program.parseAsync([
+        "node",
+        "zinkee",
+        "schemas",
+        "fields",
+        "create",
+        "contacts",
+        "--raw",
+        '{"type":"ScheduleField","slug":"recurrence","label":"Recurrence","config":{"frequency":"daily"}}',
+      ]),
+    ).rejects.toThrowError(
+      /Schedule fields require "referenceField", "beginningPeriodField", "endingPeriodField" and "frequency"/,
+    );
+
+    expect(fetchMock).not.toHaveBeenCalled();
+  });
+
   it("rejects unsupported field types before making network requests", async () => {
     const configPath = createApiConfig();
     const output = createStdoutBuffer();
@@ -612,7 +700,7 @@ describe("schemas commands", () => {
         "Bad",
       ]),
     ).rejects.toThrowError(
-      'Unsupported field type "InvalidField". Valid types: text, number, date, option, file, reference, formula, member, autoincremental.',
+      'Unsupported field type "InvalidField". Valid types: text, number, date, option, file, reference, formula, member, autoincremental, schedule.',
     );
 
     expect(fetchMock).not.toHaveBeenCalled();
@@ -629,13 +717,12 @@ describe("schemas commands", () => {
     expect(help).toContain("member");
     expect(help).toContain("autoincremental");
     expect(help).toContain("Raw payload shapes by type:");
-    expect(help).toContain('"type":"number","slug":"price-eur"');
+    expect(help).toContain('"type":"NumberField","slug":"quantity"');
     expect(help).toContain('"defaultValue":"0"');
-    expect(help).toContain('"symbolEnabled":true');
     expect(help).toContain('- member: Workspace member field.');
-    expect(help).toContain('"type":"member","slug":"owner","label":"Owner"');
+    expect(help).toContain('"type":"MemberField","slug":"owner","label":"Owner"');
     expect(help).toContain('- option: Dropdown/select field with options.');
-    expect(help).toContain('"type":"option","slug":"status","label":"Status"');
+    expect(help).toContain('"type":"OptionField","slug":"status","label":"Status"');
     expect(help).toContain('Use "zinkee --example schemas fields create --type <type>"');
   });
 
@@ -692,7 +779,7 @@ describe("schemas commands", () => {
         '{"type":"option","slug":"status","label":"Status","options":[{"id":1,"name":"Open","color":"default"}]}',
       ]),
     ).rejects.toThrowError(
-      'Invalid payload for field type "option". Expected raw shape: {"type":"option","slug":"status","label":"Status","config":{"options":[{"id":1,"name":"Open","color":"default"},{"id":2,"name":"Closed","color":"success"}]}}',
+      'Invalid payload for field type "option". Expected raw shape: {"type":"OptionField","slug":"status","label":"Status","config":{"options":[{"id":1,"name":"Open","color":"default"},{"id":2,"name":"Closed","color":"success"}]}}',
     );
   });
 

package/src/index.test.ts

@@ -85,12 +85,12 @@ describe("project bootstrap", () => {
     );
 
     expect(output).toContain('zinkee --json schemas fields create contacts --raw');
-    expect(output).toContain('"type":"option"');
-    expect(output).not.toContain('"type":"text"');
-    expect(output).toContain("Create a option field");
+    expect(output).toContain('"type":"OptionField"');
+    expect(output).not.toContain('"type":"TextField"');
+    expect(output).toContain("Option field (select dropdown)");
   });
 
-  it("shows both number creation examples, including Moneda formatting", async () => {
+  it("shows every backend number variant, including currency formatting", async () => {
     let output = "";
 
     await showExamples(
@@ -105,9 +105,14 @@ describe("project bootstrap", () => {
       { type: "number" },
     );
 
-    expect(output).toContain('"slug":"amount"');
+    expect(output).toContain('"slug":"quantity"');
+    expect(output).toContain('"slug":"amount-eur"');
+    expect(output).toContain('"slug":"amount-usd"');
     expect(output).toContain('"symbolEnabled":true');
+    expect(output).toContain('"symbolPosition":"before"');
     expect(output).toContain('"symbolPosition":"right"');
+    expect(output).toContain('"format":"percentage"');
+    expect(output).toContain('"durationFormat":"HH:MM"');
   });
 
   it("shows automation examples with descriptions and equivalent payloads", async () => {
@@ -120,7 +125,7 @@ describe("project bootstrap", () => {
       },
     });
 
-    expect(output).toContain("Create a scheduled automation with a six-field cron expression");
+    expect(output).toContain("Create a scheduled automation");
     expect(output).toContain("Equivalent JSON payload:");
     expect(output).toContain('"type": "scheduled"');
     expect(output).toContain('"cronExpression": "0 15 10 * * 1"');

package/src/parsers/expressions.test.ts

@@ -3,48 +3,93 @@ import { describe, expect, it } from "vitest";
 import { parseExpression } from "./expressions.js";
 
 describe("parseExpression", () => {
-  it("parses space-separated equality filters", () => {
-    expect(parseExpression("status eq active")).toEqual({
-      field: "status",
-      comparator: "eq",
-      value: "active",
-      raw: "status eq active",
+  describe("scalar comparators", () => {
+    it.each([
+      ["eq", "status eq active", "status", "active"],
+      ["neq", "status neq archived", "status", "archived"],
+      ["gt", "amount gt 1000", "amount", "1000"],
+      ["gte", "amount gte 500", "amount", "500"],
+      ["lt", "amount lt 100", "amount", "100"],
+      ["lte", "due-date lte 2026-12-31T23:59:59Z", "due-date", "2026-12-31T23:59:59Z"],
+      ["contains", "contact-name contains Lovelace", "contact-name", "Lovelace"],
+    ])("parses %s expressions", (comparator, input, field, value) => {
+      expect(parseExpression(input)).toEqual({
+        field,
+        comparator,
+        value,
+        raw: input,
+      });
+    });
+
+    it("preserves spaces inside contains values", () => {
+      expect(parseExpression("email contains @acme.com")).toEqual({
+        field: "email",
+        comparator: "contains",
+        value: "@acme.com",
+        raw: "email contains @acme.com",
+      });
     });
   });
 
-  it("parses contains filters with spaces in the value", () => {
-    expect(parseExpression("email contains @acme.com")).toEqual({
-      field: "email",
-      comparator: "contains",
-      value: "@acme.com",
-      raw: "email contains @acme.com",
+  describe("unary comparators", () => {
+    it.each([
+      ["is_empty", "due-date is_empty", "due-date"],
+      ["is_not_empty", "contact-email is_not_empty", "contact-email"],
+    ])("parses %s expressions without a value", (comparator, input, field) => {
+      expect(parseExpression(input)).toEqual({
+        field,
+        comparator,
+        value: null,
+        raw: input,
+      });
     });
   });
 
-  it("parses unary null checks", () => {
-    expect(parseExpression("closedAt is-null")).toEqual({
-      field: "closedAt",
-      comparator: "is-null",
-      value: null,
-      raw: "closedAt is-null",
+  describe("list comparators", () => {
+    it("parses in expressions with a comma-separated value", () => {
+      expect(parseExpression("ownerId in a,b,c")).toEqual({
+        field: "ownerId",
+        comparator: "in",
+        value: ["a", "b", "c"],
+        raw: "ownerId in a,b,c",
+      });
     });
   });
 
-  it("parses repeated value lists", () => {
-    expect(parseExpression("ownerId in a,b,c")).toEqual({
-      field: "ownerId",
-      comparator: "in",
-      value: ["a", "b", "c"],
-      raw: "ownerId in a,b,c",
+  describe("delimiters", () => {
+    it("parses colon-delimited expressions", () => {
+      expect(parseExpression("amount:gt:1000")).toEqual({
+        field: "amount",
+        comparator: "gt",
+        value: "1000",
+        raw: "amount:gt:1000",
+      });
     });
   });
 
-  it("parses colon-delimited condition expressions", () => {
-    expect(parseExpression("amount:gt:1000")).toEqual({
-      field: "amount",
-      comparator: "gt",
-      value: "1000",
-      raw: "amount:gt:1000",
+  describe("errors", () => {
+    it("rejects unknown comparators", () => {
+      expect(() => parseExpression("status ne archived")).toThrow(
+        'Unsupported comparator "ne" in expression "status ne archived".',
+      );
+    });
+
+    it("rejects scalar comparators without a value", () => {
+      expect(() => parseExpression("status eq")).toThrow(
+        'Comparator "eq" requires a value.',
+      );
+    });
+
+    it("rejects unary comparators that carry a value", () => {
+      expect(() => parseExpression("due-date is_empty 2026-01-01")).toThrow(
+        'Comparator "is_empty" does not accept a value.',
+      );
+    });
+
+    it("rejects in expressions with no values", () => {
+      expect(() => parseExpression("ownerId in")).toThrow(
+        'Comparator "in" requires at least one value.',
+      );
     });
   });
 });

package/src/parsers/expressions.ts

@@ -1,4 +1,14 @@
-export type ExpressionComparator = "eq" | "contains" | "gt" | "is-null" | "in";
+export type ExpressionComparator =
+  | "eq"
+  | "neq"
+  | "gt"
+  | "gte"
+  | "lt"
+  | "lte"
+  | "contains"
+  | "in"
+  | "is_empty"
+  | "is_not_empty";
 
 export type ExpressionValue = string | readonly string[] | null;
 
@@ -11,12 +21,19 @@ export interface ParsedExpression {
 
 const supportedComparators = new Set<ExpressionComparator>([
   "eq",
-  "contains",
+  "neq",
   "gt",
-  "is-null",
+  "gte",
+  "lt",
+  "lte",
+  "contains",
   "in",
+  "is_empty",
+  "is_not_empty",
 ]);
 
+const noValueComparators = new Set<ExpressionComparator>(["is_empty", "is_not_empty"]);
+
 function parseColonExpression(input: string): [string, string, string] {
   const parts = input.split(":");
 
@@ -60,7 +77,7 @@ function parseSpaceExpression(input: string): [string, string, string] {
 }
 
 function normalizeValue(comparator: ExpressionComparator, rawValue: string): ExpressionValue {
-  if (comparator === "is-null") {
+  if (noValueComparators.has(comparator)) {
     if (rawValue.length > 0) {
       throw new Error(`Comparator "${comparator}" does not accept a value.`);
     }

package/src/program.ts

@@ -7,6 +7,7 @@ import { registerAutomationsCommands } from "./commands/automations.js";
 import { registerCommentsCommands } from "./commands/comments.js";
 import { registerDisplaysCommands } from "./commands/displays.js";
 import { registerFilesCommands } from "./commands/files.js";
+import { registerLogsCommands } from "./commands/logs.js";
 import { registerNavigationCommands } from "./commands/navigation.js";
 import { registerProfilesCommands } from "./commands/profiles.js";
 import { registerRecordsCommands } from "./commands/records.js";
@@ -50,6 +51,7 @@ export function buildProgram(options: BuildProgramOptions = {}): Command {
   registerSchemasCommands(program, options);
   registerRecordsCommands(program, options);
   registerCommentsCommands(program, options);
+  registerLogsCommands(program, options);
   registerTeamspaceCommands(program, options);
 
   return program;

package/src/utils/examples.test.ts

@@ -21,18 +21,54 @@ describe("getCommandExamples", () => {
     const examples = getCommandExamples("schemas fields create", { type: "member" });
 
     expect(examples).toHaveLength(1);
-    expect(examples[0]?.command).toContain('"type":"member"');
-    expect(examples[0]?.description).toContain("member field");
+    expect(examples[0]?.command).toContain('"type":"MemberField"');
+    expect(examples[0]?.description).toBe("Member field");
   });
 
-  it("returns both plain and currency-style examples for number fields", () => {
-    const examples = getCommandExamples("schemas fields create", { type: "number" });
+  it("returns monthly and daily variants for schedule fields", () => {
+    const examples = getCommandExamples("schemas fields create", { type: "schedule" });
 
     expect(examples).toHaveLength(2);
-    expect(examples[0]?.command).toContain('"slug":"amount"');
-    expect(examples[1]?.command).toContain('"symbolEnabled":true');
-    expect(examples[1]?.command).toContain('"symbolValue":" €"');
-    expect(examples[1]?.description).toContain("Moneda");
+    expect(examples.map((example) => example.description)).toEqual([
+      "Schedule field (monthly)",
+      "Schedule field (daily)",
+    ]);
+    expect(examples[0]?.command).toContain('"type":"ScheduleField"');
+    expect(examples[0]?.command).toContain('"frequency":"monthly"');
+    expect(examples[1]?.command).toContain('"frequency":"daily"');
+  });
+
+  it("covers every backend number field variant", () => {
+    const examples = getCommandExamples("schemas fields create", { type: "number" });
+
+    expect(examples).toHaveLength(6);
+
+    const descriptions = examples.map((example) => example.description);
+    expect(descriptions).toEqual([
+      "Number field (plain integer)",
+      "Number field (decimal with thousands)",
+      "Number field (currency € prefix)",
+      "Number field (currency $ suffix)",
+      "Number field (percentage)",
+      "Number field (duration HH:MM)",
+    ]);
+
+    expect(examples[0]?.command).toContain('"slug":"quantity"');
+    expect(examples[0]?.command).toContain('"format":"number"');
+
+    const eurCurrency = examples[2]?.command ?? "";
+    expect(eurCurrency).toContain('"format":"currency"');
+    expect(eurCurrency).toContain('"symbolEnabled":true');
+    expect(eurCurrency).toContain('"symbolPosition":"before"');
+    expect(eurCurrency).toContain('"symbolValue":"€"');
+
+    const usdCurrency = examples[3]?.command ?? "";
+    expect(usdCurrency).toContain('"symbolPosition":"right"');
+    expect(usdCurrency).toContain('"symbolValue":" $"');
+
+    expect(examples[4]?.command).toContain('"format":"percentage"');
+    expect(examples[5]?.command).toContain('"format":"duration"');
+    expect(examples[5]?.command).toContain('"durationFormat":"HH:MM"');
   });
 
   it("returns canonical automation creation examples", () => {
@@ -64,4 +100,154 @@ describe("getCommandExamples", () => {
     expect(actionExamples.some((example) => example.raw?.includes('"rawValue"'))).toBe(true);
     expect(webhookExamples[0]?.raw).toContain("idempotencyKeyJsonPath");
   });
+
+  it("covers every records query operator documented by the backend", () => {
+    const examples = getCommandExamples("records query");
+    const backendOperators = [
+      "eq",
+      "neq",
+      "gt",
+      "gte",
+      "lt",
+      "lte",
+      "contains",
+      "in",
+      "is_empty",
+      "is_not_empty",
+    ];
+
+    for (const op of backendOperators) {
+      expect(
+        examples.some((example) => example.raw?.includes(`"op": "${op}"`)),
+        `expected an example with op "${op}"`,
+      ).toBe(true);
+    }
+  });
+
+  it("offers both a minimal and a multi-type records create example", () => {
+    const examples = getCommandExamples("records create");
+
+    expect(examples).toHaveLength(2);
+    expect(examples[0]?.raw).toContain('"contact-name"');
+    expect(examples[1]?.raw).toContain('"customer-ref"');
+    expect(examples[1]?.raw).toContain('"owner"');
+  });
+
+  it("provides full/minimal/folder variants for schemas create", () => {
+    const examples = getCommandExamples("schemas create");
+
+    expect(examples).toHaveLength(3);
+    expect(examples.some((example) => example.raw?.includes('"folderId"'))).toBe(true);
+    expect(examples.every((example) => example.command.startsWith("zinkee --json schemas create"))).toBe(
+      true,
+    );
+  });
+
+  it("covers all widget types in displays widgets create", () => {
+    const examples = getCommandExamples("displays widgets create");
+    const rawPayloads = examples.map((example) => example.raw ?? "");
+
+    expect(examples.length).toBeGreaterThanOrEqual(7);
+    for (const widgetType of ["TABLE_OR_SUBTABLE", "DETAIL", "KPI", "CHART", "TIMELINE", "KANBAN", "HIERARCHY"]) {
+      expect(rawPayloads.some((raw) => raw.includes(`"type": "${widgetType}"`))).toBe(true);
+    }
+  });
+
+  it("covers REFERENCE, MEMBER and DATE variants in displays variables create", () => {
+    const examples = getCommandExamples("displays variables create");
+    const rawPayloads = examples.map((example) => example.raw ?? "");
+
+    expect(examples.length).toBeGreaterThanOrEqual(6);
+    for (const variableType of ["REFERENCE", "MEMBER", "DATE"]) {
+      expect(rawPayloads.some((raw) => raw.includes(`"type": "${variableType}"`))).toBe(true);
+    }
+    expect(rawPayloads.some((raw) => raw.includes('"dynamicOption": "thisMonth"'))).toBe(true);
+  });
+
+  it("covers SCHEMA, WORKFLOW and DISPLAY variants in navigation resources move", () => {
+    const examples = getCommandExamples("navigation resources move");
+    const rawPayloads = examples.map((example) => example.raw ?? "");
+
+    expect(examples.length).toBeGreaterThanOrEqual(5);
+    for (const resourceType of ["SCHEMA", "WORKFLOW", "DISPLAY", "SCHEDULE"]) {
+      expect(rawPayloads.some((raw) => raw.includes(`"resourceType": "${resourceType}"`))).toBe(true);
+    }
+  });
+
+  it("covers slug and UUID variants in teamspace resources publish", () => {
+    const examples = getCommandExamples("teamspace resources publish");
+
+    expect(examples.length).toBeGreaterThanOrEqual(4);
+    expect(examples.some((example) => example.command.includes("customer-records"))).toBe(true);
+    expect(examples.some((example) => example.command.includes("2eb8bdcf-6d9c-4fbb-9018-7fa8180f4c5e"))).toBe(
+      true,
+    );
+  });
+
+  it("enriches displays list with the documented response body", () => {
+    const examples = getCommandExamples("displays list");
+
+    expect(examples).toHaveLength(1);
+    expect(examples[0]?.response).toContain('"layoutTemplate": "widget_row_tabs"');
+    expect(examples[0]?.response).toContain('"layoutTemplate": "freeform"');
+    expect(examples[0]?.response).toContain('"layoutTemplate": "grid"');
+  });
+
+  it("attaches a response body to schemas create and teamspace resources publish", () => {
+    const schemaExamples = getCommandExamples("schemas create");
+    const publishExamples = getCommandExamples("teamspace resources publish");
+
+    expect(schemaExamples[0]?.response).toContain('"schemaId"');
+    expect(publishExamples[0]?.response).toContain('"targetFolder"');
+    expect(publishExamples[0]?.response).toContain('"previousFolder"');
+  });
+
+  it("attaches a rich response body to displays get", () => {
+    const examples = getCommandExamples("displays get");
+
+    expect(examples).toHaveLength(1);
+    expect(examples[0]?.response).toContain('"widgets"');
+    expect(examples[0]?.response).toContain('"variables"');
+    expect(examples[0]?.response).toContain('"crossWidgetFilter"');
+    expect(examples[0]?.response).toContain('"navigationTargets"');
+  });
+
+  it("attaches responses to automations reads and mutations", () => {
+    expect(getCommandExamples("automations list")[0]?.response).toContain('"triggerType"');
+    expect(getCommandExamples("automations get")[0]?.response).toContain('"trigger"');
+    expect(getCommandExamples("automations create")[0]?.response).toContain('"automationId"');
+    expect(getCommandExamples("automations create")[0]?.response).toContain('"webhookEndpoint"');
+    expect(getCommandExamples("automations webhook set")[0]?.response).toContain('"endpointUrl"');
+    expect(getCommandExamples("automations folders create")[0]?.response).toContain('"automationCount": 0');
+    expect(getCommandExamples("automations connections create")[0]?.response).toContain(
+      '"ownerMemberId"',
+    );
+  });
+
+  it("covers every profiles and config subcommand with an example that emits JSON", () => {
+    const profileAndConfigCommands = [
+      "profiles list",
+      "profiles get",
+      "profiles use",
+      "profiles add",
+      "profiles update",
+      "profiles remove",
+      "config path",
+      "config show",
+      "config validate",
+    ];
+
+    for (const commandName of profileAndConfigCommands) {
+      const examples = getCommandExamples(commandName);
+      expect(examples.length, `${commandName} has no examples`).toBeGreaterThan(0);
+      for (const example of examples) {
+        expect(example.command.startsWith("zinkee "), `${commandName}: ${example.command}`).toBe(true);
+        expect(example.response, `${commandName} missing response`).toBeTruthy();
+      }
+    }
+
+    expect(getCommandExamples("profiles list")[0]?.response).toContain('"apiKey": "********cdef"');
+    expect(getCommandExamples("config show")[0]?.response).toContain('"defaultProfile": "prod"');
+    expect(getCommandExamples("config validate")[0]?.response).toContain('"valid": true');
+  });
 });