@keboola/api-client 36.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.
 
@@ -334,11 +353,19 @@ Three type guards live in `createFetchClient.ts`, re-exported from `@keboola/api
 | Guard                | Catches                                                         | UX outcome                                        |
 | -------------------- | --------------------------------------------------------------- | ------------------------------------------------- |
 | `isAbortError`       | `DOMException { name: 'AbortError' }`                           | Silently ignore — user/unmount cancelled          |
-| `isApiError`         | HTTP error responses parsed by the SDK                          | Surface `err.message` (HTTP `statusText`)         |
+| `isApiError`         | HTTP error responses parsed by the SDK                          | Surface `readableReason(err)`; see below          |
 | `isFetchClientError` | `TypeError` (DNS/CORS), `SyntaxError` (bad JSON), or `ApiError` | Show a "Network problem" message; do not re-throw |
 
 > `DOMException` is in the `FetchClientError` _type_ but **not** matched by the `isFetchClientError` _guard_ — abort `DOMException`s are reachable only through `isAbortError`, so always check `isAbortError` first.
 
+**Never render `err.message` to a user.** An `ApiError`'s message is a status line — `"404 Not Found"`, or just `"404"` over HTTP/2, which is every production response. It exists so an error reporter has the status; it names neither the action that failed nor anything the reader can do. `readableReason(err)` returns the service's own sentence from the parsed body, and `undefined` when there is none — which is the cue to render your own wording:
+
+```ts
+toast.error(readableReason(err) ?? 'The semantic model could not be deleted.');
+```
+
+Don't reach for `err.message || 'fallback'` or test `err.message === ''` instead. A status line is never empty, so those guards silently stop firing and the reader gets a number where a sentence was written for them.
+
 Error classes the SDK can throw — branch on these instead of a catch-all `unknown`:
 
 | Class                       | Exported from                            | Branch specifically when…                                                   |
@@ -359,6 +386,7 @@ import {
   isApiError,
   isFetchClientError,
   isManagementClientAuthError,
+  readableReason,
 } from '@keboola/api-client';
 
 try {
@@ -366,7 +394,7 @@ try {
 } catch (err) {
   if (isAbortError(err)) return; // cancelled — no UI
   if (isManagementClientAuthError(err)) return redirectToLogin();
-  if (isApiError(err)) return toast.error(err.message); // HTTP error from server
+  if (isApiError(err)) return toast.error(readableReason(err) ?? 'Saving failed.'); // see below
   if (isFetchClientError(err)) return toast.error('Network problem');
   throw err; // unexpected — propagate
 }
@@ -377,7 +405,7 @@ TanStack Query's `onError` / `throwOnError` handles most cases; the explicit try
 - **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.
 - **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 `err.message` (`statusText`); 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 (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).
 
 ```ts
 useQuery({
@@ -475,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:
@@ -585,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`.
 
-25 top-level namespaces, 635 methods. This index lists method **names** only — full signatures live per namespace under [`surface/`](./surface). Open `surface/<namespace>.md` for the one you need.
+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`
@@ -91,6 +95,15 @@ Every namespace and method reachable from a ready `KeboolaApi` — the `api` hal
 - `getCreditsAndTopUp`
 - `healthCheck`
 
+## [`api.businessWorkspaceApi`](./surface/businessWorkspaceApi.md)
+
+- `createDashboard`
+- `deleteDashboard`
+- `getDashboard`
+- `getDashboards`
+- `healthCheck`
+- `updateDashboard`
+
 ## [`api.chat`](./surface/chat.md)
 
 - `createChat`
@@ -186,6 +199,8 @@ Every namespace and method reachable from a ready `KeboolaApi` — the `api` hal
 - `deleteChat`
 - `downloadSandboxFile`
 - `getAgentSettings`
+- `getArtifact`
+- `getArtifacts`
 - `getChat`
 - `getHistory`
 - `getSandboxGitBranch`
@@ -198,17 +213,23 @@ Every namespace and method reachable from a ready `KeboolaApi` — the `api` hal
 - `getVotes`
 - `healthCheck`
 - `listSandboxFiles`
+- `prepareChat`
 - `readSandboxFile`
 - `setUserSpendLimit`
 - `stopChat`
 - `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`
@@ -295,6 +316,7 @@ Every namespace and method reachable from a ready `KeboolaApi` — the `api` hal
 - `payAsYouGo.getTopUpSetting`
 - `payAsYouGo.updateStripeCustomer`
 - `payAsYouGo.updateTopUpSetting`
+- `programmaticProjects.confirm`
 - `projects.addProjectFeature`
 - `projects.addProjectTemplateFeature`
 - `projects.addProjectUser`
@@ -340,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`
@@ -438,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`
@@ -696,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)