@keboola/api-client 27.0.0 → 31.0.0

package/AGENTS.md

@@ -11,7 +11,7 @@ This file is the **usage** guide — how to get a client, call it, and handle er
 All commands run from monorepo root using `--filter`:
 
 ```bash
-pnpm build --filter=@keboola/api-client     # Build with tsup (ESM + CJS + .d.ts)
+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
@@ -137,14 +137,15 @@ genuinely secure option — keeping the refresh token out of JS entirely behind
 
 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/configurations` | Core configuration SDK                                           |
-| `@keboola/api-client/domain/permissions` | Permission primitives                                            |
+| 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
 
@@ -387,6 +388,57 @@ Both clients run the same middleware chain; the OpenAPI one additionally sends a
 
 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.
@@ -456,6 +508,27 @@ const getBucket = async (…): Promise<BucketDetail> => { … }; //
 
 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.
@@ -466,11 +539,72 @@ Decision:
 | ------------------------------------------------------ | ----------------------------------------------------------------------------- |
 | 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                             | Add (or extend) an `sdks/` SDK that composes the clients                      |
+| 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. `tsup.config.ts` — add `<x>/index` and (if you ship a `types.ts`) `<x>/types` build entries
+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)

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, 609 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`
@@ -387,6 +392,7 @@ Every namespace and method reachable from a ready `KeboolaApi` — the `api` hal
 - `getQueryJob`
 - `getQueryResults`
 - `healthCheck`
+- `poller`
 
 ## [`api.queue`](./surface/queue.md)
 
@@ -395,6 +401,7 @@ Every namespace and method reachable from a ready `KeboolaApi` — the `api` hal
 - `getOrchestrationRerunPlan`
 - `healthCheck`
 - `killJob`
+- `poller`
 - `searchAllJobs`
 - `searchGroupedJobs`
 - `searchJobs`
@@ -468,7 +475,9 @@ Every namespace and method reachable from a ready `KeboolaApi` — the `api` hal
 
 ## [`api.storage`](./surface/storage.md)
 
+- `branches.createDevBranchAndWait`
 - `branches.createDevBranchAsync`
+- `branches.deleteDevBranchAndWait`
 - `branches.deleteDevBranchAsync`
 - `branches.deleteDevBranchMetadata`
 - `branches.getDevBranchMetadata`
@@ -541,6 +550,7 @@ Every namespace and method reachable from a ready `KeboolaApi` — the `api` hal
 - `configurations.purgeConfiguration`
 - `configurations.purgeConfigurations`
 - `configurations.rebaseConfiguration`
+- `configurations.rebaseConfigurationToDeleted`
 - `configurations.resetConfigurationToDefault`
 - `configurations.restoreConfiguration`
 - `configurations.searchComponentConfigurations`
@@ -572,6 +582,7 @@ Every namespace and method reachable from a ready `KeboolaApi` — the `api` hal
 - `mergeRequests.requestChangesMergeRequest`
 - `mergeRequests.requestReview`
 - `mergeRequests.updateMergeRequest`
+- `poller`
 - `search.globalSearch`
 - `search.searchTables`
 - `snapshots.createSnapshotAsync`
@@ -599,6 +610,7 @@ Every namespace and method reachable from a ready `KeboolaApi` — the `api` hal
 - `tables.updateTableDefinition`
 - `tokens.createToken`
 - `tokens.deleteToken`
+- `tokens.getTokenEvents`
 - `tokens.getTokens`
 - `tokens.refresh`
 - `tokens.shareToken`