@databricks/appkit 0.0.2

package/dist/analytics/analytics.js

@@ -0,0 +1,149 @@
+import { getRequestContext, getWorkspaceClient } from "../utils/databricks-client-middleware.js";
+import { init_utils } from "../utils/index.js";
+import { SQLWarehouseConnector } from "../connectors/sql-warehouse/client.js";
+import "../connectors/index.js";
+import { Plugin } from "../plugin/plugin.js";
+import { toPlugin } from "../plugin/to-plugin.js";
+import "../plugin/index.js";
+import { queryDefaults } from "./defaults.js";
+import { QueryProcessor } from "./query.js";
+
+//#region src/analytics/analytics.ts
+init_utils();
+var AnalyticsPlugin = class extends Plugin {
+	static {
+		this.description = "Analytics plugin for data analysis";
+	}
+	constructor(config) {
+		super(config);
+		this.name = "analytics";
+		this.envVars = [];
+		this.requiresDatabricksClient = true;
+		this.config = config;
+		this.queryProcessor = new QueryProcessor();
+		this.SQLClient = new SQLWarehouseConnector({
+			timeout: config.timeout,
+			telemetry: config.telemetry
+		});
+	}
+	injectRoutes(router) {
+		this.route(router, {
+			name: "arrow",
+			method: "get",
+			path: "/arrow-result/:jobId",
+			handler: async (req, res) => {
+				await this._handleArrowRoute(req, res);
+			}
+		});
+		this.route(router, {
+			name: "arrowAsUser",
+			method: "get",
+			path: "/users/me/arrow-result/:jobId",
+			handler: async (req, res) => {
+				await this._handleArrowRoute(req, res, { asUser: true });
+			}
+		});
+		this.route(router, {
+			name: "queryAsUser",
+			method: "post",
+			path: "/users/me/query/:query_key",
+			handler: async (req, res) => {
+				await this._handleQueryRoute(req, res, { asUser: true });
+			}
+		});
+		this.route(router, {
+			name: "query",
+			method: "post",
+			path: "/query/:query_key",
+			handler: async (req, res) => {
+				await this._handleQueryRoute(req, res, { asUser: false });
+			}
+		});
+	}
+	async _handleArrowRoute(req, res, { asUser = false } = {}) {
+		try {
+			const { jobId } = req.params;
+			const workspaceClient = getWorkspaceClient(asUser);
+			console.log(`Processing Arrow job request: ${jobId} for plugin: ${this.name}`);
+			const result = await this.getArrowData(workspaceClient, jobId);
+			res.setHeader("Content-Type", "application/octet-stream");
+			res.setHeader("Content-Length", result.data.length.toString());
+			res.setHeader("Cache-Control", "public, max-age=3600");
+			console.log(`Sending Arrow buffer: ${result.data.length} bytes for job ${jobId}`);
+			res.send(Buffer.from(result.data));
+		} catch (error) {
+			console.error(`Arrow job error for ${this.name}:`, error);
+			res.status(404).json({
+				error: error instanceof Error ? error.message : "Arrow job not found",
+				plugin: this.name
+			});
+		}
+	}
+	async _handleQueryRoute(req, res, { asUser = false } = {}) {
+		const { query_key } = req.params;
+		const { parameters, format = "JSON" } = req.body;
+		const queryParameters = format === "ARROW" ? {
+			formatParameters: {
+				disposition: "EXTERNAL_LINKS",
+				format: "ARROW_STREAM"
+			},
+			type: "arrow"
+		} : { type: "result" };
+		const requestContext = getRequestContext();
+		const userKey = asUser ? requestContext.userId : requestContext.serviceUserId;
+		if (!query_key) {
+			res.status(400).json({ error: "query_key is required" });
+			return;
+		}
+		const query = await this.app.getAppQuery(query_key, req, this.devFileReader);
+		if (!query) {
+			res.status(404).json({ error: "Query not found" });
+			return;
+		}
+		const hashedQuery = this.queryProcessor.hashQuery(query);
+		const streamExecutionSettings = { default: {
+			...queryDefaults,
+			cache: {
+				...queryDefaults.cache,
+				cacheKey: [
+					"analytics:query",
+					query_key,
+					JSON.stringify(parameters),
+					JSON.stringify(format),
+					hashedQuery,
+					userKey
+				]
+			}
+		} };
+		await this.executeStream(res, async (signal) => {
+			const processedParams = await this.queryProcessor.processQueryParams(query, parameters);
+			const result = await this.query(query, processedParams, queryParameters.formatParameters, signal, { asUser });
+			return {
+				type: queryParameters.type,
+				...result
+			};
+		}, streamExecutionSettings, userKey);
+	}
+	async query(query, parameters, formatParameters, signal, { asUser = false } = {}) {
+		const requestContext = getRequestContext();
+		const workspaceClient = getWorkspaceClient(asUser);
+		const { statement, parameters: sqlParameters } = this.queryProcessor.convertToSQLParameters(query, parameters);
+		return (await this.SQLClient.executeStatement(workspaceClient, {
+			statement,
+			warehouse_id: await requestContext.warehouseId,
+			parameters: sqlParameters,
+			...formatParameters
+		}, signal)).result;
+	}
+	async getArrowData(workspaceClient, jobId, signal) {
+		return await this.SQLClient.getArrowData(workspaceClient, jobId, signal);
+	}
+	async shutdown() {
+		this.streamManager.abortAll();
+	}
+};
+const analytics = toPlugin(AnalyticsPlugin, "analytics");
+
+//#endregion
+export { AnalyticsPlugin, analytics };
+//# sourceMappingURL=analytics.js.map

