@keboola/api-client 56.0.0 → 57.0.0

package/AGENTS.md

@@ -26,9 +26,15 @@ the working tree to diff, so discard afterwards. See
 
 ## Getting a client
 
-**React (the common case).** In `apps/kbc-ui` and other React apps, use the hooks from [`@keboola/api-client-react`](../api-client-react/AGENTS.md): `useProjectApi()` for one project's `ProjectApi` (auth + management + product namespaces), `useStackApi()` for the `StackApi` that is there before a project (sign-in, the account, the project list). `StackApiProvider` and `ProjectApiProvider` propagate them; a `ProjectApiProvider` provides its stack too. Don't create a client per component.
+| You hold                                                             | Use                                                                  |
+| -------------------------------------------------------------------- | -------------------------------------------------------------------- |
+| A React tree                                                         | `useProjectApi()` / `useStackApi()` from `@keboola/api-client-react` |
+| A bearer sign-in (browser or Node)                                   | `createKeboola` — [The bearer client](#the-bearer-client)            |
+| A Storage API token                                                  | `createStorageClient`, plus the per-service clients you call         |
+| A vendor API (`microsoftGraph`) or a public one (`assets`, `status`) | its factory from the sub-path                                        |
 
 ```ts
+// React: one project's api, provided by `ProjectApiProvider`
 const api = useProjectApi();
 const { data } = useQuery({
   queryKey: storageApiKey.getTable(id),
@@ -36,225 +42,108 @@ 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 `ProjectApiProvider` + `useProjectApi()` — see above; this section is about the non-React/single-service case.)
-- **`createLegacyKeboola` / `createKeboola`** — full SDK across all stack services. `createLegacyKeboola` returns `{ api, session }` and `createKeboola` returns `{ session, getStackApi, getProjectApi }`; drive the `session` to ready, then use the product surface. Bootstrap (`getStackInfo`, to discover services against the actual stack) runs while the storage build resolves, after which `api.stack` is synchronous. The verified token and the dev branches are the consumer's to fetch (`api.storage.tokens.verify()`, `api.storage.branches.getDevBranches()`) and derive with `createProject` / `createBranchRefs` — kbc-ui holds them in TanStack queries (`useProject` reads the token). 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
+// A Storage API token: Storage, plus any other service with its URL from the stack index
+import { createOauthClient } from '@keboola/api-client/oauth';
 import { createStorageClient } from '@keboola/api-client/storage';
 
-const storage = createStorageClient({
-  baseUrl: process.env.KEBOOLA_STACK_URL!, // canonical form, no trailing slash
-  auth: { type: 'sapi-token', token: process.env.KEBOOLA_STORAGE_TOKEN! },
-});
-const tables = await storage.tables.getTables();
-```
-
-```ts
-// Full SDK across all services — drive the session to ready, then use `api`
-import { createLegacyKeboola } from '@keboola/api-client';
-
-const { api, session } = createLegacyKeboola({ baseUrl: process.env.KEBOOLA_STACK_URL! });
-await session.authenticateStorageAsync(process.env.KEBOOLA_STORAGE_TOKEN!);
-const stack = api.stack; // synchronous — the storage build has resolved
-const buckets = await api.storage.buckets.getBuckets();
+const auth = { type: 'sapi-token', token: process.env.KEBOOLA_STORAGE_TOKEN! } as const;
+const storage = createStorageClient({ baseUrl: process.env.KEBOOLA_STACK_URL!, auth });
+const { services } = await storage.getStackInfo({ exclude: 'componentDetails' });
+const oauthUrl = services.find((service) => service.id === 'oauth')?.url;
+const oauth = oauthUrl ? createOauthClient({ baseUrl: oauthUrl, auth, middlewares: [] }) : null;
 ```
 
-## Lifecycle & auth (the stateful client)
-
-Two flow-specific factories back the SDK:
-
-- `createKeboola({ defaultBaseUrl, … })` — the **bearer (OAuth)** flow. Returns
-  `{ session, getStackApi, getProjectApi }`; `getStackApi()` is the active stack's surface,
-  `getProjectApi(projectId)` one project's (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:
-
-- **`api.auth.*`** — auth-service client, live once a `baseUrl` is configured.
-- **`api.management.*`** — management client, live once the management realm authenticates.
-- **`api.storage` / `api.queue` / `api.stack` / `api.sdk` / …** — product namespaces. Under the
-  legacy flow, live once the async storage build reaches `ready`; under bearer, `api.storage` is live
-  from the sign-in on and the rest once the stack index lands (throw `KeboolaError` (`NotReady`)
-  before that).
-
-`session` is **flow-specific** lifecycle machinery:
-
-- bearer: `stack.select(baseUrl)` → `auth.authenticate(credential)`, plus
-  `auth.signOut({ baseUrl?, retain? }?)` / `auth.replace(credential)` / `auth.isAuthenticated()` /
-  `auth.isAuthenticatedAsync()` / `auth.getHeadersAsync(projectId)` /
-  `auth.restoreRetained(baseUrl)`, and `getState()` / `subscribe(cb)` over the stack table. Every verb changes the table synchronously —
-  nothing awaits a build; `api.stack` throws `NotReady` until the stack index lands.
-  `stack.select` and `auth.signOut` also return a promise that resolves once the change is stored:
-  await it before leaving the document, or the reload boots from the stack or sign-in it was meant
-  to replace.
-  That one fetch is readable both ways: `stack.getContext(baseUrl?)` answers from cache (`null`
-  until it lands), and `stack.getContextAsync` awaits it, fetching again after a failure.
-  **The table knows no project.** `active` is a stack's `baseUrl`; which project the app is in is
-  the app's to keep (kbc-ui: the URL's `:projectId`), and it names it to `getProjectApi`.
-- legacy: `setBaseUrl`, `authenticateStorage(sapiToken)` / `authenticateStorageAsync(sapiToken)`
-  (awaits the build), `authenticateManagement(manageToken)`, `isStorageReady()`, `subscribe(cb)`
-  (fires on config **and** storage-build transitions) and `debug()`.
+There is no full `api` for a token; `apps/kbc-ui-oauth-external/src/api.ts` is the worked example.
 
