@keboola/api-client 25.0.0 → 29.0.0

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`.
 
-22 top-level namespaces, 546 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, 616 methods. This index lists method **names** only — full signatures live per namespace under [`surface/`](./surface). Open `surface/<namespace>.md` for the one you need.
 
 ## [`api.ai`](./surface/ai.md)
 
@@ -15,13 +15,45 @@ Every namespace and method reachable from a ready `KeboolaApi` — the `api` hal
 - `explainError`
 - `feedback`
 - `getComponentDetail`
+- `healthCheck`
 - `suggestComponent`
 
+## [`api.apps`](./surface/apps.md)
+
+- `createApp`
+- `createAppGitRepoCredential`
+- `createDeployment`
+- `deleteApp`
+- `deleteAppGitRepoCredential`
+- `deleteDeployment`
+- `getApp`
+- `getAppGitRepo`
+- `getAppGitRepoCredential`
+- `getAppGitRepoCredentials`
+- `getAppLogsDownload`
+- `getAppLogsTail`
+- `getAppPassword`
+- `getAppRun`
+- `getAppRuns`
+- `getApps`
+- `getDeployment`
+- `getDeploymentLogsDownload`
+- `getDeploymentLogsTail`
+- `getDeployments`
+- `healthCheck`
+- `promoteDeployment`
+- `resetAppPassword`
+- `resumeApp`
+- `suspendApp`
+- `unpublishApp`
+
 ## [`api.auth`](./surface/auth.md)
 
 - `device.approve`
 - `device.create`
 - `device.getToken`
+- `healthCheck`
+- `login.methods`
 - `login.withOidc`
 - `login.withPassword`
 - `mfa.regenerateRecoveryCodes`
@@ -61,6 +93,7 @@ Every namespace and method reachable from a ready `KeboolaApi` — the `api` hal
 - `getUsage`
 - `getUserAgentSettings`
 - `getVotes`
+- `healthCheck`
 - `submitVote`
 - `updateAgentSettings`
 - `updateUserAgentSettings`
@@ -104,6 +137,7 @@ Every namespace and method reachable from a ready `KeboolaApi` — the `api` hal
 - `getApps`
 - `getRuntimes`
 - `getSandbox`
+- `healthCheck`
 - `patchApp`
 - `resetAppPassword`
 
@@ -115,6 +149,7 @@ Every namespace and method reachable from a ready `KeboolaApi` — the `api` hal
 - `getSessionCredentials`
 - `getSessionSchema`
 - `getSessions`
+- `healthCheck`
 - `load`
 - `resetWorkspacePassword`
 - `tableDefinition`
@@ -126,9 +161,11 @@ Every namespace and method reachable from a ready `KeboolaApi` — the `api` hal
 - `encrypt`
 - `encryptScopedSecrets`
 - `encryptSecrets`
+- `healthCheck`
 
 ## [`api.import`](./surface/import.md)
 
+- `healthCheck`
 - `uploadFile`
 - `writeTable`
 
@@ -147,6 +184,7 @@ Every namespace and method reachable from a ready `KeboolaApi` — the `api` hal
 - `getUsage`
 - `getUserAgentSettings`
 - `getVotes`
+- `healthCheck`
 - `listSandboxFiles`
 - `readSandboxFile`
 - `stopChat`
@@ -192,6 +230,7 @@ Every namespace and method reachable from a ready `KeboolaApi` — the `api` hal
 - `fileStorage.setFileStorageAbsDefault`
 - `fileStorage.setFileStorageGcsDefault`
 - `fileStorage.setFileStorageS3Default`
+- `healthCheck`
 - `maintainers.addMaintainerUser`
 - `maintainers.completeMaintainerSamlSetup`
 - `maintainers.createMaintainer`
@@ -310,6 +349,7 @@ Every namespace and method reachable from a ready `KeboolaApi` — the `api` hal
 - `repository.getMetaObjectRevisions`
 - `repository.getMetaObjects`
 - `repository.replaceMetaObject`
+- `repository.replaceTargetProjects`
 - `repository.updateMetaObject`
 - `schema.getSchema`
 - `schema.getVersionedSchema`
@@ -322,6 +362,7 @@ Every namespace and method reachable from a ready `KeboolaApi` — the `api` hal
 - `deleteSubscriptions`
 - `getSubscription`
 - `getSubscriptions`
+- `healthCheck`
 
 ## [`api.oauth`](./surface/oauth.md)
 
@@ -329,6 +370,13 @@ Every namespace and method reachable from a ready `KeboolaApi` — the `api` hal
 - `deleteCredential`
 - `getCredential`
 - `getCredentials`
+- `healthCheck`
+
+## [`api.omnisearch`](./surface/omnisearch.md)
+
+- `getProjectsLineage`
+- `getTablesLineage`
+- `healthCheck`
 
 ## [`api.queryService`](./surface/queryService.md)
 
@@ -338,13 +386,17 @@ Every namespace and method reachable from a ready `KeboolaApi` — the `api` hal
 - `getQueryHistory`
 - `getQueryJob`
 - `getQueryResults`
+- `healthCheck`
+- `poller`
 
 ## [`api.queue`](./surface/queue.md)
 
 - `createJob`
 - `getJob`
 - `getOrchestrationRerunPlan`
+- `healthCheck`
 - `killJob`
+- `poller`
 - `searchAllJobs`
 - `searchGroupedJobs`
 - `searchJobs`
@@ -357,6 +409,7 @@ Every namespace and method reachable from a ready `KeboolaApi` — the `api` hal
 - `deleteSchedulesForConfigurations`
 - `getSchedule`
 - `getSchedules`
+- `healthCheck`
 - `refreshScheduleToken`
 
 ## [`api.sdk`](./surface/sdk.md)
@@ -374,6 +427,8 @@ Every namespace and method reachable from a ready `KeboolaApi` — the `api` hal
 - `semanticLayer.listModelChildren`
 - `semanticLayer.listModels`
 - `semanticLayer.listObjects`
+- `semanticLayer.promoteToOrganizationScope`
+- `semanticLayer.replaceTargetProjects`
 - `semanticLayer.updateModel`
 - `semanticLayer.updateObject`
 - `storage.addTableColumn`
@@ -386,9 +441,7 @@ Every namespace and method reachable from a ready `KeboolaApi` — the `api` hal
 - `storage.deleteTableColumn`
 - `storage.exportToFile`
 - `storage.forceUnlinkBucket`
-- `storage.getBucketListing`
 - `storage.importFromFile`
-- `storage.listBucketListings`
 - `storage.pullTable`
 - `storage.refreshExternalBucket`
 - `storage.registerBucket`
@@ -417,72 +470,87 @@ Every namespace and method reachable from a ready `KeboolaApi` — the `api` hal
 
 ## [`api.storage`](./surface/storage.md)
 
-- `branches.createDevBranchJob`
-- `branches.deleteDevBranchJob`
+- `branches.createDevBranchAndWait`
+- `branches.createDevBranchAsync`
+- `branches.deleteDevBranchAndWait`
+- `branches.deleteDevBranchAsync`
 - `branches.deleteDevBranchMetadata`
 - `branches.getDevBranchMetadata`
 - `branches.getDevBranches`
 - `branches.saveDevBranchMetadata`
 - `branches.updateDevBranch`
+- `bucketExternal.createScheduledRefresh`
+- `bucketExternal.deleteScheduledTask`
+- `bucketExternal.getBucketRegistrationGuide`
+- `bucketExternal.refreshExternalBucketAsync`
+- `bucketExternal.registerBucketAsync`
+- `bucketListings.createListingAsync`
+- `bucketListings.deleteListingAsync`
+- `bucketListings.getListing`
+- `bucketListings.getListings`
+- `bucketListings.updateListingAsync`
+- `bucketSharing.forceUnlinkBucketAsync`
+- `bucketSharing.linkBucketAsync`
+- `bucketSharing.shareBucketToOrganizationAsync`
+- `bucketSharing.shareBucketToOrganizationProjectAsync`
+- `bucketSharing.shareBucketToProjectsAsync`
+- `bucketSharing.shareBucketToUsersAsync`
+- `bucketSharing.sharedBuckets`
+- `bucketSharing.unshareBucketAsync`
 - `buckets.createBucket`
-- `buckets.createListing`
-- `buckets.createScheduledRefresh`
 - `buckets.deleteBucket`
 - `buckets.deleteBucketAsync`
 - `buckets.deleteBucketMetadata`
-- `buckets.deleteListing`
-- `buckets.deleteScheduledTask`
-- `buckets.forceUnlinkBucket`
 - `buckets.getBucket`
 - `buckets.getBucketOwner`
-- `buckets.getBucketRegistrationGuide`
 - `buckets.getBuckets`
-- `buckets.getListing`
-- `buckets.listListings`
-- `buckets.refreshExternalBucket`
-- `buckets.registerBucket`
 - `buckets.saveBucketMetadata`
-- `buckets.shareBucketToOrganization`
-- `buckets.shareBucketToOrganizationProject`
-- `buckets.shareBucketToProjects`
-- `buckets.shareBucketToUsers`
-- `buckets.sharedBuckets`
-- `buckets.unshareBucket`
 - `buckets.updateBucket`
 - `buckets.updateBucketOwner`
-- `buckets.updateListing`
-- `columns.addTableColumn`
-- `columns.createTablePrimaryKey`
+- `columns.addTableColumnAsync`
+- `columns.createTablePrimaryKeyAsync`
 - `columns.deleteColumnMetadata`
-- `columns.deleteTableColumn`
-- `columns.removeTablePrimaryKey`
+- `columns.deleteTableColumnAsync`
+- `columns.removeTablePrimaryKeyAsync`
 - `columns.saveColumnMetadata`
-- `componentsAndConfigurations.createConfiguration`
-- `componentsAndConfigurations.createConfigurationRow`
-- `componentsAndConfigurations.createConfigurationRows`
-- `componentsAndConfigurations.createConfigurationWorkspace`
-- `componentsAndConfigurations.createConfigurationWorkspaceJob`
-- `componentsAndConfigurations.deleteConfiguration`
-- `componentsAndConfigurations.deleteConfigurationRow`
-- `componentsAndConfigurations.deleteConfigurationRows`
-- `componentsAndConfigurations.deleteConfigurations`
-- `componentsAndConfigurations.getComponent`
-- `componentsAndConfigurations.getComponents`
-- `componentsAndConfigurations.getConfiguration`
-- `componentsAndConfigurations.getConfigurationDiff`
-- `componentsAndConfigurations.getConfigurationRowDiff`
-- `componentsAndConfigurations.getConfigurationWorkspaces`
-- `componentsAndConfigurations.getConfigurations`
-- `componentsAndConfigurations.rebaseConfiguration`
-- `componentsAndConfigurations.resetConfigurationToDefault`
-- `componentsAndConfigurations.restoreConfiguration`
-- `componentsAndConfigurations.searchComponentConfigurations`
-- `componentsAndConfigurations.updateConfiguration`
+- `components.getComponent`
+- `components.getComponents`
+- `configurationMetadata.deleteConfigurationMetadata`
+- `configurationMetadata.getConfigurationMetadata`
 - `configurationMetadata.saveConfigurationMetadata`
+- `configurationRows.createConfigurationRow`
+- `configurationRows.createConfigurationRows`
+- `configurationRows.deleteConfigurationRow`
+- `configurationRows.deleteConfigurationRows`
+- `configurationRows.getConfigurationRow`
+- `configurationRows.updateConfigurationRow`
+- `configurationRows.updateConfigurationRowState`
 - `configurationVersions.copyConfigurationFromVersion`
+- `configurationVersions.copyConfigurationRowFromVersion`
+- `configurationVersions.getConfigurationRowVersion`
+- `configurationVersions.getConfigurationRowVersions`
 - `configurationVersions.getConfigurationVersion`
 - `configurationVersions.getConfigurationVersions`
+- `configurationVersions.rollbackConfigurationRowToVersion`
 - `configurationVersions.rollbackConfigurationToVersion`
+- `configurationWorkspaces.createConfigurationWorkspace`
+- `configurationWorkspaces.createConfigurationWorkspaceJob`
+- `configurationWorkspaces.getConfigurationWorkspaces`
+- `configurations.createConfiguration`
+- `configurations.deleteConfiguration`
+- `configurations.deleteConfigurations`
+- `configurations.getConfiguration`
+- `configurations.getConfigurationDiff`
+- `configurations.getConfigurations`
+- `configurations.purgeConfiguration`
+- `configurations.purgeConfigurations`
+- `configurations.rebaseConfiguration`
+- `configurations.rebaseConfigurationToDeleted`
+- `configurations.resetConfigurationToDefault`
+- `configurations.restoreConfiguration`
+- `configurations.searchComponentConfigurations`
+- `configurations.updateConfiguration`
+- `configurations.updateConfigurationState`
 - `events.createEvent`
 - `events.getBucketEvents`
 - `events.getEvent`
@@ -496,6 +564,7 @@ Every namespace and method reachable from a ready `KeboolaApi` — the `api` hal
 - `files.getFiles`
 - `files.prepareFile`
 - `getStackInfo`
+- `healthCheck`
 - `jobs.getJob`
 - `jobs.getJobs`
 - `mergeRequests.approveMergeRequest`
@@ -508,13 +577,17 @@ 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`
+- `snapshots.deleteSnapshotAsync`
+- `snapshots.getSnapshot`
+- `snapshots.getTableSnapshots`
 - `stats.getRunIdStats`
 - `tables.createAliasTable`
