@databricks/appkit 0.21.0 → 0.23.0

package/dist/plugins/serving/serving.d.ts

@@ -0,0 +1,38 @@
+import { IAppRouter, ToPlugin } from "../../shared/src/plugin.js";
+import "../../shared/src/index.js";
+import { ExecutionResult } from "../../plugin/execution-result.js";
+import { Plugin } from "../../plugin/plugin.js";
+import "../../plugin/index.js";
+import { PluginManifest, ResourceRequirement } from "../../registry/types.js";
+import "../../registry/index.js";
+import { IServingConfig, ServingEndpointMethods, ServingFactory } from "./types.js";
+import express from "express";
+
+//#region src/plugins/serving/serving.d.ts
+declare class ServingPlugin extends Plugin {
+  static manifest: PluginManifest<"serving">;
+  protected static description: string;
+  protected config: IServingConfig;
+  private readonly endpoints;
+  private readonly isNamedMode;
+  private schemaAllowlists;
+  constructor(config: IServingConfig);
+  setup(): Promise<void>;
+  static getResourceRequirements(config: IServingConfig): ResourceRequirement[];
+  private resolveAndFilter;
+  injectRoutes(router: IAppRouter): void;
+  _handleInvoke(req: express.Request, res: express.Response): Promise<void>;
+  _handleStream(req: express.Request, res: express.Response): Promise<void>;
+  invoke(alias: string, body: Record<string, unknown>): Promise<ExecutionResult<unknown>>;
+  clientConfig(): Record<string, unknown>;
+  shutdown(): Promise<void>;
+  protected createEndpointAPI(alias: string): ServingEndpointMethods;
+  exports(): ServingFactory;
+}
+/**
+ * @internal
+ */
+declare const serving: ToPlugin<typeof ServingPlugin, IServingConfig, "serving">;
+//#endregion
+export { ServingPlugin, serving };
+//# sourceMappingURL=serving.d.ts.map

package/dist/plugins/serving/serving.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"serving.d.ts","names":[],"sources":["../../../src/plugins/serving/serving.ts"],"mappings":";;;;;;;;;;;cAyCa,aAAA,SAAsB,MAAA;EAAA,OAC1B,QAAA,EAAuB,cAAA;EAAA,iBAEb,WAAA;EAAA,UAEC,MAAA,EAAQ,cAAA;EAAA,iBAET,SAAA;EAAA,iBACA,WAAA;EAAA,QACT,gBAAA;cAEI,MAAA,EAAQ,cAAA;EAed,KAAA,CAAA,GAAS,OAAA;EAAA,OAiBR,uBAAA,CACL,MAAA,EAAQ,cAAA,GACP,mBAAA;EAAA,QAqBK,gBAAA;EA0BR,YAAA,CAAa,MAAA,EAAQ,UAAA;EA0Cf,aAAA,CACJ,GAAA,EAAK,OAAA,CAAQ,OAAA,EACb,GAAA,EAAK,OAAA,CAAQ,QAAA,GACZ,OAAA;EA0BG,aAAA,CACJ,GAAA,EAAK,OAAA,CAAQ,OAAA,EACb,GAAA,EAAK,OAAA,CAAQ,QAAA,GACZ,OAAA;EA2DG,MAAA,CACJ,KAAA,UACA,IAAA,EAAM,MAAA,oBACL,OAAA,CAAQ,eAAA;EAiBX,YAAA,CAAA,GAAgB,MAAA;EAOV,QAAA,CAAA,GAAY,OAAA;EAAA,UAIR,iBAAA,CAAkB,KAAA,WAAgB,sBAAA;EAM5C,OAAA,CAAA,GAAW,cAAA;AAAA;;;;cAmBA,OAAA,EAAO,QAAA,QAAA,aAAA,EAAA,cAAA"}

package/dist/plugins/serving/serving.js

@@ -0,0 +1,213 @@
+import { createLogger } from "../../logging/logger.js";
+import { getWorkspaceClient } from "../../context/execution-context.js";
+import { init_context } from "../../context/index.js";
+import { ResourceType } from "../../registry/types.generated.js";
+import "../../registry/index.js";
+import { Plugin } from "../../plugin/plugin.js";
+import { toPlugin } from "../../plugin/to-plugin.js";
+import "../../plugin/index.js";
+import "../../logging/index.js";
+import { invoke, stream } from "../../connectors/serving/client.js";
+import { servingInvokeDefaults } from "./defaults.js";
+import manifest_default from "./manifest.js";
+import { filterRequestBody, loadEndpointSchemas } from "./schema-filter.js";
+import path from "node:path";
+import { Readable } from "node:stream";
+import { pipeline } from "node:stream/promises";
+
+//#region src/plugins/serving/serving.ts
+init_context();
+const logger = createLogger("serving");
+var EndpointNotFoundError = class extends Error {
+	constructor(alias) {
+		super(`Unknown endpoint alias: ${alias}`);
+	}
+};
+var EndpointNotConfiguredError = class extends Error {
+	constructor(alias, envVar) {
+		super(`Endpoint '${alias}' is not configured: env var '${envVar}' is not set`);
+	}
+};
+var ServingPlugin = class extends Plugin {
+	static manifest = manifest_default;
+	static description = "Authenticated proxy to Databricks Model Serving endpoints";
+	endpoints;
+	isNamedMode;
+	schemaAllowlists = /* @__PURE__ */ new Map();
+	constructor(config) {
+		super(config);
+		this.config = config;
+		if (config.endpoints) {
+			this.endpoints = config.endpoints;
+			this.isNamedMode = true;
+		} else {
+			this.endpoints = { default: { env: "DATABRICKS_SERVING_ENDPOINT_NAME" } };
+			this.isNamedMode = false;
+		}
+	}
+	async setup() {
+		this.schemaAllowlists = await loadEndpointSchemas(path.join(process.cwd(), "node_modules", ".databricks", "appkit", ".appkit-serving-types-cache.json"));
+		if (this.schemaAllowlists.size > 0) logger.debug("Loaded schema allowlists for %d endpoint(s)", this.schemaAllowlists.size);
+	}
+	static getResourceRequirements(config) {
+		const endpoints = config.endpoints ?? { default: { env: "DATABRICKS_SERVING_ENDPOINT_NAME" } };
+		return Object.entries(endpoints).map(([alias, endpointConfig]) => ({
+			type: ResourceType.SERVING_ENDPOINT,
+			alias: `serving-${alias}`,
+			resourceKey: `serving-${alias}`,
+			description: `Model Serving endpoint for "${alias}" inference`,
+			permission: "CAN_QUERY",
+			fields: { name: {
+				env: endpointConfig.env,
+				description: `Serving endpoint name for "${alias}"`
+			} },
+			required: true
+		}));
+	}
+	resolveAndFilter(alias, body) {
+		const config = this.endpoints[alias];
+		if (!config) throw new EndpointNotFoundError(alias);
+		const name = process.env[config.env];
+		if (!name) throw new EndpointNotConfiguredError(alias, config.env);
+		return {
+			endpoint: { name },
+			filteredBody: filterRequestBody(body, this.schemaAllowlists, alias, this.config.filterMode)
+		};
+	}
+	injectRoutes(router) {
+		if (this.isNamedMode) {
+			this.route(router, {
+				name: "invoke",
+				method: "post",
+				path: "/:alias/invoke",
+				handler: async (req, res) => {
+					await this.asUser(req)._handleInvoke(req, res);
+				}
+			});
+			this.route(router, {
+				name: "stream",
+				method: "post",
+				path: "/:alias/stream",
+				handler: async (req, res) => {
+					await this.asUser(req)._handleStream(req, res);
+				}
+			});
+		} else {
+			this.route(router, {
+				name: "invoke",
+				method: "post",
+				path: "/invoke",
+				handler: async (req, res) => {
+					req.params.alias = "default";
+					await this.asUser(req)._handleInvoke(req, res);
+				}
+			});
+			this.route(router, {
+				name: "stream",
+				method: "post",
+				path: "/stream",
+				handler: async (req, res) => {
+					req.params.alias = "default";
+					await this.asUser(req)._handleStream(req, res);
+				}
+			});
+		}
+	}
+	async _handleInvoke(req, res) {
+		const { alias } = req.params;
+		const rawBody = req.body;
+		try {
+			const result = await this.invoke(alias, rawBody);
+			if (!result.ok) {
+				res.status(result.status).json({ error: result.message });
+				return;
+			}
+			res.json(result.data);
+		} catch (err) {
+			const message = err instanceof Error ? err.message : "Invocation failed";
+			if (err instanceof EndpointNotFoundError) res.status(404).json({ error: message });
+			else if (err instanceof EndpointNotConfiguredError || message.startsWith("Unknown request parameters:")) res.status(400).json({ error: message });
+			else res.status(502).json({ error: message });
+		}
+	}
+	async _handleStream(req, res) {
+		const { alias } = req.params;
+		const rawBody = req.body;
+		let endpoint;
+		let filteredBody;
+		try {
+			({endpoint, filteredBody} = this.resolveAndFilter(alias, rawBody));
+		} catch (err) {
+			const message = err instanceof Error ? err.message : "Invalid request";
+			const status = err instanceof EndpointNotFoundError ? 404 : 400;
+			res.status(status).json({ error: message });
+			return;
+		}
+		const timeout = this.config.timeout ?? 12e4;
+		const workspaceClient = getWorkspaceClient();
+		let rawStream;
+		try {
+			rawStream = await stream(workspaceClient, endpoint.name, filteredBody);
+		} catch (err) {
+			const message = err instanceof Error ? err.message : "Streaming request failed";
+			res.status(502).json({ error: message });
+			return;
+		}
+		res.setHeader("Content-Type", "text/event-stream");
+		res.setHeader("Cache-Control", "no-cache");
+		res.setHeader("Content-Encoding", "none");
+		res.flushHeaders();
+		const nodeStream = Readable.fromWeb(rawStream);
+		const abortController = new AbortController();
+		const timeoutId = setTimeout(() => abortController.abort(), timeout);
+		req.on("close", () => abortController.abort());
+		try {
+			await pipeline(nodeStream, res, { signal: abortController.signal });
+		} catch (err) {
+			if (err instanceof Error && err.name !== "AbortError") logger.warn("Stream pipe error: %s", err.message);
+		} finally {
+			clearTimeout(timeoutId);
+		}
+	}
+	async invoke(alias, body) {
+		const { endpoint, filteredBody } = this.resolveAndFilter(alias, body);
+		const workspaceClient = getWorkspaceClient();
+		const timeout = this.config.timeout ?? 12e4;
+		return this.execute(() => invoke(workspaceClient, endpoint.name, filteredBody), { default: {
+			...servingInvokeDefaults,
+			timeout
+		} });
+	}
+	clientConfig() {
+		return {
+			isNamedMode: this.isNamedMode,
+			aliases: Object.keys(this.endpoints)
+		};
+	}
+	async shutdown() {
+		this.streamManager.abortAll();
+	}
+	createEndpointAPI(alias) {
+		return { invoke: (body) => this.invoke(alias, body) };
+	}
+	exports() {
+		const resolveEndpoint = (alias) => {
+			const resolved = alias ?? "default";
+			return {
+				...this.createEndpointAPI(resolved),
+				asUser: (req) => {
+					return this.asUser(req).createEndpointAPI(resolved);
+				}
+			};
+		};
+		return resolveEndpoint;
+	}
+};
+/**
+* @internal
+*/
+const serving = toPlugin(ServingPlugin);
+
+//#endregion
+export { ServingPlugin, serving };
+//# sourceMappingURL=serving.js.map

