@keboola/api-client 31.0.0 → 33.0.0

package/AGENTS.md

@@ -14,7 +14,9 @@ All commands run from monorepo root using `--filter`:
 pnpm build --filter=@keboola/api-client     # Build with tsdown (ESM + CJS + .d.ts)
 pnpm test --filter=@keboola/api-client       # Vitest
 pnpm type-check --filter=@keboola/api-client # tsc --noEmit
-pnpm --filter @keboola/api-client gen:types  # Regenerate OpenAPI types from redocly.yaml
+pnpm --filter @keboola/api-client gen:types --list    # What can be regenerated
+pnpm --filter @keboola/api-client gen:types storage   # One service — leaves the rest alone
+pnpm --filter @keboola/api-client gen:types           # Every API in redocly.yaml
 ```
 
 ## Getting a client
@@ -34,6 +36,8 @@ const { data } = useQuery({
 - **`createStorageClient`** — Storage-only. Needs only `baseUrl` + `token`, skipping the stack-info round-trip. Start here when in doubt; upgrading later is mechanical, downgrading is not. (React apps still get their client via `ApiClientProvider` + `useApiClient()` — see above; this section is about the non-React/single-service case.)
 - **`createLegacyKeboola` / `createKeboola`** — full SDK across all stack services. Each returns `{ api, session }`; drive the `session` to ready, then use `api`. Bootstrap (`getStackInfo` + `tokens.verify()` to discover services against the actual stack) runs while the storage build resolves, after which `api.context` is synchronous. Every stack service — including `metastore` — is resolved from the stack's advertised service URLs. See the lifecycle section below for the per-flow `session` verbs. The token-less public clients `createAssetsClient` / `createStatusClient` are **not** part of this — import them directly from `@keboola/api-client/assets` and `@keboola/api-client/status`.
 
+**`clients/` also holds clients for third-party APIs the platform talks to directly** (`microsoftGraph` today): a vendor API is still HTTP that must run through the shared fetch client, its middleware chain and its error guards, so it gets a client here rather than a hand-rolled `fetch` in the consuming app. They differ from stack clients in three ways, and a new one should follow the same rules: **never** registered in `createServiceClients.ts` (they are not stack services, so they must not appear on `api.*`), they default their own `baseUrl` (a vendor's host and version prefix are part of its API contract, not something we discover or configure), and they carry no `healthCheck` (we don't own the service's liveness). Consumers construct them directly from the sub-path, like the token-less clients above.
+
 ```ts
 // Storage-only — imports from the /storage sub-path
 import { createStorageClient } from '@keboola/api-client/storage';
@@ -73,7 +77,7 @@ Two flow-specific factories back the SDK, and **both return `{ api, session }`**
 `subscribe(cb)` (fires on config **and** storage-build transitions), and `debug()`. Then:
 
 - bearer: `authenticate(token)` → `setProject(projectId)` / `setProjectAsync(projectId)` (awaits the
-  build) / `reset()`.
+  build) / `forProject(projectId)` (a second project alongside the first) / `reset()`.
 - legacy: `authenticateStorage(sapiToken)` / `authenticateStorageAsync(sapiToken)` (awaits the build),
   `authenticateManagement(manageToken)`.
 
