@databricks/appkit 0.51.0 → 0.53.0

package/docs/api/appkit/Function.createWorkspaceClient.md

@@ -0,0 +1,28 @@
+# Function: createWorkspaceClient()
+
+```ts
+function createWorkspaceClient(opts: WorkspaceClientOptions): WorkspaceClient;
+
+```
+
+Construct an AppKit workspace client.
+
+Auth resolution:
+
+* If `opts.token` is set, uses PAT credentials.
+* Otherwise walks the SDK default auth chain (env vars + \~/.databrickscfg).
+
+Host resolution:
+
+* Explicit `opts.host` → use it.
+* Otherwise resolved by the SDK from `DATABRICKS_HOST` / profile.
+
+## Parameters[​](#parameters "Direct link to Parameters")
+
+| Parameter | Type                                                                                    |
+| --------- | --------------------------------------------------------------------------------------- |
+| `opts`    | [`WorkspaceClientOptions`](./docs/api/appkit/Interface.WorkspaceClientOptions.md) |
+
+## Returns[​](#returns "Direct link to Returns")
+
+[`WorkspaceClient`](./docs/api/appkit/Interface.WorkspaceClient.md)

package/docs/api/appkit/Interface.WorkspaceClient.md

@@ -0,0 +1,119 @@
+# Interface: WorkspaceClient
+
+AppKit's workspace client facade. Mirrors the multi-client shape of the modular Databricks SDK: each service is its own accessor, so services can be migrated one at a time behind this stable interface.
+
+Accessors are legacy-typed for now (delegated to the underlying legacy SDK client); see the module docblock.
+
+## Properties[​](#properties "Direct link to Properties")
+
+### apiClient[​](#apiclient "Direct link to apiClient")
+
+```ts
+readonly apiClient: ApiClient;
+
+```
+
+Low-level HTTP transport (`apiClient.request(...)`). Used for endpoints without a typed service method: SCIM header probe, warehouse listing, serving SSE streaming, vector search, internal telemetry.
+
+***
+
+### config[​](#config "Direct link to config")
+
+```ts
+readonly config: Config;
+
+```
+
+SDK `Config` — exposes `host` and `authenticate(headers)`. Used by the files-upload path and agents auth-header stamping, which bypass the typed services.
+
+***
+
+### currentUser[​](#currentuser "Direct link to currentUser")
+
+```ts
+readonly currentUser: CurrentUserService;
+
+```
+
+Current user.
+
+***
+
+### files[​](#files "Direct link to files")
+
+```ts
+readonly files: FilesService;
+
+```
+
+UC Volumes / Files API.
+
+***
+
+### genie[​](#genie "Direct link to genie")
+
+```ts
+readonly genie: GenieService;
+
+```
+
+Genie / dashboards.
+
+***
+
+### jobs[​](#jobs "Direct link to jobs")
+
+```ts
+readonly jobs: JobsService;
+
+```
+
+Jobs.
+
+***
+
+### servingEndpoints[​](#servingendpoints "Direct link to servingEndpoints")
+
+```ts
+readonly servingEndpoints: ServingEndpointsService;
+
+```
+
+Serving Endpoints.
+
+***
+
+### statementExecution[​](#statementexecution "Direct link to statementExecution")
+
+```ts
+readonly statementExecution: StatementExecutionService;
+
+```
+
+Statement Execution.
+
+***
+
+### warehouses[​](#warehouses "Direct link to warehouses")
+
+```ts
+readonly warehouses: WarehousesService;
+
+```
+
+SQL Warehouses.
+
+## Methods[​](#methods "Direct link to Methods")
+
+### toLegacyWorkspaceClient()[​](#tolegacyworkspaceclient "Direct link to toLegacyWorkspaceClient()")
+
+```ts
+toLegacyWorkspaceClient(): WorkspaceClient;
+
+```
+
+Returns the underlying legacy `@databricks/sdk-experimental` `WorkspaceClient`, for handoff to code still typed against the old SDK (`@databricks/lakebase`). Transitional.
+
+#### Returns[​](#returns "Direct link to Returns")
+
+`WorkspaceClient`

