@keboola/api-client 45.0.0 → 47.0.0

package/AGENTS.md

@@ -157,8 +157,8 @@ Three things follow from that, worth knowing before you hold one:
   the sign-in stands. **The refresh is the only oracle** — the server refusing the refresh token is
   the one unambiguous report of a dead credential, and that is where the sign-out happens
   (`rotateOnce` in `credentials.ts`). A cookie credential's refresh is the same oracle: the server
-  refusing its session signs it out. A static token cannot refresh, so it never signs itself out; a
-  401 on it surfaces to the caller.
+  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.
@@ -206,14 +206,15 @@ Every credential change (login, project switch, token rotation, sign-out) is wri
 fixed key, and what it holds is the whole table rather than a single session: `current` — the scoped
 stack and project — plus a `stacks` array, each entry carrying its own credential and the projects
 open under it. Only the durable part of a credential is written: a token credential's rotating
-refresh token, a static one's token, and a cookie one's session id, which renews nothing without the
-HttpOnly session cookie the browser keeps. An access token or user identity is never written.
+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 picked at construction.** `createKeboola({ defaultBaseUrl, credentials: 'cookie' })` signs in with
-browser-mode logins (`login.withPassword({ …, browserMode: true })`) and renews through
-`token.refreshWithSession` — the refresh token never reaches JS. It only works from the stack's own
-origin, so localhost and previews stay on the default `'token'`. `authenticate` refuses the other
-rotating kind, and a restore ignores a stored one.
+**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`
+credential it renews through `token.refreshWithSession`, so the refresh token never reaches JS. That
+works only from the stack's own origin, so localhost and previews log in in API mode and hold a
+`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,
@@ -609,6 +610,54 @@ 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 query parameter that changes the result type (`include`, `exclude`)
+
+Some reads let the caller pick what comes back: `include=metadata,columns` adds keys to each item, `exclude=componentDetails` swaps a field for a thinner shape. The spec types the parameter as `string` and every conditional key as optional, so a derived return says "maybe" about all of them. Type the method from the literal it is called with instead — `getBuckets({ branchId, include: ['metadata'] })` resolves with `metadata` required, `getBuckets({ branchId })` leaves it optional. Three helpers in `fetchClient/types.ts` carry it; each endpoint declares in its `types.ts` what its values mean:
+
+```ts
+// buckets/types.ts
+/** What each `include` value adds to a listed bucket (see `IncludeMap`). */
+export type BucketIncludes = {
+  attributes: 'attributes';
+  metadata: 'metadata';
+  linkedBuckets: []; // adds `linkedBy` only to a bucket something links to, so it stays optional
+};
+
+export type BucketInclude = keyof BucketIncludes;
+
+export type GetBucketsQuery<I extends readonly BucketInclude[] = BucketInclude[]> =
+  OpenapiIncludeQueryType<paths['/v2/storage/branch/{branchId}/buckets']['get'], I>;
+export type GetBucketsInput<I extends readonly BucketInclude[] = BucketInclude[]> = GetBucketsPath &
+  GetBucketsQuery<I>;
+export type BucketWith<I extends readonly BucketInclude[]> = WithIncludes<
+  Bucket,
+  BucketIncludes,
+  I
+>;
+
+// buckets/buckets.ts
+const getBuckets = async <const I extends readonly BucketInclude[] = []>(
+  { branchId, ...query }: GetBucketsInput<I>,
+  signal?: AbortSignal,
+) => {
+  const { data } = await openApiClient.get(
+    '/v2/storage/branch/{branchId}/buckets',
+    { path: { branchId }, query: query as GetBucketsSchemaQuery },
+    { signal, queryArrayFormat: 'comma' },
+  );
+
+  return data as unknown as BucketWith<I>[];
+};
+```
+
+- **`OpenapiIncludeQueryType<Op, I>` is the query.** It is the operation's own query with `include` swapped for the tuple, so paging and filters stay spec-derived and the key name cannot drift. Tighten a wrong sibling param on top of it (`Omit<…, 'isDeleted'> & { isDeleted?: boolean }`), never by retyping the whole query.
+- **The map is the contract, and it is checked.** `WithIncludes` constrains the map to `IncludeMap<T>`: every value must be a dotted path that exists on `T` (three segments deep, array hops implicit), so a typo is a type error at the `With…` alias. `[]` marks a value that only sometimes adds a key, so it stays optional. Verify each value against Connection's action, not the spec's description.
+- **`const I`, default `[]`.** `const` keeps the tuple literal. `[]` means "nothing sent", so with no `include` every conditional key stays optional. A widened `BucketInclude[]` from a variable is not a tuple, and `WithIncludes` then returns the base type. Server-side defaults (a list that answers `name,description` with no `include`) are not modelled.
+- **Both casts are required.** The spec's query has `include?: string`, so the tuple goes out as `query as Get…SchemaQuery`. The return needs `as unknown as …With<I>[]`: a type with keys made required or removed does not overlap the spec's all-optional shape, so a single `as` is refused. A detail read that joins `include` itself (`include?.join(',')`, `getBucket`) sends a plain string and needs no query cast. Together with the spec-defect bridge above, these are the sanctioned uses of `as` in this package.
+- **`exclude` reshapes, so it is a patch map.** `WithExcludes<T, Map, E>` takes `ExcludeMap<T>`: each value is a patch over `T` where a key replaces that field's type and `never` removes it. `StackInfoExcludes` maps `componentDetails` to `{ components: StackComponent[] }` and `components` to `{ components: never }`; `undefined` returns `T`. The query is `OpenapiExcludeQueryType<Op, E>`, the method takes the same `const E` generic and the same cast.
+- **Never** a `getXWithY` sibling method, a hand-typed `include?: 'foo'[]` without a map, or a conditional key made required on the base type.
+- **Where a `*.types.test.ts` already asserts on such a method, use an instantiation expression**, never a call (the root rules forbid new type-only tests): `expectTypeOf(storage.getStackInfo<'componentDetails'>).returns.resolves.toEqualTypeOf<…>()`. A call fires a real request, which MSW rejects as an unhandled error.
+
 ### 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.
