viatris-exam-cli 0.0.0-stage → 1.3.0

package/src/args.js

@@ -0,0 +1,89 @@
+import { CliError } from "./errors.js";
+
+const BOOLEAN_OPTIONS = new Set(["help", "compact", "version"]);
+const GLOBAL_OPTIONS = [
+  "base_url",
+  "key_header",
+  "key_prefix",
+  "timeout",
+  "retries",
+  "compact",
+];
+
+export function parseArgs(argv) {
+  const positionals = [];
+  const options = {};
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const token = argv[index];
+    if (token === "--") {
+      positionals.push(...argv.slice(index + 1));
+      break;
+    }
+    if (!token.startsWith("--")) {
+      positionals.push(token);
+      continue;
+    }
+
+    const equalsAt = token.indexOf("=");
+    const rawName = token.slice(2, equalsAt === -1 ? undefined : equalsAt);
+    const name = rawName.replaceAll("-", "_");
+    if (BOOLEAN_OPTIONS.has(rawName)) {
+      if (equalsAt !== -1) {
+        throw new CliError("usage_error", `--${rawName} does not accept a value.`);
+      }
+      options[name] = true;
+      continue;
+    }
+
+    const value = equalsAt === -1 ? argv[index + 1] : token.slice(equalsAt + 1);
+    if (value === undefined || (equalsAt === -1 && value.startsWith("--"))) {
+      throw new CliError("usage_error", `--${rawName} requires a value.`);
+    }
+    options[name] = value;
+    if (equalsAt === -1) index += 1;
+  }
+
+  return { positionals, options };
+}
+
+export function requiredId(positionals, index, label) {
+  const id = positionals[index];
+  if (!id) throw new CliError("usage_error", `Missing required ${label}.`);
+  return encodeURIComponent(id);
+}
+
+export function integerOption(value, name, min, max) {
+  if (value === undefined) return undefined;
+  if (!/^\d+$/.test(value)) {
+    throw new CliError("validation_error", `--${name} must be an integer.`);
+  }
+  const number = Number(value);
+  if (number < min || number > max) {
+    throw new CliError(
+      "validation_error",
+      `--${name} must be between ${min} and ${max}.`,
+    );
+  }
+  return number;
+}
+
+export function assertNoExtraPositionals(positionals, count) {
+  if (positionals.length > count) {
+    throw new CliError(
+      "usage_error",
+      `Unexpected argument: ${positionals[count]}`,
+    );
+  }
+}
+
+export function assertOptions(options, commandOptions = []) {
+  const allowed = new Set([...GLOBAL_OPTIONS, ...commandOptions]);
+  const unknown = Object.keys(options).find((name) => !allowed.has(name));
+  if (unknown) {
+    throw new CliError(
+      "usage_error",
+      `Unknown or unsupported option for this command: --${unknown.replaceAll("_", "-")}`,
+    );
+  }
+}

package/src/cli.js

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+
+import { run } from "./app.js";
+import { normalizeError } from "./errors.js";
+import { writeError } from "./output.js";
+
+run(process.argv.slice(2)).catch((error) => {
+  const cliError = normalizeError(error);
+  writeError(process.stderr, cliError);
+  process.exitCode = cliError.exitCode;
+});

package/src/command-handlers/content.js

@@ -0,0 +1,43 @@
+import {
+  assertNoExtraPositionals,
+  assertOptions,
+  requiredId,
+} from "../args.js";
+import { readJsonInput } from "../input.js";
+
+export async function resolveContent(positionals, options) {
+  const [resource, action] = positionals;
+
+  if (resource === "exams" && action === "create") {
+    assertNoExtraPositionals(positionals, 2);
+    assertOptions(options, ["input", "json"]);
+    return {
+      method: "POST",
+      path: "/openapi/exams",
+      body: await readJsonInput(options),
+    };
+  }
+
+  if (resource === "questions" && action === "create") {
+    assertNoExtraPositionals(positionals, 2);
+    assertOptions(options, ["input", "json"]);
+    return {
+      method: "POST",
+      path: "/openapi/questions",
+      body: await readJsonInput(options),
+    };
+  }
+
+  if (resource === "questions" && action === "version") {
+    assertNoExtraPositionals(positionals, 3);
+    assertOptions(options, ["input", "json"]);
+    const id = requiredId(positionals, 2, "question ID");
+    return {
+      method: "POST",
+      path: `/openapi/questions/${id}/versions`,
+      body: await readJsonInput(options),
+    };
+  }
+
+  return null;
+}

