@keboola/api-client 48.0.0 → 50.0.0

package/AGENTS.md

@@ -26,10 +26,10 @@ 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 `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.
+**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.
 
 ```ts
-const api = useApiClient();
+const api = useProjectApi();
 const { data } = useQuery({
   queryKey: storageApiKey.getTable(id),
   queryFn: ({ signal }) => api.storage.tables.getTable({ branchId, tableId: id }, signal),
@@ -38,8 +38,8 @@ 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. `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`.
+- **`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` / `createDefaultBranch` — 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.
 
@@ -60,7 +60,7 @@ 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.context.stack; // synchronous — the storage build has resolved
+const stack = api.stack; // synchronous — the storage build has resolved
 const buckets = await api.storage.buckets.getBuckets();
 ```
 
@@ -68,31 +68,34 @@ const buckets = await api.storage.buckets.getBuckets();
 
 Two flow-specific factories back the SDK:
 
-- `createKeboola({ defaultBaseUrl, … })` — the **bearer (OAuth)** flow. Returns `{ session, getActiveApi, getApi }`;
-  `getActiveApi()` is the scoped product surface, `getApi(projectId)` a pinned one (see below).
+- `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.context` / `api.sdk` / …** — product namespaces, live only once
-  the async storage build reaches `ready` (throw `KeboolaError` (`NotReady`) before that).
+- **`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)` → `project.select(projectId)`,
-  plus `auth.signOut({ baseUrl?, retain? }?)` / `auth.replace(credential)` / `auth.isAuthenticated()` / `auth.isAuthenticatedAsync()` / `auth.rotate(baseUrl)` / `auth.getHeaders(projectId?)` / `auth.getHeadersAsync(projectId?)`, `auth.restoreRetained(baseUrl)`, `stack.close` and
-  the two `deactivate`s, and `getState()` / `subscribe(cb)` over the stack-and-project table. Every
-  verb changes the table synchronously — nothing awaits a build; a namespace throws `NotReady` until
-  its fetch lands. `stack.select`, `project.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 scope or sign-in it was meant to replace.
-  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.
+- 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()`.
@@ -104,24 +107,25 @@ await session.authenticateStorageAsync(token);
 const buckets = await api.storage.buckets.getBuckets(defaultBranchId);
 
 // Bearer (OAuth) login flow (browser)
-const { session, getActiveApi } = createKeboola({ defaultBaseUrl: baseUrl }); // `auth` is live now
-const result = await getActiveApi().auth.login.withPassword({ email, password });
+// `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 });
-session.project.select(projectId); // → the scope `getActiveApi()` addresses
+const api = getProjectApi(projectId); // → every product namespace, for the project the app is in
 ```
 
 ### Several projects at once (bearer)
 
 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:
+so `getProjectApi(projectId)` hands out a product surface per project, off the client already in
+hand:
 
 ```ts
