@databricks/appkit 0.31.0 → 0.32.0

package/dist/shared/src/plugin.d.ts

@@ -13,6 +13,14 @@ interface BasePlugin {
   getSkipBodyParsingPaths?(): ReadonlySet<string>;
   exports?(): unknown;
   clientConfig?(): Record<string, unknown>;
+  /**
+   * Binds runtime dependencies (telemetry, cache, plugin context) after the
+   * plugin has been constructed. Called by the AppKit core before `setup()`.
+   */
+  attachContext?(deps: {
+    context?: unknown;
+    telemetryConfig?: TelemetryOptions;
+  }): void;
 }
 /** Base configuration interface for AppKit plugins */
 interface BasePluginConfig {

package/dist/shared/src/plugin.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"plugin.d.ts","names":[],"sources":["../../../../shared/src/plugin.ts"],"mappings":";;;;;;UAYiB,UAAA;EACf,IAAA;EAEA,qBAAA;EAEA,KAAA,IAAS,OAAA;EAET,YAAA,CAAa,MAAA,EAAQ,OAAA,CAAQ,MAAA;EAE7B,YAAA,IAAgB,iBAAA;EAEhB,uBAAA,KAA4B,WAAA;EAE5B,OAAA;EAEA,YAAA,KAAiB,MAAA;AAAA;;UAIF,gBAAA;EACf,IAAA;EACA,IAAA;EAAA,CAEC,GAAA;EAMD,SAAA,GAAY,gBAAA;AAAA;AAAA,KAGF,gBAAA;EAGN,MAAA;EACA,OAAA;EACA,IAAA;AAAA;AAAA,KAQM,WAAA;AA1BZ;;;;AAAA,KAgCY,iBAAA,KACN,gBAAA,YACM,UAAA,GAAa,UAAA,UAEvB,MAAA,EAAQ,CAAA,KACL,CAAA;EACH,cAAA,GAAiB,MAAA;EACjB,KAAA,GAAQ,WAAA;EA7BR;;;;EAkCA,QAAA,EAAU,cAAA;EA/BgB;;;;EAoC1B,uBAAA,EAAyB,MAAA,EAAQ,CAAA,GAAI,mBAAA;AAAA;;;AAvBvC;;;;;AAMA;;UA6BiB,cAAA,wCACP,IAAA,CACN,gBAAA;EAGF,IAAA,EAAM,KAAA;EACN,SAAA;IACE,QAAA,EAAU,IAAA,CAAK,mBAAA;IACf,QAAA,EAAU,IAAA,CAAK,mBAAA;EAAA;EAEjB,MAAA;IACE,MAAA,EAAQ,WAAA;EAAA;AAAA;;;;;;;;;UAYK,mBAAA,SAA4B,qBAAA;EAC3C,MAAA,EAAQ,MAAA,SAAe,kBAAA;EACvB,QAAA;AAAA;;;;;;KAoCU,aAAA,WAAwB,UAAA,IAClC,CAAA,sCAAqC,CAAA,GAAI,MAAA;;;;;;;;KAS/B,UAAA,QAAkB,GAAA,cAAgB,IAAA,mBAC1C,GAAA,GACA,GAAA;EAlEU;;;;;EAwER,MAAA,GAAS,GAAA,EAAK,WAAA,KAAgB,GAAA;AAAA;;;;AAxDpC;;;;;KAmEY,SAAA,oBACS,UAAA,CAAW,iBAAA,gCAExB,CAAA,YAAa,CAAA,WAAY,UAAA,CAC7B,aAAA,CAAc,YAAA,CAAa,CAAA;;KAKnB,UAAA;EAAwB,MAAA,EAAQ,CAAA;EAAG,MAAA,EAAQ,CAAA;EAAG,IAAA,EAAM,CAAA;AAAA;;KAEpD,QAAA,4BACV,MAAA,GAAS,CAAA,KACN,UAAA,CAAW,CAAA,EAAG,CAAA,EAAG,CAAA;;KAGV,UAAA,GAAa,OAAA,CAAQ,MAAA;AAAA,KACrB,YAAA,GAAe,OAAA,CAAQ,QAAA;AAAA,KACvB,WAAA,GAAc,OAAA,CAAQ,OAAA;AAAA,KAEtB,UAAA;AAAA,KAEA,WAAA;EAlDqC,+DAoD/C,IAAA;EACA,MAAA,EAAQ,UAAA;EACR,IAAA;EACA,OAAA,GAAU,GAAA,EAAK,WAAA,EAAa,GAAA,EAAK,YAAA,KAAiB,OAAA,QAvDb;EAyDrC,eAAA;AAAA;;KAIU,iBAAA,GAAoB,MAAA"}
+{"version":3,"file":"plugin.d.ts","names":[],"sources":["../../../../shared/src/plugin.ts"],"mappings":";;;;;;UAYiB,UAAA;EACf,IAAA;EAEA,qBAAA;EAEA,KAAA,IAAS,OAAA;EAET,YAAA,CAAa,MAAA,EAAQ,OAAA,CAAQ,MAAA;EAE7B,YAAA,IAAgB,iBAAA;EAEhB,uBAAA,KAA4B,WAAA;EAE5B,OAAA;EAEA,YAAA,KAAiB,MAAA;EAQmB;;;;EAFpC,aAAA,EAAe,IAAA;IACb,OAAA;IACA,eAAA,GAAkB,gBAAA;EAAA;AAAA;;UAKL,gBAAA;EACf,IAAA;EACA,IAAA;EAAA,CAEC,GAAA;EAMD,SAAA,GAAY,gBAAA;AAAA;AAAA,KAGF,gBAAA;EAGN,MAAA;EACA,OAAA;EACA,IAAA;AAAA;AAAA,KAQM,WAAA;;;;;KAMA,iBAAA,KACN,gBAAA,YACM,UAAA,GAAa,UAAA,UAEvB,MAAA,EAAQ,CAAA,KACL,CAAA;EACH,cAAA,GAAiB,MAAA;EACjB,KAAA,GAAQ,WAAA;EA7BoB;;AAG9B;;EA+BE,QAAA,EAAU,cAAA;EA/BgB;;;;EAoC1B,uBAAA,EAAyB,MAAA,EAAQ,CAAA,GAAI,mBAAA;AAAA;AAvBvC;;;;;AAMA;;;;AANA,UAmCiB,cAAA,wCACP,IAAA,CACN,gBAAA;EAGF,IAAA,EAAM,KAAA;EACN,SAAA;IACE,QAAA,EAAU,IAAA,CAAK,mBAAA;IACf,QAAA,EAAU,IAAA,CAAK,mBAAA;EAAA;EAEjB,MAAA;IACE,MAAA,EAAQ,WAAA;EAAA;AAAA;;;;;;;;;UAYK,mBAAA,SAA4B,qBAAA;EAC3C,MAAA,EAAQ,MAAA,SAAe,kBAAA;EACvB,QAAA;AAAA;;;;;;KAoCU,aAAA,WAAwB,UAAA,IAClC,CAAA,sCAAqC,CAAA,GAAI,MAAA;;;;;;;;KAS/B,UAAA,QAAkB,GAAA,cAAgB,IAAA,mBAC1C,GAAA,GACA,GAAA;EAjEA;;;;;EAuEE,MAAA,GAAS,GAAA,EAAK,WAAA,KAAgB,GAAA;AAAA;;AAxDpC;;;;;;;KAmEY,SAAA,oBACS,UAAA,CAAW,iBAAA,gCAExB,CAAA,YAAa,CAAA,WAAY,UAAA,CAC7B,aAAA,CAAc,YAAA,CAAa,CAAA;;KAKnB,UAAA;EAAwB,MAAA,EAAQ,CAAA;EAAG,MAAA,EAAQ,CAAA;EAAG,IAAA,EAAM,CAAA;AAAA;;KAEpD,QAAA,4BACV,MAAA,GAAS,CAAA,KACN,UAAA,CAAW,CAAA,EAAG,CAAA,EAAG,CAAA;;KAGV,UAAA,GAAa,OAAA,CAAQ,MAAA;AAAA,KACrB,YAAA,GAAe,OAAA,CAAQ,QAAA;AAAA,KACvB,WAAA,GAAc,OAAA,CAAQ,OAAA;AAAA,KAEtB,UAAA;AAAA,KAEA,WAAA;EAnDwB,+DAqDlC,IAAA;EACA,MAAA,EAAQ,UAAA;EACR,IAAA;EACA,OAAA,GAAU,GAAA,EAAK,WAAA,EAAa,GAAA,EAAK,YAAA,KAAiB,OAAA,QAvDH;EAyD/C,eAAA;AAAA;;KAIU,iBAAA,GAAoB,MAAA"}

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