@@ -94,6 +98,83 @@ session.setProject(otherId); // runtime re-scope (rebuilds against the new proje
 session.debug(); // { baseUrl, authReady, managementReady, storage, config }
 ```
 
+### Several projects at once (bearer)
+
+One session can address any number of projects. The credential is a **user** token — project scope is
+one header, `X-KBC-ProjectId` — so `session.forProject(projectId)` builds a `ProjectClients` set for
+any project the user can reach, off the session already in hand:
+
+```ts
+const { api, session } = createKeboola({ baseUrl });
+const result = await api.auth.login.withPassword({ email, password });
+if (!result.mfaRequired) session.authenticate(result); // a TokenSet, not a token string
+await session.setProjectAsync(42); // the session's scope — this is what `api.*` addresses
+
+const other = await session.forProject(7); // a second project, alongside the first
+const [mine, theirs] = await Promise.all([
+  api.storage.buckets.getBuckets({ branchId: 'default' }), // project 42
+  other.storage.buckets.getBuckets({ branchId: 'default' }), // project 7
+]);
+```
+
+`setProjectAsync` **moves** the session (and `api`) to another project; `forProject` **adds** one. Use
+`setProjectAsync` for the project the app is centred on, and `forProject` for every other project it
+reads alongside — the returned clients are yours to hold and never appear on `api`.
+
+- **One credential, one refresh loop.** Every set shares the session's auth middleware, so a token
+  rotation happens once and serves all of them.
+- **Repeat calls are cheap** — a project is bootstrapped once and concurrent callers share that one
+  build. A failed build is retryable.
+- **A project you cannot reach fails the build, not the session.** Connection answers a denied or
+  nonexistent project with the same `invalid_token` 401 as a revoked token — bearer failures are
+  collapsed deliberately, so scope cannot be probed. `forProject` is the only surface taking a
+  caller-supplied id, so it reads a 401 that survives a token rotation as being about the project:
+  the build rejects with the underlying `ApiError` and the session stays signed in. A credential that
+  really is dead still signs you out — the refresh itself 401s, which is unambiguous.
+- **Independent of the scope**, in both directions: re-scoping the session never redirects a set
+  someone holds, and `forProject(scopedProject)` builds a _second_ set rather than reusing `api`'s.
+  For the project the app is centred on, use `api.*`.
+- **Nothing extra is persisted.** Storage still holds one entry, `{ baseUrl, projectId, refreshToken }`
+  — and that `projectId` is the _scope_. The extra projects are runtime state; re-add them on startup.
+- **`reset()` really is a teardown.** Every set is pinned to the sign-in that built it, so one held
+  across a sign-out throws `KeboolaError` (`NotAuthenticated`) on its next request instead of quietly
+  acting as whoever signed in after. Ask again for a fresh one. `clearProject()` drops the scope, not
+  the credential, so it leaves the extra projects alone.
+
+The pin is not specific to `forProject`: **anything that emits this session's credential is bound to
+the sign-in it was built on** — `api.storage`, `api.context`, `api.management`,
+`session.getAuthHeaders()` and `session.restore()` included. The auth middleware holds no token, it
+reads the credential live, so rebuilding a store on sign-out only stops new reads; a request already
+in flight would otherwise complete as the next user, still stamped with the previous project.
+`api.auth` is built once per stack and serves every session, so it pins each _request_ to the sign-in
+that started it rather than to its build — enough to stop a 401 recovery from replaying as the next
+user, and the next session's `login` runs unstamped either way. The guard wraps the **credential**,
+not just the outgoing request: the 401 path rotates the token by calling the credential directly, and
+a straggler from a dead session would otherwise spend the live session's single-use refresh token —
+and sign that session out if the rotation itself came back 401. Anything new that takes the auth
+middleware, or hands the credential to a transport we don't own, needs the same pin — see
+`createPinnedAuthMiddleware` / `pinToSession` in `bearer/keboola.ts`.
+
+**The pin has to cover the failure branches, not only the happy path** — that is where it keeps being
+missed. Two shapes:
+
+- **Anything that re-invokes `next` goes _inside_ the pin**, via `createPinnedAuthMiddleware`'s
+  `inner`, never beside it in the middleware array. The array's first element is the outermost one,
+  so a retry placed there re-enters the pin per attempt — and where the epoch is read per request
+  (`api.auth`) every attempt re-pins to whoever is signed in by then. A 503 backoff is long enough
+  for a sign-out to land in.
+- **A rotation or a restore that _fails_ after its session ended must be re-labelled before the
+  error travels on.** A raw 401 is read as "this credential is dead" by `credential.ts` and as "the
+  stored token is dead" by `restore()`, and both then act on the session that replaced it — signing
+  it out, or clearing the storage entry it just wrote. Compare the epoch in the `catch` as well as
+  after the `await`.
+
+⚠️ **A second `createKeboola()` is not the way to reach a second project — it signs you out of both.**
+Both instances hold the same single-use refresh token, and refresh _rotates_ it, with two-phase
+rotation and replay detection on the server. Whichever instance rotates first invalidates the other's
+token, whose next refresh 401s and signs it out. This is a functional break, not a style preference,
+and it does not depend on a `storage` adapter being configured.
+
 In React, `useApiClient()` returns `api`; `AuthProvider` (bearer) / `LegacyAuthProvider` (legacy) own
 driving the `session` to ready and gate on a `fallback`. See
 [`@keboola/api-client-react`](../api-client-react/AGENTS.md).
@@ -108,7 +189,8 @@ const { api, session } = createKeboola({ baseUrl, storage: createLocalStorage()
 // On startup, call `session.restore()` to rehydrate: it exchanges the persisted refresh token for a
 // fresh credential eagerly (before any request), then re-scopes to the stored project. It resolves
 // `{ status: 'restored' | 'empty' | 'expired' }` — `expired` means the refresh token was dead and the
-// stored session was cleared; route to login. `session.reset()` clears the stored session.
+// stored session was cleared; route to login. `session.reset()` clears the stored session — and one
+// landing mid-restore wins: the restore resolves `empty` rather than signing the user back in.
 const result = await session.restore();
 ```
 
@@ -323,7 +405,7 @@ Surfacing — toast vs inline:
 
 `@keboola/api-client/domain/permissions` holds token-only capability predicates: `canX` (boolean, safe in any UI condition) paired with `assertCanX` (throws `PermissionDeniedError` before any HTTP round-trip). Catch the error to gate UI without a network call; let it propagate from `useQuery` to surface a "no access" empty state.
 
-Implemented today: `admin.ts` (`isAdmin`, `isProductionManager`, … + matching `assertCan*`, all `(token)`-only) and `configurations.ts` (`canCreate/canCopy/canMigrateFromTemplate/canPurge/canAssignFolder` + `assertCan*`, taking a trailing `ctx: ConfigurationCtx`). `storage.ts`, `devBranches.ts`, `sandboxes.ts`, `organization.ts` are still `export {}` placeholders.
+Implemented today: `admin.ts` (`isAdmin`, `isProductionManager`, … + matching `assertCan*`, all `(token)`-only), `configurations.ts` (`canCreate/canCopy/canMigrateFromTemplate/canPurge/canAssignFolder` + `assertCan*`, taking a trailing `ctx: ConfigurationCtx`), and `organization.ts` (`isOrganizationMember`, `isOrganizationAdmin`, `canWriteKaiSpendCaps`, all `(token)`-only — reads `StorageToken.admin.isOrganizationMember` rather than the project role string; `assertCanAdministerOrganization`/`assertCanWriteKaiSpendCaps` pair with the latter two, `isOrganizationMember` is a raw signal with no assert). `storage.ts`, `devBranches.ts`, `sandboxes.ts` are still `export {}` placeholders.
 
 ```ts
 import { PermissionDeniedError } from '@keboola/api-client/domain/permissions';
@@ -424,7 +506,7 @@ owns the store, `credential.ts`, `middleware.ts` and `tokenExpiry.ts` — the an
 Three things about it are unusual:
 
 - **Generated from the spec, like every other client.** `https://apps-api.keboola.com/docs/openapi.yaml`