package/docs/api/appkit/Interface.WorkspaceClientOptions.md

@@ -0,0 +1,47 @@
+# Interface: WorkspaceClientOptions
+
+Options used to construct the wrapper. Mirrors the subset of the old SDK's `Config` + `ClientOptions` that AppKit relies on today; we deliberately do NOT re-expose every old-SDK config knob.
+
+## Properties[​](#properties "Direct link to Properties")
+
+### authType?[​](#authtype "Direct link to authType?")
+
+```ts
+optional authType: "pat";
+
+```
+
+Authentication strategy passed to the legacy client.
+
+***
+
+### clientOptions?[​](#clientoptions "Direct link to clientOptions?")
+
+```ts
+optional clientOptions: ClientOptions;
+
+```
+
+SDK client options (product / productVersion / userAgentExtra) used to stamp the outbound User-Agent. Produced by `getClientOptions()`; omitted by build-time callers that don't stamp a User-Agent.
+
+***
+
+### host?[​](#host "Direct link to host?")
+
+```ts
+optional host: string;
+
+```
+
+Databricks host, e.g. <https://my-workspace.cloud.databricks.com>. Defaults to DATABRICKS\_HOST / profile resolution.
+
+***
+
+### token?[​](#token "Direct link to token?")
+
+```ts
+optional token: string;
+
+```
+
+Bearer token. When set, `authType` defaults to "pat".

package/docs/api/appkit.md

@@ -85,7 +85,9 @@ Documentation merge entry for Typedoc — combines the stable `@databricks/appki
 | [ToolkitOptions](./docs/api/appkit/Interface.ToolkitOptions.md)                                       | -                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
 | [ToolProvider](./docs/api/appkit/Interface.ToolProvider.md)                                           | -                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
 | [ValidationResult](./docs/api/appkit/Interface.ValidationResult.md)                                   | Result of validating all registered resources against the environment.                                                                                                                                                                                                                                                                                                                                                                                        |
+| [WorkspaceClient](./docs/api/appkit/Interface.WorkspaceClient.md)                                     | AppKit's workspace client facade. Mirrors the multi-client shape of the modular Databricks SDK: each service is its own accessor, so services can be migrated one at a time behind this stable interface.                                                                                                                                                                                                                                                     |
 | [WorkspaceClientLike](./docs/api/appkit/Interface.WorkspaceClientLike.md)                             | Structural shape of a Databricks SDK client used by [fromSupervisorApi](./docs/api/appkit/Function.fromSupervisorApi.md). Only what we need: `apiClient.request` for streaming and `config.ensureResolved` to materialise the host/credentials.                                                                                                                                                                                                         |
+| [WorkspaceClientOptions](./docs/api/appkit/Interface.WorkspaceClientOptions.md)                       | Options used to construct the wrapper. Mirrors the subset of the old SDK's `Config` + `ClientOptions` that AppKit relies on today; we deliberately do NOT re-expose every old-SDK config knob.                                                                                                                                                                                                                                                                |
 
 ## Type Aliases[​](#type-aliases "Direct link to Type Aliases")
 
@@ -136,6 +138,7 @@ Documentation merge entry for Typedoc — combines the stable `@databricks/appki
 | [createApp](./docs/api/appkit/Function.createApp.md)                                   | Bootstraps AppKit with the provided configuration.                                                                                                                                                                                                                                            |
 | [createLakebasePool](./docs/api/appkit/Function.createLakebasePool.md)                 | Create a Lakebase pool with appkit's logger integration. Telemetry automatically uses appkit's OpenTelemetry configuration via global registry.                                                                                                                                               |
 | [createLakebasePoolManager](./docs/api/appkit/Function.createLakebasePoolManager.md)   | Create a pool manager that maintains per-key Lakebase connection pools.                                                                                                                                                                                                                       |
