@databricks/appkit 0.0.2

package/dist/plugin/interceptors/retry.js

@@ -0,0 +1,32 @@
+//#region src/plugin/interceptors/retry.ts
+var RetryInterceptor = class {
+	constructor(config) {
+		this.attempts = config.attempts ?? 3;
+		this.initialDelay = config.initialDelay ?? 1e3;
+		this.maxDelay = config.maxDelay ?? 3e4;
+	}
+	async intercept(fn, context) {
+		let lastError;
+		for (let attempt = 1; attempt <= this.attempts; attempt++) try {
+			return await fn();
+		} catch (error) {
+			lastError = error;
+			if (attempt === this.attempts) throw error;
+			if (context.signal?.aborted) throw error;
+			const delay = this.calculateDelay(attempt);
+			await this.sleep(delay);
+		}
+		throw lastError;
+	}
+	calculateDelay(attempt) {
+		const delay = this.initialDelay * 2 ** (attempt - 1);
+		return Math.min(delay, this.maxDelay);
+	}
+	sleep(ms) {
+		return new Promise((resolve) => setTimeout(resolve, ms));
+	}
+};
+
+//#endregion
+export { RetryInterceptor };
+//# sourceMappingURL=retry.js.map

package/dist/plugin/interceptors/retry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"retry.js","names":["lastError: Error | unknown"],"sources":["../../../src/plugin/interceptors/retry.ts"],"sourcesContent":["import type { RetryConfig } from \"shared\";\nimport type { ExecutionContext, ExecutionInterceptor } from \"./types\";\n\n// interceptor to handle retry logic\nexport class RetryInterceptor implements ExecutionInterceptor {\n  private attempts: number;\n  private initialDelay: number;\n  private maxDelay: number;\n\n  constructor(config: RetryConfig) {\n    this.attempts = config.attempts ?? 3;\n    this.initialDelay = config.initialDelay ?? 1000;\n    this.maxDelay = config.maxDelay ?? 30000;\n  }\n\n  async intercept<T>(\n    fn: () => Promise<T>,\n    context: ExecutionContext,\n  ): Promise<T> {\n    let lastError: Error | unknown;\n\n    for (let attempt = 1; attempt <= this.attempts; attempt++) {\n      try {\n        return await fn();\n      } catch (error) {\n        lastError = error;\n\n        // last attempt, rethrow the error\n        if (attempt === this.attempts) {\n          throw error;\n        }\n\n        // don't retry if was already aborted\n        if (context.signal?.aborted) {\n          throw error;\n        }\n\n        const delay = this.calculateDelay(attempt);\n        await this.sleep(delay);\n      }\n    }\n\n    // type guard\n    throw lastError;\n  }\n\n  private calculateDelay(attempt: number): number {\n    // exponential backoff\n    const delay = this.initialDelay * 2 ** (attempt - 1);\n\n    // max delay cap\n    return Math.min(delay, this.maxDelay);\n  }\n\n  private sleep(ms: number): Promise<void> {\n    return new Promise((resolve) => setTimeout(resolve, ms));\n  }\n}\n"],"mappings":";AAIA,IAAa,mBAAb,MAA8D;CAK5D,YAAY,QAAqB;AAC/B,OAAK,WAAW,OAAO,YAAY;AACnC,OAAK,eAAe,OAAO,gBAAgB;AAC3C,OAAK,WAAW,OAAO,YAAY;;CAGrC,MAAM,UACJ,IACA,SACY;EACZ,IAAIA;AAEJ,OAAK,IAAI,UAAU,GAAG,WAAW,KAAK,UAAU,UAC9C,KAAI;AACF,UAAO,MAAM,IAAI;WACV,OAAO;AACd,eAAY;AAGZ,OAAI,YAAY,KAAK,SACnB,OAAM;AAIR,OAAI,QAAQ,QAAQ,QAClB,OAAM;GAGR,MAAM,QAAQ,KAAK,eAAe,QAAQ;AAC1C,SAAM,KAAK,MAAM,MAAM;;AAK3B,QAAM;;CAGR,AAAQ,eAAe,SAAyB;EAE9C,MAAM,QAAQ,KAAK,eAAe,MAAM,UAAU;AAGlD,SAAO,KAAK,IAAI,OAAO,KAAK,SAAS;;CAGvC,AAAQ,MAAM,IAA2B;AACvC,SAAO,IAAI,SAAS,YAAY,WAAW,SAAS,GAAG,CAAC"}

package/dist/plugin/interceptors/telemetry.js