@@ -624,26 +673,42 @@ 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`
+### A method that hands back the poller for its job ends in `Poller`
 
-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.
+The sibling of an `*Async` method that hands back the poller for the enqueued job ends in `Poller`: `createTablePoller`, `importPoller`, `unshareBucketPoller`. 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`        |
+| 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`           |
+| hands back the poller for the enqueue            | `*Poller`  | `createTablePoller`          |
+| runs a batch to completion and reports it        | `*AndWait` | `purgeConfigurationsAndWait` |
 
 - **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 `AndWait` for a poller.** The method waits for nothing; the poller it returns does, once started. `AndWait` is for a method that itself awaits the work and resolves what it reports, like the chunked batch purge and restore.
 - **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`.
+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 Azure's `beginCreateTable` would sort nowhere near `createTableAsync`.
+
+**A `*Poller` returns the job's `Poller`**, handed the enqueue as `init`, so the handle exists before any request is sent. It is lazy: nothing runs until `start()` or `wait()`. `start()` resolves the `PollResult`; `wait()` resolves the succeeded job or throws, the poll's failure, a refused enqueue or the job's `StorageJobError`; `subscribe` and `stop` let a caller watch or cancel the wait. `start()` still resolves a job that ended `error`, for a caller that reads partial results off it.
+
+### A paginated collection has a page method and a `getAll*` sibling
 
-Storage's wait helpers currently live in `sdks/storage` under bare-verb names (`createTable`); the clients are where new ones belong.
+Connection's newer collections are cursor-paginated: a `data` / `meta` / `links` envelope,
+`page[limit]` / `page[after]` and `filter[...]` query objects, `links.next` null on the last page
+(connection's `docs/guidelines/.../paginated-collections.md`; `/manage/deleted-projects`,
+`/v1/auth/me/*`). Older ones are offset-paginated (`limit` / `offset`). Both get the same two
+methods:
 
-**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.
+- **The page method is the bare plural** (`getProjects(query, signal)`) and returns the envelope
+  untouched. A consumer that renders one page at a time pages with it, reading the next cursor
+  off `links.next` with `nextCursorOf` — never rebuilding it from the last row, since the encoding
+  is the server's.
+- **The all-pages sibling is `getAll<Noun>(signal)`** (`auth.me.getAllProjects`), built on
+  `collectByCursor` or `collectByOffset` from `utils/async`. It owns the page size as a client
+  constant set to the server's maximum, and exists only where a consumer needs the whole
+  collection. An app never walks pages itself; the walk, the cursor parsing and the page limit
+  live here.
 
 ## Extending the SDK (endpoint not in the client yet)
 

package/API-SURFACE.md

@@ -4,7 +4,7 @@
 
 Every namespace and method reachable from a ready `KeboolaApi` — the `api` half of a keboola client (`createKeboola(...).api` / `createLegacyKeboola(...).api`, or `useApiClient()`). Generated from the TypeScript type checker — see `scripts/gen-surface.mjs`.
 
-25 top-level namespaces, 708 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, 725 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)
 
@@ -60,6 +60,8 @@ Every namespace and method reachable from a ready `KeboolaApi` — the `api` hal
 - `manageTokens.getAll`
 - `manageTokens.revoke`
 - `me.get`
+- `me.getAllOrganizations`
+- `me.getAllProjects`
 - `me.getMaintainers`
 - `me.getOrganizations`
 - `me.getProjects`
@@ -116,6 +118,12 @@ Every namespace and method reachable from a ready `KeboolaApi` — the `api` hal
 - `updateAgentSettings`
 - `updateUserAgentSettings`
 
+## [`api.componentsMcp`](./surface/componentsMcp.md)
+
+- `getConnectors`
+- `healthCheck`
+- `setConnectorCredentials`
+
 ## [`api.context`](./surface/context.md)
 
 - `defaultBranch.getType`
@@ -355,9 +363,11 @@ Every namespace and method reachable from a ready `KeboolaApi` — the `api` hal
 - `snowflakePartnerConnect.check`
 - `snowflakePartnerConnect.unlock`
 - `storageBackends.activateStorageBackend`
+- `storageBackends.createBigqueryServerSideStorageBackend`
 - `storageBackends.createBigqueryStorageBackend`
 - `storageBackends.createSnowflakeStorageBackend`
 - `storageBackends.deleteStorageBackend`
+- `storageBackends.getPolicyTagEnablementGuide`
 - `storageBackends.getStorageBackend`
 - `storageBackends.getStorageBackendMaintainers`
 - `storageBackends.getStorageBackendProjects`
@@ -424,6 +434,7 @@ Every namespace and method reachable from a ready `KeboolaApi` — the `api` hal
 - `deleteCredential`
 - `getCredential`
 - `getCredentials`
+- `getOrganizationConnections`
 - `healthCheck`
 
 ## [`api.omnisearch`](./surface/omnisearch.md)