-- `tables.createSnapshot`
 - `tables.createTableAsync`
 - `tables.createTableDefinitionAsync`
-- `tables.deleteSnapshot`
 - `tables.deleteTable`
 - `tables.deleteTableMetadata`
 - `tables.deleteTableRows`
@@ -524,8 +597,7 @@ Every namespace and method reachable from a ready `KeboolaApi` — the `api` hal
 - `tables.getTable`
 - `tables.getTables`
 - `tables.importAsync`
-- `tables.loadTableSnapshots`
-- `tables.pullTable`
+- `tables.pullTableAsync`
 - `tables.removeAliasTableFilter`
 - `tables.saveTableMetadata`
 - `tables.setAliasTableFilter`
@@ -533,6 +605,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`
@@ -540,7 +613,7 @@ Every namespace and method reachable from a ready `KeboolaApi` — the `api` hal
 - `tokens.verify`
 - `triggers.createTrigger`
 - `triggers.deleteTrigger`
-- `triggers.listTriggers`
+- `triggers.getTriggers`
 - `triggers.updateTrigger`
 - `workspaces.deleteWorkspace`
 - `workspaces.deleteWorkspaceJob`
@@ -583,6 +656,7 @@ Every namespace and method reachable from a ready `KeboolaApi` — the `api` hal
 - `getSourceVersions`
 - `getSources`
 - `getTask`
+- `healthCheck`
 - `rollbackSinkVersion`
 - `rollbackSourceVersion`
 - `rotateSourceSecret`
@@ -598,12 +672,13 @@ Every namespace and method reachable from a ready `KeboolaApi` — the `api` hal
 
 - `apify.getActors`
 - `apify.getTasks`
+- `dbt.compile`
+- `dbt.runResults`
 - `enrollMFA`
-- `gitRepository.getDataAppPasswordPrivateGitRepository`
-- `gitRepository.getDataAppPublicGitRepository`
-- `gitRepository.getDataAppSSHKeyPrivateGitRepository`
-- `gitRepository.getPrivateGitRepository`
-- `gitRepository.getPublicGitRepository`
+- `git.getBranches`
+- `git.getEntrypoints`
+- `healthCheck`
+- `looker.testCredentials`
 - `sendSyncAction`
 
 ## [`api.telemetry`](./surface/telemetry.md)
@@ -617,3 +692,4 @@ Every namespace and method reachable from a ready `KeboolaApi` — the `api` hal
 - `getProjectWideVariables`
 - `getVariables`
 - `getVariablesByBranchId`
+- `healthCheck`

package/README.md

@@ -199,7 +199,7 @@ src/
   utils/
     concurrent.ts               # Concurrent task runner with middleware
     series.ts                   # Sequential task runner
-    poll.ts                     # Polling with isDone/isFailed predicates
+    poll/                       # Polling: the loop, the poller, the registry
     delay.ts                    # Abortable delay
     keboolaUID.ts               # Keboola object ID serialization
     generateUUID.ts             # crypto.randomUUID wrapper
@@ -211,23 +211,23 @@ 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.*`, `componentsAndConfigurations.*`, `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)  | `enrollMFA()`, `gitRepository.*`                                                                                                                                                |
-| `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.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)  | `enrollMFA()`, `gitRepository.*`                                                                                                                                                                                    |
+| `api.telemetry`    | Telemetry               | `provisioning.*`                                                                                                                                                                                                    |
+| `api.import`       | Import (OpenAPI)        | `uploadFile()`, `writeTable()`                                                                                                                                                                                      |
 
 Additional accessors on the ready client:
 
