@databricks/appkit-ui 0.22.0 → 0.24.0

package/dist/react/index.js

@@ -47,6 +47,8 @@ import { useGenieChat } from "./genie/use-genie-chat.js";
 import { GenieChat } from "./genie/genie-chat.js";
 import "./genie/index.js";
 import { usePluginClientConfig } from "./hooks/use-plugin-config.js";
+import { useServingInvoke } from "./hooks/use-serving-invoke.js";
+import { useServingStream } from "./hooks/use-serving-stream.js";
 import "./hooks/index.js";
 import { Input } from "./ui/input.js";
 import { Select, SelectContent, SelectGroup, SelectItem, SelectLabel, SelectScrollDownButton, SelectScrollUpButton, SelectSeparator, SelectTrigger, SelectValue } from "./ui/select.js";
@@ -95,4 +97,4 @@ import { Toggle, toggleVariants } from "./ui/toggle.js";
 import { ToggleGroup, ToggleGroupItem } from "./ui/toggle-group.js";
 import "./ui/index.js";
 
-export { Accordion, AccordionContent, AccordionItem, AccordionTrigger, Alert, AlertDescription, AlertDialog, AlertDialogAction, AlertDialogCancel, AlertDialogContent, AlertDialogDescription, AlertDialogFooter, AlertDialogHeader, AlertDialogOverlay, AlertDialogPortal, AlertDialogTitle, AlertDialogTrigger, AlertTitle, AreaChart, AspectRatio, Avatar, AvatarFallback, AvatarImage, Badge, BarChart, BaseChart, Breadcrumb, BreadcrumbEllipsis, BreadcrumbItem, BreadcrumbLink, BreadcrumbList, BreadcrumbPage, BreadcrumbSeparator, Button, ButtonGroup, ButtonGroupSeparator, ButtonGroupText, CHART_COLOR_VARS, CHART_COLOR_VARS_CATEGORICAL, CHART_COLOR_VARS_DIVERGING, CHART_COLOR_VARS_SEQUENTIAL, Calendar, CalendarDayButton, Card, CardAction, CardContent, CardDescription, CardFooter, CardHeader, CardTitle, Carousel, CarouselContent, CarouselItem, CarouselNext, CarouselPrevious, ChartContainer, ChartLegend, ChartLegendContent, ChartStyle, ChartTooltip, ChartTooltipContent, ChartWrapper, Checkbox, Collapsible, CollapsibleContent, CollapsibleTrigger, Command, CommandDialog, CommandEmpty, CommandGroup, CommandInput, CommandItem, CommandList, CommandSeparator, CommandShortcut, ContextMenu, ContextMenuCheckboxItem, ContextMenuContent, ContextMenuGroup, ContextMenuItem, ContextMenuLabel, ContextMenuPortal, ContextMenuRadioGroup, ContextMenuRadioItem, ContextMenuSeparator, ContextMenuShortcut, ContextMenuSub, ContextMenuSubContent, ContextMenuSubTrigger, ContextMenuTrigger, DATE_FIELD_PATTERNS, DataTable, Dialog, DialogClose, DialogContent, DialogDescription, DialogFooter, DialogHeader, DialogOverlay, DialogPortal, DialogTitle, DialogTrigger, DirectoryList, DonutChart, Drawer, DrawerClose, DrawerContent, DrawerDescription, DrawerFooter, DrawerHeader, DrawerOverlay, DrawerPortal, DrawerTitle, DrawerTrigger, DropdownMenu, DropdownMenuCheckboxItem, DropdownMenuContent, DropdownMenuGroup, DropdownMenuItem, DropdownMenuLabel, DropdownMenuPortal, DropdownMenuRadioGroup, DropdownMenuRadioItem, DropdownMenuSeparator, DropdownMenuShortcut, DropdownMenuSub, DropdownMenuSubContent, DropdownMenuSubTrigger, DropdownMenuTrigger, Empty, EmptyContent, EmptyDescription, EmptyHeader, EmptyMedia, EmptyTitle, FALLBACK_COLORS_CATEGORICAL, FALLBACK_COLORS_DIVERGING, FALLBACK_COLORS_SEQUENTIAL, Field, FieldContent, FieldDescription, FieldError, FieldGroup, FieldLabel, FieldLegend, FieldSeparator, FieldSet, FieldTitle, FileBreadcrumb, FileEntry, FilePreviewPanel, Form, FormControl, FormDescription, FormField, FormItem, FormLabel, FormMessage, GenieChat, GenieChatInput, GenieChatMessage, GenieChatMessageList, GenieQueryVisualization, HeatmapChart, HoverCard, HoverCardContent, HoverCardTrigger, Input, InputGroup, InputGroupAddon, InputGroupButton, InputGroupInput, InputGroupText, InputGroupTextarea, InputOTP, InputOTPGroup, InputOTPSeparator, InputOTPSlot, Item, ItemActions, ItemContent, ItemDescription, ItemFooter, ItemGroup, ItemHeader, ItemMedia, ItemSeparator, ItemTitle, Kbd, KbdGroup, Label, LineChart, METADATA_DATE_PATTERNS, Menubar, MenubarCheckboxItem, MenubarContent, MenubarGroup, MenubarItem, MenubarLabel, MenubarMenu, MenubarPortal, MenubarRadioGroup, MenubarRadioItem, MenubarSeparator, MenubarShortcut, MenubarSub, MenubarSubContent, MenubarSubTrigger, MenubarTrigger, NAME_FIELD_PATTERNS, NavigationMenu, NavigationMenuContent, NavigationMenuIndicator, NavigationMenuItem, NavigationMenuLink, NavigationMenuList, NavigationMenuTrigger, NavigationMenuViewport, NewFolderInput, Pagination, PaginationContent, PaginationEllipsis, PaginationItem, PaginationLink, PaginationNext, PaginationPrevious, PieChart, Popover, PopoverAnchor, PopoverContent, PopoverTrigger, PortalContainerContext, PortalContainerProvider, Progress, RadarChart, RadioGroup, RadioGroupItem, ResizableHandle, ResizablePanel, ResizablePanelGroup, ScatterChart, ScrollArea, ScrollBar, Select, SelectContent, SelectGroup, SelectItem, SelectLabel, SelectScrollDownButton, SelectScrollUpButton, SelectSeparator, SelectTrigger, SelectValue, Separator, Sheet, SheetClose, SheetContent, SheetDescription, SheetFooter, SheetHeader, SheetTitle, SheetTrigger, Sidebar, SidebarContent, SidebarFooter, SidebarGroup, SidebarGroupAction, SidebarGroupContent, SidebarGroupLabel, SidebarHeader, SidebarInput, SidebarInset, SidebarMenu, SidebarMenuAction, SidebarMenuBadge, SidebarMenuButton, SidebarMenuItem, SidebarMenuSkeleton, SidebarMenuSub, SidebarMenuSubButton, SidebarMenuSubItem, SidebarProvider, SidebarRail, SidebarSeparator, SidebarTrigger, Skeleton, Slider, Spinner, Switch, Table, TableBody, TableCaption, TableCell, TableFooter, TableHead, TableHeader, TableRow, Tabs, TabsContent, TabsList, TabsTrigger, Textarea, Toaster, Toggle, ToggleGroup, ToggleGroupItem, Tooltip, TooltipContent, TooltipProvider, TooltipTrigger, badgeVariants, buildCartesianOption, buildHeatmapOption, buildHorizontalBarOption, buildPieOption, buildRadarOption, buttonGroupVariants, buttonVariants, cn, createChart, createTimeSeriesData, formatFileSize, formatLabel, getCompatibleChartTypes, inferChartType, isArrowTable, isDataProps, isQueryProps, navigationMenuTriggerStyle, normalizeChartData, normalizeHeatmapData, sortTimeSeriesAscending, toChartArray, toChartValue, toggleVariants, transformGenieData, truncateLabel, useAllThemeColors, useAnalyticsQuery, useChartData, useFormField, useGenieChat, usePluginClientConfig, usePortalContainer, useResolvedPortalContainer, useSidebar, useThemeColors };
+export { Accordion, AccordionContent, AccordionItem, AccordionTrigger, Alert, AlertDescription, AlertDialog, AlertDialogAction, AlertDialogCancel, AlertDialogContent, AlertDialogDescription, AlertDialogFooter, AlertDialogHeader, AlertDialogOverlay, AlertDialogPortal, AlertDialogTitle, AlertDialogTrigger, AlertTitle, AreaChart, AspectRatio, Avatar, AvatarFallback, AvatarImage, Badge, BarChart, BaseChart, Breadcrumb, BreadcrumbEllipsis, BreadcrumbItem, BreadcrumbLink, BreadcrumbList, BreadcrumbPage, BreadcrumbSeparator, Button, ButtonGroup, ButtonGroupSeparator, ButtonGroupText, CHART_COLOR_VARS, CHART_COLOR_VARS_CATEGORICAL, CHART_COLOR_VARS_DIVERGING, CHART_COLOR_VARS_SEQUENTIAL, Calendar, CalendarDayButton, Card, CardAction, CardContent, CardDescription, CardFooter, CardHeader, CardTitle, Carousel, CarouselContent, CarouselItem, CarouselNext, CarouselPrevious, ChartContainer, ChartLegend, ChartLegendContent, ChartStyle, ChartTooltip, ChartTooltipContent, ChartWrapper, Checkbox, Collapsible, CollapsibleContent, CollapsibleTrigger, Command, CommandDialog, CommandEmpty, CommandGroup, CommandInput, CommandItem, CommandList, CommandSeparator, CommandShortcut, ContextMenu, ContextMenuCheckboxItem, ContextMenuContent, ContextMenuGroup, ContextMenuItem, ContextMenuLabel, ContextMenuPortal, ContextMenuRadioGroup, ContextMenuRadioItem, ContextMenuSeparator, ContextMenuShortcut, ContextMenuSub, ContextMenuSubContent, ContextMenuSubTrigger, ContextMenuTrigger, DATE_FIELD_PATTERNS, DataTable, Dialog, DialogClose, DialogContent, DialogDescription, DialogFooter, DialogHeader, DialogOverlay, DialogPortal, DialogTitle, DialogTrigger, DirectoryList, DonutChart, Drawer, DrawerClose, DrawerContent, DrawerDescription, DrawerFooter, DrawerHeader, DrawerOverlay, DrawerPortal, DrawerTitle, DrawerTrigger, DropdownMenu, DropdownMenuCheckboxItem, DropdownMenuContent, DropdownMenuGroup, DropdownMenuItem, DropdownMenuLabel, DropdownMenuPortal, DropdownMenuRadioGroup, DropdownMenuRadioItem, DropdownMenuSeparator, DropdownMenuShortcut, DropdownMenuSub, DropdownMenuSubContent, DropdownMenuSubTrigger, DropdownMenuTrigger, Empty, EmptyContent, EmptyDescription, EmptyHeader, EmptyMedia, EmptyTitle, FALLBACK_COLORS_CATEGORICAL, FALLBACK_COLORS_DIVERGING, FALLBACK_COLORS_SEQUENTIAL, Field, FieldContent, FieldDescription, FieldError, FieldGroup, FieldLabel, FieldLegend, FieldSeparator, FieldSet, FieldTitle, FileBreadcrumb, FileEntry, FilePreviewPanel, Form, FormControl, FormDescription, FormField, FormItem, FormLabel, FormMessage, GenieChat, GenieChatInput, GenieChatMessage, GenieChatMessageList, GenieQueryVisualization, HeatmapChart, HoverCard, HoverCardContent, HoverCardTrigger, Input, InputGroup, InputGroupAddon, InputGroupButton, InputGroupInput, InputGroupText, InputGroupTextarea, InputOTP, InputOTPGroup, InputOTPSeparator, InputOTPSlot, Item, ItemActions, ItemContent, ItemDescription, ItemFooter, ItemGroup, ItemHeader, ItemMedia, ItemSeparator, ItemTitle, Kbd, KbdGroup, Label, LineChart, METADATA_DATE_PATTERNS, Menubar, MenubarCheckboxItem, MenubarContent, MenubarGroup, MenubarItem, MenubarLabel, MenubarMenu, MenubarPortal, MenubarRadioGroup, MenubarRadioItem, MenubarSeparator, MenubarShortcut, MenubarSub, MenubarSubContent, MenubarSubTrigger, MenubarTrigger, NAME_FIELD_PATTERNS, NavigationMenu, NavigationMenuContent, NavigationMenuIndicator, NavigationMenuItem, NavigationMenuLink, NavigationMenuList, NavigationMenuTrigger, NavigationMenuViewport, NewFolderInput, Pagination, PaginationContent, PaginationEllipsis, PaginationItem, PaginationLink, PaginationNext, PaginationPrevious, PieChart, Popover, PopoverAnchor, PopoverContent, PopoverTrigger, PortalContainerContext, PortalContainerProvider, Progress, RadarChart, RadioGroup, RadioGroupItem, ResizableHandle, ResizablePanel, ResizablePanelGroup, ScatterChart, ScrollArea, ScrollBar, Select, SelectContent, SelectGroup, SelectItem, SelectLabel, SelectScrollDownButton, SelectScrollUpButton, SelectSeparator, SelectTrigger, SelectValue, Separator, Sheet, SheetClose, SheetContent, SheetDescription, SheetFooter, SheetHeader, SheetTitle, SheetTrigger, Sidebar, SidebarContent, SidebarFooter, SidebarGroup, SidebarGroupAction, SidebarGroupContent, SidebarGroupLabel, SidebarHeader, SidebarInput, SidebarInset, SidebarMenu, SidebarMenuAction, SidebarMenuBadge, SidebarMenuButton, SidebarMenuItem, SidebarMenuSkeleton, SidebarMenuSub, SidebarMenuSubButton, SidebarMenuSubItem, SidebarProvider, SidebarRail, SidebarSeparator, SidebarTrigger, Skeleton, Slider, Spinner, Switch, Table, TableBody, TableCaption, TableCell, TableFooter, TableHead, TableHeader, TableRow, Tabs, TabsContent, TabsList, TabsTrigger, Textarea, Toaster, Toggle, ToggleGroup, ToggleGroupItem, Tooltip, TooltipContent, TooltipProvider, TooltipTrigger, badgeVariants, buildCartesianOption, buildHeatmapOption, buildHorizontalBarOption, buildPieOption, buildRadarOption, buttonGroupVariants, buttonVariants, cn, createChart, createTimeSeriesData, formatFileSize, formatLabel, getCompatibleChartTypes, inferChartType, isArrowTable, isDataProps, isQueryProps, navigationMenuTriggerStyle, normalizeChartData, normalizeHeatmapData, sortTimeSeriesAscending, toChartArray, toChartValue, toggleVariants, transformGenieData, truncateLabel, useAllThemeColors, useAnalyticsQuery, useChartData, useFormField, useGenieChat, usePluginClientConfig, usePortalContainer, useResolvedPortalContainer, useServingInvoke, useServingStream, useSidebar, useThemeColors };

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

