zinkee 0.1.0

package/src/program.ts

@@ -0,0 +1,56 @@
+import { createRequire } from "node:module";
+
+import { Command } from "commander";
+
+import { registerConfigCommands } from "./commands/config.js";
+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 { registerNavigationCommands } from "./commands/navigation.js";
+import { registerProfilesCommands } from "./commands/profiles.js";
+import { registerRecordsCommands } from "./commands/records.js";
+import { registerSchemasCommands } from "./commands/schemas.js";
+import { registerTeamspaceCommands } from "./commands/teamspace.js";
+
+const require = createRequire(import.meta.url);
+const { version } = require("../package.json") as { version: string };
+
+interface CommandIo {
+  write(chunk: string): unknown;
+}
+
+export interface BuildProgramOptions {
+  configPath?: string;
+  stdout?: CommandIo;
+}
+
+export function buildProgram(options: BuildProgramOptions = {}): Command {
+  const program = new Command();
+
+  program
+    .name("zinkee")
+    .description("CLI for Zinkee API v2")
+    .version(version)
+    .enablePositionalOptions()
+    .showHelpAfterError()
+    .option("--profile <name>", "select a profile from config")
+    .option("--base-url <url>", "override the configured base URL")
+    .option("--api-key <token>", "override the configured API key")
+    .option("--read-only", "run in read-only mode")
+    .option("--example", "show examples for a command")
+    .option("--json", "emit JSON output");
+
+  registerProfilesCommands(program, options);
+  registerAutomationsCommands(program, options);
+  registerConfigCommands(program, options);
+  registerDisplaysCommands(program, options);
+  registerFilesCommands(program, options);
+  registerNavigationCommands(program, options);
+  registerSchemasCommands(program, options);
+  registerRecordsCommands(program, options);
+  registerCommentsCommands(program, options);
+  registerTeamspaceCommands(program, options);
+
+  return program;
+}

package/src/runtime-context.ts

@@ -0,0 +1,18 @@
+import type { AppConfig, RuntimeContext, RuntimeOverrides } from "./types.js";
+
+import { resolveProfile } from "./config.js";
+
+export function resolveRuntimeContext(
+  config: AppConfig,
+  overrides: RuntimeOverrides = {},
+): RuntimeContext {
+  const profile = resolveProfile(config, overrides);
+
+  return {
+    profile: profile.name,
+    baseUrl: overrides.baseUrl ?? profile.baseUrl,
+    apiKey: overrides.apiKey ?? profile.apiKey,
+    readOnly: overrides.readOnly ?? false,
+    json: overrides.json ?? false,
+  };
+}

package/src/types.ts

@@ -0,0 +1,71 @@
+export interface CliContext {
+  argv: string[];
+}
+
+export interface ProfileConfig {
+  apiKey?: string;
+  baseUrl?: string;
+  [key: string]: unknown;
+}
+
+export interface AppConfig {
+  defaultProfile?: string;
+  profiles: Record<string, ProfileConfig>;
+  [key: string]: unknown;
+}
+
+export interface ResolvedProfile extends ProfileConfig {
+  name: string;
+}
+
+export interface RuntimeOverrides {
+  profile?: string;
+  baseUrl?: string;
+  apiKey?: string;
+  readOnly?: boolean;
+  json?: boolean;
+}
+
+export interface RuntimeContext {
+  profile: string;
+  baseUrl?: string;
+  apiKey?: string;
+  readOnly: boolean;
+  json: boolean;
+}
+
+export type JsonScalar = string | number | boolean | null;
+
+export interface JsonObject {
+  [key: string]: JsonValue;
+}
+
+export type JsonValue = JsonScalar | JsonObject | JsonValue[];
+
+export interface JsonEnvelopeMeta {
+  [key: string]: unknown;
+}
+
+export interface JsonSuccessEnvelope<TData = JsonValue, TMeta extends JsonEnvelopeMeta = JsonEnvelopeMeta> {
+  data: TData;
+  meta: TMeta;
+}
+
+export interface JsonErrorEnvelope<TErr = JsonValue, TMeta extends JsonEnvelopeMeta = JsonEnvelopeMeta> {
+  error: TErr;
+  meta: TMeta;
+}
+
+export type OutputFormat = "json" | "table";
+
+export type CommandAccessLevel = "read" | "write" | "destructive";
+
+export type CommandOutputCapability = "table-json" | "json-only" | "binary";
+
+export interface CommandMeta {
+  command: string;
+  accessLevel: CommandAccessLevel;
+  supportsExample: boolean;
+  supportsRaw: boolean;
+  output: CommandOutputCapability;
+}