@@ -0,0 +1,33 @@
+import { SpanStatusCode } from "../../telemetry/index.js";
+
+//#region src/plugin/interceptors/telemetry.ts
+/**
+* Interceptor to automatically instrument plugin executions with telemetry spans.
+* Wraps the execution in a span and handles success/error status.
+*/
+var TelemetryInterceptor = class {
+	constructor(telemetry, config) {
+		this.telemetry = telemetry;
+		this.config = config;
+	}
+	async intercept(fn, _context) {
+		const spanName = this.config?.spanName || "plugin.execute";
+		return this.telemetry.startActiveSpan(spanName, { attributes: this.config?.attributes }, async (span) => {
+			try {
+				const result = await fn();
+				span.setStatus({ code: SpanStatusCode.OK });
+				return result;
+			} catch (error) {
+				span.recordException(error);
+				span.setStatus({ code: SpanStatusCode.ERROR });
+				throw error;
+			} finally {
+				span.end();
+			}
+		});
+	}
+};
+
+//#endregion
+export { TelemetryInterceptor };
+//# sourceMappingURL=telemetry.js.map

package/dist/plugin/interceptors/telemetry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"telemetry.js","names":["telemetry: ITelemetry","config?: TelemetryConfig"],"sources":["../../../src/plugin/interceptors/telemetry.ts"],"sourcesContent":["import type { ITelemetry, Span } from \"../../telemetry\";\nimport { SpanStatusCode } from \"../../telemetry\";\nimport type { TelemetryConfig } from \"shared\";\nimport type { ExecutionContext, ExecutionInterceptor } from \"./types\";\n\n/**\n * Interceptor to automatically instrument plugin executions with telemetry spans.\n * Wraps the execution in a span and handles success/error status.\n */\nexport class TelemetryInterceptor implements ExecutionInterceptor {\n  constructor(\n    private telemetry: ITelemetry,\n    private config?: TelemetryConfig,\n  ) {}\n\n  async intercept<T>(\n    fn: () => Promise<T>,\n    _context: ExecutionContext,\n  ): Promise<T> {\n    const spanName = this.config?.spanName || \"plugin.execute\";\n    return this.telemetry.startActiveSpan(\n      spanName,\n      { attributes: this.config?.attributes },\n      async (span: Span) => {\n        try {\n          const result = await fn();\n          span.setStatus({ code: SpanStatusCode.OK });\n          return result;\n        } catch (error) {\n          span.recordException(error as Error);\n          span.setStatus({ code: SpanStatusCode.ERROR });\n          throw error;\n        } finally {\n          span.end();\n        }\n      },\n    );\n  }\n}\n"],"mappings":";;;;;;;AASA,IAAa,uBAAb,MAAkE;CAChE,YACE,AAAQA,WACR,AAAQC,QACR;EAFQ;EACA;;CAGV,MAAM,UACJ,IACA,UACY;EACZ,MAAM,WAAW,KAAK,QAAQ,YAAY;AAC1C,SAAO,KAAK,UAAU,gBACpB,UACA,EAAE,YAAY,KAAK,QAAQ,YAAY,EACvC,OAAO,SAAe;AACpB,OAAI;IACF,MAAM,SAAS,MAAM,IAAI;AACzB,SAAK,UAAU,EAAE,MAAM,eAAe,IAAI,CAAC;AAC3C,WAAO;YACA,OAAO;AACd,SAAK,gBAAgB,MAAe;AACpC,SAAK,UAAU,EAAE,MAAM,eAAe,OAAO,CAAC;AAC9C,UAAM;aACE;AACR,SAAK,KAAK;;IAGf"}

package/dist/plugin/interceptors/timeout.js

@@ -0,0 +1,35 @@
+//#region src/plugin/interceptors/timeout.ts
+var TimeoutInterceptor = class {
+	constructor(timeoutMs) {
+		this.timeoutMs = timeoutMs;
+	}
+	async intercept(fn, context) {
+		const timeoutController = new AbortController();
+		const timeoutId = setTimeout(() => {
+			timeoutController.abort(/* @__PURE__ */ new Error(`Operation timed out after ${this.timeoutMs} ms`));
+		}, this.timeoutMs);
+		try {
+			context.signal = context.signal ? this._combineSignals([context.signal, timeoutController.signal]) : timeoutController.signal;
+			return await fn();
+		} finally {
+			clearTimeout(timeoutId);
+		}
+	}
+	_combineSignals(signals) {
+		const controller = new AbortController();
+		for (const signal of signals) {
+			if (signal.aborted) {
+				controller.abort(signal.reason);
+				break;
+			}
+			signal.addEventListener("abort", () => {
+				controller.abort(signal.reason);
+			}, { once: true });
+		}
+		return controller.signal;
+	}
+};
+
+//#endregion
+export { TimeoutInterceptor };
+//# sourceMappingURL=timeout.js.map

