zinkee 0.1.2 → 0.1.7

package/src/config.test.ts

@@ -1,6 +1,7 @@
 import { describe, expect, it } from "vitest";
 
 import {
+  DEFAULT_PRODUCTION_BASE_URL,
   ENV_API_KEY,
   ENV_BASE_URL,
   ENV_PROFILE,
@@ -176,6 +177,50 @@ describe("resolveRuntimeContext", () => {
     }
   });
 
+  it("falls back to the production base URL when the resolved profile has no base URL", () => {
+    expect(
+      resolveRuntimeContext({
+        defaultProfile: "prod",
+        profiles: {
+          prod: { apiKey: "prod-token" },
+        },
+      }, {}),
+    ).toEqual({
+      profile: "prod",
+      baseUrl: DEFAULT_PRODUCTION_BASE_URL,
+      apiKey: "prod-token",
+      readOnly: false,
+      json: false,
+      profileSource: "config",
+      baseUrlSource: "config",
+      apiKeySource: "config",
+    });
+  });
+
+  it("still prefers an explicit base URL override over the production fallback", () => {
+    expect(
+      resolveRuntimeContext({
+        defaultProfile: "prod",
+        profiles: {
+          prod: { apiKey: "prod-token" },
+        },
+      }, {
+        profile: "prod",
+        baseUrl: "http://localhost:8088",
+        apiKey: "override-token",
+      }),
+    ).toEqual({
+      profile: "prod",
+      baseUrl: "http://localhost:8088",
+      apiKey: "override-token",
+      readOnly: false,
+      json: false,
+      profileSource: "flag",
+      baseUrlSource: "flag",
+      apiKeySource: "flag",
+    });
+  });
+
   it("throws a clear error when runtime api key is provided without base url", () => {
     const previousApiKey = process.env[ENV_API_KEY];
     const previousBaseUrl = process.env[ENV_BASE_URL];

package/src/config.ts

@@ -11,6 +11,7 @@ export const redactedSecretMask = "********";
 export const ENV_API_KEY = "ZINKEE_API_KEY";
 export const ENV_BASE_URL = "ZINKEE_API_BASE_URL";
 export const ENV_PROFILE = "ZINKEE_PROFILE";
+export const DEFAULT_PRODUCTION_BASE_URL = "https://api-z2.zinkee.com";
 
 export class ProfileResolutionError extends Error {
   override name = "ProfileResolutionError";

package/src/index.test.ts

@@ -120,7 +120,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/runtime-context.ts

@@ -1,6 +1,7 @@
 import type { AppConfig, RuntimeContext, RuntimeOverrides } from "./types.js";
 
 import {
+  DEFAULT_PRODUCTION_BASE_URL,
   ENV_API_KEY,
   ENV_BASE_URL,
   readEnvApiKey,
@@ -70,7 +71,7 @@ export function resolveRuntimeContext(
 
   return {
     profile: profile.name,
-    baseUrl: baseUrlOverride ?? profile.baseUrl,
+    baseUrl: baseUrlOverride ?? profile.baseUrl ?? DEFAULT_PRODUCTION_BASE_URL,
     apiKey: apiKeyOverride ?? profile.apiKey,
     readOnly: overrides.readOnly ?? false,
     json: overrides.json ?? false,

package/src/utils/examples.test.ts

@@ -64,4 +64,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');
+  });
 });