@databricks/appkit-ui 0.96.0 → 0.97.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CLAUDE.md +16 -7
- package/dist/js/database/client.d.ts +2 -2
- package/dist/js/database/client.js +1 -1
- package/dist/js/database/client.js.map +1 -1
- package/dist/react/beta.d.ts +2 -2
- package/dist/react/beta.js +1 -2
- package/dist/react/hooks/use-database-list.d.ts +4 -4
- package/dist/react/hooks/use-database-list.d.ts.map +1 -1
- package/dist/react/hooks/use-database-list.js +1 -2
- package/dist/react/hooks/use-database-list.js.map +1 -1
- package/dist/react/hooks/use-database-read.d.ts +4 -41
- package/dist/react/hooks/use-database-read.d.ts.map +1 -1
- package/dist/react/hooks/use-database-read.js +7 -68
- package/dist/react/hooks/use-database-read.js.map +1 -1
- package/dist/react/hooks/use-database-record.d.ts +3 -3
- package/dist/react/hooks/use-database-record.d.ts.map +1 -1
- package/dist/react/hooks/use-database-record.js +2 -3
- package/dist/react/hooks/use-database-record.js.map +1 -1
- package/dist/react/hooks/use-database-write.d.ts +3 -3
- package/dist/react/hooks/use-database-write.js.map +1 -1
- package/dist/shared/src/database/api-types.d.ts +1 -4
- package/dist/shared/src/database/api-types.d.ts.map +1 -1
- package/dist/shared/src/database/index.d.ts +3 -0
- package/dist/shared/src/database/operations.d.ts +11 -0
- package/dist/shared/src/database/operations.d.ts.map +1 -0
- package/dist/shared/src/index.d.ts +1 -0
- package/docs/api/appkit/Class.DatabaseValidationError.md +1 -1
- package/docs/api/appkit/Function.defineOperation.md +61 -0
- package/docs/api/appkit/Function.definePolicy.md +52 -0
- package/docs/api/appkit/Function.defineSchema.md +1 -1
- package/docs/api/appkit/Interface.Actor.md +21 -0
- package/docs/api/appkit/Interface.DatabaseOperationContract.md +30 -0
- package/docs/api/appkit/Interface.DatabaseRoutes.md +30 -0
- package/docs/api/appkit/Interface.OperationContext.md +75 -0
- package/docs/api/appkit/Interface.OperationDefinition.md +77 -0
- package/docs/api/appkit/Interface.PolicyContext.md +49 -0
- package/docs/api/appkit/Interface.PolicyDenial.md +21 -0
- package/docs/api/appkit/TypeAlias.DatabricksAppKitDatabaseOperations.md +8 -0
- package/docs/api/appkit/TypeAlias.IDatabaseConfig.md +0 -10
- package/docs/api/appkit/TypeAlias.OperationMethod.md +8 -0
- package/docs/api/appkit/TypeAlias.OperationWireInput.md +14 -0
- package/docs/api/appkit/TypeAlias.OperationWireOutput.md +14 -0
- package/docs/api/appkit/TypeAlias.Policy.md +15 -0
- package/docs/api/appkit/TypeAlias.PolicyDecision.md +8 -0
- package/docs/api/appkit.md +60 -51
- package/docs/plugins/database.md +17 -70
- package/llms.txt +16 -7
- package/package.json +1 -1
- package/sbom.cdx.json +1 -1
- package/docs/api/appkit/Interface.EntityMutationHooks.md +0 -173
- package/docs/api/appkit/Interface.HookApp.md +0 -12
- package/docs/api/appkit/Interface.HookContext.md +0 -21
- package/docs/api/appkit/Interface.ReadSerializerContext.md +0 -21
- package/docs/api/appkit/TypeAlias.EntityHooks.md +0 -25
- package/docs/api/appkit/TypeAlias.ReadSerializer.md +0 -19
|
@@ -0,0 +1,15 @@
|
|
|
1
|
+
# Type Alias: Policy\<In, R>
|
|
2
|
+
|
|
3
|
+
```ts
|
|
4
|
+
type Policy<In, R> = AllowPolicy<In> | ResourcePolicy<In, R>;
|
|
5
|
+
|
|
6
|
+
```
|
|
7
|
+
|
|
8
|
+
A reusable authorization rule, with or without a resource lookup.
|
|
9
|
+
|
|
10
|
+
## Type Parameters[](#type-parameters "Direct link to Type Parameters")
|
|
11
|
+
|
|
12
|
+
| Type Parameter | Default type |
|
|
13
|
+
| -------------- | ------------ |
|
|
14
|
+
| `In` | `unknown` |
|
|
15
|
+
| `R` | `undefined` |
|
package/docs/api/appkit.md
CHANGED
|
@@ -19,7 +19,7 @@ Documentation merge entry for Typedoc — combines the stable `@databricks/appki
|
|
|
19
19
|
| [AuthenticationError](./docs/api/appkit/Class.AuthenticationError.md) | Error thrown when authentication fails. Use for missing tokens, invalid credentials, or authorization failures. |
|
|
20
20
|
| [ConfigurationError](./docs/api/appkit/Class.ConfigurationError.md) | Error thrown when configuration is missing or invalid. Use for missing environment variables, invalid settings, or setup issues. |
|
|
21
21
|
| [ConnectionError](./docs/api/appkit/Class.ConnectionError.md) | Error thrown when a connection or network operation fails. Use for database pool errors, API failures, timeouts, etc. |
|
|
22
|
-
| [DatabaseValidationError](./docs/api/appkit/Class.DatabaseValidationError.md) | Deliberate validation failure
|
|
22
|
+
| [DatabaseValidationError](./docs/api/appkit/Class.DatabaseValidationError.md) | Deliberate validation failure. An explicit transaction callback can throw it, and the transaction rethrows that same error. Generated routes answer `422` and echo only the issues naming a public column. Every other failure stays an opaque server error. |
|
|
23
23
|
| [DatabricksAdapter](./docs/api/appkit/Class.DatabricksAdapter.md) | Adapter that talks directly to Databricks Model Serving `/invocations` endpoint. |
|
|
24
24
|
| [ExecutionError](./docs/api/appkit/Class.ExecutionError.md) | Error thrown when an operation execution fails. Use for statement failures, canceled operations, or unexpected states. |
|
|
25
25
|
| [IdentityExpiredError](./docs/api/appkit/Class.IdentityExpiredError.md) | The downstream service rejected the active caller's credentials. |
|
|
@@ -38,6 +38,7 @@ Documentation merge entry for Typedoc — combines the stable `@databricks/appki
|
|
|
38
38
|
|
|
39
39
|
| Interface | Description |
|
|
40
40
|
| ----------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
41
|
+
| [Actor](./docs/api/appkit/Interface.Actor.md) | The authenticated caller. The HTTP boundary resolves it before any policy runs. |
|
|
41
42
|
| [AgentAdapter](./docs/api/appkit/Interface.AgentAdapter.md) | - |
|
|
42
43
|
| [AgentDefinition](./docs/api/appkit/Interface.AgentDefinition.md) | - |
|
|
43
44
|
| [AgentInput](./docs/api/appkit/Interface.AgentInput.md) | - |
|
|
@@ -53,7 +54,9 @@ Documentation merge entry for Typedoc — combines the stable `@databricks/appki
|
|
|
53
54
|
| [CallerContext](./docs/api/appkit/Interface.CallerContext.md) | Caller identity and workspace for one immutable execution scope. |
|
|
54
55
|
| [CustomJudgeSpec](./docs/api/appkit/Interface.CustomJudgeSpec.md) | A custom LLM-judge definition: a prompt template and choice→score mapping. |
|
|
55
56
|
| [DatabaseCredential](./docs/api/appkit/Interface.DatabaseCredential.md) | Database credentials with OAuth token for Postgres connection |
|
|
57
|
+
| [DatabaseOperationContract](./docs/api/appkit/Interface.DatabaseOperationContract.md) | The browser-safe contract of one generated operation. `input` and `output` are JSON types. A generated `database.d.ts` fills this interface by name. |
|
|
56
58
|
| [DatabaseRegistry](./docs/api/appkit/Interface.DatabaseRegistry.md) | CANONICAL augmentation target. Empty by default; the generated `database.d.ts` augments it via `declare module "@databricks/appkit" { interface DatabaseRegistry { ... } }`. |
|
|
59
|
+
| [DatabaseRoutes](./docs/api/appkit/Interface.DatabaseRoutes.md) | The generated route entry. `schema` and each module stay lazy, so importing the registry evaluates neither the schema nor an operation. |
|
|
57
60
|
| [DatabaseValidationIssue](./docs/api/appkit/Interface.DatabaseValidationIssue.md) | One rejected field; `path` names public columns, never their values. |
|
|
58
61
|
| [DatabricksAuth](./docs/api/appkit/Interface.DatabricksAuth.md) | Resolved Databricks host + bearer token for the eval runner's REST calls. |
|
|
59
62
|
| [DatasetRow](./docs/api/appkit/Interface.DatasetRow.md) | One row of a managed evaluation dataset. `inputs` are the kwargs passed to the agent for the turn; `expectations` (when present) is the row's ground truth / guidelines. Mirrors the `{inputs, expectations}` shape of `mlflow.genai` datasets and of the Unity Catalog table backing a managed eval dataset. |
|
|
@@ -63,7 +66,6 @@ Documentation merge entry for Typedoc — combines the stable `@databricks/appki
|
|
|
63
66
|
| [~~DownloadResponse~~](./docs/api/appkit/Interface.DownloadResponse.md) | Response object for file downloads containing a readable stream. |
|
|
64
67
|
| [DriveResult](./docs/api/appkit/Interface.DriveResult.md) | What a driver returns for a single `t.send`. |
|
|
65
68
|
| [EndpointConfig](./docs/api/appkit/Interface.EndpointConfig.md) | - |
|
|
66
|
-
| [EntityMutationHooks](./docs/api/appkit/Interface.EntityMutationHooks.md) | Mutation lifecycle for one entity. A before hook may return a replacement payload, which is revalidated against the trusted schema before it is persisted. Every hook, the mutation, and any write a hook issues through `ctx.app.database` share one transaction, so a rejection anywhere rolls all of them back. Throw `DatabaseValidationError` to answer a generated route with `422`; any other failure stays an opaque server error. |
|
|
67
69
|
| [EvalDefinition](./docs/api/appkit/Interface.EvalDefinition.md) | A single eval, default-exported from a `*.eval.ts` file. |
|
|
68
70
|
| [EvalDriver](./docs/api/appkit/Interface.EvalDriver.md) | Abstraction over how the agent is driven. The HTTP driver posts to a running app's agents endpoint; future drivers (in-process) implement the same shape. |
|
|
69
71
|
| [EvalResult](./docs/api/appkit/Interface.EvalResult.md) | The outcome of running one eval. |
|
|
@@ -75,8 +77,6 @@ Documentation merge entry for Typedoc — combines the stable `@databricks/appki
|
|
|
75
77
|
| [FunctionTool](./docs/api/appkit/Interface.FunctionTool.md) | - |
|
|
76
78
|
| [GenerateDatabaseCredentialRequest](./docs/api/appkit/Interface.GenerateDatabaseCredentialRequest.md) | Request parameters for generating database OAuth credentials |
|
|
77
79
|
| [GenerationParams](./docs/api/appkit/Interface.GenerationParams.md) | Optional generation parameters forwarded to the OpenAI-compatible serving request body. Names match the serving API wire keys. Only keys that are set are sent — undefined values are omitted so the endpoint applies its own defaults. Ranges are not validated here; the serving endpoint validates. |
|
|
78
|
-
| [HookApp](./docs/api/appkit/Interface.HookApp.md) | The only capability a hook receives: entities bound to its transaction. |
|
|
79
|
-
| [HookContext](./docs/api/appkit/Interface.HookContext.md) | Which entity is being mutated, and the surface a hook may write through. |
|
|
80
80
|
| [HostedSupervisorTool](./docs/api/appkit/Interface.HostedSupervisorTool.md) | Tagged record returned by every [supervisorTools](./docs/api/appkit/Variable.supervisorTools.md) factory. The `__kind` discriminator lets the agents plugin (and standalone `runAgent`) classify these tools without a structural match against the wire format — keeps the SA wire shape free to evolve and avoids namespace collisions with MCP hosted tools (which use `type: "genie-space"` hyphenated, vs SA's `type: "genie_space"` underscored). |
|
|
81
81
|
| [HttpDriverOptions](./docs/api/appkit/Interface.HttpDriverOptions.md) | - |
|
|
82
82
|
| [IAiSearchConfig](./docs/api/appkit/Interface.IAiSearchConfig.md) | Base configuration interface for AppKit plugins |
|
|
@@ -94,12 +94,15 @@ Documentation merge entry for Typedoc — combines the stable `@databricks/appki
|
|
|
94
94
|
| [MatchResult](./docs/api/appkit/Interface.MatchResult.md) | Result of a deterministic matcher run against a value. |
|
|
95
95
|
| [McpConnectAllResult](./docs/api/appkit/Interface.McpConnectAllResult.md) | Per-endpoint outcome of [AppKitMcpClient.connectAll](./docs/api/appkit/Class.AppKitMcpClient.md#connectall). Callers (the agents plugin in particular) use the split to warn at startup when some MCP servers are unreachable without aborting boot for the rest. |
|
|
96
96
|
| [Message](./docs/api/appkit/Interface.Message.md) | - |
|
|
97
|
+
| [OperationContext](./docs/api/appkit/Interface.OperationContext.md) | What `allow` and `execute` receive: the policy context and the loaded resource. |
|
|
98
|
+
| [OperationDefinition](./docs/api/appkit/Interface.OperationDefinition.md) | One immutable operation descriptor. Nothing in it runs until a request does. |
|
|
97
99
|
| [PluginManifest](./docs/api/appkit/Interface.PluginManifest.md) | Plugin manifest that declares metadata and resource requirements. Attached to plugin classes as a static property. Extends the shared PluginManifest with strict resource types. |
|
|
98
100
|
| [PluginToolkitProvider](./docs/api/appkit/Interface.PluginToolkitProvider.md) | Minimum shape every entry in the [Plugins](./docs/api/appkit/TypeAlias.Plugins.md) map must expose. Core plugins (analytics, files, genie, lakebase) implement this directly via their `.toolkit()` method. The agents plugin and standalone `runAgent` synthesize this shape for any registered plugin that doesn't implement `.toolkit()` directly (falling back to `getAgentTools()` walking). |
|
|
101
|
+
| [PolicyContext](./docs/api/appkit/Interface.PolicyContext.md) | What every authorization callback receives, the `resource` lookup included. `actor` is the verified caller, so a lookup can scope its query to them. |
|
|
102
|
+
| [PolicyDenial](./docs/api/appkit/Interface.PolicyDenial.md) | An explicit refusal. `reason` stays on the server; HTTP and logs do not receive it. |
|
|
99
103
|
| [PostResult](./docs/api/appkit/Interface.PostResult.md) | Structured result for a best-effort POST that must not throw. |
|
|
100
104
|
| [PromptContext](./docs/api/appkit/Interface.PromptContext.md) | Context passed to `baseSystemPrompt` callbacks. |
|
|
101
105
|
| [ReadEvalDatasetOptions](./docs/api/appkit/Interface.ReadEvalDatasetOptions.md) | - |
|
|
102
|
-
| [ReadSerializerContext](./docs/api/appkit/Interface.ReadSerializerContext.md) | Which entity and generated operation produced the row being shaped. |
|
|
103
106
|
| [RegisteredAgent](./docs/api/appkit/Interface.RegisteredAgent.md) | - |
|
|
104
107
|
| [ReportOutcome](./docs/api/appkit/Interface.ReportOutcome.md) | - |
|
|
105
108
|
| [RequestedClaims](./docs/api/appkit/Interface.RequestedClaims.md) | Optional claims for fine-grained Unity Catalog table permissions When specified, the returned token will be scoped to only the requested tables |
|
|
@@ -137,51 +140,55 @@ Documentation merge entry for Typedoc — combines the stable `@databricks/appki
|
|
|
137
140
|
|
|
138
141
|
## Type Aliases[](#type-aliases "Direct link to Type Aliases")
|
|
139
142
|
|
|
140
|
-
| Type Alias
|
|
141
|
-
|
|
|
142
|
-
| [AgentAuth](./docs/api/appkit/TypeAlias.AgentAuth.md)
|
|
143
|
-
| [AgentEvent](./docs/api/appkit/TypeAlias.AgentEvent.md)
|
|
144
|
-
| [AgentTool](./docs/api/appkit/TypeAlias.AgentTool.md)
|
|
145
|
-
| [AgentTools](./docs/api/appkit/TypeAlias.AgentTools.md)
|
|
146
|
-
| [AgentToolsFn](./docs/api/appkit/TypeAlias.AgentToolsFn.md)
|
|
147
|
-
| [AppKitApi](./docs/api/appkit/TypeAlias.AppKitApi.md)
|
|
148
|
-
| [BaseSystemPromptOption](./docs/api/appkit/TypeAlias.BaseSystemPromptOption.md)
|
|
149
|
-
| [CallerPrincipal](./docs/api/appkit/TypeAlias.CallerPrincipal.md)
|
|
150
|
-
| [ConfigSchema](./docs/api/appkit/TypeAlias.ConfigSchema.md)
|
|
151
|
-
| [DatabaseApiConfig](./docs/api/appkit/TypeAlias.DatabaseApiConfig.md)
|
|
152
|
-
| [DatabaseApiWriteOperation](./docs/api/appkit/TypeAlias.DatabaseApiWriteOperation.md)
|
|
153
|
-
| [DatabaseApiWritesConfig](./docs/api/appkit/TypeAlias.DatabaseApiWritesConfig.md)
|
|
154
|
-
| [DatabaseExports](./docs/api/appkit/TypeAlias.DatabaseExports.md)
|
|
155
|
-
| [
|
|
156
|
-
| [EvalProgress](./docs/api/appkit/TypeAlias.EvalProgress.md)
|
|
157
|
-
| [ExecutionContext](./docs/api/appkit/TypeAlias.ExecutionContext.md)
|
|
158
|
-
| [ExecutionResult](./docs/api/appkit/TypeAlias.ExecutionResult.md)
|
|
159
|
-
| [FileAction](./docs/api/appkit/TypeAlias.FileAction.md)
|
|
160
|
-
| [FilePolicy](./docs/api/appkit/TypeAlias.FilePolicy.md)
|
|
161
|
-
| [FilesDirectoryEntry](./docs/api/appkit/TypeAlias.FilesDirectoryEntry.md)
|
|
162
|
-
| [FilesDownloadResponse](./docs/api/appkit/TypeAlias.FilesDownloadResponse.md)
|
|
163
|
-
| [HostedTool](./docs/api/appkit/TypeAlias.HostedTool.md)
|
|
164
|
-
| [IAppRouter](./docs/api/appkit/TypeAlias.IAppRouter.md)
|
|
165
|
-
| [IDatabaseConfig](./docs/api/appkit/TypeAlias.IDatabaseConfig.md)
|
|
166
|
-
| [JobsExport](./docs/api/appkit/TypeAlias.JobsExport.md)
|
|
167
|
-
| [Matcher](./docs/api/appkit/TypeAlias.Matcher.md)
|
|
168
|
-
| [
|
|
169
|
-
| [
|
|
170
|
-
| [
|
|
171
|
-
| [
|
|
172
|
-
| [
|
|
173
|
-
| [
|
|
174
|
-
| [
|
|
175
|
-
| [
|
|
176
|
-
| [
|
|
177
|
-
| [
|
|
178
|
-
| [
|
|
179
|
-
| [
|
|
180
|
-
| [
|
|
181
|
-
| [
|
|
182
|
-
| [
|
|
183
|
-
| [
|
|
184
|
-
| [
|
|
143
|
+
| Type Alias | Description |
|
|
144
|
+
| ------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
145
|
+
| [AgentAuth](./docs/api/appkit/TypeAlias.AgentAuth.md) | Identity an agent runs under. The only value is on-behalf-of-user. |
|
|
146
|
+
| [AgentEvent](./docs/api/appkit/TypeAlias.AgentEvent.md) | - |
|
|
147
|
+
| [AgentTool](./docs/api/appkit/TypeAlias.AgentTool.md) | Any tool an agent can invoke: inline function tools (`tool()`), hosted MCP tools (`mcpServer()` / raw hosted), toolkit references from plugins (`analytics().toolkit()`), or adapter-hosted Supervisor-API tools (`supervisorTools.*`). |
|
|
148
|
+
| [AgentTools](./docs/api/appkit/TypeAlias.AgentTools.md) | Per-agent tool record. String keys map to inline tools, toolkit entries, hosted tools, etc. |
|
|
149
|
+
| [AgentToolsFn](./docs/api/appkit/TypeAlias.AgentToolsFn.md) | Function form of `AgentDefinition.tools`. Receives the typed [Plugins](./docs/api/appkit/TypeAlias.Plugins.md) map and returns a tool record. Invoked exactly once at setup (or once per `runAgent` call in standalone mode); the result is cached as the agent's resolved tool record. |
|
|
150
|
+
| [AppKitApi](./docs/api/appkit/TypeAlias.AppKitApi.md) | App instance with plugin exports and an explicit caller-scoped entry point. |
|
|
151
|
+
| [BaseSystemPromptOption](./docs/api/appkit/TypeAlias.BaseSystemPromptOption.md) | - |
|
|
152
|
+
| [CallerPrincipal](./docs/api/appkit/TypeAlias.CallerPrincipal.md) | The caller identity whose permissions authorize execution, not its resources. |
|
|
153
|
+
| [ConfigSchema](./docs/api/appkit/TypeAlias.ConfigSchema.md) | Configuration schema definition for plugin config. Re-exported from the standard JSON Schema Draft 7 types. |
|
|
154
|
+
| [DatabaseApiConfig](./docs/api/appkit/TypeAlias.DatabaseApiConfig.md) | Full generated CRUD for every declared table by default. Set false to disable all generated routes, or use an object to restrict tables and writes. Keyed routes require a public primary key; upsert stays programmatic. Route names must start with a letter, contain only letters, digits, `_`, or `-`, be at most 64 characters, and be unique ignoring case. Invalid names fail setup; exclude internal tables with `api.tables` or use `api: false`. |
|
|
155
|
+
| [DatabaseApiWriteOperation](./docs/api/appkit/TypeAlias.DatabaseApiWriteOperation.md) | Generated HTTP write operations. |
|
|
156
|
+
| [DatabaseApiWritesConfig](./docs/api/appkit/TypeAlias.DatabaseApiWritesConfig.md) | All writes by default; false keeps reads only, and an object narrows writes. |
|
|
157
|
+
| [DatabaseExports](./docs/api/appkit/TypeAlias.DatabaseExports.md) | Typed database API published by the plugin. |
|
|
158
|
+
| [DatabricksAppKitDatabaseOperations](./docs/api/appkit/TypeAlias.DatabricksAppKitDatabaseOperations.md) | The same global registry, available as a module type for package exports. |
|
|
159
|
+
| [EvalProgress](./docs/api/appkit/TypeAlias.EvalProgress.md) | - |
|
|
160
|
+
| [ExecutionContext](./docs/api/appkit/TypeAlias.ExecutionContext.md) | - |
|
|
161
|
+
| [ExecutionResult](./docs/api/appkit/TypeAlias.ExecutionResult.md) | Discriminated union for plugin execution results. |
|
|
162
|
+
| [FileAction](./docs/api/appkit/TypeAlias.FileAction.md) | Every action the files plugin can perform. |
|
|
163
|
+
| [FilePolicy](./docs/api/appkit/TypeAlias.FilePolicy.md) | A policy function that decides whether `user` may perform `action` on `resource`. Return `true` to allow, `false` to deny. |
|
|
164
|
+
| [FilesDirectoryEntry](./docs/api/appkit/TypeAlias.FilesDirectoryEntry.md) | A single directory entry in the modular SDK shape (camelCase). `list()` and the `/list` route still return the legacy [DirectoryEntry](./docs/api/appkit/Interface.DirectoryEntry.md); they move to this type in a future release. |
|
|
165
|
+
| [FilesDownloadResponse](./docs/api/appkit/TypeAlias.FilesDownloadResponse.md) | Download response in the modular SDK shape (`contentLength` is a `bigint`). `download()` still returns the legacy [DownloadResponse](./docs/api/appkit/Interface.DownloadResponse.md); it moves to this type in a future release. |
|
|
166
|
+
| [HostedTool](./docs/api/appkit/TypeAlias.HostedTool.md) | - |
|
|
167
|
+
| [IAppRouter](./docs/api/appkit/TypeAlias.IAppRouter.md) | Express router type for plugin route registration |
|
|
168
|
+
| [IDatabaseConfig](./docs/api/appkit/TypeAlias.IDatabaseConfig.md) | Configuration for one schema-bound DatabasePlugin instance. |
|
|
169
|
+
| [JobsExport](./docs/api/appkit/TypeAlias.JobsExport.md) | Public API shape of the jobs plugin. Callable to select a job by key. |
|
|
170
|
+
| [Matcher](./docs/api/appkit/TypeAlias.Matcher.md) | A deterministic matcher: inspects a string value and returns a result. |
|
|
171
|
+
| [OperationMethod](./docs/api/appkit/TypeAlias.OperationMethod.md) | HTTP methods an operation can answer; the browser client reads the same union. |
|
|
172
|
+
| [OperationWireInput](./docs/api/appkit/TypeAlias.OperationWireInput.md) | The JSON a caller sends to an operation; a bigint travels as a string or safe integer. |
|
|
173
|
+
| [OperationWireOutput](./docs/api/appkit/TypeAlias.OperationWireOutput.md) | The JSON a successful call answers with; without an output schema there is none. |
|
|
174
|
+
| [PluginData](./docs/api/appkit/TypeAlias.PluginData.md) | Tuple of plugin class, config, and name. Created by `toPlugin()` and passed to `createApp()`. |
|
|
175
|
+
| [Plugins](./docs/api/appkit/TypeAlias.Plugins.md) | Plugin map passed to the function form of [AgentDefinition.tools](./docs/api/appkit/Interface.AgentDefinition.md#tools). Each entry exposes a `.toolkit(opts?)` method that returns a record of [ToolkitEntry](./docs/api/appkit/Interface.ToolkitEntry.md) markers ready to be spread into a tool record. |
|
|
176
|
+
| [Policy](./docs/api/appkit/TypeAlias.Policy.md) | A reusable authorization rule, with or without a resource lookup. |
|
|
177
|
+
| [PolicyDecision](./docs/api/appkit/TypeAlias.PolicyDecision.md) | Only literal `true` admits. False and an explicit denial refuse. |
|
|
178
|
+
| [ResolvedToolEntry](./docs/api/appkit/TypeAlias.ResolvedToolEntry.md) | Internal tool-index entry after a tool record has been resolved to a dispatchable form. |
|
|
179
|
+
| [ResourceFieldEntry](./docs/api/appkit/TypeAlias.ResourceFieldEntry.md) | - |
|
|
180
|
+
| [ResourcePermission](./docs/api/appkit/TypeAlias.ResourcePermission.md) | Union of all possible permission levels across all resource types. |
|
|
181
|
+
| [ScopedPluginMap](./docs/api/appkit/TypeAlias.ScopedPluginMap.md) | - |
|
|
182
|
+
| [SearchFilters](./docs/api/appkit/TypeAlias.SearchFilters.md) | - |
|
|
183
|
+
| [ServingFactory](./docs/api/appkit/TypeAlias.ServingFactory.md) | Factory function returned by `AppKit.serving`. |
|
|
184
|
+
| [Severity](./docs/api/appkit/TypeAlias.Severity.md) | Whether an assertion fails the eval (`gate`) or is tracked only (`soft`). |
|
|
185
|
+
| [SupervisorTool](./docs/api/appkit/TypeAlias.SupervisorTool.md) | Tools supported by the Databricks AI Gateway Responses API. The shapes match the wire format the endpoint expects, so the adapter passes the array straight into the request body. |
|
|
186
|
+
| [ToolRegistry](./docs/api/appkit/TypeAlias.ToolRegistry.md) | - |
|
|
187
|
+
| [ToPlugin](./docs/api/appkit/TypeAlias.ToPlugin.md) | Factory function type returned by `toPlugin()`. Accepts optional config and returns a PluginData tuple. |
|
|
188
|
+
| [TransactionClient](./docs/api/appkit/TypeAlias.TransactionClient.md) | Entity and SQL capabilities bound to one transaction. |
|
|
189
|
+
| [~~UserContext~~](./docs/api/appkit/TypeAlias.UserContext.md) | - |
|
|
190
|
+
| [UserScopedApp](./docs/api/appkit/TypeAlias.UserScopedApp.md) | - |
|
|
191
|
+
| [WorkspaceClientLike](./docs/api/appkit/TypeAlias.WorkspaceClientLike.md) | Structural shape of a Databricks SDK client used by [fromSupervisorApi](./docs/api/appkit/Function.fromSupervisorApi.md). Only what we need: `request` for streaming. A legacy SDK client (`apiClient.request` + `config.ensureResolved`) is still accepted (deprecated). |
|
|
185
192
|
|
|
186
193
|
## Variables[](#variables "Direct link to Variables")
|
|
187
194
|
|
|
@@ -218,7 +225,9 @@ Documentation merge entry for Typedoc — combines the stable `@databricks/appki
|
|
|
218
225
|
| [defineEval](./docs/api/appkit/Function.defineEval.md) | Define an agent eval. Default-export the result from a `server/agents/<id>/evals/*.eval.ts` file. |
|
|
219
226
|
| [defineEvalConfig](./docs/api/appkit/Function.defineEvalConfig.md) | Define per-directory eval config. Default-export from `evals.config.ts`. |
|
|
220
227
|
| [defineManifest](./docs/api/appkit/Function.defineManifest.md) | Validates a raw manifest (typically a `manifest.json` import) against the canonical Zod schema and returns it as a strict [PluginManifest](./docs/api/appkit/Interface.PluginManifest.md). |
|
|
221
|
-
| [
|
|
228
|
+
| [defineOperation](./docs/api/appkit/Function.defineOperation.md) | Declare one database operation. `name` is its public identifier. Declare an `input` Zod schema to accept parameters; without one, callbacks receive `undefined`. Declare an `output` Zod schema to answer a body; without one, the operation answers none. Definition only freezes a descriptor. |
|
|
229
|
+
| [definePolicy](./docs/api/appkit/Function.definePolicy.md) | Declare a reusable authorization rule. Without `resource` it decides from the actor and input. With `resource` it loads one record first, from the same context every callback receives, `actor` included; annotate the lookup context to fix the input the policy needs. `allow` may return `true`, `false`, or `{ deny }`. |
|
|
230
|
+
| [defineSchema](./docs/api/appkit/Function.defineSchema.md) | Compile one declared schema. The returned type keeps the table names the builder returned, so `api.tables` can name only real tables. |
|
|
222
231
|
| [defineTool](./docs/api/appkit/Function.defineTool.md) | Defines a single tool entry for a plugin's internal registry. |
|
|
223
232
|
| [discoverEvalConfigs](./docs/api/appkit/Function.discoverEvalConfigs.md) | Discover the per-agent `evals.config.ts` (from [defineEvalConfig](./docs/api/appkit/Function.defineEvalConfig.md)) at `<rootDir>/server/agents/<agent>/evals/evals.config.ts`. Config is per-agent: each agent's config applies only to that agent's evals. Agents without a config file are omitted. Returns a stable, sorted list. |
|
|
224
233
|
| [discoverEvalFiles](./docs/api/appkit/Function.discoverEvalFiles.md) | Discover evals under `<rootDir>/server/agents/<agent>/evals/` — co-located with each agent's `agent.{md,ts}` (same folder-per-agent layout the agents plugin discovers). The agent id is the folder name; the eval id is the file path relative to that evals dir with `.eval.ts` stripped. Sorted + stable. |
|
package/docs/plugins/database.md
CHANGED
|
@@ -75,7 +75,7 @@ database({ schema });
|
|
|
75
75
|
|
|
76
76
|
An explicit schema always takes precedence and skips file discovery. An invalid explicit schema fails setup instead of falling back to another file.
|
|
77
77
|
|
|
78
|
-
Run `appkit generate-types` to generate the database registry. With that registry, configuration without an explicit schema still infers table names
|
|
78
|
+
Run `appkit generate-types` to generate the database registry. With that registry, configuration without an explicit schema still infers table names. An explicitly supplied schema also checks configuration keys against its own table names.
|
|
79
79
|
|
|
80
80
|
## Connection pool[](#connection-pool "Direct link to Connection pool")
|
|
81
81
|
|
|
@@ -123,11 +123,11 @@ database({
|
|
|
123
123
|
| `api.writes.tables` | All exposed tables | Limits which exposed tables accept writes |
|
|
124
124
|
| `api.writes.operations` | `create`, `update`, `delete` | Limits which writes are enabled |
|
|
125
125
|
|
|
126
|
-
`api.tables: []` disables all generated routes. An empty write-table or write-operation list keeps reads and disables writes. Tables omitted from `api.tables` also cannot be included through relations on exposed tables. These restrictions apply to HTTP only, not to the server-side client
|
|
126
|
+
`api.tables: []` disables all generated routes. An empty write-table or write-operation list keeps reads and disables writes. Tables omitted from `api.tables` also cannot be included through relations on exposed tables. These restrictions apply to HTTP only, not to the server-side client.
|
|
127
127
|
|
|
128
128
|
An omitted restriction uses its default. A malformed restriction fails setup. For example, `{ api: { write: false } }` is an error, not permission to generate all writes. Unknown tables, duplicate names, and unsupported operations also fail setup before the plugin creates a connection pool.
|
|
129
129
|
|
|
130
|
-
Replace the former `crudRoutes` option with `api`. The old name is rejected at runtime so an old opt-out cannot silently enable the API. To preserve read-only behavior, specify `api: { writes: false }`.
|
|
130
|
+
Replace the former `crudRoutes` option with `api`. The old name is rejected at runtime so an old opt-out cannot silently enable the API. To preserve read-only behavior, specify `api: { writes: false }`. The removed `hooks` option is also rejected, so routes never run without the rules it used to enforce.
|
|
131
131
|
|
|
132
132
|
### Table names and setup errors[](#table-names-and-setup-errors "Direct link to Table names and setup errors")
|
|
133
133
|
|
|
@@ -148,34 +148,26 @@ The generated API validates request bodies and rejects unknown or read-only fiel
|
|
|
148
148
|
|
|
149
149
|
Validation is not authorization. A valid request can still read or change any exposed row. Use custom authorized routes when that is not the desired access model.
|
|
150
150
|
|
|
151
|
-
##
|
|
151
|
+
## Transactions[](#transactions "Direct link to Transactions")
|
|
152
152
|
|
|
153
|
-
A
|
|
153
|
+
A root write outside `database.transaction()` uses the connection pool directly. Related writes belong in one explicit transaction. The callback receives a transaction client with the same entity methods and `sql` tag. A later `transaction()` call inside that callback joins the open transaction instead of opening another one. A root write made while the callback is running also joins it, and keeps the predicate from the query that issued the write. A read or an `sql` call made on the root client does not join.
|
|
154
154
|
|
|
155
155
|
```ts
|
|
156
|
-
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
notes: {
|
|
161
|
-
beforeCreate(values) {
|
|
162
|
-
if (typeof values.body === "string" && values.body.length > 5_000) {
|
|
163
|
-
throw new DatabaseValidationError("Note too long", [
|
|
164
|
-
{ path: ["body"], message: "Must be at most 5000 characters" },
|
|
165
|
-
]);
|
|
166
|
-
}
|
|
167
|
-
},
|
|
168
|
-
},
|
|
169
|
-
},
|
|
156
|
+
const note = await appkit.database.transaction(async (tx) => {
|
|
157
|
+
const created = await tx.notes.create({ body: "Ship it" });
|
|
158
|
+
await tx.note_events.create({ note_id: created.id, action: "created" });
|
|
159
|
+
return created;
|
|
170
160
|
});
|
|
171
161
|
|
|
172
162
|
```
|
|
173
163
|
|
|
174
|
-
|
|
164
|
+
The callback commits when it returns and rolls back when it throws. A thrown `DatabaseValidationError` keeps its identity. Any other thrown error becomes an opaque transaction failure. The transaction does not cover writes through other plugins or external services.
|
|
175
165
|
|
|
176
|
-
|
|
166
|
+
`update()` returns `null` and `delete()` returns `false` when no row matches. Those results do not abort the caller's transaction. A later write in the same callback can still commit.
|
|
177
167
|
|
|
178
|
-
The callback deadline
|
|
168
|
+
Await every database call inside the callback. The callback has a 30-second deadline and one shared budget. That budget counts entity writes and `tx.sql` statements. It does not count reads. The 101st counted operation rejects the transaction. PostgreSQL also enforces a 30-second `statement_timeout` and a 30-second `idle_in_transaction_session_timeout`.
|
|
169
|
+
|
|
170
|
+
The callback deadline does not cancel arbitrary JavaScript, HTTP requests, or other external side effects. Avoid starting external work that needs the database rollback to undo it.
|
|
179
171
|
|
|
180
172
|
## Browser client (beta)[](#browser-client-beta "Direct link to Browser client (beta)")
|
|
181
173
|
|
|
@@ -240,15 +232,13 @@ await databaseApi.list("notes", { where });
|
|
|
240
232
|
|
|
241
233
|
A to-many include adds an array to each row and a to-one include adds a row or `null`. JSON carries bigint columns as decimal strings, so rows type them as `string`, and filters accept a string or a safe integer. Dynamic `select` arrays return optional properties for their possible columns; a literal tuple returns those properties as required. This also applies to detail and included rows. Params typed broadly with an optional `select` keep row fields optional.
|
|
242
234
|
|
|
243
|
-
If a server-side read serializer changes a list or detail row, the schema-based return type cannot describe that custom response. Validate or narrow custom read results in the caller; the client does not infer serializer output.
|
|
244
|
-
|
|
245
235
|
### Values[](#values "Direct link to Values")
|
|
246
236
|
|
|
247
237
|
`create` and `update` accept only the fields the generated route accepts. Private columns, server-generated columns such as `id()`, and unknown fields are compile errors, including fields that a spread carries in. Every update field is optional, and primary keys and `defaultNow()` or `defaultRandom()` columns cannot be updated. Bigint columns accept a decimal string or a safe integer. NaN and positive or negative Infinity fail locally before a write is sent, including inside JSON values. Use an explicit `null` to clear a nullable column; a non-finite number never implicitly becomes null. Query numbers must also be finite.
|
|
248
238
|
|
|
249
|
-
Skip an update when a form has no changes.
|
|
239
|
+
Skip an update when a form has no changes. An empty update returns `INVALID_REQUEST` with a `body` detail explaining that at least one field is required, and the stored row does not change.
|
|
250
240
|
|
|
251
|
-
The answered row is the public row the database holds after
|
|
241
|
+
The answered row is the public row the database holds after the write.
|
|
252
242
|
|
|
253
243
|
### Errors[](#errors "Direct link to Errors")
|
|
254
244
|
|
|
@@ -348,48 +338,6 @@ Only tables with a public primary key have a detail route, so a keyless table or
|
|
|
348
338
|
* `error` keeps its identity across renders until it changes, so an effect that depends on it, such as a toast, runs once per failure.
|
|
349
339
|
* A successful write through a write hook restarts mounted reads. See [Refresh reads after a write](#refresh-reads-after-a-write).
|
|
350
340
|
|
|
351
|
-
### Serializer-shaped reads[](#serializer-shaped-reads "Direct link to Serializer-shaped reads")
|
|
352
|
-
|
|
353
|
-
A read serializer can change the rows a list or detail route returns. The `shape` option types the result, and can check it. The entity, id, and parameters are still checked against the generated registry either way.
|
|
354
|
-
|
|
355
|
-
To check each row at runtime, pass a function that takes one decoded row and returns it typed, such as a zod schema's `parse`. It runs once per response, on each list item or on the record, and its return value becomes the row. If it throws, the read fails with `INTERNAL`; the thrown error is in `error.cause`, not in the message, since it may quote row values.
|
|
356
|
-
|
|
357
|
-
```tsx
|
|
358
|
-
import { useDatabaseList } from "@databricks/appkit-ui/react/beta";
|
|
359
|
-
import { z } from "zod";
|
|
360
|
-
|
|
361
|
-
// server: serialize: (row) => ({ id: row.id, excerpt: String(row.body).slice(0, 80) })
|
|
362
|
-
const NoteCard = z.object({ id: z.number(), excerpt: z.string() });
|
|
363
|
-
|
|
364
|
-
const notes = useDatabaseList(
|
|
365
|
-
"notes",
|
|
366
|
-
{ limit: 20 },
|
|
367
|
-
{ shape: NoteCard.parse },
|
|
368
|
-
);
|
|
369
|
-
notes.data?.items[0]?.excerpt;
|
|
370
|
-
|
|
371
|
-
```
|
|
372
|
-
|
|
373
|
-
Zod 4's `parse` works unbound. For a library whose parse method needs its schema as `this`, pass an arrow: `shape: (row) => schema.parse(row)`.
|
|
374
|
-
|
|
375
|
-
To only declare the type, pass `serialized<T>()`. Nothing checks it at runtime, so keep `T` in step with the serializer.
|
|
376
|
-
|
|
377
|
-
```tsx
|
|
378
|
-
import { serialized, useDatabaseList } from "@databricks/appkit-ui/react/beta";
|
|
379
|
-
|
|
380
|
-
interface NoteCard {
|
|
381
|
-
id: number;
|
|
382
|
-
excerpt: string;
|
|
383
|
-
}
|
|
384
|
-
|
|
385
|
-
const notes = useDatabaseList(
|
|
386
|
-
"notes",
|
|
387
|
-
{ limit: 20 },
|
|
388
|
-
{ shape: serialized<NoteCard>() },
|
|
389
|
-
);
|
|
390
|
-
|
|
391
|
-
```
|
|
392
|
-
|
|
393
341
|
### Write rows[](#write-rows "Direct link to Write rows")
|
|
394
342
|
|
|
395
343
|
```tsx
|
|
@@ -455,7 +403,7 @@ The callbacks run for every call, including one a later call superseded and one
|
|
|
455
403
|
|
|
456
404
|
When a write succeeds, every mounted database read restarts, so lists and includes that show the changed row refresh without a manual `refetch()`. Each read keeps its last `data` while it reloads. A failed write restarts nothing.
|
|
457
405
|
|
|
458
|
-
The default restarts every read because a
|
|
406
|
+
The default restarts every read because a foreign key declared with `onDelete("cascade")` can change other tables, and the browser cannot see that. When a page mounts many reads, pass `invalidate` to restart only the reads that show the tables you name, or none:
|
|
459
407
|
|
|
460
408
|
```ts
|
|
461
409
|
// A board's title changes only boards rows.
|
|
@@ -492,4 +440,3 @@ await invalidateDatabaseReads(["boards", "notes"]);
|
|
|
492
440
|
* [`database`](./docs/api/appkit/Function.database.md)
|
|
493
441
|
* [`IDatabaseConfig`](./docs/api/appkit/TypeAlias.IDatabaseConfig.md)
|
|
494
442
|
* [`DatabaseApiConfig`](./docs/api/appkit/TypeAlias.DatabaseApiConfig.md)
|
|
495
|
-
* [`EntityHooks`](./docs/api/appkit/TypeAlias.EntityHooks.md)
|