@keboola/api-client 29.0.0 → 32.0.0

package/AGENTS.md

@@ -14,7 +14,9 @@ All commands run from monorepo root using `--filter`:
 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
+pnpm --filter @keboola/api-client gen:types --list    # What can be regenerated
+pnpm --filter @keboola/api-client gen:types storage   # One service — leaves the rest alone
+pnpm --filter @keboola/api-client gen:types           # Every API in redocly.yaml
 ```
 
 ## Getting a client
@@ -34,6 +36,8 @@ const { data } = useQuery({
 - **`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`.
 
+**`clients/` also holds clients for third-party APIs the platform talks to directly** (`microsoftGraph` today): a vendor API is still HTTP that must run through the shared fetch client, its middleware chain and its error guards, so it gets a client here rather than a hand-rolled `fetch` in the consuming app. They differ from stack clients in three ways, and a new one should follow the same rules: **never** registered in `createServiceClients.ts` (they are not stack services, so they must not appear on `api.*`), they default their own `baseUrl` (a vendor's host and version prefix are part of its API contract, not something we discover or configure), and they carry no `healthCheck` (we don't own the service's liveness). Consumers construct them directly from the sub-path, like the token-less clients above.
+
 ```ts
 // Storage-only — imports from the /storage sub-path
 import { createStorageClient } from '@keboola/api-client/storage';
@@ -323,7 +327,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) 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.
+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.
 
 ```ts
 import { PermissionDeniedError } from '@keboola/api-client/domain/permissions';
@@ -424,7 +428,7 @@ owns the store, `credential.ts`, `middleware.ts` and `tokenExpiry.ts` — the an
 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
+  is registered in `redocly.yaml`, so `pnpm gen:types developerPortal` 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.
@@ -441,7 +445,9 @@ Three things about it are unusual:
 
 ## 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.
+`@keboola/api-fixtures` provides typed, endpoint-keyed fixtures so tests don't hand-roll response shapes. It covers the storage bootstrap and tables, apps, and the developer portal; extend it as more services need coverage.
+
+**This package's own tests cannot use it** — `api-fixtures` depends on `api-client`, so the reverse edge is a build cycle. Tests here keep hand-rolled bodies; consumers get the fixtures.
 
 ```ts
 import { fixtures, getTable, listTables, tableFixtures } from '@keboola/api-fixtures';
@@ -609,7 +615,7 @@ A new client/namespace means touching four places that must stay in lock-step
 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.
+Full mechanical steps (redocly registration, `gen:types`, file templates) live in [`README.md` → Adding a New OpenAPI Client](./README.md#adding-a-new-openapi-client). Add typed fixtures to `@keboola/api-fixtures` alongside the client so consumers can test against it.
 
 **Worked example — the `auth` client.** `packages/api-client/src/clients/auth/*` (`authClient.ts`, `pkce.ts`, `index.ts`, `types.ts`) is a self-contained new service added this way: it exposes `./auth` + `./auth/types` sub-paths and is surfaced by `src/keboola/createApi.ts`. Read it as the reference shape for a new client rather than copying boilerplate. **Bearer auth lives in `keboola/bearer/`, not the auth client**, since it's specific to the bearer engine: `credential.ts` is a token provider (`getAccessToken({ forceRefresh })` returns a valid token, refreshing — deduped — when near expiry or forced), and `middleware.ts` is a thin policy that on every request asks the credential for a token and stamps the `Authorization` header, and on 401 force-refreshes and replays once. Session-expiry is latched (fire-once, re-armed per session) in `createConfig.notifyExpired`, not the credential — the credential and middleware are long-lived singletons. The middleware holds no token and reads no config — all token state is in the credential, whose `getToken` reads live from `config` so a rotation is picked up without rebuilding. See `keboola/bearer/keboola.ts` for the wiring.
 

package/API-SURFACE.md

@@ -4,7 +4,7 @@
 
 Every namespace and method reachable from a ready `KeboolaApi` — the `api` half of a keboola client (`createKeboola(...).api` / `createLegacyKeboola(...).api`, or `useApiClient()`). Generated from the TypeScript type checker — see `scripts/gen-surface.mjs`.
 
-24 top-level namespaces, 616 methods. This index lists method **names** only — full signatures live per namespace under [`surface/`](./surface). Open `surface/<namespace>.md` for the one you need.
+24 top-level namespaces, 621 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)
 
@@ -80,6 +80,10 @@ Every namespace and method reachable from a ready `KeboolaApi` — the `api` hal
 - `token.introspect`
 - `token.refresh`
 - `token.revoke`
+- `webauthn.getAll`
+- `webauthn.register`
+- `webauthn.registerOptions`
+- `webauthn.remove`
 
 ## [`api.chat`](./surface/chat.md)
 
@@ -174,6 +178,7 @@ Every namespace and method reachable from a ready `KeboolaApi` — the `api` hal
 - `approveToolCall`
 - `createChat`
 - `deleteChat`
+- `downloadSandboxFile`
 - `getAgentSettings`
 - `getChat`
 - `getHistory`
@@ -616,7 +621,7 @@ Every namespace and method reachable from a ready `KeboolaApi` — the `api` hal
 - `triggers.getTriggers`
 - `triggers.updateTrigger`
 - `workspaces.deleteWorkspace`
-- `workspaces.deleteWorkspaceJob`
+- `workspaces.deleteWorkspaceAsync`
 - `workspaces.deleteWorkspaceObjectsAsync`
 - `workspaces.deleteWorkspaces`
 - `workspaces.getWorkspace`