package/src/utils/errors.test.ts

@@ -0,0 +1,48 @@
+import { describe, expect, it } from "vitest";
+
+import { ApiClientError } from "../client.js";
+
+import { formatCliErrorJson } from "./errors.js";
+
+describe("formatCliErrorJson", () => {
+  it("preserves backend reason, action, requestId, and status details", () => {
+    const error = new ApiClientError(
+      "http_error",
+      "Request failed with status 409 for PATCH https://api.example.com/api/v2/automations/1.",
+      {
+        url: "https://api.example.com/api/v2/automations/1",
+        method: "PATCH",
+        status: 409,
+        responseBody: {
+          error: {
+            reason: "schema_locked",
+            action: "retry_later",
+            message: "Schema is locked.",
+          },
+          meta: {
+            requestId: "req_123",
+          },
+        },
+      },
+    );
+
+    expect(JSON.parse(formatCliErrorJson(error, { exitCode: 1 }))).toEqual({
+      error: {
+        code: "unknown_error",
+        message: "Schema is locked.",
+        exitCode: 1,
+        details: {
+          reason: "schema_locked",
+          action: "retry_later",
+          requestId: "req_123",
+          status: 409,
+        },
+      },
+      meta: {
+        requestId: "req_123",
+        status: 409,
+        exitCode: 1,
+      },
+    });
+  });
+});

package/src/utils/errors.ts