package/dist/analytics/analytics.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"analytics.js","names":["streamExecutionSettings: StreamExecutionSettings"],"sources":["../../src/analytics/analytics.ts"],"sourcesContent":["import type { WorkspaceClient } from \"@databricks/sdk-experimental\";\nimport type {\n  IAppRouter,\n  PluginExecuteConfig,\n  SQLTypeMarker,\n  StreamExecutionSettings,\n} from \"shared\";\nimport { SQLWarehouseConnector } from \"../connectors\";\nimport { Plugin, toPlugin } from \"../plugin\";\nimport type { Request, Response } from \"../utils\";\nimport { getRequestContext, getWorkspaceClient } from \"../utils\";\nimport { queryDefaults } from \"./defaults\";\nimport { QueryProcessor } from \"./query\";\nimport type {\n  AnalyticsQueryResponse,\n  IAnalyticsConfig,\n  IAnalyticsQueryRequest,\n} from \"./types\";\n\nexport class AnalyticsPlugin extends Plugin {\n  name = \"analytics\";\n  envVars = [];\n  requiresDatabricksClient = true;\n\n  protected static description = \"Analytics plugin for data analysis\";\n  protected declare config: IAnalyticsConfig;\n\n  // analytics services\n  private SQLClient: SQLWarehouseConnector;\n  private queryProcessor: QueryProcessor;\n\n  constructor(config: IAnalyticsConfig) {\n    super(config);\n    this.config = config;\n    this.queryProcessor = new QueryProcessor();\n\n    this.SQLClient = new SQLWarehouseConnector({\n      timeout: config.timeout,\n      telemetry: config.telemetry,\n    });\n  }\n\n  injectRoutes(router: IAppRouter) {\n    this.route(router, {\n      name: \"arrow\",\n      method: \"get\",\n      path: \"/arrow-result/:jobId\",\n      handler: async (req: Request, res: Response) => {\n        await this._handleArrowRoute(req, res);\n      },\n    });\n\n    this.route(router, {\n      name: \"arrowAsUser\",\n      method: \"get\",\n      path: \"/users/me/arrow-result/:jobId\",\n      handler: async (req: Request, res: Response) => {\n        await this._handleArrowRoute(req, res, { asUser: true });\n      },\n    });\n\n    this.route<AnalyticsQueryResponse>(router, {\n      name: \"queryAsUser\",\n      method: \"post\",\n      path: \"/users/me/query/:query_key\",\n      handler: async (req: Request, res: Response) => {\n        await this._handleQueryRoute(req, res, { asUser: true });\n      },\n    });\n\n    this.route<AnalyticsQueryResponse>(router, {\n      name: \"query\",\n      method: \"post\",\n      path: \"/query/:query_key\",\n      handler: async (req: Request, res: Response) => {\n        await this._handleQueryRoute(req, res, { asUser: false });\n      },\n    });\n  }\n\n  private async _handleArrowRoute(\n    req: Request,\n    res: Response,\n    { asUser = false }: { asUser?: boolean } = {},\n  ): Promise<void> {\n    try {\n      const { jobId } = req.params;\n\n      const workspaceClient = getWorkspaceClient(asUser);\n\n      console.log(\n        `Processing Arrow job request: ${jobId} for plugin: ${this.name}`,\n      );\n\n      const result = await this.getArrowData(workspaceClient, jobId);\n\n      res.setHeader(\"Content-Type\", \"application/octet-stream\");\n      res.setHeader(\"Content-Length\", result.data.length.toString());\n      res.setHeader(\"Cache-Control\", \"public, max-age=3600\");\n\n      console.log(\n        `Sending Arrow buffer: ${result.data.length} bytes for job ${jobId}`,\n      );\n      res.send(Buffer.from(result.data));\n    } catch (error) {\n      console.error(`Arrow job error for ${this.name}:`, error);\n      res.status(404).json({\n        error: error instanceof Error ? error.message : \"Arrow job not found\",\n        plugin: this.name,\n      });\n    }\n  }\n\n  private async _handleQueryRoute(\n    req: Request,\n    res: Response,\n    { asUser = false }: { asUser?: boolean } = {},\n  ): Promise<void> {\n    const { query_key } = req.params;\n    const { parameters, format = \"JSON\" } = req.body as IAnalyticsQueryRequest;\n    const queryParameters =\n      format === \"ARROW\"\n        ? {\n            formatParameters: {\n              disposition: \"EXTERNAL_LINKS\",\n              format: \"ARROW_STREAM\",\n            },\n            type: \"arrow\",\n          }\n        : {\n            type: \"result\",\n          };\n\n    const requestContext = getRequestContext();\n    const userKey = asUser\n      ? requestContext.userId\n      : requestContext.serviceUserId;\n\n    if (!query_key) {\n      res.status(400).json({ error: \"query_key is required\" });\n      return;\n    }\n\n    const query = await this.app.getAppQuery(\n      query_key,\n      req,\n      this.devFileReader,\n    );\n\n    if (!query) {\n      res.status(404).json({ error: \"Query not found\" });\n      return;\n    }\n\n    const hashedQuery = this.queryProcessor.hashQuery(query);\n\n    const defaultConfig: PluginExecuteConfig = {\n      ...queryDefaults,\n      cache: {\n        ...queryDefaults.cache,\n        cacheKey: [\n          \"analytics:query\",\n          query_key,\n          JSON.stringify(parameters),\n          JSON.stringify(format),\n          hashedQuery,\n          userKey,\n        ],\n      },\n    };\n\n    const streamExecutionSettings: StreamExecutionSettings = {\n      default: defaultConfig,\n    };\n\n    await this.executeStream(\n      res,\n      async (signal) => {\n        const processedParams = await this.queryProcessor.processQueryParams(\n          query,\n          parameters,\n        );\n\n        const result = await this.query(\n          query,\n          processedParams,\n          queryParameters.formatParameters,\n          signal,\n          {\n            asUser,\n          },\n        );\n\n        return { type: queryParameters.type, ...result };\n      },\n      streamExecutionSettings,\n      userKey,\n    );\n  }\n\n  async query(\n    query: string,\n    parameters?: Record<string, SQLTypeMarker | null | undefined>,\n    formatParameters?: Record<string, any>,\n    signal?: AbortSignal,\n    { asUser = false }: { asUser?: boolean } = {},\n  ): Promise<any> {\n    const requestContext = getRequestContext();\n    const workspaceClient = getWorkspaceClient(asUser);\n\n    const { statement, parameters: sqlParameters } =\n      this.queryProcessor.convertToSQLParameters(query, parameters);\n\n    const response = await this.SQLClient.executeStatement(\n      workspaceClient,\n      {\n        statement,\n        warehouse_id: await requestContext.warehouseId,\n        parameters: sqlParameters,\n        ...formatParameters,\n      },\n      signal,\n    );\n\n    return response.result;\n  }\n\n  // If we need arrow stream in more plugins we can define this as a base method in the core plugin class\n  // and have a generic endpoint for each plugin that consumes this arrow data.\n  protected async getArrowData(\n    workspaceClient: WorkspaceClient,\n    jobId: string,\n    signal?: AbortSignal,\n  ): Promise<ReturnType<typeof this.SQLClient.getArrowData>> {\n    return await this.SQLClient.getArrowData(workspaceClient, jobId, signal);\n  }\n\n  async shutdown(): Promise<void> {\n    this.streamManager.abortAll();\n  }\n}\n\nexport const analytics = toPlugin<\n  typeof AnalyticsPlugin,\n  IAnalyticsConfig,\n  \"analytics\"\n>(AnalyticsPlugin, \"analytics\");\n"],"mappings":"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"}