package/dist/plugins/serving/serving.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"serving.js","names":["manifest","servingConnector.stream","servingConnector.invoke"],"sources":["../../../src/plugins/serving/serving.ts"],"sourcesContent":["import path from \"node:path\";\nimport { Readable } from \"node:stream\";\nimport { pipeline } from \"node:stream/promises\";\nimport type express from \"express\";\nimport type { IAppRouter } from \"shared\";\nimport * as servingConnector from \"../../connectors/serving/client\";\nimport { getWorkspaceClient } from \"../../context\";\nimport { createLogger } from \"../../logging\";\nimport { type ExecutionResult, Plugin, toPlugin } from \"../../plugin\";\nimport type { PluginManifest, ResourceRequirement } from \"../../registry\";\nimport { ResourceType } from \"../../registry\";\nimport { servingInvokeDefaults } from \"./defaults\";\nimport manifest from \"./manifest.json\";\nimport { filterRequestBody, loadEndpointSchemas } from \"./schema-filter\";\nimport type {\n  EndpointConfig,\n  IServingConfig,\n  ServingEndpointMethods,\n  ServingFactory,\n} from \"./types\";\n\nconst logger = createLogger(\"serving\");\n\nclass EndpointNotFoundError extends Error {\n  constructor(alias: string) {\n    super(`Unknown endpoint alias: ${alias}`);\n  }\n}\n\nclass EndpointNotConfiguredError extends Error {\n  constructor(alias: string, envVar: string) {\n    super(\n      `Endpoint '${alias}' is not configured: env var '${envVar}' is not set`,\n    );\n  }\n}\n\ninterface ResolvedEndpoint {\n  name: string;\n}\n\nexport class ServingPlugin extends Plugin {\n  static manifest = manifest as PluginManifest<\"serving\">;\n\n  protected static description =\n    \"Authenticated proxy to Databricks Model Serving endpoints\";\n  protected declare config: IServingConfig;\n\n  private readonly endpoints: Record<string, EndpointConfig>;\n  private readonly isNamedMode: boolean;\n  private schemaAllowlists = new Map<string, Set<string>>();\n\n  constructor(config: IServingConfig) {\n    super(config);\n    this.config = config;\n\n    if (config.endpoints) {\n      this.endpoints = config.endpoints;\n      this.isNamedMode = true;\n    } else {\n      this.endpoints = {\n        default: { env: \"DATABRICKS_SERVING_ENDPOINT_NAME\" },\n      };\n      this.isNamedMode = false;\n    }\n  }\n\n  async setup(): Promise<void> {\n    const cacheFile = path.join(\n      process.cwd(),\n      \"node_modules\",\n      \".databricks\",\n      \"appkit\",\n      \".appkit-serving-types-cache.json\",\n    );\n    this.schemaAllowlists = await loadEndpointSchemas(cacheFile);\n    if (this.schemaAllowlists.size > 0) {\n      logger.debug(\n        \"Loaded schema allowlists for %d endpoint(s)\",\n        this.schemaAllowlists.size,\n      );\n    }\n  }\n\n  static getResourceRequirements(\n    config: IServingConfig,\n  ): ResourceRequirement[] {\n    const endpoints = config.endpoints ?? {\n      default: { env: \"DATABRICKS_SERVING_ENDPOINT_NAME\" },\n    };\n\n    return Object.entries(endpoints).map(([alias, endpointConfig]) => ({\n      type: ResourceType.SERVING_ENDPOINT,\n      alias: `serving-${alias}`,\n      resourceKey: `serving-${alias}`,\n      description: `Model Serving endpoint for \"${alias}\" inference`,\n      permission: \"CAN_QUERY\" as const,\n      fields: {\n        name: {\n          env: endpointConfig.env,\n          description: `Serving endpoint name for \"${alias}\"`,\n        },\n      },\n      required: true,\n    }));\n  }\n\n  private resolveAndFilter(\n    alias: string,\n    body: Record<string, unknown>,\n  ): { endpoint: ResolvedEndpoint; filteredBody: Record<string, unknown> } {\n    const config = this.endpoints[alias];\n    if (!config) {\n      throw new EndpointNotFoundError(alias);\n    }\n\n    const name = process.env[config.env];\n    if (!name) {\n      throw new EndpointNotConfiguredError(alias, config.env);\n    }\n\n    const endpoint: ResolvedEndpoint = { name };\n    const filteredBody = filterRequestBody(\n      body,\n      this.schemaAllowlists,\n      alias,\n      this.config.filterMode,\n    );\n    return { endpoint, filteredBody };\n  }\n\n  // All serving routes use OBO (On-Behalf-Of) by default, consistent with the\n  // Genie and Files plugins. This ensures per-user CAN_QUERY permissions are enforced.\n  injectRoutes(router: IAppRouter) {\n    if (this.isNamedMode) {\n      this.route(router, {\n        name: \"invoke\",\n        method: \"post\",\n        path: \"/:alias/invoke\",\n        handler: async (req: express.Request, res: express.Response) => {\n          await this.asUser(req)._handleInvoke(req, res);\n        },\n      });\n\n      this.route(router, {\n        name: \"stream\",\n        method: \"post\",\n        path: \"/:alias/stream\",\n        handler: async (req: express.Request, res: express.Response) => {\n          await this.asUser(req)._handleStream(req, res);\n        },\n      });\n    } else {\n      this.route(router, {\n        name: \"invoke\",\n        method: \"post\",\n        path: \"/invoke\",\n        handler: async (req: express.Request, res: express.Response) => {\n          req.params.alias = \"default\";\n          await this.asUser(req)._handleInvoke(req, res);\n        },\n      });\n\n      this.route(router, {\n        name: \"stream\",\n        method: \"post\",\n        path: \"/stream\",\n        handler: async (req: express.Request, res: express.Response) => {\n          req.params.alias = \"default\";\n          await this.asUser(req)._handleStream(req, res);\n        },\n      });\n    }\n  }\n\n  async _handleInvoke(\n    req: express.Request,\n    res: express.Response,\n  ): Promise<void> {\n    const { alias } = req.params;\n    const rawBody = req.body as Record<string, unknown>;\n\n    try {\n      const result = await this.invoke(alias, rawBody);\n      if (!result.ok) {\n        res.status(result.status).json({ error: result.message });\n        return;\n      }\n      res.json(result.data);\n    } catch (err) {\n      const message = err instanceof Error ? err.message : \"Invocation failed\";\n      if (err instanceof EndpointNotFoundError) {\n        res.status(404).json({ error: message });\n      } else if (\n        err instanceof EndpointNotConfiguredError ||\n        message.startsWith(\"Unknown request parameters:\")\n      ) {\n        res.status(400).json({ error: message });\n      } else {\n        res.status(502).json({ error: message });\n      }\n    }\n  }\n\n  async _handleStream(\n    req: express.Request,\n    res: express.Response,\n  ): Promise<void> {\n    const { alias } = req.params;\n    const rawBody = req.body as Record<string, unknown>;\n\n    let endpoint: ResolvedEndpoint;\n    let filteredBody: Record<string, unknown>;\n    try {\n      ({ endpoint, filteredBody } = this.resolveAndFilter(alias, rawBody));\n    } catch (err) {\n      const message = err instanceof Error ? err.message : \"Invalid request\";\n      const status = err instanceof EndpointNotFoundError ? 404 : 400;\n      res.status(status).json({ error: message });\n      return;\n    }\n\n    const timeout = this.config.timeout ?? 120_000;\n    const workspaceClient = getWorkspaceClient();\n\n    // Pipe raw SSE bytes from the upstream endpoint directly to the client.\n    // No parsing/re-serialization — the upstream response is already valid SSE.\n    let rawStream: ReadableStream<Uint8Array>;\n    try {\n      rawStream = await servingConnector.stream(\n        workspaceClient,\n        endpoint.name,\n        filteredBody,\n      );\n    } catch (err) {\n      const message =\n        err instanceof Error ? err.message : \"Streaming request failed\";\n      res.status(502).json({ error: message });\n      return;\n    }\n\n    res.setHeader(\"Content-Type\", \"text/event-stream\");\n    res.setHeader(\"Cache-Control\", \"no-cache\");\n    res.setHeader(\"Content-Encoding\", \"none\");\n    res.flushHeaders();\n\n    const nodeStream = Readable.fromWeb(\n      rawStream as import(\"stream/web\").ReadableStream,\n    );\n    const abortController = new AbortController();\n    const timeoutId = setTimeout(() => abortController.abort(), timeout);\n\n    req.on(\"close\", () => abortController.abort());\n\n    try {\n      await pipeline(nodeStream, res, { signal: abortController.signal });\n    } catch (err) {\n      // AbortError is expected on client disconnect or timeout\n      if (err instanceof Error && err.name !== \"AbortError\") {\n        logger.warn(\"Stream pipe error: %s\", err.message);\n      }\n    } finally {\n      clearTimeout(timeoutId);\n    }\n  }\n\n  async invoke(\n    alias: string,\n    body: Record<string, unknown>,\n  ): Promise<ExecutionResult<unknown>> {\n    const { endpoint, filteredBody } = this.resolveAndFilter(alias, body);\n    const workspaceClient = getWorkspaceClient();\n    const timeout = this.config.timeout ?? 120_000;\n\n    return this.execute(\n      () =>\n        servingConnector.invoke(workspaceClient, endpoint.name, filteredBody),\n      {\n        default: {\n          ...servingInvokeDefaults,\n          timeout,\n        },\n      },\n    );\n  }\n\n  clientConfig(): Record<string, unknown> {\n    return {\n      isNamedMode: this.isNamedMode,\n      aliases: Object.keys(this.endpoints),\n    };\n  }\n\n  async shutdown(): Promise<void> {\n    this.streamManager.abortAll();\n  }\n\n  protected createEndpointAPI(alias: string): ServingEndpointMethods {\n    return {\n      invoke: (body: Record<string, unknown>) => this.invoke(alias, body),\n    };\n  }\n\n  exports(): ServingFactory {\n    const resolveEndpoint = (alias?: string) => {\n      const resolved = alias ?? \"default\";\n      const spApi = this.createEndpointAPI(resolved);\n      return {\n        ...spApi,\n        asUser: (req: express.Request) => {\n          const userPlugin = this.asUser(req) as ServingPlugin;\n          return userPlugin.createEndpointAPI(resolved);\n        },\n      };\n    };\n    return resolveEndpoint as ServingFactory;\n  }\n}\n\n/**\n * @internal\n */\nexport const serving = toPlugin(ServingPlugin);\n"],"mappings":"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"}