+| [createWorkspaceClient](./docs/api/appkit/Function.createWorkspaceClient.md)           | Construct an AppKit workspace client.                                                                                                                                                                                                                                                         |
 | [defineTool](./docs/api/appkit/Function.defineTool.md)                                 | Defines a single tool entry for a plugin's internal registry.                                                                                                                                                                                                                                 |
 | [executeFromRegistry](./docs/api/appkit/Function.executeFromRegistry.md)               | Validates tool-call arguments against the entry's schema and invokes its handler. On validation failure, returns an LLM-friendly error string (matching the behavior of `tool()`) rather than throwing, so the model can self-correct on its next turn.                                       |
 | [extractServingEndpoints](./docs/api/appkit/Function.extractServingEndpoints.md)       | Extract serving endpoint config from a server file by AST-parsing it. Looks for `serving({ endpoints: { alias: { env: "..." }, ... } })` calls and extracts the endpoint alias names and their environment variable mappings.                                                                 |

package/docs/development/type-generation.md

@@ -84,7 +84,22 @@ npx @databricks/appkit generate-types --wait
 
 ```
 
-In blocking mode the generator starts a stopped warehouse, waits (bounded) for it to reach `RUNNING`, and then describes your queries. It fails only when the configured warehouse no longer exists (deleted/deleting), so a transient outage or a cold warehouse degrades gracefully rather than breaking the build. The app template wires this up for you: `postinstall` and `predev` run the non-blocking default, while `prebuild` runs `--wait`.
+#### CI resilience: committed types as fallback[​](#ci-resilience-committed-types-as-fallback "Direct link to CI resilience: committed types as fallback")
+
+In blocking mode (`--wait`), the generator attempts to fetch real types from your warehouse, but delegates to **committed `.d.ts` files** (`shared/appkit-types/analytics.d.ts`, `metric-views.d.ts`) as the fallback when the warehouse is unreachable. These committed files should be part of your repository. On a fresh CI checkout, every build attempts to DESCRIBE against the warehouse; the committed types are used only when that cannot complete.
+
+The generator **never overwrites committed types with degraded (`result: unknown`) types** — it writes real types, or it does not write at all.
+
+A **two-bucket failure taxonomy** determines whether the build crashes or falls back to committed types:
+
+* **Deterministic failures (always crash):** SQL syntax errors in your queries (genuine DESCRIBE failure against a reachable warehouse), HTTP 404 (bad or unknown warehouse ID), HTTP 400 (malformed request). These are developer or configuration errors that committed types must not hide.
+* **Environmental failures (gate on committed types):** Authentication failures (401/403), network unreachability, warehouse unavailability (cold, deleting, or deleted), wait timeout on `RUNNING`, or any unrecognized failure. If committed types exist, the build **keeps them, emits a loud warning to stderr, and succeeds (exit 0)**. If no committed types exist, the build **crashes** with a message instructing you to run `npx @databricks/appkit generate-types --wait` locally (against a reachable warehouse) and commit the `.d.ts` files.
+
+The loud warning is a single greppable stderr line naming the coarse cause (auth blocked / warehouse unreachable / warehouse unavailable) and the warehouse ID, so CI logs surface that the build fell back to committed types.
+
+**Note:** If your app declares only metric views and no `config/queries/`, the first build still writes an empty `analytics.d.ts`, which counts as "committed types present" for the gate. An environmental failure will then fall back and warn rather than crash, even on a first build — an accepted v1 simplification.
+
+The app template wires this up for you: `postinstall` and `predev` run the non-blocking default, while `prebuild` runs `--wait`.
 
 ## Metric-view types[​](#metric-view-types "Direct link to Metric-view types")
 
@@ -92,7 +107,7 @@ In blocking mode the generator starts a stopped warehouse, waits (bounded) for i
 
 * `metric-views.d.ts` — augments the `MetricRegistry` interface so `useMetricView('<key>', …)` is autocompleted and type-checked. Each view's measures, dimensions, and their semantic metadata (SQL type, display name, format, time grains) are encoded at the type level.
 
-If `config/metric-views/definitions.json` is absent the metric path stays dormant (nothing is emitted). When present it follows the **same** warehouse-readiness contract as query types: in the default non-blocking run a view that can't be described yet — a cold warehouse, or a bad/unreachable source — is written with permissive types and a warning, while under `--wait` that same situation fails the build so CI never ships incomplete metric types. A malformed `definitions.json` (invalid JSON, or a source that isn't a three-part UC FQN) fails fast in every mode.
+If `config/metric-views/definitions.json` is absent the metric path stays dormant (nothing is emitted). When present it follows the **same** warehouse-readiness contract as query types: in the default non-blocking run a view that can't be described yet — a cold warehouse, or a bad/unreachable source — is written with permissive types and a warning, while under `--wait` metric views obey the [two-bucket taxonomy](#ci-resilience-committed-types-as-fallback) (environmental failures gate to committed `metric-views.d.ts` + warn; deterministic failures like malformed definitions crash the build). A malformed `definitions.json` (invalid JSON, or a source that isn't a three-part UC FQN) fails fast in every mode.
 
 `definitions.json` is keyed by metric key; each entry names the three-part UC FQN of the view and, optionally, the executor it runs as (`app_service_principal`, the default, or `user`):
 

package/llms.txt

@@ -86,6 +86,7 @@ npx @databricks/appkit docs <query>
 - [Function: createApp()](./docs/api/appkit/Function.createApp.md): Bootstraps AppKit with the provided configuration.
 - [Function: createLakebasePool()](./docs/api/appkit/Function.createLakebasePool.md): Create a Lakebase pool with appkit's logger integration.
 - [Function: createLakebasePoolManager()](./docs/api/appkit/Function.createLakebasePoolManager.md): Create a pool manager that maintains per-key Lakebase connection pools.
+- [Function: createWorkspaceClient()](./docs/api/appkit/Function.createWorkspaceClient.md): Construct an AppKit workspace client.
 - [Function: defineTool()](./docs/api/appkit/Function.defineTool.md): Defines a single tool entry for a plugin's internal registry.
 - [Function: executeFromRegistry()](./docs/api/appkit/Function.executeFromRegistry.md): Validates tool-call arguments against the entry's schema and invokes its
 - [Function: extractServingEndpoints()](./docs/api/appkit/Function.extractServingEndpoints.md): Extract serving endpoint config from a server file by AST-parsing it.
@@ -165,7 +166,9 @@ npx @databricks/appkit docs <query>
 - [Interface: ToolkitOptions](./docs/api/appkit/Interface.ToolkitOptions.md): Properties
 - [Interface: ToolProvider](./docs/api/appkit/Interface.ToolProvider.md): Methods
 - [Interface: ValidationResult](./docs/api/appkit/Interface.ValidationResult.md): Result of validating all registered resources against the environment.
+- [Interface: WorkspaceClient](./docs/api/appkit/Interface.WorkspaceClient.md): AppKit's workspace client facade. Mirrors the multi-client shape of the
 - [Interface: WorkspaceClientLike](./docs/api/appkit/Interface.WorkspaceClientLike.md): Structural shape of a Databricks SDK client used by fromSupervisorApi.
+- [Interface: WorkspaceClientOptions](./docs/api/appkit/Interface.WorkspaceClientOptions.md): Options used to construct the wrapper. Mirrors the subset of the old SDK's
 - [Type Alias: AgentEvent](./docs/api/appkit/TypeAlias.AgentEvent.md): Type Declaration
 - [Type Alias: AgentTool](./docs/api/appkit/TypeAlias.AgentTool.md): Any tool an agent can invoke: inline function tools (tool()), hosted MCP
 - [Type Alias: AgentTools](./docs/api/appkit/TypeAlias.AgentTools.md): Per-agent tool record. String keys map to inline tools, toolkit entries,

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@databricks/appkit",
   "type": "module",
-  "version": "0.51.0",
+  "version": "0.53.0",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "bin": {