zinkee 0.1.0

package/src/api/teamspace.ts

@@ -0,0 +1,110 @@
+import { ApiClient } from "../client.js";
+import type { NormalizedUuidOrSlug } from "../parsers/selectors.js";
+import type { JsonObject } from "../types.js";
+
+export interface ApiTeamspaceResource {
+  [key: string]: unknown;
+  id?: string;
+  name?: string;
+}
+
+export interface ApiTeamspaceFolder {
+  [key: string]: unknown;
+  id?: string;
+  name?: string;
+  order?: number;
+  additionalProperties?: JsonObject;
+  resources?: ApiTeamspaceResource[];
+}
+
+export interface CreateTeamspaceFolderInput {
+  [key: string]: unknown;
+  name: string;
+  order?: number;
+  additionalProperties?: JsonObject;
+}
+
+export interface UpdateTeamspaceFolderInput {
+  [key: string]: unknown;
+  name?: string;
+  order?: number;
+  additionalProperties?: JsonObject;
+}
+
+export interface PublishTeamspaceResourceInput {
+  resourceId: string;
+  targetFolderId: string;
+}
+
+function jsonOptions(body: unknown, method: string): RequestInit {
+  return {
+    method,
+    headers: {
+      "content-type": "application/json",
+    },
+    body: JSON.stringify(body),
+  };
+}
+
+function selectorValue(selector: NormalizedUuidOrSlug): string {
+  return selector.value;
+}
+
+export class TeamspaceApi {
+  constructor(private readonly client: ApiClient) {}
+
+  listFolders(includeResources: boolean = false): Promise<ApiTeamspaceFolder[]> {
+    const params = new URLSearchParams();
+
+    if (includeResources) {
+      params.set("include", "resources");
+    }
+
+    const path = "/api/v2/teamspaces/folders";
+    const queryString = params.toString();
+
+    return this.client.getJson<ApiTeamspaceFolder[]>(
+      queryString ? `${path}?${queryString}` : path,
+    );
+  }
+
+  createFolder(input: CreateTeamspaceFolderInput): Promise<ApiTeamspaceFolder> {
+    return this.client.requestJson<ApiTeamspaceFolder>(
+      "/api/v2/teamspaces/folders",
+      jsonOptions(input, "POST"),
+    );
+  }
+
+  updateFolder(
+    folder: NormalizedUuidOrSlug,
+    input: UpdateTeamspaceFolderInput,
+  ): Promise<ApiTeamspaceFolder> {
+    return this.client.requestJson<ApiTeamspaceFolder>(
+      `/api/v2/teamspaces/folders/${selectorValue(folder)}`,
+      jsonOptions(input, "PATCH"),
+    );
+  }
+
+  deleteFolder(folder: NormalizedUuidOrSlug): Promise<Record<string, unknown>> {
+    return this.client.requestJson<Record<string, unknown>>(
+      `/api/v2/teamspaces/folders/${selectorValue(folder)}`,
+      { method: "DELETE" },
+    );
+  }
+
+  publishResource(
+    input: PublishTeamspaceResourceInput,
+  ): Promise<Record<string, unknown>> {
+    return this.client.requestJson<Record<string, unknown>>(
+      "/api/v2/teamspaces/resources:publish",
+      jsonOptions(input, "POST"),
+    );
+  }
+
+  unpublishResource(resourceId: string): Promise<Record<string, unknown>> {
+    return this.client.requestJson<Record<string, unknown>>(
+      "/api/v2/teamspaces/resources:unpublish",
+      jsonOptions({ resourceId }, "POST"),
+    );
+  }
+}

package/src/cli-examples.ts