@@ -497,27 +508,6 @@ Every namespace and method reachable from a ready `KeboolaApi` — the `api` hal
 - `semanticLayer.updateModel`
 - `semanticLayer.updateObject`
 - `semanticLayer.withdrawScopeElevationRequest`
-- `storage.addTableColumn`
-- `storage.createBucketListing`
-- `storage.createSnapshot`
-- `storage.createTable`
-- `storage.createTableDefinition`
-- `storage.createTablePrimaryKey`
-- `storage.deleteBucketListing`
-- `storage.deleteTableColumn`
-- `storage.exportToFile`
-- `storage.forceUnlinkBucket`
-- `storage.importFromFile`
-- `storage.pullTable`
-- `storage.refreshExternalBucket`
-- `storage.registerBucket`
-- `storage.removeTablePrimaryKey`
-- `storage.shareBucketToOrganization`
-- `storage.shareBucketToOrganizationProject`
-- `storage.shareBucketToProjects`
-- `storage.shareBucketToUsers`
-- `storage.unshareBucket`
-- `storage.updateBucketListing`
 - `tag.assignTags`
 - `tag.createAndAssignTag`
 - `tag.createTag`
@@ -536,11 +526,11 @@ Every namespace and method reachable from a ready `KeboolaApi` — the `api` hal
 
 ## [`api.storage`](./surface/storage.md)
 
-- `branches.createDevBranchAndWait`
 - `branches.createDevBranchAsync`
-- `branches.deleteDevBranchAndWait`
+- `branches.createDevBranchPoller`
 - `branches.deleteDevBranchAsync`
 - `branches.deleteDevBranchMetadata`
+- `branches.deleteDevBranchPoller`
 - `branches.getDevBranchMetadata`
 - `branches.getDevBranches`
 - `branches.saveDevBranchMetadata`
@@ -549,24 +539,38 @@ Every namespace and method reachable from a ready `KeboolaApi` — the `api` hal
 - `bucketExternal.deleteScheduledTask`
 - `bucketExternal.getBucketRegistrationGuide`
 - `bucketExternal.refreshExternalBucketAsync`
+- `bucketExternal.refreshExternalBucketPoller`
 - `bucketExternal.registerBucketAsync`
+- `bucketExternal.registerBucketPoller`
 - `bucketListings.createListingAsync`
+- `bucketListings.createListingPoller`
 - `bucketListings.deleteListingAsync`
+- `bucketListings.deleteListingPoller`
 - `bucketListings.getListing`
+- `bucketListings.getListingSubscriptions`
 - `bucketListings.getListings`
 - `bucketListings.updateListingAsync`
+- `bucketListings.updateListingPoller`
 - `bucketSharing.forceUnlinkBucketAsync`
+- `bucketSharing.forceUnlinkBucketPoller`
 - `bucketSharing.linkBucketAsync`
+- `bucketSharing.linkBucketPoller`
 - `bucketSharing.shareBucketToOrganizationAsync`
+- `bucketSharing.shareBucketToOrganizationPoller`
 - `bucketSharing.shareBucketToOrganizationProjectAsync`
+- `bucketSharing.shareBucketToOrganizationProjectPoller`
 - `bucketSharing.shareBucketToProjectsAsync`
+- `bucketSharing.shareBucketToProjectsPoller`
 - `bucketSharing.shareBucketToUsersAsync`
+- `bucketSharing.shareBucketToUsersPoller`
 - `bucketSharing.sharedBuckets`
 - `bucketSharing.unshareBucketAsync`
+- `bucketSharing.unshareBucketPoller`
 - `buckets.createBucket`
 - `buckets.deleteBucket`
 - `buckets.deleteBucketAsync`
 - `buckets.deleteBucketMetadata`
+- `buckets.deleteBucketPoller`
 - `buckets.getBucket`
 - `buckets.getBucketOwner`
 - `buckets.getBuckets`
@@ -574,10 +578,14 @@ Every namespace and method reachable from a ready `KeboolaApi` — the `api` hal
 - `buckets.updateBucket`
 - `buckets.updateBucketOwner`
 - `columns.addTableColumnAsync`
+- `columns.addTableColumnPoller`
 - `columns.createTablePrimaryKeyAsync`
+- `columns.createTablePrimaryKeyPoller`
 - `columns.deleteColumnMetadata`
 - `columns.deleteTableColumnAsync`
+- `columns.deleteTableColumnPoller`
 - `columns.removeTablePrimaryKeyAsync`
+- `columns.removeTablePrimaryKeyPoller`
 - `columns.saveColumnMetadata`
 - `components.getComponent`
 - `components.getComponents`
@@ -600,7 +608,8 @@ Every namespace and method reachable from a ready `KeboolaApi` — the `api` hal
 - `configurationVersions.rollbackConfigurationRowToVersion`
 - `configurationVersions.rollbackConfigurationToVersion`
 - `configurationWorkspaces.createConfigurationWorkspace`
-- `configurationWorkspaces.createConfigurationWorkspaceJob`
+- `configurationWorkspaces.createConfigurationWorkspaceAsync`
+- `configurationWorkspaces.createConfigurationWorkspacePoller`
 - `configurationWorkspaces.getConfigurationWorkspaces`
 - `configurations.createConfiguration`
 - `configurations.deleteConfiguration`
@@ -640,9 +649,9 @@ Every namespace and method reachable from a ready `KeboolaApi` — the `api` hal
 - `mergeRequests.createMergeRequest`
 - `mergeRequests.getMergeRequest`
 - `mergeRequests.getMergeRequestConflicts`
