@toloka-platform/sdk 0.11.1 → 0.11.2

package/src/cli/context.ts

@@ -10,8 +10,14 @@ import type { CliAnalytics } from "./analytics";
 import type { BrowserLoginFlow } from "./browser-login";
 import { createBrowserSessionAuth, findBrowserLogin } from "./browser-session";
 import type { checkProject } from "./check";
-import { PRODUCTION_BASE_URL, resolveApiKey, resolveBaseUrl, resolveTolokaConfig } from "./config";
-import type { ResolvedTolokaConfig, TolokaEnvironment } from "./config";
+import type { DescribeTaskUiComponents } from "../testing/task-ui-browser";
+import {
+  PRODUCTION_BASE_URL,
+  resolveBaseUrl,
+  resolveConfiguredCredential,
+  resolveTolokaConfig,
+} from "./config";
+import type { CliCredential, ResolvedTolokaConfig, TolokaEnvironment } from "./config";
 import { findCommandCredentials } from "./credentials";
 import type { StoredCredentials } from "./credentials";
 import { resolveProjectContext } from "./project-context";
@@ -36,6 +42,7 @@ export type ProgramContext = {
   readonly browserLogin?: BrowserLoginFlow;
   readonly runChecks?: typeof checkProject;
   readonly analytics?: CliAnalytics;
+  readonly taskUiComponents?: DescribeTaskUiComponents;
 };
 
 export type GlobalOptions = {
@@ -54,6 +61,7 @@ export type Resolved = {
   readonly sourceRoot: string;
   readonly client: PotatoClient;
   readonly baseUrl: string;
+  readonly credential: CliCredential;
   readonly state: TolokaState | undefined;
   readonly stored: StoredCredentials | undefined;
   readonly projectId?: string;
@@ -61,10 +69,11 @@ export type Resolved = {
 
 export const CREDENTIAL_PRECEDENCE = [
   "Credentials resolve in this order, highest first:",
-  "  1. --api-key / --base-url",
-  "  2. TOLOKA_API_KEY / TOLOKA_BASE_URL",
-  "  3. the API key stored by toloka login --api-key-stdin",
-  "  4. the browser login stored by toloka login",
+  "  1. --api-key",
+  "  2. TOLOKA_SCOPED_TOKEN",
+  "  3. TOLOKA_API_KEY",
+  "  4. the API key stored by toloka login --api-key-stdin",
+  "  5. the browser login stored by toloka login",
   `The platform defaults to ${PRODUCTION_BASE_URL}.`,
 ].join("\n");
 
@@ -205,7 +214,9 @@ export const resolveInitRoot = (globals: GlobalOptions): string =>
 export const readCommandCredentials = async (globals: GlobalOptions, context: ProgramContext) => {
   const { found, warning } = await findCommandCredentials(
     context.environment,
-    globals.apiKey ?? context.environment.TOLOKA_API_KEY,
+    globals.apiKey ??
+      context.environment.TOLOKA_SCOPED_TOKEN ??
+      context.environment.TOLOKA_API_KEY,
   );
   if (warning !== undefined) context.io.stderr(warning);
   return found?.credentials;
@@ -229,7 +240,7 @@ export const resolveClient = async (
 ): Promise<{ readonly config: ResolvedTolokaConfig; readonly client: PotatoClient }> => {
   const { environment } = context;
   const browserLogin =
-    resolveApiKey(globals, environment, stored) === undefined
+    resolveConfiguredCredential(globals, environment, stored) === undefined
       ? (await findBrowserLogin(resolveBaseUrl(globals, environment, stored), environment))?.provider
       : undefined;
   const config = resolveTolokaConfig(globals, state, environment, stored, browserLogin);
@@ -239,10 +250,16 @@ export const resolveClient = async (
     createClient(
       credential.type === "apiKey"
         ? { baseUrl, apiKey: credential.apiKey }
-        : {
-            baseUrl,
-            accessToken: createBrowserSessionAuth({ provider: credential.provider, baseUrl, environment }),
-          },
+        : credential.type === "scopedToken"
+          ? { baseUrl, scopedToken: credential.scopedToken }
+          : {
+              baseUrl,
+              accessToken: createBrowserSessionAuth({
+                provider: credential.provider,
+                baseUrl,
+                environment,
+              }),
+            },
     );
   return { config, client };
 };
@@ -261,6 +278,7 @@ export const resolveContext = async (
     sourceRoot,
     client,
     baseUrl: config.baseUrl,
+    credential: config.credential,
     state,
     stored,
     ...(config.projectId === undefined ? {} : { projectId: config.projectId }),

package/src/cli/credentials.ts

@@ -192,12 +192,12 @@ export async function findStoredCredentials(
 
 export async function findCommandCredentials(
   environment: CliEnvironment,
-  overrideApiKey: string | undefined,
+  overrideCredential: string | undefined,
 ): Promise<CommandCredentialLookup> {
   try {
     return { found: await findStoredCredentials(environment) };
   } catch (error) {
-    if (!(error instanceof CredentialsError) || overrideApiKey === undefined) throw error;
+    if (!(error instanceof CredentialsError) || overrideCredential === undefined) throw error;
     return { found: undefined, warning: error.message };
   }
 }

package/src/cli/environment.ts

@@ -6,7 +6,11 @@ const LEGACY_ENVIRONMENT_NAMES: Readonly<Record<string, string>> = {
   POTATO_PROJECT_ID: "TOLOKA_PROJECT_ID",
 };
 
-export const API_KEY_ENVIRONMENT_NAMES = ["TOLOKA_API_KEY", "POTATO_API_KEY"];
+export const CREDENTIAL_ENVIRONMENT_NAMES = [
+  "TOLOKA_SCOPED_TOKEN",
+  "TOLOKA_API_KEY",
+  "POTATO_API_KEY",
+];
 
 export type NormalizedEnvironment = {
   readonly environment: TolokaEnvironment;

package/src/cli/program.ts

@@ -5,6 +5,7 @@ import type { CliAnalytics, CliAnalyticsCommandOutcome } from "./analytics";
 import type { AutoUpdateHooks } from "./auto-update";
 import { maybeAutoUpdate } from "./auto-update";
 import type { BrowserLoginFlow } from "./browser-login";
+import type { DescribeTaskUiComponents } from "../testing/task-ui-browser";
 import { CHECK_RESULT_FILE_ENV, type checkProject } from "./check";
 import { registerAudienceCommands } from "./commands/audience";
 import { registerAuthCommands } from "./commands/auth";
@@ -20,6 +21,7 @@ import { registerSkillCommands } from "./commands/skill";
 import { registerSourceCommands } from "./commands/source";
 import { registerStatusCommand } from "./commands/status";
 import { registerTrainingCommands } from "./commands/training";
+import { registerUiCommands } from "./commands/ui";
 import { registerVersionCommand } from "./commands/version";
 import type { TolokaEnvironment } from "./config";
 import {
@@ -103,6 +105,7 @@ export function createProgram(context: ProgramContext): CreatedProgram {
   registerStatusCommand(program, host);
   registerReportCommand(program, host);
   registerSkillCommands(program, host);
+  registerUiCommands(program, host);
 
   return { program, exitCode };
 }
@@ -198,6 +201,7 @@ export async function runTolokaCli(
   runChecks?: typeof checkProject,
   autoUpdate?: AutoUpdateHooks,
   browserLogin?: BrowserLoginFlow,
+  taskUiComponents?: DescribeTaskUiComponents,
 ): Promise<number> {
   const { environment, warnings } = normalizeEnvironment(rawEnvironment);
   for (const warning of warnings) io.stderr(warning);
@@ -220,6 +224,7 @@ export async function runTolokaCli(
     ...(injectedClient === undefined ? {} : { injectedClient }),
     ...(browserLogin === undefined ? {} : { browserLogin }),
     ...(runChecks === undefined ? {} : { runChecks }),
+    ...(taskUiComponents === undefined ? {} : { taskUiComponents }),
   };
   const { program, exitCode } = createProgram(baseContext);
   const startedAt = Date.now();

package/src/cli/project-context.ts

@@ -50,7 +50,7 @@ export const NO_PROJECT_SELECTED_MESSAGE =
   "No project selected. Run toloka project create for a new project, toloka project add for an existing project, or cd into a checkout.";
 
 const NETWORK_MISMATCH_MESSAGE =
-  "project add writes the machine registry; unset --api-key / --base-url / TOLOKA_API_KEY / TOLOKA_BASE_URL, or run login against that platform first.";
+  "project add writes the machine registry; unset --api-key / --base-url / TOLOKA_SCOPED_TOKEN / TOLOKA_API_KEY / TOLOKA_BASE_URL, or run login against that platform first.";
 
 const ALIAS_PATTERN = /^[^/\s]+$/u;
 
@@ -187,7 +187,10 @@ const assertStoredNetworkMatches = (
   environment: TolokaEnvironment,
   stored: StoredCredentials,
 ) => {
-  const flagOrEnvKey = firstNonEmpty(flags.apiKey) ?? firstNonEmpty(environment.TOLOKA_API_KEY);
+  const flagOrEnvKey =
+    firstNonEmpty(flags.apiKey) ??
+    firstNonEmpty(environment.TOLOKA_SCOPED_TOKEN) ??
+    firstNonEmpty(environment.TOLOKA_API_KEY);
   const flagOrEnvBase =
     firstNonEmpty(flags.baseUrl) ??
     firstNonEmpty(environment.TOLOKA_BASE_URL) ??

package/src/cli/ui.ts

@@ -0,0 +1,61 @@
+import type { TaskUiComponentDescription } from "../testing/types";
+import type { DescribeTaskUiComponents } from "../testing/task-ui-browser";
+import type { CliIo } from "./context";
+
+const formatList = (title: string, items: readonly string[]): string[] =>
+  items.length === 0 ? [] : [`${title}:`, ...items.map((item) => `- ${item}`)];
+
+export const formatComponentIndex = (
+  components: Readonly<Record<string, TaskUiComponentDescription>>,
+): string =>
+  [
+    ...Object.values(components).map(({ name, description }) => `${name}: ${description}`),
+    "",
+    "Run `toloka ui components <name> [name...]` for the props, value shape, and example of a component.",
+  ].join("\n");
+
+export const formatComponentDetails = (
+  components: Readonly<Record<string, TaskUiComponentDescription>>,
+): string =>
+  Object.values(components)
+    .map((component) =>
+      [
+        `## ${component.name}`,
+        component.description,
+        `When to use: ${component.whenToUse}`,
+        ...formatList("Capabilities", component.capabilities),
+        ...formatList("Limitations", component.limitations),
+        ...formatList("Best practices", component.bestPractices),
+        "Props:",
+        component.propsType,
+        ...(component.valueType === undefined ? [] : ["Value:", component.valueType]),
+        ...(component.example === undefined
+          ? []
+          : ["Example:", component.example.jsxTemplate, "Example output:", component.example.output]),
+      ].join("\n"),
+    )
+    .join("\n\n");
+
+export const uiComponentsCommand = async ({
+  sourceRoot,
+  names,
+  json,
+  io,
+  describe,
+}: {
+  sourceRoot: string;
+  names: readonly string[];
+  json: boolean;
+  io: CliIo;
+  describe: DescribeTaskUiComponents;
+}): Promise<void> => {
+  const components = await describe({
+    resolveFrom: sourceRoot,
+    ...(names.length === 0 ? {} : { names: [...names] }),
+  });
+  if (json) {
+    io.stdout(JSON.stringify(components, undefined, 2));
+    return;
+  }
+  io.stdout(names.length === 0 ? formatComponentIndex(components) : formatComponentDetails(components));
+};

package/src/core-entity-types.json

@@ -0,0 +1,32 @@
+[
+  "JUDGEMENT",
+  "EXPLANATION",
+  "PROMPT",
+  "USER_PROMPT",
+  "RESPONSE",
+  "RESPONSE_EVALUATION",
+  "RUBRIC",
+  "RUBRICS_GROUP",
+  "DIALOG",
+  "DIALOG_STEP",
+  "DIALOG_EVALUATION",
+  "SHORT_ANSWER",
+  "FEEDBACK",
+  "CONTEXT",
+  "IMAGE",
+  "ANNOTATION",
+  "SINGLE_LABEL",
+  "MULTI_LABEL",
+  "VIDEO",
+  "DOCUMENT",
+  "GOLDEN_SET",
+  "LOGS",
+  "SOLUTION",
+  "CODE",
+  "METADATA",
+  "AUDIO",
+  "AGENT_TRAJECTORY",
+  "MCP_SERVER",
+  "CONTAINER",
+  "CUSTOM"
+]

package/src/testing/task-ui-browser.ts

@@ -1,5 +1,9 @@
 import { assert } from "es-toolkit";
-import { chromium, type Browser, type Page } from "playwright";
+import { createRequire } from "node:module";
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+import type * as Playwright from "playwright";
+import type { Browser, Page } from "playwright";
 import {
   TaskUiInfrastructureError,
   type TaskUiComponentDescription,
@@ -95,8 +99,20 @@ export const readDataPath = (state: Record<string, unknown>): string | undefined
 export const componentIds = (tree: string): string[] =>
   [...tree.matchAll(/\bid="([^"]+)"/gu)].map((match) => match[1]!);
 
-export const launchDefaultBrowser = async (): Promise<Browser> => {
+const playwrightSpecifier = (resolveFrom: string | undefined): string => {
+  if (resolveFrom === undefined) return "playwright";
   try {
+    return pathToFileURL(createRequire(join(resolveFrom, "package.json")).resolve("playwright")).href;
+  } catch {
+    return "playwright";
+  }
+};
+
+export const launchDefaultBrowser = async ({
+  resolveFrom,
+}: { resolveFrom?: string } = {}): Promise<Browser> => {
+  try {
+    const { chromium }: typeof Playwright = await import(playwrightSpecifier(resolveFrom));
     return await chromium.launch({ headless: true });
   } catch (error) {
     throw new TaskUiInfrastructureError(
@@ -117,4 +133,31 @@ export const waitForTaskUiApi = async (page: Page): Promise<void> => {
   );
 };
 
+export const readComponentDocumentation = async (
+  page: Page,
+  launcherUrl: string,
+  names?: string[],
+): Promise<Record<string, TaskUiComponentDescription>> => {
+  await page.goto(launcherUrl, { waitUntil: "domcontentloaded", timeout: 30_000 });
+  await waitForTaskUiApi(page);
+  return selectComponentDocumentation(
+    await evaluateWithApi(page, { operation: "getComponentsDescriptions" }),
+    names,
+  );
+};
+
+export type DescribeTaskUiComponents = (input: {
+  names?: string[];
+  resolveFrom?: string;
+}) => Promise<Record<string, TaskUiComponentDescription>>;
+
+export const describeTaskUiComponents: DescribeTaskUiComponents = async ({ names, resolveFrom }) => {
+  const browser = await launchDefaultBrowser({ resolveFrom });
+  try {
+    return await readComponentDocumentation(await browser.newPage(), DEFAULT_TBX_LAUNCHER_URL, names);
+  } finally {
+    await browser.close();
+  }
+};
+
 export type { Browser, Page, TbxTemplate };

package/src/testing/task-ui.ts

@@ -9,6 +9,7 @@ import {
   componentIds,
   evaluateWithApi,
   launchDefaultBrowser,
+  readComponentDocumentation,
   readDataPath,
   selectComponentDocumentation,
   waitForTaskUiApi,
@@ -287,15 +288,7 @@ const createTaskUiTest = ({
           const context = await _uiBrowser.newContext();
           const page = await context.newPage();
           try {
-            await page.goto(_uiConfig.launcherUrl, {
-              waitUntil: "domcontentloaded",
-              timeout: 30_000,
-            });
-            await waitForTaskUiApi(page);
-            return selectComponentDocumentation(
-              await evaluateWithApi(page, { operation: "getComponentsDescriptions" }),
-              names,
-            );
+            return await readComponentDocumentation(page, _uiConfig.launcherUrl, names);
           } finally {
             await page.close();
             await context.close();

package/src/transport.ts

@@ -2,12 +2,17 @@ import { assert } from "es-toolkit";
 import { PotatoApiError } from "./errors";
 
 const BASE_URL_HEADER = "x-potato-sdk-base-url";
-const SCOPED_TOKEN_PREFIX = "pst_";
+export const SCOPED_TOKEN_PREFIX = "pst_";
 const SCOPED_TOKEN_HEADER = "X-Scoped-Token";
 
 export type ClientCredential =
-  | { readonly apiKey: string; readonly accessToken?: undefined }
-  | { readonly accessToken: () => Promise<string>; readonly apiKey?: undefined };
+  | { readonly apiKey: string; readonly accessToken?: undefined; readonly scopedToken?: undefined }
+  | {
+      readonly accessToken: () => Promise<string>;
+      readonly apiKey?: undefined;
+      readonly scopedToken?: undefined;
+    }
+  | { readonly scopedToken: string; readonly accessToken?: undefined; readonly apiKey?: undefined };
 
 type TransportRequestInit = RequestInit & {
   readonly fetch?: typeof globalThis.fetch;
@@ -29,6 +34,13 @@ export const createRequestOptions = (
     const accessToken = credential.accessToken;
     return { headers, fetch, authorization: async () => `Bearer ${await accessToken()}` };
   }
+  if (credential.scopedToken !== undefined) {
+    assert(credential.scopedToken.length > 0, "The SDK scoped token cannot be empty");
+    return {
+      headers: { ...headers, [SCOPED_TOKEN_HEADER]: credential.scopedToken },
+      fetch,
+    };
+  }
 
   const { apiKey } = credential;
   assert(apiKey.length > 0, "The SDK API key cannot be empty");
@@ -51,14 +63,24 @@ const prepareRequestInit = (requestOptions: RequestInit, headers: Headers): Requ
 // those against the base's origin, dropping its path. Join them instead, so a base URL served under a
 // path prefix (a gateway in front of the platform) keeps that prefix.
 const resolveRequestUrl = (url: string, baseUrl: string): URL => {
-  if (!url.startsWith("/") || url.startsWith("//")) return new URL(url, baseUrl);
   const base = new URL(baseUrl);
-  return new URL(`${base.pathname.replace(/\/+$/, "")}${url}`, base.origin);
+  const basePath = base.pathname.replace(/\/+$/, "");
+  const suffix = url.startsWith("/") ? url : `/${url}`;
+  const resolved = new URL(`${base.origin}${basePath}${suffix}`);
+  assert(
+    resolved.origin === base.origin,
+    "The SDK refused a request whose origin did not match the base URL",
+  );
+  return resolved;
 };
 
 export function potatoFetch<T>(url: string, options: TransportRequestInit): Promise<T>;
 export async function potatoFetch(url: string, options: TransportRequestInit): Promise<unknown> {
-  const { fetch: fetchImplementation = globalThis.fetch, authorization, ...requestOptions } = options;
+  const {
+    fetch: fetchImplementation = globalThis.fetch,
+    authorization,
+    ...requestOptions
+  } = options;
   const headers = new Headers(requestOptions.headers);
   const baseUrl = headers.get(BASE_URL_HEADER);
   assert(baseUrl, "The SDK base URL is missing");

package/src/validate.ts

@@ -2,12 +2,55 @@ import Ajv2020, { type ErrorObject } from 'ajv/dist/2020.js';
 import addFormats from 'ajv-formats';
 import { assert } from 'es-toolkit';
 import type { PipelineGraphV1 } from '../openapi/gen/models';
+import coreEntityTypes from './core-entity-types.json' with { type: 'json' };
 import { PipelineGraphValidationError, type PipelineGraphValidationIssue } from './errors';
 import pipelineGraphV1Contract from './pipeline-graph-v1.contract.json' with { type: 'json' };
 
 const ajv = new Ajv2020({ strict: false });
 addFormats(ajv);
-const validatePipelineGraph = ajv.compile(pipelineGraphV1Contract);
+const validatePipelineGraph = ajv.compile<PipelineGraphV1>(pipelineGraphV1Contract);
+
+const CORE_ENTITY_TYPES = new Set<string>(coreEntityTypes);
+const LABEL_ENTITY_TYPES = new Set(['SINGLE_LABEL', 'MULTI_LABEL']);
+const LABEL_VALUE_PATTERN = /^[a-z0-9]+(_[a-z0-9]+)*$/;
+
+type EntityLike = { entityType: string; allowedLabels?: { label: string; value: string }[] };
+
+const entityIssues = (
+  entities: readonly EntityLike[],
+  side: 'input' | 'output',
+  prefix: string,
+): PipelineGraphValidationIssue[] =>
+  entities.flatMap((entity, index) => {
+    const path = `${prefix}/${side}/${index}`;
+    const issues: PipelineGraphValidationIssue[] = [];
+    if (!CORE_ENTITY_TYPES.has(entity.entityType)) {
+      issues.push({
+        path: `${path}/entityType`,
+        reason: `must be one of the supported core entity types: ${coreEntityTypes.join(', ')}`,
+      });
+    }
+    if (side === 'output' && LABEL_ENTITY_TYPES.has(entity.entityType)) {
+      const labels = entity.allowedLabels ?? [];
+      if (labels.length < 2) {
+        issues.push({ path: `${path}/allowedLabels`, reason: 'label entities require at least 2 allowedLabels' });
+      }
+      if (labels.some(({ value }) => !LABEL_VALUE_PATTERN.test(value))) {
+        issues.push({ path: `${path}/allowedLabels`, reason: 'label values must be snake_case (e.g. this_is_value)' });
+      }
+    }
+    return issues;
+  });
+
+const graphEntityIssues = (graph: PipelineGraphV1): PipelineGraphValidationIssue[] =>
+  graph.nodes.flatMap((node, index) => {
+    if (node.type !== 'generation' && node.type !== 'quorum') return [];
+    const prefix = `/nodes/${index}/settings/entities`;
+    return [
+      ...entityIssues(node.settings.entities.input, 'input', prefix),
+      ...entityIssues(node.settings.entities.output, 'output', prefix),
+    ];
+  });
 
 const toValidationIssue = (error: ErrorObject): PipelineGraphValidationIssue => {
   const property =
@@ -25,7 +68,11 @@ const toValidationIssue = (error: ErrorObject): PipelineGraphValidationIssue =>
 };
 
 export function validate(graph: unknown): asserts graph is PipelineGraphV1 {
-  if (validatePipelineGraph(graph)) return;
+  if (validatePipelineGraph(graph)) {
+    const issues = graphEntityIssues(graph);
+    if (issues.length > 0) throw PipelineGraphValidationError.fromIssues(issues);
+    return;
+  }
 
   const errors = validatePipelineGraph.errors;
   assert(errors, 'Pipeline graph validation failed without errors');