@@ -139,6 +139,15 @@ protected config: TConfig;
 
 ***
 
+### context?[​](#context "Direct link to context?")
+
+```ts
+protected optional context: PluginContext;
+
+```
+
+***
+
 ### devFileReader[​](#devfilereader "Direct link to devFileReader")
 
 ```ts
@@ -255,6 +264,39 @@ AuthenticationError if user token is not available in request headers (productio
 
 ***
 
+### attachContext()[​](#attachcontext "Direct link to attachContext()")
+
+```ts
+attachContext(deps: {
+  context?: unknown;
+  telemetryConfig?: TelemetryOptions;
+}): void;
+
+```
+
+Binds runtime dependencies (telemetry provider, cache, plugin context) to this plugin. Called by `AppKit._createApp` after construction and before `setup()`. Idempotent: safe to call if the constructor already bound them eagerly. Kept separate so factories can eagerly construct plugin instances without running this before `TelemetryManager.initialize()` / `CacheManager.getInstance()` have run.
+
+#### Parameters[​](#parameters-2 "Direct link to Parameters")
+
+| Parameter               | Type                                                               |
+| ----------------------- | ------------------------------------------------------------------ |
+| `deps`                  | { `context?`: `unknown`; `telemetryConfig?`: `TelemetryOptions`; } |
+| `deps.context?`         | `unknown`                                                          |
+| `deps.telemetryConfig?` | `TelemetryOptions`                                                 |
+
+#### Returns[​](#returns-3 "Direct link to Returns")
+
+`void`
+
+#### Implementation of[​](#implementation-of-2 "Direct link to Implementation of")
+
+```ts
+BasePlugin.attachContext
+
+```
+
+***
+
 ### clientConfig()[​](#clientconfig "Direct link to clientConfig()")
 
 ```ts