package/dist/analytics/defaults.js

@@ -0,0 +1,17 @@
+//#region src/analytics/defaults.ts
+const queryDefaults = {
+	cache: {
+		enabled: true,
+		ttl: 3600
+	},
+	retry: {
+		enabled: true,
+		initialDelay: 1500,
+		attempts: 3
+	},
+	timeout: 18e3
+};
+
+//#endregion
+export { queryDefaults };
+//# sourceMappingURL=defaults.js.map

package/dist/analytics/defaults.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"defaults.js","names":["queryDefaults: PluginExecuteConfig"],"sources":["../../src/analytics/defaults.ts"],"sourcesContent":["import type { PluginExecuteConfig } from \"shared\";\n\nexport const queryDefaults: PluginExecuteConfig = {\n  cache: {\n    enabled: true,\n    ttl: 3600,\n  },\n  retry: {\n    enabled: true,\n    initialDelay: 1500,\n    attempts: 3,\n  },\n  timeout: 18000,\n};\n"],"mappings":";AAEA,MAAaA,gBAAqC;CAChD,OAAO;EACL,SAAS;EACT,KAAK;EACN;CACD,OAAO;EACL,SAAS;EACT,cAAc;EACd,UAAU;EACX;CACD,SAAS;CACV"}

package/dist/analytics/index.js