package/dist/plugins/serving/types.d.ts

@@ -0,0 +1,58 @@
+import { BasePluginConfig } from "../../shared/src/plugin.js";
+import "../../shared/src/index.js";
+import * as express$1 from "express";
+
+//#region src/plugins/serving/types.d.ts
+interface EndpointConfig {
+  /** Environment variable holding the endpoint name. */
+  env: string;
+  /** Target a specific served model (bypasses traffic routing). */
+  servedModel?: string;
+}
+interface IServingConfig extends BasePluginConfig {
+  /** Map of alias → endpoint config. Defaults to { default: { env: "DATABRICKS_SERVING_ENDPOINT_NAME" } } if omitted. */
+  endpoints?: Record<string, EndpointConfig>;
+  /** Request timeout in ms. Default: 120000 (2 min) */
+  timeout?: number;
+  /** How to handle unknown request parameters. 'strip' silently removes them (default). 'reject' returns 400. */
+  filterMode?: "strip" | "reject";
+}
+/**
+ * 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.
+ */
+interface ServingEndpointRegistry {}
+/** Shape of a single registry entry. */
+interface ServingEndpointEntry {
+  request: Record<string, unknown>;
+  response: unknown;
+  chunk: unknown;
+}
+/** Typed invoke method for a serving endpoint. */
+interface ServingEndpointMethods<TRequest extends Record<string, unknown> = Record<string, unknown>, TResponse = unknown> {
+  invoke: (body: TRequest) => Promise<TResponse>;
+}
+/** Endpoint handle with asUser support, returned by the exports factory. */
+type ServingEndpointHandle<TRequest extends Record<string, unknown> = Record<string, unknown>, TResponse = unknown> = ServingEndpointMethods<TRequest, TResponse> & {
+  asUser: (req: express$1.Request) => ServingEndpointMethods<TRequest, TResponse>;
+};
+/**
+ * Factory function returned by `AppKit.serving`.
+ *
+ * This is a conditional type that adapts based on whether `ServingEndpointRegistry`
+ * has been populated via module augmentation (generated by `appKitServingTypesPlugin()`):
+ *
+ * - **Registry empty (default):** `(alias?: string) => ServingEndpointHandle` —
+ *   accepts any alias string with untyped request/response.
+ * - **Registry populated:** `<K>(alias: K) => ServingEndpointHandle<...>` —
+ *   restricts `alias` to known endpoint keys and infers typed request/response
+ *   from the registry entry.
+ *
+ * Run `appKitServingTypesPlugin()` in your Vite config to generate the registry
+ * augmentation and enable full type safety.
+ */
+type ServingFactory = keyof ServingEndpointRegistry extends never ? (alias?: string) => ServingEndpointHandle : <K extends keyof ServingEndpointRegistry>(alias: K) => ServingEndpointHandle<ServingEndpointRegistry[K]["request"], ServingEndpointRegistry[K]["response"]>;
+//#endregion
+export { EndpointConfig, IServingConfig, ServingEndpointEntry, ServingEndpointHandle, ServingEndpointMethods, ServingEndpointRegistry, ServingFactory };
+//# sourceMappingURL=types.d.ts.map

package/dist/plugins/serving/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","names":[],"sources":["../../../src/plugins/serving/types.ts"],"mappings":";;;;;UAEiB,cAAA;;EAEf,GAAA;;EAEA,WAAA;AAAA;AAAA,UAGe,cAAA,SAAuB,gBAAA;EALtC;EAOA,SAAA,GAAY,MAAA,SAAe,cAAA;EAFZ;EAIf,OAAA;;EAEA,UAAA;AAAA;;;;;;UASe,uBAAA;;UAGA,oBAAA;EACf,OAAA,EAAS,MAAA;EACT,QAAA;EACA,KAAA;AAAA;;UAIe,sBAAA,kBACE,MAAA,oBAA0B,MAAA;EAG3C,MAAA,GAAS,IAAA,EAAM,QAAA,KAAa,OAAA,CAAQ,SAAA;AAAA;;KAI1B,qBAAA,kBACO,MAAA,oBAA0B,MAAA,0CAEzC,sBAAA,CAAuB,QAAA,EAAU,SAAA;EACnC,MAAA,GACE,GAAA,EAFsB,SAAA,CAEC,OAAA,KACpB,sBAAA,CAAuB,QAAA,EAAU,SAAA;AAAA;;;;;;AAdxC;;;;;;;;;;KAgCY,cAAA,SAAuB,uBAAA,kBAC9B,KAAA,cAAmB,qBAAA,oBACH,uBAAA,EACf,KAAA,EAAO,CAAA,KACJ,qBAAA,CACH,uBAAA,CAAwB,CAAA,cACxB,uBAAA,CAAwB,CAAA"}

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

@@ -13,7 +13,7 @@ interface StreamConfig {
   heartbeatInterval?: number;
   maxActiveStreams?: number;
 }