@@ -272,7 +314,7 @@ Values must be JSON-serializable plain data (no functions, Dates, classes, Maps,
 
 On the client, read the config with the `usePluginClientConfig` hook (React) or the `getPluginClientConfig` function (vanilla JS), both from `@databricks/appkit-ui`.
 
-#### Returns[​](#returns-3 "Direct link to Returns")
+#### Returns[​](#returns-4 "Direct link to Returns")
 
 `Record`<`string`, `unknown`>
 
@@ -304,7 +346,7 @@ const config = getPluginClientConfig<MyPluginConfig>("myPlugin");
 
 ```
 
-#### Implementation of[​](#implementation-of-2 "Direct link to Implementation of")
+#### Implementation of[​](#implementation-of-3 "Direct link to Implementation of")
 
 ```ts
 BasePlugin.clientConfig
@@ -338,7 +380,7 @@ Errors are never thrown — the method is production-safe.
 | -------------- |
 | `T`            |
 
-#### Parameters[​](#parameters-2 "Direct link to Parameters")
+#### Parameters[​](#parameters-3 "Direct link to Parameters")
 
 | Parameter  | Type                                         |
 | ---------- | -------------------------------------------- |
@@ -346,7 +388,7 @@ Errors are never thrown — the method is production-safe.
 | `options`  | `PluginExecutionSettings`                    |
 | `userKey?` | `string`                                     |
 
-#### Returns[​](#returns-4 "Direct link to Returns")
+#### Returns[​](#returns-5 "Direct link to Returns")
 
 `Promise`<[`ExecutionResult`](./docs/api/appkit/TypeAlias.ExecutionResult.md)<`T`>>
 
@@ -369,7 +411,7 @@ userKey?: string): Promise<void>;
 | -------------- |
 | `T`            |
 
