@toloka-platform/sdk 0.2.0-preview.2 → 0.2.0-preview.4

package/src/checks/task-ui-typecheck.ts

@@ -265,6 +265,16 @@ const mapParseErrorsToBlocks = (
   return report;
 };
 
+const runtimeSyntaxReport = (source: string): TaskUiDiagnosticsReport => {
+  const jsxReport = mapParseErrorsToBlocks(source, parseSync("runtime.jsx", source).errors);
+  const tsxReport = mapParseErrorsToBlocks(source, parseSync("runtime.tsx", source).errors);
+  return {
+    ...tsxReport,
+    preprocess: jsxReport.preprocess,
+    postprocess: jsxReport.postprocess,
+  };
+};
+
 export const createTaskUiTypechecker = ({
   reactDeclaration,
   elementsDeclaration,
@@ -311,11 +321,7 @@ export const createTaskUiTypechecker = ({
       ...syntacticDiagnostics,
       ...otherDiagnostics,
     ]);
-    const runtimeSource = buildRuntimeSource(input);
-    const runtimeReport = mapParseErrorsToBlocks(
-      runtimeSource,
-      parseSync("runtime.jsx", runtimeSource).errors,
-    );
+    const runtimeReport = runtimeSyntaxReport(buildRuntimeSource(input));
     return mergeRuntimeDiagnostics(typeScriptReport, syntacticReport, runtimeReport);
   },
 
@@ -325,11 +331,7 @@ export const createTaskUiTypechecker = ({
       typeScriptSource,
       parseSync(FILE_NAME, typeScriptSource).errors,
     );
-    const runtimeSource = buildRuntimeSource(input);
-    const runtimeReport = mapParseErrorsToBlocks(
-      runtimeSource,
-      parseSync("runtime.jsx", runtimeSource).errors,
-    );
+    const runtimeReport = runtimeSyntaxReport(buildRuntimeSource(input));
     return mergeRuntimeDiagnostics(typeScriptReport, typeScriptReport, runtimeReport);
   },
 });

package/src/cli/analytics.ts

@@ -1,14 +1,15 @@
-import { assert } from "es-toolkit";
 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 { PipelineGraphValidationError } from "../errors";
 import type { TolokaEnvironment } from "./config";
 import type { CliEnvironment } from "./credentials";
 import { credentialsPath, preparePrivateFilePath } from "./credentials";
 import { isFalseyFlag, isTruthyFlag } from "./boolean-flag";
-import { SDK_VERSION } from "./init";
+import { SDK_VERSION } from "./sdk-version";
+import { assertCli, TolokaCliError } from "./cli-error";
+import { findPotatoApiError } from "./format-error";
 
 export const POSTHOG_PROJECT_KEY = "phc_kqHt0f53B5MVqURyzWpW1aNlbOmYt1YbUYza0JPcg19";
 export const POSTHOG_HOST = "https://eu.posthog.com";
@@ -56,6 +57,11 @@ export type PosthogLike = {
     properties?: Record<string, unknown>;
     disableGeoip: boolean;
   }) => void;
+  captureException: (
+    error: unknown,
+    distinctId: string,
+    properties?: Record<string, unknown>,
+  ) => void;
   alias: (event: { distinctId: string; alias: string }) => void;
   flush: () => Promise<void>;
   on?: (event: "error", listener: (error: Error) => void) => void;
@@ -72,7 +78,9 @@ export function telemetryEnabled(environment: CliEnvironment): boolean {
   return true;
 }
 