package/dist/plugin/interceptors/timeout.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"timeout.js","names":["timeoutMs: number"],"sources":["../../../src/plugin/interceptors/timeout.ts"],"sourcesContent":["import type { ExecutionContext, ExecutionInterceptor } from \"./types\";\n\n// interceptor to handle timeout logic\nexport class TimeoutInterceptor implements ExecutionInterceptor {\n  constructor(private timeoutMs: number) {}\n\n  async intercept<T>(\n    fn: () => Promise<T>,\n    context: ExecutionContext,\n  ): Promise<T> {\n    // create timeout signal\n    const timeoutController = new AbortController();\n    const timeoutId = setTimeout(() => {\n      timeoutController.abort(\n        new Error(`Operation timed out after ${this.timeoutMs} ms`),\n      );\n    }, this.timeoutMs);\n\n    try {\n      // combine user signal (if exists) with timeout signal\n      const combinedSignal = context.signal\n        ? this._combineSignals([context.signal, timeoutController.signal])\n        : timeoutController.signal;\n\n      // execute function with combined signal\n      context.signal = combinedSignal;\n      return await fn();\n    } finally {\n      // cleanup timeout\n      clearTimeout(timeoutId);\n    }\n  }\n\n  private _combineSignals(signals: AbortSignal[]): AbortSignal {\n    const controller = new AbortController();\n    for (const signal of signals) {\n      if (signal.aborted) {\n        controller.abort(signal.reason);\n        break;\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"],"mappings":";AAGA,IAAa,qBAAb,MAAgE;CAC9D,YAAY,AAAQA,WAAmB;EAAnB;;CAEpB,MAAM,UACJ,IACA,SACY;EAEZ,MAAM,oBAAoB,IAAI,iBAAiB;EAC/C,MAAM,YAAY,iBAAiB;AACjC,qBAAkB,sBAChB,IAAI,MAAM,6BAA6B,KAAK,UAAU,KAAK,CAC5D;KACA,KAAK,UAAU;AAElB,MAAI;AAOF,WAAQ,SALe,QAAQ,SAC3B,KAAK,gBAAgB,CAAC,QAAQ,QAAQ,kBAAkB,OAAO,CAAC,GAChE,kBAAkB;AAItB,UAAO,MAAM,IAAI;YACT;AAER,gBAAa,UAAU;;;CAI3B,AAAQ,gBAAgB,SAAqC;EAC3D,MAAM,aAAa,IAAI,iBAAiB;AACxC,OAAK,MAAM,UAAU,SAAS;AAC5B,OAAI,OAAO,SAAS;AAClB,eAAW,MAAM,OAAO,OAAO;AAC/B;;AAEF,UAAO,iBACL,eACM;AACJ,eAAW,MAAM,OAAO,OAAO;MAEjC,EAAE,MAAM,MAAM,CACf;;AAEH,SAAO,WAAW"}

package/dist/plugin/plugin.d.ts