-/** Retry configuration for the RetryInterceptor. Uses exponential backoff between attempts. */
+/** Retry configuration for the RetryInterceptor. Uses exponential backoff with full jitter between attempts. */
 interface RetryConfig {
   enabled?: boolean;
   attempts?: number;

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

@@ -12,6 +12,7 @@ interface BasePlugin {
   getEndpoints(): PluginEndpointMap;
   getSkipBodyParsingPaths?(): ReadonlySet<string>;
   exports?(): unknown;
+  clientConfig?(): Record<string, unknown>;
 }
 /** 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;AAAA;;UAIe,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"}
+{"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"}

package/dist/stream/stream-manager.js

@@ -197,6 +197,7 @@ var StreamManager = class {
 			if (message.includes("timeout") || message.includes("timed out")) return SSEErrorCode.TIMEOUT;
 			if (message.includes("unavailable") || message.includes("econnrefused")) return SSEErrorCode.TEMPORARY_UNAVAILABLE;
 			if (error.name === "AbortError") return SSEErrorCode.STREAM_ABORTED;
+			if ("statusCode" in error && typeof error.statusCode === "number") return SSEErrorCode.UPSTREAM_ERROR;
 		}
 		return SSEErrorCode.INTERNAL_ERROR;
 	}

package/dist/stream/stream-manager.js.map

@@ -1 +1 @@
-{"version":3,"file":"stream-manager.js","names":[],"sources":["../../src/stream/stream-manager.ts"],"sourcesContent":["import { randomUUID } from \"node:crypto\";\nimport { context } from \"@opentelemetry/api\";\nimport type { IAppResponse, StreamConfig } from \"shared\";\nimport { EventRingBuffer } from \"./buffers\";\nimport { streamDefaults } from \"./defaults\";\nimport { SSEWriter } from \"./sse-writer\";\nimport { StreamRegistry } from \"./stream-registry\";\nimport { SSEErrorCode, type StreamEntry, type StreamOperation } from \"./types\";\nimport { StreamValidator } from \"./validator\";\n\n// main entry point for Server-Sent events streaming\nexport class StreamManager {\n  private activeOperations: Set<StreamOperation>;\n  private streamRegistry: StreamRegistry;\n  private sseWriter: SSEWriter;\n  private maxEventSize: number;\n  private bufferTTL: number;\n\n  constructor(options?: StreamConfig) {\n    this.streamRegistry = new StreamRegistry(\n      options?.maxActiveStreams ?? streamDefaults.maxActiveStreams,\n    );\n    this.sseWriter = new SSEWriter();\n    this.maxEventSize = options?.maxEventSize ?? streamDefaults.maxEventSize;\n    this.bufferTTL = options?.bufferTTL ?? streamDefaults.bufferTTL;\n    this.activeOperations = new Set();\n  }\n\n  // main streaming method - handles new connection and reconnection\n  async stream(\n    res: IAppResponse,\n    handler: (signal: AbortSignal) => AsyncGenerator<any, void, unknown>,\n    options?: StreamConfig,\n  ): Promise<void> {\n    const { streamId } = options || {};\n\n    // check if response is already closed\n    if (res.writableEnded || res.destroyed) {\n      return;\n    }\n\n    // setup SSE headers\n    this.sseWriter.setupHeaders(res);\n\n    // handle reconnection\n    if (streamId && StreamValidator.validateStreamId(streamId)) {\n      const existingStream = this.streamRegistry.get(streamId);\n      // if stream exists, attach to it\n      if (existingStream) {\n        return this._attachToExistingStream(res, existingStream, options);\n      }\n    }\n\n    // if stream does not exist, create a new one\n    return this._createNewStream(res, handler, options);\n  }\n\n  // abort all active operations\n  abortAll(): void {\n    this.activeOperations.forEach((operation) => {\n      if (operation.heartbeat) clearInterval(operation.heartbeat);\n      operation.controller.abort(\"Server shutdown\");\n    });\n    this.activeOperations.clear();\n    this.streamRegistry.clear();\n  }\n\n  // get the number of active operations\n  getActiveCount(): number {\n    return this.activeOperations.size;\n  }\n\n  // attach to existing stream\n  private async _attachToExistingStream(\n    res: IAppResponse,\n    streamEntry: StreamEntry,\n    options?: StreamConfig,\n  ): Promise<void> {\n    // handle reconnection - replay missed events\n    const lastEventId = res.req?.headers[\"last-event-id\"];\n\n    if (StreamValidator.validateEventId(lastEventId)) {\n      // cast to string after validation\n      const validEventId = lastEventId as string;\n      if (streamEntry.eventBuffer.has(validEventId)) {\n        const missedEvents =\n          streamEntry.eventBuffer.getEventsSince(validEventId);\n        // broadcast missed events to client\n        for (const event of missedEvents) {\n          if (options?.userSignal?.aborted) break;\n          this.sseWriter.writeBufferedEvent(res, event);\n        }\n      } else {\n        // buffer overflow - send warning\n        this.sseWriter.writeBufferOverflowWarning(res, validEventId);\n      }\n    }\n\n    // add client to stream entry\n    streamEntry.clients.add(res);\n    streamEntry.lastAccess = Date.now();\n\n    // start heartbeat\n    const combinedSignal = this._combineSignals(\n      streamEntry.abortController.signal,\n      options?.userSignal,\n    );\n    const heartbeat = this.sseWriter.startHeartbeat(res, combinedSignal);\n\n    // track operation\n    const streamOperation: StreamOperation = {\n      controller: streamEntry.abortController,\n      type: \"stream\",\n      heartbeat,\n    };\n    this.activeOperations.add(streamOperation);\n\n    // handle client disconnect\n    res.on(\"close\", () => {\n      clearInterval(heartbeat);\n      streamEntry.clients.delete(res);\n      this.activeOperations.delete(streamOperation);\n\n      // cleanup if stream is completed and no clients are connected\n      if (streamEntry.isCompleted && streamEntry.clients.size === 0) {\n        setTimeout(() => {\n          if (streamEntry.clients.size === 0) {\n            this.streamRegistry.remove(streamEntry.streamId);\n          }\n        }, this.bufferTTL);\n      }\n    });\n\n    // if stream is completed, close connection\n    if (streamEntry.isCompleted) {\n      res.end();\n      // cleanup operation\n      this.activeOperations.delete(streamOperation);\n      clearInterval(heartbeat);\n    }\n  }\n  private async _createNewStream(\n    res: IAppResponse,\n    handler: (signal: AbortSignal) => AsyncGenerator<any, void, unknown>,\n    options?: StreamConfig,\n  ): Promise<void> {\n    const streamId = options?.streamId ?? randomUUID();\n\n    // abort stream if response is closed\n    if (res.writableEnded || res.destroyed) {\n      return;\n    }\n\n    const abortController = new AbortController();\n\n    // create event buffer\n    const eventBuffer = new EventRingBuffer(\n      options?.bufferSize ?? streamDefaults.bufferSize,\n    );\n\n    // setup signals and heartbeat\n    const combinedSignal = this._combineSignals(\n      abortController.signal,\n      options?.userSignal,\n    );\n    const heartbeat = this.sseWriter.startHeartbeat(res, combinedSignal);\n\n    // capture the current trace context at stream creation time\n    const traceContext = context.active();\n\n    // abort stream if response is closed\n    if (res.writableEnded || res.destroyed) {\n      clearInterval(heartbeat);\n      return;\n    }\n\n    // create stream entry\n    const streamEntry: StreamEntry = {\n      streamId,\n      generator: handler(combinedSignal),\n      eventBuffer,\n      clients: new Set([res]),\n      isCompleted: false,\n      lastAccess: Date.now(),\n      abortController,\n      traceContext,\n    };\n    this.streamRegistry.add(streamEntry);\n\n    // track operation\n    const streamOperation: StreamOperation = {\n      controller: abortController,\n      type: \"stream\",\n      heartbeat,\n    };\n    this.activeOperations.add(streamOperation);\n\n    res.on(\"close\", () => {\n      clearInterval(heartbeat);\n      this.activeOperations.delete(streamOperation);\n      streamEntry.clients.delete(res);\n    });\n\n    await this._processGeneratorInBackground(streamEntry);\n\n    // cleanup\n    clearInterval(heartbeat);\n    this.activeOperations.delete(streamOperation);\n  }\n\n  private async _processGeneratorInBackground(\n    streamEntry: StreamEntry,\n  ): Promise<void> {\n    // run the entire generator processing within the captured trace context\n    return context.with(streamEntry.traceContext, async () => {\n      try {\n        // retrieve all events from generator\n        for await (const event of streamEntry.generator) {\n          if (streamEntry.abortController.signal.aborted) break;\n          const eventId = randomUUID();\n          const eventData = JSON.stringify(event);\n\n          // validate event size\n          if (eventData.length > this.maxEventSize) {\n            const errorMsg = `Event exceeds max size of ${this.maxEventSize} bytes`;\n            const errorCode = SSEErrorCode.INVALID_REQUEST;\n            // broadcast error to all connected clients\n            this._broadcastErrorToClients(\n              streamEntry,\n              eventId,\n              errorMsg,\n              errorCode,\n            );\n            continue;\n          }\n\n          // buffer event for reconnection\n          streamEntry.eventBuffer.add({\n            id: eventId,\n            type: event.type,\n            data: eventData,\n            timestamp: Date.now(),\n          });\n\n          // broadcast to all connected clients\n          this._broadcastEventsToClients(streamEntry, eventId, event);\n          streamEntry.lastAccess = Date.now();\n        }\n\n        streamEntry.isCompleted = true;\n\n        // close all clients\n        this._closeAllClients(streamEntry);\n\n        // cleanup if no clients are connected\n        this._cleanupStream(streamEntry);\n      } catch (error) {\n        const errorMsg =\n          error instanceof Error ? error.message : \"Internal server error\";\n        const errorEventId = randomUUID();\n        const errorCode = this._categorizeError(error);\n\n        // buffer error event\n        streamEntry.eventBuffer.add({\n          id: errorEventId,\n          type: \"error\",\n          data: JSON.stringify({ error: errorMsg, code: errorCode }),\n          timestamp: Date.now(),\n        });\n\n        // send error event to all connected clients\n        this._broadcastErrorToClients(\n          streamEntry,\n          errorEventId,\n          errorMsg,\n          errorCode,\n          true,\n        );\n        streamEntry.isCompleted = true;\n      }\n    });\n  }\n\n  private _combineSignals(\n    internalSignal?: AbortSignal,\n    userSignal?: AbortSignal,\n  ): AbortSignal {\n    if (!userSignal) return internalSignal || new AbortController().signal;\n\n    const signals = [internalSignal, userSignal].filter(\n      Boolean,\n    ) as AbortSignal[];\n    const controller = new AbortController();\n\n    signals.forEach((signal) => {\n      if (signal?.aborted) {\n        controller.abort(signal.reason);\n        return;\n      }\n\n      signal?.addEventListener(\n        \"abort\",\n        () => {\n          controller.abort(signal.reason);\n        },\n        { once: true },\n      );\n    });\n    return controller.signal;\n  }\n\n  // broadcast events to all connected clients\n  private _broadcastEventsToClients(\n    streamEntry: StreamEntry,\n    eventId: string,\n    event: any,\n  ): void {\n    for (const client of streamEntry.clients) {\n      if (!client.writableEnded) {\n        this.sseWriter.writeEvent(client, eventId, event);\n      }\n    }\n  }\n\n  // broadcast error to all connected clients\n  private _broadcastErrorToClients(\n    streamEntry: StreamEntry,\n    eventId: string,\n    errorMessage: string,\n    errorCode: SSEErrorCode,\n    closeClients: boolean = false,\n  ): void {\n    for (const client of streamEntry.clients) {\n      if (!client.writableEnded) {\n        this.sseWriter.writeError(client, eventId, errorMessage, errorCode);\n        if (closeClients) {\n          client.end();\n        }\n      }\n    }\n  }\n\n  // close all connected clients\n  private _closeAllClients(streamEntry: StreamEntry): void {\n    for (const client of streamEntry.clients) {\n      if (!client.writableEnded) {\n        client.end();\n      }\n    }\n  }\n\n  // cleanup stream if no clients are connected\n  private _cleanupStream(streamEntry: StreamEntry): void {\n    if (streamEntry.clients.size === 0) {\n      setTimeout(() => {\n        if (streamEntry.clients.size === 0) {\n          this.streamRegistry.remove(streamEntry.streamId);\n        }\n      }, this.bufferTTL);\n    }\n  }\n\n  private _categorizeError(error: unknown): SSEErrorCode {\n    if (error instanceof Error) {\n      const message = error.message.toLowerCase();\n      if (message.includes(\"timeout\") || message.includes(\"timed out\")) {\n        return SSEErrorCode.TIMEOUT;\n      }\n\n      if (message.includes(\"unavailable\") || message.includes(\"econnrefused\")) {\n        return SSEErrorCode.TEMPORARY_UNAVAILABLE;\n      }\n\n      if (error.name === \"AbortError\") {\n        return SSEErrorCode.STREAM_ABORTED;\n      }\n    }\n\n    return SSEErrorCode.INTERNAL_ERROR;\n  }\n}\n"],"mappings":"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"}
+{"version":3,"file":"stream-manager.js","names":[],"sources":["../../src/stream/stream-manager.ts"],"sourcesContent":["import { randomUUID } from \"node:crypto\";\nimport { context } from \"@opentelemetry/api\";\nimport type { IAppResponse, StreamConfig } from \"shared\";\nimport { EventRingBuffer } from \"./buffers\";\nimport { streamDefaults } from \"./defaults\";\nimport { SSEWriter } from \"./sse-writer\";\nimport { StreamRegistry } from \"./stream-registry\";\nimport { SSEErrorCode, type StreamEntry, type StreamOperation } from \"./types\";\nimport { StreamValidator } from \"./validator\";\n\n// main entry point for Server-Sent events streaming\nexport class StreamManager {\n  private activeOperations: Set<StreamOperation>;\n  private streamRegistry: StreamRegistry;\n  private sseWriter: SSEWriter;\n  private maxEventSize: number;\n  private bufferTTL: number;\n\n  constructor(options?: StreamConfig) {\n    this.streamRegistry = new StreamRegistry(\n      options?.maxActiveStreams ?? streamDefaults.maxActiveStreams,\n    );\n    this.sseWriter = new SSEWriter();\n    this.maxEventSize = options?.maxEventSize ?? streamDefaults.maxEventSize;\n    this.bufferTTL = options?.bufferTTL ?? streamDefaults.bufferTTL;\n    this.activeOperations = new Set();\n  }\n\n  // main streaming method - handles new connection and reconnection\n  async stream(\n    res: IAppResponse,\n    handler: (signal: AbortSignal) => AsyncGenerator<any, void, unknown>,\n    options?: StreamConfig,\n  ): Promise<void> {\n    const { streamId } = options || {};\n\n    // check if response is already closed\n    if (res.writableEnded || res.destroyed) {\n      return;\n    }\n\n    // setup SSE headers\n    this.sseWriter.setupHeaders(res);\n\n    // handle reconnection\n    if (streamId && StreamValidator.validateStreamId(streamId)) {\n      const existingStream = this.streamRegistry.get(streamId);\n      // if stream exists, attach to it\n      if (existingStream) {\n        return this._attachToExistingStream(res, existingStream, options);\n      }\n    }\n\n    // if stream does not exist, create a new one\n    return this._createNewStream(res, handler, options);\n  }\n\n  // abort all active operations\n  abortAll(): void {\n    this.activeOperations.forEach((operation) => {\n      if (operation.heartbeat) clearInterval(operation.heartbeat);\n      operation.controller.abort(\"Server shutdown\");\n    });\n    this.activeOperations.clear();\n    this.streamRegistry.clear();\n  }\n\n  // get the number of active operations\n  getActiveCount(): number {\n    return this.activeOperations.size;\n  }\n\n  // attach to existing stream\n  private async _attachToExistingStream(\n    res: IAppResponse,\n    streamEntry: StreamEntry,\n    options?: StreamConfig,\n  ): Promise<void> {\n    // handle reconnection - replay missed events\n    const lastEventId = res.req?.headers[\"last-event-id\"];\n\n    if (StreamValidator.validateEventId(lastEventId)) {\n      // cast to string after validation\n      const validEventId = lastEventId as string;\n      if (streamEntry.eventBuffer.has(validEventId)) {\n        const missedEvents =\n          streamEntry.eventBuffer.getEventsSince(validEventId);\n        // broadcast missed events to client\n        for (const event of missedEvents) {\n          if (options?.userSignal?.aborted) break;\n          this.sseWriter.writeBufferedEvent(res, event);\n        }\n      } else {\n        // buffer overflow - send warning\n        this.sseWriter.writeBufferOverflowWarning(res, validEventId);\n      }\n    }\n\n    // add client to stream entry\n    streamEntry.clients.add(res);\n    streamEntry.lastAccess = Date.now();\n\n    // start heartbeat\n    const combinedSignal = this._combineSignals(\n      streamEntry.abortController.signal,\n      options?.userSignal,\n    );\n    const heartbeat = this.sseWriter.startHeartbeat(res, combinedSignal);\n\n    // track operation\n    const streamOperation: StreamOperation = {\n      controller: streamEntry.abortController,\n      type: \"stream\",\n      heartbeat,\n    };\n    this.activeOperations.add(streamOperation);\n\n    // handle client disconnect\n    res.on(\"close\", () => {\n      clearInterval(heartbeat);\n      streamEntry.clients.delete(res);\n      this.activeOperations.delete(streamOperation);\n\n      // cleanup if stream is completed and no clients are connected\n      if (streamEntry.isCompleted && streamEntry.clients.size === 0) {\n        setTimeout(() => {\n          if (streamEntry.clients.size === 0) {\n            this.streamRegistry.remove(streamEntry.streamId);\n          }\n        }, this.bufferTTL);\n      }\n    });\n\n    // if stream is completed, close connection\n    if (streamEntry.isCompleted) {\n      res.end();\n      // cleanup operation\n      this.activeOperations.delete(streamOperation);\n      clearInterval(heartbeat);\n    }\n  }\n  private async _createNewStream(\n    res: IAppResponse,\n    handler: (signal: AbortSignal) => AsyncGenerator<any, void, unknown>,\n    options?: StreamConfig,\n  ): Promise<void> {\n    const streamId = options?.streamId ?? randomUUID();\n\n    // abort stream if response is closed\n    if (res.writableEnded || res.destroyed) {\n      return;\n    }\n\n    const abortController = new AbortController();\n\n    // create event buffer\n    const eventBuffer = new EventRingBuffer(\n      options?.bufferSize ?? streamDefaults.bufferSize,\n    );\n\n    // setup signals and heartbeat\n    const combinedSignal = this._combineSignals(\n      abortController.signal,\n      options?.userSignal,\n    );\n    const heartbeat = this.sseWriter.startHeartbeat(res, combinedSignal);\n\n    // capture the current trace context at stream creation time\n    const traceContext = context.active();\n\n    // abort stream if response is closed\n    if (res.writableEnded || res.destroyed) {\n      clearInterval(heartbeat);\n      return;\n    }\n\n    // create stream entry\n    const streamEntry: StreamEntry = {\n      streamId,\n      generator: handler(combinedSignal),\n      eventBuffer,\n      clients: new Set([res]),\n      isCompleted: false,\n      lastAccess: Date.now(),\n      abortController,\n      traceContext,\n    };\n    this.streamRegistry.add(streamEntry);\n\n    // track operation\n    const streamOperation: StreamOperation = {\n      controller: abortController,\n      type: \"stream\",\n      heartbeat,\n    };\n    this.activeOperations.add(streamOperation);\n\n    res.on(\"close\", () => {\n      clearInterval(heartbeat);\n      this.activeOperations.delete(streamOperation);\n      streamEntry.clients.delete(res);\n    });\n\n    await this._processGeneratorInBackground(streamEntry);\n\n    // cleanup\n    clearInterval(heartbeat);\n    this.activeOperations.delete(streamOperation);\n  }\n\n  private async _processGeneratorInBackground(\n    streamEntry: StreamEntry,\n  ): Promise<void> {\n    // run the entire generator processing within the captured trace context\n    return context.with(streamEntry.traceContext, async () => {\n      try {\n        // retrieve all events from generator\n        for await (const event of streamEntry.generator) {\n          if (streamEntry.abortController.signal.aborted) break;\n          const eventId = randomUUID();\n          const eventData = JSON.stringify(event);\n\n          // validate event size\n          if (eventData.length > this.maxEventSize) {\n            const errorMsg = `Event exceeds max size of ${this.maxEventSize} bytes`;\n            const errorCode = SSEErrorCode.INVALID_REQUEST;\n            // broadcast error to all connected clients\n            this._broadcastErrorToClients(\n              streamEntry,\n              eventId,\n              errorMsg,\n              errorCode,\n            );\n            continue;\n          }\n\n          // buffer event for reconnection\n          streamEntry.eventBuffer.add({\n            id: eventId,\n            type: event.type,\n            data: eventData,\n            timestamp: Date.now(),\n          });\n\n          // broadcast to all connected clients\n          this._broadcastEventsToClients(streamEntry, eventId, event);\n          streamEntry.lastAccess = Date.now();\n        }\n\n        streamEntry.isCompleted = true;\n\n        // close all clients\n        this._closeAllClients(streamEntry);\n\n        // cleanup if no clients are connected\n        this._cleanupStream(streamEntry);\n      } catch (error) {\n        const errorMsg =\n          error instanceof Error ? error.message : \"Internal server error\";\n        const errorEventId = randomUUID();\n        const errorCode = this._categorizeError(error);\n\n        // buffer error event\n        streamEntry.eventBuffer.add({\n          id: errorEventId,\n          type: \"error\",\n          data: JSON.stringify({ error: errorMsg, code: errorCode }),\n          timestamp: Date.now(),\n        });\n\n        // send error event to all connected clients\n        this._broadcastErrorToClients(\n          streamEntry,\n          errorEventId,\n          errorMsg,\n          errorCode,\n          true,\n        );\n        streamEntry.isCompleted = true;\n      }\n    });\n  }\n\n  private _combineSignals(\n    internalSignal?: AbortSignal,\n    userSignal?: AbortSignal,\n  ): AbortSignal {\n    if (!userSignal) return internalSignal || new AbortController().signal;\n\n    const signals = [internalSignal, userSignal].filter(\n      Boolean,\n    ) as AbortSignal[];\n    const controller = new AbortController();\n\n    signals.forEach((signal) => {\n      if (signal?.aborted) {\n        controller.abort(signal.reason);\n        return;\n      }\n\n      signal?.addEventListener(\n        \"abort\",\n        () => {\n          controller.abort(signal.reason);\n        },\n        { once: true },\n      );\n    });\n    return controller.signal;\n  }\n\n  // broadcast events to all connected clients\n  private _broadcastEventsToClients(\n    streamEntry: StreamEntry,\n    eventId: string,\n    event: any,\n  ): void {\n    for (const client of streamEntry.clients) {\n      if (!client.writableEnded) {\n        this.sseWriter.writeEvent(client, eventId, event);\n      }\n    }\n  }\n\n  // broadcast error to all connected clients\n  private _broadcastErrorToClients(\n    streamEntry: StreamEntry,\n    eventId: string,\n    errorMessage: string,\n    errorCode: SSEErrorCode,\n    closeClients: boolean = false,\n  ): void {\n    for (const client of streamEntry.clients) {\n      if (!client.writableEnded) {\n        this.sseWriter.writeError(client, eventId, errorMessage, errorCode);\n        if (closeClients) {\n          client.end();\n        }\n      }\n    }\n  }\n\n  // close all connected clients\n  private _closeAllClients(streamEntry: StreamEntry): void {\n    for (const client of streamEntry.clients) {\n      if (!client.writableEnded) {\n        client.end();\n      }\n    }\n  }\n\n  // cleanup stream if no clients are connected\n  private _cleanupStream(streamEntry: StreamEntry): void {\n    if (streamEntry.clients.size === 0) {\n      setTimeout(() => {\n        if (streamEntry.clients.size === 0) {\n          this.streamRegistry.remove(streamEntry.streamId);\n        }\n      }, this.bufferTTL);\n    }\n  }\n\n  private _categorizeError(error: unknown): SSEErrorCode {\n    if (error instanceof Error) {\n      const message = error.message.toLowerCase();\n      if (message.includes(\"timeout\") || message.includes(\"timed out\")) {\n        return SSEErrorCode.TIMEOUT;\n      }\n\n      if (message.includes(\"unavailable\") || message.includes(\"econnrefused\")) {\n        return SSEErrorCode.TEMPORARY_UNAVAILABLE;\n      }\n\n      if (error.name === \"AbortError\") {\n        return SSEErrorCode.STREAM_ABORTED;\n      }\n\n      // Detect upstream API errors (e.g., from Databricks SDK ApiError)\n      if (\n        \"statusCode\" in error &&\n        typeof (error as any).statusCode === \"number\"\n      ) {\n        return SSEErrorCode.UPSTREAM_ERROR;\n      }\n    }\n\n    return SSEErrorCode.INTERNAL_ERROR;\n  }\n}\n"],"mappings":"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"}

package/dist/stream/types.js

@@ -6,7 +6,8 @@ const SSEErrorCode = {
 	INTERNAL_ERROR: "INTERNAL_ERROR",
 	INVALID_REQUEST: "INVALID_REQUEST",
 	STREAM_ABORTED: "STREAM_ABORTED",
-	STREAM_EVICTED: "STREAM_EVICTED"
+	STREAM_EVICTED: "STREAM_EVICTED",
+	UPSTREAM_ERROR: "UPSTREAM_ERROR"
 };
 
 //#endregion

package/dist/stream/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","names":[],"sources":["../../src/stream/types.ts"],"sourcesContent":["import type { Context } from \"@opentelemetry/api\";\nimport type { IAppResponse } from \"shared\";\nimport type { EventRingBuffer } from \"./buffers\";\n\nexport const SSEWarningCode = {\n  BUFFER_OVERFLOW_RESTART: \"BUFFER_OVERFLOW_RESTART\",\n} as const satisfies Record<string, string>;\n\nexport type SSEWarningCode =\n  (typeof SSEWarningCode)[keyof typeof SSEWarningCode];\n\nexport const SSEErrorCode = {\n  TEMPORARY_UNAVAILABLE: \"TEMPORARY_UNAVAILABLE\",\n  TIMEOUT: \"TIMEOUT\",\n  INTERNAL_ERROR: \"INTERNAL_ERROR\",\n  INVALID_REQUEST: \"INVALID_REQUEST\",\n  STREAM_ABORTED: \"STREAM_ABORTED\",\n  STREAM_EVICTED: \"STREAM_EVICTED\",\n} as const satisfies Record<string, string>;\n\nexport type SSEErrorCode = (typeof SSEErrorCode)[keyof typeof SSEErrorCode];\n\nexport interface SSEError {\n  error: string;\n  code: SSEErrorCode;\n}\n\nexport interface BufferedEvent {\n  id: string;\n  type: string;\n  data: string;\n  timestamp: number;\n}\n\nexport interface StreamEntry {\n  streamId: string;\n  generator: AsyncGenerator<any, void, unknown>;\n  eventBuffer: EventRingBuffer;\n  clients: Set<IAppResponse>;\n  isCompleted: boolean;\n  lastAccess: number;\n  abortController: AbortController;\n  traceContext: Context;\n}\n\nexport interface StreamOperation {\n  controller: AbortController;\n  type: \"query\" | \"stream\";\n  heartbeat?: NodeJS.Timeout;\n}\n"],"mappings":";AAIA,MAAa,iBAAiB,EAC5B,yBAAyB,2BAC1B;AAKD,MAAa,eAAe;CAC1B,uBAAuB;CACvB,SAAS;CACT,gBAAgB;CAChB,iBAAiB;CACjB,gBAAgB;CAChB,gBAAgB;CACjB"}
+{"version":3,"file":"types.js","names":[],"sources":["../../src/stream/types.ts"],"sourcesContent":["import type { Context } from \"@opentelemetry/api\";\nimport type { IAppResponse } from \"shared\";\nimport type { EventRingBuffer } from \"./buffers\";\n\nexport const SSEWarningCode = {\n  BUFFER_OVERFLOW_RESTART: \"BUFFER_OVERFLOW_RESTART\",\n} as const satisfies Record<string, string>;\n\nexport type SSEWarningCode =\n  (typeof SSEWarningCode)[keyof typeof SSEWarningCode];\n\nexport const SSEErrorCode = {\n  TEMPORARY_UNAVAILABLE: \"TEMPORARY_UNAVAILABLE\",\n  TIMEOUT: \"TIMEOUT\",\n  INTERNAL_ERROR: \"INTERNAL_ERROR\",\n  INVALID_REQUEST: \"INVALID_REQUEST\",\n  STREAM_ABORTED: \"STREAM_ABORTED\",\n  STREAM_EVICTED: \"STREAM_EVICTED\",\n  UPSTREAM_ERROR: \"UPSTREAM_ERROR\",\n} as const satisfies Record<string, string>;\n\nexport type SSEErrorCode = (typeof SSEErrorCode)[keyof typeof SSEErrorCode];\n\nexport interface SSEError {\n  error: string;\n  code: SSEErrorCode;\n}\n\nexport interface BufferedEvent {\n  id: string;\n  type: string;\n  data: string;\n  timestamp: number;\n}\n\nexport interface StreamEntry {\n  streamId: string;\n  generator: AsyncGenerator<any, void, unknown>;\n  eventBuffer: EventRingBuffer;\n  clients: Set<IAppResponse>;\n  isCompleted: boolean;\n  lastAccess: number;\n  abortController: AbortController;\n  traceContext: Context;\n}\n\nexport interface StreamOperation {\n  controller: AbortController;\n  type: \"query\" | \"stream\";\n  heartbeat?: NodeJS.Timeout;\n}\n"],"mappings":";AAIA,MAAa,iBAAiB,EAC5B,yBAAyB,2BAC1B;AAKD,MAAa,eAAe;CAC1B,uBAAuB;CACvB,SAAS;CACT,gBAAgB;CAChB,iBAAiB;CACjB,gBAAgB;CAChB,gBAAgB;CAChB,gBAAgB;CACjB"}

package/dist/type-generator/cache.js

@@ -5,7 +5,7 @@ import path from "node:path";
 
 //#region src/type-generator/cache.ts
 const logger = createLogger("type-generator:cache");
-const CACHE_VERSION = "2";
+const CACHE_VERSION = "3";
 const CACHE_FILE = ".appkit-types-cache.json";
 const CACHE_DIR = path.join(process.cwd(), "node_modules", ".databricks", "appkit");
 /**

package/dist/type-generator/cache.js.map

@@ -1 +1 @@
-{"version":3,"file":"cache.js","names":[],"sources":["../../src/type-generator/cache.ts"],"sourcesContent":["import crypto from \"node:crypto\";\nimport fs from \"node:fs/promises\";\nimport path from \"node:path\";\nimport { createLogger } from \"../logging/logger\";\n\nconst logger = createLogger(\"type-generator:cache\");\n\n/**\n * Cache types\n * @property hash - the hash of the SQL query\n * @property type - the type of the query\n */\ninterface CacheEntry {\n  hash: string;\n  type: string;\n  retry: boolean;\n}\n\n/**\n * Cache interface\n * @property version - the version of the cache\n * @property queries - the queries in the cache\n */\ninterface Cache {\n  version: string;\n  queries: Record<string, CacheEntry>;\n}\n\nexport const CACHE_VERSION = \"2\";\nconst CACHE_FILE = \".appkit-types-cache.json\";\nconst CACHE_DIR = path.join(\n  process.cwd(),\n  \"node_modules\",\n  \".databricks\",\n  \"appkit\",\n);\n\n/**\n * Hash the SQL query\n * Uses MD5 to hash the SQL query\n * @param sql - the SQL query to hash\n * @returns - the hash of the SQL query\n */\nexport function hashSQL(sql: string): string {\n  return crypto.createHash(\"md5\").update(sql).digest(\"hex\");\n}\n\n/**\n * Load the cache from the file system\n * If the cache is not found, run the query explain\n * @returns - the cache\n */\nexport async function loadCache(): Promise<Cache> {\n  const cachePath = path.join(CACHE_DIR, CACHE_FILE);\n  try {\n    await fs.mkdir(CACHE_DIR, { recursive: true });\n\n    const raw = await fs.readFile(cachePath, \"utf8\");\n    const cache = JSON.parse(raw) as Cache;\n    if (cache.version === CACHE_VERSION) {\n      return cache;\n    }\n  } catch (err) {\n    if ((err as NodeJS.ErrnoException).code !== \"ENOENT\") {\n      logger.warn(\"Cache file is corrupted, flushing cache completely.\");\n    }\n  }\n  return { version: CACHE_VERSION, queries: {} };\n}\n\n/**\n * Save the cache to the file system\n * @param cache - cache object to save\n */\nexport async function saveCache(cache: Cache): Promise<void> {\n  const cachePath = path.join(CACHE_DIR, CACHE_FILE);\n  await fs.writeFile(cachePath, JSON.stringify(cache, null, 2), \"utf8\");\n}\n"],"mappings":";;;;;;AAKA,MAAM,SAAS,aAAa,uBAAuB;AAuBnD,MAAa,gBAAgB;AAC7B,MAAM,aAAa;AACnB,MAAM,YAAY,KAAK,KACrB,QAAQ,KAAK,EACb,gBACA,eACA,SACD;;;;;;;AAQD,SAAgB,QAAQ,KAAqB;AAC3C,QAAO,OAAO,WAAW,MAAM,CAAC,OAAO,IAAI,CAAC,OAAO,MAAM;;;;;;;AAQ3D,eAAsB,YAA4B;CAChD,MAAM,YAAY,KAAK,KAAK,WAAW,WAAW;AAClD,KAAI;AACF,QAAM,GAAG,MAAM,WAAW,EAAE,WAAW,MAAM,CAAC;EAE9C,MAAM,MAAM,MAAM,GAAG,SAAS,WAAW,OAAO;EAChD,MAAM,QAAQ,KAAK,MAAM,IAAI;AAC7B,MAAI,MAAM,YAAY,cACpB,QAAO;UAEF,KAAK;AACZ,MAAK,IAA8B,SAAS,SAC1C,QAAO,KAAK,sDAAsD;;AAGtE,QAAO;EAAE,SAAS;EAAe,SAAS,EAAE;EAAE;;;;;;AAOhD,eAAsB,UAAU,OAA6B;CAC3D,MAAM,YAAY,KAAK,KAAK,WAAW,WAAW;AAClD,OAAM,GAAG,UAAU,WAAW,KAAK,UAAU,OAAO,MAAM,EAAE,EAAE,OAAO"}
+{"version":3,"file":"cache.js","names":[],"sources":["../../src/type-generator/cache.ts"],"sourcesContent":["import crypto from \"node:crypto\";\nimport fs from \"node:fs/promises\";\nimport path from \"node:path\";\nimport { createLogger } from \"../logging/logger\";\n\nconst logger = createLogger(\"type-generator:cache\");\n\n/**\n * Cache types\n * @property hash - the hash of the SQL query\n * @property type - the type of the query\n */\ninterface CacheEntry {\n  hash: string;\n  type: string;\n  retry: boolean;\n}\n\n/**\n * Cache interface\n * @property version - the version of the cache\n * @property queries - the queries in the cache\n */\ninterface Cache {\n  version: string;\n  queries: Record<string, CacheEntry>;\n}\n\nexport const CACHE_VERSION = \"3\";\nconst CACHE_FILE = \".appkit-types-cache.json\";\nconst CACHE_DIR = path.join(\n  process.cwd(),\n  \"node_modules\",\n  \".databricks\",\n  \"appkit\",\n);\n\n/**\n * Hash the SQL query\n * Uses MD5 to hash the SQL query\n * @param sql - the SQL query to hash\n * @returns - the hash of the SQL query\n */\nexport function hashSQL(sql: string): string {\n  return crypto.createHash(\"md5\").update(sql).digest(\"hex\");\n}\n\n/**\n * Load the cache from the file system\n * If the cache is not found, run the query explain\n * @returns - the cache\n */\nexport async function loadCache(): Promise<Cache> {\n  const cachePath = path.join(CACHE_DIR, CACHE_FILE);\n  try {\n    await fs.mkdir(CACHE_DIR, { recursive: true });\n\n    const raw = await fs.readFile(cachePath, \"utf8\");\n    const cache = JSON.parse(raw) as Cache;\n    if (cache.version === CACHE_VERSION) {\n      return cache;\n    }\n  } catch (err) {\n    if ((err as NodeJS.ErrnoException).code !== \"ENOENT\") {\n      logger.warn(\"Cache file is corrupted, flushing cache completely.\");\n    }\n  }\n  return { version: CACHE_VERSION, queries: {} };\n}\n\n/**\n * Save the cache to the file system\n * @param cache - cache object to save\n */\nexport async function saveCache(cache: Cache): Promise<void> {\n  const cachePath = path.join(CACHE_DIR, CACHE_FILE);\n  await fs.writeFile(cachePath, JSON.stringify(cache, null, 2), \"utf8\");\n}\n"],"mappings":";;;;;;AAKA,MAAM,SAAS,aAAa,uBAAuB;AAuBnD,MAAa,gBAAgB;AAC7B,MAAM,aAAa;AACnB,MAAM,YAAY,KAAK,KACrB,QAAQ,KAAK,EACb,gBACA,eACA,SACD;;;;;;;AAQD,SAAgB,QAAQ,KAAqB;AAC3C,QAAO,OAAO,WAAW,MAAM,CAAC,OAAO,IAAI,CAAC,OAAO,MAAM;;;;;;;AAQ3D,eAAsB,YAA4B;CAChD,MAAM,YAAY,KAAK,KAAK,WAAW,WAAW;AAClD,KAAI;AACF,QAAM,GAAG,MAAM,WAAW,EAAE,WAAW,MAAM,CAAC;EAE9C,MAAM,MAAM,MAAM,GAAG,SAAS,WAAW,OAAO;EAChD,MAAM,QAAQ,KAAK,MAAM,IAAI;AAC7B,MAAI,MAAM,YAAY,cACpB,QAAO;UAEF,KAAK;AACZ,MAAK,IAA8B,SAAS,SAC1C,QAAO,KAAK,sDAAsD;;AAGtE,QAAO;EAAE,SAAS;EAAe,SAAS,EAAE;EAAE;;;;;;AAOhD,eAAsB,UAAU,OAA6B;CAC3D,MAAM,YAAY,KAAK,KAAK,WAAW,WAAW;AAClD,OAAM,GAAG,UAAU,WAAW,KAAK,UAAU,OAAO,MAAM,EAAE,EAAE,OAAO"}