@@ -0,0 +1,175 @@
+import { commandRegistry } from "./command-registry.js";
+import { CliError } from "./utils/errors.js";
+import { getResolvedCommandExamples } from "./utils/examples.js";
+import { buildJsonSuccess } from "./utils/output.js";
+
+interface CommandIo {
+  write(chunk: string): unknown;
+}
+
+export interface ExampleRequest {
+  commandName: string;
+  filters: {
+    type?: string;
+  };
+  overrides: {
+    profile?: string;
+    baseUrl?: string;
+    apiKey?: string;
+  };
+  json: boolean;
+}
+
+function getStdout(stdout?: CommandIo): CommandIo {
+  return stdout ?? process.stdout;
+}
+
+function resolveExampleCommand(tokens: readonly string[]): {
+  commandName: string;
+  remainingTokens: readonly string[];
+} {
+  const commands = Object.keys(commandRegistry).sort(
+    (left, right) => right.split(" ").length - left.split(" ").length,
+  );
+
+  for (const commandName of commands) {
+    const commandTokens = commandName.split(" ");
+    const matches = commandTokens.every((token, index) => tokens[index] === token);
+
+    if (matches) {
+      return {
+        commandName,
+        remainingTokens: tokens.slice(commandTokens.length),
+      };
+    }
+  }
+
+  const commandTokens = tokens.filter((token) => !token.startsWith("-"));
+
+  return {
+    commandName: commandTokens.join(" "),
+    remainingTokens: [],
+  };
+}
+
+function extractExampleFilters(tokens: readonly string[]): { type?: string } {
+  const filters: { type?: string } = {};
+
+  for (let index = 0; index < tokens.length; index += 1) {
+    const token = tokens[index];
+
+    if (token === "--type") {
+      const value = tokens[index + 1];
+      if (value && !value.startsWith("-")) {
+        filters.type = value;
+        index += 1;
+      }
+    }
+  }
+
+  return filters;
+}
+
+function extractExampleOverrides(tokens: readonly string[]): {
+  profile?: string;
+  baseUrl?: string;
+  apiKey?: string;
+} {
+  const overrides: {
+    profile?: string;
+    baseUrl?: string;
+    apiKey?: string;
+  } = {};
+
+  for (let index = 0; index < tokens.length; index += 1) {
+    const token = tokens[index];
+    const value = tokens[index + 1];
+
+    if (!value || value.startsWith("-")) {
+      continue;
+    }
+
+    if (token === "--profile") {
+      overrides.profile = value;
+      index += 1;
+      continue;
+    }
+
+    if (token === "--base-url") {
+      overrides.baseUrl = value;
+      index += 1;
+      continue;
+    }
+
+    if (token === "--api-key") {
+      overrides.apiKey = value;
+      index += 1;
+    }
+  }
+
+  return overrides;
+}
+
+export function extractExampleRequest(argv: readonly string[]): ExampleRequest | null {
+  const exampleIndex = argv.indexOf("--example");
+
+  if (exampleIndex === -1) {
+    return null;
+  }
+
+  const requestTokens = argv.slice(exampleIndex + 1);
+  const { commandName, remainingTokens } = resolveExampleCommand(requestTokens);
+
+  if (commandName.length === 0) {
+    throw new CliError("invalid_cli_usage", 'Provide a command after "--example".');
+  }
+
+  return {
+    commandName,
+    filters: extractExampleFilters(remainingTokens),
+    overrides: extractExampleOverrides(argv),
+    json: argv.includes("--json"),
+  };
+}
+
+export async function showExamples(
+  commandName: string,
+  json: boolean,
+  stdout?: CommandIo,
+  filters: { type?: string } = {},
+  options: {
+    enabled?: boolean;
+    configPath?: string;
+    overrides?: {
+      profile?: string;
+      baseUrl?: string;
+      apiKey?: string;
+    };
+  } = {},
+): Promise<void> {
+  const examples = await getResolvedCommandExamples(commandName, filters, options);
+
+  if (examples.length === 0) {
+    throw new CliError("invalid_cli_usage", `No examples registered for "${commandName}".`);
+  }
+
+  const writer = getStdout(stdout);
+
+  if (json) {
+    writer.write(`${JSON.stringify(buildJsonSuccess({ examples }, { command: commandName }))}\n`);
+    return;
+  }
+
+  writer.write("Examples:\n");
+  for (const [index, example] of examples.entries()) {
+    writer.write(`\n${index + 1}. ${example.description}\n`);
+    writer.write(`   ${example.command}\n`);
+
+    if (example.raw) {
+      writer.write("   Equivalent JSON payload:\n");
+      for (const line of example.raw.split("\n")) {
+        writer.write(`     ${line}\n`);
+      }
+    }
+  }
+}

package/src/cli-runner.ts

