@toloka-platform/sdk 0.1.0-preview.3

package/src/cli/cost.ts

@@ -0,0 +1,144 @@
+import type { PipelineCostEstimate } from "../../openapi/gen/models";
+import type { PotatoClient } from "../client";
+import type { TolokaState } from "../state";
+import { resolvePipelineRef } from "./runs";
+
+export type CostCommandResult = {
+  readonly output: string;
+};
+
+type TableRow = readonly [string, string, string];
+
+type CostLine = {
+  readonly label: string;
+  readonly expectedTotal: string;
+  readonly maxTotal: string;
+  readonly subLines?: readonly unknown[];
+};
+
+const isCostLine = (value: unknown): value is CostLine => {
+  if (typeof value !== "object" || value === null) return false;
+  if (!("label" in value) || typeof value.label !== "string") return false;
+  if (!("expectedTotal" in value) || typeof value.expectedTotal !== "string") return false;
+  if (!("maxTotal" in value) || typeof value.maxTotal !== "string") return false;
+  if ("subLines" in value && value.subLines !== undefined && !Array.isArray(value.subLines)) {
+    return false;
+  }
+  return true;
+};
+
+const formatTable = (rows: readonly TableRow[]): string[] => {
+  const widths = [0, 0, 0];
+  for (const row of rows) {
+    for (let index = 0; index < 3; index += 1) {
+      const cell = row[index];
+      widths[index] = Math.max(widths[index] ?? 0, cell?.length ?? 0);
+    }
+  }
+
+  return rows.map((row) =>
+    row
+      .map((cell, index) =>
+        index === 0 ? cell.padEnd(widths[0] ?? 0) : cell.padStart(widths[index] ?? 0),
+      )
+      .join("  "),
+  );
+};
+
+const collectLineRows = (line: CostLine, depth: number): TableRow[] => {
+  const indent = "  ".repeat(depth);
+  const rows: TableRow[] = [[`${indent}${line.label}`, line.expectedTotal, line.maxTotal]];
+  for (const subLine of line.subLines ?? []) {
+    if (isCostLine(subLine)) rows.push(...collectLineRows(subLine, depth + 1));
+  }
+  return rows;
+};
+
+const collectNodeRows = (
+  nodes: PipelineCostEstimate["nodes"],
+): { billed: TableRow[]; unpriced: string[] } => {
+  const billed: TableRow[] = [];
+  const unpriced: string[] = [];
+
+  for (const node of nodes) {
+    if (node.kind === "priced") {
+      billed.push([node.nodeNameDisplay, node.expectedTotal, node.maxTotal]);
+      for (const line of node.displayBreakdown) {
+        if (isCostLine(line)) billed.push(...collectLineRows(line, 1));
+      }
+      continue;
+    }
+
+    unpriced.push(
+      node.kind === "validation-errors"
+        ? `  ${node.nodeNameDisplay}  skipped (validation errors)`
+        : `  ${node.nodeNameDisplay}  not billed`,
+    );
+  }
+
+  return { billed, unpriced };
+};
+
+const collectTotalRows = (total: PipelineCostEstimate["total"]): TableRow[] => {
+  const totals: TableRow[] = [["Total", total.expected, total.worstCase]];
+  if (total.bestCase != null) {
+    totals.push(["Best case", total.bestCase, ""]);
+  }
+  if (total.perItemExpected != null) {
+    totals.push(["Per item", total.perItemExpected, total.perItemWorstCase ?? ""]);
+  }
+  return totals;
+};
+
+export const formatCostEstimate = (
+  estimate: PipelineCostEstimate,
+  pipelineName: string,
+): string => {
+  const { billed, unpriced } = collectNodeRows(estimate.nodes);
+  const totals = collectTotalRows(estimate.total);
+  const table = formatTable([["Item", "Expected", "Maximum"], ...billed, ...totals]);
+  const billedRows = table.slice(0, 1 + billed.length);
+  const totalRows = table.slice(1 + billed.length);
+
+  const output = [
+    `Cost estimate for ${pipelineName}  ${estimate.dataset.itemCount} item${estimate.dataset.itemCount === 1 ? "" : "s"}`,
+    "",
+    ...billedRows,
+  ];
+
+  if (billed.length === 0) {
+    output.push("  (no billed nodes)");
+  }
+
+  output.push("", ...totalRows);
+
+  if (unpriced.length > 0) {
+    output.push("", "Not billed", ...unpriced);
+  }
+
+  if (estimate.isInternalPricing === true) {
+    output.push("", "Internal-team pricing.");
+  }
+
+  output.push("", estimate.disclaimer);
+  return output.join("\n");
+};
+
+export async function estimatePipelineCost(
+  client: PotatoClient,
+  options: {
+    readonly projectId: string;
+    readonly state?: TolokaState;
+    readonly pipeline?: string;
+    readonly itemLimit?: number;
+    readonly select?: (choices: readonly { name: string; value: string }[]) => Promise<string>;
+  },
+): Promise<CostCommandResult> {
+  const ref = await resolvePipelineRef({ client, ...options });
+  const estimate = await client.pipelines.estimateCost({
+    pipelineId: ref.pipelineId,
+    ...(options.itemLimit === undefined ? {} : { itemLimit: options.itemLimit }),
+  });
+
+  return { output: formatCostEstimate(estimate, ref.name) };
+}

