@keboola/api-client 46.0.0 → 48.0.0

package/AGENTS.md

@@ -82,9 +82,12 @@ Two flow-specific factories back the SDK:
 `session` is **flow-specific** lifecycle machinery:
 
 - bearer: `stack.select(baseUrl)` → `auth.authenticate(credential)` → `project.select(projectId)`,
-  plus `auth.signOut()` / `auth.replace(credential)` / `auth.isAuthenticated()` / `auth.isAuthenticatedAsync()` / `auth.rotate(baseUrl)` / `auth.getHeaders(projectId?)` / `auth.getHeadersAsync(projectId?)`, `stack.close` and
+  plus `auth.signOut({ baseUrl?, retain? }?)` / `auth.replace(credential)` / `auth.isAuthenticated()` / `auth.isAuthenticatedAsync()` / `auth.rotate(baseUrl)` / `auth.getHeaders(projectId?)` / `auth.getHeadersAsync(projectId?)`, `auth.restoreRetained(baseUrl)`, `stack.close` and
   the two `deactivate`s, and `getState()` / `subscribe(cb)` over the stack-and-project table. Every
-  verb is synchronous — nothing awaits a build; a namespace throws `NotReady` until its fetch lands.
+  verb changes the table synchronously — nothing awaits a build; a namespace throws `NotReady` until
+  its fetch lands. `stack.select`, `project.select` and `auth.signOut` also return a promise that
+  resolves once the change is stored: await it before leaving the document, or the reload boots
+  from the scope or sign-in it was meant to replace.
   The one fetch each entry does own is readable both ways: `stack.getContext(baseUrl?)` /
   `project.getContext(entryId?)` answer from cache (`null` until it lands), and the
   `getContextAsync` sibling of each awaits it. `retryContext` refetches after a failure. The
@@ -157,8 +160,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 +209,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,
@@ -487,7 +491,10 @@ 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.
+**`api.apps` needs no availability check.** Every stack's sandboxes-service serves `/v2` from the same image as `/v1`, and `api.apps` resolves off the `data-science` service id like `api.dataScience`. When probing a stack by hand, only an authenticated call answers:
+
+- `healthCheck()`, `GET /v2/docs/swagger.yaml` and unauthenticated calls answer the same everywhere.
+- A `401` from an authenticated call means a bad or expired token, not a missing API.
 
 Clients backing optional stack services (vault, queue, …) throw `ServiceUnavailableError` if absent from the current stack — check `api.context.stack.hasService(...)` before assuming a namespace exists.
 
@@ -609,6 +616,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 +679,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, 727 methods. This index lists method **names** only — full signatures live per namespace under [`surface/`](./surface). Open `surface/<namespace>.md` for the one you need.
 
 ## [`api.ai`](./surface/ai.md)
 
@@ -13,7 +13,6 @@ Every namespace and method reachable from a ready `KeboolaApi` — the `api` hal
 - `describeConfigurationVersion`
 - `docsQuestion`
 - `explainError`
-- `feedback`
 - `getComponentDetail`
 - `healthCheck`
 - `suggestComponent`
@@ -60,6 +59,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 +117,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`
@@ -221,6 +228,7 @@ Every namespace and method reachable from a ready `KeboolaApi` — the `api` hal
 - `updateProjectToolPolicy`
 - `updateSpendCaps`
 - `updateUserAgentSettings`
+- `updateUserMemory`
 
 ## [`api.management`](./surface/management.md)
 
@@ -319,6 +327,7 @@ Every namespace and method reachable from a ready `KeboolaApi` — the `api` hal
 - `payAsYouGo.updateStripeCustomer`
 - `payAsYouGo.updateTopUpSetting`
 - `programmaticProjects.confirm`
+- `programmaticProjects.getClaim`
 - `projects.addProjectFeature`
 - `projects.addProjectTemplateFeature`
 - `projects.addProjectUser`
@@ -355,9 +364,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 +435,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 +509,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 +527,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 +540,39 @@ 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.sharingTargets`
 - `bucketSharing.unshareBucketAsync`
+- `bucketSharing.unshareBucketPoller`
 - `buckets.createBucket`
 - `buckets.deleteBucket`
 - `buckets.deleteBucketAsync`
 - `buckets.deleteBucketMetadata`
+- `buckets.deleteBucketPoller`
 - `buckets.getBucket`
 - `buckets.getBucketOwner`
 - `buckets.getBuckets`
@@ -574,10 +580,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 +610,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 +651,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 +661,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 +707,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,90 @@
 # @keboola/api-client
 
+## 48.0.0
+
+### Major Changes
+
+- - A `StorageAdapter` may answer with a promise, and may offer `withLock` for a critical section shared across documents. **Breaking:** `createPersistor` is `read` / `write` / `modify` / `remove`, plus `transaction(task)`, which hands `task` the same four verbs under the adapter's lock: every write resolves once it has landed and rejects when it could not, writes run in the order they were issued, and `read` waits for the ones in flight. `hydrate`, `persist`, `update`, `clear`, `flush` and `hasPersistedValue` are gone.
+  - **Breaking:** `session.auth.signOut` resolves once the sign-out is stored — await it before leaving the document.
+  - **Breaking:** `session.auth.signOut` takes one options object, `{ baseUrl?, retain? }`. With `retain`, the stack signs out but keeps its grant; `session.auth.restoreRetained(baseUrl)` signs it back in. `Stack.retained` holds the kept grant with its issue time.
+  - **Breaking:** `CredentialType` is renamed `GrantType`. `Grant` is what renews a credential and what persists; `Credential` is the grant with its access token.
+
+- Remove `api.ai.feedback()` and the `FeedbackBody` type. The UI no longer sends 👍/👎 feedback on AI-generated content to the AI service.
+
+### Minor Changes
+
+- Kai saves a personal note right away by default (AI-4061). The chat shows "Remembered: …" with Undo and Edit; Kai settings → Memory switches back to asking before each save. Company notes still go through approval and a project admin's review. `api.kaiAgent.updateUserMemory(id, content)` edits a note, and user settings carry `memorySaveMode` (`auto` | `ask`).
+
+- `Workspace` carries `lastActivityAt`, the last observed use, and `warnAt`, when retention will warn the owner (both ISO 8601, `null` or absent otherwise).
+
+- `api.storage.bucketSharing.sharingTargets()` lists the projects and users a bucket can be shared to (`GET /v2/storage/sharing-targets`), and `api.management.programmaticProjects.getClaim()` reads the parked agent-project claim (`GET /manage/programmatic-projects/claim`). Both come from the regenerated Storage and Manage schemas; the Storage regen also adds `lastActivityAt` and `warnAt` to workspaces (UT-5889)
+
+### Patch Changes
+
+- The `apps` (`/v2` App Deployments) types are generated from `apps.keboola.com`; the types are unchanged.
+  - `suspendApp` sleeps the app; the next visitor wakes it.
+  - `getDeployments` lists live deployments; `archived: true` lists the deleted ones instead.
+
+- Regenerate the developerPortal, queryService, kaiAgent, componentsMcp, storage and management OpenAPI types against the live services (UT-5860)
+
+- `kaiAgent` history types: a stored tool part's `approval.approved` is optional — a call whose approval card was shown keeps only the approval `id`.
+
+- `canWriteSemanticLayer` admits the `share` project role, matching the metastore's role mapping (`admin`, `productionManager`, `share` get project-admin). A `share` member now gets the semantic-layer write actions in kbc-ui and Kai's semantic-layer write tools.
+
+## 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