@keboola/api-client 39.0.0 → 40.0.0

package/AGENTS.md

@@ -17,8 +17,13 @@ pnpm type-check --filter=@keboola/api-client # tsc --noEmit
 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
+pnpm --filter @keboola/api-client gen:types:drift     # Which schemas no longer match their service
 ```
 
+`gen:types:drift` is what the weekly **api-client Weekly OpenAPI Drift** lane runs; it writes into
+the working tree to diff, so discard afterwards. See
+[`docs/regenerate-api-types.md`](./docs/regenerate-api-types.md).
+
 ## Getting a client
 
 **React (the common case).** In `apps/kbc-ui` and other React apps, use `useApiClient()` from [`@keboola/api-client-react`](../api-client-react/AGENTS.md) — it returns the flow-agnostic `api` (auth + management + product namespaces). At startup an auth provider (`LegacyAuthProvider` for SAPI, `AuthProvider` for bearer) drives the module-load singleton's `session` to ready and renders a fallback until then; `ApiClientProvider` propagates that `api` to the tree. Don't create a client per component.
@@ -34,7 +39,7 @@ const { data } = useQuery({
 **Scripts / CLIs / non-React.** Create one directly — pick the smallest that covers you:
 
 - **`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`.
+- **`createLegacyKeboola` / `createKeboola`** — full SDK across all stack services. `createLegacyKeboola` returns `{ api, session }` and `createKeboola` returns `{ session, getActiveApi, getApi }`; drive the `session` to ready, then use the product surface. 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.
 
@@ -61,10 +66,11 @@ const buckets = await api.storage.buckets.getBuckets();
 
 ## Lifecycle & auth (the stateful client)
 
-Two flow-specific factories back the SDK, and **both return `{ api, session }`**:
+Two flow-specific factories back the SDK:
 
-- `createKeboola(opts?)` — the **bearer (OAuth)** flow.
-- `createLegacyKeboola(opts?)` — the **legacy (SAPI-token)** flow.
+- `createKeboola({ defaultBaseUrl, … })` — the **bearer (OAuth)** flow. Returns `{ session, getActiveApi, getApi }`;
+  `getActiveApi()` is the scoped product surface, `getApi(projectId)` a pinned one (see below).
+- `createLegacyKeboola(opts?)` — the **legacy (SAPI-token)** flow. Returns `{ api, session }`.
 
 `api` is the same **flow-agnostic** product surface for both — a state-gating proxy:
 
@@ -73,13 +79,20 @@ Two flow-specific factories back the SDK, and **both return `{ api, session }`**
 - **`api.storage` / `api.queue` / `api.context` / `api.sdk` / …** — product namespaces, live only once
   the async storage build reaches `ready` (throw `KeboolaError` (`NotReady`) before that).
 
-`session` is **flow-specific** lifecycle machinery. Both share `setBaseUrl`, `isStorageReady()`,
-`subscribe(cb)` (fires on config **and** storage-build transitions), and `debug()`. Then:
-
-- bearer: `authenticate(token)` → `setProject(projectId)` / `setProjectAsync(projectId)` (awaits the
-  build) / `forProject(projectId)` (a second project alongside the first) / `reset()`.
-- legacy: `authenticateStorage(sapiToken)` / `authenticateStorageAsync(sapiToken)` (awaits the build),
-  `authenticateManagement(manageToken)`.
+`session` is **flow-specific** lifecycle machinery:
+
+- bearer: `stack.select(baseUrl)` → `auth.authenticate(credential)` → `project.select(projectId)`,
+  plus `auth.signOut()` / `auth.replace(credential)` / `auth.isAuthenticated()` / `auth.isAuthenticatedAsync()` / `auth.rotate(baseUrl)` / `auth.getHeaders(projectId?)`, `stack.close` and
+  the two `deactivate`s, and `getState()` / `subscribe(cb)` over the stack-and-project table. Every
+  verb is synchronous — nothing awaits a build; a namespace throws `NotReady` until its fetch lands.
+  The one fetch each entry does own is readable both ways: `stack.getContext(baseUrl?)` /
+  `project.getContext(entryId?)` answer from cache (`null` until it lands), and the
+  `getContextAsync` sibling of each awaits it. `retryContext` refetches after a failure. The
+  project trio keys by `${baseUrl}#${projectId}` — a row on any stack — where `getApi` and
+  `auth.getHeaders` take a bare project id and address the active stack.
+- legacy: `setBaseUrl`, `authenticateStorage(sapiToken)` / `authenticateStorageAsync(sapiToken)`
+  (awaits the build), `authenticateManagement(manageToken)`, `isStorageReady()`, `subscribe(cb)`
+  (fires on config **and** storage-build transitions) and `debug()`.
 
 ```ts
 // Legacy (SAPI token in hand): one step to ready
@@ -88,92 +101,86 @@ await session.authenticateStorageAsync(token);
 const buckets = await api.storage.buckets.getBuckets(defaultBranchId);
 
 // Bearer (OAuth) login flow (browser)
-const { api, session } = createKeboola({ baseUrl });
-await api.auth.login({ email, password }); // → carries the bearer token
-const projects = await api.auth.getProjects(); // introspect → picker
-await session.authenticate(bearerToken);
-await session.setProjectAsync(projects[0].id); // → ready
-session.setProject(otherId); // runtime re-scope (rebuilds against the new project)
-
-session.debug(); // { baseUrl, authReady, managementReady, storage, config }
+const { session, getActiveApi } = createKeboola({ defaultBaseUrl: baseUrl }); // `auth` is live now
+const result = await getActiveApi().auth.login.withPassword({ email, password });
+if (!result.mfaRequired) session.auth.authenticate({ type: 'token', ...result });
+session.project.select(projectId); // → the scope `getActiveApi()` addresses
 ```
 
 ### 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:
+One credential reaches every project on its stack — project scope is one header, `X-KBC-ProjectId` —
+so `getApi(projectId)` hands out a product surface per project, off the client 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 { session, getActiveApi, getApi } = createKeboola({ defaultBaseUrl: baseUrl });
+session.auth.authenticate(credential);
+session.project.select(42);
+
+const api = getActiveApi(); // the scoped project, 42
+const other = getApi(7); //     project 7, opened by the call
 
-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
+  api.storage.buckets.getBuckets({ branchId: 'default' }),
+  other.storage.buckets.getBuckets({ branchId: 'default' }),
 ]);
 ```
 
-`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.
+Both return the same `KeboolaApi`, and both are synchronous and lazy: the surface resolves per
+property read, so a namespace throws `KeboolaError` (`NotReady`) until that project's context fetch
+lands, exactly as the scoped one does.
+
+**The method is the lifetime, and that is the whole difference:**
+
+- **`getActiveApi()` follows the scope.** It re-points when `session.project.select` moves, so a
+  component holding it sees the new project. This is the handle an app is centred on, and what
+  `ApiClientProvider` propagates to `useApiClient()`.
+- **`getApi(7)` is pinned.** It never re-points, and it stops working when project 7 closes — by
+  `session.project.close(7)`, or by a sign-out, which closes every project on the stack. A handle
+  held across either throws `No project "…"` on its next read rather than quietly serving whoever
+  signed in after. Ask for a fresh one.
+
+Three things follow from that, worth knowing before you hold one:
+
+- **`getApi(7)` opens project 7**, which starts its context fetch and persists the row — so the
+  project comes back on reload, alongside the scoped one. **Close it when you are done with it**
+  (`session.project.close(7)`), or the set only grows and every reload re-fetches all of it. The
+  open is attempted, not required: asked for before the sign-in lands, the handle comes back
+  anyway and its reads throw until the row exists. It resolves against the **active stack at call
+  time** and pins the result; nothing follows a later `session.stack.select`.
+- **One credential, one refresh loop.** Every handle shares the stack's auth middleware, which reads
+  the credential live, so a rotation happens once and serves all of them. `auth` and `management`
+  answer for the stack the handle's project sits on, not for whatever stack is active.
+- **A project you cannot reach fails the request, not the session.** Connection answers a denied or
+  nonexistent project with the same `invalid_token` 401 as a revoked token — collapsed deliberately,
+  so scope cannot be probed. So a 401 is never read as expiry: the project's row goes `errored` and
+  the sign-in stands. **The refresh is the only oracle** — the server refusing the refresh token is
+  the one unambiguous report of a dead credential, and that is where the sign-out happens
+  (`rotateOnce` in `credentials.ts`). A cookie credential's refresh is the same oracle: the server
+  refusing its session signs it out. A static token cannot refresh, so it never signs itself out; a
+  401 on it surfaces to the caller.
+- **Memoised per project** — `getApi(7) === getApi(7)`, which is what React `key`s and hook deps
+  need. A sign-out drops everything built for that stack's projects, so a reopened project is built
+  from scratch rather than from what the previous sign-in left behind.
+
+`session.auth.getHeaders(projectId?)` takes the same optional argument, for a transport that is not
+a fetch client (the chat stream). Pass the project whose `api` produced the URL, so the request's
+headers and its target name the same project. A project id alone does not name a project — two
+stacks can each have a project 138 — so the active stack decides, falling back to a single project
+with that id open elsewhere.
+
+⚠️ **One client per stack, per page.** Two `createKeboola()` instances signed in to the same stack
+share its single-use refresh token: whichever rotates first invalidates the other's, and that one's
+next rotation is refused — which signs it out. Nothing in the SDK detects this (a client has no
+`dispose`, so a live sibling is indistinguishable from an abandoned one). `apps/kbc-ui` builds two
+bearer clients for its two strategies and stays correct only because just one of them ever holds a
+credential.
+
+⚠️ **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
@@ -185,21 +192,33 @@ and the session is in-memory (lost on reload); pass a storage adapter to make it
 ```ts
 import { createLocalStorage } from '@keboola/api-client';
 
-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 — and one
-// landing mid-restore wins: the restore resolves `empty` rather than signing the user back in.
-const result = await session.restore();
+// `defaultBaseUrl` is active from here on, until `resume()` or `stack.select` moves it.
+const { session } = createKeboola({ defaultBaseUrl, storage: createLocalStorage() });
+
+// The stored stack and project become active again; with nothing stored, the default stays.
+// Resolves `restored | empty | expired | unreachable` — `expired` means a stored credential was refused.
+const status = await session.resume();
 ```
 