package/dist/type-generator/index.js

@@ -1,5 +1,6 @@
 import { createLogger } from "../logging/logger.js";
 import { generateQueriesFromDescribe } from "./query-registry.js";
+import { generateServingTypes as generateServingTypes$1 } from "./serving/generator.js";
 import fs from "node:fs/promises";
 import dotenv from "dotenv";
 
@@ -38,11 +39,22 @@ async function generateFromEntryPoint(options) {
 	logger.debug("Starting type generation...");
 	let queryRegistry = [];
 	if (queryFolder) queryRegistry = await generateQueriesFromDescribe(queryFolder, warehouseId, { noCache });
+	const failedQueries = queryRegistry.filter((q) => q.type.includes("result: unknown"));
+	if (failedQueries.length > 0) {
+		const names = failedQueries.map((q) => q.name).join(", ");
+		throw new Error([
+			`Type generation failed: ${failedQueries.length} ${failedQueries.length === 1 ? "query" : "queries"} could not be described: ${names}.`,
+			`DESCRIBE QUERY failed for these queries — see the error codes above for details.`,
+			`Common causes: SQL syntax errors, missing tables/views, or warehouse format incompatibilities.`,
+			`To debug: run the failing query directly in a SQL editor against warehouse ${warehouseId}.`
+		].join("\n"));
+	}
 	const typeDeclarations = generateTypeDeclarations(queryRegistry);
 	await fs.writeFile(outFile, typeDeclarations, "utf-8");
 	logger.debug("Type generation complete!");
 }