-  is registered in `redocly.yaml`, so `pnpm gen:types` refreshes
+  is registered in `redocly.yaml`, so `pnpm gen:types developerPortal` refreshes
   `developerPortal/__generated__/schema.d.ts` and `types.ts` derives from it. **The spec is the source of
   truth** — if it is wrong, fix it in `keboola/developer-portal` and regenerate, rather than
   hand-writing a parallel shape here.
@@ -441,7 +523,9 @@ Three things about it are unusual:
 
 ## Testing with `@keboola/api-fixtures`
 
-`@keboola/api-fixtures` provides typed, endpoint-keyed fixtures so tests don't hand-roll response shapes. Early today (storage tables only); extend it as more services need coverage.
+`@keboola/api-fixtures` provides typed, endpoint-keyed fixtures so tests don't hand-roll response shapes. It covers the storage bootstrap and tables, apps, and the developer portal; extend it as more services need coverage.
+
+**This package's own tests cannot use it** — `api-fixtures` depends on `api-client`, so the reverse edge is a build cycle. Tests here keep hand-rolled bodies; consumers get the fixtures.
 
 ```ts
 import { fixtures, getTable, listTables, tableFixtures } from '@keboola/api-fixtures';
@@ -609,7 +693,7 @@ A new client/namespace means touching four places that must stay in lock-step
 3. `package.json` `typesVersions` — add `<x>` and `<x>/types`
 4. `src/keboola/createServiceClients.ts` — register the client in the registry with `.add({ serviceId, clientName, clientFn })` (+ `src/keboola/createMiddlewareFor.ts` for its `ServiceClientName` entry and any bespoke middleware)
 
-Full mechanical steps (redocly registration, `pnpm gen:types`, file templates) live in [`README.md` → Adding a New OpenAPI Client](./README.md#adding-a-new-openapi-client). Add typed fixtures to `@keboola/api-fixtures` alongside the client so consumers can test against it.
+Full mechanical steps (redocly registration, `gen:types`, file templates) live in [`README.md` → Adding a New OpenAPI Client](./README.md#adding-a-new-openapi-client). Add typed fixtures to `@keboola/api-fixtures` alongside the client so consumers can test against it.
 
 **Worked example — the `auth` client.** `packages/api-client/src/clients/auth/*` (`authClient.ts`, `pkce.ts`, `index.ts`, `types.ts`) is a self-contained new service added this way: it exposes `./auth` + `./auth/types` sub-paths and is surfaced by `src/keboola/createApi.ts`. Read it as the reference shape for a new client rather than copying boilerplate. **Bearer auth lives in `keboola/bearer/`, not the auth client**, since it's specific to the bearer engine: `credential.ts` is a token provider (`getAccessToken({ forceRefresh })` returns a valid token, refreshing — deduped — when near expiry or forced), and `middleware.ts` is a thin policy that on every request asks the credential for a token and stamps the `Authorization` header, and on 401 force-refreshes and replays once. Session-expiry is latched (fire-once, re-armed per session) in `createConfig.notifyExpired`, not the credential — the credential and middleware are long-lived singletons. The middleware holds no token and reads no config — all token state is in the credential, whose `getToken` reads live from `config` so a rotation is picked up without rebuilding. See `keboola/bearer/keboola.ts` for the wiring.
 

package/API-SURFACE.md

@@ -4,7 +4,7 @@
 
 Every namespace and method reachable from a ready `KeboolaApi` — the `api` half of a keboola client (`createKeboola(...).api` / `createLegacyKeboola(...).api`, or `useApiClient()`). Generated from the TypeScript type checker — see `scripts/gen-surface.mjs`.
 
-24 top-level namespaces, 621 methods. This index lists method **names** only — full signatures live per namespace under [`surface/`](./surface). Open `surface/<namespace>.md` for the one you need.
+24 top-level namespaces, 624 methods. This index lists method **names** only — full signatures live per namespace under [`surface/`](./surface). Open `surface/<namespace>.md` for the one you need.
 
 ## [`api.ai`](./surface/ai.md)
 
@@ -184,6 +184,7 @@ Every namespace and method reachable from a ready `KeboolaApi` — the `api` hal
 - `getHistory`
 - `getSandboxGitBranch`
 - `getSkillsList`
+- `getSpendCaps`
 - `getSuggestions`
 - `getToolsList`
 - `getUsage`
@@ -192,10 +193,12 @@ Every namespace and method reachable from a ready `KeboolaApi` — the `api` hal
 - `healthCheck`
 - `listSandboxFiles`
 - `readSandboxFile`
+- `setUserSpendLimit`
 - `stopChat`
 - `submitToolOutput`
 - `submitVote`
 - `updateAgentSettings`
+- `updateSpendCaps`
 - `updateUserAgentSettings`
 
 ## [`api.management`](./surface/management.md)
@@ -621,7 +624,7 @@ Every namespace and method reachable from a ready `KeboolaApi` — the `api` hal
 - `triggers.getTriggers`
 - `triggers.updateTrigger`
 - `workspaces.deleteWorkspace`
-- `workspaces.deleteWorkspaceJob`
+- `workspaces.deleteWorkspaceAsync`
 - `workspaces.deleteWorkspaceObjectsAsync`
 - `workspaces.deleteWorkspaces`
 - `workspaces.getWorkspace`

package/CHANGELOG.md

@@ -1,5 +1,332 @@
 # @keboola/api-client
 
+## 33.0.0
+
+### Minor Changes
+
+- `createEmitter` delivers events in emission order, never nested, and `Store` gains `asReadable()`.
+  - An `emit` from inside a listener is queued until the current pass has reached every listener, so
+    no listener hears event N+1 before event N. For a store this means a subscriber that writes back
+    can no longer leave a later subscriber on stale state — the last notification is always the
+    latest value.
+  - A listener's own emit is handled after it returns; a throwing listener is logged and does not
+    stall the queue behind it. Nothing is coalesced: every event is delivered.
+  - A pass reaches the listeners present when it began. Subscribing from inside a listener no longer
+    delivers the event in flight to the new listener — it hears the next one, as it would have had it
+    subscribed a moment earlier. Unsubscribing (or `clear()`) from inside a listener still takes
+    effect immediately for the rest of that pass.
+  - `store.asReadable()` returns the same store without `set` — the read-only view consumers were
+    building by hand from `get` / `subscribe` / `dispose`.
+
+- `auth.pat.create` / `auth.pat.exchange` take a `CreatePatInput` / `ExchangePatInput` whose optional
+  fields may be left out, and drop the keys a caller passes as `null` instead of putting them on the
+  wire. The spec documents every optional PAT field as "omit, do not send `null`", but the generated
+  bodies demand each of them, so a caller holding a nullable — an empty expiry picker, an untouched
+  read-only switch — had no way to express the default. `scope` gains the same treatment: a
+  `{ projects, readOnly }` that narrows nothing is sent as no `scope` at all.
+
+  Existing calls keep compiling and keep their behaviour, since the previously required
+  `expiresIn: null` / `scope: null` is what the normaliser now drops.
+
+- The semantic layer's closed value sets ship as runtime lists, so an authoring surface no longer
+  writes them out by hand. `FIELD_ROLES`, `CONSTRAINT_SEVERITIES`, `CONSTRAINT_SCOPES`,
+  `RULE_OPERATORS` and `RELATIONSHIP_JOIN_TYPES` join `SQL_DIALECTS` and `CONSTRAINT_TYPES`, which
+  move to the same module and keep their existing import paths.
+
+  ```ts
+  import {
+    CONSTRAINT_SCOPES,
+    metastoreErrorMessage,
+  } from "@keboola/api-client/sdk/semanticLayer";
+  import type { SemanticConstraintScope } from "@keboola/api-client/sdk/semanticLayer/types";
+
+  // a total label map, so a scope the metastore adds is a compile error rather than a missing option
+  const SCOPE_LABELS: Record<SemanticConstraintScope, string> = {
+    global: "Global" /* … */,
+  };
+  const options = CONSTRAINT_SCOPES.map((value) => ({
+    value,
+    label: SCOPE_LABELS[value],
+  }));
+  ```
+
+  - Each union in `./types` is now derived from its list rather than spelled out again, so the type
+    and the list a validator or a dropdown is built from cannot disagree. `SemanticConstraintSeverity`
+    and `SemanticRelationshipJoinType` are named for the first time; they were inline unions on
+    `SemanticConstraintData.severity` and `SemanticRelationshipData.type`.
+  - The `./sdk/semanticLayer/types` entry point stays free of runtime code — the derivation reads the
+    lists through an `import type`.
+  - `metastoreErrorMessage(body)` reads the one field that says what is actually wrong with a
+    rejected write (`errors[0].message`, e.g. `missing property 'fqn'`). The status and the
+    response's own message say no more than "Validation failed". Any other shape returns `undefined`,
+    so a caller keeps its own fallback.
+
+- Reach several projects from one bearer session with `session.forProject(projectId)`
+
+  A bearer access token is a user token — project scope is a single `X-KBC-ProjectId` header — so one
+  session can legitimately address many projects. Until now only the scoped project had clients, and
+  the obvious workaround was a second `createKeboola()`, which signs both instances out: they hold the
+  same single-use refresh token, and the first to rotate invalidates the other's.
+
+  `session.forProject(projectId)` returns that project's `ProjectClients` off the session in hand,
+  reusing its credential and auth middleware, so a token rotation happens once for every project rather
+  than once each. `setProjectAsync` moves the session (and `api`); `forProject` adds a project alongside
+  it. A project is bootstrapped once and concurrent callers share that build; a failed build is
+  retryable.
+
+  Every client set is pinned to the sign-in that built it, so `reset()` is a teardown rather than a
+  cache eviction — a set held across a sign-out throws `NotAuthenticated` on its next request, the 401
+  replay included, instead of quietly acting as whoever signed in after. `clearProject()` drops the
+  scope, not the credential, and leaves the extra projects alone. Nothing extra is persisted.
+
+  The same pin covers every other surface that emits this session's credential.
+  `api.storage`/`api.context` and `api.management` rebuild on sign-out, but that could not stop a
+  request already in flight from completing as the next user, with the previous project's
+  `X-KBC-ProjectId` still on it. `session.getAuthHeaders()` resolved to the dead session's token and
+  project, because the proactive rotation swallows its own refusal. A token rotation is pinned to the
+  sign-in that spent the refresh token, so one resolving after its own session ended is dropped rather
+  than written over the credential of whoever signed in since, and a sign-out abandons the in-flight
+  rotation so the next session starts its own. `api.auth` is built once per stack and serves every
+  session, so it pins each _request_ to the sign-in that started it: a 401 recovery no longer replays
+  as the next user, while `login` still goes out unstamped. `session.restore()` is pinned too — a
+  sign-out landing while the stored token is being exchanged resolves `empty` instead of signing the
+  user back in.
+
+  The guard wraps the **credential**, not only the outgoing request, because the 401 path rotates the
+  token by calling the credential directly: a straggler from a dead session would otherwise spend the
+  live session's single-use refresh token, and sign that session out if the rotation itself came back 401.
+
+  The pin covers the failure branches too, which is where it was missed. A retry re-invokes `next`,
+  so `retryContention` is composed _inside_ the pin rather than beside it in the auth client's
+  middleware array — outside it, an `api.auth` request that hit a 503 re-pinned per attempt and the
+  retry went out as whoever signed in during the backoff. And a rotation or a restore that _fails_
+  after its session ended is re-labelled `NotAuthenticated` before the error travels on: a raw 401
+  reads as "this credential is dead" to the credential and as "the stored token is dead" to
+  `restore()`, so a straggler used to sign out the session that replaced it, and a losing concurrent
+  restore used to clear the winner's stored session — leaving it alive in memory and gone on the next
+  reload.
+
+  A project the session cannot reach now fails its own build and nothing else. Connection answers a
+  denied or nonexistent project with the same `invalid_token` 401 as a revoked token, so `forProject`
+  reads a 401 that survives a token rotation as being about the project rather than the credential —
+  a mistyped project id used to sign the whole session out.
+
+  `ProjectClients` is now exported as a type.
+
+### Patch Changes
+
+- `kaiAgent`'s spend-caps response gains `defaultProjectCapPpu` — the bare platform default project
+  cap, independent of what's persisted. Previously only `effectiveProjectCapPpu` (the server's
+  resolution of the _persisted_ cap) was exposed, which a consumer could not use to validate a
+  cleared-but-unsaved project-cap field against the true default.
+
+- `kaiAgent`'s generated schema is regenerated against the deployed spec, so `getUsage` reports the
+  spend-cap scope and the one project-level figure a plain member is shown.
+  - `getUsage` gains `ppuLimitScope: 'user' | 'project' | null` — which ceiling stops the caller next.
+    A label, never a figure: the project's absolute budget stays admin-only.
+  - `getUsage` gains `projectPpuPercentage: number | null` — how much of the project's cap is spent.
+    It is the fallback a caller with no personal `ppuLimit` is measured against, and `null` only
+    where no project cap applies at all.
+  - `getChat` gains `ppuPercentage: number | null`, the same figure alongside a conversation.
+  - The `rate_limit` error `subtype` splits `monthly_credits` into `monthly_credits_user` and
+    `monthly_credits_project`.
+  - Additive drift the same regeneration picked up: the `/api/settings/spend-caps` pair, the
+    `/api/chat/{id}/sandbox/file/download` path, and a `payload_too_large` error type with its 413.
+
+- `Result` gains constructors, guards and combinators, so code that returns a `Result` of its own no
+  longer writes the object literal, and code that consumes one no longer branches on `success` by
+  hand.
+
+  ```ts
+  import { Result } from "@keboola/api-client";
+
+  const getStack = (id: string): Result<Stack> =>
+    stacks.has(id)
+      ? Result.success(stacks.get(id))
+      : Result.failure(new Error(`No stack "${id}"`));
+
+  // handle both branches in one expression, Rust-match style
+  const label = Result.match(
+    getStack(id),
+    (stack) => stack.name,
+    (error) => error.message,
+  );
+
+  // at a layer boundary, relabel the failure as the error this layer speaks, then throw it
+  const stack = Result.unwrap(
+    Result.mapError(
+      getStack(id),
+      () => new KeboolaError(KeboolaErrorType.Unconfigured),
+    ),
+  );
+  ```
+
+  - `success` is `Result<T, never>` and `failure` is `Result<never, E>`, so either widens into any
+    `Result<T, E>` without an annotation. `Success<T>` and `Failure<E>` name the two branches.
+  - `isSuccess` / `isFailure` are type guards; `map`, `mapError` and `andThen` rewrite one branch
+    and pass the other through untouched.
+  - `match(result, onSuccess, onFailure)` returns whichever callback ran, so the two must agree on a
+    type; `void` works. `unwrap` throws the error as-is; `unwrapOr` returns a fallback instead.
+  - `tryCatch` and `fromThrowable` reject a task that returns a promise at the type level, since they
+    would report success before it settles. Use `tryCatchAsync` / `fromThrowableAsync` for those.
+
+- `TableDetail` declares the three freshness fields the detail response carries: `lastImportDate`,
+  `lastChangeDate` and `rowsCount`.
+
+  ```ts
+  const table = await api.storage.tables.getTable({ branchId, id });
+  // `null` is the table's own answer — nothing has ever been written into it.
+  if (table.lastImportDate === null) return "Nothing loaded yet";
+  ```
+
+  - Declared required, where `TableDetailResponse` in the generated schema marks them optional. That
+    node marks `?` on every nullable field it has, so the marker conflates "nullable" with
+    "optional"; `TableCreateResponse` — which the table list reuses — and `AliasFilterSetResponse`
+    declare the same fields required-and-nullable. `Table` and `TableDetail` now agree on all three.
+  - `null` means different things per field, and each one says so: never written into
+    (`lastImportDate`), and Storage declining to count rather than a count of zero (`rowsCount`).
+
+- `isTimeoutError` joins `isAbortError` in the fetch-client error taxonomy, exported from both
+  `@keboola/api-client` and `@keboola/api-client/fetchClient`.
+
+  ```ts
+  import { isTimeoutError } from "@keboola/api-client";
+
+  // `DOMException('signal timed out', 'TimeoutError')` — what an `AbortSignal.timeout` rejects with.
+  if (isTimeoutError(error)) return null;
+  ```
+
+  - Matches on `DOMException.name`, since the message is a browser string rather than a contract.
+  - Distinct from `isAbortError`: a timeout is the deadline expiring, an abort is someone cancelling.
+  - `xhrFetch` is not covered — its `handleAbort` builds an `AbortError` without reading
+    `signal.reason`, so a timeout on that transport reports as a cancel.
+
+  `@keboola/sentry`'s shared `beforeSend` is the first caller: a request that never got a response
+  measures the network, not the code, and reports with no stacktrace.
+
+- Security patches for transitive dependencies: qs 6.16.0 in api-client, mermaid 11.17.2 and dompurify
+  3.4.14 in design.
+
+  No API or behaviour change in either package.
+
+- Interpret the org-admin `kai-assistant.monthlyCreditsLimitPerUser` Storage key as PPU (the same
+  unit an admin sees and sets everywhere else, per AI-3628), converting it to the internal
+  Kai-credits ceiling at the read boundary. `@keboola/api-client`'s kai-agent schema regenerated to
+  pick up `ppuUsed`/`ppuLimit` on `GET /api/usage`; `@keboola/kai-fake-agent`'s stub updated to match.
+  `@keboola/kai-agent` and `@keboola/kbc-ui` are private, nothing to release for them — acknowledged
+  so `changeset status` doesn't choke on them alongside the real `@keboola/api-client` release.
+
+- Show Kai spend caps in project settings and scope-aware chat copy (AI-3738).
+
+  `@keboola/api-client`'s kai-agent client/surface-docs regenerated for the spend-caps endpoints;
+  `@keboola/constants`, `@keboola/kai-fake-agent`, `@keboola/kai-agent` and `@keboola/kbc-ui` are
+  private, nothing to release for them — acknowledged so `changeset status` doesn't choke on them.
+
+## 32.0.0
+
+### Major Changes
+
+- Adopt Connection's OpenAPI spec fixes across the storage, management and auth clients.
+
+  Breaking changes to the storage surface:
+  - `workspaceId` is a `number` on all nine workspace operations, and `versionId` a `number` on the
+    configuration-version ones — both were `string` on some and `number` on others.
+  - `branchId` is the `string` the spec declares, and is now required: `configurations`,
+    `configurationRows`, `configurationVersions`, `configurationMetadata`, `components` and `events`
+    no longer default it to `'default'`. `components.getComponents` and
+    `configurations.searchComponentConfigurations` therefore take an argument.
+  - `metadataId` is the spec's integer on all nine metadata deletes; the `MetadataId` alias is gone.
+  - `DevBranch` is a union discriminated on `isDefault`, since the default branch carries no
+    `creatorToken`.
+  - `deleteWorkspaceJob` is renamed `deleteWorkspaceAsync`.
+  - `File.sizeBytes` is nullable, as the serializer returns.
+  - `BranchMetadataEntry`, `BranchMetadataRaw` and `PreparedFile` are removed — all three unused.
+
+  New: a per-call `parseAs` option on every client method (`'auto' | 'text' | 'json' | 'blob'`),
+  defaulting to the existing content-type dispatch. `storage.files.getFileContent` uses it to return
+  a file's exact bytes instead of re-serialising JSON files.
+
+- `STACKS` is typed by its own key set instead of `Record<string, …>`. A name the registry does not
+  carry is now a compile error at the call site, so code can read `STACKS.US_EAST_1_AWS.host` without
+  an `undefined` to fall back from. The entries and their `KeboolaStack` value type are unchanged.
+
+  Breaking for typed consumers: a lookup by a non-literal key — `STACKS[someRuntimeString]` — stops
+  type-checking. Narrow the key first (`if (key in STACKS)`), or iterate `Object.values(STACKS)` when
+  the name itself does not matter.
+
+### Minor Changes
+
+- Let a bearer session hand out the headers for a request the client does not make itself.
+
+  `session.getAuthHeaders()` resolves `Authorization: Bearer <token>` plus `X-KBC-ProjectId`, going through the credential on every call — so a near-expiry token rotates and a revoked one is never re-sent. It exists for transports this package does not own, chiefly the chat SSE stream whose `fetch` the AI SDK holds; anything with a service client on `api` should keep using that.
+
+  It returns the assembled bag rather than the access token, so no caller handles the credential as a bare string and the project header is composed in one place. An anonymous or unscoped session throws instead of emitting a half-formed `Bearer null`.
+
+- Microsoft Graph joins the SDK as a standalone client on two new sub-paths, `@keboola/api-client/microsoftGraph` and `@keboola/api-client/microsoftGraph/types`.
+
+  ```ts
+  import {
+    createMicrosoftGraphAuthMiddleware,
+    createMicrosoftGraphClient,
+  } from "@keboola/api-client/microsoftGraph";
+
+  // The client holds no credential — auth arrives as a middleware. Not a singleton either: a Graph
+  // token is minted per user interaction by your own OAuth flow (MSAL in the browser) and is scoped
+  // to one account, so build a client where you hold it. There is no `sdks/microsoftGraph/` because
+  // MSAL owns refresh; this package has no token state to manage.
+  const graph = createMicrosoftGraphClient({
+    middlewares: [createMicrosoftGraphAuthMiddleware(accessToken)],
+  });
+  const item = await graph.getFile(driveId, fileId, signal);
+  ```
+
+  It exposes `getMySite`, `getMyDrive`, `getFile` and `getDriveItemBySharingUrl` (which redeems a sharing URL into the real `DriveItem`, for "Shared with me" SharePoint files the picker returns with empty ids). Graph is not a Keboola service, so — like `assets` and `status` — it is **not** on `api.*` and is never registered in `createServiceClients.ts`; it also defaults its own `baseUrl`, since a vendor's host and version prefix are part of its API contract rather than something we discover, and it carries no `healthCheck`.
+
+  Types come from Microsoft's own OpenAPI document, but **vendored as a slice** rather than fetched whole: the published v1.0 description covers all of Graph at ~41MB and generates 35MB of `.d.ts`, which this package's declaration emit crashes on (`rolldown-plugin-dts` throws; the previous tsup build hit `ERR_WORKER_OUT_OF_MEMORY` on the same file) and which would ship in the tarball. A `gen:types` run that selects `microsoftGraph` vendors a slice of only the operations the client calls, then generates from it (~650KB of declarations); runs that don't select it never touch the slice. Adding an operation means listing its path in `scripts/vendor-microsoft-graph-spec.mjs`; see `docs/regenerate-api-types.md`.
+
+  The client wires **no transport-level retry**, matching every other client here — where superagent
+  applied 3 attempts (network errors, and 5xx on GET), a transient Graph 503 now surfaces to the caller
+  on the first failure. Consumers that want retry choose it per call site: TanStack Query's `retry` for
+  a query, or `createRetryMiddleware` in `middlewares` for a client whose every call should retry. The
+  OneDrive pickers deliberately take neither — they run inside an interactive MSAL flow where a silent
+  multi-second retry is worse than a prompt failure the user can act on.
+
+  One fix reaches beyond this client: `OpenapiSuccessType` now understands OpenAPI 3 **range** response codes (`2XX`). Operations declaring a range instead of an explicit status previously resolved to `unknown`; ranges are checked after the explicit codes, so a spec declaring both still resolves to the precise one.
+
+- Consumers can now import the kai-agent client directly from `@keboola/api-client/kaiAgent` instead of going through the main barrel.
+
+- `@keboola/api-client/kaiAgent/types` is now its own subpath, exporting `ChatWithMessages` for the `/api/chat/{id}` response — so consumers can derive the chat-detail shape from kai-agent's spec instead of transcribing it.
+
+### Patch Changes
+
+- Add organization-admin permission predicates (AI-3738).
+
+  `domain/permissions/organization.ts` (previously an empty placeholder) now exports
+  `isOrganizationMember`, `isOrganizationAdmin`, `canWriteKaiSpendCaps`, plus
+  `assertCanAdministerOrganization`/`assertCanWriteKaiSpendCaps` (`isOrganizationMember` is a raw
+  signal with no assert pair), mirroring `admin.ts`'s conventions — `canWriteKaiSpendCaps` is
+  strictly stricter than the existing `canWriteKaiSettings` (admin/share only vs. organization-admin
+  only).
+
+- Shrink the permission tests' `StorageToken` fixture to the fields they read.
+
+  `buildStorageToken` transcribed all ~40 fields of the contract shape so it could be annotated `: StorageToken`. Its consumers read three of them — `isMasterToken`, `admin.{role,isOrganizationMember}` — plus `owner.{features,hasSnowflake,hasBigquery}` via `createProject()`, and its `features` / `adminFeatures` options were passed by no caller. The fixture now builds only that, cast at the boundary; the contract-typed `StorageToken` fixtures live in `@keboola/api-fixtures`, which is where a field the backend adds should fail to compile. No published behaviour changes.
+
+- Add a `storage.bootstrap` fixture slice — the three responses a client's ready gate needs before
+  it is usable (`GET /v2/storage`, `/v2/storage/tokens/verify`, `/v2/storage/dev-branches`).
+
+  `getStackInfo()`, `verifyStorageToken()` and `getDevBranches()` are typed by
+  `@keboola/api-client/storage/types`, so a field the backend adds arrives with `pnpm gen:types`
+  rather than being transcribed into every MSW test that bootstraps a client. `getStackInfo()`
+  announces every service by default, which is what keeps a test's queue / data-science / vault
+  client from being a dummy that throws `ServiceUnavailableError`; pass `services` to narrow it.
+
+  `@keboola/api-client` gains a runtime `ServiceId` const in `@keboola/api-client/constants`, with
+  the `ServiceId` type now derived from it. Announcing every service is exhaustive by construction:
+  a service added to the client flows into the fixture without an edit.
+
+  `@keboola/api-client-react`'s test fixtures now come from the slice; its published output is unchanged.
+
 ## 31.0.0
 
 ### Minor Changes

package/README.md

@@ -522,24 +522,20 @@ apis:
 
 #### Step 2: Generate Types
 
-Run the type generation command:
+Name the service you just registered, so the other schemas stay untouched:
 
 ```bash
