@toloka-platform/sdk 0.5.1 → 0.6.0

package/dist/cli/toloka.js.jsc.sha256

@@ -1 +1 @@
-115309d50a2755a511f097ac14ea83f5cd03fa198fb0e975e64ad9538c2e3474  toloka.js.jsc
+4152a6a66243067c73d45dd077a87a1705b645b14e36c558263663f4939006a4  toloka.js.jsc

package/dist/cli/toloka.js.sha256

@@ -1 +1 @@
-5f0222c5ad52de0073174b3fcc1d9a3433262a803f2e2be183337d8dc3106215  toloka.js
+5dac0697d5d6357e396c06f60b30f99939d2b4cba45130a15effdce678045f48  toloka.js

package/docs/cli.md

@@ -137,8 +137,16 @@ toloka project url
 toloka project remove <alias>
 toloka project create [alias] [--name <name>] [--team-id <id>] [--delivery-order-id <id>]
 toloka project untrack <pipeline|dataset> <name> [--confirm]
+toloka project token [--preset <name>] [--permissions <list>] [--expires-in <seconds>] [--projects <list>]
+toloka project tokens
+toloka project revoke-token <tokenId>
+toloka project revoke-tokens
 ```
 
+`token` mints a project-scoped token for the selected project and prints it once; it is never stored. The token acts as you inside that project (plus any `--projects`, which must belong to the same team) with the permissions of the `--preset` (`read`, `write`, `deploy`, `labeling-read`, `labeling-write`, `labeling-deploy`; default `write`) or an explicit `--permissions` list, and expires after `--expires-in` seconds (60..21600, default six hours). Hand it to an agent as `TOLOKA_API_KEY`. One user may hold at most 1000 live tokens per project, counted against every project the token covers; beyond that, `token` fails with `429 You already hold 1000 live tokens for project <id>; revoke unused tokens first`.
+
+`tokens` lists every live token of the selected project, newest first, with its id, user, expiry, projects, and permissions. `revoke-token <tokenId>` revokes one token and prints `Revoked <tokenId>.`; `revoke-tokens` revokes every live token of the selected project in one call and prints `Revoked <n> tokens.`. A token that covers several projects is revoked as a whole by either command. Revocation takes effect immediately.
+
 `add`, `switch`, `remove`, and `create` write the machine registry in the credentials file. They refuse `--api-key` / `--base-url` / `TOLOKA_*` when those would select a different key or platform than the stored file. `project list` prints project id, name, and team id. `create` uses the account's only writable team (`GET /me` lists the teams; `whoami` prints them) and asks for `--team-id` when there are several. A project owned by an internal team also needs `--delivery-order-id`; `toloka delivery-order list` shows the orders and answers with an explanation for accounts without internal teams.
 
 `project untrack` removes one pipeline or dataset binding from `toloka.json` without deleting the live resource. It previews the name and id in a terminal; outside a terminal, pass `--confirm` after reviewing the state file.

package/openapi/gen/api.ts

@@ -57,6 +57,7 @@ import type {
   ListProjectPipelinesParams,
   ListProjectSecrets200,
   ListProjectTokens200,
+  ListProjectTokensParams,
   ListProjectTrainings200,
   ListProjectTrainingsParams,
   ListProjects200,
@@ -83,6 +84,7 @@ import type {
   ProjectSecretName,
   ReplacePipelineGraphBody,
   ReplaceTrainingConfigurationBody,
+  RevokedScopedTokens,
   RunCost,
   RunId,
   RunItem,
@@ -1646,7 +1648,37 @@ export const createProjectToken = async (projectId: ProjectId,
 
 
 
-export const getListProjectTokensUrl = (projectId: ProjectId,) => {
+export const getListProjectTokensUrl = (projectId: ProjectId,
+    params?: ListProjectTokensParams,) => {
+  const normalizedParams = new URLSearchParams();
+
+  Object.entries(params || {}).forEach(([key, value]) => {
+    
+    if (value !== undefined) {
+      normalizedParams.append(key, value === null ? 'null' : value.toString())
+    }
+  });
+
+  const stringifiedParams = normalizedParams.toString();
+
+  return stringifiedParams.length > 0 ? `/api/v2-beta/projects/${projectId}/tokens?${stringifiedParams}` : `/api/v2-beta/projects/${projectId}/tokens`
+}
+
+export const listProjectTokens = async (projectId: ProjectId,
+    params?: ListProjectTokensParams, options?: RequestInit): Promise<ListProjectTokens200> => {
+  
+  return potatoFetch<ListProjectTokens200>(getListProjectTokensUrl(projectId,params),
+  {      
+    ...options,
+    method: 'GET'
+    
+    
+  }
+);}
+
+
+
+export const getRevokeProjectTokensUrl = (projectId: ProjectId,) => {
 
 
   
@@ -1654,12 +1686,12 @@ export const getListProjectTokensUrl = (projectId: ProjectId,) => {
   return `/api/v2-beta/projects/${projectId}/tokens`
 }
 
-export const listProjectTokens = async (projectId: ProjectId, options?: RequestInit): Promise<ListProjectTokens200> => {
+export const revokeProjectTokens = async (projectId: ProjectId, options?: RequestInit): Promise<RevokedScopedTokens> => {
   
-  return potatoFetch<ListProjectTokens200>(getListProjectTokensUrl(projectId),
+  return potatoFetch<RevokedScopedTokens>(getRevokeProjectTokensUrl(projectId),
   {      
     ...options,
-    method: 'GET'
+    method: 'DELETE'
     
     
   }

package/openapi/gen/models/index.ts

@@ -312,6 +312,7 @@ export * from './listProjectPipelines200';
 export * from './listProjectPipelinesParams';
 export * from './listProjectSecrets200';
 export * from './listProjectTokens200';
+export * from './listProjectTokensParams';
 export * from './listProjectTrainings200';
 export * from './listProjectTrainingsParams';
 export * from './listProjects200';
@@ -784,6 +785,7 @@ export * from './quorumNodeSettingsSmartSearchAnyOfProjectDescription';
 export * from './quorumNodeSettingsUi';
 export * from './replacePipelineGraphBody';
 export * from './replaceTrainingConfigurationBody';
+export * from './revokedScopedTokens';
 export * from './rootNode';
 export * from './rootNodeSettings';
 export * from './rootNodeSettingsCompletedFieldProxies';

package/openapi/gen/models/listProjectTokens200.ts

@@ -1,5 +1,7 @@
 import type { ScopedTokenSummary } from './scopedTokenSummary';
+import type { Pagination } from './pagination';
 
 export type ListProjectTokens200 = {
   tokens: ScopedTokenSummary[];
+  pagination: Pagination;
 };

package/openapi/gen/models/listProjectTokensParams.ts

@@ -0,0 +1,5 @@
+
+export type ListProjectTokensParams = {
+limit?: number;
+offset?: number;
+};

package/openapi/gen/models/revokedScopedTokens.ts

@@ -0,0 +1,4 @@
+
+export interface RevokedScopedTokens {
+  revokedCount: number;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@toloka-platform/sdk",
-  "version": "0.5.1",
+  "version": "0.6.0",
   "private": false,
   "description": "Build, inspect, and operate Toloka pipeline projects as TypeScript source. The public API may change between minor versions before 1.0.",
   "license": "Apache-2.0",
@@ -77,6 +77,6 @@
     "bun": ">=1.4.0"
   },
   "tolokaBuild": {
-    "commit": "f42223610fd0991694e1fb7852690b9b9a42e565"
+    "commit": "4658b9a88d4322ec5c9bc8cedbc0f31e0150a859"
   }
 }

package/skills/catalog.json

@@ -11,8 +11,8 @@
         "testing",
         "checks"
       ],
-      "version": "0.5.1",
-      "digest": "d10767a13e558bb74e64768dbcc5260e8f78b5541050ed5cb6d5eb9809733107",
+      "version": "0.6.0",
+      "digest": "c17a1c4f9b3b974ae07859bc3ac7669d98d47d9984e174712f550ef7c3204d63",
       "files": [
         "SKILL.md",
         "references/node-semantics.md",
@@ -29,7 +29,7 @@
         "bug",
         "report"
       ],
-      "version": "0.5.1",
+      "version": "0.6.0",
       "digest": "70f0bd2c80b32f87896aeb27c363b8a2d37f40e22424f57fe1aad142e125ad67",
       "files": [
         "SKILL.md",
@@ -46,7 +46,7 @@
         "getting-started",
         "agent"
       ],
-      "version": "0.5.1",
+      "version": "0.6.0",
       "digest": "ccf148c682de4e452bb031db95d3933257899006b1766f0fdbc3d15265a63bb9",
       "files": [
         "SKILL.md"
@@ -63,7 +63,7 @@
         "sft",
         "models"
       ],
-      "version": "0.5.1",
+      "version": "0.6.0",
       "digest": "f9c34569fc344f365c79c86819adffc86c78a2ce74e17ba10755ddefaf71790f",
       "files": [
         "SKILL.md"
@@ -80,7 +80,7 @@
         "prompt",
         "models"
       ],
-      "version": "0.5.1",
+      "version": "0.6.0",
       "digest": "902aee47c952e105a6340ee56bf22e79513e2d45d19a7ffbf58990f277387e34",
       "files": [
         "SKILL.md"

package/skills/toloka-build/SKILL.md

@@ -76,7 +76,7 @@ Use `node_modules/@toloka-platform/sdk/examples/face-image-collection/` as a con
 
 Distinguish server requirements from optional design choices. The following constraints and defaults are not all checked by `definePipeline`:
 
-- **Do not pair `projectType: 'general'` with `verifiedExperts: false`.** The server answers `General projects require an ID-verified audience`. Specializations also require a verified audience.
+- **Specializations require a verified audience.** Pair `audience.specializations` with `verifiedExperts: true`. Any project type may use the broad unverified crowd; the default is verified, so set `verifiedExperts: false` only when the task asks for it.
 - **Training is part of the node, not extra.** A quorum node requires `onboarding`, and while it is enabled the platform wants at least three steps and at least one quiz block. Preserve an explicit `enabled: false` that a user or `toloka import` put there; never switch Training on to satisfy your own sense of completeness.
 - **Optional settings should serve the task.** Exams, non-default QA, audience reuse, and smart search can be useful when the requirements call for them. Omit blocks that add no value rather than copying placeholders; an empty disabled block is still authored state. Preserve imported choices unless changing them is part of the task, and explain additions that affect cost or expert eligibility.
 - **Run scope belongs to the platform.** `itemFilter` and `itemLimit` on the root node are set from the platform, and apply preserves whatever is live unless source declares its own value. Do not add an item limit to source to "restore" one you saw in the UI.

package/skills/toloka-build/references/node-semantics.md

@@ -117,7 +117,7 @@ Use `generation` for a single human-in-the-loop task type:
 
 Use `about.projectType: 'general'` when experts act on existing items: annotation, classification, judgment, ranking, rating, comparison, or rewriting.
 
-Use `about.projectType: 'data_collection'` when experts produce new original content instead of labeling an existing item. Build the UI with the corresponding upload or recording component. Prefer the larger unverified crowd for this work by setting `audienceAndPricing.verifiedExperts: false` unless the task specifically requires verified expertise. Do not use an unverified audience for a `general` project.
+Use `about.projectType: 'data_collection'` when experts produce new original content instead of labeling an existing item. Build the UI with the corresponding upload or recording component.
 
 ### Configure it
 
@@ -164,7 +164,7 @@ Keep `instruction` actionable and in English. Include the workflow, concepts, qu
 
 #### Audience and pricing
 
-For humans, set `audienceType: 'human'`, `verifiedExperts`, all three audience filters, `pricePerTask`, and `timeForTask`. The public shapes differ by filter: languages use `{ type: 'and' | 'or', values: [{ value: 'English' }] }`; specializations use `{ type: 'and' | 'or', values: [{ value, qualificationId }] }`; countries use ISO 3166-1 alpha-2 codes, for example `{ type: 'or', values: ['US'] }`. Verify every country value matches `/^[A-Z]{2}$/`; apply currently accepts arbitrary strings that can match no experts. Derive languages and expertise from the task and its inputs, leaving specialization and country filters unrestricted unless needed. English is a reasonable starting language for an English-language task, not a universal audience default. Ask when an unresolved audience requirement changes who can do the work. Do not put specializations on an unverified audience. A specialization's `qualificationId` is platform identity: preserve an imported value, and discover new ones with `toloka audience specialization list`, copying `ID` into `qualificationId` and `NAME` into `value`; never invent one.
+For humans, set `audienceType: 'human'`, `verifiedExperts`, all three audience filters, `pricePerTask`, and `timeForTask`. Set `verifiedExperts: true` unless the task explicitly asks for the broad unverified crowd. The public shapes differ by filter: languages use `{ type: 'and' | 'or', values: [{ value: 'English' }] }`; specializations use `{ type: 'and' | 'or', values: [{ value, qualificationId }] }`; countries use ISO 3166-1 alpha-2 codes, for example `{ type: 'or', values: ['US'] }`. Verify every country value matches `/^[A-Z]{2}$/`; apply currently accepts arbitrary strings that can match no experts. Derive languages and expertise from the task and its inputs, leaving specialization and country filters unrestricted unless needed. English is a reasonable starting language for an English-language task, not a universal audience default. Ask when an unresolved audience requirement changes who can do the work. Do not put specializations on an unverified audience. A specialization's `qualificationId` is platform identity: preserve an imported value, and discover new ones with `toloka audience specialization list`, copying `ID` into `qualificationId` and `NAME` into `value`; never invent one.
 
 `$0.20` and 120 seconds are a starting point for a short task, not a universal rate. Estimate effort from the work and required expertise, respect explicit rates, and explain meaningful adjustments in the cost forecast. The per-expert cap is normally off. For collection tasks, choose a cap based on contributor diversity and repetition requirements; 1 fits one-response-per-expert collection. Avoid copying an arbitrary cap into a task that does not need one.
 
@@ -187,7 +187,8 @@ Use `reuseAudienceWithNodeId` only with real imported `{ pipelineId, nodeId }` v
 - Do not add fields, explanations, comments, or labor the task does not require.
 - Do not choose synthetic generation merely because a model could do the task; require an explicit request.
 - Do not treat the constructor's generated placeholder Training or blank UI as production-ready configuration.
-- Do not pair `projectType: 'general'` with `verifiedExperts: false`. General projects require an ID-verified audience, and the server rejects the graph with `General projects require an ID-verified audience`. `data_collection` supports both modes but requires a hardware upload or recording component supported by the current UI catalog. An annotation task with an unverified audience therefore cannot be expressed: `general` demands verified experts and `data_collection` demands an upload control the task has no use for. When a request asks for one, say so and let the requester choose, rather than quietly flipping a setting.
+- Do not pair `audience.specializations` with `verifiedExperts: false`. Specializations are qualification-backed, and only verified experts hold them.
+- Do not flip an explicitly requested `verifiedExperts: false` to `true`. Every project type accepts either audience mode.
 - Do not omit `ui.constants`. It is required alongside `code`, `data`, `preprocess`, and `postprocess`; `'{}'` is the right value when there is nothing to pass. Omitting it fails validation with `must have required property 'constants'`, usually reported together with a misleading `type must be equal to constant` from the failed node discrimination.
 - Do not omit `maxCostPerAttempt` from a synthetic `audienceAndPricing`. Omitting it fails validation with `must have required property 'maxCostPerAttempt'`, reported together with a misleading `type must be equal to constant` and the human branch's `must have required property 'verifiedExperts'` from the failed `oneOf` discrimination.
 - Do not ship a generation node without Training. `onboarding` is mandatory: at least three `steps`, of which at least one carries a `quiz` block. The server rejects fewer with `Onboarding must have at least 3 steps` and `Onboarding must include at least one quiz block`.

package/skills/toloka-build/references/workflow-and-cli.md

@@ -92,6 +92,12 @@ revoke an API key.
 
 Standalone and Bun-global `toloka` installations check the public npm registry at most once per day and install eligible releases at least 24 hours old before rerunning the command. Project-local installs, CI, and `config`, `version`, and `help` skip the check. Turn it off with `toloka config set auto-update false`. For manual standalone updates, rerun `curl -fsSL https://platform.toloka.ai/cli/install.sh | sh -s -- --native`; Bun-global updates should use `--bun` instead. Preserve the mode and put any original `TOLOKA_CLI_INSTALL_DIR`, `TOLOKA_CLI_CHANNEL`, `TOLOKA_CLI_PACKAGE`, and `TOLOKA_CLI_REGISTRY` overrides on the `sh` side of the pipe again. A package version pin does not disable automatic updates, which always use the public npm registry.
 