+const generateServingTypes = generateServingTypes$1;
 
 //#endregion
-export { generateFromEntryPoint };
+export { generateFromEntryPoint, generateServingTypes };
 //# sourceMappingURL=index.js.map

package/dist/type-generator/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","names":[],"sources":["../../src/type-generator/index.ts"],"sourcesContent":["import fs from \"node:fs/promises\";\nimport dotenv from \"dotenv\";\nimport { createLogger } from \"../logging/logger\";\nimport { generateQueriesFromDescribe } from \"./query-registry\";\nimport type { QuerySchema } from \"./types\";\n\ndotenv.config();\n\nconst logger = createLogger(\"type-generator\");\n\n/**\n * Generate type declarations for QueryRegistry\n * Create the d.ts file from the plugin routes and query schemas\n * @param querySchemas - the list of query schemas\n * @returns - the type declarations as a string\n */\nfunction generateTypeDeclarations(querySchemas: QuerySchema[] = []): string {\n  const queryEntries = querySchemas\n    .map(({ name, type }) => {\n      const indentedType = type\n        .split(\"\\n\")\n        .map((line, i) => (i === 0 ? line : `    ${line}`))\n        .join(\"\\n\");\n      return `    ${name}: ${indentedType}`;\n    })\n    .join(\";\\n\");\n\n  const querySection = queryEntries ? `\\n${queryEntries};\\n  ` : \"\";\n\n  return `// Auto-generated by AppKit - DO NOT EDIT\n// Generated by 'npx @databricks/appkit generate-types' or Vite plugin during build\nimport \"@databricks/appkit-ui/react\";\nimport type { SQLTypeMarker, SQLStringMarker, SQLNumberMarker, SQLBooleanMarker, SQLBinaryMarker, SQLDateMarker, SQLTimestampMarker } from \"@databricks/appkit-ui/js\";\n\ndeclare module \"@databricks/appkit-ui/react\" {\n  interface QueryRegistry {${querySection}}\n}\n`;\n}\n\n/**\n * Entry point for generating type declarations from all imported files\n * @param options - the options for the generation\n * @param options.entryPoint - the entry point file\n * @param options.outFile - the output file\n * @param options.querySchemaFile - optional path to query schema file (e.g. config/queries/schema.ts)\n */\nexport async function generateFromEntryPoint(options: {\n  outFile: string;\n  queryFolder?: string;\n  warehouseId: string;\n  noCache?: boolean;\n}) {\n  const { outFile, queryFolder, warehouseId, noCache } = options;\n\n  logger.debug(\"Starting type generation...\");\n\n  let queryRegistry: QuerySchema[] = [];\n  if (queryFolder)\n    queryRegistry = await generateQueriesFromDescribe(\n      queryFolder,\n      warehouseId,\n      {\n        noCache,\n      },\n    );\n\n  const typeDeclarations = generateTypeDeclarations(queryRegistry);\n\n  await fs.writeFile(outFile, typeDeclarations, \"utf-8\");\n\n  logger.debug(\"Type generation complete!\");\n}\n"],"mappings":";;;;;;AAMA,OAAO,QAAQ;AAEf,MAAM,SAAS,aAAa,iBAAiB;;;;;;;AAQ7C,SAAS,yBAAyB,eAA8B,EAAE,EAAU;CAC1E,MAAM,eAAe,aAClB,KAAK,EAAE,MAAM,WAAW;AAKvB,SAAO,OAAO,KAAK,IAJE,KAClB,MAAM,KAAK,CACX,KAAK,MAAM,MAAO,MAAM,IAAI,OAAO,OAAO,OAAQ,CAClD,KAAK,KAAK;GAEb,CACD,KAAK,MAAM;AAId,QAAO;;;;;;6BAFc,eAAe,KAAK,aAAa,SAAS,GAQvB;;;;;;;;;;;AAY1C,eAAsB,uBAAuB,SAK1C;CACD,MAAM,EAAE,SAAS,aAAa,aAAa,YAAY;AAEvD,QAAO,MAAM,8BAA8B;CAE3C,IAAI,gBAA+B,EAAE;AACrC,KAAI,YACF,iBAAgB,MAAM,4BACpB,aACA,aACA,EACE,SACD,CACF;CAEH,MAAM,mBAAmB,yBAAyB,cAAc;AAEhE,OAAM,GAAG,UAAU,SAAS,kBAAkB,QAAQ;AAEtD,QAAO,MAAM,4BAA4B"}
+{"version":3,"file":"index.js","names":["generateServingTypesImpl"],"sources":["../../src/type-generator/index.ts"],"sourcesContent":["import fs from \"node:fs/promises\";\nimport dotenv from \"dotenv\";\nimport { createLogger } from \"../logging/logger\";\nimport { generateQueriesFromDescribe } from \"./query-registry\";\nimport { generateServingTypes as generateServingTypesImpl } from \"./serving/generator\";\nimport type { QuerySchema } from \"./types\";\n\ndotenv.config();\n\nconst logger = createLogger(\"type-generator\");\n\n/**\n * Generate type declarations for QueryRegistry\n * Create the d.ts file from the plugin routes and query schemas\n * @param querySchemas - the list of query schemas\n * @returns - the type declarations as a string\n */\nfunction generateTypeDeclarations(querySchemas: QuerySchema[] = []): string {\n  const queryEntries = querySchemas\n    .map(({ name, type }) => {\n      const indentedType = type\n        .split(\"\\n\")\n        .map((line, i) => (i === 0 ? line : `    ${line}`))\n        .join(\"\\n\");\n      return `    ${name}: ${indentedType}`;\n    })\n    .join(\";\\n\");\n\n  const querySection = queryEntries ? `\\n${queryEntries};\\n  ` : \"\";\n\n  return `// Auto-generated by AppKit - DO NOT EDIT\n// Generated by 'npx @databricks/appkit generate-types' or Vite plugin during build\nimport \"@databricks/appkit-ui/react\";\nimport type { SQLTypeMarker, SQLStringMarker, SQLNumberMarker, SQLBooleanMarker, SQLBinaryMarker, SQLDateMarker, SQLTimestampMarker } from \"@databricks/appkit-ui/js\";\n\ndeclare module \"@databricks/appkit-ui/react\" {\n  interface QueryRegistry {${querySection}}\n}\n`;\n}\n\n/**\n * Entry point for generating type declarations from all imported files\n * @param options - the options for the generation\n * @param options.entryPoint - the entry point file\n * @param options.outFile - the output file\n * @param options.querySchemaFile - optional path to query schema file (e.g. config/queries/schema.ts)\n */\nexport async function generateFromEntryPoint(options: {\n  outFile: string;\n  queryFolder?: string;\n  warehouseId: string;\n  noCache?: boolean;\n}) {\n  const { outFile, queryFolder, warehouseId, noCache } = options;\n\n  logger.debug(\"Starting type generation...\");\n\n  let queryRegistry: QuerySchema[] = [];\n  if (queryFolder)\n    queryRegistry = await generateQueriesFromDescribe(\n      queryFolder,\n      warehouseId,\n      {\n        noCache,\n      },\n    );\n\n  const failedQueries = queryRegistry.filter((q) =>\n    q.type.includes(\"result: unknown\"),\n  );\n  if (failedQueries.length > 0) {\n    const names = failedQueries.map((q) => q.name).join(\", \");\n    throw new Error(\n      [\n        `Type generation failed: ${failedQueries.length} ${failedQueries.length === 1 ? \"query\" : \"queries\"} could not be described: ${names}.`,\n        `DESCRIBE QUERY failed for these queries — see the error codes above for details.`,\n        `Common causes: SQL syntax errors, missing tables/views, or warehouse format incompatibilities.`,\n        `To debug: run the failing query directly in a SQL editor against warehouse ${warehouseId}.`,\n      ].join(\"\\n\"),\n    );\n  }\n\n  const typeDeclarations = generateTypeDeclarations(queryRegistry);\n\n  await fs.writeFile(outFile, typeDeclarations, \"utf-8\");\n\n  logger.debug(\"Type generation complete!\");\n}\n\n// Rolldown tree-shaking only preserves \"own exports\" (locally defined) — not re-exports.\n// A local binding ensures the serving vite plugin's import keeps this in the dependency graph,\n// mirroring how generateFromEntryPoint (also defined here) is preserved via the analytics vite plugin.\nexport const generateServingTypes = generateServingTypesImpl;\n"],"mappings":";;;;;;;AAOA,OAAO,QAAQ;AAEf,MAAM,SAAS,aAAa,iBAAiB;;;;;;;AAQ7C,SAAS,yBAAyB,eAA8B,EAAE,EAAU;CAC1E,MAAM,eAAe,aAClB,KAAK,EAAE,MAAM,WAAW;AAKvB,SAAO,OAAO,KAAK,IAJE,KAClB,MAAM,KAAK,CACX,KAAK,MAAM,MAAO,MAAM,IAAI,OAAO,OAAO,OAAQ,CAClD,KAAK,KAAK;GAEb,CACD,KAAK,MAAM;AAId,QAAO;;;;;;6BAFc,eAAe,KAAK,aAAa,SAAS,GAQvB;;;;;;;;;;;AAY1C,eAAsB,uBAAuB,SAK1C;CACD,MAAM,EAAE,SAAS,aAAa,aAAa,YAAY;AAEvD,QAAO,MAAM,8BAA8B;CAE3C,IAAI,gBAA+B,EAAE;AACrC,KAAI,YACF,iBAAgB,MAAM,4BACpB,aACA,aACA,EACE,SACD,CACF;CAEH,MAAM,gBAAgB,cAAc,QAAQ,MAC1C,EAAE,KAAK,SAAS,kBAAkB,CACnC;AACD,KAAI,cAAc,SAAS,GAAG;EAC5B,MAAM,QAAQ,cAAc,KAAK,MAAM,EAAE,KAAK,CAAC,KAAK,KAAK;AACzD,QAAM,IAAI,MACR;GACE,2BAA2B,cAAc,OAAO,GAAG,cAAc,WAAW,IAAI,UAAU,UAAU,2BAA2B,MAAM;GACrI;GACA;GACA,8EAA8E,YAAY;GAC3F,CAAC,KAAK,KAAK,CACb;;CAGH,MAAM,mBAAmB,yBAAyB,cAAc;AAEhE,OAAM,GAAG,UAAU,SAAS,kBAAkB,QAAQ;AAEtD,QAAO,MAAM,4BAA4B;;AAM3C,MAAa,uBAAuBA"}