@@ -0,0 +1,183 @@
+import { ApiClientError } from "../client.js";
+import type { JsonEnvelopeMeta, JsonErrorEnvelope } from "../types.js";
+
+import { buildJsonError } from "./output.js";
+
+export type CliErrorCode =
+  | "unknown_error"
+  | "invalid_cli_usage"
+  | "configuration_error"
+  | "command_not_allowed_in_read_only_mode";
+
+export const cliExitCodeByErrorCode = {
+  unknown_error: 1,
+  invalid_cli_usage: 2,
+  configuration_error: 2,
+  command_not_allowed_in_read_only_mode: 7,
+} as const satisfies Record<CliErrorCode, number>;
+
+export interface CliErrorDetails {
+  [key: string]: unknown;
+}
+
+export interface CliErrorPayload {
+  code: CliErrorCode;
+  message: string;
+  exitCode: number;
+  details?: CliErrorDetails;
+}
+
+const errorCodeByName: Record<string, CliErrorCode> = {
+  ProfileResolutionError: "configuration_error",
+};
+
+export class CliError extends Error {
+  override name = "CliError";
+
+  readonly code: CliErrorCode;
+
+  readonly exitCode: number;
+
+  readonly details?: CliErrorDetails;
+
+  constructor(
+    code: CliErrorCode,
+    message: string,
+    details: CliErrorDetails = {},
+    exitCode: number = cliExitCodeByErrorCode[code],
+  ) {
+    super(message);
+    this.code = code;
+    this.exitCode = exitCode;
+
+    if (Object.keys(details).length > 0) {
+      this.details = details;
+    }
+  }
+
+  toJSON(): CliErrorPayload {
+    const payload: CliErrorPayload = {
+      code: this.code,
+      message: this.message,
+      exitCode: this.exitCode,
+    };
+
+    if (this.details) {
+      payload.details = this.details;
+    }
+
+    return payload;
+  }
+}
+
+export function isCliError(error: unknown): error is CliError {
+  return error instanceof CliError;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function readString(value: unknown): string | undefined {
+  return typeof value === "string" && value.trim().length > 0 ? value : undefined;
+}
+
+function readNumber(value: unknown): number | undefined {
+  return typeof value === "number" ? value : undefined;
+}
+
+function extractApiErrorDetails(error: ApiClientError): {
+  message: string;
+  details: CliErrorDetails;
+  meta: JsonEnvelopeMeta;
+} {
+  const details: CliErrorDetails = {};
+  const meta: JsonEnvelopeMeta = {};
+  const responseBody = isRecord(error.responseBody) ? error.responseBody : undefined;
+  const errorBody = responseBody?.error;
+  const backendError = isRecord(errorBody) ? errorBody : responseBody;
+  const backendMeta = isRecord(responseBody?.meta) ? responseBody.meta : undefined;
+  const reason =
+    readString(backendError?.reason) ??
+    readString(backendError?.code);
+  const action = readString(backendError?.action);
+  const requestId =
+    readString(backendMeta?.requestId) ??
+    readString(responseBody?.requestId) ??
+    readString(backendError?.requestId);
+  const status =
+    readNumber(backendError?.status) ??
+    readNumber(responseBody?.status) ??
+    error.status;
+  const backendMessage = readString(backendError?.message);
+
+  if (reason !== undefined) {
+    details.reason = reason;
+  }
+
+  if (action !== undefined) {
+    details.action = action;
+  }
+
+  if (requestId !== undefined) {
+    details.requestId = requestId;
+    meta.requestId = requestId;
+  }
+
+  if (status !== undefined) {
+    details.status = status;
+    meta.status = status;
+  }
+
+  return {
+    message: backendMessage ?? error.message,
+    details,
+    meta,
+  };
+}
+
+export function toCliError(error: unknown): CliError {
+  if (error instanceof CliError) {
+    return error;
+  }
+
+  if (error instanceof ApiClientError) {
+    const apiError = extractApiErrorDetails(error);
+
+    return new CliError("unknown_error", apiError.message, apiError.details);
+  }
+
+  if (error instanceof Error) {
+    return new CliError(errorCodeByName[error.name] ?? "unknown_error", error.message);
+  }
+
+  return new CliError("unknown_error", "Unknown error");
+}
+
+export function getExitCode(error: unknown): number {
+  return toCliError(error).exitCode;
+}
+
+export function buildJsonCliError<TMeta extends JsonEnvelopeMeta = JsonEnvelopeMeta>(
+  error: unknown,
+  meta: TMeta = {} as TMeta,
+): JsonErrorEnvelope<CliErrorPayload, TMeta> {
+  const cliError = toCliError(error);
+  const apiErrorMeta =
+    error instanceof ApiClientError
+      ? extractApiErrorDetails(error).meta
+      : {};
+
+  return buildJsonError(cliError.toJSON(), { ...apiErrorMeta, ...meta } as TMeta);
+}
+
+export function formatCliErrorText(error: unknown): string {
+  return toCliError(error).message;
+}
+
+export function formatCliErrorJson<TMeta extends JsonEnvelopeMeta = JsonEnvelopeMeta>(
+  error: unknown,
+  meta: TMeta = {} as TMeta,
+): string {
+  return JSON.stringify(buildJsonCliError(error, meta));
+}

package/src/utils/examples.test.ts

@@ -0,0 +1,67 @@
+import { describe, expect, it } from "vitest";
+
+import { getCommandExamples } from "./examples.js";
+
+describe("getCommandExamples", () => {
+  it("returns registered examples for complex commands", () => {
+    const examples = getCommandExamples("records query");
+
+    expect(examples.length).toBeGreaterThan(0);
+    expect(examples[0]?.command).toContain("records query");
+  });
+
+  it("returns fallback examples for simple commands", () => {
+    const examples = getCommandExamples("schemas list");
+
+    expect(examples.length).toBeGreaterThan(0);
+    expect(examples[0]?.command).toContain("schemas list");
+  });
+
+  it("returns schema field examples filtered by member type", () => {
+    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");
+  });
+
+  it("returns both plain and currency-style examples for number fields", () => {
+    const examples = getCommandExamples("schemas fields create", { type: "number" });
+
+    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");
+  });
+
+  it("returns canonical automation creation examples", () => {
+    const examples = getCommandExamples("automations create");
+
+    expect(examples.length).toBeGreaterThanOrEqual(3);
+    expect(examples[0]?.command).toContain("--trigger-type scheduled");
+    expect(examples.some((example) => example.command.includes("--trigger-type record_changed"))).toBe(
+      true,
+    );
+  });
+
+  it("returns automation trigger, webhook, and connection examples", () => {
+    expect(getCommandExamples("automations trigger set")).not.toHaveLength(0);
+    expect(getCommandExamples("automations webhook set")).not.toHaveLength(0);
+    expect(getCommandExamples("automations connections create")).not.toHaveLength(0);
+    expect(getCommandExamples("automations connections update")).not.toHaveLength(0);
+  });
+
+  it("includes raw payloads for key automation examples", () => {
+    const createExamples = getCommandExamples("automations create");
+    const actionExamples = getCommandExamples("automations actions add");
+    const webhookExamples = getCommandExamples("automations webhook set");
+
+    expect(createExamples.every((example) => typeof example.raw === "string" && example.raw.length > 0)).toBe(
+      true,
+    );
+    expect(actionExamples.some((example) => example.command.includes("--condition-json"))).toBe(true);
+    expect(actionExamples.some((example) => example.raw?.includes('"rawValue"'))).toBe(true);
+    expect(webhookExamples[0]?.raw).toContain("idempotencyKeyJsonPath");
+  });
+});