-const { session, getActiveApi, getApi } = createKeboola({ defaultBaseUrl: baseUrl });
+const { session, getProjectApi } = 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 api = getProjectApi(42);
+const other = getProjectApi(7);
 
 const [mine, theirs] = await Promise.all([
   api.storage.buckets.getBuckets({ branchId: 'default' }),
@@ -129,50 +133,48 @@ const [mine, theirs] = await Promise.all([
 ]);
 ```
 
-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.
+Both are synchronous and lazy: the surface resolves per property read, so `stack` throws
+`KeboolaError` (`NotReady`) until the stack index lands.
 
-**The method is the lifetime, and that is the whole difference:**
+**Two handles, two lifetimes:**
 
-- **`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.
+- **`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.
 
-Three things follow from that, worth knowing before you hold one:
+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`.
+- **`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 project's row goes `errored` and
-  the sign-in stands. **The refresh is the only oracle** — the server refusing the refresh token is
+  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** — `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
+- **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 the active stack decides, falling back to a single project
-with that id open elsewhere. `getHeaders` reads the token the fetch clients keep fresh;
-`auth.getHeadersAsync(projectId?)` renews it first once it nears expiry, for a transport that can
-run after the fetch traffic has gone quiet.
+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
@@ -187,9 +189,9 @@ two-phase rotation and replay detection on the server. Whichever instance rotate
 the other's token, whose next refresh 401s and signs it out. This is a functional break, not a style
 preference, and it does not depend on a `storage` adapter being configured.
 
-In React, `useApiClient()` returns `api`; `AuthProvider` (bearer) / `LegacyAuthProvider` (legacy) own
-driving the `session` to ready and gate on a `fallback`. See
-[`@keboola/api-client-react`](../api-client-react/AGENTS.md).
+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:
@@ -200,17 +202,17 @@ 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 and project become active again; with nothing stored, the default stays.
+// 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();
 ```
 
-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, 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.
+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`
@@ -219,12 +221,11 @@ works only from the stack's own origin, so localhost and previews log in in API
 `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` and the active
-stack cannot be closed. Call `resume()` once on startup: persistence starts only after it settles,
+**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 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.
+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.
 
@@ -238,9 +239,9 @@ on every refresh) and server-revocable, so a leaked snapshot has limited, revoca
 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` / `project` / `defaultBranch`). Per-service factories (`@keboola/api-client/storage`, `@keboola/api-client/management`, …) also exist for standalone single-service use.
+`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.context.baseUrl`, not `api.context.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.
+**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:
 
@@ -265,22 +266,35 @@ Never reach below `clients/` to `fetchClient` directly — all HTTP must flow th
 
 ## Writing a configuration safely (agents / Node)
 
-When a caller writes a component configuration on a user's behalf — an agent-generated payload, a BE/Node process, a script — go through `api.sdk.configuration`, **never** `api.storage.configurations.createConfiguration` directly. The SDK method carries the config-write business logic that would otherwise have to be re-implemented (and kept in sync) per consumer:
+When a caller writes a component configuration on a user's behalf — an agent-generated payload, a BE/Node process, a script — go through the configuration SDK, **never** `api.storage.configurations.createConfiguration` directly. The SDK method carries the config-write business logic that would otherwise have to be re-implemented (and kept in sync) per consumer:
 
 1. **Validate** — parses `configuration` against the component's registered **input schema** (a deep-partial of the runnable schema) from `sdks/configurations/registry.ts`.
 2. **Encrypt** — hands every `#`-prefixed secret field to the encryption service (a remote call) and writes back the ciphertext, so a **plaintext secret is never sent to Storage**.
 3. **Write** — only then calls Storage.
 
-`api.sdk.configuration` is auto-wired (storage + encryption + project context) by `createKeboola` / `createLegacyKeboola`, so a Node consumer constructs nothing by hand:
+`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 default branch as `createDefaultBranch` builds it. It is not on `api.sdk`: the token is the consumer's to fetch.
 
 ```ts
-import { createLegacyKeboola } from '@keboola/api-client';
+import { createDefaultBranch, createLegacyKeboola, createProject } from '@keboola/api-client';
+import { createConfigurationSdk } from '@keboola/api-client/sdk/configurations';
 
 const { api, session } = createLegacyKeboola({ baseUrl });
 await session.authenticateStorageAsync(sapiToken); // → ready
+const [token, devBranches] = await Promise.all([
+  api.storage.tokens.verify(),
+  api.storage.branches.getDevBranches(),
+]);
+const configuration = createConfigurationSdk({
+  storageClient: api.storage,
+  encryptionClient: api.encryption,
+  context: {
+    project: createProject({ sapiToken: token }),
+    defaultBranch: createDefaultBranch({ devBranches }),
+  },
+});
 
 // componentId must be a registered id; `#`-prefixed fields are encrypted before the write.
-const result = await api.sdk.configuration.createConfiguration({
+const result = await configuration.createConfiguration({
   componentId: 'keboola.ex-db-mysql',
   name: 'Orders DB',
   configuration: {
@@ -439,7 +453,7 @@ Surfacing — toast vs inline:
 
 `@keboola/api-client/domain/permissions` holds token-only capability predicates: `canX` (boolean, safe in any UI condition) paired with `assertCanX` (throws `PermissionDeniedError` before any HTTP round-trip). Catch the error to gate UI without a network call; let it propagate from `useQuery` to surface a "no access" empty state.
 
-Implemented today: `admin.ts` (`isAdmin`, `isProductionManager`, … + matching `assertCan*`, all `(token)`-only), `configurations.ts` (`canCreate/canCopy/canMigrateFromTemplate/canPurge/canAssignFolder` + `assertCan*`, taking a trailing `ctx: ConfigurationCtx`), and `organization.ts` (`isOrganizationMember`, `isOrganizationAdmin`, `canWriteKaiSpendCaps`, all `(token)`-only — reads `StorageToken.admin.isOrganizationMember` rather than the project role string; `assertCanAdministerOrganization`/`assertCanWriteKaiSpendCaps` pair with the latter two, `isOrganizationMember` is a raw signal with no assert). `storage.ts`, `devBranches.ts`, `sandboxes.ts` are still `export {}` placeholders.
+Implemented today: `admin.ts` (`isAdmin`, `isProductionManager`, … + matching `assertCan*`, all `(token)`-only), `configurations.ts` (`canCreate/canCopy/canMigrateFromTemplate/canPurge/canAssignFolder` + `assertCan*`, taking a trailing `ctx: ConfigurationCtx`), and `organization.ts` (`isOrganizationMember`, `isOrganizationAdmin`, `canWriteKaiSpendCaps`, all `(token)`-only — reads `StorageToken.admin.isOrganizationMember` rather than the project role string; `assertCanAdministerOrganization`/`assertCanWriteKaiSpendCaps` pair with the latter two, `isOrganizationMember` is a raw signal with no assert), and `storage.ts` (`canListSharingTargets`, `(token)`-only, no assert — it gates a query; `createProject` exposes it). `devBranches.ts`, `sandboxes.ts` are still `export {}` placeholders.
 
 ```ts
 import { PermissionDeniedError } from '@keboola/api-client/domain/permissions';
@@ -457,13 +471,13 @@ try {
 
 ## What NOT to Do
 
-| Anti-pattern                                     | Why it's wrong                             | Replacement                                       |
-| ------------------------------------------------ | ------------------------------------------ | ------------------------------------------------- |
-| `fetch('/api/...')` directly                     | Bypasses auth, middleware, and type safety | `useApiClient()` + `api.*` methods                |
-| `import axios from 'axios'`                      | Not installed; circumvents the SDK layer   | `useApiClient()` from `@keboola/api-client-react` |
-| `import { Api } from '@/api'`                    | Legacy hand-rolled client being removed    | `useApiClient()` + typed service client           |
-| Importing from `@keboola/api-client/fetchClient` | Internal transport layer, not public API   | Use the `clients/` or `sdks/` layer               |
-| `enabled: false` for conditional queries         | Does not narrow `data` type                | `queryFn: !ready ? skipToken : ...`               |
+| Anti-pattern                                     | Why it's wrong                             | Replacement                                        |
+| ------------------------------------------------ | ------------------------------------------ | -------------------------------------------------- |
+| `fetch('/api/...')` directly                     | Bypasses auth, middleware, and type safety | `useProjectApi()` + `api.*` methods                |
+| `import axios from 'axios'`                      | Not installed; circumvents the SDK layer   | `useProjectApi()` from `@keboola/api-client-react` |
+| `import { Api } from '@/api'`                    | Legacy hand-rolled client being removed    | `useProjectApi()` + typed service client           |
+| Importing from `@keboola/api-client/fetchClient` | Internal transport layer, not public API   | Use the `clients/` or `sdks/` layer                |
+| `enabled: false` for conditional queries         | Does not narrow `data` type                | `queryFn: !ready ? skipToken : ...`                |
 
 The `fetch()`, `axios`, and legacy `@/api` bans are mechanically enforced by oxlint — see `apps/kbc-ui/oxlint.config.ts`.
 
@@ -475,9 +489,9 @@ The `fetch()`, `axios`, and legacy `@/api` bans are mechanically enforced by oxl
 
 ## Service Discovery
 
-**Authoritative surface index: [`API-SURFACE.md`](./API-SURFACE.md)** — a compact list of every namespace and method **name** (no signatures), generated from the `KeboolaApi` 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`.
+**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 `KeboolaApi` 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/createApi.ts`. Quick top-level reference (see the index for the complete, current list):
 
 ```
 api.storage.*        api.management.*     api.vault.*
@@ -496,7 +510,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.context.stack.hasService(...)` before assuming a namespace exists.
+Clients backing optional stack services (vault, queue, …) throw `ServiceUnavailableError` if absent from the current stack — check `api.stack.hasService(...)` before assuming a namespace exists.
 
 **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:
 
@@ -511,9 +525,9 @@ 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 `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.
+Connection storage token. `createKeboola`'s session cannot drive it: its credential and its stack
+index are Connection's. 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:
 
@@ -569,7 +583,7 @@ import { fixtures, getTable, listTables, tableFixtures } from '@keboola/api-fixt
 import type { Table, TableDetail } from '@keboola/api-fixtures';
 ```
 
-To mock the client itself, mock at the module boundary with `vi.mock` against `@keboola/api-client` or the `useApiClient` hook.
+To mock the client itself, mock at the module boundary with `vi.mock` against `@keboola/api-client` or the `useProjectApi` hook.
 
 ## Authoring types — the generated schema is the source
 

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 `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`.
+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`.
 
-26 top-level namespaces, 727 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, 709 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)
 
@@ -27,8 +27,10 @@ Every namespace and method reachable from a ready `KeboolaApi` — the `api` hal
 - `deleteDeployment`
 - `getApp`
 - `getAppGitRepo`
+- `getAppGitRepoBranches`
 - `getAppGitRepoCredential`
 - `getAppGitRepoCredentials`
+- `getAppGitRepoEntrypoints`
 - `getAppLogsDownload`
 - `getAppLogsTail`
 - `getAppPassword`
@@ -123,31 +125,6 @@ Every namespace and method reachable from a ready `KeboolaApi` — the `api` hal
 - `healthCheck`
 - `setConnectorCredentials`
 
-## [`api.context`](./surface/context.md)
-
-- `defaultBranch.getType`
-- `defaultBranch.isDefault`
-- `defaultBranch.isDev`
-- `project.hasAdminFeature`
-- `project.hasBackend`
-- `project.hasFeature`
-- `st.createBucket`
-- `st.createDefaultBucket`
-- `st.createDefaultConfigBucket`
-- `st.createDefaultConfigTable`
-- `st.createDefaultCsvImportTable`
-- `st.createTable`
-- `st.parse`
-- `st.parseBucket`
-- `st.safeCreateDefaultBucket`
-- `st.safeParse`
-- `st.safeParseBucket`
-- `stack.getComponent`
-- `stack.getServiceUrl`
-- `stack.hasComponent`
-- `stack.hasFeature`
-- `stack.hasService`
-
 ## [`api.dataScience`](./surface/dataScience.md)
 
 - `createApp`
@@ -326,7 +303,8 @@ Every namespace and method reachable from a ready `KeboolaApi` — the `api` hal
 - `payAsYouGo.getTopUpSetting`
 - `payAsYouGo.updateStripeCustomer`
 - `payAsYouGo.updateTopUpSetting`
-- `programmaticProjects.confirm`
+- `programmaticProjects.confirmByCookie`
+- `programmaticProjects.confirmByToken`
 - `programmaticProjects.getClaim`
 - `projects.addProjectFeature`
 - `projects.addProjectTemplateFeature`
@@ -480,9 +458,6 @@ Every namespace and method reachable from a ready `KeboolaApi` — the `api` hal
 
 ## [`api.sdk`](./surface/sdk.md)
 
-- `configuration.createConfiguration`
-- `configuration.getConfiguration`
-- `configuration.updateConfiguration`
 - `kaiMemory.createItem`
 - `kaiMemory.deleteUnreadableItem`
 - `kaiMemory.getItems`
@@ -525,6 +500,14 @@ Every namespace and method reachable from a ready `KeboolaApi` — the `api` hal
 - `vault.setVariablesGroup`
 - `vault.updateVariable`
 
+## [`api.stack`](./surface/stack.md)
+
+- `getComponent`
+- `getServiceUrl`
+- `hasComponent`
+- `hasFeature`
+- `hasService`
+
 ## [`api.storage`](./surface/storage.md)
 
 - `branches.createDevBranchAsync`
@@ -779,7 +762,6 @@ Every namespace and method reachable from a ready `KeboolaApi` — the `api` hal
 - `genericExtractor.performFunction`
 - `genericExtractor.testRequest`
 - `git.getBranches`
-- `git.getEntrypoints`
 - `googleAnalytics.getProfilesProperties`
 - `googleAnalytics.getPropertiesMetadata`
 - `googleDrive.createFile`

package/CHANGELOG.md

@@ -1,5 +1,83 @@
 # @keboola/api-client
 
+## 50.0.0
+
+### Major Changes
+
+- The SDK no longer fetches a project's state. `api.baseUrl` and `api.stack` replace `api.context`; the verified token and the dev branches are the consumer's to fetch (`api.storage.tokens.verify()`, `api.storage.branches.getDevBranches()`) and derive with the exported `createProject` / `createDefaultBranch`.
+  - **Breaking:** `api.context` is gone. `api.baseUrl` is the canonical stack URL — on a bearer handle readable before a sign-in; `api.stack` is the parsed stack index, `NotReady` until it lands. The `ClientContext` type is replaced by `Stack`.
+  - **Breaking:** the project context (`sapiToken`, `defaultBranch`) is gone, with `session.project.getContext` / `getContextAsync` / `retryContext` and the `context` status on a project row. `api.sdk.configuration` is gone — build it with `createConfigurationSdk` from `@keboola/api-client/sdk/configurations`, handing it the project and default branch.
+  - **Breaking:** the bearer session knows no project; which one the app is in is the app's to keep. `getState().active` is the active stack's `baseUrl`. `session.project` (`select`, `deactivate`, `close`), `getState().projects` and the `ProjectEntry` and `ActiveLocation` types are gone, and `resume()` restores the stack alone.
+  - **Breaking:** the flat `KeboolaApi` splits in two. `StackApi` (`auth`, `management`, `baseUrl`, `stack`) is what is there before a project; `ProjectApi` is a `StackApi` plus every project namespace. `createKeboola` returns `getStackApi()` — the active stack, re-pointed by `session.stack.select` — and `getProjectApi(projectId)` in place of `getActiveApi` / `getApi`; `createLegacyKeboola(...).api` is a `ProjectApi`.
+  - **Breaking:** `getProjectApi(projectId)` writes and persists nothing, lives as long as the sign-in it was built under, and throws `NotAuthenticated` before one lands. A handle read after its sign-in ended throws `KeboolaError` (`SignInEnded`).
+  - **Breaking:** `auth.getHeadersAsync(projectId)` requires the project, resolved on the active stack. The synchronous `auth.getHeaders` is gone.
+  - **Breaking:** `session.stack.close`, `session.stack.retryContext`, `session.auth.rotate` and the `StackActive` error type are gone. A stack, once opened, stays in the table; `stack.getContextAsync` fetches a failed stack index again.
+  - The persisted session still writes `current.projectId: null` and an empty `projects` per stack, so an older build reading it does not sign out.
+  - **Breaking:** `@keboola/api-client-react` replaces `ApiClientProvider` / `useApiClient` with `StackApiProvider` / `useStackApi` and `ProjectApiProvider` / `useProjectApi`; a `ProjectApiProvider` provides its stack too. `useStack` and `useProject` are gone; `useStackApi().stack` reads the stack.
+  - **Breaking:** `createLegacyKeboola`'s storage build reads the stack index only; it no longer verifies the SAPI token, so a ready session does not mean a live token. Verify it with `api.storage.tokens.verify()` where a dead token must be caught.
+  - **Breaking:** the storage client no longer re-verifies the token after a bucket or feature write, and `isStorageTokenMutatingRequest` is no longer exported; the predicate moved to kbc-ui beside its refresh middleware.
+  - `api.storage` under the bearer flow is live from the sign-in on.
+
+- Data apps list git branches and entrypoints from the app's saved configuration; `syncActions.git` serves only dbt
+  - `apps.getAppGitRepoBranches(appId)` and `apps.getAppGitRepoEntrypoints(appId, { ref? })` call `GET /apps/{appId}/git-repo/branches` and `/entrypoints`. The service reads the saved Git settings and decrypts their credentials, so changes count only once saved.
+  - `syncActions.git.getBranches` takes only dbt component ids and `public`, `password` or `organization` auth (`GitAuth`). `organization` is sent as `authType: organization`, the same key as data apps.
+  - `syncActions.git.getEntrypoints`, the `sshKey` auth, the `GitComponentId` and `DataAppComponentId` types and the `DATA_APP_ENTRYPOINTS` / `DATA_APP_GIT_REPOSITORY` sync actions are gone; `DbtComponentId` names the accepted ids.
+
+- `api.kaiAgent.createChat`, `prepareChat` and `getHistory` accept only `client: 'kbc-ui'`.
+  - A history row's `client` is still typed `'kbc-ui' | 'business-chat' | null`; no row holds `business-chat`.
+  - `getHistory`'s `client` filters nothing: every listed chat is Kai's.
+
+### Minor Changes
+
+- `management.projects.addProjectFeature` returns the API's `warnings` (`ProjectWithFeatureWarnings`), and `ProjectFeature.BigqueryPolicyTags` names the `bigquery-policy-tags` feature.
+
+### Patch Changes
+
+- `AdminFeature.CanManageMaintainers` names the `can-manage-maintainers` admin feature.
+
+- `storageTable` decodes every bucket name the parser accepts into a bucket that serializes back without throwing.
+  - A `c-` or `{branchId}-` prefix is stripped only when the rest is a valid name on its own.
+  - Otherwise the prefix stays in `baseName` — `c-_foo` and `c-` keep their full name as the display name.
+
+- Runtime dependencies require their latest patch and minor releases.
+  - `@keboola/design`: `@rjsf/*` 6.11, `pele` 1.10, `react-resizable-panels` 4.15, `tailwind-merge` 3.7, `vega-lite` 6.5, `@tanstack/react-virtual` 3.14.22, plus patch releases of `dompurify`, `sonner`, `react-day-picker`, `node-diff3` and `@lezer/highlight`.
+  - `@keboola/api-client`: `qs` 6.16.1.
+  - `@keboola/codemirror-lang-sql`: `@lezer/highlight` 1.2.5.
+
+## 49.0.0
+
+### Major Changes
+
+- **Breaking:** `programmaticProjects.confirm` is gone. `confirmByToken(claimToken)` redeems the claim a link carried and `confirmByCookie()` the claim Connection parked in its cookie, both through the OpenAPI client now that the Manage schema carries the endpoint (UT-5890)
+
+### Minor Changes
+
+- `App` carries `hasManagedGitRepo`: whether the app's code lives in a Keboola-managed Git repository.
+
+- `canListSharingTargets(token)` in `@keboola/api-client/domain/permissions`, exposed as `api.context.project.canListSharingTargets`, tells whether the token may call `api.storage.bucketSharing.sharingTargets()` — the `share` role, or organization membership, as Connection's voter decides.
+
+- `Credits` follows the billing spec's corrected `/credits` response (billing-api#225):
+  - `marketplaceSubscription` is a top-level key, not one under `stats`; its `vendor` includes `gcp` and its `billingLink` is `null` for `aws` and `gcp`.
+  - `stats` and its `componentJobs` are always present, and `stats.workspaceJobs` is a list.
+
+- `CreditPurchase` types x402 top-ups: `invoiceTopUpType` may be `'x402'`, and the optional `paymentProvider`, `paymentStatus` (`pending` | `settled` | `expired`) and `externalPaymentId` (the settlement tx hash) describe the payment. `X402_TOP_UP_TYPE` exports the top-up type value, and `X402_PAYMENT_STATUS` and `X402PaymentStatus` the payment-status values.
+
+- `ProjectFeature` in `constants` names every project feature the apps gate on, the new `AdminFeature` names the admin features, and `StackFeature` gains `SandboxesPythonSpark`
+
+- `ManageErrorCode` in `constants` names the Manage API's string error codes the apps classify on, starting with the programmatic-project ones (UT-5890)
+
+- `manageErrorCode(error)` reads the Manage API's string code off an `ApiError`, wherever the backend put it, and `isManageError(error, code)` narrows on one (UT-5890)
+
+- `retryAfterSeconds(error)` reads a failed response's `Retry-After` header off an `ApiError`, for the endpoints that answer 429 or 503 with one (UT-5890)
+
+- `StackFeature` in `constants` names the stack features the apps gate on, the way `ProjectFeature` already names project features (UT-5890)
+
+### Patch Changes
+
+- `resumeApp` wakes the app and clears a failure stop (`disabled`); a stopped app comes back `starting`.
+
+- The bearer session's stack-index fetch gives up after 30 seconds, so a stack that never answers errors its context instead of leaving every caller waiting (UT-5890)
+
 ## 48.0.0
 
 ### Major Changes