package/src/command-handlers/exam-records.js

@@ -0,0 +1,29 @@
+import {
+  assertNoExtraPositionals,
+  assertOptions,
+  requiredId,
+} from "../args.js";
+
+export async function resolveExamRecords(positionals, options) {
+  const [resource, action] = positionals;
+  if (resource !== "exam-records") return null;
+
+  if (action === "get") {
+    assertNoExtraPositionals(positionals, 3);
+    assertOptions(options);
+    const id = requiredId(positionals, 2, "exam record ID");
+    return { method: "GET", path: `/openapi/exam-records/${id}` };
+  }
+
+  if (action === "scoring-rules") {
+    assertNoExtraPositionals(positionals, 3);
+    assertOptions(options);
+    const id = requiredId(positionals, 2, "exam record ID");
+    return {
+      method: "GET",
+      path: `/openapi/exam-records/${id}/scoring-rules`,
+    };
+  }
+
+  return null;
+}

package/src/command-handlers/gen-tasks.js

@@ -0,0 +1,53 @@
+import {
+  assertNoExtraPositionals,
+  assertOptions,
+  integerOption,
+  requiredId,
+} from "../args.js";
+import { CliError } from "../errors.js";
+import { readJsonInput } from "../input.js";
+
+export async function resolveGenTasks(positionals, options) {
+  const [resource, action] = positionals;
+  if (resource !== "gen-tasks") return null;
+
+  if (action === "list") {
+    assertNoExtraPositionals(positionals, 2);
+    assertOptions(options, ["status", "limit"]);
+    const allowedStatuses = new Set(["generating", "partial_failed", "failed"]);
+    if (options.status && !allowedStatuses.has(options.status)) {
+      throw new CliError(
+        "validation_error",
+        "--status must be generating, partial_failed, or failed.",
+      );
+    }
+    const query = new URLSearchParams();
+    if (options.status) query.set("status", options.status);
+    const limit = integerOption(options.limit, "limit", 1, 50);
+    if (limit !== undefined) query.set("limit", String(limit));
+    return {
+      method: "GET",
+      path: `/openapi/gen-tasks${query.size ? `?${query}` : ""}`,
+    };
+  }
+
+  if (action === "get") {
+    assertNoExtraPositionals(positionals, 3);
+    assertOptions(options);
+    const id = requiredId(positionals, 2, "task ID");
+    return { method: "GET", path: `/openapi/gen-tasks/${id}` };
+  }
+
+  if (action === "submit") {
+    assertNoExtraPositionals(positionals, 3);
+    assertOptions(options, ["input", "json"]);
+    const id = requiredId(positionals, 2, "task ID");
+    return {
+      method: "POST",
+      path: `/openapi/gen-tasks/${id}/questions`,
+      body: await readJsonInput(options),
+    };
+  }
+
+  return null;
+}

package/src/command-handlers/medical-search.js

@@ -0,0 +1,55 @@
+import {
+  assertNoExtraPositionals,
+  assertOptions,
+  integerOption,
+} from "../args.js";
+import { CliError } from "../errors.js";
+import { hasPipedInput, readJsonInput } from "../input.js";
+
+export async function resolveMedicalSearch(positionals, options) {
+  const [resource, action] = positionals;
+  if (resource !== "medical-search" || action !== "search") return null;
+
+  assertNoExtraPositionals(positionals, 3);
+  assertOptions(options, [
+    "input",
+    "json",
+    "file_type",
+    "limit",
+    "max_length",
+  ]);
+  const hasStructuredInput =
+    options.input !== undefined ||
+    options.json !== undefined ||
+    (hasPipedInput() && positionals[2] === undefined);
+  if (hasStructuredInput) {
+    if (
+      positionals[2] !== undefined ||
+      options.file_type !== undefined ||
+      options.limit !== undefined ||
+      options.max_length !== undefined
+    ) {
+      throw new CliError(
+        "usage_error",
+        "Do not combine JSON input with medical-search query flags.",
+      );
+    }
+    return {
+      method: "POST",
+      path: "/openapi/medical-search",
+      body: await readJsonInput(options),
+    };
+  }
+
+  const query = positionals[2];
+  if (!query) {
+    throw new CliError("usage_error", "Missing medical search query.");
+  }
+  const body = { query };
+  if (options.file_type !== undefined) body.fileType = options.file_type;
+  const limit = integerOption(options.limit, "limit", 1, 20);
+  if (limit !== undefined) body.limit = limit;
+  const maxLength = integerOption(options.max_length, "max-length", 100, 5000);
+  if (maxLength !== undefined) body.maxLength = maxLength;
+  return { method: "POST", path: "/openapi/medical-search", body };
+}

