@keboola/api-client 25.0.0 → 29.0.0

package/AGENTS.md

@@ -0,0 +1,623 @@
+# @keboola/api-client
+
+TypeScript SDK wrapping all Keboola platform HTTP APIs with typed clients and middleware.
+
+This file is the **usage** guide — how to get a client, call it, and handle errors. For SDK internals (architecture, middleware authoring, adding a client, type generation) see [Development](#development) at the bottom.
+
+`CLAUDE.md` is a symlink to this file (`AGENTS.md`). Always edit `AGENTS.md`.
+
+## Commands
+
+All commands run from monorepo root using `--filter`:
+
+```bash
+pnpm build --filter=@keboola/api-client     # Build with tsdown (ESM + CJS + .d.ts)
+pnpm test --filter=@keboola/api-client       # Vitest
+pnpm type-check --filter=@keboola/api-client # tsc --noEmit
+pnpm --filter @keboola/api-client gen:types  # Regenerate OpenAPI types from redocly.yaml
+```
+
+## 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.
+
+```ts
+const api = useApiClient();
+const { data } = useQuery({
+  queryKey: storageApiKey.getTable(id),
+  queryFn: ({ signal }) => api.storage.tables.getTable({ branchId, tableId: id }, signal),
+});
+```
+
+**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`.
+
+```ts
+// Storage-only — imports from the /storage sub-path
+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.context.stack; // synchronous — the storage build has resolved
+const buckets = await api.storage.buckets.getBuckets();
+```
+
+## Lifecycle & auth (the stateful client)
+
+Two flow-specific factories back the SDK, and **both return `{ api, session }`**:
+
+- `createKeboola(opts?)` — the **bearer (OAuth)** flow.
+- `createLegacyKeboola(opts?)` — the **legacy (SAPI-token)** flow.
+
+`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).
+
+`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) / `reset()`.
+- legacy: `authenticateStorage(sapiToken)` / `authenticateStorageAsync(sapiToken)` (awaits the build),
+  `authenticateManagement(manageToken)`.
+
+```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)
+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 }
+```
+
+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).
+
+**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:
+
+```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.
+const result = await session.restore();
+```
+
+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).
+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` / `project` / `defaultBranch`). 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.
+
+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/domain/permissions`  | Permission primitives                                            |
+
+## Consumption Hierarchy
+
+When implementing an action that talks to a Keboola API, pick the highest layer that already covers it:
+
+1. **Prefer `sdks/`** — if an SDK exists (e.g. `@keboola/api-client/sdk/tag`), use it. SDKs encapsulate multi-client orchestration so consumers don't re-derive it.
+2. **Fallback to `clients/`** — when no SDK covers the action, compose it from the per-service client methods (e.g. `api.storage.tables.create(...)`).
+
+Never reach below `clients/` to `fetchClient` directly — all HTTP must flow through a typed client factory so middleware and types stay consistent.
+
+## 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:
+
+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:
+
+```ts
+import { createLegacyKeboola } from '@keboola/api-client';
+
+const { api, session } = createLegacyKeboola({ baseUrl });
+await session.authenticateStorageAsync(sapiToken); // → ready
+
+// componentId must be a registered id; `#`-prefixed fields are encrypted before the write.
+const result = await api.sdk.configuration.createConfiguration({
+  componentId: 'keboola.ex-db-mysql',
+  name: 'Orders DB',
+  configuration: {
+    parameters: { db: { host: 'db.example.com', user: 'svc', '#password': 'hunter2' } },
+  },
+});
+// result: { data, runnable, error } — `data` is the created config;
+// `runnable` is false + `error` set when the stored config doesn't satisfy the full schema.
+```
+
+Two boundaries to know before relying on it:
+
+- **Registered components only.** `createConfiguration` looks the id up in the registry and **throws** for an unregistered one (`No configuration registered for component "…"`) — there is no generic pass-through path. The registered set is whatever `registry.ts` lists (DB writers/extractors plus others like `scheduler` and `app-data-gateway`); a component absent from it has no safe typed path yet.
+- **Permission-guarded before any side effect.** `createConfiguration` / `updateConfiguration` call `assertCanCreateConfiguration` / `assertCanUpdateConfiguration` as their first step and throw [`PermissionDeniedError`](#error-handling) for a caller whose token can't write to the target branch — before validation, encryption, or the network. The branch's dev-vs-production mode is derived from the input's `branchId`. You get this for free; only pre-check with the [`domain/permissions`](#permissions) predicates yourself if you want to gate UI _before_ calling.
+
+## Calling the API
+
+**Narrow type imports.** Prefer per-service sub-paths over the barrel — the barrel re-exports everything and inflates autocomplete:
+
+```ts
+// PREFERRED — tree-shakes correctly
+import type { Table, Bucket } from '@keboola/api-client/storage/types';
+import type { DataApp } from '@keboola/api-client/dataScience/types';
+
+// ACCEPTABLE for runtime values / error guards (no type-only equivalent)
+import { isApiError, isAbortError, isFetchClientError } from '@keboola/api-client';
+
+// AVOID for types
+import type { Table } from '@keboola/api-client';
+```
+
+**Always forward `signal`.** Every TanStack Query `queryFn` must forward the provided `signal` to the API call — otherwise inflight requests outlive the component or the query-key change, leaking network activity and potentially writing stale data:
+
+```ts
+useQuery({
+  queryKey: storageApiKey.getTable(id),
+  queryFn: ({ signal }) => api.storage.tables.getTable({ branchId, tableId: id }, signal), // ← forwarded
+});
+```
+
+**Conditional queries** — use `skipToken`, not `enabled: false`, so TypeScript narrows `data` and the query never fires with an `undefined` key:
+
+```ts
+import { skipToken } from '@tanstack/react-query';
+
+queryOptions({
+  queryKey: sandboxesApiKey.getSandbox(id ?? ''),
+  queryFn: !id ? skipToken : async ({ signal }) => api.dataScience.getApp(id, signal),
+});
+```
+
+**Mutations.** Use `useMutation` for writes; invalidate affected queries in `onSuccess`:
+
+```ts
+const queryClient = useQueryClient();
+
+const saveSettings = useMutation({
+  mutationFn: (values: FormValues) =>
+    api.management.projects.setProjectMetadata({ projectId, ...values }),
+  onSuccess: async () => {
+    await queryClient.invalidateQueries({
+      queryKey: managementApiKey.getProjectMetadata(projectId),
+      exact: false, // invalidates all sub-keys too
+    });
+    toast.success('Settings saved.');
+  },
+});
+```
+
+Reach for **optimistic updates** only for frequent, latency-sensitive mutations (e.g. deleting from a long list): `onMutate` snapshots + applies, `onError` rolls back, `onSettled` invalidates. For rare or slow mutations (save, deploy) skip them — just show `isPending`.
+
+## Error handling
+
+Three type guards live in `createFetchClient.ts`, re-exported from `@keboola/api-client`:
+
+| 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`)         |
+| `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.
+
+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       |
+| `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` extends `ApiError`, so check `isManagementClientAuthError` first.
+
+Canonical try/catch — order guards most-specific first:
+
+```ts
+import {
+  isAbortError,
+  isApiError,
+  isFetchClientError,
+  isManagementClientAuthError,
+} 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(err.message); // HTTP error from server
+  if (isFetchClientError(err)) return toast.error('Network problem');
+  throw err; // unexpected — propagate
+}
+```
+
+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.
+- **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).
+
+```ts
+useQuery({
+  queryKey: storageApiKey.getTable(id),
+  queryFn: ({ signal }) => api.storage.tables.getTable({ branchId, tableId: id }, signal),
+  retry: (failureCount, err) => {
+    if (isApiError(err)) return false; // HTTP errors handled per-status above
+    return err instanceof TypeError && failureCount < 3; // retry transport failures only
+  },
+  retryDelay: (attempt) => Math.min(1000 * 2 ** attempt, 30_000), // exponential backoff
+});
+```
+
+Surfacing — toast vs inline:
+
+| Trigger                                     | Surface  | Why                                       |
+| ------------------------------------------- | -------- | ----------------------------------------- |
+| Mutation failure (user-initiated write)     | Toast    | Action-scoped — user just clicked         |
+| Query failure on a page or panel            | Inline   | Page-scoped — the region knows it's empty |
+| 404 in a `useQuery`                         | Empty UI | Not an error                              |
+| `isAbortError` (cancellation, route change) | Silent   | The user caused it                        |
+| Background refetch failure                  | Silent   | Stale data is still useful; log only      |
+
+## Permissions
+
+`@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) and `configurations.ts` (`canCreate/canCopy/canMigrateFromTemplate/canPurge/canAssignFolder` + `assertCan*`, taking a trailing `ctx: ConfigurationCtx`). `storage.ts`, `devBranches.ts`, `sandboxes.ts`, `organization.ts` are still `export {}` placeholders.
+
+```ts
+import { PermissionDeniedError } from '@keboola/api-client/domain/permissions';
+
+try {
+  assertCanCreateConfiguration(token, ctx);
+  await api.storage.configurations.createConfiguration(payload);
+} catch (err) {
+  if (err instanceof PermissionDeniedError) return toast.error(err.reason ?? 'No permission');
+  throw err;
+}
+```
+
+`PermissionDeniedError` shape (stable public contract): `{ action: string; reason?: string; subject?: string }`. `action` is a stable kebab-case id (`assertCanCreateConfiguration` → `'create-configuration'`) consumers may pattern-match on — renames are breaking. `subject` **must not** carry the full `StorageToken`, raw tokens, or secrets.
+
+## 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 : ...`               |
+
+The `fetch()`, `axios`, and legacy `@/api` bans are mechanically enforced by oxlint — see `apps/kbc-ui/oxlint.config.ts`.
+
+## Common Pitfalls
+
+**Trailing slashes in base URLs.** `createFetchRequest` strips trailing slashes via `normalizeBaseUrl` at the `baseUrl + path` join, so `https://connection.keboola.com/` no longer produces a double-slash 404 — every client gets this for free. Clients take the plain stack host as `baseUrl` and put the service prefix in the request path (e.g. `management` calls `/manage/...`), so no client hand-builds a composite base URL. Still pass the canonical form (no trailing `/`) to keep the contract clear.
+
+**Listing tables by bucket.** The Storage API exposes no `GET /buckets/{id}/tables`, and `GET /tables` takes no `bucketId` param. `api.storage.tables.getTables()` returns every table in the project; filter client-side by `table.bucket?.id` or the `{bucketId}.` prefix in `table.id` (IDs use `{bucketId}.{tableName}`, e.g. `in.c-main.users`).
+
+## 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`.
+
+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):
+
+```
+api.storage.*        api.management.*     api.vault.*
+api.queue.*          api.dataScience.*    api.encryption.*
+api.editor.*         api.syncActions.*    api.telemetry.*
+api.queryService.*   api.chat.*           api.ai.*
+api.import.*         api.kaiAgent.*       api.oauth.*
+api.stream.*         api.omnisearch.*     api.apps.*
+api.sdk.tag.*        api.sdk.storage.*
+```
+
+`api.apps` is the data-apps `/v2` App Deployments surface (apps + deployments); `api.dataScience` is the same service's `/v1` surface, which still owns workspaces (`/sandboxes`, `/runtimes`) and the data-app endpoints the UI has not moved off yet.
+
+**`hasService('data-science')` is not the availability check for `api.apps`, and neither is `api.apps.healthCheck()`.** Both clients resolve off that one service id, so `api.apps` is live on every stack that advertises it — while `/v2` itself is implemented only where sandboxes-service serves it (canary at the time of writing). Nothing cheap discriminates: `apps` is absent from the service index on every stack including canary; the `/v2/*` routes are scaffolded everywhere (unauthenticated they 401, so the route exists); and `healthCheck()` answers 200 everywhere because `GET /v2/` falls through to the same root handler as `GET /`, down to an `apiDocs` pointing at the v1 swagger. The one thing that differs is the implementation: off canary, a real call answers `501 {"error":"This endpoint is not implemented yet."}` — measured on three production stacks (AJDA-3140). So gate a data-apps feature on a real call's 501, or on a stack feature flag once one exists.
+
+Clients backing optional stack services (vault, queue, …) throw `ServiceUnavailableError` if absent from the current stack — check `api.context.stack.hasService(...)` before assuming a namespace exists.
+
+**Liveness: every service client exposes a root-level `healthCheck()`** (all but `telemetry`, which has no such endpoint). It resolves with the service's payload when up and throws like any other call when not, and it needs no session — every one of these endpoints answers unauthenticated, so a probe works before login and is indifferent to whether a token rides along. Probe a service that way rather than by calling a real endpoint and interpreting the failure. **A 200 means up and a throw means down — that is the whole contract.** The payload is incidental, so **never hand-roll a response type** to make it look useful. Adding a client means adding its `healthCheck` too, and which client you probe through follows from the spec:
+
+- the service's spec declares the probe path → **probe through the client's own OpenAPI client** (`client.get('/health-check', {}, { signal })`). The return type comes from the spec for free — no type argument, no alias in `types.ts`, and no generic client to construct. Five do today: `ai`, `editor`, `import`, `chat` (which probes `/ping`) and `apps` (which probes `/`, the only unauthenticated root the `/v2` surface declares).
+- it doesn't → fall back to a generic fetch client over the service `baseUrl` and **pass no type argument.** The payload resolves as `unknown`, which is honest: callers only need the 200.
+
+Both clients run the same middleware chain; the OpenAPI one additionally sends auth headers, which is fine — these endpoints answer the same with a valid token, a bogus one, or none.
+
+Don't invent a shape for the second case. These specs are uneven and, where present, often wrong — `vault` declares the path POST-only though a GET answers 200; `metastore` and `queryService` type the body as a bare index signature; `dataScience` and `oauth` declare a service-info shape with no `status` field at all, despite really answering `{"status":"ok"}`. A client moves to a generated type only once its spec matches what the endpoint actually returns, which you confirm by probing it, not by reading the spec.
+
+## Off-session clients: the Developer Portal (apps-api)
+
+`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
+`createServiceClients.ts` and never appears on the `api` proxy — `api.developerPortal` does not exist.
+
+Two layers, as everywhere else in this package:
+
+| Layer      | Subpath                                     | What it is                                                       |
+| ---------- | ------------------------------------------- | ---------------------------------------------------------------- |
+| **SDK**    | `@keboola/api-client/sdk/developerPortal`   | `createDeveloperPortalSdk` → `{ api, session }`. **Start here.** |
+| **Client** | `@keboola/api-client/developerPortal`       | One method per endpoint, no state                                |
+| Types      | `@keboola/api-client/developerPortal/types` | Response and `Input` types                                       |
+
+```ts
+import { createDeveloperPortalSdk } from '@keboola/api-client/sdk/developerPortal';
+import { isMfaChallengeResponse } from '@keboola/api-client/developerPortal';
+import type { App, Vendor } from '@keboola/api-client/developerPortal/types';
+
+const { api, session } = createDeveloperPortalSdk({
+  baseUrl: 'https://apps-api.keboola.com',
+  tokens: readPersistedTokens(),
+  onTokensChange: persistTokens, // the SDK never touches storage
+  onSessionExpired: () => redirectToLogin(),
+});
+```
+
+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: []`.
+
+Three things about it are unusual:
+
+- **Generated from the spec, like every other client.** `https://apps-api.keboola.com/docs/openapi.yaml`
+  is registered in `redocly.yaml`, so `pnpm gen:types` refreshes
+  `developerPortal/__generated__/schema.d.ts` and `types.ts` derives from it. **The spec is the source of
+  truth** — if it is wrong, fix it in `keboola/developer-portal` and regenerate, rather than
+  hand-writing a parallel shape here.
+- **No `Bearer` prefix** — the spec's security schemes are `type: apiKey` and say "passed verbatim", so
+  `createBearerAuthMiddleware` is not reusable and the SDK ships `createDeveloperPortalAuthMiddleware`.
+- **Two fetch clients.** The authenticated one carries the auth middleware, which stamps the **id**
+  token. The other carries none and backs the `security: []` operations plus the four calls that supply
+  their own `Authorization` (`GET /auth/token` takes the refresh token, `POST /auth/logout` the access
+  token, and `/auth/mfa` + `/auth/mfa/confirm` the id token alongside an access token in the **body**).
+  Those four take the token as an argument — the client holds no session — and the SDK binds them from
+  the store, so `api.auth.logout()` needs nothing from the caller. Keeping `/auth/mfa*` off the
+  authenticated client is what keeps them out of refresh-and-replay: restamping a header cannot fix a
+  stale token in a body.
+
+## Testing with `@keboola/api-fixtures`
+
+`@keboola/api-fixtures` provides typed, endpoint-keyed fixtures so tests don't hand-roll response shapes. Early today (storage tables only); extend it as more services need coverage.
+
+```ts
+import { fixtures, getTable, listTables, tableFixtures } from '@keboola/api-fixtures';
+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.
+
+## Authoring types — the generated schema is the source
+
+Every request and response shape starts from `__generated__/schema.d.ts`, never from reading a JSON payload and transcribing it. Derive with the `Openapi*Type` helpers (`OpenapiPathType`, `OpenapiQueryType`, `OpenapiBodyType`, `OpenapiReturnType`, `OpenapiFormDataType`, all from `../../fetchClient`) over an **inlined** `paths['…']['method']`, in the namespace's own `types.ts`:
+
+```ts
+import type { OpenapiBodyType, OpenapiPathType } from '../../../fetchClient';
+import type { paths } from '../__generated__/schema';
+
+export type CreateWidgetPath = OpenapiPathType<paths['/v2/storage/widgets']['post']>;
+export type CreateWidgetSchemaBody = OpenapiBodyType<paths['/v2/storage/widgets']['post']>;
+```
+
+- **Repeat the full `paths['…']` in every type.** Don't introduce an intermediate `type WidgetEndpoint = paths['…']` to shorten them — the whole path is what makes the type greppable against the spec. Group the aliases that share a path together instead.
+- **Never reference `components['schemas'][…]` from a client file.** A cast in `foo.ts` points at a named alias in `foo/types.ts`; the generated namespace is only ever touched by that alias.
+- **Never hardcode what the generator emitted.** `body as Record<string, never>` freezes today's broken spec into our source. Alias it (`OpenapiBodyType<paths[…]>`) and cast to the alias, so the day the spec grows a real body the cast either becomes unnecessary or fails loudly.
+
+### Tighten with a hybrid, don't trust the document
+
+These specs are routinely looser than the API: fields the server requires come through optional and nullable, and free-form objects render as `Record<string, never>`. So derive, then re-tighten the parts we rely on — keeping the enums spec-derived so they can't drift:
+
+```ts
+export type BackendType = NonNullable<CreateWidgetSchemaBody['backend']>;
+
+export type CreateWidgetBody = Omit<CreateWidgetSchemaBody, 'backend' | 'size'> & {
+  backend: BackendType; // required in practice, optional in the spec
+  size: number;
+};
+```
+
+The hybrid is the default because it fails in the right direction — new spec fields arrive for free, while the constraints we actually depend on stay enforced. Note in a comment _which_ fields you tightened and why, since the next reader will otherwise "fix" it back to the spec.
+
+Where the spec is outright wrong or stubs the operation (`content?: never` on the success response, a `Record<string, never>` body), keep the hand-authored type and bridge with **`as`** at the call site. That is the sanctioned use of `as` in this package — it records a known spec defect at one line rather than spreading a wrong type through consumers. Prefer a single `as`; reach for `as unknown as` only when TypeScript refuses the direct conversion.
+
+### The `*Input` pattern
+
+A public method takes **one** object. Compose it from the path and body aliases rather than spelling an intersection at the signature:
+
+```ts
+export type CreateWidgetInput = CreateWidgetPath & CreateWidgetBody;
+
+const createWidget = async ({ widgetId, branchId, ...body }: CreateWidgetInput) => { … };
+```
+
+Name them `<Verb><Entity>Path` / `…Query` / `…Body` / `…Input`, with `…SchemaBody` / `…SchemaQuery` reserved for the raw spec-derived alias when a tightened sibling shares the name. Because `Input` is built from the spec's `Path`, path parameters keep the spec's own names (`configurationId`, not a local `configId`) — that keeps a call site diffable against the endpoint it hits.
+
+### A method that returns a job ends in `Async`
+
+If the resolved value is a `Job` — the request only _enqueues_ the work — the method name **must** end in `Async`: `deleteBucketAsync`, `importAsync`, `createSnapshotAsync`. Never `*Job` (that names the return type, not what the call does) and never a bare verb, which reads like the work is finished when the promise resolves.
+
+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.
+
+```ts
+const deleteBucketAsync = async (…): Promise<Job<'bucketDelete'>> => { … }; // enqueues
+const getBucket = async (…): Promise<BucketDetail> => { … }; //                done on resolve
+```
+
+One shape needs a judgement call: an endpoint that answers _either_ the resource or a job depending on a parameter (`createAliasTable` → `Table | CreateAliasJob`). Prefer splitting it into a sync method and an `*Async` sibling; where that isn't worth it, leave the bare name and say so in a comment, because a caller that must branch on the response can't be told anything useful by the name alone.
+
+### A method that waits for its job ends in `AndWait`
+
+The sibling of an `*Async` method that also waits for the enqueued job to finish ends in `AndWait`: `createTableAndWait`, `importAndWait`, `unshareBucketAndWait`. It lives on the client, next to the `*Async` it mirrors.
+
+| What the call does                               | Name shape | Example                     |
+| ------------------------------------------------ | ---------- | --------------------------- |
+| returns the finished resource in one request     | bare verb  | `getBucket`, `deleteBucket` |
+| enqueues the work and hands back a `Job` to poll | `*Async`   | `createTableAsync`          |
+| enqueues the work and polls it to completion     | `*AndWait` | `createTableAndWait`        |
+
+- **Never a bare verb.** `buckets.deleteBucket` is a real single-request endpoint sitting next to `deleteBucketAsync`, so a bare name would mean "one request" on one resource and "poll loop" on the next.
+- **Never `Sync`.** In JavaScript that suffix promises no yielding (`readFileSync`); this is the method that yields most.
+- **Never a `{ wait: true }` option.** Both branches return `Job` — the same TS type — so nothing discriminates work that is merely enqueued from work that is done, and the name is the only signal a call site gets.
+- **Never `AndPoll`.** That names the transport, not the contract. A route that later grows long-poll or SSE turns every `AndPoll` into a lie.
+
+It is a suffix, not a prefix, because a suffix means "same endpoint, different completion contract" — the variant shares its sibling's prefix and so sorts beside it in autocomplete, where a `waitForTableCreate` would sort nowhere near `createTableAsync`.
+
+Storage's wait helpers currently live in `sdks/storage` under bare-verb names (`createTable`); the clients are where new ones belong.
+
+**What an `*AndWait` resolves with is not settled** — the job, its `results`, and whether a failed job throws are all open. Don't document a return contract until it is decided.
+
+## Extending the SDK (endpoint not in the client yet)
+
+When a backend endpoint you need has no method on any client, the sanctioned path is to **add it to `@keboola/api-client` first, then consume it** — never drop to `fetch()` in the app. A one-off `fetch()` skips the middleware chain (storage-token, auth, retry, logging), the typed error guards, and `signal` forwarding, and it can't be mocked with `@keboola/api-fixtures`. The [What NOT to Do](#what-not-to-do) `fetch()` ban is enforced by oxlint precisely so this stays the only route.
+
+Decision:
+
+| Situation                                              | Do this                                                                       |
+| ------------------------------------------------------ | ----------------------------------------------------------------------------- |
+| Endpoint belongs to an existing service (`storage`, …) | Add the method to that client; cover it with an `@keboola/api-fixtures` entry |
+| Endpoint belongs to a brand-new service                | Add a new client/namespace under `src/clients/<x>/`, then wire its sub-path   |
+| Multi-client orchestration, or any session/token state | Add (or extend) an `sdks/` SDK that composes the clients                      |
+
+### Eight rules for a new client or SDK
+
+Every one of these was a round of review on a single PR (#7953). They are not style
+preferences — each cost a rewrite. Work them in order; the first three decide the shape of
+everything after.
+
+**1. Find the spec before you write a single type.** Probe the service directly —
+`/docs/openapi.yaml`, `/docs/swagger.yaml`, `/openapi.json`, `/api/docs` — and only then conclude
+there isn't one. A README, a wiki page or an Apiary link is not evidence of absence. A
+hand-written client on a service that turned out to publish a spec is a full rewrite, and the
+generated types immediately found 15 wrong path placeholders, a `healthCheck` on the wrong
+endpoint, and 12 operations that had simply been missed.
+
+**2. The spec is the source of truth, including where it is wrong.** When it disagrees with
+production, **fix it in the service's repo** — do not carry a corrected shape here. Overlays look
+cheap and are not: they force an `as` cast at every call site (23 of them, in that PR), and they
+silently absorb the real bugs the generated types would have caught. Verify the divergence against
+production **and** against the handler that builds the response before claiming it, then open the
+backend PR. To prove a spec fix before it deploys: run `openapi-typescript` over the fixed file and
+`oxfmt` the result, having first round-tripped the _live_ spec the same way and reproduced the
+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
+`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.
+
+**4. Naming — read [`API-SURFACE.md`](./API-SURFACE.md) before inventing a shape.**
+
+- **`get*`, never `list*`.** 180 methods start with `get`, 7 with `list`, and those 7 are strays.
+  A collection read is the plural noun: `getBuckets`, `getDeletedProjects`, `getAllFeatures`.
+  `delete*` (62) over `remove*` (11), except when unlinking a relation rather than destroying a row.
+- **One level of sub-namespace, and the method carries the noun** — `buckets.getBucket`,
+  `currentUser.getProjectInvitations`. Not `buckets.get`, and not `admin.apps.get`. If a namespace
+  is growing a second level, add a sibling namespace instead. (`auth.mfa.totp.*` is the one
+  exception in the package; don't copy it.)
+- Query and input types follow their method: `GetAppsQuery`, not `ListAppsQuery`.
+
+**5. Never send a credential to an endpoint the spec marks `security: []`.** Those responses are
+public and cacheable; a token on one buys nothing and leaks into any shared cache in front of it.
+When the spec splits its operations, build **two fetch clients** — one carrying the auth
+middleware, one carrying none — and put each endpoint on the side the spec says.
+
+**6. Test the logic, not the transport.** A test asserting that a method called its URL, or
+substituted its path parameters, tests the generated client and the mock server. Delete it. Test
+where a decision lives: which credential an endpoint gets, refresh-and-replay, dedupe, what happens
+when the session is cleared mid-rotation. If the generated `paths` type already makes a mistake a
+compile error, a runtime assertion of the same thing proves nothing.
+
+**7. Comment what the code cannot say, and nothing else.** Package median is **9%** of lines,
+p90 32%; `vaultClient.ts` and `queueClient.ts` are at 0%. Past ~20% you are narrating the code. Keep
+the comment that explains why sign-out has to win a race against an in-flight rotation; delete the
+one that says a method issues a GET.
+
+**8. Read your own diff before pushing.** `git add -A` swallows build output when a `.gitignore`
+is not on the branch you switched to. Stage explicit paths, and check the pushed file list against
+the GitHub API rather than trusting the local working tree.
+
+A new client/namespace means touching four places that must stay in lock-step — **guarded by the [`subpathExportParity` test](./src/subpathExportParity.test.ts)**, so forgetting one fails CI instead of silently breaking resolution:
+
+1. `tsdown.config.ts` — add `<x>/index` and (if you ship a `types.ts`) `<x>/types` build entries
+2. `package.json` `exports` — add `./<x>` and `./<x>/types`
+3. `package.json` `typesVersions` — add `<x>` and `<x>/types`
+4. `src/keboola/createServiceClients.ts` — register the client in the registry with `.add({ serviceId, clientName, clientFn })` (+ `src/keboola/createMiddlewareFor.ts` for its `ServiceClientName` entry and any bespoke middleware)
+
+Full mechanical steps (redocly registration, `pnpm 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.
+
+## Development
+
+SDK internals — layered architecture, middleware authoring, adding a new client, OpenAPI type generation, `redocly.yaml`, ownership/versioning — live in the package docs, not here:
+
+- [`README.md` → Architecture](./README.md#architecture), [Middleware](./README.md#middleware), [Service Clients](./README.md#service-clients), [Utilities](./README.md#utilities)
+- [`README.md` → Contributing](./README.md#contributing) — adding an OpenAPI/generic client, type generation, `redocly.yaml`
+- [`README.md` → Ownership](./README.md#ownership) — UI team, npm Trusted Publisher, Changesets
+- [`docs/regenerate-api-types.md`](./docs/regenerate-api-types.md) — regenerating types from a local backend