-```ts
-// Legacy (SAPI token in hand): one step to ready
-const { api, session } = createLegacyKeboola({ baseUrl });
-await session.authenticateStorageAsync(token);
-const buckets = await api.storage.buckets.getBuckets(defaultBranchId);
-
-// Bearer (OAuth) login flow (browser)
-// `auth` is live from here on
-const { session, getStackApi, getProjectApi } = createKeboola({ defaultBaseUrl: baseUrl });
-const result = await getStackApi().auth.login.withPassword({ email, password });
-if (!result.mfaRequired) session.auth.authenticate({ type: 'token', ...result });
-const api = getProjectApi(projectId); // → every product namespace, for the project the app is in
-```
+A vendor client in `clients/` (`microsoftGraph`):
 
-### Several projects at once (bearer)
+- is **never** registered in `createServiceClients.ts`, so it never appears on `api.*`;
+- defaults its own `baseUrl` — the vendor's host is part of its contract;
+- carries no `healthCheck` — we don't own its liveness.
 
-One credential reaches every project on its stack — project scope is one header, `X-KBC-ProjectId` —
-so `getProjectApi(projectId)` hands out a product surface per project, off the client already in
-hand:
+## The bearer client
 
 ```ts
-const { session, getProjectApi } = createKeboola({ defaultBaseUrl: baseUrl });
-session.auth.authenticate(credential);
-
-const api = getProjectApi(42);
-const other = getProjectApi(7);
+const { session, stackApi, projectApi } = createKeboola({ defaultBaseUrl: baseUrl });
+const result = await stackApi.auth.login.withPassword({ email, password });
+if (!result.mfaRequired) session.auth.authenticate({ type: 'token', ...result });
 
-const [mine, theirs] = await Promise.all([
-  api.storage.buckets.getBuckets({ branchId: 'default' }),
-  other.storage.buckets.getBuckets({ branchId: 'default' }),
-]);
+const api = projectApi(projectId);
+const buckets = await api.storage.buckets.getBuckets({ branchId: 'default' });
 ```
 