package/src/command-handlers/products.js

@@ -0,0 +1,31 @@
+import {
+  assertNoExtraPositionals,
+  assertOptions,
+  requiredId,
+} from "../args.js";
+import { readJsonInput } from "../input.js";
+
+export async function resolveProducts(positionals, options) {
+  const [resource, action] = positionals;
+  if (resource !== "products") return null;
+
+  if (action === "get") {
+    assertNoExtraPositionals(positionals, 3);
+    assertOptions(options);
+    const id = requiredId(positionals, 2, "product ID");
+    return { method: "GET", path: `/openapi/products/${id}` };
+  }
+
+  if (action === "update-knowledge-tree") {
+    assertNoExtraPositionals(positionals, 3);
+    assertOptions(options, ["input", "json"]);
+    const id = requiredId(positionals, 2, "product ID");
+    return {
+      method: "PUT",
+      path: `/openapi/products/${id}/knowledge-tree`,
+      body: await readJsonInput(options),
+    };
+  }
+
+  return null;
+}

package/src/command-handlers/scoring.js

@@ -0,0 +1,31 @@
+import {
+  assertNoExtraPositionals,
+  assertOptions,
+  requiredId,
+} from "../args.js";
+import { readJsonInput } from "../input.js";
+
+export async function resolveScoring(positionals, options) {
+  const [resource, action] = positionals;
+  if (resource !== "scoring") return null;
+
+  if (action === "get") {
+    assertNoExtraPositionals(positionals, 3);
+    assertOptions(options);
+    const id = requiredId(positionals, 2, "task ID");
+    return { method: "GET", path: `/openapi/scoring/${id}` };
+  }
+
+  if (action === "submit") {
+    assertNoExtraPositionals(positionals, 3);
+    assertOptions(options, ["input", "json"]);
+    const id = requiredId(positionals, 2, "task ID");
+    return {
+      method: "POST",
+      path: `/openapi/scoring/${id}/results`,
+      body: await readJsonInput(options),
+    };
+  }
+
+  return null;
+}

package/src/commands.js

@@ -0,0 +1,28 @@
+import { resolveContent } from "./command-handlers/content.js";
+import { resolveExamRecords } from "./command-handlers/exam-records.js";
+import { resolveGenTasks } from "./command-handlers/gen-tasks.js";
+import { resolveMedicalSearch } from "./command-handlers/medical-search.js";
+import { resolveProducts } from "./command-handlers/products.js";
+import { resolveScoring } from "./command-handlers/scoring.js";
+import { CliError } from "./errors.js";
+
+const resolvers = [
+  resolveProducts,
+  resolveGenTasks,
+  resolveExamRecords,
+  resolveScoring,
+  resolveContent,
+  resolveMedicalSearch,
+];
+
+export async function resolveCommand(positionals, options) {
+  for (const resolve of resolvers) {
+    const command = await resolve(positionals, options);
+    if (command) return command;
+  }
+
+  throw new CliError(
+    "usage_error",
+    "Unknown command. Run `viatris-exam --help` or `viatris-exam describe`.",
+  );
+}

package/src/config.js