-- `mergeRequests.getMergeRequestWithActivityLog`
 - `mergeRequests.getMergeRequests`
-- `mergeRequests.mergeMergeRequest`
+- `mergeRequests.mergeMergeRequestAsync`
+- `mergeRequests.mergeMergeRequestPoller`
 - `mergeRequests.requestChangesMergeRequest`
 - `mergeRequests.requestReview`
 - `mergeRequests.updateMergeRequest`
@@ -650,28 +659,37 @@ Every namespace and method reachable from a ready `KeboolaApi` — the `api` hal
 - `search.globalSearch`
 - `search.searchTables`
 - `snapshots.createSnapshotAsync`
+- `snapshots.createSnapshotPoller`
 - `snapshots.deleteSnapshotAsync`
+- `snapshots.deleteSnapshotPoller`
 - `snapshots.getSnapshot`
 - `snapshots.getTableSnapshots`
 - `stats.getRunIdStats`
 - `tables.createAliasTable`
 - `tables.createTableAsync`
 - `tables.createTableDefinitionAsync`
+- `tables.createTableDefinitionPoller`
+- `tables.createTablePoller`
 - `tables.deleteTable`
 - `tables.deleteTableMetadata`
-- `tables.deleteTableRows`
+- `tables.deleteTableRowsAsync`
+- `tables.deleteTableRowsPoller`
 - `tables.deleteTables`
 - `tables.exportAsync`
+- `tables.exportPoller`
 - `tables.getDataPreview`
 - `tables.getTable`
 - `tables.getTables`
 - `tables.importAsync`
+- `tables.importPoller`
 - `tables.pullTableAsync`
+- `tables.pullTablePoller`
 - `tables.removeAliasTableFilter`
 - `tables.saveTableMetadata`
 - `tables.setAliasTableFilter`
 - `tables.updateTable`
-- `tables.updateTableDefinition`
+- `tables.updateTableDefinitionAsync`
+- `tables.updateTableDefinitionPoller`
 - `tokens.createToken`
 - `tokens.deleteToken`
 - `tokens.getTokenEvents`
@@ -687,6 +705,8 @@ Every namespace and method reachable from a ready `KeboolaApi` — the `api` hal
 - `workspaces.deleteWorkspace`
 - `workspaces.deleteWorkspaceAsync`
 - `workspaces.deleteWorkspaceObjectsAsync`
+- `workspaces.deleteWorkspaceObjectsPoller`
+- `workspaces.deleteWorkspacePoller`
 - `workspaces.deleteWorkspaces`
 - `workspaces.getWorkspace`
 - `workspaces.getWorkspaceObjects`

package/CHANGELOG.md

@@ -1,5 +1,74 @@
 # @keboola/api-client
 