-const COMMAND_GROUPS: Readonly<Record<string, Readonly<Record<string, true>>>> = {
+type CommandGroup = Readonly<Record<string, true | Readonly<Record<string, true>>>>;
+
+const COMMAND_GROUPS: Readonly<Record<string, CommandGroup>> = {
   project: { list: true, add: true, switch: true, current: true, remove: true, create: true },
   pipeline: {
     list: true,
@@ -83,7 +91,31 @@ const COMMAND_GROUPS: Readonly<Record<string, Readonly<Record<string, true>>>> =
     cancel: true,
     results: true,
   },
-  dataset: { list: true, fields: true, load: true, upload: true },
+  dataset: { list: true, create: true, fields: true, load: true, upload: true },
+  "delivery-order": { list: true },
+  training: {
+    list: true,
+    get: true,
+    create: true,
+    update: true,
+    cost: true,
+    run: true,
+    runs: true,
+    status: true,
+    resume: true,
+    cancel: true,
+    metrics: true,
+    logs: true,
+  },
+  "base-model": { list: true, get: true },
+  model: {
+    list: true,
+    get: true,
+    versions: true,
+    create: true,
+    archive: true,
+    version: { download: true },
+  },
   secret: { set: true },
   skill: { list: true, search: true, install: true },
   config: { get: true, set: true },
@@ -115,9 +147,13 @@ const nameFromTokens = (tokens: readonly string[]): string => {
   if (subcommands === undefined) return ROOT_COMMANDS[command] === true ? command : "unknown";
 
   const subcommand = tokens[1];
-  return subcommand !== undefined && subcommands[subcommand] === true
-    ? `${command} ${subcommand}`
-    : command;
+  const nested = subcommand === undefined ? undefined : subcommands[subcommand];
+  if (nested === undefined) return command;
+  if (nested === true) return `${command} ${subcommand}`;
+  const leaf = tokens[2];
+  return leaf !== undefined && nested[leaf] === true
+    ? `${command} ${subcommand} ${leaf}`
+    : `${command} ${subcommand}`;
 };
 
 export function commandNameFromArgv(argv: readonly string[]): string {
@@ -138,12 +174,19 @@ export function commandNameFromArgv(argv: readonly string[]): string {
 
 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 };
-  }
+  const apiError = findPotatoApiError(error);
+  if (apiError !== undefined) return { error_code: apiError.code };
+  if (error instanceof PipelineGraphValidationError) return { error_code: error.code };
   return { error_code: error instanceof Error ? "error" : "unknown" };
 }
 
+const cliErrorProperties = (error: unknown): Record<string, unknown> => {
+  const apiError = findPotatoApiError(error);
+  return apiError === undefined
+    ? {}
+    : { status_code: apiError.status, request_id: apiError.requestId };
+};
+
 const anonymousIdPath = (environment: CliEnvironment): string =>
   join(dirname(credentialsPath(environment)), "anonymous-id");
 
@@ -171,7 +214,11 @@ const noopAnalytics = (): CliAnalytics => ({
   identifyCurrentUser() {},
   captureCommand() {},
   async submitIssueReport() {
-    assert(false, "Issue reporting is disabled. Re-run with TOLOKA_TELEMETRY=1.");
+    assertCli(
+      false,
+      "Issue reporting is disabled. Re-run with TOLOKA_TELEMETRY=1.",
+      { hint: { disabled: true } },
+    );
   },
   async shutdown() {},
 });
@@ -237,18 +284,40 @@ export function createCliAnalytics(options: {
         .then(() => {
           if (client === undefined || distinctId === undefined) return;
           const shared = sharedProperties();
+          const command = nameFromTokens(event.command.split(" "));
+
           if (event.outcome === "failed") {
             const classified = classifyCliError(event.error);
+            const errorProperties = cliErrorProperties(event.error);
+
+            if (event.error !== undefined) {
+              const exception = new TolokaCliError(`CLI command failed: ${classified.error_code}`, {
+                hint: { disabled: true },
+              });
+              exception.name = "PotatoCliError";
+              client.captureException(exception, distinctId, {
+                ...shared,
+                command,
+                duration_ms: event.durationMs,
+                exit_code: event.exitCode,
+                $process_person_profile: false,
+                $geoip_disable: true,
+                ...classified,
+                ...errorProperties,
+              });
+            }
+
             client.capture({
               distinctId,
               event: "sdk_cli_command_failed",
               disableGeoip: true,
               properties: {
                 ...shared,
-                command: nameFromTokens(event.command.split(" ")),
+                command,
                 duration_ms: event.durationMs,
                 exit_code: event.exitCode,
                 ...classified,
+                ...errorProperties,
               },
             });
             return;
@@ -259,7 +328,7 @@ export function createCliAnalytics(options: {
             disableGeoip: true,
             properties: {
               ...shared,
-              command: nameFromTokens(event.command.split(" ")),
+              command,
               duration_ms: event.durationMs,
               exit_code: event.exitCode,
               outcome: event.outcome,
@@ -270,7 +339,11 @@ export function createCliAnalytics(options: {
     },
     submitIssueReport(report) {
       const submission = queue.then(async () => {
-        assert(client && distinctId, "PostHog issue reporting could not be initialized.");
+        assertCli(
+          client && distinctId,
+          "PostHog issue reporting could not be initialized.",
+          { hint: { description: "Set TOLOKA_TELEMETRY=1 and check that this machine can reach PostHog, then retry." } },
+        );
         deliveryErrors.length = 0;
         client.capture({
           distinctId,

package/src/cli/auth.ts

@@ -1,5 +1,5 @@
-import { assert } from "es-toolkit";
 import { createClient } from "../client";
+import { PotatoApiError } from "../errors";
 import { PRODUCTION_BASE_URL, consoleUrlFor, resolveInternalBaseUrl } from "./config";
 import {
   clearStoredCredentials,
@@ -18,6 +18,41 @@ import type {
 } from "./credentials";
 import type { ProjectContext } from "./project-context";
 import { formatProjectContextLine } from "./project-context";
+import { assertCli, TolokaCliError } from "./cli-error";
+
+type ProbeFailureKind = "rejected" | "unreachable" | "platform";
+
+type ProbeFailure = { readonly kind: ProbeFailureKind; readonly reason: string };
+
+const classifyProbeFailure = (error: unknown): ProbeFailure => {
+  const reason = error instanceof Error ? error.message : String(error);
+  if (!(error instanceof PotatoApiError) || error.status === undefined)
+    return { kind: "unreachable", reason };
+  return {
+    kind: error.status === 401 || error.status === 403 ? "rejected" : "platform",
+    reason,
+  };
+};
+
+const PROBE_FAILURE_HEADLINE: Record<ProbeFailureKind, string> = {
+  rejected: "Rejected",
+  unreachable: "Not reachable",
+  platform: "Platform error",
+};
+
+const LOGIN_FAILURE_ADVICE: Record<ProbeFailureKind, (baseUrl: string) => string> = {
+  rejected: () => "Check that the key was copied whole and has not been revoked.",
+  unreachable: (baseUrl) =>
+    `${baseUrl} did not answer, so the key was not evaluated. Check network access, VPN, or proxy settings and retry.`,
+  platform: () => "The platform failed before confirming the key. Retry later.",
+};
+
+const STATUS_FAILURE_ADVICE: Record<ProbeFailureKind, (baseUrl: string) => string> = {
+  rejected: () => "Run toloka login to store a working key.",
+  unreachable: (baseUrl) =>
+    `Check network access to ${baseUrl}; the stored key was not evaluated.`,
+  platform: () => "The platform failed before confirming the key. Retry later.",
+};
 
 export const apiKeyInstructions = (baseUrl: string): string => {
   const console = consoleUrlFor(baseUrl);
@@ -54,6 +89,14 @@ export type AuthProbe = {
       readonly pagination: { readonly total: number };
     }>;
   };
+  readonly me?: () => Promise<{
+    readonly internal: boolean;
+    readonly teams?: ReadonlyArray<{
+      readonly id: string;
+      readonly writable: boolean;
+      readonly internal?: boolean;
+    }>;
+  }>;
 };
 
 export type LoginOptions = {
@@ -76,21 +119,26 @@ export async function login(options: LoginOptions = {}): Promise<LoginResult> {
   const write = options.write ?? (() => undefined);
   const baseUrl = normalizeBaseUrl(
     options.baseUrl ??
-      environment.POTATO_BASE_URL ??
+      environment.TOLOKA_BASE_URL ??
       resolveInternalBaseUrl(environment) ??
       PRODUCTION_BASE_URL,
   );
 
-  let apiKey = options.apiKey ?? environment.POTATO_API_KEY;
+  let apiKey = options.apiKey ?? environment.TOLOKA_API_KEY;
   if (apiKey === undefined) {
-    assert(
+    assertCli(
       options.prompt,
-      "Missing API key. Pass --api-key, or set POTATO_API_KEY, when stdin is not a terminal.",
+      "Missing API key. Without a terminal, pipe the key to toloka login --api-key-stdin, pass --api-key, or set TOLOKA_API_KEY.",
+      { hint: { disabled: true } },
     );
     write(`\n${apiKeyInstructions(baseUrl)}\n`);
     apiKey = (await options.prompt("API key: ", { mask: true })).trim();
   }
-  assert(apiKey.length > 0, "No API key entered.");
+  assertCli(
+    apiKey.length > 0,
+    "No API key entered.",
+    { hint: { description: "Re-run toloka login and paste the key at the prompt, or pass --api-key." } },
+  );
   const credentials: StoredCredentials = { baseUrl, apiKey };
   const probe: AuthProbe = options.probe?.(credentials) ?? createClient(credentials);
 
@@ -99,14 +147,14 @@ export async function login(options: LoginOptions = {}): Promise<LoginResult> {
     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(
+    const failure = classifyProbeFailure(error);
+    throw new TolokaCliError(
       [
-        `Could not authenticate against ${baseUrl}: ${reason}`,
+        `Could not authenticate against ${baseUrl}: ${failure.reason}`,
         "",
-        "Nothing was saved. Check that the key was copied whole and has not been revoked.",
+        `Nothing was saved. ${LOGIN_FAILURE_ADVICE[failure.kind](baseUrl)}`,
       ].join("\n"),
-      { cause: error },
+      { cause: error, hint: { disabled: true } },
     );
   }
 
@@ -136,7 +184,7 @@ export async function login(options: LoginOptions = {}): Promise<LoginResult> {
       reachable,
       `Saved credentials to ${credentialsFile}.`,
       "",
-      "toloka reads them automatically. --api-key and POTATO_API_KEY still win when set.",
+      "toloka reads them automatically. --api-key and TOLOKA_API_KEY still win when set.",
     ].join("\n"),
   };
 }
@@ -183,9 +231,9 @@ const resolveApiKey = (
     options.flagApiKey === undefined
       ? undefined
       : { value: options.flagApiKey, source: "from --api-key" },
-    environment.POTATO_API_KEY === undefined
+    environment.TOLOKA_API_KEY === undefined
       ? undefined
-      : { value: environment.POTATO_API_KEY, source: "from POTATO_API_KEY" },
+      : { value: environment.TOLOKA_API_KEY, source: "from TOLOKA_API_KEY" },
     found === undefined
       ? undefined
       : { value: found.credentials.apiKey, source: `stored in ${storedPath}` },
@@ -202,9 +250,9 @@ const resolvePlatform = (
       options.flagBaseUrl === undefined
         ? undefined
         : { value: options.flagBaseUrl.replace(/\/+$/u, ""), source: "from --base-url" },
-      environment.POTATO_BASE_URL === undefined
+      environment.TOLOKA_BASE_URL === undefined
         ? undefined
-        : { value: environment.POTATO_BASE_URL, source: "from POTATO_BASE_URL" },
+        : { value: environment.TOLOKA_BASE_URL, source: "from TOLOKA_BASE_URL" },
       internalBaseUrl === undefined
         ? undefined
         : { value: internalBaseUrl, source: `from ENV=${environment.ENV}` },
@@ -213,11 +261,29 @@ const resolvePlatform = (
   );
 };
 
+const accountLines = async (probe: AuthProbe): Promise<readonly string[]> => {
+  if (probe.me === undefined) return [];
+  try {
+    const me = await probe.me();
+    if (me.teams === undefined) return [`Internal: ${me.internal}`];
+    const teams = me.teams.map((team) => {
+      const qualifiers = [...(team.internal ? ["internal"] : []), ...(team.writable ? [] : ["read-only"])];
+      return qualifiers.length === 0 ? team.id : `${team.id} (${qualifiers.join(", ")})`;
+    });
+    return [
+      `Internal: ${me.internal}`,
+      `Teams:    ${teams.length === 0 ? "(none)" : teams.join(", ")}`,
+    ];
+  } catch {
+    return [];
+  }
+};
+
 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));
+    (await findCommandCredentials(environment, options.flagApiKey ?? environment.TOLOKA_API_KEY));
   const { found, warning } = credentialLookup;
   const storedPath = found?.path ?? credentialsPath(environment);
   const apiKey = resolveApiKey(options, environment, found, storedPath);
@@ -244,8 +310,8 @@ export async function authStatus(options: AuthStatusOptions = {}): Promise<AuthS
     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 (environment.TOLOKA_API_KEY !== undefined && found !== undefined) {
+    lines.push("", `TOLOKA_API_KEY is set, so the key stored in ${found.path} is ignored.`);
   }
   if (found?.legacy === true) {
     lines.push(
@@ -260,10 +326,16 @@ export async function authStatus(options: AuthStatusOptions = {}): Promise<AuthS
   try {
     const page = await probe.projects.listPage({ limit: 1 });
     lines.push("", `Reachable: ${page.pagination.total} project(s) visible.`);
+    lines.push(...(await accountLines(probe)));
     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.");
+    const failure = classifyProbeFailure(error);
+    lines.push(
+      "",
+      `${PROBE_FAILURE_HEADLINE[failure.kind]}: ${failure.reason}`,
+      "",
+      STATUS_FAILURE_ADVICE[failure.kind](baseUrl),
+    );
     return { authenticated: false, output: lines.join("\n") };
   }
 }

package/src/cli/auto-update.ts

@@ -6,16 +6,22 @@ import { join, sep } from "node:path";
 import { findCliEntry } from "./cli-entry";
 import type { CliEnvironment } from "./credentials";
 import { configDirectory, preparePrivateFilePath } from "./credentials";
-import { SDK_VERSION } from "./init";
+import {
+  compareSdkVersions,
+  releaseChannelFor,
+  SDK_PACKAGE_NAME,
+  SDK_VERSION,
+  type ReleaseChannel,
+} from "./sdk-version";
 import { commandNameFromArgv } from "./analytics";
 import { readCliSettings } from "./settings";
 import { CHECK_RESULT_FILE_ENV } from "./check";
 import { isFalseyFlag, isTruthyFlag } from "./boolean-flag";
-import packageMetadata from "../../package.json" with { type: "json" };
+import { TolokaCliError } from "./cli-error";
+import { formatCliError } from "./format-error";
 
 export const AUTO_UPDATE_INTERVAL_MS = 24 * 60 * 60 * 1000;
 export const AUTO_UPDATE_QUARANTINE_MS = 24 * 60 * 60 * 1000;
-export const SDK_PACKAGE_NAME = packageMetadata.name;
 export const DEFAULT_NPM_REGISTRY = "https://registry.npmjs.org/";
 
 const SKIP_COMMANDS: Readonly<Record<string, true>> = {
@@ -75,32 +81,6 @@ export const npmRegistryUrl = (): string => DEFAULT_NPM_REGISTRY;
 export const npmPackageMetadataUrl = (packageName: string): string =>
   new URL(encodeURIComponent(packageName), DEFAULT_NPM_REGISTRY).toString();
 
-export const parseSdkVersion = (version: string): readonly number[] | undefined => {
-  const match = /^(\d+)\.(\d+)\.(\d+)(?:-preview\.(\d+))?$/u.exec(version);
-  if (match === null) return undefined;
-  const [, major, minor, patch, preview] = match;
-  return [
-    Number(major),
-    Number(minor),
-    Number(patch),
-    preview === undefined ? Number.POSITIVE_INFINITY : Number(preview),
-  ];
-};
-
-export const compareSdkVersions = (left: string, right: string): number | undefined => {
-  const parsedLeft = parseSdkVersion(left);
-  const parsedRight = parseSdkVersion(right);
-  if (parsedLeft === undefined || parsedRight === undefined) return undefined;
-  const length = Math.max(parsedLeft.length, parsedRight.length);
-  for (let index = 0; index < length; index += 1) {
-    const leftPart = parsedLeft[index] ?? 0;
-    const rightPart = parsedRight[index] ?? 0;
-    if (leftPart < rightPart) return -1;
-    if (leftPart > rightPart) return 1;
-  }
-  return 0;
-};
-
 const asStringRecord = (value: unknown): Readonly<Record<string, string>> | undefined => {
   if (typeof value !== "object" || value === null || Array.isArray(value)) return undefined;
   const record: Record<string, string> = {};
@@ -122,9 +102,22 @@ export const asNpmPackageView = (payload: unknown): NpmPackageView | undefined =
   };
 };
 
-export const latestPublishedVersion = (view: NpmPackageView): string | undefined => {
-  const latest = view["dist-tags"]?.latest;
-  return typeof latest === "string" && latest.length > 0 ? latest : undefined;
+export const latestPublishedVersion = (
+  view: NpmPackageView,
+  currentVersion: string,
+): string | undefined => {
+  const tags = view["dist-tags"];
+  if (tags === undefined) return undefined;
+  const channels: readonly ReleaseChannel[] =
+    releaseChannelFor(currentVersion) === "preview" ? ["latest", "preview"] : ["latest"];
+  let newest: string | undefined;
+  for (const channel of channels) {
+    const candidate = tags[channel];
+    if (candidate === undefined || candidate.length === 0) continue;
+    if (newest === undefined || (compareSdkVersions(candidate, newest) ?? 0) > 0)
+      newest = candidate;
+  }
+  return newest;
 };
 
 const publishedAt = (view: NpmPackageView, version: string): Date | undefined => {
@@ -208,9 +201,9 @@ const collectOutput = async (stream: NodeJS.ReadableStream | null): Promise<stri
   return Buffer.concat(chunks).toString("utf8");
 };
 
-class RegistryError extends Error {
+class RegistryError extends TolokaCliError {
   constructor(message: string) {
-    super(message);
+    super(message, { hint: { disabled: true } });
     this.name = "RegistryError";
   }
 }
@@ -248,10 +241,16 @@ const defaultInstall: AutoUpdateInstall = async ({
   const exitCode = close[0];
   if (exitCode === 0) return;
   const detail = [stderr.trim(), stdout.trim()].filter((part) => part.length > 0).join("\n");
-  throw new Error(
+  throw new TolokaCliError(
     detail.length > 0
       ? `bun add --global failed: ${detail}`
       : `bun add --global exited ${String(exitCode)}`,
+    {
+      hint: {
+        description:
+          "Run the bun add --global command yourself, or turn the check off with toloka config set auto-update false.",
+      },
+    },
   );
 };
 
@@ -310,7 +309,7 @@ const selectUpdateCandidate = async (options: {
     return { status: "skip" };
   }
 
-  const version = latestPublishedVersion(view);
+  const version = latestPublishedVersion(view, currentVersion);
   if (version === undefined) return { status: "skip" };
   const order = compareSdkVersions(currentVersion, version);
   if (order === undefined || order >= 0) return { status: "skip" };
@@ -349,9 +348,7 @@ export async function maybeAutoUpdate(options: {
       environment,
     });
   } catch (error) {
-    io.stderr(
-      `Auto-update to ${candidate.version} failed: ${error instanceof Error ? error.message : String(error)}.`,
-    );
+    io.stderr(`Auto-update to ${candidate.version} failed: ${formatCliError(error)}`);
     return continueResult();
   }