@toloka-platform/sdk 0.3.1 → 0.5.0

package/README.md

@@ -2,7 +2,7 @@
 
 Build and operate Toloka pipeline projects as TypeScript source.
 
-> **Stable 0.2.0.** The current supported release is published on `latest`. Because the SDK is still `0.x`, the authoring API, CLI surface, and generated source layout can change between minor releases. Use `latest` to stay current, or pin `@toloka-platform/sdk@0.2.0` for reproducible installs. Read [limitations](./docs/limitations.md).
+> **Use the latest release.** The current supported release is published on `latest`. Because the SDK is still `0.x`, the authoring API, CLI surface, and generated source layout can change between minor releases. Read [limitations](./docs/limitations.md).
 
 A pipeline project is a graph of nodes that moves items from a dataset through deterministic code and human work and back into the dataset. This package lets you write that project as TypeScript, keep it in version control, and reconcile it onto the platform with one command.
 
@@ -99,6 +99,8 @@ Two rules the platform enforces and the SDK will not paper over:
 
 `createClient` takes the platform URL and one credential. `{ baseUrl, apiKey }` sends the key with the `ApiKey` authorization scheme on every request; the key does not expire until it is deleted in the Business Console. `{ baseUrl, accessToken }` calls the `accessToken` function before every request and sends its result as a Bearer token, so a renewable session can back the client. The two forms are exclusive. The CLI uses the second form for its browser sign-in.
 
+A project-scoped token (`toloka project token`, or `POST /api/v2-beta/projects/:id/tokens`) is passed as `apiKey` too; the client recognizes the `pst_` prefix and sends it in the `X-Scoped-Token` header instead of `Authorization` (the platform gateway forwards only platform credentials in `Authorization`). Such a token acts as its minting user, confined to one or more projects of one team (`--projects` adds more) and the granted permissions, for at most six hours — hand it to an agent as `TOLOKA_API_KEY` instead of a long-lived key. `toloka project tokens` lists the live tokens of the selected project and `toloka project revoke-token <id>` kills one; a token can also end itself with `client.projects.revokeCurrentToken()`.
+
 ## Agent support
 
 `toloka init` initializes the current directory with one managed `<toloka>` Agent Bootstrap block in `AGENTS.md` plus minimal pointers to it: a Claude skill at `.claude/skills/toloka-bootstrap/SKILL.md` and, when `.cursor/rules/` exists, an always-applied Cursor rule at `.cursor/rules/toloka-bootstrap.mdc`. It does not bind a checkout from the machine registry's current project. Pass `--project-id`, set `TOLOKA_PROJECT_ID`, or run `toloka project create` first when `init` must write `toloka.json`. For an existing project, run `toloka import <projectId>` before `init`. Re-running `init` refreshes only CLI-owned content and removes only Toloka-generated legacy entry points; run it again after updating the standalone CLI. Then open your coding agent in that directory and ask it to create the project you need; the bootstrap directs the agent to `toloka --help`, skill discovery, and the installed skill.
@@ -106,3 +108,7 @@ Two rules the platform enforces and the SDK will not paper over:
 ## Agent evals
 
 The live agent eval harness lives in [evals](./evals/). It is not part of the published package.
+
+## Regenerating the client
+
+`openapi/openapi.json` is produced from the running API (`bun run generate:api-v2-openapi` in `app`; a unit test fails when the committed document drifts from what the server serves) and `openapi/gen` is produced from that document by orval (`bun run generate` here). Both are committed. After any change to the api-v2 schemas, run both and commit the result; CI runs `bun run generate:check` and fails when `openapi/gen` is stale.