@@ -0,0 +1,43 @@
+import { BasePlugin, BasePluginConfig, IAppResponse, PluginEndpointMap, PluginPhase, RouteConfig } from "../shared/src/plugin.js";
+import { PluginExecutionSettings, StreamExecuteHandler, StreamExecutionSettings } from "../shared/src/execute.js";
+import { AppManager } from "../app/index.js";
+import { CacheManager } from "../cache/index.js";
+import { StreamManager } from "../stream/stream-manager.js";
+import { ITelemetry } from "../telemetry/types.js";
+import { DevFileReader } from "./dev-reader.js";
+import express from "express";
+
+//#region src/plugin/plugin.d.ts
+declare abstract class Plugin<TConfig extends BasePluginConfig = BasePluginConfig> implements BasePlugin {
+  protected config: TConfig;
+  protected isReady: boolean;
+  protected cache: CacheManager;
+  protected app: AppManager;
+  protected devFileReader: DevFileReader;
+  protected streamManager: StreamManager;
+  protected telemetry: ITelemetry;
+  protected abstract envVars: string[];
+  /** If the plugin requires the Databricks client to be set in the request context */
+  requiresDatabricksClient: boolean;
+  /** Registered endpoints for this plugin */
+  private registeredEndpoints;
+  static phase: PluginPhase;
+  name: string;
+  constructor(config: TConfig);
+  validateEnv(): void;
+  injectRoutes(_: express.Router): void;
+  setup(): Promise<void>;
+  getEndpoints(): PluginEndpointMap;
+  abortActiveOperations(): void;
+  protected executeStream<T>(res: IAppResponse, fn: StreamExecuteHandler<T>, options: StreamExecutionSettings, userKey: string): Promise<void>;
+  protected execute<T>(fn: (signal?: AbortSignal) => Promise<T>, options: PluginExecutionSettings, userKey: string): Promise<T | undefined>;
+  protected registerEndpoint(name: string, path: string): void;
+  protected route<_TResponse>(router: express.Router, config: RouteConfig): void;
+  private _buildExecutionConfig;
+  private _buildInterceptors;
+  private _executeWithInterceptors;
+  private _checkIfGenerator;
+}
+//#endregion
+export { Plugin };
+//# sourceMappingURL=plugin.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.d.ts","names":[],"sources":["../../src/plugin/plugin.ts"],"sourcesContent":[],"mappings":";;;;;;;;;;uBAgCsB,uBACJ,mBAAmB,6BACxB;oBAmBmB;;EArBV,UAAM,KAAA,EAKT,YALS;EAAA,UAAA,GAAA,EAMX,UANW;YACV,aAAA,EAMS,aANT;YAAmB,aAAA,EAOV,aAPU;YAoBL,SAAA,EAZT,UAYS;qBAhBb,OAAA,EAAA,MAAA,EAAA;;0BAEQ,EAAA,OAAA;;UAEJ,mBAAA;SASP,KAAA,EAAA,WAAA;MAGgB,EAAA,MAAA;aAeN,CAAA,MAAA,EAfM,OAeN;aAIb,CAAA,CAAA,EAAA,IAAA;cAEK,CAAA,CAAA,EANA,OAAA,CAAQ,MAMR,CAAA,EAAA,IAAA;OAUT,CAAA,CAAA,EAZI,OAYJ,CAAA,IAAA,CAAA;cACoB,CAAA,CAAA,EAXX,iBAWW;uBAArB,CAAA,CAAA,EAAA,IAAA;YACK,aAAA,CAAA,CAAA,CAAA,CAAA,GAAA,EAFJ,YAEI,EAAA,EAAA,EADL,oBACK,CADgB,CAChB,CAAA,EAAA,OAAA,EAAA,uBAAA,EAAA,OAAA,EAAA,MAAA,CAAA,EACM,OADN,CAAA,IAAA,CAAA;YACM,OAAA,CAAA,CAAA,CAAA,CAAA,EAAA,EAAA,CAAA,MAAA,CAAA,EAwDD,WAxDC,EAAA,GAwDe,OAxDf,CAwDuB,CAxDvB,CAAA,EAAA,OAAA,EAyDN,uBAzDM,EAAA,OAAA,EAAA,MAAA,CAAA,EA2Dd,OA3Dc,CA2DN,CA3DM,GAAA,SAAA,CAAA;YAwDD,gBAAA,CAAA,IAAA,EAAA,MAAA,EAAA,IAAA,EAAA,MAAA,CAAA,EAAA,IAAA;YAAwB,KAAA,CAAA,UAAA,CAAA,CAAA,MAAA,EA0B9B,OAAA,CAAQ,MA1BsB,EAAA,MAAA,EA2B9B,WA3B8B,CAAA,EAAA,IAAA;UAAR,qBAAA;UACrB,kBAAA;UAEA,wBAAA;UAAR,iBAAA"}

package/dist/plugin/plugin.js