-#### Parameters[​](#parameters-3 "Direct link to Parameters")
+#### Parameters[​](#parameters-4 "Direct link to Parameters")
 
 | Parameter  | Type                                                                                      |
 | ---------- | ----------------------------------------------------------------------------------------- |
@@ -378,7 +420,7 @@ userKey?: string): Promise<void>;
 | `options`  | [`StreamExecutionSettings`](./docs/api/appkit/Interface.StreamExecutionSettings.md) |
 | `userKey?` | `string`                                                                                  |
 
-#### Returns[​](#returns-5 "Direct link to Returns")
+#### Returns[​](#returns-6 "Direct link to Returns")
 
 `Promise`<`void`>
 
@@ -395,7 +437,7 @@ Returns the public exports for this plugin. Override this to define a custom pub
 
 The returned object becomes the plugin's public API on the AppKit instance (e.g. `appkit.myPlugin.method()`). AppKit automatically binds method context and adds `asUser(req)` for user-scoped execution.
 
-#### Returns[​](#returns-6 "Direct link to Returns")
+#### Returns[​](#returns-7 "Direct link to Returns")
 
 `unknown`
 
@@ -416,7 +458,7 @@ appkit.myPlugin.getData();
 
 ```
 
-#### Implementation of[​](#implementation-of-3 "Direct link to Implementation of")
+#### Implementation of[​](#implementation-of-4 "Direct link to Implementation of")
 
 ```ts
 BasePlugin.exports
@@ -432,11 +474,11 @@ getEndpoints(): PluginEndpointMap;
 
 ```
 
-#### Returns[​](#returns-7 "Direct link to Returns")
+#### Returns[​](#returns-8 "Direct link to Returns")
 
 `PluginEndpointMap`
 
-#### Implementation of[​](#implementation-of-4 "Direct link to Implementation of")
+#### Implementation of[​](#implementation-of-5 "Direct link to Implementation of")
 
 ```ts
 BasePlugin.getEndpoints
@@ -452,11 +494,11 @@ getSkipBodyParsingPaths(): ReadonlySet<string>;
 
 ```
 
-#### Returns[​](#returns-8 "Direct link to Returns")
+#### Returns[​](#returns-9 "Direct link to Returns")
 
 `ReadonlySet`<`string`>
 
-#### Implementation of[​](#implementation-of-5 "Direct link to Implementation of")
+#### Implementation of[​](#implementation-of-6 "Direct link to Implementation of")
 
 ```ts
 BasePlugin.getSkipBodyParsingPaths
@@ -472,17 +514,17 @@ injectRoutes(_: Router): void;
 
 ```
 
-#### Parameters[​](#parameters-4 "Direct link to Parameters")
+#### Parameters[​](#parameters-5 "Direct link to Parameters")
 
 | Parameter | Type     |
 | --------- | -------- |
 | `_`       | `Router` |
 
-#### Returns[​](#returns-9 "Direct link to Returns")
+#### Returns[​](#returns-10 "Direct link to Returns")
 
 `void`
 
-#### Implementation of[​](#implementation-of-6 "Direct link to Implementation of")
+#### Implementation of[​](#implementation-of-7 "Direct link to Implementation of")
 
 ```ts
 BasePlugin.injectRoutes