@@ -319,13 +319,18 @@ BasePlugin.clientConfig
 protected execute<T>(
    fn: (signal?: AbortSignal) => Promise<T>, 
    options: PluginExecutionSettings, 
-userKey?: string): Promise<T | undefined>;
+userKey?: string): Promise<ExecutionResult<T>>;
 
 ```
 
 Execute a function with the plugin's interceptor chain.
 
-All errors are caught and `undefined` is returned (production-safe). Route handlers should check for `undefined` and respond with an appropriate error status.
+Returns an [ExecutionResult](./docs/api/appkit/TypeAlias.ExecutionResult.md) discriminated union:
+
+* `{ ok: true, data: T }` on success
+* `{ ok: false, status: number, message: string }` on failure
+
+Errors are never thrown — the method is production-safe.
 
 #### Type Parameters[​](#type-parameters-1 "Direct link to Type Parameters")
 
@@ -343,7 +348,7 @@ All errors are caught and `undefined` is returned (production-safe). Route handl
 
 #### Returns[​](#returns-4 "Direct link to Returns")
 
-`Promise`<`T` | `undefined`>
+`Promise`<[`ExecutionResult`](./docs/api/appkit/TypeAlias.ExecutionResult.md)<`T`>>
 
 ***
 

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

@@ -0,0 +1,24 @@
+# Function: appKitServingTypesPlugin()
+
+```ts
+function appKitServingTypesPlugin(options?: AppKitServingTypesPluginOptions): Plugin$1;
+
+```
+
+Vite plugin to generate TypeScript types for AppKit serving endpoints. Fetches OpenAPI schemas from Databricks and generates a .d.ts with ServingEndpointRegistry module augmentation.
+
+Endpoint discovery order:
+
+1. Explicit `endpoints` option (override)
+2. AST extraction from server file (server/index.ts or server/server.ts)
+3. DATABRICKS\_SERVING\_ENDPOINT\_NAME env var (single default endpoint)
+
+## Parameters[​](#parameters "Direct link to Parameters")
+
+| Parameter  | Type                              |
+| ---------- | --------------------------------- |
+| `options?` | `AppKitServingTypesPluginOptions` |
+
+## Returns[​](#returns "Direct link to Returns")
+
+`Plugin$1`

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

@@ -0,0 +1,22 @@
+# Function: extractServingEndpoints()
+
+```ts
+function extractServingEndpoints(serverFilePath: string): 
+  | Record<string, EndpointConfig>
+  | null;
+
+```
+
+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.
+
+## Parameters[​](#parameters "Direct link to Parameters")
+
+| Parameter        | Type     | Description                            |
+| ---------------- | -------- | -------------------------------------- |
+| `serverFilePath` | `string` | Absolute path to the server entry file |
+
+## Returns[​](#returns "Direct link to Returns")
+
+\| `Record`<`string`, [`EndpointConfig`](./docs/api/appkit/Interface.EndpointConfig.md)> | `null`
+
+Extracted endpoint config, or null if not found or not extractable

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

@@ -0,0 +1,20 @@
+# Function: findServerFile()
+
+```ts
+function findServerFile(basePath: string): string | null;
+
+```
+
+Find the server entry file by checking candidate paths in order.
+
+## Parameters[​](#parameters "Direct link to Parameters")
+
+| Parameter  | Type     | Description                           |
+| ---------- | -------- | ------------------------------------- |
+| `basePath` | `string` | Project root directory to search from |
+
+## Returns[​](#returns "Direct link to Returns")
+
+`string` | `null`
+
+Absolute path to the server file, or null if none found

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

@@ -0,0 +1,23 @@
+# Interface: EndpointConfig
+
+## Properties[​](#properties "Direct link to Properties")
+
+### env[​](#env "Direct link to env")
+
+```ts
+env: string;
+
+```
+
+Environment variable holding the endpoint name.
+
+***
+
+### servedModel?[​](#servedmodel "Direct link to servedModel?")
+
+```ts
+optional servedModel: string;
+
+```
+
+Target a specific served model (bypasses traffic routing).

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

@@ -0,0 +1,30 @@
+# Interface: ServingEndpointEntry
+
+Shape of a single registry entry.
+
+## Properties[​](#properties "Direct link to Properties")
+
+### chunk[​](#chunk "Direct link to chunk")
+
+```ts
+chunk: unknown;
+
+```
+
+***
+
+### request[​](#request "Direct link to request")
+
+```ts
+request: Record<string, unknown>;
+
+```
+
+***
+
+### response[​](#response "Direct link to response")
+
+```ts
+response: unknown;
+
+```

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

@@ -0,0 +1,3 @@
+# Interface: ServingEndpointRegistry
+
+Registry interface for serving endpoint type generation. Empty by default — augmented by the Vite type generator's `.d.ts` output via module augmentation. When populated, provides autocomplete for alias names and typed request/response/chunk per endpoint.

package/docs/api/appkit/TypeAlias.ExecutionResult.md

@@ -0,0 +1,36 @@
+# Type Alias: ExecutionResult\<T>
+
+```ts
+type ExecutionResult<T> = 
+  | {
+  data: T;
+  ok: true;
+}
+  | {
+  message: string;
+  ok: false;
+  status: number;
+};
+
+```
+
+Discriminated union for plugin execution results.
+
+Replaces the previous `T | undefined` return type on `execute()`.
+
+On failure, the HTTP status code is preserved from:
+
+* `AppKitError` subclasses (via `statusCode`)
+* Any `Error` with a numeric `statusCode` property (e.g. `ApiError`)
+* All other errors default to status 500
+
+In production, error messages from non-AppKitError sources are handled as:
+
+* 4xx errors: original message is preserved (client-facing by design)
+* 5xx errors: replaced with "Server error" to prevent information leakage
+
+## Type Parameters[​](#type-parameters "Direct link to Type Parameters")
+
+| Type Parameter |
+| -------------- |
+| `T`            |

package/docs/api/appkit/TypeAlias.ServingFactory.md

@@ -0,0 +1,19 @@
+# Type Alias: ServingFactory
+
+```ts
+type ServingFactory = keyof ServingEndpointRegistry extends never ? (alias?: string) => ServingEndpointHandle : true extends IsUnion<keyof ServingEndpointRegistry> ? <K>(alias: K) => ServingEndpointHandle<ServingEndpointRegistry[K]["request"], ServingEndpointRegistry[K]["response"]> : {
+<K>  (alias: K): ServingEndpointHandle<ServingEndpointRegistry[K]["request"], ServingEndpointRegistry[K]["response"]>;
+  (): ServingEndpointHandle<never, never>;
+};
+
+```
+
+Factory function returned by `AppKit.serving`.
+
+Adapts based on the `ServingEndpointRegistry` state:
+
+* **Empty (default):** `(alias?: string) => ServingEndpointHandle` — any string, untyped.
+* **Single key:** alias optional — `serving()` returns the typed handle for the only endpoint.
+* **Multiple keys:** alias required — must specify which endpoint.
+
+Run `npx appkit generate-types` or start the dev server to generate the registry.

package/docs/api/appkit.md

@@ -27,32 +27,37 @@ Core library for building Databricks applications with type-safe SQL queries, pl
 
 ## Interfaces[​](#interfaces "Direct link to Interfaces")
 
-| Interface                                                                                                   | Description                                                                                                                                                                                                                                                   |
-| ----------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| [BasePluginConfig](./docs/api/appkit/Interface.BasePluginConfig.md)                                   | Base configuration interface for AppKit plugins                                                                                                                                                                                                               |
-| [CacheConfig](./docs/api/appkit/Interface.CacheConfig.md)                                             | Configuration for the CacheInterceptor. Controls TTL, size limits, storage backend, and probabilistic cleanup.                                                                                                                                                |
-| [DatabaseCredential](./docs/api/appkit/Interface.DatabaseCredential.md)                               | Database credentials with OAuth token for Postgres connection                                                                                                                                                                                                 |
-| [GenerateDatabaseCredentialRequest](./docs/api/appkit/Interface.GenerateDatabaseCredentialRequest.md) | Request parameters for generating database OAuth credentials                                                                                                                                                                                                  |
-| [ITelemetry](./docs/api/appkit/Interface.ITelemetry.md)                                               | Plugin-facing interface for OpenTelemetry instrumentation. Provides a thin abstraction over OpenTelemetry APIs for plugins.                                                                                                                                   |
-| [LakebasePoolConfig](./docs/api/appkit/Interface.LakebasePoolConfig.md)                               | Configuration for creating a Lakebase connection pool                                                                                                                                                                                                         |
-| [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.                                                                              |
-| [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                                                                                                               |
-| [RequestedResource](./docs/api/appkit/Interface.RequestedResource.md)                                 | Resource to request permissions for in Unity Catalog                                                                                                                                                                                                          |
-| [ResourceEntry](./docs/api/appkit/Interface.ResourceEntry.md)                                         | Internal representation of a resource in the registry. Extends ResourceRequirement with resolution state and plugin ownership.                                                                                                                                |
-| [ResourceFieldEntry](./docs/api/appkit/Interface.ResourceFieldEntry.md)                               | Defines a single field for a resource. Each field has its own environment variable and optional description. Single-value types use one key (e.g. id); multi-value types (database, secret) use multiple (e.g. instance\_name, database\_name or scope, key). |
-| [ResourceRequirement](./docs/api/appkit/Interface.ResourceRequirement.md)                             | Declares a resource requirement for a plugin. Can be defined statically in a manifest or dynamically via getResourceRequirements(). Narrows the generated base: type → ResourceType enum, permission → ResourcePermission union.                              |
-| [StreamExecutionSettings](./docs/api/appkit/Interface.StreamExecutionSettings.md)                     | Execution settings for streaming endpoints. Extends PluginExecutionSettings with SSE stream configuration.                                                                                                                                                    |
-| [TelemetryConfig](./docs/api/appkit/Interface.TelemetryConfig.md)                                     | OpenTelemetry configuration for AppKit applications                                                                                                                                                                                                           |
-| [ValidationResult](./docs/api/appkit/Interface.ValidationResult.md)                                   | Result of validating all registered resources against the environment.                                                                                                                                                                                        |
+| Interface                                                                                                   | Description                                                                                                                                                                                                                                                     |
+| ----------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [BasePluginConfig](./docs/api/appkit/Interface.BasePluginConfig.md)                                   | Base configuration interface for AppKit plugins                                                                                                                                                                                                                 |
+| [CacheConfig](./docs/api/appkit/Interface.CacheConfig.md)                                             | Configuration for the CacheInterceptor. Controls TTL, size limits, storage backend, and probabilistic cleanup.                                                                                                                                                  |
+| [DatabaseCredential](./docs/api/appkit/Interface.DatabaseCredential.md)                               | Database credentials with OAuth token for Postgres connection                                                                                                                                                                                                   |
+| [EndpointConfig](./docs/api/appkit/Interface.EndpointConfig.md)                                       | -                                                                                                                                                                                                                                                               |
+| [GenerateDatabaseCredentialRequest](./docs/api/appkit/Interface.GenerateDatabaseCredentialRequest.md) | Request parameters for generating database OAuth credentials                                                                                                                                                                                                    |
+| [ITelemetry](./docs/api/appkit/Interface.ITelemetry.md)                                               | Plugin-facing interface for OpenTelemetry instrumentation. Provides a thin abstraction over OpenTelemetry APIs for plugins.                                                                                                                                     |
+| [LakebasePoolConfig](./docs/api/appkit/Interface.LakebasePoolConfig.md)                               | Configuration for creating a Lakebase connection pool                                                                                                                                                                                                           |
+| [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.                                                                                |
+| [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                                                                                                                 |
+| [RequestedResource](./docs/api/appkit/Interface.RequestedResource.md)                                 | Resource to request permissions for in Unity Catalog                                                                                                                                                                                                            |
+| [ResourceEntry](./docs/api/appkit/Interface.ResourceEntry.md)                                         | Internal representation of a resource in the registry. Extends ResourceRequirement with resolution state and plugin ownership.                                                                                                                                  |
+| [ResourceFieldEntry](./docs/api/appkit/Interface.ResourceFieldEntry.md)                               | Defines a single field for a resource. Each field has its own environment variable and optional description. Single-value types use one key (e.g. id); multi-value types (database, secret) use multiple (e.g. instance\_name, database\_name or scope, key).   |
+| [ResourceRequirement](./docs/api/appkit/Interface.ResourceRequirement.md)                             | Declares a resource requirement for a plugin. Can be defined statically in a manifest or dynamically via getResourceRequirements(). Narrows the generated base: type → ResourceType enum, permission → ResourcePermission union.                                |
+| [ServingEndpointEntry](./docs/api/appkit/Interface.ServingEndpointEntry.md)                           | Shape of a single registry entry.                                                                                                                                                                                                                               |
+| [ServingEndpointRegistry](./docs/api/appkit/Interface.ServingEndpointRegistry.md)                     | Registry interface for serving endpoint type generation. Empty by default — augmented by the Vite type generator's `.d.ts` output via module augmentation. When populated, provides autocomplete for alias names and typed request/response/chunk per endpoint. |
+| [StreamExecutionSettings](./docs/api/appkit/Interface.StreamExecutionSettings.md)                     | Execution settings for streaming endpoints. Extends PluginExecutionSettings with SSE stream configuration.                                                                                                                                                      |
+| [TelemetryConfig](./docs/api/appkit/Interface.TelemetryConfig.md)                                     | OpenTelemetry configuration for AppKit applications                                                                                                                                                                                                             |
+| [ValidationResult](./docs/api/appkit/Interface.ValidationResult.md)                                   | Result of validating all registered resources against the environment.                                                                                                                                                                                          |
 
 ## Type Aliases[​](#type-aliases "Direct link to Type Aliases")
 
 | Type Alias                                                                    | Description                                                                                                 |
 | ----------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
 | [ConfigSchema](./docs/api/appkit/TypeAlias.ConfigSchema.md)             | Configuration schema definition for plugin config. Re-exported from the standard JSON Schema Draft 7 types. |
+| [ExecutionResult](./docs/api/appkit/TypeAlias.ExecutionResult.md)       | Discriminated union for plugin execution results.                                                           |
 | [IAppRouter](./docs/api/appkit/TypeAlias.IAppRouter.md)                 | Express router type for plugin route registration                                                           |
 | [PluginData](./docs/api/appkit/TypeAlias.PluginData.md)                 | Tuple of plugin class, config, and name. Created by `toPlugin()` and passed to `createApp()`.               |
 | [ResourcePermission](./docs/api/appkit/TypeAlias.ResourcePermission.md) | Union of all possible permission levels across all resource types.                                          |
+| [ServingFactory](./docs/api/appkit/TypeAlias.ServingFactory.md)         | Factory function returned by `AppKit.serving`.                                                              |
 | [ToPlugin](./docs/api/appkit/TypeAlias.ToPlugin.md)                     | Factory function type returned by `toPlugin()`. Accepts optional config and returns a PluginData tuple.     |
 
 ## Variables[​](#variables "Direct link to Variables")
@@ -63,17 +68,20 @@ Core library for building Databricks applications with type-safe SQL queries, pl
 
 ## Functions[​](#functions "Direct link to Functions")
 
-| Function                                                                                     | Description                                                                                                                                     |
-| -------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
-| [appKitTypesPlugin](./docs/api/appkit/Function.appKitTypesPlugin.md)                   | Vite plugin to generate types for AppKit queries. Calls generateFromEntryPoint under the hood.                                                  |
-| [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. |
-| [generateDatabaseCredential](./docs/api/appkit/Function.generateDatabaseCredential.md) | Generate OAuth credentials for Postgres database connection using the proper Postgres API.                                                      |
-| [getExecutionContext](./docs/api/appkit/Function.getExecutionContext.md)               | Get the current execution context.                                                                                                              |
-| [getLakebaseOrmConfig](./docs/api/appkit/Function.getLakebaseOrmConfig.md)             | Get Lakebase connection configuration for ORMs that don't accept pg.Pool directly.                                                              |
-| [getLakebasePgConfig](./docs/api/appkit/Function.getLakebasePgConfig.md)               | Get Lakebase connection configuration for PostgreSQL clients.                                                                                   |
-| [getPluginManifest](./docs/api/appkit/Function.getPluginManifest.md)                   | Loads and validates the manifest from a plugin constructor. Normalizes string type/permission to strict ResourceType/ResourcePermission.        |
-| [getResourceRequirements](./docs/api/appkit/Function.getResourceRequirements.md)       | Gets the resource requirements from a plugin's manifest.                                                                                        |
-| [getUsernameWithApiLookup](./docs/api/appkit/Function.getUsernameWithApiLookup.md)     | Resolves the PostgreSQL username for a Lakebase connection.                                                                                     |
-| [getWorkspaceClient](./docs/api/appkit/Function.getWorkspaceClient.md)                 | Get workspace client from config or SDK default auth chain                                                                                      |
-| [isSQLTypeMarker](./docs/api/appkit/Function.isSQLTypeMarker.md)                       | Type guard to check if a value is a SQL type marker                                                                                             |
+| Function                                                                                     | Description                                                                                                                                                                                                                   |
+| -------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [appKitServingTypesPlugin](./docs/api/appkit/Function.appKitServingTypesPlugin.md)     | Vite plugin to generate TypeScript types for AppKit serving endpoints. Fetches OpenAPI schemas from Databricks and generates a .d.ts with ServingEndpointRegistry module augmentation.                                        |
+| [appKitTypesPlugin](./docs/api/appkit/Function.appKitTypesPlugin.md)                   | Vite plugin to generate types for AppKit queries. Calls generateFromEntryPoint under the hood.                                                                                                                                |
+| [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.                                                                               |
+| [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. |
+| [findServerFile](./docs/api/appkit/Function.findServerFile.md)                         | Find the server entry file by checking candidate paths in order.                                                                                                                                                              |
+| [generateDatabaseCredential](./docs/api/appkit/Function.generateDatabaseCredential.md) | Generate OAuth credentials for Postgres database connection using the proper Postgres API.                                                                                                                                    |
+| [getExecutionContext](./docs/api/appkit/Function.getExecutionContext.md)               | Get the current execution context.                                                                                                                                                                                            |
+| [getLakebaseOrmConfig](./docs/api/appkit/Function.getLakebaseOrmConfig.md)             | Get Lakebase connection configuration for ORMs that don't accept pg.Pool directly.                                                                                                                                            |
+| [getLakebasePgConfig](./docs/api/appkit/Function.getLakebasePgConfig.md)               | Get Lakebase connection configuration for PostgreSQL clients.                                                                                                                                                                 |
+| [getPluginManifest](./docs/api/appkit/Function.getPluginManifest.md)                   | Loads and validates the manifest from a plugin constructor. Normalizes string type/permission to strict ResourceType/ResourcePermission.                                                                                      |
+| [getResourceRequirements](./docs/api/appkit/Function.getResourceRequirements.md)       | Gets the resource requirements from a plugin's manifest.                                                                                                                                                                      |
+| [getUsernameWithApiLookup](./docs/api/appkit/Function.getUsernameWithApiLookup.md)     | Resolves the PostgreSQL username for a Lakebase connection.                                                                                                                                                                   |
+| [getWorkspaceClient](./docs/api/appkit/Function.getWorkspaceClient.md)                 | Get workspace client from config or SDK default auth chain                                                                                                                                                                    |
+| [isSQLTypeMarker](./docs/api/appkit/Function.isSQLTypeMarker.md)                       | Type guard to check if a value is a SQL type marker                                                                                                                                                                           |

package/docs/development/type-generation.md

@@ -4,7 +4,9 @@ AppKit can automatically generate TypeScript types for your SQL queries, providi
 
 ## Goal[​](#goal "Direct link to Goal")
 
-Generate `client/src/appKitTypes.d.ts` so query keys, parameters, and result rows are type-safe.
+Generate type-safe TypeScript declarations for query keys, parameters, and result rows.
+
+All generated files live in `shared/appkit-types/`, one per plugin (e.g. `analytics.d.ts`). They use [`declare module`](https://www.typescriptlang.org/docs/handbook/declaration-merging.html#module-augmentation) to augment existing interfaces, so the types apply globally — you never need to import them. TypeScript auto-discovers them through `"include": ["shared/appkit-types"]` in your tsconfig.
 
 ## Vite plugin: `appKitTypesPlugin`[​](#vite-plugin-appkittypesplugin "Direct link to vite-plugin-appkittypesplugin")
 
@@ -12,7 +14,7 @@ The recommended approach is to use the Vite plugin, which watches your SQL files
 
 ### Configuration[​](#configuration "Direct link to Configuration")
 
-* `outFile?: string` - Output file path (default: `src/appKitTypes.d.ts`)
+* `outFile?: string` - Output file path (default: `shared/appkit-types/analytics.d.ts`)
 * `watchFolders?: string[]` - Folders to watch for SQL files (default: `["../config/queries"]`)
 
 ### Example[​](#example "Direct link to Example")
@@ -27,7 +29,6 @@ export default defineConfig({
   plugins: [
     react(),
     appKitTypesPlugin({
-      outFile: "src/appKitTypes.d.ts",
       watchFolders: ["../config/queries"],
     }),
   ],
@@ -54,14 +55,14 @@ npx @databricks/appkit generate-types [rootDir] [outFile] [warehouseId]
 * Generate types using warehouse ID from environment
 
   ```bash