@@ -363,27 +363,36 @@ const ordered = await series({
 
 ### poll
 
+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.
+
 ```typescript
-import { poll, PollException } from '@keboola/api-client';
+import { poll } 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.
+// `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),
+  until: ({ data }) => data.status === 'success' || data.status === 'error',
+  backoff: { type: 'exponential', initialInterval: 1000, factor: 2, maxInterval: 30_000 },
+  maxAttempts: 30,
+  timeout: 5 * 60_000,
+});
 
-const controller = new AbortController();
+if (result.state === 'done') console.log(result.data.status);
 
-try {
-  const { data, callCount } = await poll({
-    pollFn: (signal) => api.queue.getJob(jobId, signal),
-    isDone: (job) => job.status === 'success',
-    isFailed: (job) => job.status === 'error',
-    interval: 2000,
-    maxAttempts: 30,
-    abortSignal: controller.signal,
-  });
-} catch (error) {
-  if (error instanceof PollException) {
-    console.error(error.message, error.result);
-  }
-}
+// Or: resolve the value, throw on anything else. `stop()` ends the poll from outside.
+const task = poll({ pollFn, until });
+const job = await task.unwrap();
 ```
 
+`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.
+
 ### keboolaUID
 
 ```typescript
@@ -448,6 +457,27 @@ MIT. See [LICENSE](./LICENSE).
 
 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`.