-Every credential change (login, project switch, token rotation, sign-out) is written back — only the
-durable subset `{ baseUrl, projectId, refreshToken }`, never the access token or user identity. A
-single fixed key holds one bearer session, tagged with the stack (`baseUrl`) it belongs to. The
-configured stack is authoritative: `restore()` adopts the stored `baseUrl` only when you construct
-without one; if you pass a `baseUrl` that differs from the stored session's stack, that session is
-**discarded** (a stored refresh token is only ever sent to the stack that issued it, never another).
+Every credential change (login, project switch, token rotation, sign-out) is written back under one
+fixed key, and what it holds is the whole table rather than a single session: `current` — the scoped
+stack and project — plus a `stacks` array, each entry carrying its own credential and the projects
+open under it. Only the durable part of a credential is written: a token credential's rotating
+refresh token, a static one's token, and a cookie one's session id, which renews nothing without the
+HttpOnly session cookie the browser keeps. An access token or user identity is never written.
+
+**Token or cookie is picked at construction.** `createKeboola({ defaultBaseUrl, credentials: 'cookie' })` signs in with
+browser-mode logins (`login.withPassword({ …, browserMode: true })`) and renews through
+`token.refreshWithSession` — the refresh token never reaches JS. It only works from the stack's own
+origin, so localhost and previews stay on the default `'token'`. `authenticate` refuses the other
+rotating kind, and a restore ignores a stored one.
+
+**A stack is always active**, so `session.stack.getActive()` never returns `null` and the active
+stack cannot be closed. Call `resume()` once on startup: persistence starts only after it settles,
+and a second call returns the same promise. The caller wins over the stored session — once it
+has selected a stack or project, or signed in or out, the resume leaves the scope where it is, and a
+stack already signed in or out keeps that sign-in. Leaving a project is `project.deactivate()`; switching stacks
+keeps every other stack's credential.
 Adapters: `createLocalStorage` / `createSessionStorage` (browser, memory fallback on Node/SSR),
 `createMemoryStorage`, `createNullStorage`. In Node, supply your own adapter or default to memory.
 
@@ -484,7 +503,7 @@ Don't invent a shape for the second case. These specs are uneven and, where pres
 `apps-api.keboola.com` (the Developer Portal / `components.keboola.com` backend) authenticates with its
 **own Cognito pool**, issuing a token trio — `token` (id), `accessToken`, `refreshToken` — not a
 Connection storage token. `createKeboola`'s session cannot drive it: driving to ready runs
-`tokens.verify()` against Connection, and `setProjectAsync` is meaningless. So it is not registered in
+`tokens.verify()` against Connection, and `session.project.select` is meaningless. So it is not registered in
 `createServiceClients.ts` and never appears on the `api` proxy — `api.developerPortal` does not exist.
 
 Two layers, as everywhere else in this package:
@@ -594,6 +613,8 @@ If the resolved value is a `Job` — the request only _enqueues_ the work — th
 
 The suffix is the only thing at a call site that says "you are not done yet — poll this." Anything that returns a job needs a follow-up (`jobs.getJob`, `pollStorageJob`, a `jobPoller`), and a bare name is what makes a caller forget. Correspondingly, **don't** use `Async` on a method that resolves to the finished resource; every method here is `async` in the JavaScript sense, so the suffix would carry no information.
 