@@ -0,0 +1,3 @@
+import { AnalyticsPlugin, analytics } from "./analytics.js";
+
+export {  };

package/dist/analytics/query.js

@@ -0,0 +1,50 @@
+import { isSQLTypeMarker, sql } from "../shared/src/sql/helpers.js";
+import { getRequestContext } from "../utils/databricks-client-middleware.js";
+import { init_utils } from "../utils/index.js";
+import { createHash } from "node:crypto";
+
+//#region src/analytics/query.ts
+init_utils();
+var QueryProcessor = class {
+	async processQueryParams(query, parameters) {
+		const processed = { ...parameters };
+		const paramMatches = query.matchAll(/:([a-zA-Z_]\w*)/g);
+		if (new Set(Array.from(paramMatches, (m) => m[1])).has("workspaceId") && !processed.workspaceId) {
+			const workspaceId = await getRequestContext().workspaceId;
+			if (workspaceId) processed.workspaceId = sql.string(workspaceId);
+		}
+		return processed;
+	}
+	hashQuery(query) {
+		return createHash("md5").update(query).digest("hex");
+	}
+	convertToSQLParameters(query, parameters) {
+		const sqlParameters = [];
+		if (parameters) {
+			const queryParamMatches = query.matchAll(/:([a-zA-Z_]\w*)/g);
+			const queryParams = new Set(Array.from(queryParamMatches, (m) => m[1]));
+			for (const key of Object.keys(parameters)) if (!queryParams.has(key)) throw new Error(`Parameter "${key}" not found in query. Valid parameters: ${Array.from(queryParams).join(", ") || "none"}`);
+			for (const [key, value] of Object.entries(parameters)) {
+				const parameter = this._createParameter(key, value);
+				if (parameter) sqlParameters.push(parameter);
+			}
+		}
+		return {
+			statement: query,
+			parameters: sqlParameters
+		};
+	}
+	_createParameter(key, value) {
+		if (value === null || value === void 0) return null;
+		if (!isSQLTypeMarker(value)) throw new Error(`Parameter "${key}" must be a SQL type. Use sql.string(), sql.number(), sql.date(), sql.timestamp(), or sql.boolean().`);
+		return {
+			name: key,
+			value: value.value,
+			type: value.__sql_type
+		};
+	}
+};
+
+//#endregion
+export { QueryProcessor };
+//# sourceMappingURL=query.js.map