@@ -0,0 +1,73 @@
+import { realpathSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+
+import chalk from "chalk";
+
+import { extractExampleRequest, showExamples } from "./cli-examples.js";
+import { buildProgram } from "./program.js";
+import {
+  formatCliErrorJson,
+  formatCliErrorText,
+  getExitCode,
+} from "./utils/errors.js";
+
+class ExampleDisplayed extends Error {
+  override name = "ExampleDisplayed";
+}
+
+function hasJsonOutput(argv: readonly string[]): boolean {
+  return argv.includes("--json");
+}
+
+function resolveExecutablePath(candidatePath: string): string {
+  try {
+    return realpathSync(candidatePath);
+  } catch {
+    return candidatePath;
+  }
+}
+
+export function isExecutedAsEntry(argvEntry: string | undefined, moduleUrl: string): boolean {
+  if (!argvEntry) {
+    return false;
+  }
+
+  return resolveExecutablePath(argvEntry) === resolveExecutablePath(fileURLToPath(moduleUrl));
+}
+
+export async function runCli(argv: string[]): Promise<void> {
+  try {
+    const exampleRequest = extractExampleRequest(argv);
+
+    if (exampleRequest) {
+      await showExamples(
+        exampleRequest.commandName,
+        exampleRequest.json,
+        undefined,
+        exampleRequest.filters,
+        {
+          enabled: true,
+          overrides: exampleRequest.overrides,
+        },
+      );
+      throw new ExampleDisplayed();
+    }
+
+    await buildProgram().parseAsync(argv);
+  } catch (error) {
+    if (error instanceof ExampleDisplayed) {
+      process.exitCode = 0;
+      return;
+    }
+
+    const exitCode = getExitCode(error);
+
+    if (hasJsonOutput(argv)) {
+      process.stderr.write(`${formatCliErrorJson(error, { exitCode })}\n`);
+    } else {
+      process.stderr.write(`${chalk.red("Error:")} ${formatCliErrorText(error)}\n`);
+    }
+
+    process.exitCode = exitCode;
+  }
+}

package/src/client.test.ts

@@ -0,0 +1,128 @@
+import { describe, expect, it, vi } from "vitest";
+
+import { ApiClient, ApiClientError } from "./client.js";
+
+type FetchInput = Parameters<typeof fetch>[0];
+
+function jsonResponse(body: unknown, init: ResponseInit = {}): Response {
+  return new Response(JSON.stringify(body), {
+    ...init,
+    headers: {
+      "content-type": "application/json",
+      ...(init.headers ?? {}),
+    },
+  });
+}
+
+function binaryResponse(bytes: number[], init: ResponseInit = {}): Response {
+  return new Response(new Uint8Array(bytes), {
+    ...init,
+    headers: {
+      "content-type": "application/octet-stream",
+      ...(init.headers ?? {}),
+    },
+  });
+}
+
+describe("ApiClient", () => {
+  it("adds auth headers and parses JSON responses", async () => {
+    const fetchMock = vi.fn(async (_input: FetchInput, init?: RequestInit) => {
+      const headers = new Headers(init?.headers);
+
+      expect(headers.get("authorization")).toBe("Bearer secret");
+      expect(headers.get("accept")).toBe("application/json");
+
+      return jsonResponse({ data: { id: "1" } });
+    });
+
+    const client = new ApiClient({
+      baseUrl: "https://api.example.com",
+      apiKey: "secret",
+      fetch: fetchMock,
+    });
+
+    await expect(client.getJson<{ data: { id: string } }>("/api/v2/schemas")).resolves.toEqual({
+      data: { id: "1" },
+    });
+  });
+
+  it("preserves JSON error payloads from failed responses", async () => {
+    const fetchMock = vi.fn(async () =>
+      jsonResponse(
+        {
+          error: { code: "bad_request", message: "Bad request" },
+          meta: { requestId: "req_1" },
+        },
+        { status: 400, statusText: "Bad Request" },
+      ),
+    );
+
+    const client = new ApiClient({
+      baseUrl: "https://api.example.com",
+      fetch: fetchMock,
+    });
+
+    await expect(client.getJson("/api/v2/schemas")).rejects.toMatchObject({
+      name: "ApiClientError",
+      code: "http_error",
+      status: 400,
+      responseBody: {
+        error: { code: "bad_request", message: "Bad request" },
+        meta: { requestId: "req_1" },
+      },
+    });
+  });
+
+  it("times out slow requests", async () => {
+    vi.useFakeTimers();
+
+    try {
+      const fetchMock = vi.fn(
+        (_input: FetchInput, init?: RequestInit) =>
+          new Promise<Response>((_resolve, reject) => {
+            const signal = init?.signal;
+
+            signal?.addEventListener(
+              "abort",
+              () => {
+                reject(new Error("aborted"));
+              },
+              { once: true },
+            );
+          }),
+      );
+
+      const client = new ApiClient({
+        baseUrl: "https://api.example.com",
+        timeoutMs: 10,
+        fetch: fetchMock,
+      });
+
+      const promise = client.getJson("/api/v2/schemas");
+      const assertion = expect(promise).rejects.toMatchObject({
+        name: "ApiClientError",
+        code: "timeout",
+        message: "Request timed out after 10ms.",
+      });
+
+      await vi.advanceTimersByTimeAsync(10);
+
+      await assertion;
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+
+  it("returns binary responses as ArrayBuffers", async () => {
+    const fetchMock = vi.fn(async () => binaryResponse([1, 2, 3]));
+
+    const client = new ApiClient({
+      baseUrl: "https://api.example.com",
+      fetch: fetchMock,
+    });
+
+    const result = await client.requestBinary("/api/v2/files/abc");
+
+    expect(Array.from(new Uint8Array(result))).toEqual([1, 2, 3]);
+  });
+});