@@ -498,14 +540,14 @@ protected registerEndpoint(name: string, path: string): void;
 
 ```
 
-#### Parameters[​](#parameters-5 "Direct link to Parameters")
+#### Parameters[​](#parameters-6 "Direct link to Parameters")
 
 | Parameter | Type     |
 | --------- | -------- |
 | `name`    | `string` |
 | `path`    | `string` |
 
-#### Returns[​](#returns-10 "Direct link to Returns")
+#### Returns[​](#returns-11 "Direct link to Returns")
 
 `void`
 
@@ -522,13 +564,13 @@ Resolve the effective user ID from a request.
 
 Returns the `x-forwarded-user` header when present. In development mode (`NODE_ENV=development`) falls back to the current context user ID so that callers outside an active `runInUserContext` scope still get a consistent value.
 
-#### Parameters[​](#parameters-6 "Direct link to Parameters")
+#### Parameters[​](#parameters-7 "Direct link to Parameters")
 
 | Parameter | Type      |
 | --------- | --------- |
 | `req`     | `Request` |
 
-#### Returns[​](#returns-11 "Direct link to Returns")
+#### Returns[​](#returns-12 "Direct link to Returns")
 
 `string`
 
@@ -551,14 +593,14 @@ protected route<_TResponse>(router: Router, config: RouteConfig): void;
 | -------------- |
 | `_TResponse`   |
 
-#### Parameters[​](#parameters-7 "Direct link to Parameters")
+#### Parameters[​](#parameters-8 "Direct link to Parameters")
 
 | Parameter | Type          |
 | --------- | ------------- |
 | `router`  | `Router`      |
 | `config`  | `RouteConfig` |
 
-#### Returns[​](#returns-12 "Direct link to Returns")
+#### Returns[​](#returns-13 "Direct link to Returns")
 
 `void`
 
@@ -571,11 +613,11 @@ setup(): Promise<void>;
 
 ```
 
-#### Returns[​](#returns-13 "Direct link to Returns")
+#### Returns[​](#returns-14 "Direct link to Returns")
 
 `Promise`<`void`>
 