package/dist/analytics/query.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"query.js","names":["sqlHelpers","sqlParameters: sql.StatementParameterListItem[]"],"sources":["../../src/analytics/query.ts"],"sourcesContent":["import { createHash } from \"node:crypto\";\nimport type { sql } from \"@databricks/sdk-experimental\";\nimport { isSQLTypeMarker, type SQLTypeMarker, sql as sqlHelpers } from \"shared\";\nimport { getRequestContext } from \"../utils\";\n\ntype SQLParameterValue = SQLTypeMarker | null | undefined;\n\nexport class QueryProcessor {\n  async processQueryParams(\n    query: string,\n    parameters?: Record<string, SQLParameterValue>,\n  ): Promise<Record<string, SQLParameterValue>> {\n    const processed = { ...parameters };\n\n    // extract all params from the query\n    const paramMatches = query.matchAll(/:([a-zA-Z_]\\w*)/g);\n    const queryParams = new Set(Array.from(paramMatches, (m) => m[1]));\n\n    // auto-inject workspaceId if needed and not provided\n    if (queryParams.has(\"workspaceId\") && !processed.workspaceId) {\n      const requestContext = getRequestContext();\n      const workspaceId = await requestContext.workspaceId;\n      if (workspaceId) {\n        processed.workspaceId = sqlHelpers.string(workspaceId);\n      }\n    }\n\n    return processed;\n  }\n\n  hashQuery(query: string): string {\n    return createHash(\"md5\").update(query).digest(\"hex\");\n  }\n\n  convertToSQLParameters(\n    query: string,\n    parameters?: Record<string, SQLParameterValue>,\n  ): { statement: string; parameters: sql.StatementParameterListItem[] } {\n    const sqlParameters: sql.StatementParameterListItem[] = [];\n\n    if (parameters) {\n      // extract all params from the query\n      const queryParamMatches = query.matchAll(/:([a-zA-Z_]\\w*)/g);\n      const queryParams = new Set(Array.from(queryParamMatches, (m) => m[1]));\n\n      // only allow parameters that exist in the query\n      for (const key of Object.keys(parameters)) {\n        if (!queryParams.has(key)) {\n          throw new Error(\n            `Parameter \"${key}\" not found in query. Valid parameters: ${\n              Array.from(queryParams).join(\", \") || \"none\"\n            }`,\n          );\n        }\n      }\n\n      // convert parameters to SQL parameters\n      for (const [key, value] of Object.entries(parameters)) {\n        const parameter = this._createParameter(key, value);\n        if (parameter) {\n          sqlParameters.push(parameter);\n        }\n      }\n    }\n\n    return { statement: query, parameters: sqlParameters };\n  }\n\n  private _createParameter(\n    key: string,\n    value: SQLParameterValue,\n  ): sql.StatementParameterListItem | null {\n    if (value === null || value === undefined) {\n      return null;\n    }\n\n    if (!isSQLTypeMarker(value)) {\n      throw new Error(\n        `Parameter \"${key}\" must be a SQL type. Use sql.string(), sql.number(), sql.date(), sql.timestamp(), or sql.boolean().`,\n      );\n    }\n\n    return {\n      name: key,\n      value: value.value,\n      type: value.__sql_type,\n    };\n  }\n}\n"],"mappings":";;;;;;YAG6C;AAI7C,IAAa,iBAAb,MAA4B;CAC1B,MAAM,mBACJ,OACA,YAC4C;EAC5C,MAAM,YAAY,EAAE,GAAG,YAAY;EAGnC,MAAM,eAAe,MAAM,SAAS,mBAAmB;AAIvD,MAHoB,IAAI,IAAI,MAAM,KAAK,eAAe,MAAM,EAAE,GAAG,CAAC,CAGlD,IAAI,cAAc,IAAI,CAAC,UAAU,aAAa;GAE5D,MAAM,cAAc,MADG,mBAAmB,CACD;AACzC,OAAI,YACF,WAAU,cAAcA,IAAW,OAAO,YAAY;;AAI1D,SAAO;;CAGT,UAAU,OAAuB;AAC/B,SAAO,WAAW,MAAM,CAAC,OAAO,MAAM,CAAC,OAAO,MAAM;;CAGtD,uBACE,OACA,YACqE;EACrE,MAAMC,gBAAkD,EAAE;AAE1D,MAAI,YAAY;GAEd,MAAM,oBAAoB,MAAM,SAAS,mBAAmB;GAC5D,MAAM,cAAc,IAAI,IAAI,MAAM,KAAK,oBAAoB,MAAM,EAAE,GAAG,CAAC;AAGvE,QAAK,MAAM,OAAO,OAAO,KAAK,WAAW,CACvC,KAAI,CAAC,YAAY,IAAI,IAAI,CACvB,OAAM,IAAI,MACR,cAAc,IAAI,0CAChB,MAAM,KAAK,YAAY,CAAC,KAAK,KAAK,IAAI,SAEzC;AAKL,QAAK,MAAM,CAAC,KAAK,UAAU,OAAO,QAAQ,WAAW,EAAE;IACrD,MAAM,YAAY,KAAK,iBAAiB,KAAK,MAAM;AACnD,QAAI,UACF,eAAc,KAAK,UAAU;;;AAKnC,SAAO;GAAE,WAAW;GAAO,YAAY;GAAe;;CAGxD,AAAQ,iBACN,KACA,OACuC;AACvC,MAAI,UAAU,QAAQ,UAAU,OAC9B,QAAO;AAGT,MAAI,CAAC,gBAAgB,MAAM,CACzB,OAAM,IAAI,MACR,cAAc,IAAI,sGACnB;AAGH,SAAO;GACL,MAAM;GACN,OAAO,MAAM;GACb,MAAM,MAAM;GACb"}

package/dist/analytics/types.d.ts

@@ -0,0 +1,9 @@
+import { BasePluginConfig } from "../shared/src/plugin.js";
+
+//#region src/analytics/types.d.ts
+interface IAnalyticsConfig extends BasePluginConfig {
+  timeout?: number;
+}
+//#endregion
+export { IAnalyticsConfig };
+//# sourceMappingURL=types.d.ts.map

package/dist/analytics/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","names":[],"sources":["../../src/analytics/types.ts"],"sourcesContent":[],"mappings":";;;UAEiB,gBAAA,SAAyB;;AAA1C"}

package/dist/app/index.d.ts

@@ -0,0 +1,23 @@
+//#region src/app/index.d.ts
+interface RequestLike {
+  query?: Record<string, any>;
+  headers: Record<string, string | string[] | undefined>;
+}
+interface DevFileReader {
+  readFile(filePath: string, req: RequestLike): Promise<string>;
+}
+declare class AppManager {
+  /**
+   * Retrieves a query file by key from the queries directory
+   * In dev mode with a request context, reads from local filesystem via WebSocket
+   * @param queryKey - The query file name (without extension)
+   * @param req - Optional request object to detect dev mode
+   * @param devFileReader - Optional DevFileReader instance to read files from local filesystem
+   * @returns The query content as a string
+   * @throws Error if query key is invalid or file not found
+   */
+  getAppQuery(queryKey: string, req?: RequestLike, devFileReader?: DevFileReader): Promise<string | null>;
+}
+//#endregion
+export { AppManager };
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","names":[],"sources":["../../src/app/index.ts"],"sourcesContent":[],"mappings":";UAGU,WAAA;EAAA,KAAA,CAAA,EACA,MADW,CAAA,MAAA,EAAA,GAAA,CAAA;EAAA,OAAA,EAEV,MAFU,CAAA,MAAA,EAAA,MAAA,GAAA,MAAA,EAAA,GAAA,SAAA,CAAA;;UAKX,aAAA,CAHC;EAAM,QAAA,CAAA,QAAA,EAAA,MAAA,EAAA,GAAA,EAIiB,WAJjB,CAAA,EAI+B,OAJ/B,CAAA,MAAA,CAAA;AAAA;AAGM,cAIV,UAAA,CAJU;;;;AAIvB;;;;;;sCAYU,6BACU,gBACf"}