@@ -0,0 +1,119 @@
+import { normalizeTelemetryOptions } from "../telemetry/config.js";
+import { TelemetryManager } from "../telemetry/telemetry-manager.js";
+import "../telemetry/index.js";
+import { validateEnv } from "../utils/env-validator.js";
+import { deepMerge } from "../utils/merge.js";
+import { init_utils } from "../utils/index.js";
+import { AppManager } from "../app/index.js";
+import { CacheManager } from "../cache/index.js";
+import { StreamManager } from "../stream/stream-manager.js";
+import "../stream/index.js";
+import { DevFileReader } from "./dev-reader.js";
+import { CacheInterceptor } from "./interceptors/cache.js";
+import { RetryInterceptor } from "./interceptors/retry.js";
+import { TelemetryInterceptor } from "./interceptors/telemetry.js";
+import { TimeoutInterceptor } from "./interceptors/timeout.js";
+
+//#region src/plugin/plugin.ts
+init_utils();
+var Plugin = class {
+	static {
+		this.phase = "normal";
+	}
+	constructor(config) {
+		this.config = config;
+		this.isReady = false;
+		this.requiresDatabricksClient = false;
+		this.registeredEndpoints = {};
+		this.name = config.name ?? "plugin";
+		this.telemetry = TelemetryManager.getProvider(this.name, config.telemetry);
+		this.streamManager = new StreamManager();
+		this.cache = CacheManager.getInstanceSync();
+		this.app = new AppManager();
+		this.devFileReader = DevFileReader.getInstance();
+		this.isReady = true;
+	}
+	validateEnv() {
+		validateEnv(this.envVars);
+	}
+	injectRoutes(_) {}
+	async setup() {}
+	getEndpoints() {
+		return this.registeredEndpoints;
+	}
+	abortActiveOperations() {
+		this.streamManager.abortAll();
+	}
+	async executeStream(res, fn, options, userKey) {
+		const { stream: streamConfig, default: defaultConfig, user: userConfig } = options;
+		const executeConfig = this._buildExecutionConfig({
+			default: defaultConfig,
+			user: userConfig
+		});
+		const self = this;
+		const asyncWrapperFn = async function* (streamSignal) {
+			const context = {
+				signal: streamSignal,
+				metadata: /* @__PURE__ */ new Map(),
+				userKey
+			};
+			const interceptors = self._buildInterceptors(executeConfig);
+			const wrappedFn = async () => {
+				return await fn(context.signal);
+			};
+			const result = await self._executeWithInterceptors(wrappedFn, interceptors, context);
+			if (self._checkIfGenerator(result)) yield* result;
+			else yield result;
+		};
+		await this.streamManager.stream(res, asyncWrapperFn, streamConfig);
+	}
+	async execute(fn, options, userKey) {
+		const executeConfig = this._buildExecutionConfig(options);
+		const interceptors = this._buildInterceptors(executeConfig);
+		const context = {
+			metadata: /* @__PURE__ */ new Map(),
+			userKey
+		};
+		try {
+			return await this._executeWithInterceptors(fn, interceptors, context);
+		} catch (_error) {
+			return;
+		}
+	}
+	registerEndpoint(name, path) {
+		this.registeredEndpoints[name] = path;
+	}
+	route(router, config) {
+		const { name, method, path, handler } = config;
+		router[method](path, handler);
+		this.registerEndpoint(name, `/api/${this.name}${path}`);
+	}
+	_buildExecutionConfig(options) {
+		const { default: methodDefaults, user: userOverride } = options;
+		return deepMerge(deepMerge(methodDefaults, this.config), userOverride ?? {});
+	}
+	_buildInterceptors(options) {
+		const interceptors = [];
+		if (normalizeTelemetryOptions(this.config.telemetry).traces && (options.telemetryInterceptor?.enabled ?? true)) interceptors.push(new TelemetryInterceptor(this.telemetry, options.telemetryInterceptor));
+		if (options.timeout && options.timeout > 0) interceptors.push(new TimeoutInterceptor(options.timeout));
+		if (options.retry?.enabled && options.retry.attempts && options.retry.attempts > 1) interceptors.push(new RetryInterceptor(options.retry));
+		if (options.cache?.enabled && options.cache.cacheKey?.length) interceptors.push(new CacheInterceptor(this.cache, options.cache));
+		return interceptors;
+	}
+	async _executeWithInterceptors(fn, interceptors, context) {
+		if (interceptors.length === 0) return fn(context.signal);
+		let wrappedFn = () => fn(context.signal);
+		for (const interceptor of interceptors) {
+			const previousFn = wrappedFn;
+			wrappedFn = () => interceptor.intercept(previousFn, context);
+		}
+		return wrappedFn();
+	}
+	_checkIfGenerator(result) {
+		return result && typeof result === "object" && Symbol.asyncIterator in result;
+	}
+};
+
+//#endregion
+export { Plugin };
+//# sourceMappingURL=plugin.js.map