-Both are synchronous and lazy: the surface resolves per property read, so `stack` throws
-`KeboolaError` (`NotReady`) until the stack index lands.
-
-**Two handles, two lifetimes:**
-
-- **`getStackApi()` is the active stack's `StackApi`.** `auth`, `management`, `baseUrl` and `stack`
-  follow `session.stack.select`; it has no project namespace. It is what an app uses before there is
-  a project — sign-in, the project picker.
-- **`getProjectApi(7)` is one project's `ProjectApi`, pinned.** It never re-points, and it lives as
-  long as the sign-in it was built under. A handle held across a sign-out throws on its next read
-  rather than quietly serving whoever signed in after. Ask for a fresh one.
-
-Worth knowing before you hold one:
-
-- **`getProjectApi(7)` holds no state.** Nothing is written to the table or persisted, so there is
-  nothing to close; the app keeps which project it is in. Asked for before the sign-in lands, the
-  handle comes back anyway and its reads throw `NotAuthenticated` until one does. 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 request fails 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. `onExpired` on `createKeboola` reports that sign-out, once per
-  sign-in and never for one the caller made, so an app can leave the document.
-- **Memoised per project** — `getProjectApi(7) === getProjectApi(7)`, which is what React `key`s and
-  hook deps need. A sign-out drops everything built for that stack's projects, so the next sign-in's
-  handle is built from scratch rather than from what the previous sign-in left behind.
-- **A project's token is not on the handle.** `api.storage.tokens.verify()` answers for the project
-  the handle names; derive the features with `createProject` and keep it where the app keeps state.
-
-`session.auth.getHeadersAsync(projectId)` takes the same 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 it resolves on the active stack, as `getProjectApi` does.
-It renews the token first once it nears expiry, for a transport that can run after the fetch
-traffic has gone quiet.
-
-⚠️ **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, `useStackApi()` and `useProjectApi()` read what `StackApiProvider` and
-`ProjectApiProvider` provide; `LegacyAuthProvider` drives a SAPI session to ready and gates on a
-`fallback`. See [`@keboola/api-client-react`](../api-client-react/AGENTS.md).
-
-**Persisting the bearer session.** `createKeboola` accepts a `storage` adapter (bearer only). Omit it
-and the session is in-memory (lost on reload); pass a storage adapter to make it durable:
+- **`stackApi`** — the active stack: `auth`, `management`, `baseUrl`, `stack`. It follows
+  `session.stack.select`; it is what an app uses before there is a project.
+- **`projectApi(projectId)`** — one project on the active stack, with every namespace.
+  - Memoised: `projectApi(7) === projectApi(7)`.
+  - Pinned to the stack and the sign-in it was built under; after a sign-out it throws — ask for a
+    fresh one.
+  - One credential reaches every project on its stack, so several projects are several handles on
+    one client.
+- **Namespaces are lazy.** `auth` works from the start; the rest need a sign-in (`NotAuthenticated`
+  before one). `api.stack` is `NotReady` until the stack index lands. A call to a service the stack
+  does not run rejects with `ServiceUnavailableError`.
+- **The project's token is the caller's to fetch** — `api.storage.tokens.verify()`, derived with
+  `createProject`; dev branches likewise, with `createBranchRefs`.
+- **`api.baseUrl`, not `api.stack.host`,** is the URL requests go to.
+
+### The session
+
+- `stack.select(baseUrl)`, `auth.authenticate` / `replace` / `signOut({ baseUrl?, retain? })` /
+  `restoreRetained(baseUrl)` / `isAuthenticated` / `isAuthenticatedAsync`, and `getState()` /
+  `subscribe(cb)` over the stack table.
+- Every verb changes the table at once; `stack.select` and `auth.signOut` also resolve once the
+  change is stored — await them before leaving the document. `signOut` also waits, bounded, for the
+  server session to end.
+- The table knows no project: the app keeps which one it is in and names it to `projectApi`.
+- `stack.getContext(baseUrl?)` reads the stack index from cache (`null` until it lands);
+  `stack.getContextAsync` awaits it.
+- `auth.getHeadersAsync(projectId)` is for a transport that is not a fetch client (the chat
+  stream); it renews a token near expiry first.
+
+### Expiry
+
+- A 401 fails the request, never the session: Connection answers an unreachable project with the
+  same 401 as a revoked token.
+- A refused refresh is the one sign of a dead credential. It signs the stack out, and `onExpired`
+  reports it once per sign-in.
+- `onExpired` also fires when a rotation finds the stack signed out in storage: another tab signed
+  out.
+
+⚠️ **One client per stack, per page.** Two `createKeboola()` clients signed in to one stack share a
+single-use refresh token, and the first rotation signs the other out. A second project is
+`projectApi(id)` on the same client, never a second client.
+
+### Persisting the session
 
 ```ts
-import { createLocalStorage } from '@keboola/api-client';
-
-// `defaultBaseUrl` is active from here on, until `resume()` or `stack.select` moves it.
 const { session } = createKeboola({ defaultBaseUrl, storage: createLocalStorage() });
-
-// The stored stack becomes 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();
+const status = await session.resume(); // restored | empty | expired | unreachable
 ```
 