+
+| 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()` |
+
+The suffix is a suffix on purpose: a wait-variant shares its sibling's prefix, so the two sort together in autocomplete.
+
+Names that are ruled out, and why:
+
+- **bare verb** for a wait-variant — `buckets.deleteBucket` is a genuinely synchronous endpoint sitting next to `deleteBucketAsync`, so one name shape would mean two different things.
+- **`*Sync`** as the opposite of `*Async` — in JavaScript that promises no yielding (`readFileSync`).
+- **`createTableAsync(input, { wait: true })`** — both branches return `Job`, the same TS type, so nothing discriminates work that is merely enqueued from work that is done.
+- **`*AndPoll`** — names the transport rather than the contract.
+
+[`poll`](#poll) is the shared engine underneath. Storage's wait helpers currently live in the `sdks/storage` layer under bare-verb names; new ones go on the client.
+
 ### Testing conventions
 
 Tests are co-located `*.test.ts` files run by Vitest. There are two complementary ways to fake the network — pick by what the test is about:
@@ -472,6 +502,11 @@ Publish-time export-shape validation stays in `build:check` via `attw` — ortho
 
 ### Adding a New OpenAPI Client
 
+> These are the mechanical steps. The decisions they don't cover — client vs SDK, method naming,
+> what to do when the published spec is wrong, what not to test — are the eight rules in
+> [`AGENTS.md`](./AGENTS.md#eight-rules-for-a-new-client-or-sdk). Read those first; each one is a
+> review round somebody already paid for.
+
 #### Step 1: Register the API in `redocly.yaml`
 
 Add your API specification to the `redocly.yaml` file:
@@ -493,14 +528,18 @@ Run the type generation command:
 pnpm gen:types
 ```
 