package/dist/plugin/plugin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.js","names":["config: TConfig","context: ExecutionContext","interceptors: ExecutionInterceptor[]"],"sources":["../../src/plugin/plugin.ts"],"sourcesContent":["import type express from \"express\";\nimport type {\n  BasePlugin,\n  BasePluginConfig,\n  IAppResponse,\n  PluginEndpointMap,\n  PluginExecuteConfig,\n  PluginExecutionSettings,\n  PluginPhase,\n  RouteConfig,\n  StreamExecuteHandler,\n  StreamExecutionSettings,\n} from \"shared\";\nimport { AppManager } from \"../app\";\nimport { CacheManager } from \"../cache\";\nimport { StreamManager } from \"../stream\";\nimport {\n  type ITelemetry,\n  normalizeTelemetryOptions,\n  TelemetryManager,\n} from \"../telemetry\";\nimport { deepMerge, validateEnv } from \"../utils\";\nimport { DevFileReader } from \"./dev-reader\";\nimport { CacheInterceptor } from \"./interceptors/cache\";\nimport { RetryInterceptor } from \"./interceptors/retry\";\nimport { TelemetryInterceptor } from \"./interceptors/telemetry\";\nimport { TimeoutInterceptor } from \"./interceptors/timeout\";\nimport type {\n  ExecutionContext,\n  ExecutionInterceptor,\n} from \"./interceptors/types\";\n\nexport abstract class Plugin<\n  TConfig extends BasePluginConfig = BasePluginConfig,\n> implements BasePlugin\n{\n  protected isReady = false;\n  protected cache: CacheManager;\n  protected app: AppManager;\n  protected devFileReader: DevFileReader;\n  protected streamManager: StreamManager;\n  protected telemetry: ITelemetry;\n  protected abstract envVars: string[];\n\n  /** If the plugin requires the Databricks client to be set in the request context */\n  requiresDatabricksClient = false;\n\n  /** Registered endpoints for this plugin */\n  private registeredEndpoints: PluginEndpointMap = {};\n\n  static phase: PluginPhase = \"normal\";\n  name: string;\n\n  constructor(protected config: TConfig) {\n    this.name = config.name ?? \"plugin\";\n    this.telemetry = TelemetryManager.getProvider(this.name, config.telemetry);\n    this.streamManager = new StreamManager();\n    this.cache = CacheManager.getInstanceSync();\n    this.app = new AppManager();\n    this.devFileReader = DevFileReader.getInstance();\n\n    this.isReady = true;\n  }\n\n  validateEnv() {\n    validateEnv(this.envVars);\n  }\n\n  injectRoutes(_: express.Router) {\n    return;\n  }\n\n  async setup() {}\n\n  getEndpoints(): PluginEndpointMap {\n    return this.registeredEndpoints;\n  }\n\n  abortActiveOperations(): void {\n    this.streamManager.abortAll();\n  }\n\n  // streaming execution with interceptors\n  protected async executeStream<T>(\n    res: IAppResponse,\n    fn: StreamExecuteHandler<T>,\n    options: StreamExecutionSettings,\n    userKey: string,\n  ) {\n    // destructure options\n    const {\n      stream: streamConfig,\n      default: defaultConfig,\n      user: userConfig,\n    } = options;\n\n    // build execution options\n    const executeConfig = this._buildExecutionConfig({\n      default: defaultConfig,\n      user: userConfig,\n    });\n\n    const self = this;\n\n    // wrapper function to ensure it returns a generator\n    const asyncWrapperFn = async function* (streamSignal?: AbortSignal) {\n      // build execution context\n      const context: ExecutionContext = {\n        signal: streamSignal,\n        metadata: new Map(),\n        userKey: userKey,\n      };\n\n      // build interceptors\n      const interceptors = self._buildInterceptors(executeConfig);\n\n      // wrap the function to ensure it returns a promise\n      const wrappedFn = async () => {\n        const result = await fn(context.signal);\n        return result;\n      };\n\n      // execute the function with interceptors\n      const result = await self._executeWithInterceptors(\n        wrappedFn as (signal?: AbortSignal) => Promise<T>,\n        interceptors,\n        context,\n      );\n\n      // check if result is a generator\n      if (self._checkIfGenerator(result)) {\n        yield* result;\n      } else {\n        yield result;\n      }\n    };\n\n    // stream the result to the client\n    await this.streamManager.stream(res, asyncWrapperFn, streamConfig);\n  }\n\n  // single sync execution with interceptors\n  protected async execute<T>(\n    fn: (signal?: AbortSignal) => Promise<T>,\n    options: PluginExecutionSettings,\n    userKey: string,\n  ): Promise<T | undefined> {\n    const executeConfig = this._buildExecutionConfig(options);\n\n    const interceptors = this._buildInterceptors(executeConfig);\n\n    const context: ExecutionContext = {\n      metadata: new Map(),\n      userKey: userKey,\n    };\n\n    try {\n      return await this._executeWithInterceptors(fn, interceptors, context);\n    } catch (_error) {\n      // production-safe, don't crash sdk\n      return undefined;\n    }\n  }\n\n  protected registerEndpoint(name: string, path: string): void {\n    this.registeredEndpoints[name] = path;\n  }\n\n  protected route<_TResponse>(\n    router: express.Router,\n    config: RouteConfig,\n  ): void {\n    const { name, method, path, handler } = config;\n\n    router[method](path, handler);\n\n    this.registerEndpoint(name, `/api/${this.name}${path}`);\n  }\n\n  // build execution options by merging defaults, plugin config, and user overrides\n  private _buildExecutionConfig(\n    options: PluginExecutionSettings,\n  ): PluginExecuteConfig {\n    const { default: methodDefaults, user: userOverride } = options;\n\n    // Merge: method defaults <- plugin config <- user override (highest priority)\n    return deepMerge(\n      deepMerge(methodDefaults, this.config),\n      userOverride ?? {},\n    ) as PluginExecuteConfig;\n  }\n\n  // build interceptors based on execute options\n  private _buildInterceptors(\n    options: PluginExecuteConfig,\n  ): ExecutionInterceptor[] {\n    const interceptors: ExecutionInterceptor[] = [];\n\n    // order matters: telemetry → timeout → retry → cache (innermost to outermost)\n\n    // Only add telemetry interceptor if traces are enabled\n    const telemetryConfig = normalizeTelemetryOptions(this.config.telemetry);\n    if (\n      telemetryConfig.traces &&\n      (options.telemetryInterceptor?.enabled ?? true)\n    ) {\n      interceptors.push(\n        new TelemetryInterceptor(this.telemetry, options.telemetryInterceptor),\n      );\n    }\n\n    if (options.timeout && options.timeout > 0) {\n      interceptors.push(new TimeoutInterceptor(options.timeout));\n    }\n\n    if (\n      options.retry?.enabled &&\n      options.retry.attempts &&\n      options.retry.attempts > 1\n    ) {\n      interceptors.push(new RetryInterceptor(options.retry));\n    }\n\n    if (options.cache?.enabled && options.cache.cacheKey?.length) {\n      interceptors.push(new CacheInterceptor(this.cache, options.cache));\n    }\n\n    return interceptors;\n  }\n\n  // execute method wrapped with interceptors\n  private async _executeWithInterceptors<T>(\n    fn: (signal?: AbortSignal) => Promise<T>,\n    interceptors: ExecutionInterceptor[],\n    context: ExecutionContext,\n  ): Promise<T> {\n    // no interceptors, execute directly\n    if (interceptors.length === 0) {\n      return fn(context.signal);\n    }\n    // build nested execution chain from interceptors\n    let wrappedFn = () => fn(context.signal);\n\n    // wrap each interceptor around the previous function\n    for (const interceptor of interceptors) {\n      const previousFn = wrappedFn;\n      wrappedFn = () => interceptor.intercept(previousFn, context);\n    }\n\n    return wrappedFn();\n  }\n\n  private _checkIfGenerator(\n    result: any,\n  ): result is AsyncGenerator<any, void, unknown> {\n    return (\n      result && typeof result === \"object\" && Symbol.asyncIterator in result\n    );\n  }\n}\n"],"mappings":"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"}

