@keboola/api-client 32.0.0 → 34.0.0

package/AGENTS.md

@@ -77,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)`.
 
@@ -98,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).
@@ -112,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();
 ```
 
@@ -383,9 +461,9 @@ api.sdk.tag.*        api.sdk.storage.*
 
 Clients backing optional stack services (vault, queue, …) throw `ServiceUnavailableError` if absent from the current stack — check `api.context.stack.hasService(...)` before assuming a namespace exists.
 
-**Liveness: every service client exposes a root-level `healthCheck()`** (all but `telemetry`, which has no such endpoint). It resolves with the service's payload when up and throws like any other call when not, and it needs no session — every one of these endpoints answers unauthenticated, so a probe works before login and is indifferent to whether a token rides along. Probe a service that way rather than by calling a real endpoint and interpreting the failure. **A 200 means up and a throw means down — that is the whole contract.** The payload is incidental, so **never hand-roll a response type** to make it look useful. Adding a client means adding its `healthCheck` too, and which client you probe through follows from the spec:
+**Liveness: every service client exposes a root-level `healthCheck()`.** It resolves with the service's payload when up and throws like any other call when not, and it needs no session — every one of these endpoints answers unauthenticated, so a probe works before login and is indifferent to whether a token rides along. Probe a service that way rather than by calling a real endpoint and interpreting the failure. **A 200 means up and a throw means down — that is the whole contract.** The payload is incidental, so **never hand-roll a response type** to make it look useful. Adding a client means adding its `healthCheck` too, and which client you probe through follows from the spec:
 
-- the service's spec declares the probe path → **probe through the client's own OpenAPI client** (`client.get('/health-check', {}, { signal })`). The return type comes from the spec for free — no type argument, no alias in `types.ts`, and no generic client to construct. Five do today: `ai`, `editor`, `import`, `chat` (which probes `/ping`) and `apps` (which probes `/`, the only unauthenticated root the `/v2` surface declares).
+- the service's spec declares the probe path → **probe through the client's own OpenAPI client** (`client.get('/health-check', {}, { signal })`). The return type comes from the spec for free — no type argument, no alias in `types.ts`, and no generic client to construct. Six do today: `ai`, `editor`, `import`, `telemetry`, `chat` (which probes `/ping`) and `apps` (which probes `/`, the only unauthenticated root the `/v2` surface declares).
 - it doesn't → fall back to a generic fetch client over the service `baseUrl` and **pass no type argument.** The payload resolves as `unknown`, which is honest: callers only need the 200.
 
 Both clients run the same middleware chain; the OpenAPI one additionally sends auth headers, which is fine — these endpoints answer the same with a valid token, a bogus one, or none.

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.
+25 top-level namespaces, 635 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)
 
@@ -85,6 +85,12 @@ Every namespace and method reachable from a ready `KeboolaApi` — the `api` hal
 - `webauthn.registerOptions`
 - `webauthn.remove`
 
+## [`api.billing`](./surface/billing.md)
+
+- `getCredits`
+- `getCreditsAndTopUp`
+- `healthCheck`
+
 ## [`api.chat`](./surface/chat.md)
 
 - `createChat`
@@ -184,6 +190,7 @@ Every namespace and method reachable from a ready `KeboolaApi` — the `api` hal
 - `getHistory`
 - `getSandboxGitBranch`
 - `getSkillsList`
+- `getSpendCaps`
 - `getSuggestions`
 - `getToolsList`
 - `getUsage`
@@ -192,10 +199,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)
@@ -279,6 +288,13 @@ Every namespace and method reachable from a ready `KeboolaApi` — the `api` hal
 - `organizations.removeOrganizationUser`
 - `organizations.setOrganizationMetadata`
 - `organizations.updateOrganization`
+- `payAsYouGo.createPaymentRequest`
+- `payAsYouGo.getBillingConfiguration`
+- `payAsYouGo.getCreditPurchases`
+- `payAsYouGo.getStripeCustomer`
+- `payAsYouGo.getTopUpSetting`
+- `payAsYouGo.updateStripeCustomer`
+- `payAsYouGo.updateTopUpSetting`
 - `projects.addProjectFeature`
 - `projects.addProjectTemplateFeature`
 - `projects.addProjectUser`
@@ -688,7 +704,8 @@ Every namespace and method reachable from a ready `KeboolaApi` — the `api` hal
 
 ## [`api.telemetry`](./surface/telemetry.md)
 
-- `provisioning.createCredentials`
+- `getProvisioningToken`
+- `healthCheck`
 
 ## [`api.vault`](./surface/vault.md)
 