@@ -0,0 +1,85 @@
+import { integerOption } from "./args.js";
+import { CliError } from "./errors.js";
+import {
+  API_ENVIRONMENT_ALIASES,
+  API_ENVIRONMENTS,
+  DEFAULT_RETRIES,
+  DEFAULT_TIMEOUT_MS,
+} from "./metadata.js";
+
+export function configFrom(options, environmentVariables = process.env) {
+  const baseUrlOverride =
+    options.base_url ?? environmentVariables.VIATRIS_API_BASE_URL;
+  let environment = null;
+  let baseUrl = baseUrlOverride;
+  if (baseUrlOverride === undefined) {
+    const requestedEnvironment = (
+      environmentVariables.VIATRIS_API_ENV ?? "production"
+    ).toLowerCase();
+    environment =
+      API_ENVIRONMENT_ALIASES[requestedEnvironment] ?? requestedEnvironment;
+    if (!Object.hasOwn(API_ENVIRONMENTS, environment)) {
+      throw new CliError(
+        "config_error",
+        "VIATRIS_API_ENV must be production, development, prod, or dev.",
+        { exitCode: 3 },
+      );
+    }
+    baseUrl = API_ENVIRONMENTS[environment];
+  }
+
+  const apiKey = environmentVariables.VIATRIS_API_KEY;
+  const keyHeader =
+    options.key_header ??
+    environmentVariables.VIATRIS_API_KEY_HEADER ??
+    "X-API-Key";
+  const keyPrefix =
+    options.key_prefix ?? environmentVariables.VIATRIS_API_KEY_PREFIX ?? "";
+  const timeoutMs = integerOption(
+    options.timeout ?? String(DEFAULT_TIMEOUT_MS),
+    "timeout",
+    1,
+    600_000,
+  );
+  const retries = integerOption(
+    options.retries ?? String(DEFAULT_RETRIES),
+    "retries",
+    0,
+    5,
+  );
+
+  if (!baseUrl) {
+    throw new CliError(
+      "config_error",
+      "The API base URL override cannot be empty.",
+      { exitCode: 3 },
+    );
+  }
+  if (!/^https?:\/\//.test(baseUrl)) {
+    throw new CliError(
+      "config_error",
+      "VIATRIS_API_BASE_URL must start with http:// or https://.",
+      { exitCode: 3 },
+    );
+  }
+  if (!apiKey) {
+    throw new CliError("config_error", "VIATRIS_API_KEY is required.", {
+      exitCode: 3,
+    });
+  }
+  if (!/^[A-Za-z0-9-]+$/.test(keyHeader)) {
+    throw new CliError("config_error", "API key header name is invalid.", {
+      exitCode: 3,
+    });
+  }
+
+  return {
+    baseUrl: baseUrl.replace(/\/+$/, ""),
+    environment,
+    apiKey,
+    keyHeader,
+    keyPrefix,
+    timeoutMs,
+    retries,
+  };
+}

package/src/errors.js

@@ -0,0 +1,14 @@
+export class CliError extends Error {
+  constructor(type, message, { exitCode = 2, details } = {}) {
+    super(message);
+    this.name = "CliError";
+    this.type = type;
+    this.exitCode = exitCode;
+    this.details = details;
+  }
+}
+
+export function normalizeError(error) {
+  if (error instanceof CliError) return error;
+  return new CliError("internal_error", error.message, { exitCode: 1 });
+}

package/src/help.js

@@ -0,0 +1,52 @@
+import { VERSION } from "./metadata.js";
+
+export function helpText() {
+  return `viatris-exam ${VERSION}
+
+Usage:
+  viatris-exam <resource> <action> [id|query] [options]
+  viatris-exam describe
+
+Commands:
+  products get <product-id>
+  products update-knowledge-tree <product-id> --input <file|->
+  gen-tasks list [--status STATUS] [--limit N]
+  gen-tasks get <task-id>
+  gen-tasks submit <task-id> --input <file|->
+  exam-records get <record-id>
+  exam-records scoring-rules <record-id>
+  scoring get <task-id>
+  scoring submit <task-id> --input <file|->
+  exams create --input <file|->
+  questions create --input <file|->
+  questions version <question-id> --input <file|->
+  medical-search search [query] [--file-type TYPE] [--limit N] [--max-length N]
+
+Input:
+  --input <file|->       Read a JSON object from a file or stdin.
+  --json <object>        Pass a JSON object inline.
+  Piped stdin            Used automatically by commands that require JSON.
+
+Global options:
+  --base-url <url>       Override the selected environment URL.
+  --key-header <name>    Override VIATRIS_API_KEY_HEADER (default: X-API-Key).
+  --key-prefix <value>   Override VIATRIS_API_KEY_PREFIX (default: empty).
+  --timeout <ms>         Request timeout (default: 30000).
+  --retries <n>          GET retries for 429/5xx/network errors (default: 2).
+  --compact              Emit compact JSON.
+  --help                 Show help.
+  --version              Show CLI version.
+
+Environment:
+  VIATRIS_API_ENV        API environment: production (default) or development.
+  VIATRIS_API_BASE_URL   Optional URL override with highest priority.
+  VIATRIS_API_KEY        Required API key. It cannot be passed as a CLI argument.
+  VIATRIS_API_KEY_HEADER Optional authentication header name.
+  VIATRIS_API_KEY_PREFIX Optional header value prefix, for example "Bearer ".
+
+Agent contract:
+  Successful API JSON is written to stdout. Structured errors are written to
+  stderr. Exit codes: 0 success, 1 API error, 2 usage/input error,
+  3 configuration error, 4 network/timeout error, 5 authentication error.
+`;
+}

package/src/http.js