+## Hand out a project-scoped token
+
+`toloka project token` mints a token that acts as the signed-in user inside the selected project only (`--projects` adds more projects of the same team), with the permissions of `--preset` (default `write`) or an explicit `--permissions` list, for at most six hours. It is printed once and never stored; pass it to another agent or script as `TOLOKA_API_KEY`. `toloka project tokens` lists the live tokens of the project; `toloka project revoke-token <tokenId>` ends one and `toloka project revoke-tokens` ends every live token of the project at once, for example when a run finished or a token leaked. One user may hold at most 1000 live tokens per project; when `token` fails with `429 … revoke unused tokens first`, run `revoke-tokens`.
+
+A scoped token downloads project files in two steps: a request to `ProjectFile.url` with the token answers `200 {"url": "<storage URL>"}` instead of the redirect a human credential gets. Fetch that `url` as a plain request without the `X-Scoped-Token` header; HTTP clients replay custom headers across redirects, and the token must never reach the storage host.
+
 ## Configure the CLI
 
 Provide the API key and base URL on networked workflows through `TOLOKA_API_KEY` and
@@ -126,6 +132,10 @@ toloka project url
 toloka project remove <alias>
 toloka project create [alias] [--name <name>] [--team-id <id>] [--delivery-order-id <id>]
 toloka project untrack <pipeline|dataset> <name> [--confirm]
