@keboola/api-client 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Keboola s.r.o.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,456 @@
+# @keboola/api-client
+
+TypeScript SDK for Keboola APIs. Provides typed clients for all Keboola platform services.
+
+## Installation
+
+```bash
+npm install @keboola/api-client
+```
+
+## Quick Start
+
+### Full client initialization (browser)
+
+```typescript
+import { createApiClient } from '@keboola/api-client';
+
+const api = createApiClient();
+
+await api.init({
+  baseUrl: 'https://connection.keboola.com',
+  token: {
+    storageApi: 'your-storage-token',
+    managementApi: 'your-management-token', // optional
+  },
+  assetsBaseUrl: 'https://assets.keboola.com',
+  statusBaseUrl: 'https://status.keboola.com',
+  metastoreBaseUrl: 'https://metastore.keboola.com',
+  callbacks: {
+    onError: (error) => console.error('API Error:', error),
+    onSuccess: () => {},
+    onSettled: () => {},
+  },
+});
+
+const tables = await api.storage.tables.list();
+const jobs = await api.queue.searchJobs();
+```
+
+### Individual client (Node.js)
+
+```typescript
+import { createStorageClient, createStorageTokenMiddleware } from '@keboola/api-client/storage';
+
+const tokenMiddleware = createStorageTokenMiddleware('your-storage-token');
+const storage = createStorageClient({
+  baseUrl: 'https://connection.keboola.com',
+  middlewares: [tokenMiddleware],
+});
+
+const stackInfo = await storage.getStackInfo();
+const files = await storage.files.list();
+```
+
+### Type imports
+
+```typescript
+import type { ApiClientOptions, ApiClient } from '@keboola/api-client';
+import type { StackInfo, ServiceId } from '@keboola/api-client/storage/types';
+import type { GetQueueJobPath } from '@keboola/api-client/queue/types';
+import type { VariableWithHash } from '@keboola/api-client/vault/types';
+```
+
+## Architecture
+
+```
+src/
+  client.ts                     # createApiClient() factory — top-level entry
+  devClient.ts                  # Lightweight dev/verify client
+  constants.ts                  # HTTP headers, prefixes
+  fetchClient/
+    createFetchClient/          # Core fetch wrapper, middleware composition
+    createGenericFetchClient.ts # Untyped HTTP client (manual generics)
+    createOpenapiFetchClient.ts # Typed HTTP client (from OpenAPI schemas)
+    types.ts                    # OpenAPI type-level helpers
+  clients/
+    storage/                    # Storage API (buckets, tables, files, branches, ...)
+    management/                 # Management API (projects, features, users)
+    vault/                      # Vault secrets
+    dataScience/                # Data apps, sandboxes, runtimes
+    editor/                     # SQL sessions, queries
+    encryption/                 # Value/secret encryption
+    chat/                       # Kai Assistant chat
+    kaiAgent/                   # Kai Agent (agentic assistant)
+    ai/                         # AI describe/explain/suggest
+    queue/                      # Job Queue
+    queryService/               # SQL query service
+    syncActions/                # Sync actions, MFA, git repos
+    telemetry/                  # Telemetry provisioning
+    metastore/                  # Metastore repository/schema
+    assets/                     # Platform changelog
+    status/                     # Status page summary
+    import/                     # File upload
+    verify/                     # Token verification
+  domain/
+    stack.ts                    # Stack info, service discovery, feature flags
+    project.ts                  # Project info, backend/feature checks
+  sdks/
+    tag/                        # High-level tag CRUD (composes metastore client)
+  errors/
+    ApiError.ts                 # HTTP error with response/request/data
+    UserError.ts                # User-facing validation error
+    ServiceUnavailableError.ts  # Service not available in current stack
+    ManagementClientAuthError.ts
+  utils/
+    concurrent.ts               # Concurrent task runner with middleware
+    series.ts                   # Sequential task runner
+    poll.ts                     # Polling with isDone/isFailed predicates
+    delay.ts                    # Abortable delay
+    keboolaUID.ts               # Keboola object ID serialization
+    generateUUID.ts             # crypto.randomUUID wrapper
+    assert.ts                   # Runtime assertions
+```
+
+## Service Clients
+
+After calling `api.init(...)`, the following clients are available on the `api` object.
+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.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.assets`       | Assets                  | `getPublishedChangelogPosts()`                                                                                                                                                  |
+| `api.status`       | Status                  | `getSummary()`                                                                                                                                                                  |
+| `api.import`       | Import                  | `uploadFile()`                                                                                                                                                                  |
+
+Additional accessors on the initialized client:
+
+| Accessor          | Purpose                                                                                                                                            |
+| ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `api.stack`       | Stack info: `hasFeature()`, `hasService()`, `getServiceUrl()`, `hasComponent()`, `getComponent()`, `services`, `features`, `components`            |
+| `api.project`     | Project info: `hasFeature()`, `hasAdminFeature()`, `hasBackend()`, `sapiToken`                                                                     |
+| `api.sdk.tag`     | Tag SDK: `getTags()`, `getTagsByObjectId()`, `createTag()`, `updateTag()`, `deleteTag()`, `assignTags()`, `unassignTags()`, `createAndAssignTag()` |
+| `api.serviceMeta` | Service availability metadata from the registry                                                                                                    |
+
+## Entry Points
+
+```typescript
+// Main entry — full ApiClient + all exports
+import { createApiClient, isApiError, concurrent, poll } from '@keboola/api-client';
+
+// Per-client imports — individual client factories
+import { createStorageClient } from '@keboola/api-client/storage';
+import { createVerifyClient } from '@keboola/api-client/verify';
+
+// Per-service type imports (tree-shakeable)
+import type { StackInfo } from '@keboola/api-client/storage/types';
+import type { GetQueueJobPath } from '@keboola/api-client/queue/types';
+```
+
+## Error Handling
+
+```typescript
+import {
+  isApiError,
+  isFetchClientError,
+  isAbortError,
+  ApiError,
+  UserError,
+  ServiceUnavailableError,
+} from '@keboola/api-client';
+
+try {
+  await api.storage.tables.list();
+} catch (error) {
+  if (isApiError(error)) {
+    // HTTP error — has response, request, and parsed data
+    console.error(error.response.status, error.data);
+  } else if (isFetchClientError(error)) {
+    // Network-level error
+    console.error(error.message);
+  } else if (isAbortError(error)) {
+    // Request was aborted via AbortSignal
+  } else if (error instanceof ServiceUnavailableError) {
+    // Service not available in the current stack
+  } else if (error instanceof UserError) {
+    // Validation error safe to show to end users
+  }
+}
+```
+
+## Middleware
+
+Middleware functions wrap every HTTP request. They execute in registration order (first registered = outermost).
+
+```typescript
+import type { MiddlewareFn } from '@keboola/api-client';
+
+const loggingMiddleware: MiddlewareFn = (next) => async (request) => {
+  console.log('Request:', request.url);
+  const response = await next(request);
+  console.log('Response:', response.response.status);
+  return response;
+};
+```
+
+### Callback middleware
+
+The built-in callback middleware provides `onError`, `onSuccess`, and `onSettled` hooks:
+
+```typescript
+import { createApiClient } from '@keboola/api-client';
+
+const api = createApiClient();
+await api.init({
+  baseUrl: 'https://connection.keboola.com',
+  token: { storageApi: 'your-token' },
+  assetsBaseUrl: 'https://assets.keboola.com',
+  statusBaseUrl: 'https://status.keboola.com',
+  metastoreBaseUrl: 'https://metastore.keboola.com',
+  callbacks: {
+    onError: (error) => {
+      /* handle error */
+    },
+    onSuccess: () => {
+      /* e.g. reset idle timer */
+    },
+    onSettled: () => {
+      /* e.g. hide loading indicator */
+    },
+  },
+});
+```
+
+## Utilities
+
+### concurrent / series
+
+```typescript
+import { concurrent, series } from '@keboola/api-client';
+
+// Process items with concurrency limit (default: 2)
+const results = await concurrent({
+  items: ['a', 'b', 'c', 'd'],
+  process: async (item) => fetchData(item),
+  concurrency: 3,
+});
+
+// Process items one at a time
+const ordered = await series({
+  items: ['a', 'b', 'c'],
+  process: async (item) => fetchData(item),
+});
+```
+
+### poll
+
+```typescript
+import { poll, PollException } from '@keboola/api-client';
+
+const controller = new AbortController();
+
+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);
+  }
+}
+```
+
+### keboolaUID
+
+```typescript
+import { keboolaUID } from '@keboola/api-client';
+
+const uid = keboolaUID.serialize({
+  type: 'table',
+  projectId: 123,
+  uid: 'in.c-main.users',
+});
+// "KID--123--table--in.c-main.users"
+
+const parsed = keboolaUID.deserialize(uid);
+// { type: 'table', projectId: 123, uid: 'in.c-main.users' }
+```
+
+### Other utilities
+
+```typescript
+import { delay, generateUUID, assert } from '@keboola/api-client';
+
+// Abortable delay
+await delay(1000, abortSignal);
+
+// crypto.randomUUID wrapper
+const id = generateUUID();
+
+// Runtime assertion (throws if falsy)
+assert(value, 'value must be defined');
+```
+
+## React Bindings
+
+React bindings (provider, hooks, query integration) are in the separate `@keboola/api-client-react` package.
+
+```typescript
+import { ApiClientProvider, useApiClient } from '@keboola/api-client-react';
+```
+
+## License
+
+MIT. See [LICENSE](./LICENSE).
+
+---
+
+## Contributing
+
+Internal guide for adding new service clients to this package.
+
+### Adding a New OpenAPI Client
+
+#### Step 1: Register the API in `redocly.yaml`
+
+Add your API specification to the `redocly.yaml` file:
+
+```yaml
+apis:
+  # Existing APIs...
+  yourNewService:
+    root: https://your-service.keboola.com/docs/swagger.yaml
+    x-openapi-ts:
+      output: ./src/clients/yourNewService/__generated__/schema.d.ts
+```
+
+#### Step 2: Generate Types
+
+Run the type generation command:
+
+```bash
+yarn gen:types
+```
+
+This will create the TypeScript definitions at the specified output path.
+
+#### Step 3: Create the Client Implementation
+
+Create `src/clients/yourNewService/yourNewServiceClient.ts`:
+
+```typescript
+import { createOpenapiFetchClient } from '../../fetchClient';
+import type { ClientInitOptions } from '../types';
+
+import type { paths } from './__generated__/schema';
+
+export const createYourNewServiceClient = ({ baseUrl, middlewares }: ClientInitOptions) => {
+  const client = createOpenapiFetchClient<paths>({
+    baseUrl,
+    middlewares,
+  });
+
+  const listItems = async (signal?: AbortSignal) => {
+    const { data } = await client.get('/items', {}, { signal });
+    return data;
+  };
+
+  return {
+    listItems,
+  };
+};
+```
+
+#### Step 4: Create the Types Export File
+
+Create `src/clients/yourNewService/types.ts` to re-export all types:
+
+```typescript
+export type * from './__generated__/schema';
+export type { YourNewServiceClient } from './yourNewServiceClient';
+```
+
+#### Step 5: Create the Index File
+
+Create `src/clients/yourNewService/index.ts`:
+
+```typescript
+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`:
+
+```json
+{
+  "exports": {
+    "./types/yourNewService": {
+      "import": {
+        "types": "./dist/types/yourNewService.d.ts",
+        "default": "./dist/types/yourNewService.js"
+      },
+      "require": {
+        "types": "./dist/types/yourNewService.d.cts",
+        "default": "./dist/types/yourNewService.cjs"
+      }
+    }
+  }
+}
+```
+
+#### Step 7: Integrate with Main ApiClient
+
+Update `src/client.ts` to register the client in the `createServiceClientRegistry` call:
+
+```typescript
+import { createYourNewServiceClient } from './clients/yourNewService';
+
+// Inside createClients, add to the clients array:
+{
+  serviceId: 'your-service',
+  clientName: 'yourNewService',
+  clientFn: (serviceBaseUrl) =>
+    createYourNewServiceClient({ baseUrl: serviceBaseUrl, middlewares: commonMiddlewares }),
+},
+```
+
+### Adding a New Generic Client
+
+Follow the same steps but use `createGenericFetchClient` instead of `createOpenapiFetchClient`. No `redocly.yaml` registration or `yarn gen:types` step is needed. Define request/response types manually.
+
+### OpenAPI Type Generation Workflow
+
+1. Update API specifications (if needed, edit `redocly.yaml`)
+2. Run `yarn gen:types` to regenerate TypeScript definitions
+3. Review generated files in `__generated__/` directories
+4. Update client implementation if the API surface changed
+5. Always commit generated files to version control
+
+### redocly.yaml Configuration Reference
+
+```yaml
+apis:
+  serviceName:
+    root: https://api.example.com/swagger.yaml
+    x-openapi-ts:
+      output: ./src/clients/serviceName/__generated__/schema.d.ts
+```

package/dist/ai/index.cjs

@@ -0,0 +1,203 @@
+'use strict';
+
+var qs = require('qs');
+
+function _interopDefault (e) { return e && e.__esModule ? e : { default: e }; }
+
+var qs__default = /*#__PURE__*/_interopDefault(qs);
+
+// src/errors/ApiError.ts
+var ApiError = class extends Error {
+  response;
+  request;
+  data;
+  constructor({ response, request, data }) {
+    super(response.statusText);
+    this.response = response;
+    this.request = request;
+    this.data = data;
+  }
+};
+var HttpHeader = {
+  CONTENT_TYPE: "content-type"};
+var HttpContentType = {
+  JSON: "application/json"};
+var defaultValidateStatus = ({ response }) => response.status >= 200 && response.status <= 299;
+function removeUndefined(obj) {
+  const objCopy = { ...obj };
+  for (const [key, value] of Object.entries(objCopy)) {
+    if (value == null) delete objCopy[key];
+  }
+  return objCopy;
+}
+var parseData = async (response) => {
+  if (response.status === 204) return null;
+  const contentType = response.headers.get(HttpHeader.CONTENT_TYPE);
+  if (contentType && contentType == HttpContentType.JSON) {
+    return response.json();
+  }
+  const text = await response.text();
+  try {
+    return JSON.parse(text);
+  } catch {
+    return text;
+  }
+};
+var cleanHeadersInit = (headersInit) => {
+  if (Array.isArray(headersInit)) return headersInit;
+  if (headersInit instanceof Headers) return headersInit;
+  if (headersInit == null) return headersInit;
+  return removeUndefined(headersInit);
+};
+var createHeaders = (headersInitA, headersInitB) => {
+  const headersA = new Headers(cleanHeadersInit(headersInitA));
+  const headersB = new Headers(cleanHeadersInit(headersInitB));
+  headersB.forEach((value, key) => {
+    headersA.set(key, value);
+  });
+  return headersA;
+};
+var createPath = (path, pathParam = {}) => path.replace(/\{([^}]+)}/g, (_, key) => {
+  if (!(key in pathParam))
+    throw new Error(`Path parameter "${key}" is missing in the path "${path}"`);
+  return encodeURIComponent(pathParam[key]);
+});
+var createSearch = (query, options = {}) => {
+  return qs__default.default.stringify(query, {
+    encodeValuesOnly: true,
+    skipNulls: true,
+    ...options
+  });
+};
+var createBody = (body, headers) => {
+  if (body == null) return null;
+  if (body instanceof FormData) return body;
+  if (typeof body === "string") return body;
+  const stringifyBody = JSON.stringify(body);
+  const stringBody = stringifyBody === "{}" ? null : stringifyBody;
+  if (stringBody) headers.set(HttpHeader.CONTENT_TYPE, HttpContentType.JSON);
+  return stringBody;
+};
+var createFetchRequest = ({
+  url,
+  method,
+  params,
+  options = {},
+  defaultOptions
+}) => {
+  const {
+    baseUrl,
+    validateStatus: defValidateStatus = defaultValidateStatus,
+    headers: defaultHeaders,
+    ...restDefaultOptions
+  } = defaultOptions;
+  const { validateStatus, queryArrayFormat, headers: endpointHeaders, ...restOptions } = options;
+  const headers = createHeaders(defaultHeaders, endpointHeaders);
+  const path = createPath(url, params.path);
+  const search = createSearch(params.query ?? {}, { arrayFormat: queryArrayFormat });
+  const body = createBody(params.body, headers);
+  const urlInstance = new URL(baseUrl + path);
+  urlInstance.search = search;
+  const request = new Request(urlInstance, {
+    ...restDefaultOptions,
+    ...restOptions,
+    headers,
+    method: method.toUpperCase(),
+    body
+  });
+  return { request, validateStatus: validateStatus ?? defValidateStatus };
+};
+
+// src/fetchClient/createFetchClient/createFetchClient.ts
+var isApiError = (error) => error instanceof ApiError;
+var createCoreFetch = (fetchFn) => async ({ request, validateStatus }) => {
+  const response = await fetchFn(request);
+  const data = await parseData(response);
+  const apiResponse = {
+    request,
+    response,
+    data
+  };
+  const boolOrError = validateStatus(apiResponse);
+  if (isApiError(boolOrError)) throw boolOrError;
+  if (!boolOrError) throw new ApiError(apiResponse);
+  return apiResponse;
+};
+var createFetchClient = ({
+  middlewares = [],
+  ...defaultOptions
+}) => {
+  const coreFetch = createCoreFetch(defaultOptions.fetchFn ?? fetch);
+  const fetchWithMiddlewares = middlewares.reduceRight(
+    (next, middleware) => middleware(next),
+    coreFetch
+  );
+  const createFetchMethod = (method) => async (url, params, options = {}) => {
+    const request = createFetchRequest({
+      url,
+      method,
+      params,
+      defaultOptions,
+      options
+    });
+    const methodMiddlewares = options?.middlewares ?? [];
+    return methodMiddlewares.reduceRight(
+      (next, middleware) => middleware(next),
+      fetchWithMiddlewares
+    )(request);
+  };
+  return {
+    get: createFetchMethod("get"),
+    post: createFetchMethod("post"),
+    put: createFetchMethod("put"),
+    patch: createFetchMethod("patch"),
+    delete: createFetchMethod("delete")
+  };
+};
+
+// src/fetchClient/createOpenapiFetchClient.ts
+var createOpenapiFetchClient = (defaultOptions) => createFetchClient(defaultOptions);
+
+// src/clients/ai/aiClient.ts
+var createAiClient = ({ baseUrl, middlewares }) => {
+  const client = createOpenapiFetchClient({
+    baseUrl,
+    middlewares
+  });
+  const describeConfigurationVersion = async (body) => {
+    const { data } = await client.post("/describe/configuration-version", { body });
+    return data;
+  };
+  const describeConfigurationMerge = async (body) => {
+    const { data } = await client.post("/describe/configuration-merge", { body });
+    return data;
+  };
+  const explainError = async (body) => {
+    const { data } = await client.post("/explain", { body });
+    return data;
+  };
+  const describeConfiguration = async (body) => {
+    const { data } = await client.post("/describe/configuration", { body });
+    return data;
+  };
+  const suggestComponent = async (body) => {
+    const { data } = await client.post("/suggest/component", { body });
+    return data;
+  };
+  const feedback = async (body) => {
+    const { data } = await client.post("/feedback", { body });
+    return data;
+  };
+  return {
+    describeConfigurationVersion,
+    describeConfigurationMerge,
+    explainError,
+    describeConfiguration,
+    suggestComponent,
+    feedback
+  };
+};
+
+exports.createAiClient = createAiClient;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map