+This rule governs **service-client endpoint methods**, where every method is already async. On a `session` surface the suffix means the other thing — the promise-returning sibling of a genuinely _synchronous_ call, where it does carry information: `authenticateStorage` / `authenticateStorageAsync`, `stack.getContext` / `stack.getContextAsync`.
+
 ```ts
 const deleteBucketAsync = async (…): Promise<Job<'bucketDelete'>> => { … }; // enqueues
 const getBucket = async (…): Promise<BucketDetail> => { … }; //                done on resolve

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`.
 
-26 top-level namespaces, 645 methods. This index lists method **names** only — full signatures live per namespace under [`surface/`](./surface). Open `surface/<namespace>.md` for the one you need.
+26 top-level namespaces, 666 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)
 
@@ -56,6 +56,9 @@ Every namespace and method reachable from a ready `KeboolaApi` — the `api` hal
 - `login.methods`
 - `login.withOidc`
 - `login.withPassword`
+- `manageTokens.create`
+- `manageTokens.getAll`
+- `manageTokens.revoke`
 - `mfa.regenerateRecoveryCodes`
 - `mfa.totp.disable`
 - `mfa.totp.setup`
@@ -78,7 +81,8 @@ Every namespace and method reachable from a ready `KeboolaApi` — the `api` hal
 - `sudo.challenge`
 - `sudo.verify`
 - `token.introspect`
-- `token.refresh`
+- `token.refreshWithSession`
+- `token.refreshWithToken`
 - `token.revoke`
 - `webauthn.getAll`
 - `webauthn.register`
@@ -216,11 +220,16 @@ Every namespace and method reachable from a ready `KeboolaApi` — the `api` hal
 - `submitToolOutput`
 - `submitVote`
 - `updateAgentSettings`
+- `updateProjectToolPolicy`
 - `updateSpendCaps`
 - `updateUserAgentSettings`
 
 ## [`api.management`](./surface/management.md)
 
+- `applicationTokens.createApplicationToken`
+- `applicationTokens.deleteApplicationToken`
+- `applicationTokens.getApplicationTokenScopes`
+- `applicationTokens.getApplicationTokens`
 - `currentUser.acceptMaintainerInvitation`
 - `currentUser.acceptOrganizationInvitation`
 - `currentUser.acceptProjectInvitation`
@@ -353,8 +362,10 @@ Every namespace and method reachable from a ready `KeboolaApi` — the `api` hal
 - `storageBackends.updateStorageBackend`
 - `uiApps.activateUiAppVersion`
 - `uiApps.deleteUiApp`
+- `uiApps.getUiApp`
 - `uiApps.getUiApps`
 - `uiApps.registerUiApp`
+- `uiApps.renameUiApp`
 - `users.addUserAdminFeature`
 - `users.deleteUser`
 - `users.deleteUserMetadata`
@@ -451,6 +462,13 @@ Every namespace and method reachable from a ready `KeboolaApi` — the `api` hal
 - `configuration.createConfiguration`
 - `configuration.getConfiguration`
 - `configuration.updateConfiguration`
+- `kaiMemory.createItem`
+- `kaiMemory.deleteUnreadableItem`
+- `kaiMemory.getItems`
+- `kaiMemory.getItemsByStatus`
+- `kaiMemory.getItemsByStatusStrict`
+- `kaiMemory.getUnreadableItemIds`
+- `kaiMemory.updateStatus`
 - `semanticLayer.createModel`
 - `semanticLayer.createModelTree`
 - `semanticLayer.createObject`
@@ -709,11 +727,14 @@ Every namespace and method reachable from a ready `KeboolaApi` — the `api` hal
 - `dbt.compile`
 - `dbt.runResults`
 - `enrollMFA`
+- `flowMigration.preview`
+- `flowMigration.validate`
 - `git.getBranches`
 - `git.getEntrypoints`
 - `healthCheck`
 - `looker.testCredentials`
 - `sendSyncAction`
+- `sshKeys.generate`
 
 ## [`api.telemetry`](./surface/telemetry.md)
 

package/CHANGELOG.md

@@ -1,5 +1,125 @@
 # @keboola/api-client
 