+## 47.0.0
+
+### Major Changes
+
+- `collectByCursor` walks a cursor-paginated collection (`data` / `meta` / `links` envelope) to the end by following `links.next`; `nextCursorOf` reads the `page[after]` cursor off such a link. `auth.me.getAllOrganizations` and `auth.me.getAllProjects` use it to return the caller's full collections behind the `/v1/auth/me` previews.
+  - **Breaking:** `collect` is renamed `collectByOffset`. Replace the import; the options and behaviour are unchanged.
+
+- - **Breaking:** the `static` credential kind is removed. A bearer session holds a `token` or a `cookie` credential, both of which renew; a persisted session carries only the grant that restores it, never an access token.
+  - A persisted credential of a kind the build does not know restores that stack signed out instead of discarding the whole stored session.
+  - **Breaking:** `BearerCredentialEntry` is renamed `CredentialEntry` and `CredentialMode` is renamed `CredentialType`; a bearer is the only kind there is, and the type is the credential's own `type`.
+
+- The bearer client renews whichever rotating credential it holds: a `token` credential by its refresh token, a `cookie` credential by its session id. One client signs in with either kind, and a persisted grant of either kind is restored through its own channel.
+  - **Breaking:** `KeboolaOptions.credentials` is removed; there is no client-wide credential mode. Drop the option.
+  - **Breaking:** `session.auth.adoptInjected` is removed; call `session.auth.replace` with the injected credential.
+  - **Breaking:** `KeboolaErrorType.CredentialKindMismatch` is removed; nothing throws it.
+
+- Every storage method that enqueues a job has an `*Poller` twin that waits for it, in the shape `branches.createDevBranchPoller` already had: it takes the same input plus `StorageJobPollOptions` and returns the job's `Poller`, lazy until `start()` or `wait()`: `start()` resolves the `PollResult`, `wait()` the succeeded job (throws the poll's failure when the wait did not finish, a refused enqueue included, and `StorageJobError` when the job ended `error`), `subscribe` watches it, `stop` cancels it. A client `poller` takes one options object, `{ init, interval, … }`, where `init` is the job or the enqueue that yields it. The `branches` pair returns the same. `storage.poller` stays, as the one wait on a job the `*Poller` methods are built on, the same way `queue.poller` and `queryService.poller` are. `tableSnapshotDelete` and `devBranchMerge` join `JobOperation`, and the `aliasCreate` job's `results` is the alias `Table`, as the backend returns it.
+  - **Breaking:** `createStorageSdk` and `sdk.storage` are removed; they only wrapped the poller. Each method maps onto a client `*Poller` (`sdk.storage.createTableDefinition` → `storage.tables.createTableDefinitionPoller`, `sdk.storage.importFromFile` → `storage.tables.importPoller`, `sdk.storage.exportToFile` → `storage.tables.exportPoller`, `sdk.storage.createBucketListing` → `storage.bucketListings.createListingPoller`, and so on). Where the SDK threw, `.wait()` the `*Poller`.
+  - **Breaking:** the job-enqueueing methods without the `Async` suffix are renamed: `tables.deleteTableRows` → `tables.deleteTableRowsAsync`, `tables.updateTableDefinition` → `tables.updateTableDefinitionAsync`, `configurationWorkspaces.createConfigurationWorkspaceJob` → `configurationWorkspaces.createConfigurationWorkspaceAsync`, `mergeRequests.mergeMergeRequest` → `mergeRequests.mergeMergeRequestAsync`.
+  - **Breaking:** `createQueryServiceSdk().waitForJob` and `QueryJobTimeoutError` are removed. `queryService.poller` is the one wait on a query job; `executeQuery` is built on it, takes the poller's `QueryJobPollOptions` (`timeout` replaces `maxWaitTime`, with the same 5-minute default; the 500 ms interval stays) and throws the poll's failure when the wait did not finish.
+  - `queue.poller` and `queryService.poller` wait the same way, throwing `QueueJobError` / `QueryJobError` for a job that ended failed. A poller's `wait(onFailure)` now hands the mapper the error as its second argument.
+  - **Breaking:** `poller` and `poll` require `pollKey`, a key or a function of `init`, so every poll is named in the registry; `pollFn` and `until` no longer receive the key, `pollFn` reads `init`.
+  - **Breaking:** `poll()` is removed; `poller(options).start()` resolves the `PollResult` it did, `poller(options).wait()` what its `unwrap` did.
+  - `queue.poller` and `queryService.poller` retry a transient status read, a 5xx, 429 or network failure, up to five times in a row, as `storage.poller` does.
+
+- Storage client types derive from Connection's OpenAPI spec (regenerated storage, management, oauth and kaiAgent schemas). Hand-rolled shapes remain only where the spec has a gap, each tracked on DMD-1942.
+  - **Breaking:** token, trigger and snapshot ids are numbers; callers pass `Number(id)`. `saveColumnMetadata` and `deleteColumnMetadata` take the spec's `id` (a string) instead of `columnId`.
+  - **Breaking:** `getMergeRequest({ id, include })` replaces `getMergeRequest(id)` and `getMergeRequestWithActivityLog(id)`; `getRunIdStats({ runId })`, `deleteScheduledTask({ taskId })` and the snapshot methods take the spec's parameter names (`id`, `snapshotId`).
+  - **Breaking:** `AdminRole` is the spec's enum and `admin.role` is nullable; `Workspace.name` is nullable and `deactivateAt` is always present.
+  - `include` / `exclude` query parameters type the result they are called with (`OpenapiIncludeQueryType`, `OpenapiExcludeQueryType`, `WithIncludes`, `WithExcludes`); buckets, tables, components, shared buckets, configuration versions, merge requests, search and stack info use them.
+  - api-fixtures bodies follow the regenerated types.
+
+### Minor Changes
+
+- Adds the `componentsMcp` service client (`api.componentsMcp`, `@keboola/api-client/componentsMcp`), resolved from the stack's `components-mcp` service index entry: `getConnectors` and `setConnectorCredentials` for Kai's connector credential form. Storage-token strategy only: the service does not accept `Authorization` yet.
+
+- Adds `oauth.getOrganizationConnections()` (`GET /organization-credentials/connections`): the GitHub connections (`accountLogin`, `host`) of the project's organization, readable with any project member's Storage token. Exports the `OrganizationConnection` type from `@keboola/api-client/oauth/types`.
+
+- Adds `onExpired` to `KeboolaOptions`: called once per sign-in when a live credential's refresh is refused and the stack signs out, never for a `signOut()` the caller made or a stored session a restore found dead. An app wires its leave-the-document reaction there instead of subscribing to the session table.
+
+- `Workspace` carries `deleteAt`, the ISO 8601 timestamp when retention deletes a deactivated workspace (`null` or absent otherwise).
+
+- Storage `bucketListings`: add `getListingSubscriptions({ branchId, bucketId })`, the consumers currently subscribing to a bucket exposure. It returns `null` when the bucket has no exposure. The method is declared by hand on the generic client until the route reaches the generated schema. The storage client also exports `StorageGenericFetchClient`.
+
+- `management.storageBackends.getPolicyTagEnablementGuide` fetches the BigQuery policy-tag enablement guide (`GET /manage/storage-backend/{id}/policy-tags/enablement-guide`) as Markdown or Terraform. `resourceScopes` and `probeTags` go out as `resourceScopes[]` / `probeTags[]`. `StorageBackend` gains an optional `policyTagsEnabled`.
+
+- Management `storageBackends`: the result of `createBigqueryStorageBackend` is exported as `StorageBackendBigquery`.
+
+- Management `storageBackends`: `createBigqueryServerSideStorageBackend` (`POST /manage/storage-backend/bigquery/server-side`) with its `CreateBigqueryServerSideStorageBackendBody`; the BigQuery create/update results are typed `StorageBackendBigquery`, which gains an optional `isEnabled`.
+
+### Patch Changes
+
+- The Developer Portal client sends `@` and `+` in a path parameter unencoded, so inviting a developer, accepting an invitation and the email-keyed auth calls pass apps-api's email validation. apps-api does not decode path parameters, so `%40` failed with `Parameter email in uri must be valid email address`. The other clients keep `encodeURIComponent`.
+
+## 46.0.0
+
+### Major Changes
+
+- Regenerate the omnisearch, developerPortal, vault, dataScience, apps, kaiAgent, storage, management, auth, oauth and microsoftGraph OpenAPI types against the live services
+  - **Breaking:** `auth.me.getOrganizations`, `getProjects` and `getMaintainers` return a cursor page `{ data, meta, links }` instead of `{ count, items, limit, offset, hasMore }`, and take `{ page: { after, limit }, filter: { … } }` instead of `limit` / `offset` / top-level filters (`q` is now `filter.name`).
+  - `storage.tokens.createToken` resolves `token` as a required `string`.
+
+### Minor Changes
+
+- The admin behind a Manage token, as a domain object.
+  - `createAdminAccount({ managementToken })` mirrors `createProject`: `isSuperAdmin`, `hasAdminFeature`, `hasAnyAdminFeature`, the raw `user` and the token.
+  - A token with no admin behind it, or `null` for no token at all, yields an account where every helper answers `false`.
+  - `ManagementSessionMintError` (a `ManagementClientAuthError`) when the legacy client could not mint a session token from the login cookie, with `isManagementSessionMintError`. A bearer client never raises it.
+
 ## 45.0.0
 
 ### Major Changes

