@databricks/appkit 0.43.1 → 0.45.0

package/docs/api/appkit/Class.ConfigurationError.md

@@ -21,6 +21,7 @@ throw new ConfigurationError("Warehouse ID not found", { context: { env: "produc
 ```ts
 new ConfigurationError(message: string, options?: {
   cause?: Error;
+  clientMessage?: string;
   context?: Record<string, unknown>;
 }): ConfigurationError;
 
@@ -28,12 +29,13 @@ new ConfigurationError(message: string, options?: {
 
 #### Parameters[​](#parameters "Direct link to Parameters")
 
-| Parameter          | Type                                                              |
-| ------------------ | ----------------------------------------------------------------- |
-| `message`          | `string`                                                          |
-| `options?`         | { `cause?`: `Error`; `context?`: `Record`<`string`, `unknown`>; } |
-| `options.cause?`   | `Error`                                                           |
-| `options.context?` | `Record`<`string`, `unknown`>                                     |
+| Parameter                | Type                                                                                          |
+| ------------------------ | --------------------------------------------------------------------------------------------- |
+| `message`                | `string`                                                                                      |
+| `options?`               | { `cause?`: `Error`; `clientMessage?`: `string`; `context?`: `Record`<`string`, `unknown`>; } |
+| `options.cause?`         | `Error`                                                                                       |
+| `options.clientMessage?` | `string`                                                                                      |
+| `options.context?`       | `Record`<`string`, `unknown`>                                                                 |
 
 #### Returns[​](#returns "Direct link to Returns")
 
@@ -45,6 +47,23 @@ new ConfigurationError(message: string, options?: {
 
 ## Properties[​](#properties "Direct link to Properties")
 
+### \_clientMessage?[​](#_clientmessage "Direct link to _clientMessage?")
+
+```ts
+protected readonly optional _clientMessage: string;
+
+```
+
+Client-safe error message. When set, callers serializing the error to a client (SSE, HTTP body) MUST prefer `clientMessage` over `message` — `message` may contain raw upstream / SDK text including statement fragments, internal object names, and correlation IDs.
+
+Subclasses can set this in their constructor for a fixed sanitized string. When unset, `clientMessage` defaults to a generic per-code string (see the getter), and the raw `message` is kept server-side only.
+
+#### Inherited from[​](#inherited-from-1 "Direct link to Inherited from")
+
+[`AppKitError`](./docs/api/appkit/Class.AppKitError.md).[`_clientMessage`](./docs/api/appkit/Class.AppKitError.md#_clientmessage)
+
+***
+
 ### cause?[​](#cause "Direct link to cause?")
 
 ```ts
@@ -54,7 +73,7 @@ readonly optional cause: Error;
 
 Optional cause of the error
 
-#### Inherited from[​](#inherited-from-1 "Direct link to Inherited from")
+#### Inherited from[​](#inherited-from-2 "Direct link to Inherited from")
 
 [`AppKitError`](./docs/api/appkit/Class.AppKitError.md).[`cause`](./docs/api/appkit/Class.AppKitError.md#cause)
 
@@ -84,7 +103,7 @@ readonly optional context: Record<string, unknown>;
 
 Additional context for the error
 
-#### Inherited from[​](#inherited-from-2 "Direct link to Inherited from")
+#### Inherited from[​](#inherited-from-3 "Direct link to Inherited from")
 
 [`AppKitError`](./docs/api/appkit/Class.AppKitError.md).[`context`](./docs/api/appkit/Class.AppKitError.md#context)
 
@@ -118,6 +137,27 @@ HTTP status code suggestion (can be overridden)
 
 [`AppKitError`](./docs/api/appkit/Class.AppKitError.md).[`statusCode`](./docs/api/appkit/Class.AppKitError.md#statuscode)
 
+## Accessors[​](#accessors "Direct link to Accessors")
+
+### clientMessage[​](#clientmessage "Direct link to clientMessage")
+
+#### Get Signature[​](#get-signature "Direct link to Get Signature")
+
+```ts
+get clientMessage(): string;
+
+```
+
+Sanitized message safe to forward to clients. Override in subclasses if a more specific default is appropriate.
+
+##### Returns[​](#returns-1 "Direct link to Returns")
+
+`string`
+
+#### Inherited from[​](#inherited-from-4 "Direct link to Inherited from")
+
+[`AppKitError`](./docs/api/appkit/Class.AppKitError.md).[`clientMessage`](./docs/api/appkit/Class.AppKitError.md#clientmessage)
+
 ## Methods[​](#methods "Direct link to Methods")
 
 ### toJSON()[​](#tojson "Direct link to toJSON()")
@@ -129,11 +169,11 @@ toJSON(): Record<string, unknown>;
 
 Convert error to JSON for logging/serialization. Sensitive values in context are automatically redacted.
 
-#### Returns[​](#returns-1 "Direct link to Returns")
+#### Returns[​](#returns-2 "Direct link to Returns")
 
 `Record`<`string`, `unknown`>
 
-#### Inherited from[​](#inherited-from-3 "Direct link to Inherited from")
+#### Inherited from[​](#inherited-from-5 "Direct link to Inherited from")
 
 [`AppKitError`](./docs/api/appkit/Class.AppKitError.md).[`toJSON`](./docs/api/appkit/Class.AppKitError.md#tojson)
 
@@ -148,11 +188,11 @@ toString(): string;
 
 Create a human-readable string representation
 
-#### Returns[​](#returns-2 "Direct link to Returns")
+#### Returns[​](#returns-3 "Direct link to Returns")
 
 `string`
 
-#### Inherited from[​](#inherited-from-4 "Direct link to Inherited from")
+#### Inherited from[​](#inherited-from-6 "Direct link to Inherited from")
 
 [`AppKitError`](./docs/api/appkit/Class.AppKitError.md).[`toString`](./docs/api/appkit/Class.AppKitError.md#tostring)
 
@@ -179,7 +219,7 @@ By default the message is short; key lines use **picocolors** when the terminal
 | `options?`       | { `cause?`: `Error`; } |
 | `options.cause?` | `Error`                |
 
-#### Returns[​](#returns-3 "Direct link to Returns")
+#### Returns[​](#returns-4 "Direct link to Returns")
 
 `ConfigurationError`
 
@@ -201,7 +241,7 @@ Create a configuration error for invalid connection config
 | `service`  | `string` |
 | `details?` | `string` |
 
-#### Returns[​](#returns-4 "Direct link to Returns")
+#### Returns[​](#returns-5 "Direct link to Returns")
 
 `ConfigurationError`
 
@@ -222,7 +262,7 @@ Create a configuration error for missing connection string parameter
 | --------- | -------- |
 | `param`   | `string` |
 
-#### Returns[​](#returns-5 "Direct link to Returns")
+#### Returns[​](#returns-6 "Direct link to Returns")
 
 `ConfigurationError`
 
@@ -243,7 +283,7 @@ Create a configuration error for missing environment variable
 | --------- | -------- |
 | `varName` | `string` |
 
-#### Returns[​](#returns-6 "Direct link to Returns")
+#### Returns[​](#returns-7 "Direct link to Returns")
 
 `ConfigurationError`
 
@@ -265,6 +305,6 @@ Create a configuration error for missing resource
 | `resource` | `string` |
 | `hint?`    | `string` |
 
-#### Returns[​](#returns-7 "Direct link to Returns")
+#### Returns[​](#returns-8 "Direct link to Returns")
 
 `ConfigurationError`

package/docs/api/appkit/Class.ConnectionError.md

@@ -21,6 +21,7 @@ throw new ConnectionError("No response received from SQL Warehouse API");
 ```ts
 new ConnectionError(message: string, options?: {
   cause?: Error;
+  clientMessage?: string;
   context?: Record<string, unknown>;
 }): ConnectionError;
 
@@ -28,12 +29,13 @@ new ConnectionError(message: string, options?: {
 
 #### Parameters[​](#parameters "Direct link to Parameters")
 
-| Parameter          | Type                                                              |
-| ------------------ | ----------------------------------------------------------------- |
-| `message`          | `string`                                                          |
-| `options?`         | { `cause?`: `Error`; `context?`: `Record`<`string`, `unknown`>; } |
-| `options.cause?`   | `Error`                                                           |
-| `options.context?` | `Record`<`string`, `unknown`>                                     |
+| Parameter                | Type                                                                                          |
+| ------------------------ | --------------------------------------------------------------------------------------------- |
+| `message`                | `string`                                                                                      |
+| `options?`               | { `cause?`: `Error`; `clientMessage?`: `string`; `context?`: `Record`<`string`, `unknown`>; } |
+| `options.cause?`         | `Error`                                                                                       |
+| `options.clientMessage?` | `string`                                                                                      |
+| `options.context?`       | `Record`<`string`, `unknown`>                                                                 |
 
 #### Returns[​](#returns "Direct link to Returns")
 
@@ -45,6 +47,23 @@ new ConnectionError(message: string, options?: {
 
 ## Properties[​](#properties "Direct link to Properties")
 
+### \_clientMessage?[​](#_clientmessage "Direct link to _clientMessage?")
+
+```ts
+protected readonly optional _clientMessage: string;
+
+```
+
+Client-safe error message. When set, callers serializing the error to a client (SSE, HTTP body) MUST prefer `clientMessage` over `message` — `message` may contain raw upstream / SDK text including statement fragments, internal object names, and correlation IDs.
+
+Subclasses can set this in their constructor for a fixed sanitized string. When unset, `clientMessage` defaults to a generic per-code string (see the getter), and the raw `message` is kept server-side only.
+
+#### Inherited from[​](#inherited-from-1 "Direct link to Inherited from")
+
+[`AppKitError`](./docs/api/appkit/Class.AppKitError.md).[`_clientMessage`](./docs/api/appkit/Class.AppKitError.md#_clientmessage)
+
+***
+
 ### cause?[​](#cause "Direct link to cause?")
 
 ```ts
@@ -54,7 +73,7 @@ readonly optional cause: Error;
 
 Optional cause of the error
 
-#### Inherited from[​](#inherited-from-1 "Direct link to Inherited from")
+#### Inherited from[​](#inherited-from-2 "Direct link to Inherited from")
 
 [`AppKitError`](./docs/api/appkit/Class.AppKitError.md).[`cause`](./docs/api/appkit/Class.AppKitError.md#cause)
 
@@ -84,7 +103,7 @@ readonly optional context: Record<string, unknown>;
 
 Additional context for the error
 
-#### Inherited from[​](#inherited-from-2 "Direct link to Inherited from")
+#### Inherited from[​](#inherited-from-3 "Direct link to Inherited from")
 
 [`AppKitError`](./docs/api/appkit/Class.AppKitError.md).[`context`](./docs/api/appkit/Class.AppKitError.md#context)
 
@@ -118,6 +137,27 @@ HTTP status code suggestion (can be overridden)
 
 [`AppKitError`](./docs/api/appkit/Class.AppKitError.md).[`statusCode`](./docs/api/appkit/Class.AppKitError.md#statuscode)
 
+## Accessors[​](#accessors "Direct link to Accessors")
+
+### clientMessage[​](#clientmessage "Direct link to clientMessage")
+
+#### Get Signature[​](#get-signature "Direct link to Get Signature")
+
+```ts
+get clientMessage(): string;
+
+```
+
+Sanitized message safe to forward to clients. Override in subclasses if a more specific default is appropriate.
+
+##### Returns[​](#returns-1 "Direct link to Returns")
+
+`string`
+
+#### Inherited from[​](#inherited-from-4 "Direct link to Inherited from")
+
+[`AppKitError`](./docs/api/appkit/Class.AppKitError.md).[`clientMessage`](./docs/api/appkit/Class.AppKitError.md#clientmessage)
+
 ## Methods[​](#methods "Direct link to Methods")
 
 ### toJSON()[​](#tojson "Direct link to toJSON()")
@@ -129,11 +169,11 @@ toJSON(): Record<string, unknown>;
 
 Convert error to JSON for logging/serialization. Sensitive values in context are automatically redacted.
 
-#### Returns[​](#returns-1 "Direct link to Returns")
+#### Returns[​](#returns-2 "Direct link to Returns")
 
 `Record`<`string`, `unknown`>
 
-#### Inherited from[​](#inherited-from-3 "Direct link to Inherited from")
+#### Inherited from[​](#inherited-from-5 "Direct link to Inherited from")
 
 [`AppKitError`](./docs/api/appkit/Class.AppKitError.md).[`toJSON`](./docs/api/appkit/Class.AppKitError.md#tojson)
 
@@ -148,11 +188,11 @@ toString(): string;
 
 Create a human-readable string representation
 
-#### Returns[​](#returns-2 "Direct link to Returns")
+#### Returns[​](#returns-3 "Direct link to Returns")
 
 `string`
 
-#### Inherited from[​](#inherited-from-4 "Direct link to Inherited from")
+#### Inherited from[​](#inherited-from-6 "Direct link to Inherited from")
 
 [`AppKitError`](./docs/api/appkit/Class.AppKitError.md).[`toString`](./docs/api/appkit/Class.AppKitError.md#tostring)
 
@@ -174,7 +214,7 @@ Create a connection error for API failures
 | `service` | `string` |
 | `cause?`  | `Error`  |
 
-#### Returns[​](#returns-3 "Direct link to Returns")
+#### Returns[​](#returns-4 "Direct link to Returns")
 
 `ConnectionError`
 
@@ -196,7 +236,7 @@ Create a connection error for client unavailable
 | `clientType` | `string` |
 | `hint?`      | `string` |
 
-#### Returns[​](#returns-4 "Direct link to Returns")
+#### Returns[​](#returns-5 "Direct link to Returns")
 
 `ConnectionError`
 
@@ -218,7 +258,7 @@ Create a connection error for pool errors
 | `operation` | `string` |
 | `cause?`    | `Error`  |
 
-#### Returns[​](#returns-5 "Direct link to Returns")
+#### Returns[​](#returns-6 "Direct link to Returns")
 
 `ConnectionError`
 
@@ -239,7 +279,7 @@ Create a connection error for query failure
 | --------- | ------- |
 | `cause?`  | `Error` |
 
-#### Returns[​](#returns-6 "Direct link to Returns")
+#### Returns[​](#returns-7 "Direct link to Returns")
 
 `ConnectionError`
 
@@ -260,6 +300,6 @@ Create a connection error for transaction failure
 | --------- | ------- |
 | `cause?`  | `Error` |
 
-#### Returns[​](#returns-7 "Direct link to Returns")
+#### Returns[​](#returns-8 "Direct link to Returns")
 
 `ConnectionError`

package/docs/api/appkit/Class.ExecutionError.md

@@ -21,30 +21,51 @@ throw new ExecutionError("Statement was canceled");
 ```ts
 new ExecutionError(message: string, options?: {
   cause?: Error;
+  clientMessage?: string;
   context?: Record<string, unknown>;
+  errorCode?: string;
 }): ExecutionError;
 
 ```
 
 #### Parameters[​](#parameters "Direct link to Parameters")
 
-| Parameter          | Type                                                              |
-| ------------------ | ----------------------------------------------------------------- |
-| `message`          | `string`                                                          |
-| `options?`         | { `cause?`: `Error`; `context?`: `Record`<`string`, `unknown`>; } |
-| `options.cause?`   | `Error`                                                           |
-| `options.context?` | `Record`<`string`, `unknown`>                                     |
+| Parameter                | Type                                                                                                                  |
+| ------------------------ | --------------------------------------------------------------------------------------------------------------------- |
+| `message`                | `string`                                                                                                              |
+| `options?`               | { `cause?`: `Error`; `clientMessage?`: `string`; `context?`: `Record`<`string`, `unknown`>; `errorCode?`: `string`; } |
+| `options.cause?`         | `Error`                                                                                                               |
+| `options.clientMessage?` | `string`                                                                                                              |
+| `options.context?`       | `Record`<`string`, `unknown`>                                                                                         |
+| `options.errorCode?`     | `string`                                                                                                              |
 
 #### Returns[​](#returns "Direct link to Returns")
 
 `ExecutionError`
 
-#### Inherited from[​](#inherited-from "Direct link to Inherited from")
+#### Overrides[​](#overrides "Direct link to Overrides")
 
 [`AppKitError`](./docs/api/appkit/Class.AppKitError.md).[`constructor`](./docs/api/appkit/Class.AppKitError.md#constructor)
 
 ## Properties[​](#properties "Direct link to Properties")
 
+### \_clientMessage?[​](#_clientmessage "Direct link to _clientMessage?")
+
+```ts
+protected readonly optional _clientMessage: string;
+
+```
+
+Client-safe error message. When set, callers serializing the error to a client (SSE, HTTP body) MUST prefer `clientMessage` over `message` — `message` may contain raw upstream / SDK text including statement fragments, internal object names, and correlation IDs.
+
+Subclasses can set this in their constructor for a fixed sanitized string. When unset, `clientMessage` defaults to a generic per-code string (see the getter), and the raw `message` is kept server-side only.
+
+#### Inherited from[​](#inherited-from "Direct link to Inherited from")
+
+[`AppKitError`](./docs/api/appkit/Class.AppKitError.md).[`_clientMessage`](./docs/api/appkit/Class.AppKitError.md#_clientmessage)
+
+***
+
 ### cause?[​](#cause "Direct link to cause?")
 
 ```ts
@@ -69,7 +90,7 @@ readonly code: "EXECUTION_ERROR" = "EXECUTION_ERROR";
 
 Error code for programmatic error handling
 
-#### Overrides[​](#overrides "Direct link to Overrides")
+#### Overrides[​](#overrides-1 "Direct link to Overrides")
 
 [`AppKitError`](./docs/api/appkit/Class.AppKitError.md).[`code`](./docs/api/appkit/Class.AppKitError.md#code)
 
@@ -90,6 +111,17 @@ Additional context for the error
 
 ***
 
+### errorCode?[​](#errorcode "Direct link to errorCode?")
+
+```ts
+readonly optional errorCode: string;
+
+```
+
+Structured error code from the upstream source (typically the warehouse's `error_code` for statement-level failures, or the SDK's `ApiError.errorCode` for HTTP failures). Preserved through wrapping so callers can branch on a stable identifier without substring-matching the message.
+
+***
+
 ### isRetryable[​](#isretryable "Direct link to isRetryable")
 
 ```ts
@@ -99,7 +131,7 @@ readonly isRetryable: false = false;
 
 Whether this error type is generally safe to retry
 
-#### Overrides[​](#overrides-1 "Direct link to Overrides")
+#### Overrides[​](#overrides-2 "Direct link to Overrides")
 
 [`AppKitError`](./docs/api/appkit/Class.AppKitError.md).[`isRetryable`](./docs/api/appkit/Class.AppKitError.md#isretryable)
 
@@ -114,10 +146,31 @@ readonly statusCode: 500 = 500;
 
 HTTP status code suggestion (can be overridden)
 
-#### Overrides[​](#overrides-2 "Direct link to Overrides")
+#### Overrides[​](#overrides-3 "Direct link to Overrides")
 
 [`AppKitError`](./docs/api/appkit/Class.AppKitError.md).[`statusCode`](./docs/api/appkit/Class.AppKitError.md#statuscode)
 
+## Accessors[​](#accessors "Direct link to Accessors")
+
+### clientMessage[​](#clientmessage "Direct link to clientMessage")
+
+#### Get Signature[​](#get-signature "Direct link to Get Signature")
+
+```ts
+get clientMessage(): string;
+
+```
+
+Execution errors default to a generic message — the raw warehouse / SDK text in `.message` often includes statement fragments, internal paths, and correlation IDs. UI code should branch on `errorCode` (`RESULT_TOO_LARGE_FOR_JSON_FALLBACK`, `NOT_IMPLEMENTED`, etc.) and not on the human string.
+
+##### Returns[​](#returns-1 "Direct link to Returns")
+
+`string`
+
+#### Overrides[​](#overrides-4 "Direct link to Overrides")
+
+[`AppKitError`](./docs/api/appkit/Class.AppKitError.md).[`clientMessage`](./docs/api/appkit/Class.AppKitError.md#clientmessage)
+
 ## Methods[​](#methods "Direct link to Methods")
 
 ### toJSON()[​](#tojson "Direct link to toJSON()")
@@ -129,7 +182,7 @@ toJSON(): Record<string, unknown>;
 
 Convert error to JSON for logging/serialization. Sensitive values in context are automatically redacted.
 
-#### Returns[​](#returns-1 "Direct link to Returns")
+#### Returns[​](#returns-2 "Direct link to Returns")
 
 `Record`<`string`, `unknown`>
 
@@ -148,7 +201,7 @@ toString(): string;
 
 Create a human-readable string representation
 
-#### Returns[​](#returns-2 "Direct link to Returns")
+#### Returns[​](#returns-3 "Direct link to Returns")
 
 `string`
 
@@ -167,7 +220,7 @@ static canceled(): ExecutionError;
 
 Create an execution error for canceled operation
 
-#### Returns[​](#returns-3 "Direct link to Returns")
+#### Returns[​](#returns-4 "Direct link to Returns")
 
 `ExecutionError`
 
@@ -188,7 +241,7 @@ Create an execution error for missing data
 | ---------- | -------- |
 | `dataType` | `string` |
 
-#### Returns[​](#returns-4 "Direct link to Returns")
+#### Returns[​](#returns-5 "Direct link to Returns")
 
 `ExecutionError`
 
@@ -203,7 +256,7 @@ static resultsClosed(): ExecutionError;
 
 Create an execution error for closed/expired results
 
-#### Returns[​](#returns-5 "Direct link to Returns")
+#### Returns[​](#returns-6 "Direct link to Returns")
 
 `ExecutionError`
 
@@ -212,19 +265,24 @@ Create an execution error for closed/expired results
 ### statementFailed()[​](#statementfailed "Direct link to statementFailed()")
 
 ```ts
-static statementFailed(errorMessage?: string): ExecutionError;
+static statementFailed(
+   errorMessage?: string, 
+   errorCode?: string, 
+   clientMessage?: string): ExecutionError;
 
 ```
 
-Create an execution error for statement failure
+Create an execution error for statement failure.
 
 #### Parameters[​](#parameters-2 "Direct link to Parameters")
 
-| Parameter       | Type     |
-| --------------- | -------- |
-| `errorMessage?` | `string` |
+| Parameter        | Type     | Description                                                                                                                                                                                       |
+| ---------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `errorMessage?`  | `string` | Human-readable error from the warehouse / SDK. Goes into `.message` for server logs only — *never* echoed to the client. Pass `clientMessage` explicitly if a sanitized text should reach the UI. |
+| `errorCode?`     | `string` | Structured code (e.g. "INVALID\_PARAMETER\_VALUE") to preserve through wrapping. Optional. Forwarded on SSE error payloads so UI can branch on it instead of substring-matching `error`.          |
+| `clientMessage?` | `string` | Optional client-safe replacement for `.message`. Defaults to "Query execution failed" via the `clientMessage` getter. Set this only when the upstream text is known-safe.                         |
 
-#### Returns[​](#returns-6 "Direct link to Returns")
+#### Returns[​](#returns-7 "Direct link to Returns")
 
 `ExecutionError`
 
@@ -245,6 +303,6 @@ Create an execution error for unknown state
 | --------- | -------- |
 | `state`   | `string` |
 
-#### Returns[​](#returns-7 "Direct link to Returns")
+#### Returns[​](#returns-8 "Direct link to Returns")
 
 `ExecutionError`