-  npx @databricks/appkit generate-types . client/src/appKitTypes.d.ts
+  npx @databricks/appkit generate-types . shared/appkit-types/analytics.d.ts
 
   ```
 
 * Generate types using warehouse ID explicitly
 
   ```bash
-  npx @databricks/appkit generate-types . client/src/appKitTypes.d.ts abc123...
+  npx @databricks/appkit generate-types . shared/appkit-types/analytics.d.ts abc123...
 
   ```
 

package/docs/faq.md

@@ -0,0 +1,66 @@
+# FAQ
+
+## Integrations[​](#integrations "Direct link to Integrations")
+
+### What Databricks services are available through AppKit?[​](#what-databricks-services-are-available-through-appkit "Direct link to What Databricks services are available through AppKit?")
+
+AppKit provides built-in integrations with the following Databricks services via its [plugin system](./docs/plugins.md):
+
+| Plugin                                         | Databricks Service                | What It Does                                                                            |
+| ---------------------------------------------- | --------------------------------- | --------------------------------------------------------------------------------------- |
+| [Analytics](./docs/plugins/analytics.md) | SQL Warehouses                    | Execute parameterized SQL queries with built-in caching, retry, and Arrow support       |
+| [Lakebase](./docs/plugins/lakebase.md)   | Lakebase Autoscaling (PostgreSQL) | Relational database access via standard pg.Pool with automatic OAuth token refresh      |
+| [Genie](./docs/plugins/genie.md)         | AI/BI Genie Spaces                | Natural language data queries with conversation management and streaming                |
+| [Files](./docs/plugins/files.md)         | Unity Catalog Volumes             | Multi-volume file operations (list, read, upload, download, delete, preview)            |
+| [Serving](./docs/plugins/serving.md)     | Model Serving                     | Authenticated proxy to Model Serving endpoints with invoke and streaming support        |
+| [Server](./docs/plugins/server.md)       | N/A                               | Express HTTP server with static file serving, Vite dev mode, and plugin route injection |
+
+Stay tuned for new plugins as we constantly expand integrations!
+
+### Can I add custom integrations?[​](#can-i-add-custom-integrations "Direct link to Can I add custom integrations?")
+
+Yes. AppKit's plugin architecture is extensible - you can create custom plugins using the CLI (`npx appkit plugin create`) or manually. See the [creating custom plugins guide](./docs/plugins/custom-plugins.md).
+
+## Authentication[​](#authentication "Direct link to Authentication")
+
+### How does authentication work in AppKit apps?[​](#how-does-authentication-work-in-appkit-apps "Direct link to How does authentication work in AppKit apps?")
+
+AppKit apps are designed to run on [Databricks Apps](https://docs.databricks.com/aws/en/dev-tools/databricks-apps/), which handles user authentication and authorization. Databricks Apps forwards user identity to the app via request headers, and AppKit integrates with this through the `.asUser(req)` pattern for on-behalf-of (OBO) execution — allowing plugins to act on behalf of the authenticated user.
+
+For details on how authentication and authorization work in Databricks Apps, see the [official auth documentation](https://docs.databricks.com/aws/en/dev-tools/databricks-apps/auth).
+
+## Databases[​](#databases "Direct link to Databases")
+
+*Also: Lakebase, PostgreSQL, OLTP*
+
+### How does AppKit handle databases?[​](#how-does-appkit-handle-databases "Direct link to How does AppKit handle databases?")
+
+AppKit is a TypeScript SDK (Express + React) and does not manage databases directly.
+
+To add database support, use the [Lakebase plugin](./docs/plugins/lakebase.md), which integrates with Lakebase Autoscaling.
+
+AppKit also uses Lakebase for caching when it is available (see the [caching](#does-appkit-support-caching) section below).
+
+You can manage Lakebase Autoscaling projects and branches using the dedicated agent skill from [Databricks Agent Skills](./docs/development/ai-assisted-development.md), installed with the Databricks CLI.
+
+### How does database setup and permission management work in AppKit?[​](#how-does-database-setup-and-permission-management-work-in-appkit "Direct link to How does database setup and permission management work in AppKit?")
+
+AppKit apps can have an attached Lakebase Autoscaling instance. No database is bundled by default - you add one by configuring the [Lakebase plugin](./docs/plugins/lakebase.md). When running `databricks apps init` and selecting the Lakebase plugin, the selected database is automatically attached as an app resource after deployment.
+
+With [AI-assisted development](./docs/development/ai-assisted-development.md), you can also ask the Agent to create a Lakebase project and branch for you.
+
+When deployed, a Databricks app uses its Service Principal for schema and table creation. If you configure the Lakebase Autoscaling project as an [app resource](https://docs.databricks.com/aws/en/dev-tools/databricks-apps/resources), the necessary connect and create permissions are granted automatically to the app's Service Principal.
+
+### Does AppKit support Lakebase Provisioned?[​](#does-appkit-support-lakebase-provisioned "Direct link to Does AppKit support Lakebase Provisioned?")
+
+No. AppKit only supports Lakebase Autoscaling. Lakebase Provisioned databases are not supported by the [Lakebase plugin](./docs/plugins/lakebase.md) or Lakebase agent skill from [Databricks Agent Skills](./docs/development/ai-assisted-development.md).
+
+## Caching[​](#caching "Direct link to Caching")
+
+### Does AppKit support caching?[​](#does-appkit-support-caching "Direct link to Does AppKit support caching?")
+
+Yes. The [Analytics plugin](./docs/plugins/analytics.md) - used for executing SQL queries against Databricks SQL Warehouses - supports an optional cache layer.
+
+Caching is configured per plugin and can use either [Lakebase Autoscaling](https://docs.databricks.com/aws/en/oltp/) or an in-memory store, depending on the configuration.
+
+If the Lakebase Autoscaling connection is configured, the AppKit-based app creates an `appkit` schema in the configured database with internal tables required for caching.

package/docs/plugins/analytics.md

@@ -139,7 +139,7 @@ function SpendTable() {
 Augment the `QueryRegistry` interface to get full type inference on parameters and results:
 
 ```ts