package/README.md

@@ -176,6 +176,7 @@ src/
     oauth/                      # OAuth credentials
     chat/                       # Kai Assistant chat
     kaiAgent/                   # Kai Agent (agentic assistant)
+    componentsMcp/              # Components MCP connector vault
     ai/                         # AI describe/explain/suggest
     queue/                      # Job Queue
     queryService/               # SQL query service
@@ -211,23 +212,24 @@ src/
 On the `api` object returned by `createKeboola()` / `createLegacyKeboola()` — once the session reaches `ready` — the following clients are available.
 Clients backed by OpenAPI specs are marked with (OpenAPI); the rest use the generic fetch client.
 
-| Accessor           | Service                 | Key methods                                                                                                                                                                                                         |
-| ------------------ | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `api.storage`      | Storage API             | `buckets.*`, `tables.*`, `files.*`, `branches.*`, `workspaces.*`, `mergeRequests.*`, `jobs.*`, `components.*`, `configurations.*`, `configurationRows.*`, `configurationWorkspaces.*`, `tokens.*`, `getStackInfo()` |
-| `api.management`   | Management API          | `projects.*`, `features.*`, `users.*`                                                                                                                                                                               |
-| `api.vault`        | Vault (OpenAPI)         | `getVariables()`, `createVariable()`, `deleteVariable()`, `getVariablesByBranchId()`, `getProjectWideVariables()`                                                                                                   |
-| `api.oauth`        | OAuth                   | `getCredentials()`, `getCredential()`, `createCredential()`, `deleteCredential()`                                                                                                                                   |
-| `api.dataScience`  | Data Science (OpenAPI)  | `getApps()`, `getApp()`, `createApp()`, `patchApp()`, `deleteApp()`, `getAppRuns()`, `getAppRun()`, `getAppLogsTail()`, `getAppLogsDownload()`, `getRuntimes()`, `getSandbox()`                                     |
-| `api.editor`       | SQL Editor (OpenAPI)    | `createSession()`, `getSession()`, `getSessions()`, `getSessionSchema()`, `createQueryJob()`, `tablePreview()`, `tableDefinition()`, `load()`, `unload()`                                                           |
-| `api.encryption`   | Encryption              | `encrypt()`, `encryptSecrets()`                                                                                                                                                                                     |
-| `api.chat`         | Kai Assistant (OpenAPI) | `getHistory()`, `getChat()`, `createChat()`, `deleteChat()`, `getVotes()`, `submitVote()`, `getUsage()`, `getSuggestions()`, `getAgentSettings()`, `getToolsList()`                                                 |
-| `api.kaiAgent`     | Kai Agent (OpenAPI)     | `getHistory()`, `getChat()`, `createChat()`, `deleteChat()`, `approveToolCall()`, `submitToolOutput()`, `getSuggestions()`, `getAgentSettings()`                                                                    |
-| `api.ai`           | AI Service (OpenAPI)    | `describeConfiguration()`, `describeConfigurationVersion()`, `describeConfigurationMerge()`, `explainError()`, `suggestComponent()`, `feedback()`                                                                   |
-| `api.queue`        | Job Queue (OpenAPI)     | `getJob()`, `searchJobs()`                                                                                                                                                                                          |
-| `api.queryService` | Query Service (OpenAPI) | `createQueryJob()`, `cancelQueryJob()`, `getQueryJob()`, `getQueryResults()`, `getQueryHistory()`, `exportResults()`                                                                                                |
-| `api.syncActions`  | Sync Actions (OpenAPI)  | `sendSyncAction()` + one namespace per component; see [`surface/syncActions.md`](./surface/syncActions.md)                                                                                                          |
-| `api.telemetry`    | Telemetry               | `provisioning.*`                                                                                                                                                                                                    |
-| `api.import`       | Import (OpenAPI)        | `uploadFile()`, `writeTable()`                                                                                                                                                                                      |
+| Accessor            | Service                  | Key methods                                                                                                                                                                                                         |
+| ------------------- | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `api.storage`       | Storage API              | `buckets.*`, `tables.*`, `files.*`, `branches.*`, `workspaces.*`, `mergeRequests.*`, `jobs.*`, `components.*`, `configurations.*`, `configurationRows.*`, `configurationWorkspaces.*`, `tokens.*`, `getStackInfo()` |
+| `api.management`    | Management API           | `projects.*`, `features.*`, `users.*`                                                                                                                                                                               |
+| `api.vault`         | Vault (OpenAPI)          | `getVariables()`, `createVariable()`, `deleteVariable()`, `getVariablesByBranchId()`, `getProjectWideVariables()`                                                                                                   |
+| `api.oauth`         | OAuth                    | `getCredentials()`, `getCredential()`, `createCredential()`, `deleteCredential()`                                                                                                                                   |
+| `api.dataScience`   | Data Science (OpenAPI)   | `getApps()`, `getApp()`, `createApp()`, `patchApp()`, `deleteApp()`, `getAppRuns()`, `getAppRun()`, `getAppLogsTail()`, `getAppLogsDownload()`, `getRuntimes()`, `getSandbox()`                                     |
+| `api.editor`        | SQL Editor (OpenAPI)     | `createSession()`, `getSession()`, `getSessions()`, `getSessionSchema()`, `createQueryJob()`, `tablePreview()`, `tableDefinition()`, `load()`, `unload()`                                                           |
+| `api.encryption`    | Encryption               | `encrypt()`, `encryptSecrets()`                                                                                                                                                                                     |
+| `api.chat`          | Kai Assistant (OpenAPI)  | `getHistory()`, `getChat()`, `createChat()`, `deleteChat()`, `getVotes()`, `submitVote()`, `getUsage()`, `getSuggestions()`, `getAgentSettings()`, `getToolsList()`                                                 |
+| `api.kaiAgent`      | Kai Agent (OpenAPI)      | `getHistory()`, `getChat()`, `createChat()`, `deleteChat()`, `approveToolCall()`, `submitToolOutput()`, `getSuggestions()`, `getAgentSettings()`                                                                    |
+| `api.componentsMcp` | Components MCP (OpenAPI) | `getConnectors()`, `setConnectorCredentials()`                                                                                                                                                                      |
+| `api.ai`            | AI Service (OpenAPI)     | `describeConfiguration()`, `describeConfigurationVersion()`, `describeConfigurationMerge()`, `explainError()`, `suggestComponent()`, `feedback()`                                                                   |
+| `api.queue`         | Job Queue (OpenAPI)      | `getJob()`, `searchJobs()`                                                                                                                                                                                          |
+| `api.queryService`  | Query Service (OpenAPI)  | `createQueryJob()`, `cancelQueryJob()`, `getQueryJob()`, `getQueryResults()`, `getQueryHistory()`, `exportResults()`                                                                                                |
+| `api.syncActions`   | Sync Actions (OpenAPI)   | `sendSyncAction()` + one namespace per component; see [`surface/syncActions.md`](./surface/syncActions.md)                                                                                                          |
+| `api.telemetry`     | Telemetry                | `provisioning.*`                                                                                                                                                                                                    |
+| `api.import`        | Import (OpenAPI)         | `uploadFile()`, `writeTable()`                                                                                                                                                                                      |
 
 Additional accessors on the ready client:
 