package/dist/app/index.js

@@ -0,0 +1,49 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+
+//#region src/app/index.ts
+var AppManager = class {
+	/**
+	* Retrieves a query file by key from the queries directory
+	* In dev mode with a request context, reads from local filesystem via WebSocket
+	* @param queryKey - The query file name (without extension)
+	* @param req - Optional request object to detect dev mode
+	* @param devFileReader - Optional DevFileReader instance to read files from local filesystem
+	* @returns The query content as a string
+	* @throws Error if query key is invalid or file not found
+	*/
+	async getAppQuery(queryKey, req, devFileReader) {
+		if (!queryKey || !/^[a-zA-Z0-9_-]+$/.test(queryKey)) {
+			console.error(`Invalid query key format: "${queryKey}". Only alphanumeric characters, underscores, and hyphens are allowed.`);
+			return null;
+		}
+		const queryFilePath = path.join(process.cwd(), "config/queries", `${queryKey}.sql`);
+		const resolvedPath = path.resolve(queryFilePath);
+		const queriesDir = path.resolve(process.cwd(), "config/queries");
+		if (!resolvedPath.startsWith(queriesDir)) {
+			console.error(`Invalid query path: path traversal detected`);
+			return null;
+		}
+		if (req?.query?.dev !== void 0 && devFileReader && req) try {
+			const relativePath = path.relative(process.cwd(), resolvedPath);
+			return await devFileReader.readFile(relativePath, req);
+		} catch (error) {
+			console.error(`Failed to read query "${queryKey}" from dev tunnel: ${error.message}`);
+			return null;
+		}
+		try {
+			return await fs.readFile(resolvedPath, "utf8");
+		} catch (error) {
+			if (error.code === "ENOENT") {
+				console.error(`Query "${queryKey}" not found at path: ${resolvedPath}`);
+				return null;
+			}
+			console.error(`Failed to read query "${queryKey}" from server filesystem: ${error.message}`);
+			return null;
+		}
+	}
+};
+
+//#endregion
+export { AppManager };
+//# sourceMappingURL=index.js.map