package/CHANGELOG.md

@@ -1,5 +1,470 @@
 # @keboola/api-client
 
+## 34.0.0
+
+### Minor Changes
+
+- New `approvalGoneReasonSchema` / `ApprovalGoneReason` in `chat/types` — the shared wire contract for why a Kai approval slot is gone.
+
+  kai-agent now tombstones every removed approval slot and answers a POST to a gone slot with 409 carrying the reason as the error envelope's `subtype`, so the client can tell "already processed" and "the chat was stopped" apart from a genuine expiry instead of reading every 404 as one.
+
+- `session.getAuthHeaders()` takes an optional project, so a host holding several projects can
+  authorize an off-client request against one the session is not scoped to. Until now this surface
+  read `X-KBC-ProjectId` off the session's own scope and nothing else, which left the chat SSE stream
+  — its only caller, and the one transport with no service client behind it — able to _read_ another
+  project through `session.forProject(id)` but never to send to it.
+
+  ```ts
+  // The session's own scope, exactly as before.
+  await session.getAuthHeaders();
+
+  // The project the caller names, whatever the session is scoped to.
+  await session.getAuthHeaders(projectId);
+  ```
+
+  - Omitting it is unchanged, including the rule that the scope is re-read _after_ the token
+    rotation: a `setProject` mid-flight lands, and a `clearProject` refuses the call.
+  - Naming one requires the session to be authenticated, not scoped. The credential is user-level and
+    the project is a header on top of it, so a caller that names a project has said everything the
+    request needs.
+  - A named project survives the rotation as given — it is the caller's, not the session's to move —
+    and the session pin is unchanged: a call whose rotation outlived its sign-in is still refused.
+  - The project is **not** checked against an access set, because the session cannot acquire one:
+    connection collapses every bearer failure into a single `invalid_token` response, so "no access to
+    this project" and "revoked token" are indistinguishable. That is the same reason
+    `session.forProject` does not probe scope either. Whether a project is reachable is the caller's
+    knowledge, from `token.introspect`; what this guarantees is that the header names what was asked
+    for and never something else.
+
+- New `api.billing` namespace over the Billing API — the pay-as-you-go credit balance of the project
+  the token identifies.
+
+  ```ts
+  if (api.context.stack.hasService("billing")) {
+    const { remaining, stats } = await api.billing.getCredits();
+  }
+  ```
+
+  The service is a separate stack deployment (service id `billing`), not part of the Manage API that
+  `api.management.payAsYouGo` covers, and `/credits` authenticates with a Storage API token rather
+  than a Manage token — so it gets its own client rather than another method there. Types generate
+  from the service's published spec, newly registered in `redocly.yaml`.
+  - `getCredits` answers only for a project carrying the `pay-as-you-go` feature.
+  - `getCreditsAndTopUp` is the same read with an automatic top-up attempted first, which the service
+    runs only when the balance is at or below zero and the project has a top-up configuration
+    (`management.payAsYouGo.getTopUpSetting`). A charge that fails does not fail the call.
+  - `stats` is absent unless the project has consumption to report.
+
+  Three groups of endpoints stay unwrapped: `/duration/*` and `/marketplaces/{resolve-token,
+confirm-subscription}` are service-to-service calls needing a Manage _application_ token with a
+  `billing:manage` or `marketplace-subscriptions:manage` scope, `/marketplaces/azure-webhook` is
+  called by Azure Marketplace against an Azure-issued JWT, and `/` only restates what `healthCheck`
+  already reports.
+
+  The spec's `servers` block names the queue host rather than the billing one; it is ignored, since
+  every stack client resolves its base URL from the stack's service index.
+
+- `kaiAgent.getHistory` can ask for the conversations one app opened, and every history row says which
+  app opened it.
+
+  ```ts
+  // Only what this app started — a business user never sees the data team's Kai threads.
+  const { chats } = await api.kaiAgent.getHistory({ client: "business-chat" });
+  ```
+
+  kai-agent lists a project's conversations without regard to which host started them, so a second
+  host on the same agent shows its readers somebody else's chats. The service now records the host on
+  the chat and filters on it; this is the SDK half.
+  - `client` is `'kbc-ui' | 'business-chat'`, and omitting it keeps the current behaviour — every
+    conversation, whatever opened it.
+  - The row's own `client` is nullable: a chat opened before the service recorded it is unattributable,
+    and the service gives those to `kbc-ui`. So a filtered list starts from the deploy, not from the
+    project's first conversation.
+  - `POST /api/chat` accepts the same `client` on its body, which is what a host sets so its
+    conversations are attributed at all.
+
+  Regenerated from the deployed spec, so `getSpendCaps` / `updateSpendCaps` now carry
+  `defaultProjectCapPpu` in the generated schema too. Nothing changes for a caller — the method
+  already returned that field through a hand-written zod schema while the service rolled out, and the
+  fallback stays until every stack has the deploy.
+
+- Type the maintainer SAML SSO read responses (ST-4306).
+
+  `management/maintainers/types` exports `SamlConfigSummary` and `SamlConfigDetail`, derived from the
+  regenerated management schema. The two `GET /manage/maintainers/{maintainerId}/saml*` responses were
+  previously typed with every field optional and without `membershipRestriction`; the schema now marks
+  all of them required and the detail response also carries `permittedEmailDomains`, so callers no
+  longer have to guard fields the backend always sends. The list endpoint documents its 403.
+
+  The six client methods are unchanged — the two getters pick up the tightened return types on their
+  own.
+
+- `api.management.payAsYouGo` covers the pay-as-you-go billing endpoints — the credit price and tax
+  rates the checkout quotes, a project's credit purchases, its Stripe customer and saved cards, and
+  its automatic top-up configuration.
+
+  ```ts
+  const { "credit-price": creditPrice } =
+    await api.management.payAsYouGo.getBillingConfiguration();
+  const purchases =
+    await api.management.payAsYouGo.getCreditPurchases(idProject);
+  const { clientSecret } = await api.management.payAsYouGo.createPaymentRequest(
+    {
+      idProject,
+      amount: 100,
+      saveCard: true,
+    },
+  );
+  ```
+
+  Connection serves these off the same host as the Manage API but outside its `/manage` prefix, and
+  they accept a Manage token of type `admin` or `session`, so they run through the management client's
+  auth middleware like every other management method.
+  - Parameters carry the endpoint's own names: the project is `idProject` everywhere except
+    `getTopUpSetting`, whose path names it `projectId`.
+  - `getStripeCustomer` resolves `null` when the project has no Stripe customer yet — the endpoint
+    answers 204.
+  - `updateTopUpSetting` resolves `void`; the endpoint answers 202 with no body, so read the stored
+    configuration back with `getTopUpSetting`.
+  - `getTopUpSetting` throws a 404 `ApiError` when top-up was never configured for the project, which
+    is a product state rather than a failure.
+
+  Four response types are tightened past the manage OpenAPI document, which is looser than the
+  endpoints: `credit-price` and the three top-up fields and `clientSecret` are required rather than
+  optional, `stripeInvoiceStatus` and `invoiceTopUpType` are unions rather than bare strings, and
+  `moneyAmount` is nullable. They revert to plain generated types once connection's spec is corrected.
+
+  The maintainer SAML responses gained `membershipRestriction`, `getMaintainerSamlConfig` gained
+  `permittedEmailDomains`, and both configs' fields are no longer optional — the manage OpenAPI
+  document now marks them required.
+
+- New `canWriteSemanticLayer(token)` permission predicate — whether a project role may create, update
+  or delete semantic-layer objects in the metastore.
+
+  ```ts
+  if (canWriteSemanticLayer(api.context.project.sapiToken)) {
+    // offer the add / edit / delete affordances
+  }
+  ```
+
+  A denylist, unlike `canWriteKaiSettings`: the metastore's project-level ACL admits ordinary project
+  work, so only `readOnly` is refused. Organization-scope promotion stays a separate, narrower right
+  the metastore answers with a 403.
+
+- `api.telemetry` moves onto its own OpenAPI document, loses its one-method sub-namespace, and gains
+  the endpoint the embed dashboards need.
+
+  ```ts
+  const { token } = await api.telemetry.getProvisioningToken({
+    project_type: projectType,
+  });
+  ```
+
+  - **`getProvisioningToken`** returns the short-lived ES256 JWT a telemetry embed authenticates with.
+    Both response fields are optional in the spec, so check `token` before use.
+  - **`healthCheck`** joins the other service clients. The endpoint was only ever thought missing
+    because its path sits behind the ingress prefix described below.
+  - **`provisioning.createCredentials` is gone**, and with it the `provisioning` namespace, so the two
+    remaining methods sit directly on `api.telemetry`. It posted to an endpoint the service does not
+    route, document, or implement — the word `workspace` appears nowhere in
+    `keboola/gooddata-cn-provisioning`, and one ingress rule sends all of `/provisioning/*` to that
+    one backend, so there was nowhere else it could have landed. It answered 404 on every stack
+    probed and had no caller. `CreateCredentialsBody` and `WorkspaceData` go with it.
+
+  Types generate from the service's own `swagger.yaml`, newly registered in `redocly.yaml`. Its repo
+  is private and it does not serve the document over HTTP, so the spec is vendored beside the
+  generated schema — the same local-root arrangement `microsoftGraph` uses.
+
+  The client owns the `/provisioning` prefix rather than its callers: the service listens on its root,
+  and one ingress rule on the telemetry host routes that prefix to it. `baseUrl` stays the plain
+  telemetry service URL, and request paths stay the spec's own (`/token`, `/health`).
+
+  `project_type` is a free-form string passed straight into the JWT claim, not an enum — the service
+  validates it nowhere.
+
+- Expose organization membership on project users. The shared User type keeps the field optional for older stacks and endpoints that do not return project membership.
+
+### Patch Changes
+
+- A successful `text/html` response is only read as Connection's login screen when it actually carries
+  a body. Symfony's `Response::prepare()` stamps `Content-Type: text/html` on every bodyless response
+  but `204`/`304`, so a framework default was being reported to the user as an expired session.
+
+  `PUT /pay-as-you-go/billing/top-up` answers `202` with an empty body, and it is the middle call of
+  the kbc-ui Pay flow — so buying pay-as-you-go credits failed with "You will be logged out
+  automatically." for every user, on every auth strategy, and never reached Stripe. The same trap was
+  live on the invitation, join-request, password-reset and token-revoke endpoints.
+
+  Both validators are fixed, `validateManagementStatus` (`ManagementClientAuthError`) and
+  `validateConnectionStatus` (`HtmlResponseError`, used by the storage and auth clients), through a
+  new shared `isLoginPageRedirect` — `isHtmlResponse && !isContentEmpty`. `isHtmlResponse` keeps its
+  header-only meaning and `isContentEmpty` is new; calling the header check on its own is what read an
+  empty `202` as a login page. All three are workspace-internal, not part of the package's public
+  export surface.
+
+  Connection declares JSON on those responses in connection#8414; this is the client-side half
+  and holds regardless of what a service labels an empty body.
+
+- The semantic-layer SDK parses what it reads instead of asserting it, so an object that does not
+  match its declared shape is dropped rather than handed to a caller half-formed.
+
+  `listModels` and `listObjects` cast the metastore's response to the types in
+  `sdk/semanticLayer/types`. Those types declare `SemanticMetricData.name`, `.sql` and
+  `SemanticGlossaryData.term`, `.definition` as required strings, and every consumer is entitled to
+  call a method on them — the first one to do so (`.trim()`, in business-chat's openers) turns a
+  missing field into a `TypeError` thrown inside a render.
+  - Each element is validated against its object type's shape. One that fails is left out and the
+    reason logged — object type, UUID, and which field is wrong, never the payload, because a model's
+    vocabulary and its SQL are the customer's.
+  - A drop never takes its container with it, at either level: a model holding one malformed metric
+    still lists the other nine, and a dataset carrying one nameless field still lists its other
+    columns rather than disappearing from the model.
+  - A response that is not a collection still throws a `ValidationError` — reading it as an empty
+    list would say "this project has no metrics".
+  - Undeclared fields still reach callers untouched, exactly as they did under the cast.
+  - `SemanticObject.meta` stops lying: an envelope that omits it — or sends it as `null` — now
+    normalizes to `{}` rather than being typed as present and arriving `undefined`.
+  - An **optional** enum carrying a value outside the list (`role`, `severity`, `scope`, a
+    relationship's `type`) reads as absent instead of dropping its object — a new value the metastore
+    starts issuing must not delete the dataset carrying it. A required one (`constraintType`) has no
+    such reading.
+
+  **`listModelChildren` now throws `SemanticLayerUnreadableChildrenError` instead of degrading**, and
+  `deleteModel` inherits it. A list read degrades because a shorter list is still useful; this one
+  cannot, because it answers what a delete would destroy. A dropped child would otherwise be missing
+  from the cascade, leave `failedChildren` empty, and let the model be deleted — orphaning an object
+  whose `modelUUID` points at a model that no longer exists and that no list returns, so it can never
+  be found, fixed or deleted again. The throw happens before the first child delete, so a refusal
+  destroys nothing. An unreadable object is counted against the model its raw envelope names, and
+  against every model when the envelope cannot name one.
+
+  Writes are untouched: the metastore echoes back the object it has just validated and stored.
+
+  `formatValidationIssues` is now exported alongside `ValidationError`, for boundaries that degrade
+  instead of throwing and still owe a one-line reason.
+
+## 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