@@ -361,37 +363,44 @@ const ordered = await series({
 });
 ```
 
-### poll
+### poller
 
 A poll **returns** how it ended — `done`, `timedOut`, `exhausted`, `aborted`, `errored` — so nothing is
-thrown at a caller that wants to branch. `unwrap()` is the shortcut for the caller that doesn't: it
-resolves the value or throws.
+thrown at a caller that wants to branch. `wait()` is the shortcut for the caller that doesn't: it
+resolves the succeeded value or throws.
 
 ```typescript
-import { poll } from '@keboola/api-client';
+import { poller } from '@keboola/api-client';
 
-// `pollKey` is the poll's identity, in the shape of a TanStack query key. It is handed to `pollFn`
-// the way a `queryFn` gets its key, and dev tools name a running poll from it.
+// `pollKey` names the poll, in the shape of a TanStack query key; dev tools show a running poll by it.
+// `init` is what the poll starts from, handed to `pollFn`: a value, or a request for it (an enqueue),
+// which runs on `start()` before the first attempt.
 // `backoff` names the curve by the field it starts from: `interval` for `constant`, `initialInterval`
 // for `linear` and `exponential`. Add `jitter: 'full' | 'equal'` to spread a herd of polls apart.
-const result = await poll({
-  pollKey: ['queue.job', { jobId }] as const,
-  pollFn: ({ pollKey: [, params], signal }) => api.queue.getJob(params.jobId, signal),
+const handle = poller({
+  pollKey: ({ id }) => ['queue.job', { id }] as const,
+  init: { id: jobId },
+  pollFn: ({ init, signal }) => api.queue.getJob(init.id, signal),
   until: ({ data }) => data.status === 'success' || data.status === 'error',
+  failed: (job) => (job.status === 'error' ? new Error(job.result?.message) : undefined),
   backoff: { type: 'exponential', initialInterval: 1000, factor: 2, maxInterval: 30_000 },
   maxAttempts: 30,
   timeout: 5 * 60_000,
 });
 
+// Nothing runs until one of these. `start()` resolves how the poll ended; `wait()` resolves the
+// value, or throws: the poll's failure, or what `failed` reads off a value that ended badly.
+const result = await handle.start();
 if (result.state === 'done') console.log(result.data.status);
 
-// Or: resolve the value, throw on anything else. `stop()` ends the poll from outside.
-const task = poll({ pollFn, until });
-const job = await task.unwrap();
+const job = await handle.wait();
+
+// `subscribe()` watches the attempts as they happen, `stop()` ends the poll from outside.
 ```
 
-`poller(options)` is the same thing cold — it polls only once `start()` is called, and adds
-`subscribe()` / `debug()` for watching a poll's attempts as they happen.
+The job clients wrap this: `api.storage.poller({ init: job })`, `api.queue.poller({ init: job })` and
+`api.queryService.poller({ init: job })`, and every `*Poller` method hands back the handle for the
+job it enqueues, `api.storage.tables.createTablePoller(input).wait()`.
 
 ### keboolaUID
 
@@ -459,13 +468,14 @@ Internal guide for adding new service clients to this package.
 
 ### Method naming conventions
 
-A method's name states what the call does, so a call site can tell whether the work is finished once the promise settles. Clients expose the endpoint methods plus — where the endpoint enqueues a job — a wait-variant suffixed `AndWait`.
+A method's name states what the call does, so a call site can tell whether the work is finished once the promise settles. Clients expose the endpoint methods plus — where the endpoint enqueues a job — a `*Poller` twin that hands back the poller for the job.
 
-| What the call does                               | Name shape | Example                       |
-| ------------------------------------------------ | ---------- | ----------------------------- |
-| returns the finished resource in one request     | bare verb  | `buckets.getBucket()`         |
-| enqueues the work and hands back a `Job` to poll | `*Async`   | `tables.createTableAsync()`   |
-| enqueues the work and polls it to completion     | `*AndWait` | `tables.createTableAndWait()` |
+| What the call does                               | Name shape | Example                                       |
+| ------------------------------------------------ | ---------- | --------------------------------------------- |
+| returns the finished resource in one request     | bare verb  | `buckets.getBucket()`                         |
+| enqueues the work and hands back a `Job` to poll | `*Async`   | `tables.createTableAsync()`                   |
+| hands back the poller for the enqueue            | `*Poller`  | `tables.createTablePoller()`                  |
+| runs a batch to completion and reports it        | `*AndWait` | `configurations.purgeConfigurationsAndWait()` |
 
 The suffix is a suffix on purpose: a wait-variant shares its sibling's prefix, so the two sort together in autocomplete.
 

package/dist/ManagementSessionMintError-4Pkn5Oob.js

@@ -0,0 +1,36 @@
+import { p as ApiError } from "./createFetchClient-CkHdS_IG.js";
+//#region src/errors/ManagementClientAuthError.ts
+var ManagementClientAuthError = class extends ApiError {
+	title;
+	message;
+	constructor(title, message, res) {
+		super(res);
+		this.name = "ManagementClientAuthError";
+		this.title = title;
+		this.message = message;
+	}
+};
+//#endregion
+//#region src/errors/ManagementSessionMintError.ts
+/**
+* The Manage client has no credential of its own and could not mint a session token from the
+* login cookie.
+*
+* - Only the legacy (SAPI) entry point mints; a bearer client never raises it.
+* - The login page in place of the token: the session expired, or there is no cookie (off the
+*   stack host).
+*/
+var ManagementSessionMintError = class extends ManagementClientAuthError {
+	constructor({ title, message, response, request, data }) {
+		super(title, message, {
+			response,
+			request,
+			data
+		});
+		this.name = "ManagementSessionMintError";
+	}
+};
+//#endregion
+export { ManagementClientAuthError as n, ManagementSessionMintError as t };
+
+//# sourceMappingURL=ManagementSessionMintError-4Pkn5Oob.js.map

package/dist/ManagementSessionMintError-4Pkn5Oob.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ManagementSessionMintError-4Pkn5Oob.js","names":[],"sources":["../src/errors/ManagementClientAuthError.ts","../src/errors/ManagementSessionMintError.ts"],"sourcesContent":["import type { ApiResponse } from '../fetchClient/createFetchClient/types';\n\nimport { ApiError } from './ApiError';\n\nexport class ManagementClientAuthError extends ApiError {\n  title: string;\n  message: string;\n  constructor(title: string, message: string, res: ApiResponse) {\n    super(res);\n    this.name = 'ManagementClientAuthError';\n    this.title = title;\n    this.message = message;\n  }\n}\n","import { ManagementClientAuthError } from './ManagementClientAuthError';\n\n/**\n * The Manage client has no credential of its own and could not mint a session token from the\n * login cookie.\n *\n * - Only the legacy (SAPI) entry point mints; a bearer client never raises it.\n * - The login page in place of the token: the session expired, or there is no cookie (off the\n *   stack host).\n */\nexport class ManagementSessionMintError extends ManagementClientAuthError {\n  constructor({ title, message, response, request, data }: ManagementClientAuthError) {\n    super(title, message, { response, request, data });\n    this.name = 'ManagementSessionMintError';\n  }\n}\n"],"mappings":";;AAIA,IAAa,4BAAb,cAA+C,SAAS;CACtD;CACA;CACA,YAAY,OAAe,SAAiB,KAAkB;EAC5D,MAAM,GAAG;EACT,KAAK,OAAO;EACZ,KAAK,QAAQ;EACb,KAAK,UAAU;CACjB;AACF;;;;;;;;;;;ACHA,IAAa,6BAAb,cAAgD,0BAA0B;CACxE,YAAY,EAAE,OAAO,SAAS,UAAU,SAAS,QAAmC;EAClF,MAAM,OAAO,SAAS;GAAE;GAAU;GAAS;EAAK,CAAC;EACjD,KAAK,OAAO;CACd;AACF"}