-This will create the TypeScript definitions at the specified output path. Two manual steps follow,
-because the generator's raw output does not satisfy the repo's own checks:
+This will create the TypeScript definitions at the specified output path. Leave the generated file's
+contents alone — `oxlint.config.ts` turns `consistent-type-definitions` off for
+`src/clients/*/__generated__/*.d.ts`, so the `export interface operations` the generator emits
+despite `--export-type` is fine as it stands. Two mechanical steps do follow: run `oxfmt` on the new
+file (the raw output is 4-space), and revert the other schemas the command regenerated — it rewrites
+all of them, mostly reformatting. See
+[`docs/regenerate-api-types.md`](./docs/regenerate-api-types.md).
 
-- `openapi-typescript` emits `export interface operations` even with `--export-type`, which trips
-  oxlint's `consistent-type-definitions`. Convert it to `export type operations = { … };` — every
-  committed schema is in that form.
-- Run `oxfmt` on the new file, and revert the other schemas the command regenerated (it rewrites all
-  of them, mostly reformatting) — see [`docs/regenerate-api-types.md`](./docs/regenerate-api-types.md).
+`gen:types` regenerates every source in `redocly.yaml`, so to generate only the new one, run
+`openapi-typescript` directly against its URL from a directory without a `redocly.yaml` (it
+auto-discovers the file up the tree and ignores a positional URL when it finds one) with an absolute
+`--output`.
 
 #### Step 3: Create the Client Implementation
 