+toloka project token [--preset <name>] [--permissions <list>] [--expires-in <seconds>] [--projects <list>]
+toloka project tokens
+toloka project revoke-token <tokenId>
+toloka project revoke-tokens
 toloka delivery-order list
 toloka audience specialization list [--json]
 toloka init

package/src/cli/commands/project.ts

@@ -14,7 +14,7 @@ import { addProject, assertProjectSelected, createProject, currentProject, listR
 import { readTolokaState } from "../../state";
 import { assertCli } from "../cli-error";
 import { formatTable } from "../table";
-import type { CreateScopedTokenBodyAnyOfPreset } from "../../../openapi/gen/models";
+import type { CreateScopedTokenBodyAnyOfPreset, ScopedTokenSummary } from "../../../openapi/gen/models";
 
 const TOKEN_PRESETS: readonly CreateScopedTokenBodyAnyOfPreset[] = [
   "read",
@@ -183,7 +183,10 @@ export const registerProjectCommands = (program: Command, host: CommandHost): vo
     .action(async () => {
       const { client, projectId } = await resolveContext(globals(), context);
       assertProjectSelected(projectId);
-      const { tokens } = await client.projects.listTokens({ projectId });
+      const tokens: ScopedTokenSummary[] = [];
+      for await (const token of client.projects.listAllTokens({ projectId })) {
+        tokens.push(token);
+      }
       context.io.stdout(
         tokens.length === 0
           ? "No live tokens."
@@ -209,6 +212,15 @@ export const registerProjectCommands = (program: Command, host: CommandHost): vo
       await client.projects.revokeToken({ projectId, tokenId });
       context.io.stdout(`Revoked ${tokenId}.`);
     });
+  project
+    .command("revoke-tokens")
+    .description("revoke every live project-scoped token of the project; they stop working immediately")
+    .action(async () => {
+      const { client, projectId } = await resolveContext(globals(), context);
+      assertProjectSelected(projectId);
+      const { revokedCount } = await client.projects.revokeAllTokens({ projectId });
+      context.io.stdout(`Revoked ${revokedCount} token${revokedCount === 1 ? "" : "s"}.`);
+    });
   const create = project
     .command("create")
     .argument("[alias]", "local name for the new project")

package/src/client.ts

@@ -37,6 +37,7 @@ import type {
   ListAudienceSpecializationsParams,
   ListProjectModelsParams,
   ListProjectsParams,
+  ListProjectTokensParams,
   ListTrainingRunsParams,
   ListProjectTrainingsParams,
   Pipeline as GeneratedPipeline,
@@ -292,10 +293,17 @@ const createClientImplementation = (config: ClientConfig) => {
       }, params),
     createToken: ({ projectId, ...body }: { projectId: ProjectId } & CreateScopedTokenBody) =>
       wire.createProjectToken(projectId, body, requestOptions),
-    listTokens: ({ projectId }: { projectId: ProjectId }) =>
-      wire.listProjectTokens(projectId, requestOptions),
+    listTokens: ({ projectId, ...params }: { projectId: ProjectId } & ListProjectTokensParams) =>
+      wire.listProjectTokens(projectId, params, requestOptions),
+    listAllTokens: ({ projectId, ...params }: { projectId: ProjectId } & ListProjectTokensParams) =>
+      listAllPages(async (pageOptions) => {
+        const page = await wire.listProjectTokens(projectId, { ...params, ...pageOptions }, requestOptions);
+        return { items: page.tokens, pagination: page.pagination };
+      }, params),
     revokeToken: ({ projectId, tokenId }: { projectId: ProjectId; tokenId: string }) =>
       wire.revokeProjectToken(projectId, tokenId, requestOptions),
+    revokeAllTokens: ({ projectId }: { projectId: ProjectId }) =>
+      wire.revokeProjectTokens(projectId, requestOptions),
     revokeCurrentToken: () => wire.revokeCurrentToken(requestOptions),
   };