package/dist/plugin/to-plugin.d.ts

@@ -0,0 +1,7 @@
+import { ToPlugin } from "../shared/src/plugin.js";
+
+//#region src/plugin/to-plugin.d.ts
+declare function toPlugin<T, U, N extends string>(plugin: T, name: N): ToPlugin<T, U, N>;
+//#endregion
+export { toPlugin };
+//# sourceMappingURL=to-plugin.d.ts.map

package/dist/plugin/to-plugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"to-plugin.d.ts","names":[],"sources":["../../src/plugin/to-plugin.ts"],"sourcesContent":[],"mappings":";;;iBAEgB,yCACN,SACF,IACL,SAAS,GAAG,GAAG"}

package/dist/plugin/to-plugin.js

@@ -0,0 +1,12 @@
+//#region src/plugin/to-plugin.ts
+function toPlugin(plugin, name) {
+	return (config = {}) => ({
+		plugin,
+		config,
+		name
+	});
+}
+
+//#endregion
+export { toPlugin };
+//# sourceMappingURL=to-plugin.js.map

package/dist/plugin/to-plugin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"to-plugin.js","names":[],"sources":["../../src/plugin/to-plugin.ts"],"sourcesContent":["import type { PluginData, ToPlugin } from \"shared\";\n\nexport function toPlugin<T, U, N extends string>(\n  plugin: T,\n  name: N,\n): ToPlugin<T, U, N> {\n  return (config: U = {} as U): PluginData<T, U, N> => ({\n    plugin: plugin as T,\n    config: config as U,\n    name,\n  });\n}\n"],"mappings":";AAEA,SAAgB,SACd,QACA,MACmB;AACnB,SAAQ,SAAY,EAAE,MAAgC;EAC5C;EACA;EACR;EACD"}

package/dist/server/base-server.js

@@ -0,0 +1,24 @@
+import { getConfigScript } from "./utils.js";
+
+//#region src/server/base-server.ts
+/**
+* Base server for the AppKit.
+*
+* Abstract base class that provides common functionality for serving
+* frontend applications. Subclasses implement specific serving strategies
+* (Vite dev server, static file server, etc.).
+*/
+var BaseServer = class {
+	constructor(app, endpoints = {}) {
+		this.app = app;
+		this.endpoints = endpoints;
+	}
+	async close() {}
+	getConfigScript() {
+		return getConfigScript(this.endpoints);
+	}
+};
+
+//#endregion
+export { BaseServer };
+//# sourceMappingURL=base-server.js.map

package/dist/server/base-server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"base-server.js","names":[],"sources":["../../src/server/base-server.ts"],"sourcesContent":["import type express from \"express\";\nimport { type PluginEndpoints, getConfigScript } from \"./utils\";\n\n/**\n * Base server for the AppKit.\n *\n * Abstract base class that provides common functionality for serving\n * frontend applications. Subclasses implement specific serving strategies\n * (Vite dev server, static file server, etc.).\n */\nexport abstract class BaseServer {\n  protected app: express.Application;\n  protected endpoints: PluginEndpoints;\n\n  constructor(app: express.Application, endpoints: PluginEndpoints = {}) {\n    this.app = app;\n    this.endpoints = endpoints;\n  }\n\n  abstract setup(): void | Promise<void>;\n\n  async close(): Promise<void> {}\n\n  protected getConfigScript(): string {\n    return getConfigScript(this.endpoints);\n  }\n}\n"],"mappings":";;;;;;;;;;AAUA,IAAsB,aAAtB,MAAiC;CAI/B,YAAY,KAA0B,YAA6B,EAAE,EAAE;AACrE,OAAK,MAAM;AACX,OAAK,YAAY;;CAKnB,MAAM,QAAuB;CAE7B,AAAU,kBAA0B;AAClC,SAAO,gBAAgB,KAAK,UAAU"}

