feat: appkit exposed apis

chore: fixup

chore: fixup

chore: fixup

chore: fixup

chore: fixup

chore: fixup

Author: MarioCadenas

apps/dev-playground/server/reconnect-plugin.ts

@@ -15,7 +15,7 @@ interface ReconnectStreamResponse {
 
 export class ReconnectPlugin extends Plugin {
   public name = "reconnect";
-  public envVars = [];
+  protected envVars: string[] = [];
 
   injectRoutes(router: IAppRouter): void {
     this.route<ReconnectResponse>(router, {

apps/dev-playground/server/telemetry-example-plugin.ts

@@ -17,7 +17,7 @@ import type { Request, Response, Router } from "express";
 
 class TelemetryExamples extends Plugin {
   public name = "telemetry-examples" as const;
-  public envVars: string[] = [];
+  protected envVars: string[] = [];
 
   private requestCounter: Counter;
   private durationHistogram: Histogram;
@@ -516,5 +516,5 @@ class TelemetryExamples extends Plugin {
 export const telemetryExamples = toPlugin<
   typeof TelemetryExamples,
   BasePluginConfig,
-  "telemetry-examples"
->(TelemetryExamples, "telemetry-examples");
+  "telemetryExamples"
+>(TelemetryExamples, "telemetryExamples");

docs/docs/api/appkit/Class.AppKitError.md

@@ -76,6 +76,12 @@ readonly optional cause: Error;
 
 Optional cause of the error
 
+#### Overrides
+
+```ts
+Error.cause
+```
+
 ***
 
 ### code

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

@@ -142,11 +142,11 @@ BasePlugin.abortActiveOperations
 asUser(req: Request): this;
 ```
 
-Execute operations using the user's identity from the request.
+Defined in: [appkit/src/plugin/plugin.ts:127](https://github.com/databricks/appkit/blob/main/packages/appkit/src/plugin/plugin.ts#L127)
 
-Returns a scoped instance of this plugin where all method calls
-will execute with the user's Databricks credentials instead of
-the service principal.
+Execute operations using the user's identity from the request.
+Returns a proxy of this plugin where all method calls execute
+with the user's Databricks credentials instead of the service principal.
 
 #### Parameters
 
@@ -158,31 +158,12 @@ the service principal.
 
 `this`
 
-A scoped plugin instance that executes as the user
+A proxied plugin instance that executes as the user
 
 #### Throws
 
 Error if user token is not available in request headers
 
-#### Example
-
-```typescript
-// In route handler - execute query as the requesting user
-router.post('/users/me/query/:key', async (req, res) => {
-  const result = await this.asUser(req).query(req.params.key)
-  res.json(result)
-})
-
-// Mixed execution in same handler
-router.post('/dashboard', async (req, res) => {
-  const [systemData, userData] = await Promise.all([
-    this.getSystemStats(),                  // Service principal
-    this.asUser(req).getUserPreferences(), // User context
-  ])
-  res.json({ systemData, userData })
-})
-```
-
 ***
 
 ### execute()
@@ -194,6 +175,8 @@ protected execute<T>(
 userKey?: string): Promise<T | undefined>;
 ```
 
+Defined in: [appkit/src/plugin/plugin.ts:249](https://github.com/databricks/appkit/blob/main/packages/appkit/src/plugin/plugin.ts#L249)
+
 #### Type Parameters
 
 | Type Parameter |
@@ -224,6 +207,8 @@ protected executeStream<T>(
 userKey?: string): Promise<void>;
 ```
 
+Defined in: [appkit/src/plugin/plugin.ts:187](https://github.com/databricks/appkit/blob/main/packages/appkit/src/plugin/plugin.ts#L187)
+
 #### Type Parameters
 
 | Type Parameter |
@@ -293,6 +278,8 @@ BasePlugin.injectRoutes
 protected registerEndpoint(name: string, path: string): void;
 ```
 
+Defined in: [appkit/src/plugin/plugin.ts:274](https://github.com/databricks/appkit/blob/main/packages/appkit/src/plugin/plugin.ts#L274)
+
 #### Parameters
 
 | Parameter | Type |
@@ -312,6 +299,8 @@ protected registerEndpoint(name: string, path: string): void;
 protected route<_TResponse>(router: Router, config: RouteConfig): void;
 ```
 
+Defined in: [appkit/src/plugin/plugin.ts:278](https://github.com/databricks/appkit/blob/main/packages/appkit/src/plugin/plugin.ts#L278)
+
 #### Type Parameters
 
 | Type Parameter |
@@ -331,6 +320,30 @@ protected route<_TResponse>(router: Router, config: RouteConfig): void;
 
 ***
 
+### sdk()
+
+```ts
+sdk(): unknown;
+```
+
+Defined in: [appkit/src/plugin/plugin.ts:114](https://github.com/databricks/appkit/blob/main/packages/appkit/src/plugin/plugin.ts#L114)
+
+Returns the public SDK for this plugin.
+Override this to define a custom public API.
+By default, returns an empty object.
+
+#### Returns
+
+`unknown`
+
+#### Implementation of
+
+```ts
+BasePlugin.sdk
+```
+
+***
+
 ### setup()
 
 ```ts

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

@@ -8,6 +8,8 @@ function createApp<T>(config: {
 }): Promise<PluginMap<T>>;
 ```
 
+Defined in: [appkit/src/core/appkit.ts:176](https://github.com/databricks/appkit/blob/main/packages/appkit/src/core/appkit.ts#L176)
+
 Bootstraps AppKit with the provided configuration.
 
 ## Type Parameters

docs/docs/api/appkit/Function.getExecutionContext.md

@@ -0,0 +1,20 @@
+# Function: getExecutionContext()
+
+```ts
+function getExecutionContext(): ExecutionContext;
+```
+
+Defined in: [appkit/src/context/execution-context.ts:35](https://github.com/databricks/appkit/blob/main/packages/appkit/src/context/execution-context.ts#L35)
+
+Get the current execution context.
+
+- If running inside a user context (via asUser), returns the user context
+- Otherwise, returns the service context
+
+## Returns
+
+`ExecutionContext`
+
+## Throws
+
+Error if ServiceContext is not initialized

docs/docs/api/appkit/Interface.BasePluginConfig.md

@@ -1,6 +1,7 @@
 # Interface: BasePluginConfig
 
 Base configuration interface for AppKit plugins
+Defined in: [shared/src/plugin.ts:19](https://github.com/databricks/appkit/blob/main/packages/shared/src/plugin.ts#L19)
 
 ## Indexable
 
@@ -16,6 +17,8 @@ Base configuration interface for AppKit plugins
 optional host: string;
 ```
 
+Defined in: [shared/src/plugin.ts:21](https://github.com/databricks/appkit/blob/main/packages/shared/src/plugin.ts#L21)
+
 ***
 
 ### name?
@@ -24,10 +27,14 @@ optional host: string;
 optional name: string;
 ```
 
+Defined in: [shared/src/plugin.ts:20](https://github.com/databricks/appkit/blob/main/packages/shared/src/plugin.ts#L20)
+
 ***
 
 ### telemetry?
 
 ```ts
 optional telemetry: TelemetryOptions;
 ```
+
+Defined in: [shared/src/plugin.ts:29](https://github.com/databricks/appkit/blob/main/packages/shared/src/plugin.ts#L29)

docs/docs/api/appkit/index.md

@@ -46,4 +46,5 @@ plugin architecture, and React integration.
 | ------ | ------ |
 | [appKitTypesPlugin](Function.appKitTypesPlugin.md) | Vite plugin to generate types for AppKit queries. Calls generateFromEntryPoint under the hood. |
 | [createApp](Function.createApp.md) | Bootstraps AppKit with the provided configuration. |
+| [getExecutionContext](Function.getExecutionContext.md) | Get the current execution context. |
 | [isSQLTypeMarker](Function.isSQLTypeMarker.md) | Type guard to check if a value is a SQL type marker |

docs/docs/api/appkit/typedoc-sidebar.ts

@@ -124,6 +124,11 @@ const typedocSidebar: SidebarsConfig = {
           id: "api/appkit/Function.createApp",
           label: "createApp"
         },
+        {
+          type: "doc",
+          id: "api/appkit/Function.getExecutionContext",
+          label: "getExecutionContext"
+        },
         {
           type: "doc",
           id: "api/appkit/Function.isSQLTypeMarker",

docs/docs/plugins.md

@@ -219,17 +219,25 @@ import type express from "express";
 
 class MyPlugin extends Plugin {
   name = "myPlugin";
-  envVars = [];                 // list required env vars here
-
-  injectRoutes(router: express.Router) {
-    this.route(router, {
-      name: "hello",
-      method: "get",
-      path: "/hello",
-      handler: async (_req, res) => {
-        res.json({ ok: true });
-      },
-    });
+  envVars = ["MY_API_KEY"];
+
+  async setup() {
+    // Initialize your plugin
+  }
+
+  myCustomMethod() {
+    // Some implementation
+  }
+
+  async shutdown() {
+    // Clean up resources
+  }
+
+  sdk() {
+    // an object with the methods from this plugin to expose as SDK
+    return {
+      myCustomMethod: this.myCustomMethod
+    }
   }
 }
 
@@ -248,6 +256,23 @@ export const myPlugin = toPlugin<typeof MyPlugin, Record<string, never>, "myPlug
   - **Telemetry**: Instrument your plugin with traces and metrics via `this.telemetry`. See [`ITelemetry`](api/appkit/Interface.ITelemetry.md).
 - **Execution interceptors**: Use `execute()` and `executeStream()` with [`StreamExecutionSettings`](api/appkit/Interface.StreamExecutionSettings.md)
 
+**Consuming your plugin as an SDK**
+
+Optionally, you may want to provide a way to consume your plugin in an imperative way using the AppKit object.
+To do that, your plugin needs to implement the `sdk` method, returning an object with the API methods you want to expose. From the previous example, the plugin could be consumed as follows:
+
+```ts
+const AppKit = await createApp({
+  plugins: [
+    server({ port: 8000 }),
+    analytics(),
+    myPlugin(),
+  ],
+});
+
+AppKit.myPlugin.myCustomMethod();
+```
+
 See the [`Plugin`](api/appkit/Class.Plugin.md) API reference for complete documentation.
 
 ## Caching