@@ -548,7 +587,7 @@ export * from './yourNewServiceClient';
 
 #### Step 6: Add Type Export to package.json
 
-Add the type export path to `package.json` exports and add the entry to `tsup.config.ts`:
+Add the type export path to `package.json` exports and add the entry to `tsdown.config.ts`:
 
 ```json
 {

package/dist/ManagementClientAuthError-B97OtOQ7.js

@@ -0,0 +1,15 @@
+import { p as ApiError } from "./createFetchClient-BK0TZK-U.js";
+//#region src/errors/ManagementClientAuthError.ts
+var ManagementClientAuthError = class extends ApiError {
+	title;
+	message;
+	constructor(title, message, res) {
+		super(res);
+		this.title = title;
+		this.message = message;
+	}
+};
+//#endregion
+export { ManagementClientAuthError as t };
+
+//# sourceMappingURL=ManagementClientAuthError-B97OtOQ7.js.map

package/dist/ManagementClientAuthError-B97OtOQ7.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ManagementClientAuthError-B97OtOQ7.js","names":[],"sources":["../src/errors/ManagementClientAuthError.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.title = title;\n    this.message = message;\n  }\n}\n"],"mappings":";;AAIA,IAAa,4BAAb,cAA+C,SAAS;CACtD;CACA;CACA,YAAY,OAAe,SAAiB,KAAkB;EAC5D,MAAM,GAAG;EACT,KAAK,QAAQ;EACb,KAAK,UAAU;CACjB;AACF"}

package/dist/ManagementClientAuthError-ZJ2-RoKT.cjs

@@ -0,0 +1,20 @@
+const require_createFetchClient = require("./createFetchClient-BsG719K1.cjs");
+//#region src/errors/ManagementClientAuthError.ts
+var ManagementClientAuthError = class extends require_createFetchClient.ApiError {
+	title;
+	message;
+	constructor(title, message, res) {
+		super(res);
+		this.title = title;
+		this.message = message;
+	}
+};
+//#endregion
+Object.defineProperty(exports, "ManagementClientAuthError", {
+	enumerable: true,
+	get: function() {
+		return ManagementClientAuthError;
+	}
+});
+
+//# sourceMappingURL=ManagementClientAuthError-ZJ2-RoKT.cjs.map

package/dist/ManagementClientAuthError-ZJ2-RoKT.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"ManagementClientAuthError-ZJ2-RoKT.cjs","names":["ApiError"],"sources":["../src/errors/ManagementClientAuthError.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.title = title;\n    this.message = message;\n  }\n}\n"],"mappings":";;AAIA,IAAa,4BAAb,cAA+CA,0BAAAA,SAAS;CACtD;CACA;CACA,YAAY,OAAe,SAAiB,KAAkB;EAC5D,MAAM,GAAG;EACT,KAAK,QAAQ;EACb,KAAK,UAAU;CACjB;AACF"}

package/dist/QueryJobTimeoutError-C7JbNGOM.js

@@ -0,0 +1,38 @@
+//#region src/errors/QueryJobError.ts
+/**
+* A query job that reached the API's terminal `failed` state — the submit/poll round-trip
+* succeeded, the job itself did not. Distinct from {@link ApiError}, which is an HTTP-level failure
+* of the submit/poll/results requests themselves.
+*/
+var QueryJobError = class QueryJobError extends Error {
+	queryJobId;
+	failedStatements;
+	constructor(message, queryJobId, { failedStatements }) {
+		super(message);
+		this.name = "QueryJobError";
+		this.queryJobId = queryJobId;
+		this.failedStatements = failedStatements;
+		Object.setPrototypeOf(this, QueryJobError.prototype);
+	}
+};
+const isQueryJobError = (error) => error instanceof QueryJobError;
+//#endregion
+//#region src/errors/QueryJobTimeoutError.ts
+/**
+* A query job that never reached a terminal state within the caller's `maxWaitTime` — the job may
+* still complete later; this only means `waitForJob`/`executeQuery` gave up watching it.
+*/
+var QueryJobTimeoutError = class QueryJobTimeoutError extends Error {
+	queryJobId;
+	constructor(message, queryJobId) {
+		super(message);
+		this.name = "QueryJobTimeoutError";
+		this.queryJobId = queryJobId;
+		Object.setPrototypeOf(this, QueryJobTimeoutError.prototype);
+	}
+};
+const isQueryJobTimeoutError = (error) => error instanceof QueryJobTimeoutError;
+//#endregion
+export { isQueryJobError as i, isQueryJobTimeoutError as n, QueryJobError as r, QueryJobTimeoutError as t };
+
+//# sourceMappingURL=QueryJobTimeoutError-C7JbNGOM.js.map

package/dist/QueryJobTimeoutError-C7JbNGOM.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"QueryJobTimeoutError-C7JbNGOM.js","names":[],"sources":["../src/errors/QueryJobError.ts","../src/errors/QueryJobTimeoutError.ts"],"sourcesContent":["type FailedStatement = {\n  id: string;\n  error?: string;\n};\n\ntype QueryJobErrorOptions = {\n  failedStatements: FailedStatement[];\n};\n\n/**\n * A query job that reached the API's terminal `failed` state — the submit/poll round-trip\n * succeeded, the job itself did not. Distinct from {@link ApiError}, which is an HTTP-level failure\n * of the submit/poll/results requests themselves.\n */\nexport class QueryJobError extends Error {\n  queryJobId: string;\n  failedStatements: FailedStatement[];\n\n  constructor(message: string, queryJobId: string, { failedStatements }: QueryJobErrorOptions) {\n    super(message);\n    this.name = 'QueryJobError';\n    this.queryJobId = queryJobId;\n    this.failedStatements = failedStatements;\n    Object.setPrototypeOf(this, QueryJobError.prototype);\n  }\n}\n\nexport const isQueryJobError = (error: unknown): error is QueryJobError =>\n  error instanceof QueryJobError;\n","/**\n * A query job that never reached a terminal state within the caller's `maxWaitTime` — the job may\n * still complete later; this only means `waitForJob`/`executeQuery` gave up watching it.\n */\nexport class QueryJobTimeoutError extends Error {\n  queryJobId: string;\n\n  constructor(message: string, queryJobId: string) {\n    super(message);\n    this.name = 'QueryJobTimeoutError';\n    this.queryJobId = queryJobId;\n    Object.setPrototypeOf(this, QueryJobTimeoutError.prototype);\n  }\n}\n\nexport const isQueryJobTimeoutError = (error: unknown): error is QueryJobTimeoutError =>\n  error instanceof QueryJobTimeoutError;\n"],"mappings":";;;;;;AAcA,IAAa,gBAAb,MAAa,sBAAsB,MAAM;CACvC;CACA;CAEA,YAAY,SAAiB,YAAoB,EAAE,oBAA0C;EAC3F,MAAM,OAAO;EACb,KAAK,OAAO;EACZ,KAAK,aAAa;EAClB,KAAK,mBAAmB;EACxB,OAAO,eAAe,MAAM,cAAc,SAAS;CACrD;AACF;AAEA,MAAa,mBAAmB,UAC9B,iBAAiB;;;;;;;ACxBnB,IAAa,uBAAb,MAAa,6BAA6B,MAAM;CAC9C;CAEA,YAAY,SAAiB,YAAoB;EAC/C,MAAM,OAAO;EACb,KAAK,OAAO;EACZ,KAAK,aAAa;EAClB,OAAO,eAAe,MAAM,qBAAqB,SAAS;CAC5D;AACF;AAEA,MAAa,0BAA0B,UACrC,iBAAiB"}