-// config/appKitTypes.d.ts
+// shared/appkit-types/analytics.d.ts
 declare module "@databricks/appkit-ui/react" {
   interface QueryRegistry {
     spend_summary: {

package/docs/plugins/custom-plugins.md

@@ -3,8 +3,12 @@
 If you need custom API routes or background logic, implement an AppKit plugin. The fastest way is to use the CLI:
 
 ```bash
+# Interactive
 npx @databricks/appkit plugin create
 
+# Non-interactive
+npx @databricks/appkit plugin create --placement in-repo --path plugins/my-plugin --name my-plugin --description "My plugin" --force
+
 ```
 
 For a deeper understanding of the plugin structure, read on.

package/docs/plugins/plugin-management.md

@@ -6,19 +6,30 @@ AppKit includes a CLI for managing plugins. All commands are available under `np
 
 ## Create a plugin[​](#create-a-plugin "Direct link to Create a plugin")
 
-Scaffold a new plugin interactively:
+Scaffold a new plugin interactively or via flags:
 
 ```bash
+# Interactive mode (prompts for all options)
 npx @databricks/appkit plugin create
 
+# Non-interactive mode (all required flags provided)
+npx @databricks/appkit plugin create \
+  --placement in-repo \
+  --path plugins/my-plugin \
+  --name my-plugin \
+  --description "My custom plugin" \
+  --resources sql_warehouse \
+  --force
+
 ```
 
-The wizard walks you through:
+In interactive mode, the wizard walks you through:
 
 * **Placement**: In your repository (e.g. `plugins/my-plugin`) or as a standalone package
 * **Metadata**: Name, display name, description
 * **Resources**: Which Databricks resources the plugin needs (SQL Warehouse, Secret, etc.) and whether each is required or optional
-* **Optional fields**: Author, version, license
+
+In non-interactive mode, `--placement`, `--path`, `--name`, and `--description` are required. Resources can be specified as a comma-separated list (`--resources sql_warehouse,volume`) or as JSON for full control (`--resources-json '[{"type":"sql_warehouse","permission":"CAN_MANAGE"}]'`). For all available options, run `npx @databricks/appkit plugin create --help`.
 
 The command generates a complete plugin scaffold with `manifest.json` and a TypeScript plugin class that imports the manifest directly — ready to register in your app.
 
@@ -91,12 +102,17 @@ npx @databricks/appkit plugin list --json
 
 ## Add a resource to a plugin[​](#add-a-resource-to-a-plugin "Direct link to Add a resource to a plugin")
 
-Interactively add a new resource requirement to an existing plugin manifest. **Requires `manifest.json`** in the plugin directory (the command edits it in place; it does not modify `manifest.js`):
+Add a new resource requirement to an existing plugin manifest. **Requires `manifest.json`** in the plugin directory (the command edits it in place; it does not modify `manifest.js`):
 
 ```bash
+# Interactive mode
 npx @databricks/appkit plugin add-resource
-
-# Or specify the plugin directory
 npx @databricks/appkit plugin add-resource --path plugins/my-plugin
 
+# Non-interactive mode (--type triggers flag-based mode)
+npx @databricks/appkit plugin add-resource --path plugins/my-plugin --type sql_warehouse
+npx @databricks/appkit plugin add-resource --path plugins/my-plugin --type volume --no-required --dry-run
+
 ```
+
+In non-interactive mode, only `--type` is required — all other fields (permission, resource key, field env vars) default to sensible values from the schema. Use `--dry-run` to preview the updated manifest without writing. For all available options, run `npx @databricks/appkit plugin add-resource --help`.