@@ -0,0 +1,92 @@
+import { CliError } from "./errors.js";
+import { VERSION } from "./metadata.js";
+
+export function requestUrl(baseUrl, path) {
+  if (baseUrl.endsWith("/openapi") && path.startsWith("/openapi/")) {
+    return `${baseUrl}${path.slice("/openapi".length)}`;
+  }
+  return `${baseUrl}${path}`;
+}
+
+function sleep(milliseconds) {
+  return new Promise((resolve) => setTimeout(resolve, milliseconds));
+}
+
+function retryDelay(response, attempt) {
+  const retryAfter = response.headers.get("retry-after");
+  if (retryAfter && /^\d+$/.test(retryAfter)) {
+    return Math.min(Number(retryAfter) * 1000, 10_000);
+  }
+  return 250 * 2 ** attempt;
+}
+
+export async function request(command, config) {
+  const url = requestUrl(config.baseUrl, command.path);
+  const headers = {
+    Accept: "application/json",
+    "User-Agent": `viatris-exam-cli/${VERSION}`,
+    [config.keyHeader]: `${config.keyPrefix}${config.apiKey}`,
+  };
+  if (command.body !== undefined) headers["Content-Type"] = "application/json";
+
+  const maxAttempts = command.method === "GET" ? config.retries + 1 : 1;
+  let response;
+  for (let attempt = 0; attempt < maxAttempts; attempt += 1) {
+    try {
+      response = await fetch(url, {
+        method: command.method,
+        headers,
+        body:
+          command.body === undefined ? undefined : JSON.stringify(command.body),
+        signal: AbortSignal.timeout(config.timeoutMs),
+      });
+    } catch (error) {
+      if (attempt + 1 < maxAttempts && error.name !== "TimeoutError") {
+        await sleep(250 * 2 ** attempt);
+        continue;
+      }
+      const type = error.name === "TimeoutError" ? "timeout_error" : "network_error";
+      throw new CliError(type, error.message, {
+        exitCode: 4,
+        details: { method: command.method, path: command.path },
+      });
+    }
+
+    const retryable =
+      response.status === 429 || (response.status >= 500 && response.status <= 599);
+    if (!retryable || attempt + 1 >= maxAttempts) break;
+    await response.arrayBuffer();
+    await sleep(retryDelay(response, attempt));
+  }
+
+  const text = await response.text();
+  let data = null;
+  if (text) {
+    try {
+      data = JSON.parse(text);
+    } catch {
+      data = { raw: text };
+    }
+  }
+
+  if (!response.ok) {
+    throw new CliError(
+      "http_error",
+      `API request failed with HTTP ${response.status}.`,
+      {
+        exitCode: response.status === 401 || response.status === 403 ? 5 : 1,
+        details: {
+          status: response.status,
+          method: command.method,
+          path: command.path,
+          requestId:
+            response.headers.get("x-request-id") ??
+            response.headers.get("trace-id") ??
+            undefined,
+          response: data,
+        },
+      },
+    );
+  }
+  return data;
+}

package/src/input.js

@@ -0,0 +1,53 @@
+import { readFile } from "node:fs/promises";
+import { CliError } from "./errors.js";
+
+async function readStdin() {
+  const chunks = [];
+  for await (const chunk of process.stdin) chunks.push(chunk);
+  return Buffer.concat(chunks).toString("utf8");
+}
+
+export function hasPipedInput() {
+  return !process.stdin.isTTY;
+}
+
+export async function readJsonInput(options) {
+  const canReadStdin = hasPipedInput();
+  if (options.input !== undefined && options.json !== undefined) {
+    throw new CliError("usage_error", "Use only one of --input and --json.");
+  }
+
+  let source;
+  let text;
+  if (options.input !== undefined) {
+    source = options.input;
+    text = source === "-" ? await readStdin() : await readFile(source, "utf8");
+  } else if (options.json !== undefined) {
+    source = "--json";
+    text = options.json;
+  } else if (canReadStdin) {
+    source = "stdin";
+    text = await readStdin();
+  } else {
+    throw new CliError(
+      "usage_error",
+      "JSON input is required. Use --input <file>, --input -, --json <value>, or stdin.",
+    );
+  }
+
+  if (!text.trim()) {
+    throw new CliError("input_error", `JSON input from ${source} is empty.`);
+  }
+  try {
+    const value = JSON.parse(text);
+    if (value === null || Array.isArray(value) || typeof value !== "object") {
+      throw new Error("top-level value must be an object");
+    }
+    return value;
+  } catch (error) {
+    throw new CliError(
+      "input_error",
+      `Invalid JSON from ${source}: ${error.message}`,
+    );
+  }
+}