package/src/cli/credentials.ts

@@ -0,0 +1,285 @@
+import { assert } from "es-toolkit";
+import { chmod, lstat, mkdir, readFile, rm, stat, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+
+export type StoredProjectAlias = {
+  readonly id: string;
+  readonly name?: string;
+};
+
+export type StoredCredentials = {
+  readonly baseUrl: string;
+  readonly apiKey: string;
+  readonly current?: string;
+  readonly projects?: Readonly<Record<string, StoredProjectAlias>>;
+};
+
+export type CliEnvironment = Readonly<Record<string, string | undefined>>;
+
+export type FoundCredentials = {
+  readonly credentials: StoredCredentials;
+  readonly path: string;
+  readonly legacy: boolean;
+};
+
+export type CommandCredentialLookup = {
+  readonly found: FoundCredentials | undefined;
+  readonly warning?: string;
+};
+
+export class CredentialsError extends Error {
+  constructor(message: string, options?: { readonly cause?: unknown }) {
+    super(message, options);
+    this.name = "CredentialsError";
+  }
+}
+
+export type InspectedCredentialsFile =
+  | "missing"
+  | "invalid"
+  | { readonly credentials: StoredCredentials };
+
+const home = (environment: CliEnvironment) => environment.HOME ?? homedir();
+
+const configHome = (environment: CliEnvironment) =>
+  environment.XDG_CONFIG_HOME ?? join(home(environment), ".config");
+
+export const credentialsPath = (environment: CliEnvironment = process.env): string =>
+  environment.TOLOKA_CREDENTIALS_FILE ??
+  join(configHome(environment), "toloka", "credentials.json");
+
+export const legacyCredentialsPath = (environment: CliEnvironment = process.env): string =>
+  join(home(environment), ".toloka", "credentials.json");
+
+export const normalizeBaseUrl = (baseUrl: string): string => {
+  const trimmed = baseUrl.trim().replace(/\/+$/u, "");
+  try {
+    const url = new URL(trimmed);
+    url.hash = "";
+    url.search = "";
+    return url.toString().replace(/\/+$/u, "");
+  } catch {
+    return trimmed;
+  }
+};
+
+const readField = (payload: unknown, key: string): unknown =>
+  typeof payload === "object" && payload !== null ? Reflect.get(payload, key) : undefined;
+
+const asProjectAlias = (value: unknown): StoredProjectAlias | undefined => {
+  if (typeof value !== "object" || value === null) return undefined;
+  const id = Reflect.get(value, "id");
+  if (typeof id !== "string" || id.length === 0) return undefined;
+  const name = Reflect.get(value, "name");
+  if (name !== undefined && typeof name !== "string") return undefined;
+  return name === undefined ? { id } : { id, name };
+};
+
+const asProjectMap = (projectsField: unknown): Record<string, StoredProjectAlias> | undefined => {
+  if (
+    projectsField === undefined ||
+    typeof projectsField !== "object" ||
+    projectsField === null ||
+    Array.isArray(projectsField)
+  ) {
+    return undefined;
+  }
+
+  const projects = Object.create(null) as Record<string, StoredProjectAlias>;
+  for (const [alias, value] of Object.entries(projectsField)) {
+    if (alias.length === 0) return undefined;
+    const project = asProjectAlias(value);
+    if (project === undefined) return undefined;
+    Object.defineProperty(projects, alias, {
+      value: project,
+      writable: true,
+      enumerable: true,
+      configurable: true,
+    });
+  }
+  return projects;
+};
+
+const asProjectRegistry = (
+  projectsField: unknown,
+  currentField: unknown,
+):
+  | { readonly current?: string; readonly projects?: Record<string, StoredProjectAlias> }
+  | undefined => {
+  const projects = asProjectMap(projectsField);
+  if (projects === undefined) return undefined;
+
+  if (typeof currentField === "string") {
+    if (currentField.length === 0 || !Object.hasOwn(projects, currentField)) return undefined;
+    return { current: currentField, projects };
+  }
+  if (currentField !== undefined) return undefined;
+  return Object.keys(projects).length === 0 ? {} : { projects };
+};
+
+const asCredentials = (payload: unknown): StoredCredentials | undefined => {
+  const baseUrl = readField(payload, "baseUrl");
+  const apiKey = readField(payload, "apiKey");
+  if (typeof baseUrl !== "string" || baseUrl.length === 0) return undefined;
+  if (typeof apiKey !== "string" || apiKey.length === 0) return undefined;
+
+  const currentField = readField(payload, "current");
+  const projectsField = readField(payload, "projects");
+  if (currentField === undefined && projectsField === undefined) return { baseUrl, apiKey };
+
+  const registry = asProjectRegistry(projectsField, currentField);
+  if (registry === undefined) return undefined;
+  return { baseUrl, apiKey, ...registry };
+};
+
+export async function inspectCredentialsFile(path: string): Promise<InspectedCredentialsFile> {
+  let raw: string;
+  try {
+    raw = await readFile(path, "utf8");
+  } catch (error) {
+    if (error instanceof Error && "code" in error && error.code === "ENOENT") return "missing";
+    return "invalid";
+  }
+
+  try {
+    const credentials = asCredentials(JSON.parse(raw));
+    return credentials === undefined ? "invalid" : { credentials };
+  } catch {
+    return "invalid";
+  }
+}
+
+export async function findStoredCredentials(
+  environment: CliEnvironment = process.env,
+): Promise<FoundCredentials | undefined> {
+  const path = credentialsPath(environment);
+  const primary = await inspectCredentialsFile(path);
+  if (primary !== "missing") {
+    if (primary === "invalid") {
+      throw new CredentialsError(
+        `Invalid credentials file at ${path}. Run toloka logout, then toloka login.`,
+      );
+    }
+    return { credentials: primary.credentials, path, legacy: false };
+  }
+
+  if (environment.TOLOKA_CREDENTIALS_FILE !== undefined) return undefined;
+
+  const legacyPath = legacyCredentialsPath(environment);
+  const legacy = await inspectCredentialsFile(legacyPath);
+  if (legacy === "missing") return undefined;
+  if (legacy === "invalid") {
+    throw new CredentialsError(
+      `Invalid credentials file at ${legacyPath}. Run toloka logout, then toloka login.`,
+    );
+  }
+  return { credentials: legacy.credentials, path: legacyPath, legacy: true };
+}
+
+export async function findCommandCredentials(
+  environment: CliEnvironment,
+  overrideApiKey: string | undefined,
+): Promise<CommandCredentialLookup> {
+  try {
+    return { found: await findStoredCredentials(environment) };
+  } catch (error) {
+    if (!(error instanceof CredentialsError) || overrideApiKey === undefined) throw error;
+    return { found: undefined, warning: error.message };
+  }
+}
+
+export async function readStoredCredentials(
+  environment: CliEnvironment = process.env,
+): Promise<StoredCredentials | undefined> {
+  return (await findStoredCredentials(environment))?.credentials;
+}
+
+export async function requireStoredCredentials(
+  environment: CliEnvironment = process.env,
+): Promise<FoundCredentials> {
+  const found = await findStoredCredentials(environment);
+  if (found !== undefined) return found;
+  throw new CredentialsError(
+    `No stored credentials found at ${credentialsPath(environment)}. Run toloka login.`,
+  );
+}
+
+const serializedCredentials = (credentials: StoredCredentials): StoredCredentials => {
+  const projects = credentials.projects;
+  const hasProjects = projects !== undefined && Object.keys(projects).length > 0;
+  return {
+    baseUrl: credentials.baseUrl,
+    apiKey: credentials.apiKey,
+    ...(credentials.current === undefined ? {} : { current: credentials.current }),
+    ...(hasProjects ? { projects } : {}),
+  };
+};
+
+const assertNotSymbolicLink = async (path: string): Promise<void> => {
+  try {
+    const entry = await lstat(path);
+    assert(!entry.isSymbolicLink(), `Refusing to write through symbolic link ${path}.`);
+  } catch (error) {
+    if (error instanceof Error && "code" in error && error.code === "ENOENT") return;
+    throw error;
+  }
+};
+
+export async function preparePrivateFilePath(path: string): Promise<void> {
+  const directory = dirname(path);
+  await assertNotSymbolicLink(directory);
+  await assertNotSymbolicLink(path);
+  await mkdir(directory, { recursive: true, mode: 0o700 });
+  await chmod(directory, 0o700);
+}
+
+export async function writeStoredCredentials(
+  credentials: StoredCredentials,
+  environment: CliEnvironment = process.env,
+): Promise<string> {
+  const path = credentialsPath(environment);
+  await preparePrivateFilePath(path);
+  await writeFile(path, `${JSON.stringify(serializedCredentials(credentials), null, 2)}\n`, {
+    mode: 0o600,
+  });
+  await chmod(path, 0o600);
+  return path;
+}
+
+const fileExists = async (path: string): Promise<boolean> => {
+  try {
+    await stat(path);
+    return true;
+  } catch (error) {
+    if (error instanceof Error && "code" in error && error.code === "ENOENT") return false;
+    throw error;
+  }
+};
+
+export async function clearStoredCredentials(
+  environment: CliEnvironment = process.env,
+): Promise<string[]> {
+  const removed: string[] = [];
+  const paths = [
+    credentialsPath(environment),
+    ...(environment.TOLOKA_CREDENTIALS_FILE === undefined
+      ? [legacyCredentialsPath(environment)]
+      : []),
+  ];
+
+  for (const path of paths) {
+    if (!(await fileExists(path))) continue;
+    await rm(path, { force: true });
+    removed.push(path);
+  }
+
+  return removed;
+}
+
+const MASK_REVEALS_EDGES_ABOVE = 16;
+
+export const maskApiKey = (apiKey: string): string =>
+  apiKey.length > MASK_REVEALS_EDGES_ABOVE
+    ? `${apiKey.slice(0, 4)}${"*".repeat(apiKey.length - 8)}${apiKey.slice(-4)}`
+    : "*".repeat(apiKey.length);