-pnpm gen:types
+pnpm --filter @keboola/api-client gen:types yourNewService
 ```
 
-This will create the TypeScript definitions at the specified output path. Leave the generated file's
-contents alone — `oxlint.config.ts` turns `consistent-type-definitions` off for
+This will create the TypeScript definitions at the specified output path, already formatted. Leave
+the generated file's contents alone — `oxlint.config.ts` turns `consistent-type-definitions` off for
 `src/clients/*/__generated__/*.d.ts`, so the `export interface operations` the generator emits
-despite `--export-type` is fine as it stands. Two mechanical steps do follow: run `oxfmt` on the new
-file (the raw output is 4-space), and revert the other schemas the command regenerated — it rewrites
-all of them, mostly reformatting. See
-[`docs/regenerate-api-types.md`](./docs/regenerate-api-types.md).
+despite `--export-type` is fine as it stands.
 
-`gen:types` regenerates every source in `redocly.yaml`, so to generate only the new one, run
-`openapi-typescript` directly against its URL from a directory without a `redocly.yaml` (it
-auto-discovers the file up the tree and ignores a positional URL when it finds one) with an absolute
-`--output`.
+Passing no service regenerates every source in `redocly.yaml`, which is a full refresh, not what
+adding one client calls for. See [`docs/regenerate-api-types.md`](./docs/regenerate-api-types.md)
+for the local-backend workflow and for services with no `redocly.yaml` entry.
 
 #### Step 3: Create the Client Implementation
 
@@ -624,15 +620,42 @@ import { createYourNewServiceClient } from './clients/yourNewService';
 
 ### Adding a New Generic Client
 
-Follow the same steps but use `createGenericFetchClient` instead of `createOpenapiFetchClient`. No `redocly.yaml` registration or `pnpm gen:types` step is needed. Define request/response types manually.
+Follow the same steps but use `createGenericFetchClient` instead of `createOpenapiFetchClient`. No `redocly.yaml` registration or `gen:types` step is needed. Define request/response types manually.
+
+### `gen:types` — regenerating OpenAPI types
+
+Every `__generated__/schema.d.ts` comes out of one command, scoped to the services you name:
+
+```bash
+pnpm --filter @keboola/api-client gen:types --list          # what can be regenerated
+pnpm --filter @keboola/api-client gen:types storage         # one service — leaves the rest alone
+pnpm --filter @keboola/api-client gen:types chat queue      # several
+pnpm --filter @keboola/api-client gen:types                 # every API in redocly.yaml
+
+# One service's spec from a local dev server instead of its registered URL:
+pnpm --filter @keboola/api-client gen:types chat --url http://localhost:3001/api/docs
 
-### OpenAPI Type Generation Workflow
+```
 
-1. Update API specifications (if needed, edit `redocly.yaml`)
-2. Run `pnpm gen:types` to regenerate TypeScript definitions
-3. Review generated files in `__generated__/` directories
-4. Update client implementation if the API surface changed
-5. Always commit generated files to version control
+A service is named by its `redocly.yaml` key. Local-backend ports for `chat` and `kaiAgent` are in
+[`docs/regenerate-api-types.md`](./docs/regenerate-api-types.md).
+
+How it behaves:
+
+- **Only the named services' `schema.d.ts` files are rewritten**; every other schema is untouched.
+  (`openapi-typescript` has no per-API flag, so the script hands it a filtered copy of
+  `redocly.yaml` in a temp directory.)
+- **Output is committable as generated** — the script runs `oxfmt` over it, so a diff is the spec
+  change, not whitespace. Commit the generated files.
+- **Bad invocations exit non-zero** with the service listing appended: an unknown service name, or
+  `--url` with anything but exactly one service.
+- **`microsoftGraph` is the one local `root`** — a committed slice of Microsoft's ~41MB Graph
+  document. A run that selects it re-vendors the slice from upstream first, so naming the service
+  fetches its current spec exactly as every URL root does; a run that doesn't select it can never
+  re-pin the slice. If the download fails, or an operation in the slice no longer exists upstream
+  (a Microsoft rename), the run warns, keeps the committed slice, and carries on — it only
+  hard-fails when there is no committed slice to fall back on. Why a slice at all:
+  [`scripts/vendor-microsoft-graph-spec.mjs`](./scripts/vendor-microsoft-graph-spec.mjs).
 
 ### redocly.yaml Configuration Reference
 
@@ -643,3 +666,6 @@ apis:
     x-openapi-ts:
       output: ./src/clients/serviceName/__generated__/schema.d.ts
 ```
+
+`root` is normally a URL the generator fetches; the one local-file `root` (`microsoftGraph`) is the
+vendored slice described in the [`gen:types` section](#gentypes--regenerating-openapi-types) above.

package/dist/{ManagementClientAuthError-DFhi5yxe.cjs → ManagementClientAuthError-DqeXL8nv.cjs}

@@ -1,4 +1,4 @@
-const require_createFetchClient = require("./createFetchClient-B9Cv0W9f.cjs");
+const require_createFetchClient = require("./createFetchClient-DvZvD31l.cjs");
 //#region src/errors/ManagementClientAuthError.ts
 var ManagementClientAuthError = class extends require_createFetchClient.ApiError {
 	title;
@@ -17,4 +17,4 @@ Object.defineProperty(exports, "ManagementClientAuthError", {
 	}
 });
 
-//# sourceMappingURL=ManagementClientAuthError-DFhi5yxe.cjs.map
+//# sourceMappingURL=ManagementClientAuthError-DqeXL8nv.cjs.map