+## 40.0.0
+
+### Major Changes
+
+- Cookie (browser-mode) credentials on the bearer client.
+  - `createKeboola({ credentials: 'cookie' })` renews its credential through `auth.token.refreshWithSession`. The refresh token stays server-side, bound to the session cookie. A refused session signs the stack out, the same way a refused refresh token does. The default stays `'token'`.
+  - **Breaking:** a `cookie` credential carries `sessionId`, and `session.auth.authenticate` requires it.
+  - `authenticate` refuses a rotating credential of the kind the client was not built for, with `KeboolaErrorType.CredentialKindMismatch`. A restore reads a stored one of that kind as nothing stored.
+  - A cookie credential persists its session id, so a reload restores it through the session cookie.
+  - `CredentialMode` is exported.
+
+- Remove `removeBranchFromUrl` from `@keboola/api-client/sdk/storage`
+
+  It stripped the `/branch/{id}/` segment from a project URL. Project URLs now always name a branch — production is the default branch, not the absence of one — so a URL with the segment removed is not a production URL, it is an old link that gets rewritten back on arrival. Its last caller is gone.
+
+  Replace a call with the branch you actually want: build the URL at the default branch id rather than stripping the segment.
+
+- Browser/cookie mode on the auth client.
+  - `auth.login.withPassword` / `withOidc` take `browserMode` (default `false`), which also mints a browser session cookie for the issued session. The backend requires an `Origin` matching the stack app URL for it. The result type follows the flag: browser mode carries no `refreshToken`, API mode guarantees one.
+  - **Breaking:** `auth.token.refresh` is replaced by `refreshWithToken({ refreshToken })` (API mode) and `refreshWithSession({ sessionId })` (browser mode, sending `X-KBC-CSRF`).
+  - **Breaking:** the bearer credential kinds are renamed for what renews them — `browser` → `token`, `mediated` → `cookie`. A session stored under the old names is not read, so it signs in again.
+  - **Breaking:** `LoginSuccess` / `LoginResult` / `loginSuccessSchema` / `loginResultSchema` are replaced by `Api*` and `Browser*` pairs; `loginInputSchema` is no longer exported (use `passwordInputSchema`).
+  - **Breaking:** `saml.assert` takes the regenerated body, which now carries `browserMode`.
+
+- replace MANAGE_TOKEN_SCOPES with management.applicationTokens.getApplicationTokenScopes
+
+  The constant mirrored the stack's scope list by hand and had to be edited in lockstep with the
+  backend; the Manage API now publishes the list, so the copy is gone.
+
+- The bearer client always has an active stack, and restores only when asked.
+  - `createKeboola({ defaultBaseUrl })` is required. That stack is active from construction until `session.resume()` or `stack.select` moves it; `baseUrl` is gone.
+  - `session.stack.getActive()` returns `Stack`, never `null`. `stack.close` refuses the active stack (`KeboolaErrorType.StackActive`); `stack.deactivate()` is removed.
+  - `session.restored` is replaced by `session.resume()`, called once on startup and resolving with the same `RestoreStatus`. It rebuilds the stored stacks, credentials and projects and makes the stored stack and project active again; with nothing stored, or on a failed restore, the default stays active. A caller that selected a stack or project, or signed in or out, first keeps its scope, and a stack it signed in or out of keeps that sign-in. Persistence starts only after it settles.
+  - `session.auth.isAuthenticated()` reports whether the active stack holds a credential; `isAuthenticatedAsync()` answers once the stored session has resumed.
+  - `session.auth.replace(credential)` signs the active stack out and in with `credential`, winning over a restore still in flight.
+  - `session.auth.adoptInjected(credential)` (deprecated on arrival) adopts a server-injected `token` credential even in cookie mode. Temporary, for the agent-project claim page, until Connection stops injecting `UiConfig.programmaticAuth`.
+  - `createLegacyKeboola` keeps `baseUrl` (`LegacyKeboolaOptions`).
+
+- rework management.uiApps around the application's `stringId`
+  - **New:** `getUiApp(stringId)` returns the application with every registered version.
+  - **New:** `renameUiApp({ stringId, name })`.
+  - **New:** `getUiApps({ includeInactive })` also lists applications with no active version.
+  - **Breaking:** `activateUiAppVersion` and `deleteUiApp` take the `stringId` instead of `id`.
+  - **Breaking:** `UiApp` carries `stringId`, and its version fields are nullable; `ActivateUiAppVersionPath` is no longer exported.
+
+- Rebuild the bearer (OAuth) flow around a session-state table addressed by stack and project.
+  - **`createKeboola` is the factory's only public name.** The `createSessionClient` alias and the `SessionClient` type are gone — import `createKeboola`, and type a session as `BearerSession`.
+  - **It returns `{ session, getActiveApi, getApi }`, not `{ api, session }`.** `getActiveApi()` follows `session.project.select`; `getApi(projectId)` opens that project and stays pinned to it, so one signed-in client reaches several projects at once. Close a pinned project with `session.project.close(projectId)`.
+  - **The bearer `session` is regrouped** into `stack.*`, `project.*` and `auth.*`, plus `getState()` / `subscribe()` over the stack-and-project table and a `restored` promise resolving `RestoreStatus` (`'restored' | 'expired' | 'unreachable' | 'empty'`, where `expired` means the server refused the refresh token and `unreachable` means the exchange never got an answer — retry, never a login). Every verb is synchronous — a product namespace throws `NotReady` until that entry's context fetch lands, and `stack.getContextAsync` / `project.getContextAsync` await it.
+
+    | Was                              | Now                                        |
+    | -------------------------------- | ------------------------------------------ |
+    | `setBaseUrl(url)`                | `stack.select(url)`                        |
+    | `authenticate(tokens)`           | `auth.authenticate(credential)`            |
+    | `setProject(id)`                 | `project.select(id)`                       |
+    | `clearProject()`                 | `project.deactivate()`                     |
+    | `reset()`                        | `auth.signOut()`                           |
+    | `getAuthHeaders(projectId?)`     | `auth.getHeaders(projectId?)`              |
+    | `api` (the scoped surface)       | `getActiveApi()`                           |
+    | `forProject(id)`                 | `getApi(id)`                               |
+    | `restore()`                      | the `restored` promise                     |
+    | `subscribe(cb)` (debug snapshot) | `subscribe(cb)` + `getState()` (the table) |
+
+    Removed with no replacement: `setProjectAsync`, `isStorageReady`, `hasPersistedValue`, `debug`, `debugForceRefresh`.
+
+  - **`baseUrl` is now the stack to start on, not the stack to talk to.** The bearer factory scopes it once `restored` settles, and only if the restore scoped nothing — so a stored session keeps its own stack. Any stack still enters the table through `session.stack.select(baseUrl)`.
+  - **The bearer engine no longer carries the legacy SAPI flow.** Use `createLegacyKeboola` for SAPI tokens.
+  - New type exports: `RestoreStatus`, `SessionState`, `AuthPhase`, `FetchStatus`, `ActiveLocation`, `StackEntry`, `ProjectEntry`, `BearerCredentialEntry`.
+
+### Minor Changes
+
+- Project-level Kai tool policy: `kaiAgent.updateProjectToolPolicy`, `toolPermissions`/`canWriteToolPolicy` on agent settings and `projectToolPermissions` on user agent settings; org-admin Tool permissions card in Project Settings.
+
+- AI-3943: `kaiAgent.getUsage` exposes the organization's one-time free Kai allowance (`freeAllowance.grantedPpu`/`remainingPpu`); kbc-ui shows a one-time dismissible info notice in the Kai chat surfaces until dismissed or spent.
+
+- Deprecate `createModelTree` in the semantic layer SDK (`@keboola/api-client/sdk/semanticLayer`); it is removed in the next major
+
+  It creates a model, then its children, one request each, and rejects on the first failed child, leaving behind whatever it had already written. Nothing in this repository calls it.
+
+  Create the model with `createModel`, then its children with `createObject` or `createObjects`. To delete a model that failed partway through, use `deleteModel`.
+
+- `api.syncActions.flowMigration.validate` and `.preview` run `keboola.flow-migration-tool`'s sync
+  actions for a list of orchestrations and return one parsed result per orchestration. `preview` is a
+  dry run: its results carry the status (`dry-run`, `skipped` or `failed`), the structural changes,
+  and the flow configuration the orchestration would become.
+
+- `api.syncActions.sshKeys.generate` generates an SSH key pair via `keboola.ssh-keygen-v2` and
+  returns its `public` and `private` keys.
+
+- Deleted project detail exposes storage backend `backends` (like project detail) so the UI can show the backend ID as a link to `/control/storage-backends/<id>`; control-ui renders ID + type badge, gated by `canReadStorageBackends`.
+
+- Support per-chat model tier selection and optional Fast preparation context. Chat detail responses include requested and effective tier labels plus the fixed effort. Existing callers may omit the additive request fields.
+
+- Adds the `kaiMemory` SDK (`api.sdk.kaiMemory`) over the metastore client for Kai's org-wide knowledge-base notes, and a `canManageKaiMemory` permission predicate.
+
+- add management.applicationTokens service, including the stack-published scope list
+
+- `createManagementClient` takes `mintSessionToken` on a `management-token` auth strategy.
+  - The client authenticates every call with a session token minted from `token` (`POST /manage/current-user/session-token`), not with `token` itself.
+  - When that session token expires, the next one is minted from `token` again.
+  - Without `mintSessionToken`, an invalid token is replaced from the browser's login session (`POST /admin/account/session-token`) in every environment.
+
+### Patch Changes
+
+- `canWriteSemanticLayer` now mirrors the metastore's role rule: only the `admin` and `productionManager` project roles may write the semantic layer, and the metastore answers every other role (and a limited token) with a 403. kbc-ui's semantic-layer editor stops offering write actions to those callers, and Kai hides its semantic-layer write tools from them. Tool Permissions lists those tools for every caller, a project block hides them from Kai, and Kai reports a metastore 403 in the metastore's own words (AI-3742).
+
+- Messages the UI sends on its own (data-app preview error forwards, job-finished nudges) are tagged `autoForwarded` and no longer count toward the monthly Kai message limit; the burst limiter still counts them. kai-agent honors the flag only when the text matches one of the UI's fixed auto-forward templates and strips it otherwise (AI-3887)
+
+- Accept an optional `AbortSignal` in `chat.getHistory` and `kaiAgent.getHistory`, matching the other read methods on both clients. Callers that cancel a query now abort the request it started.
+
+- Add `auth.manageTokens` — list, create and revoke Manage API tokens. The list keeps hand-made tokens and session tokens in separate arrays, and creating one needs an active sudo window.
+
+- Add the optional `continueOnFailure` boolean to the `keboola.ex-google-ads` configuration schema, alongside the existing `onlyEnabledCustomers` flag.
+
+- The generated Manage API types match the live document.
+  - A deleted project's `backends` entries are `{ id }`, the only field the endpoint returns for each backend.
+  - The schema carries `PATCH` and `DELETE /manage/file-storage/{fileStorageId}`.
+
+- Accept an optional `query` filter on `metastore.repository.getMetaObjects` and `getMetaObjectRevisions` (AI-3975). The metastore already filters these list endpoints server-side on any object field (`{ status: 'pending' }`, `{ 'field[in]': 'a|b' }`, ...) — the SDK just wasn't forwarding it. Callers no longer have to page every object of a type and filter client-side.
+
 ## 39.0.0
 
 ### Minor Changes