-Every change (login, stack 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 active stack —
-plus a `stacks` array, each entry carrying its own credential. Only the durable part of a
-credential is written: a token credential's rotating refresh 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 the login's choice, and the credential carries it.** A browser-mode login
-(`login.withPassword({ …, browserMode: true })`) answers with no refresh token; stored as a `cookie`
-credential it renews through `token.refreshWithSession`, so the refresh token never reaches JS. That
-works only from the stack's own origin, so localhost and previews log in in API mode and hold a
-`token` credential. One client takes either kind, renews each by its own grant, and restores a
-persisted grant of either kind.
-
-**A stack is always active**, so `session.stack.getActive()` never returns `null`. 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 signed in or out, the resume leaves the active stack where it is, and a
-stack already signed in or out keeps that sign-in. 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.
-
-**`localStorage` vs `sessionStorage` — scope, not safety.** Neither is more secure: both are readable
-by any script on the origin (XSS), so the choice is purely about lifetime. `createLocalStorage()`
-survives a browser restart ("stay signed in") and is shared across tabs; `createSessionStorage()` is
-per-tab and cleared when the tab closes. Because neither is XSS-proof, the persisted blob is kept
-minimal — the rotating **refresh token** plus `baseUrl`/`projectId`, never the access token or
-identity; the access token lives only in memory, and the stored refresh token is single-use (rotated
-on every refresh) and server-revocable, so a leaked snapshot has limited, revocable value. The
-genuinely secure option — keeping the refresh token out of JS entirely behind a BFF
-(backend-for-frontend) with an HttpOnly cookie — is out of scope for now.
-
-`createStorageClient` exposes the same Storage surface as `api.storage.*` but no lifecycle and no `context` helpers (`baseUrl` / `stack`). Per-service factories (`@keboola/api-client/storage`, `@keboola/api-client/management`, …) also exist for standalone single-service use.
-
-**Need the stack URL? Use `api.baseUrl`, not `api.stack.host`.** `baseUrl` is the absolute URL the client is configured against and builds every request on, canonical form (no trailing slash). `stack.host` is a bare hostname the stack reports about itself in its index response — no scheme, and not what routes a request, so the two can legitimately differ on a proxied or custom-domain deployment.
-
-Import paths:
-
-| Export path                               | Purpose                                                          |
-| ----------------------------------------- | ---------------------------------------------------------------- |
-| `@keboola/api-client`                     | Full SDK: `createKeboola` / `createLegacyKeboola`, errors, utils |
-| `@keboola/api-client/<client>`            | Per-client factory (e.g. `storage`)                              |
-| `@keboola/api-client/<client>/types`      | Per-client type imports                                          |
-| `@keboola/api-client/sdk/tag`             | Tag SDK (composes multiple clients)                              |
-| `@keboola/api-client/sdk/developerPortal` | Developer Portal SDK (client + its session)                      |
-| `@keboola/api-client/sdk/configurations`  | Core configuration SDK                                           |
-| `@keboola/api-client/sdk/dataAppServer`   | Data app server: Query Service per signed-in user (Node only)    |
-| `@keboola/api-client/domain/permissions`  | Permission primitives                                            |
+- Call `resume()` once on startup; persistence starts after it settles. A stack the caller selected
+  or signed in or out first keeps that.
+- Stored: the active stack and each stack's grant — its refresh token, or a cookie credential's
+  session id. Never an access token or an identity.
+- A browser-mode login (`browserMode: true`) holds a `cookie` credential, which renews only on the
+  stack's own origin; localhost and previews hold a `token` one.
+- Adapters: `createLocalStorage` (survives a restart, shared across tabs), `createSessionStorage`
+  (per tab), `createMemoryStorage`, `createNullStorage`. Both browser stores are readable by any
+  script on the origin, which is why only the single-use refresh token is written.
+
+### Import paths
+
+| Export path                               | Purpose                                                       |
+| ----------------------------------------- | ------------------------------------------------------------- |
+| `@keboola/api-client`                     | Full SDK: `createKeboola`, errors, utils                      |
+| `@keboola/api-client/<client>`            | Per-client factory (e.g. `storage`)                           |
+| `@keboola/api-client/<client>/types`      | Per-client type imports                                       |
+| `@keboola/api-client/sdk/tag`             | Tag SDK (composes multiple clients)                           |
+| `@keboola/api-client/sdk/developerPortal` | Developer Portal SDK (client + its session)                   |
+| `@keboola/api-client/sdk/configurations`  | Core configuration SDK                                        |
+| `@keboola/api-client/sdk/dataAppServer`   | Data app server: Query Service per signed-in user (Node only) |
+| `@keboola/api-client/domain/permissions`  | Permission primitives                                         |
 
 ### Query Service credentials
 
@@ -340,11 +229,10 @@ When a caller writes a component configuration on a user's behalf — an agent-g
 `createConfigurationSdk` (`@keboola/api-client/sdk/configurations`) takes the storage and encryption clients plus the project context the permission guard reads — the verified token as `createProject` builds it, and the branch refs as `createBranchRefs` builds them. It is not on `api.sdk`: the token is the consumer's to fetch.
 
 ```ts
-import { createBranchRefs, createLegacyKeboola, createProject } from '@keboola/api-client';
+import { createBranchRefs, createProject } from '@keboola/api-client';
 import { createConfigurationSdk } from '@keboola/api-client/sdk/configurations';
 
-const { api, session } = createLegacyKeboola({ baseUrl });
-await session.authenticateStorageAsync(sapiToken); // → ready
+const api = keboola.projectApi(projectId); // a signed-in `createKeboola` client
 const [token, devBranches] = await Promise.all([
   api.storage.tokens.verify(),
   api.storage.branches.getDevBranches(),
@@ -453,33 +341,26 @@ Don't reach for `err.message || 'fallback'` or test `err.message === ''` instead
 
 Error classes the SDK can throw — branch on these instead of a catch-all `unknown`:
 
-| Class                       | Exported from                            | Branch specifically when…                                                   |
-| --------------------------- | ---------------------------------------- | --------------------------------------------------------------------------- |
-| `ApiError`                  | `@keboola/api-client`                    | You need raw `response` / `request` / parsed `data` (e.g. 4xx payload)      |
-| `UserError`                 | `@keboola/api-client`                    | You want to surface `err.message` verbatim — already phrased for users      |
-| `ServiceUnavailableError`   | `@keboola/api-client`                    | A namespace was accessed on a stack that doesn't host it — hide the feature |
-| `ManagementClientAuthError` | `@keboola/api-client`                    | Session expired (management redirected to login) — global re-login UX       |
-| `RowLevelSecurityError`     | `@keboola/api-client`                    | Row-level security refused the query for the caller — show "no access"      |
-| `PermissionDeniedError`     | `@keboola/api-client/domain/permissions` | A client-side `assertCan*` refused before any HTTP round-trip               |
+| Class                       | Exported from                            | Branch specifically when…                                              |
+| --------------------------- | ---------------------------------------- | ---------------------------------------------------------------------- |
+| `ApiError`                  | `@keboola/api-client`                    | You need raw `response` / `request` / parsed `data` (e.g. 4xx payload) |
+| `UserError`                 | `@keboola/api-client`                    | You want to surface `err.message` verbatim — already phrased for users |
+| `ServiceUnavailableError`   | `@keboola/api-client`                    | A call reached a service the stack doesn't host — hide the feature     |
+| `ManagementClientAuthError` | `@keboola/api-client`                    | A `management-token` session expired: Manage sent its login page       |
+| `RowLevelSecurityError`     | `@keboola/api-client`                    | Row-level security refused the query for the caller — show "no access" |
+| `PermissionDeniedError`     | `@keboola/api-client/domain/permissions` | A client-side `assertCan*` refused before any HTTP round-trip          |
 
 There is **no** `ServerError` class — server-originated failures surface as `ApiError`; discriminate 5xx from 4xx via `err.response.status` inside `isApiError(err)`. `ManagementClientAuthError` and `RowLevelSecurityError` extend `ApiError`, so check `isManagementClientAuthError` / `isRowLevelSecurityError` first.
 
 Canonical try/catch — order guards most-specific first:
 
 ```ts
-import {
-  isAbortError,
-  isApiError,
-  isFetchClientError,
-  isManagementClientAuthError,
-  readableReason,
-} from '@keboola/api-client';
+import { isAbortError, isApiError, isFetchClientError, readableReason } from '@keboola/api-client';
 
 try {
   await api.storage.tables.getTable({ branchId, tableId: id }, signal);
 } catch (err) {
   if (isAbortError(err)) return; // cancelled — no UI
-  if (isManagementClientAuthError(err)) return redirectToLogin();
   if (isApiError(err)) return toast.error(readableReason(err) ?? 'Saving failed.'); // see below
   if (isFetchClientError(err)) return toast.error('Network problem');
   throw err; // unexpected — propagate
@@ -489,9 +370,9 @@ try {
 TanStack Query's `onError` / `throwOnError` handles most cases; the explicit try/catch applies to `mutationFn`, event handlers, or one-off `await`s outside queries. **Let Query handle retries and state; let the component decide UX.** Retry by status:
 
 - **Transport (`TypeError`)** → transient; retry up to 3× with backoff (`retryDelay: (a) => Math.min(1000 * 2 ** a, 30_000)`). Skip `SyntaxError` (server contract bug, not transient).
-- **401 / 403** → never retry. Session expiry surfaces as `ManagementClientAuthError` (check `isManagementClientAuthError`) — branch to a global re-login.
+- **401 / 403** → never retry. A bearer client reports a dead sign-in once, through `createKeboola`'s `onExpired`, not on each call.
 - **404 on a `GET`** → normal product state; render an empty state, not "Something went wrong". A 404 on a _mutation_ (deleting an already-gone resource) can be treated as success.
-- **5xx** → server-side, often transient. The default client wires **no** transport-level retry (the keboola client sets only the storage-token middleware). Add `createRetryMiddleware` to the client's `middlewares` for automatic 5xx retry, and then keep `retry: false` at the query level so attempts don't multiply (query `retry: 2` × the middleware's 6 transport attempts = 18 requests). Surface `readableReason(err)` with your own wording as the fallback; richer detail may be on `err.data` (typed `unknown` — narrow before reading).
+- **5xx** → server-side, often transient. The default client wires **no** transport-level retry. Add `createRetryMiddleware` to the client's `middlewares` for automatic 5xx retry, and then keep `retry: false` at the query level so attempts don't multiply (query `retry: 2` × the middleware's 6 transport attempts = 18 requests). Surface `readableReason(err)` with your own wording as the fallback; richer detail may be on `err.data` (typed `unknown` — narrow before reading).
 
 ```ts
 useQuery({
@@ -557,7 +438,7 @@ The `fetch()`, `axios`, and legacy `@/api` bans are mechanically enforced by oxl
 
 **Authoritative surface index: [`API-SURFACE.md`](./API-SURFACE.md)** — a compact list of every namespace and method **name** (no signatures), generated from the `ProjectApi` type by `scripts/gen-surface.mjs`. Read it to confirm a namespace/method exists before calling it — don't guess. For the **full resolved signature**, open the per-namespace detail file it links to, [`surface/<namespace>.md`](./surface) (e.g. `surface/storage.md`) — split per namespace so you load only the slice you need rather than every signature at once. A CI drift check (`surface:check`, wired into the package's `ci-checks`) fails if either goes stale; regenerate with `pnpm --filter @keboola/api-client surface`.
 
-The full namespace set is the `ProjectApi` type in `src/keboola/createApi.ts`. Quick top-level reference (see the index for the complete, current list):
+The full namespace set is the `ProjectApi` type in `src/keboola/types.ts`. Quick top-level reference (see the index for the complete, current list):
 
 ```
 api.storage.*        api.management.*     api.vault.*
@@ -576,7 +457,7 @@ api.sdk.tag.*        api.sdk.storage.*
 - `healthCheck()`, `GET /v2/docs/swagger.yaml` and unauthenticated calls answer the same everywhere.
 - A `401` from an authenticated call means a bad or expired token, not a missing API.
 
-Clients backing optional stack services (vault, queue, …) throw `ServiceUnavailableError` if absent from the current stack — check `api.stack.hasService(...)` before assuming a namespace exists.
+A call to an optional stack service (vault, queue, …) that the stack doesn't host rejects with `ServiceUnavailableError` — check `api.stack.hasService(...)` before offering the feature.
 
 **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:
 
@@ -618,7 +499,7 @@ const { api, session } = createDeveloperPortalSdk({
 
 An endpoint goes on the client; anything that has to _know a token over time_ goes in the SDK, which
 owns the store, `credential.ts`, `middleware.ts` and `tokenExpiry.ts` — the analogue of
-`keboola/bearer/` for Connection. The client alone covers every operation the spec marks `security: []`.
+`keboola/` for Connection. The client alone covers every operation the spec marks `security: []`.
 
 Three things about it are unusual:
 
@@ -749,7 +630,7 @@ 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`.
+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: `auth.isAuthenticated` / `auth.isAuthenticatedAsync`, `stack.getContext` / `stack.getContextAsync`.
 
 ```ts
 const deleteBucketAsync = async (…): Promise<Job<'bucketDelete'>> => { … }; // enqueues
@@ -832,7 +713,7 @@ committed schema byte-for-byte.
 **3. Client and SDK are different things, and the split is not negotiable.** A client is one method
 per endpoint, holds **no state and never holds a token** — if it takes a credential, it is not a
 client. Anything that knows a token over time (a store, refresh-and-replay, expiry) belongs in
-`sdks/`, the way `keboola/bearer/` does for Connection. A client that needs auth takes a
+`sdks/`, the way `keboola/` does for Connection. A client that needs auth takes a
 `MiddlewareFn`, not an `auth: AuthStrategy` and not a credential; the SDK supplies it. Endpoints
 that authenticate with something other than the default credential take that token **as an
 argument** and the SDK binds it, so the consumer surface stays argument-free.
@@ -877,7 +758,7 @@ A new client/namespace means touching four places that must stay in lock-step
 
 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.
+**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/perStack.ts`. Read it as the reference shape for a new client rather than copying boilerplate. **Bearer auth lives in `keboola/`, 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 sign-in) in `state.auth.notifyExpired`, not the credential — the credential and middleware are long-lived singletons. The middleware holds no token — all token state is in the session table, which the credential reads live, so a rotation is picked up without rebuilding. See `keboola/keboola.ts` for the wiring.
 
 ## Development
 

package/API-SURFACE.md

@@ -2,9 +2,9 @@
 
 <!-- GENERATED FILE — do not edit by hand. Run `pnpm --filter @keboola/api-client surface` to regenerate. -->
 
-Every namespace and method reachable from a ready `ProjectApi` — one project's api (`createKeboola(...).getProjectApi(id)` / `createLegacyKeboola(...).api`, or `useProjectApi()`). Generated from the TypeScript type checker — see `scripts/gen-surface.mjs`.
+Every namespace and method reachable from a ready `ProjectApi` — one project's api (`createKeboola(...).projectApi(id)`, or `useProjectApi()`). Generated from the TypeScript type checker — see `scripts/gen-surface.mjs`.
 
-26 top-level namespaces, 707 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, 715 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)
 
@@ -22,9 +22,12 @@ Every namespace and method reachable from a ready `ProjectApi` — one project's
 - `createApp`
 - `createAppGitRepoCredential`
 - `createDeployment`
+- `createDraft`
+- `createDraftPreviewLink`
 - `deleteApp`
 - `deleteAppGitRepoCredential`
 - `deleteDeployment`
+- `deleteDraft`
 - `getApp`
 - `getAppGitRepo`
 - `getAppGitRepoBranches`
@@ -41,6 +44,8 @@ Every namespace and method reachable from a ready `ProjectApi` — one project's
 - `getDeploymentLogsDownload`
 - `getDeploymentLogsTail`
 - `getDeployments`
+- `getDraft`
+- `getDrafts`
 - `healthCheck`
 - `promoteDeployment`
 - `resetAppPassword`
@@ -66,6 +71,7 @@ Every namespace and method reachable from a ready `ProjectApi` — one project's
 - `me.getMaintainers`
 - `me.getOrganizations`
 - `me.getProjects`
+- `me.update`
 - `mfa.regenerateRecoveryCodes`
 - `mfa.totp.disable`
 - `mfa.totp.setup`
@@ -193,6 +199,7 @@ Every namespace and method reachable from a ready `ProjectApi` — one project's
 - `submitToolOutput`
 - `submitVote`
 - `updateAgentSettings`
+- `updateChatProjects`
 - `updateProjectToolPolicy`
 - `updateSpendCaps`
 - `updateTurnCredential`
@@ -648,6 +655,7 @@ Every namespace and method reachable from a ready `ProjectApi` — one project's
 - `stats.getRunIdStats`
 - `tableList.getAllTables`
 - `tableList.getTables`
+- `tableList.iterateTables`
 - `tables.createAliasTable`
 - `tables.createTableAsync`
 - `tables.createTableDefinitionAsync`

package/CHANGELOG.md

@@ -1,5 +1,50 @@
 # @keboola/api-client
 
+## 57.0.0
+
+### Major Changes
+
+- **Breaking:** `createLegacyKeboola` and its session are gone, with no replacement factory. `LegacySession`, `LegacyKeboolaOptions`, `LegacyAuthProvider` and `useLegacyAuth` go with it, as do the `NoManagementToken`, `NoStorageToken`, `MissingProject`, `NotBearer` and `InvalidBuildTransition` error types and the `all` key of `middlewares` — list a middleware under each client it belongs to. `createKeboola` returns `stackApi` in place of `getStackApi()` — the same object, whose reads follow the active stack — and `projectApi(projectId)` in place of `getProjectApi(projectId)`. The `BearerSession` type is `Session`. `createStorageClient` drops its `onRefreshToken` option, and `createDerivedStore`, `createDerivedAsyncStore`, `shallowEqual` and `AsyncState` go: the legacy client was their only user. `Store.dispose`, `Emitter.clear` and the `ReadableStore` type go with them. `ProjectApi.serviceMeta` goes: every entry was available, and a call to a missing service rejects instead. `ProjectFeature.FrontendLogin` goes: nothing reads it. A call to a service the stack does not run rejects with `ServiceUnavailableError` again, not `NotReady`; its `path` and `clientName` are optional. A Storage API token builds the per-service clients it calls (`createStorageClient`, `createOauthClient`, …), each service's URL from `storage.getStackInfo()`; a full `ProjectApi` comes from a `createKeboola` sign-in (UT-5193)
+
+### Minor Changes
+
+- `auth.me.update({ name })` renames the signed-in user (`PATCH /v1/auth/me`) and resolves the updated `user`. The auth schema is regenerated from Connection's spec with that endpoint; it also carries `reportedClientName` on `sessions[]` items (`SessionItemResponse`).
+
+- `StackFeature.SpaDocument` (`spa-document`): the stack serves kbc-ui as a payload-less SPA document.
+
+- Storage client: `tableList.getTables` and `tableList.getAllTables` take `filter.changedSince` (`filter[changedSince]`, an ISO 8601 time with an offset), listing only the tables whose row changed at or after it. `getAllTables` sends it on every page.
+
+- `tableList.iterateTables` yields table list V2 pages one at a time as they arrive, so a caller can render the first page before the walk ends. `iterateByCursor` is the generic cursor walk behind it and behind `collectByCursor`.
+
+- `api.apps` covers data-app drafts: `createDraft`, `getDrafts`, `getDraft`, `deleteDraft` and `createDraftPreviewLink`, with the `Draft`, `DraftId`, `DraftRunState`, `DraftPreviewLink`, `CreateDraftBody` and `GetDraftsQuery` types from `@keboola/api-client/apps/types`.
+
+- The Developer Portal admin client gains `getAppVersions(id)` (`GET /admin/apps/{id}/versions`), which lists every version with its `waveTags`, and `getAppForWave(id, wave)` (`GET /admin/apps/{id}?wave=N`), which returns the app as a stack on that wave gets it. `AppWaveTags` and `AppWavePin` are exported from `@keboola/api-client/developerPortal/types`.
+
+- Bucket listings carry the Snowflake variant (DMD-2496). `BucketListingDetail` and `ProjectBucketListing` may have `backend: 'snowflake'` with a `snowflake` section (`mode`, `grantees`, `objectName`, typed as `SnowflakeBucketListingDetail`). `createListingAsync` takes `snowflake: { mode: 'grant', grantees }` in place of `listingId` and `subscribers`, and `updateListingAsync` takes `grantees`. A finished `bucketListingUpdate` job carries its result, typed per backend as `BucketListingUpdateJobResult`. The Snowflake types are written by hand until the deployed Storage spec carries the section.
+
+- Add `api.kaiAgent.updateChatProjects(chatId, { projectIds, activeProjectId })` to set the projects a chat spans, and `projectIds`/`activeProjectId` on the `getChat` response and `projectIds` on the create-chat request.
+
+### Patch Changes
+
+- The legacy management auth middleware replaces an expired manage token instead of failing: Connection answers it with `400` and `code: storage.tokenExpired`, not `401`. Any other `400`, such as a disabled token, still propagates.
+
+- Regenerate the ai, apps, auth, dataScience, kaiAgent, management, microsoftGraph, omnisearch, queryService, queue, storage and vault OpenAPI types against the live services.
+
+  - Storage dev branches, workspaces and tokens carry a required, nullable `actor`; buckets carry `sharedByActor`; table details carry `createdBy` and `lastUpdatedBy`.
+  - `@keboola/api-fixtures` storage fixtures set these fields to `null`.
+
+- `session.auth.signOut()` ends the sign-in on the server too: the session, its refresh token, its derived PATs and the paired browser session.
+
+  - A token grant revokes its refresh token; a cookie grant renews off its session cookie and revokes that fresh access token. The grant is read from storage, so a rotation in another tab does not leave the session alive.
+  - The local sign-out never depends on it: it is stored first, a failure is logged, and the wait is bounded (10 s).
+  - A repeated sign-out on the same stack (a double click) resolves only once the first has ended the session.
+  - A rotation that finds the stack signed out in storage (another tab signed out) signs this tab out and reports it through `onExpired`.
+  - `signOut({ retain: true })` and `auth.replace()` leave the server session alone.
+
+- Configuration `folder` and `folderUpdated` come from the generated storage schema; the hand-written fields are gone (DMD-2348). A configuration read now always carries both, `null` when there is no folder, and the create and update bodies take `folder` as `string | null`.
+
+- Snowflake bucket listings use the regenerated storage types (DMD-2496). `BucketListingDetail`, `ProjectBucketListing` and the `bucketListingUpdate` job result come from the spec, so the hand-written `SnowflakeExposureMode`, `SnowflakeBucketListingDetail` and `BucketListingUpdateJobResult` are removed. `createListingAsync` sends a Snowflake body through the typed client. The regeneration also makes a job's `creatorToken.id` nullable and adds `description` to workspace table loads.
+
 ## 56.0.0
 
 ### Minor Changes