@toloka-platform/sdk 0.1.0-preview.3

package/src/cli/analytics.ts

@@ -0,0 +1,262 @@
+import { randomUUID } from "node:crypto";
+import { chmod, readFile, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { PostHog } from "posthog-node";
+import { PipelineGraphValidationError, PotatoApiError } from "../errors";
+import type { TolokaEnvironment } from "./config";
+import type { CliEnvironment } from "./credentials";
+import { credentialsPath, preparePrivateFilePath } from "./credentials";
+import { SDK_VERSION } from "./init";
+
+export const POSTHOG_PROJECT_KEY = "phc_kqHt0f53B5MVqURyzWpW1aNlbOmYt1YbUYza0JPcg19";
+export const POSTHOG_HOST = "https://eu.posthog.com";
+
+const ROOT_FLAGS_WITH_VALUE: Readonly<Record<string, true>> = {
+  "--source-root": true,
+  "--api-key": true,
+  "--base-url": true,
+  "--project-id": true,
+};
+
+export type CliAnalyticsCommandOutcome = "succeeded" | "failed" | "usage_error";
+
+export type CliAnalyticsCapture = {
+  readonly command: string;
+  readonly durationMs: number;
+  readonly exitCode: number;
+  readonly outcome: CliAnalyticsCommandOutcome;
+  readonly error?: unknown;
+};
+
+export type CliAnalytics = {
+  readonly shouldIdentify: boolean;
+  readonly identifyCurrentUser: (user: {
+    readonly id: string;
+    readonly email: string | null;
+  }) => void;
+  readonly captureCommand: (event: CliAnalyticsCapture) => void;
+  readonly shutdown: () => Promise<void>;
+};
+
+export type PosthogLike = {
+  capture: (event: {
+    distinctId: string;
+    event: string;
+    properties?: Record<string, unknown>;
+    disableGeoip: boolean;
+  }) => void;
+  alias: (event: { distinctId: string; alias: string }) => void;
+  shutdown: (shutdownTimeoutMs?: number) => Promise<void>;
+};
+
+const isTruthy = (value: string | undefined): boolean => {
+  if (value === undefined) return false;
+  const normalized = value.trim().toLowerCase();
+  return normalized === "1" || normalized === "true" || normalized === "yes" || normalized === "on";
+};
+
+const isFalsey = (value: string | undefined): boolean => {
+  if (value === undefined) return false;
+  const normalized = value.trim().toLowerCase();
+  return (
+    normalized === "0" || normalized === "false" || normalized === "no" || normalized === "off"
+  );
+};
+
+export function telemetryEnabled(environment: CliEnvironment): boolean {
+  const explicit = environment.TOLOKA_TELEMETRY ?? process.env.TOLOKA_TELEMETRY;
+  if (isFalsey(explicit)) return false;
+  if (isTruthy(explicit)) return true;
+  if (isTruthy(environment.DO_NOT_TRACK ?? process.env.DO_NOT_TRACK)) return false;
+  if (isTruthy(environment.CI ?? process.env.CI)) return false;
+  if (isTruthy(process.env.VITEST)) return false;
+  return true;
+}
+
+const COMMAND_GROUPS: Readonly<Record<string, Readonly<Record<string, true>>>> = {
+  project: { list: true, add: true, switch: true, current: true, remove: true, create: true },
+  pipeline: {
+    list: true,
+    run: true,
+    status: true,
+    runs: true,
+    cost: true,
+    cancel: true,
+    results: true,
+  },
+  dataset: { list: true, fields: true, load: true, upload: true },
+  secret: { set: true },
+};
+
+const ROOT_COMMANDS: Readonly<Record<string, true>> = {
+  apply: true,
+  "auth-status": true,
+  help: true,
+  import: true,
+  init: true,
+  login: true,
+  logout: true,
+  plan: true,
+  status: true,
+  validate: true,
+  whoami: true,
+};
+
+const nameFromTokens = (tokens: readonly string[]): string => {
+  const command = tokens[0];
+  if (command === undefined) return "help";
+
+  const subcommands = COMMAND_GROUPS[command];
+  if (subcommands === undefined) return ROOT_COMMANDS[command] === true ? command : "unknown";
+
+  const subcommand = tokens[1];
+  return subcommand !== undefined && subcommands[subcommand] === true
+    ? `${command} ${subcommand}`
+    : command;
+};
+
+export function commandNameFromArgv(argv: readonly string[]): string {
+  const tokens: string[] = [];
+  for (let index = 0; index < argv.length; index += 1) {
+    const token = argv[index];
+    if (token === undefined) continue;
+    if (token === "--help" || token === "-h") break;
+    if (token.startsWith("-")) {
+      if (ROOT_FLAGS_WITH_VALUE[token] === true) index += 1;
+      continue;
+    }
+    tokens.push(token);
+  }
+  return nameFromTokens(tokens);
+}
+
+export function classifyCliError(error: unknown): { readonly error_code: string } {
+  if (error === undefined) return { error_code: "command_failed" };
+  if (error instanceof PotatoApiError || error instanceof PipelineGraphValidationError) {
+    return { error_code: error.code };
+  }
+  return { error_code: error instanceof Error ? "error" : "unknown" };
+}
+
+const anonymousIdPath = (environment: CliEnvironment): string =>
+  join(dirname(credentialsPath(environment)), "anonymous-id");
+
+const readAnonymousId = async (environment: CliEnvironment): Promise<string> => {
+  const path = anonymousIdPath(environment);
+  await preparePrivateFilePath(path);
+  try {
+    const existing = (await readFile(path, "utf8")).trim();
+    if (existing.length > 0) {
+      await chmod(path, 0o600);
+      return existing;
+    }
+  } catch (error) {
+    if (!(error instanceof Error && "code" in error && error.code === "ENOENT")) throw error;
+  }
+  const created = randomUUID();
+  await writeFile(path, `${created}\n`, { mode: 0o600 });
+  await chmod(path, 0o600);
+  return created;
+};
+
+const noopAnalytics = (): CliAnalytics => ({
+  shouldIdentify: false,
+  identifyCurrentUser() {},
+  captureCommand() {},
+  async shutdown() {},
+});
+
+export function createCliAnalytics(options: {
+  readonly environment: TolokaEnvironment;
+  readonly client?: PosthogLike;
+  readonly distinctId?: string;
+}): CliAnalytics {
+  const { environment } = options;
+  if (options.client === undefined && !telemetryEnabled(environment)) return noopAnalytics();
+
+  let client = options.client;
+  let distinctId = options.distinctId;
+  let identifiedUserId: string | undefined;
+
+  const ensure = async () => {
+    if (client !== undefined && distinctId !== undefined) return;
+    if (client === undefined) {
+      const created = new PostHog(POSTHOG_PROJECT_KEY, {
+        host: POSTHOG_HOST,
+        flushAt: 1,
+        flushInterval: 0,
+      });
+      created.on("error", () => {});
+      client = created;
+    }
+    distinctId ??= await readAnonymousId(environment);
+  };
+
+  const sharedProperties = () => ({
+    sdk_version: SDK_VERSION,
+    bun_version: typeof process.versions.bun === "string" ? process.versions.bun : undefined,
+    actor: "user",
+    channel: "cli",
+  });
+
+  let queue: Promise<void> = ensure().catch(() => {});
+
+  return {
+    shouldIdentify: true,
+    identifyCurrentUser(user) {
+      queue = queue
+        .then(() => {
+          if (client === undefined || distinctId === undefined) return;
+          if (identifiedUserId === user.id) return;
+          identifiedUserId = user.id;
+          if (distinctId !== user.id) {
+            client.alias({ distinctId: user.id, alias: distinctId });
+          }
+          distinctId = user.id;
+        })
+        .catch(() => {});
+    },
+    captureCommand(event) {
+      queue = queue
+        .then(() => {
+          if (client === undefined || distinctId === undefined) return;
+          const shared = sharedProperties();
+          if (event.outcome === "failed") {
+            const classified = classifyCliError(event.error);
+            client.capture({
+              distinctId,
+              event: "sdk_cli_command_failed",
+              disableGeoip: true,
+              properties: {
+                ...shared,
+                command: nameFromTokens(event.command.split(" ")),
+                duration_ms: event.durationMs,
+                exit_code: event.exitCode,
+                ...classified,
+              },
+            });
+            return;
+          }
+          client.capture({
+            distinctId,
+            event: "sdk_cli_command_completed",
+            disableGeoip: true,
+            properties: {
+              ...shared,
+              command: nameFromTokens(event.command.split(" ")),
+              duration_ms: event.durationMs,
+              exit_code: event.exitCode,
+              outcome: event.outcome,
+            },
+          });
+        })
+        .catch(() => {});
+    },
+    async shutdown() {
+      try {
+        await queue;
+        await client?.shutdown(2000);
+      } catch {}
+    },
+  };
+}

package/src/cli/auth.ts

@@ -0,0 +1,269 @@
+import { assert } from "es-toolkit";
+import { createClient } from "../client";
+import { PRODUCTION_BASE_URL, consoleUrlFor, resolveInternalBaseUrl } from "./config";
+import {
+  clearStoredCredentials,
+  credentialsPath,
+  findCommandCredentials,
+  inspectCredentialsFile,
+  maskApiKey,
+  normalizeBaseUrl,
+  writeStoredCredentials,
+} from "./credentials";
+import type {
+  CliEnvironment,
+  CommandCredentialLookup,
+  FoundCredentials,
+  StoredCredentials,
+} from "./credentials";
+import type { ProjectContext } from "./project-context";
+import { formatProjectContextLine } from "./project-context";
+
+export const apiKeyInstructions = (baseUrl: string): string => {
+  const console = consoleUrlFor(baseUrl);
+  const where =
+    console === undefined
+      ? [
+          `An API key identifies you to ${baseUrl}. Generate one in the console that`,
+          "serves this platform, under Company -> API Keys -> Generate API Key.",
+        ]
+      : [
+          `An API key identifies you to ${baseUrl}. To generate one:`,
+          "",
+          `  1. open ${console}`,
+          "  2. go to Company -> API Keys",
+          "  3. press Generate API Key and copy it",
+        ];
+
+  return [
+    ...where,
+    "",
+    "The key is shown once. Treat it like a password: it is stored with owner-only",
+    "permissions and never printed back to you.",
+  ].join("\n");
+};
+
+export type AuthPrompt = (
+  question: string,
+  options?: { readonly mask?: boolean },
+) => Promise<string>;
+
+export type AuthProbe = {
+  readonly projects: {
+    readonly listPage: (params: { readonly limit: number }) => Promise<{
+      readonly pagination: { readonly total: number };
+    }>;
+  };
+};
+
+export type LoginOptions = {
+  readonly apiKey?: string;
+  readonly baseUrl?: string;
+  readonly prompt?: AuthPrompt;
+  readonly environment?: CliEnvironment;
+  readonly probe?: (credentials: StoredCredentials) => AuthProbe;
+  readonly write?: (text: string) => void;
+};
+
+export type LoginResult = {
+  readonly credentialsFile: string;
+  readonly baseUrl: string;
+  readonly output: string;
+};
+
+export async function login(options: LoginOptions = {}): Promise<LoginResult> {
+  const environment = options.environment ?? process.env;
+  const write = options.write ?? (() => undefined);
+  const baseUrl = (
+    options.baseUrl ??
+    environment.POTATO_BASE_URL ??
+    resolveInternalBaseUrl(environment) ??
+    PRODUCTION_BASE_URL
+  ).replace(/\/+$/u, "");
+
+  let apiKey = options.apiKey;
+  if (apiKey === undefined) {
+    assert(
+      options.prompt,
+      "Missing API key. Pass --api-key, or set POTATO_API_KEY, when stdin is not a terminal.",
+    );
+    write(`\n${apiKeyInstructions(baseUrl)}\n`);
+    apiKey = (await options.prompt("API key: ", { mask: true })).trim();
+  }
+  assert(apiKey.length > 0, "No API key entered.");
+  const credentials: StoredCredentials = { baseUrl, apiKey };
+  const probe: AuthProbe = options.probe?.(credentials) ?? createClient(credentials);
+
+  let reachable: string;
+  try {
+    const page = await probe.projects.listPage({ limit: 1 });
+    reachable = `Authenticated against ${baseUrl}: ${page.pagination.total} project(s) visible.`;
+  } catch (error) {
+    const reason = error instanceof Error ? error.message : String(error);
+    throw new Error(
+      [
+        `Could not authenticate against ${baseUrl}: ${reason}`,
+        "",
+        "Nothing was saved. Check that the key was copied whole and has not been revoked.",
+      ].join("\n"),
+      { cause: error },
+    );
+  }
+
+  const existingPath = credentialsPath(environment);
+  const existing = await inspectCredentialsFile(existingPath);
+  const merged: StoredCredentials =
+    typeof existing === "object" &&
+    normalizeBaseUrl(existing.credentials.baseUrl) === normalizeBaseUrl(baseUrl)
+      ? {
+          baseUrl,
+          apiKey,
+          ...(existing.credentials.current === undefined
+            ? {}
+            : { current: existing.credentials.current }),
+          ...(existing.credentials.projects === undefined
+            ? {}
+            : { projects: existing.credentials.projects }),
+        }
+      : credentials;
+
+  const credentialsFile = await writeStoredCredentials(merged, environment);
+
+  return {
+    credentialsFile,
+    baseUrl,
+    output: [
+      reachable,
+      `Saved credentials to ${credentialsFile}.`,
+      "",
+      "toloka reads them automatically. --api-key and POTATO_API_KEY still win when set.",
+    ].join("\n"),
+  };
+}
+
+export type LogoutResult = { readonly removed: readonly string[]; readonly output: string };
+
+export async function logout(environment: CliEnvironment = process.env): Promise<LogoutResult> {
+  const removed = await clearStoredCredentials(environment);
+
+  return {
+    removed,
+    output:
+      removed.length === 0
+        ? `No stored credentials found at ${credentialsPath(environment)}.`
+        : `Removed ${removed.join(", ")}.\n\nThis does not revoke the key. Delete it in console.toloka.ai to do that.`,
+  };
+}
+
+export type AuthStatusOptions = {
+  readonly environment?: CliEnvironment;
+  readonly showToken?: boolean;
+  readonly flagApiKey?: string;
+  readonly flagBaseUrl?: string;
+  readonly probe?: (credentials: StoredCredentials) => AuthProbe;
+  readonly credentialLookup?: CommandCredentialLookup;
+  readonly project?: ProjectContext;
+};
+
+export type AuthStatusResult = { readonly authenticated: boolean; readonly output: string };
+
+type ResolvedValue = { readonly value: string; readonly source: string };
+
+const firstDefined = (
+  candidates: ReadonlyArray<ResolvedValue | undefined>,
+): ResolvedValue | undefined => candidates.find((candidate) => candidate !== undefined);
+
+const resolveApiKey = (
+  options: AuthStatusOptions,
+  environment: CliEnvironment,
+  found: FoundCredentials | undefined,
+  storedPath: string,
+): ResolvedValue | undefined =>
+  firstDefined([
+    options.flagApiKey === undefined
+      ? undefined
+      : { value: options.flagApiKey, source: "from --api-key" },
+    environment.POTATO_API_KEY === undefined
+      ? undefined
+      : { value: environment.POTATO_API_KEY, source: "from POTATO_API_KEY" },
+    found === undefined
+      ? undefined
+      : { value: found.credentials.apiKey, source: `stored in ${storedPath}` },
+  ]);
+
+const resolvePlatform = (
+  options: AuthStatusOptions,
+  environment: CliEnvironment,
+  found: FoundCredentials | undefined,
+): ResolvedValue => {
+  const internalBaseUrl = resolveInternalBaseUrl(environment);
+  return (
+    firstDefined([
+      options.flagBaseUrl === undefined
+        ? undefined
+        : { value: options.flagBaseUrl.replace(/\/+$/u, ""), source: "from --base-url" },
+      environment.POTATO_BASE_URL === undefined
+        ? undefined
+        : { value: environment.POTATO_BASE_URL, source: "from POTATO_BASE_URL" },
+      internalBaseUrl === undefined
+        ? undefined
+        : { value: internalBaseUrl, source: `from ENV=${environment.ENV}` },
+      found === undefined ? undefined : { value: found.credentials.baseUrl, source: "stored" },
+    ]) ?? { value: PRODUCTION_BASE_URL, source: "default" }
+  );
+};
+
+export async function authStatus(options: AuthStatusOptions = {}): Promise<AuthStatusResult> {
+  const environment = options.environment ?? process.env;
+  const credentialLookup =
+    options.credentialLookup ??
+    (await findCommandCredentials(environment, options.flagApiKey ?? environment.POTATO_API_KEY));
+  const { found, warning } = credentialLookup;
+  const storedPath = found?.path ?? credentialsPath(environment);
+  const apiKey = resolveApiKey(options, environment, found, storedPath);
+  const platform = resolvePlatform(options, environment, found);
+  const projectLine = formatProjectContextLine(options.project, found?.credentials);
+
+  const lines: string[] = warning === undefined ? [] : [warning, ""];
+
+  if (apiKey === undefined) {
+    lines.push(
+      "Not logged in.",
+      "",
+      "Run toloka login to store an API key for this machine.",
+      "",
+      projectLine,
+    );
+    return { authenticated: false, output: lines.join("\n") };
+  }
+
+  const { value: baseUrl, source: urlSource } = platform;
+  lines.push(
+    `Platform: ${baseUrl} (${urlSource})`,
+    `API key:  ${options.showToken === true ? apiKey.value : maskApiKey(apiKey.value)} (${apiKey.source})`,
+    projectLine,
+  );
+
+  if (environment.POTATO_API_KEY !== undefined && found !== undefined) {
+    lines.push("", `POTATO_API_KEY is set, so the key stored in ${found.path} is ignored.`);
+  }
+  if (found?.legacy === true) {
+    lines.push(
+      "",
+      `Credentials still live at the old path ${found.path}. Run toloka login to move them to ${credentialsPath(environment)}.`,
+    );
+  }
+
+  const probe: AuthProbe =
+    options.probe?.({ baseUrl, apiKey: apiKey.value }) ??
+    createClient({ baseUrl, apiKey: apiKey.value });
+  try {
+    const page = await probe.projects.listPage({ limit: 1 });
+    lines.push("", `Reachable: ${page.pagination.total} project(s) visible.`);
+    return { authenticated: true, output: lines.join("\n") };
+  } catch (error) {
+    const reason = error instanceof Error ? error.message : String(error);
+    lines.push("", `Not reachable: ${reason}`, "", "Run toloka login to store a working key.");
+    return { authenticated: false, output: lines.join("\n") };
+  }
+}

package/src/cli/bin.ts

@@ -0,0 +1,4 @@
+#!/usr/bin/env bun
+import { runTolokaCli } from './program';
+
+process.exitCode = await runTolokaCli(process.argv.slice(2));

package/src/cli/config.ts

@@ -0,0 +1,82 @@
+import { assert } from "es-toolkit";
+import type { TolokaState } from "../state";
+import type { StoredCredentials } from "./credentials";
+import { resolveProjectContext } from "./project-context";
+
+export type TolokaCliFlags = {
+  readonly apiKey?: string;
+  readonly baseUrl?: string;
+  readonly projectId?: string;
+};
+
+export type TolokaEnvironment = Readonly<Record<string, string | undefined>> & {
+  readonly POTATO_API_KEY?: string;
+  readonly POTATO_BASE_URL?: string;
+  readonly POTATO_PROJECT_ID?: string;
+  readonly TOLOKA_PROJECT_ID?: string;
+};
+
+export type ResolvedTolokaConfig = {
+  readonly apiKey: string;
+  readonly baseUrl: string;
+  readonly projectId?: string;
+};
+
+export const PRODUCTION_BASE_URL = "https://platform.toloka.ai";
+
+const INTERNAL_ENVIRONMENT = /^(?:prestable|pr-\d+)$/u;
+
+export const resolveInternalBaseUrl = (environment: TolokaEnvironment): string | undefined => {
+  const name = environment.ENV?.trim();
+  if (name === undefined || !INTERNAL_ENVIRONMENT.test(name)) return undefined;
+  return `https://${name}.platform.toloka-test.ai`;
+};
+
+const PRODUCTION_CONSOLE_URL = "https://console.toloka.ai";
+const INTERNAL_CONSOLE_URL = "https://prestable.console.toloka-test.ai";
+
+export const consoleUrlFor = (baseUrl: string): string | undefined => {
+  let host: string;
+  try {
+    host = new URL(baseUrl).host;
+  } catch {
+    return undefined;
+  }
+
+  if (host === "platform.toloka.ai") return PRODUCTION_CONSOLE_URL;
+  if (host.endsWith(".platform.toloka-test.ai")) return INTERNAL_CONSOLE_URL;
+  return undefined;
+};
+
+const missingApiKeyMessage = [
+  "Missing API key. Run toloka login once to store credentials for this machine:",
+  "",
+  "  toloka login",
+  "",
+  "It explains how to generate an API key and where it is saved. To override per command,",
+  "pass --api-key or set POTATO_API_KEY. Run toloka auth-status to see what is in effect.",
+].join("\n");
+
+export function resolveTolokaConfig(
+  flags: TolokaCliFlags,
+  state: TolokaState | undefined,
+  environment: TolokaEnvironment,
+  stored?: StoredCredentials,
+): ResolvedTolokaConfig {
+  const apiKey = flags.apiKey ?? environment.POTATO_API_KEY ?? stored?.apiKey;
+  const baseUrl =
+    flags.baseUrl ??
+    environment.POTATO_BASE_URL ??
+    resolveInternalBaseUrl(environment) ??
+    stored?.baseUrl ??
+    PRODUCTION_BASE_URL;
+  const project = resolveProjectContext({
+    flags,
+    state,
+    environment,
+    stored,
+    effectiveBaseUrl: baseUrl,
+  });
+  assert(apiKey, missingApiKeyMessage);
+  return { apiKey, baseUrl, ...(project === undefined ? {} : { projectId: project.id }) };
+}