package/dist/server/index.d.ts

@@ -0,0 +1,100 @@
+import { PluginPhase, TelemetryOptions, ToPlugin } from "../shared/src/plugin.js";
+import { Plugin } from "../plugin/plugin.js";
+import { ServerConfig } from "./types.js";
+import express from "express";
+import { Server } from "node:http";
+
+//#region src/server/index.d.ts
+
+/**
+ * Server plugin for the AppKit.
+ *
+ * This plugin is responsible for starting the server and serving the static files.
+ * It also handles the remote tunneling for development purposes.
+ *
+ * @example
+ * ```ts
+ * createApp({
+ *   plugins: [server(), telemetryExamples(), analytics({})],
+ * });
+ * ```
+ *
+ */
+declare class ServerPlugin extends Plugin {
+  static DEFAULT_CONFIG: {
+    autoStart: boolean;
+    host: string;
+    port: number;
+  };
+  name: "server";
+  envVars: string[];
+  private serverApplication;
+  private server;
+  private viteDevServer?;
+  private remoteTunnelController?;
+  protected config: ServerConfig;
+  private serverExtensions;
+  static phase: PluginPhase;
+  constructor(config: ServerConfig);
+  /** Setup the server plugin. */
+  setup(): Promise<void>;
+  /** Get the server configuration. */
+  getConfig(): {
+    [key: string]: unknown;
+    port?: number;
+    staticPath?: string;
+    autoStart?: boolean;
+    host?: string;
+    name?: string;
+    telemetry?: TelemetryOptions;
+  };
+  /** Check if the server should auto start. */
+  shouldAutoStart(): boolean | undefined;
+  /**
+   * Start the server.
+   *
+   * This method starts the server and sets up the frontend.
+   * It also sets up the remote tunneling if enabled.
+   *
+   * @returns The express application.
+   */
+  start(): Promise<express.Application>;
+  /**
+   * Get the low level node.js http server instance.
+   *
+   * Only use this method if you need to access the server instance for advanced usage like a custom websocket server, etc.
+   *
+   * @throws {Error} If the server is not started or autoStart is true.
+   * @returns {HTTPServer} The server instance.
+   */
+  getServer(): Server;
+  /**
+   * Extend the server with custom routes or middleware.
+   *
+   * @param fn - A function that receives the express application.
+   * @returns The server plugin instance for chaining.
+   * @throws {Error} If autoStart is true.
+   */
+  extend(fn: (app: express.Application) => void): this;
+  /**
+   * Setup the routes with the plugins.
+   *
+   * This method goes through all the plugins and injects the routes into the server application.
+   * Returns a map of plugin names to their registered named endpoints.
+   */
+  private extendRoutes;
+  /**
+   * Setup frontend serving based on environment:
+   * - If staticPath is explicitly provided: use static server
+   * - Dev mode (no staticPath): Vite for HMR
+   * - Production (no staticPath): Static files auto-detected
+   */
+  private setupFrontend;
+  private static findStaticPath;
+  private logStartupInfo;
+  private _gracefulShutdown;
+}
+declare const server: ToPlugin<typeof ServerPlugin, ServerConfig, "server">;
+//#endregion
+export { server };
+//# sourceMappingURL=index.d.ts.map

package/dist/server/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","names":[],"sources":["../../src/server/index.ts"],"sourcesContent":[],"mappings":";;;;;;;;;;AA+BA;;;;;;;;;;;;AAAwC,cAA3B,YAAA,SAAqB,MAAA,CAAM;EA4S3B,OAAA,cAGZ,EAAA;IAAA,SAAA,EAAA,OAAA;IAHkB,IAAA,EAAA,MAAA;IAAA,IAAA,EAAA,MAAA;;EAAA,IAAA,EAAA,QAAA;;;;;;oBA/RS;;gBAEZ;sBAEM;;WAaT;;;;;;;;;gBAAA;;;;;;;;;;;;WA0BI,QAAQ,OAAA,CAAQ;;;;;;;;;eA8ClB;;;;;;;;mBAqBI,OAAA,CAAQ;;;;;;;;;;;;;;;;;;;cAiLd,QAAM,gBAAA,cAAA"}