package/README.md

@@ -78,9 +78,9 @@ Interactive login, then scope to a project:
 ```typescript
 import { createKeboola } from '@keboola/api-client';
 
-const { api, session } = createKeboola({ baseUrl });
+const { api, session } = createKeboola({ defaultBaseUrl: baseUrl });
 
-// api.auth is live as soon as baseUrl is configured
+// api.auth is live from construction: a stack is always active
 const result = await api.auth.login.withPassword({ email, password });
 if (result.mfaRequired) {
   // result is an MFA challenge — verify via api.auth.mfa.* to obtain the LoginSuccess
@@ -103,7 +103,7 @@ credential, hand a `LoginSuccess`-shaped object straight to `session.authenticat
 ```typescript
 import { createKeboola } from '@keboola/api-client';
 
-const { api, session } = createKeboola({ baseUrl: process.env.KEBOOLA_STACK_URL! });
+const { api, session } = createKeboola({ defaultBaseUrl: process.env.KEBOOLA_STACK_URL! });
 
 session.authenticate({
   mfaRequired: false,

package/dist/{ManagementClientAuthError-FcfMJNhr.cjs → ManagementClientAuthError-DE7lNGZQ.cjs}

@@ -1,4 +1,4 @@
-const require_createFetchClient = require("./createFetchClient-BlgPbjFj.cjs");
+const require_createFetchClient = require("./createFetchClient-Cwp8max9.cjs");
 //#region src/errors/ManagementClientAuthError.ts
 var ManagementClientAuthError = class extends require_createFetchClient.ApiError {
 	title;
@@ -18,4 +18,4 @@ Object.defineProperty(exports, "ManagementClientAuthError", {
 	}
 });
 
-//# sourceMappingURL=ManagementClientAuthError-FcfMJNhr.cjs.map
+//# sourceMappingURL=ManagementClientAuthError-DE7lNGZQ.cjs.map

package/dist/{ManagementClientAuthError-FcfMJNhr.cjs.map → ManagementClientAuthError-DE7lNGZQ.cjs.map}

@@ -1 +1 @@
-{"version":3,"file":"ManagementClientAuthError-FcfMJNhr.cjs","names":["ApiError"],"sources":["../src/errors/ManagementClientAuthError.ts"],"sourcesContent":["import type { ApiResponse } from '../fetchClient/createFetchClient/types';\n\nimport { ApiError } from './ApiError';\n\nexport class ManagementClientAuthError extends ApiError {\n  title: string;\n  message: string;\n  constructor(title: string, message: string, res: ApiResponse) {\n    super(res);\n    this.name = 'ManagementClientAuthError';\n    this.title = title;\n    this.message = message;\n  }\n}\n"],"mappings":";;AAIA,IAAa,4BAAb,cAA+CA,0BAAAA,SAAS;CACtD;CACA;CACA,YAAY,OAAe,SAAiB,KAAkB;EAC5D,MAAM,GAAG;EACT,KAAK,OAAO;EACZ,KAAK,QAAQ;EACb,KAAK,UAAU;CACjB;AACF"}
+{"version":3,"file":"ManagementClientAuthError-DE7lNGZQ.cjs","names":["ApiError"],"sources":["../src/errors/ManagementClientAuthError.ts"],"sourcesContent":["import type { ApiResponse } from '../fetchClient/createFetchClient/types';\n\nimport { ApiError } from './ApiError';\n\nexport class ManagementClientAuthError extends ApiError {\n  title: string;\n  message: string;\n  constructor(title: string, message: string, res: ApiResponse) {\n    super(res);\n    this.name = 'ManagementClientAuthError';\n    this.title = title;\n    this.message = message;\n  }\n}\n"],"mappings":";;AAIA,IAAa,4BAAb,cAA+CA,0BAAAA,SAAS;CACtD;CACA;CACA,YAAY,OAAe,SAAiB,KAAkB;EAC5D,MAAM,GAAG;EACT,KAAK,OAAO;EACZ,KAAK,QAAQ;EACb,KAAK,UAAU;CACjB;AACF"}

package/dist/{ManagementClientAuthError-Cr9IOsnJ.js → ManagementClientAuthError-H30lti_Q.js}

@@ -1,4 +1,4 @@
-import { g as ApiError } from "./createFetchClient-C-cadpBx.js";
+import { g as ApiError } from "./createFetchClient-DXHQK63w.js";
 //#region src/errors/ManagementClientAuthError.ts
 var ManagementClientAuthError = class extends ApiError {
 	title;
@@ -13,4 +13,4 @@ var ManagementClientAuthError = class extends ApiError {
 //#endregion
 export { ManagementClientAuthError as t };
 
-//# sourceMappingURL=ManagementClientAuthError-Cr9IOsnJ.js.map
+//# sourceMappingURL=ManagementClientAuthError-H30lti_Q.js.map

package/dist/{ManagementClientAuthError-Cr9IOsnJ.js.map → ManagementClientAuthError-H30lti_Q.js.map}

@@ -1 +1 @@
-{"version":3,"file":"ManagementClientAuthError-Cr9IOsnJ.js","names":[],"sources":["../src/errors/ManagementClientAuthError.ts"],"sourcesContent":["import type { ApiResponse } from '../fetchClient/createFetchClient/types';\n\nimport { ApiError } from './ApiError';\n\nexport class ManagementClientAuthError extends ApiError {\n  title: string;\n  message: string;\n  constructor(title: string, message: string, res: ApiResponse) {\n    super(res);\n    this.name = 'ManagementClientAuthError';\n    this.title = title;\n    this.message = message;\n  }\n}\n"],"mappings":";;AAIA,IAAa,4BAAb,cAA+C,SAAS;CACtD;CACA;CACA,YAAY,OAAe,SAAiB,KAAkB;EAC5D,MAAM,GAAG;EACT,KAAK,OAAO;EACZ,KAAK,QAAQ;EACb,KAAK,UAAU;CACjB;AACF"}
+{"version":3,"file":"ManagementClientAuthError-H30lti_Q.js","names":[],"sources":["../src/errors/ManagementClientAuthError.ts"],"sourcesContent":["import type { ApiResponse } from '../fetchClient/createFetchClient/types';\n\nimport { ApiError } from './ApiError';\n\nexport class ManagementClientAuthError extends ApiError {\n  title: string;\n  message: string;\n  constructor(title: string, message: string, res: ApiResponse) {\n    super(res);\n    this.name = 'ManagementClientAuthError';\n    this.title = title;\n    this.message = message;\n  }\n}\n"],"mappings":";;AAIA,IAAa,4BAAb,cAA+C,SAAS;CACtD;CACA;CACA,YAAY,OAAe,SAAiB,KAAkB;EAC5D,MAAM,GAAG;EACT,KAAK,OAAO;EACZ,KAAK,QAAQ;EACb,KAAK,UAAU;CACjB;AACF"}