package/dist/app/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":[],"sources":["../../src/app/index.ts"],"sourcesContent":["import fs from \"node:fs/promises\";\nimport path from \"node:path\";\n\ninterface RequestLike {\n  query?: Record<string, any>;\n  headers: Record<string, string | string[] | undefined>;\n}\n\ninterface DevFileReader {\n  readFile(filePath: string, req: RequestLike): Promise<string>;\n}\n\nexport class AppManager {\n  /**\n   * Retrieves a query file by key from the queries directory\n   * In dev mode with a request context, reads from local filesystem via WebSocket\n   * @param queryKey - The query file name (without extension)\n   * @param req - Optional request object to detect dev mode\n   * @param devFileReader - Optional DevFileReader instance to read files from local filesystem\n   * @returns The query content as a string\n   * @throws Error if query key is invalid or file not found\n   */\n  async getAppQuery(\n    queryKey: string,\n    req?: RequestLike,\n    devFileReader?: DevFileReader,\n  ): Promise<string | null> {\n    // Security: Sanitize query key to prevent path traversal\n    if (!queryKey || !/^[a-zA-Z0-9_-]+$/.test(queryKey)) {\n      console.error(\n        `Invalid query key format: \"${queryKey}\". Only alphanumeric characters, underscores, and hyphens are allowed.`,\n      );\n      return null;\n    }\n\n    const queryFilePath = path.join(\n      process.cwd(),\n      \"config/queries\",\n      `${queryKey}.sql`,\n    );\n\n    // Security: Validate resolved path is within queries directory\n    const resolvedPath = path.resolve(queryFilePath);\n    const queriesDir = path.resolve(process.cwd(), \"config/queries\");\n\n    if (!resolvedPath.startsWith(queriesDir)) {\n      console.error(`Invalid query path: path traversal detected`);\n      return null;\n    }\n\n    // Check if we're in dev mode and should use WebSocket\n    const isDevMode = req?.query?.dev !== undefined;\n\n    if (isDevMode && devFileReader && req) {\n      try {\n        // Read from local filesystem via WebSocket tunnel\n        const relativePath = path.relative(process.cwd(), resolvedPath);\n        return await devFileReader.readFile(relativePath, req);\n      } catch (error) {\n        console.error(\n          `Failed to read query \"${queryKey}\" from dev tunnel: ${(error as Error).message}`,\n        );\n        return null;\n      }\n    }\n\n    // Production mode: read from server filesystem\n    try {\n      const query = await fs.readFile(resolvedPath, \"utf8\");\n      return query;\n    } catch (error) {\n      if ((error as NodeJS.ErrnoException).code === \"ENOENT\") {\n        console.error(`Query \"${queryKey}\" not found at path: ${resolvedPath}`);\n        return null;\n      }\n      console.error(\n        `Failed to read query \"${queryKey}\" from server filesystem: ${(error as Error).message}`,\n      );\n      return null;\n    }\n  }\n}\n\nexport type { DevFileReader, RequestLike };\n"],"mappings":";;;;AAYA,IAAa,aAAb,MAAwB;;;;;;;;;;CAUtB,MAAM,YACJ,UACA,KACA,eACwB;AAExB,MAAI,CAAC,YAAY,CAAC,mBAAmB,KAAK,SAAS,EAAE;AACnD,WAAQ,MACN,8BAA8B,SAAS,wEACxC;AACD,UAAO;;EAGT,MAAM,gBAAgB,KAAK,KACzB,QAAQ,KAAK,EACb,kBACA,GAAG,SAAS,MACb;EAGD,MAAM,eAAe,KAAK,QAAQ,cAAc;EAChD,MAAM,aAAa,KAAK,QAAQ,QAAQ,KAAK,EAAE,iBAAiB;AAEhE,MAAI,CAAC,aAAa,WAAW,WAAW,EAAE;AACxC,WAAQ,MAAM,8CAA8C;AAC5D,UAAO;;AAMT,MAFkB,KAAK,OAAO,QAAQ,UAErB,iBAAiB,IAChC,KAAI;GAEF,MAAM,eAAe,KAAK,SAAS,QAAQ,KAAK,EAAE,aAAa;AAC/D,UAAO,MAAM,cAAc,SAAS,cAAc,IAAI;WAC/C,OAAO;AACd,WAAQ,MACN,yBAAyB,SAAS,qBAAsB,MAAgB,UACzE;AACD,UAAO;;AAKX,MAAI;AAEF,UADc,MAAM,GAAG,SAAS,cAAc,OAAO;WAE9C,OAAO;AACd,OAAK,MAAgC,SAAS,UAAU;AACtD,YAAQ,MAAM,UAAU,SAAS,uBAAuB,eAAe;AACvE,WAAO;;AAET,WAAQ,MACN,yBAAyB,SAAS,4BAA6B,MAAgB,UAChF;AACD,UAAO"}

package/dist/appkit/package.js

@@ -0,0 +1,7 @@
+//#region package.json
+var name = "@databricks/appkit";
+var version = "0.0.2";
+
+//#endregion
+export { name, version };
+//# sourceMappingURL=package.js.map

package/dist/appkit/package.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"package.js","names":[],"sources":["../../package.json"],"sourcesContent":[""],"mappings":""}

package/dist/cache/defaults.js

@@ -0,0 +1,14 @@
+//#region src/cache/defaults.ts
+/** Default configuration for cache */
+const cacheDefaults = {
+	enabled: true,
+	ttl: 3600,
+	maxSize: 1e3,
+	cacheKey: [],
+	cleanupProbability: .01,
+	strictPersistence: false
+};
+
+//#endregion
+export { cacheDefaults };
+//# sourceMappingURL=defaults.js.map

package/dist/cache/defaults.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"defaults.js","names":["cacheDefaults: CacheConfig"],"sources":["../../src/cache/defaults.ts"],"sourcesContent":["import type { CacheConfig } from \"shared\";\n\n/** Default configuration for cache */\nexport const cacheDefaults: CacheConfig = {\n  enabled: true,\n  ttl: 3600, // 1 hour\n  maxSize: 1000, // 1000 entries\n  cacheKey: [], // no cache key by default\n  cleanupProbability: 0.01, // 1% probability of triggering cleanup on each get operation\n  strictPersistence: false, // if false, use in-memory storage if lakebase is unavailable\n};\n"],"mappings":";;AAGA,MAAaA,gBAA6B;CACxC,SAAS;CACT,KAAK;CACL,SAAS;CACT,UAAU,EAAE;CACZ,oBAAoB;CACpB,mBAAmB;CACpB"}

package/dist/cache/index.d.ts