-#### Implementation of[​](#implementation-of-7 "Direct link to Implementation of")
+#### Implementation of[​](#implementation-of-8 "Direct link to Implementation of")
 
 ```ts
 BasePlugin.setup

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

@@ -4,6 +4,7 @@
 function createApp<T>(config: {
   cache?: CacheConfig;
   client?: WorkspaceClient;
+  disableInternalTelemetry?: boolean;
   onPluginsReady?: (appkit: PluginMap<T>) => void | Promise<void>;
   plugins?: T;
   telemetry?: TelemetryConfig;
@@ -23,14 +24,15 @@ Initializes telemetry, cache, and service context, then registers plugins in pha
 
 ## Parameters[​](#parameters "Direct link to Parameters")
 
-| Parameter                | Type                                                                                                                                                                                                                                                                                                     |
-| ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `config`                 | { `cache?`: [`CacheConfig`](./docs/api/appkit/Interface.CacheConfig.md); `client?`: `WorkspaceClient`; `onPluginsReady?`: (`appkit`: `PluginMap`<`T`>) => `void` \| `Promise`<`void`>; `plugins?`: `T`; `telemetry?`: [`TelemetryConfig`](./docs/api/appkit/Interface.TelemetryConfig.md); } |
-| `config.cache?`          | [`CacheConfig`](./docs/api/appkit/Interface.CacheConfig.md)                                                                                                                                                                                                                                        |
-| `config.client?`         | `WorkspaceClient`                                                                                                                                                                                                                                                                                        |
-| `config.onPluginsReady?` | (`appkit`: `PluginMap`<`T`>) => `void` \| `Promise`<`void`>                                                                                                                                                                                                                                              |
-| `config.plugins?`        | `T`                                                                                                                                                                                                                                                                                                      |
-| `config.telemetry?`      | [`TelemetryConfig`](./docs/api/appkit/Interface.TelemetryConfig.md)                                                                                                                                                                                                                                |
+| Parameter                          | Type                                                                                                                                                                                                                                                                                                                                             |
+| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `config`                           | { `cache?`: [`CacheConfig`](./docs/api/appkit/Interface.CacheConfig.md); `client?`: `WorkspaceClient`; `disableInternalTelemetry?`: `boolean`; `onPluginsReady?`: (`appkit`: `PluginMap`<`T`>) => `void` \| `Promise`<`void`>; `plugins?`: `T`; `telemetry?`: [`TelemetryConfig`](./docs/api/appkit/Interface.TelemetryConfig.md); } |
+| `config.cache?`                    | [`CacheConfig`](./docs/api/appkit/Interface.CacheConfig.md)                                                                                                                                                                                                                                                                                |
+| `config.client?`                   | `WorkspaceClient`                                                                                                                                                                                                                                                                                                                                |
+| `config.disableInternalTelemetry?` | `boolean`                                                                                                                                                                                                                                                                                                                                        |
+| `config.onPluginsReady?`           | (`appkit`: `PluginMap`<`T`>) => `void` \| `Promise`<`void`>                                                                                                                                                                                                                                                                                      |
+| `config.plugins?`                  | `T`                                                                                                                                                                                                                                                                                                                                              |
+| `config.telemetry?`                | [`TelemetryConfig`](./docs/api/appkit/Interface.TelemetryConfig.md)                                                                                                                                                                                                                                                                        |
 
 ## Returns[​](#returns "Direct link to Returns")
 

package/docs/privacy.md

@@ -0,0 +1,41 @@
+# Privacy
+
+AppKit sends a small amount of anonymized usage telemetry to Databricks so the team can understand how the SDK is used and prioritize improvements. This page documents exactly what is sent, when, and how to turn it off.
+
+## What we collect[​](#what-we-collect "Direct link to What we collect")
+
+Every event is a single record with three top-level fields:
+
+| Field            | Type   | Source                                               |
+| ---------------- | ------ | ---------------------------------------------------- |
+| `event_name`     | enum   | One of `APP_STARTUP`, `HEARTBEAT`, `REQUEST_METRICS` |
+| `app_id`         | string | The app's OAuth client UUID (`DATABRICKS_CLIENT_ID`) |
+| `appkit_version` | string | The AppKit SDK version                               |
+
+Each event also carries one of three event-specific bodies:
+
+* **`APP_STARTUP`** — emitted once when `createApp` finishes booting. Empty body.
+
+* **`HEARTBEAT`** — emitted every five minutes from a running app. Empty body.
+
+* **`REQUEST_METRICS`** — emitted once per minute, one record per HTTP endpoint that received traffic in the window. Each record contains:
+
+  <!-- -->
+
+  * `endpoint` — the route template (e.g. `GET /api/genie/:space_id/messages`), never the raw request URL or any user-provided values.
+  * `request_count`
+  * `request_latency_ms_avg`
+  * `response_count_http4xx`
+  * `response_count_http5xx`
+
+## How to opt out[​](#how-to-opt-out "Direct link to How to opt out")
+
+Set any one of the following:
+
+```sh
+DISABLE_APPKIT_INTERNAL_TELEMETRY=true
+DO_NOT_TRACK=1
+
+```
+
+Either fully disables the reporter — no events are emitted and no network calls are made.

package/llms.txt

@@ -29,6 +29,7 @@ npx @databricks/appkit docs <query>
 - [Development](./docs/development.md): AppKit provides multiple development workflows to suit different needs: local development with hot reload, AI-assisted development with Agent Skills, and remote tunneling to deployed backends.
 - [FAQ](./docs/faq.md): Integrations
 - [Plugins](./docs/plugins.md): Plugins are modular extensions that add capabilities to your AppKit application. They follow a defined lifecycle and have access to shared services like caching, telemetry, and streaming.
+- [Privacy](./docs/privacy.md): AppKit sends a small amount of anonymized usage telemetry to Databricks
 
 ## Development
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@databricks/appkit",
   "type": "module",
-  "version": "0.31.0",
+  "version": "0.32.0",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "packageManager": "pnpm@10.21.0",
@@ -44,7 +44,7 @@
   "dependencies": {
     "@ast-grep/napi": "0.37.0",
     "@databricks/lakebase": "0.3.0",
-    "@databricks/sdk-experimental": "0.16.0",
+    "@databricks/sdk-experimental": "0.17.0",
     "@opentelemetry/api": "1.9.0",
     "@opentelemetry/api-logs": "0.208.0",
     "@opentelemetry/auto-instrumentations-node": "0.67.2",
@@ -64,6 +64,7 @@
     "dotenv": "16.6.1",
     "express": "4.22.0",
     "get-port": "7.2.0",
+    "js-yaml": "4.1.1",
     "obug": "2.1.1",
     "pg": "8.18.0",
     "picocolors": "1.1.1",
@@ -79,6 +80,7 @@
   "devDependencies": {
     "@opentelemetry/context-async-hooks": "2.6.1",
     "@types/express": "4.17.25",
+    "@types/js-yaml": "4.0.9",
     "@types/json-schema": "7.0.15",
     "@types/pg": "8.16.0",
     "@types/ws": "8.18.1",