@@ -0,0 +1,119 @@
+import { CacheConfig } from "../shared/src/cache.js";
+
+//#region src/cache/index.d.ts
+
+/**
+ * Cache manager class to handle cache operations.
+ * Can be used with in-memory storage or persistent storage (Lakebase).
+ *
+ * The cache is automatically initialized by AppKit. Use `getInstanceSync()` to access
+ * the singleton instance after initialization.
+ *
+ * @example
+ * ```typescript
+ * const cache = CacheManager.getInstanceSync();
+ * const result = await cache.getOrExecute(["users", userId], () => fetchUser(userId), userKey);
+ * ```
+ */
+declare class CacheManager {
+  private static readonly MIN_CLEANUP_INTERVAL_MS;
+  private readonly name;
+  private static instance;
+  private static initPromise;
+  private storage;
+  private config;
+  private inFlightRequests;
+  private cleanupInProgress;
+  private lastCleanupAttempt;
+  private telemetry;
+  private telemetryMetrics;
+  private constructor();
+  /**
+   * Get the singleton instance of the cache manager (sync version).
+   *
+   * Throws if not initialized - ensure AppKit.create() has completed first.
+   * @returns CacheManager instance
+   */
+  static getInstanceSync(): CacheManager;
+  /**
+   * Initialize and get the singleton instance of the cache manager.
+   * Called internally by AppKit - prefer `getInstanceSync()` for plugin access.
+   * @param userConfig - User configuration for the cache manager
+   * @returns CacheManager instance
+   * @internal
+   */
+  static getInstance(userConfig?: Partial<CacheConfig>): Promise<CacheManager>;
+  /**
+   * Create a new cache manager instance
+   *
+   * Storage selection logic:
+   * 1. If `storage` provided and healthy → use provided storage
+   * 2. If `storage` provided but unhealthy → fallback to InMemory (or disable if strictPersistence)
+   * 3. If no `storage` provided and Lakebase available → use Lakebase
+   * 4. If no `storage` provided and Lakebase unavailable → fallback to InMemory (or disable if strictPersistence)
+   *
+   * @param userConfig - User configuration for the cache manager
+   * @returns CacheManager instance
+   */
+  private static create;
+  /**
+   * Get or execute a function and cache the result
+   * @param key - Cache key
+   * @param fn - Function to execute
+   * @param userKey - User key
+   * @param options - Options for the cache
+   * @returns Promise of the result
+   */
+  getOrExecute<T>(key: (string | number | object)[], fn: () => Promise<T>, userKey: string, options?: {
+    ttl?: number;
+  }): Promise<T>;
+  /**
+   * Get a cached value
+   * @param key - Cache key
+   * @returns Promise of the value or null if not found or expired
+   */
+  get<T>(key: string): Promise<T | null>;
+  /** Probabilistically trigger cleanup of expired entries (fire-and-forget) */
+  private maybeCleanup;
+  /**
+   * Set a value in the cache
+   * @param key - Cache key
+   * @param value - Value to set
+   * @param options - Options for the cache
+   * @returns Promise of the result
+   */
+  set<T>(key: string, value: T, options?: {
+    ttl?: number;
+  }): Promise<void>;
+  /**
+   * Delete a value from the cache
+   * @param key - Cache key
+   * @returns Promise of the result
+   */
+  delete(key: string): Promise<void>;
+  /** Clear the cache */
+  clear(): Promise<void>;
+  /**
+   * Check if a value exists in the cache
+   * @param key - Cache key
+   * @returns Promise of true if the value exists, false otherwise
+   */
+  has(key: string): Promise<boolean>;
+  /**
+   * Generate a cache key
+   * @param parts - Parts of the key
+   * @param userKey - User key
+   * @returns Cache key
+   */
+  generateKey(parts: (string | number | object)[], userKey: string): string;
+  /** Close the cache */
+  close(): Promise<void>;
+  /**
+   * Check if the storage is healthy
+   * @returns Promise of true if the storage is healthy, false otherwise
+   */
+  isStorageHealthy(): Promise<boolean>;
+}
+//#endregion
+export { CacheManager };
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","names":[],"sources":["../../src/cache/index.ts"],"sourcesContent":[],"mappings":";;;;;;AAuBA;;;;;;;;;;;AAwQqC,cAxQxB,YAAA,CAwQwB;0BAAR,uBAAA;mBAkDlB,IAAA;iBAEN,QAAA;iBAawB,WAAA;UAMZ,OAAA;UAUS,MAAA;UA0BT,gBAAA;UAQW,iBAAA;EAAO,QAAA,kBAAA;;;;;;;;;;4BA3UP;;;;;;;;kCAkBX,QAAQ,eACpB,QAAQ;;;;;;;;;;;;;;;;;;;;;;+DAuGC,QAAQ;;MAGjB,QAAQ;;;;;;uBA2FgB,QAAQ;;;;;;;;;;6BAkD1B;;MAEN;;;;;;uBAawB;;WAMZ;;;;;;oBAUS;;;;;;;;;WA0BT;;;;;sBAQW"}