@databricks/appkit 0.1.4 → 0.2.0

package/dist/errors/server.js

@@ -0,0 +1,45 @@
+import { __esmMin } from "../_virtual/rolldown_runtime.js";
+import { AppKitError, init_base } from "./base.js";
+
+//#region src/errors/server.ts
+var ServerError;
+var init_server = __esmMin((() => {
+	init_base();
+	ServerError = class ServerError extends AppKitError {
+		constructor(..._args) {
+			super(..._args);
+			this.code = "SERVER_ERROR";
+			this.statusCode = 500;
+			this.isRetryable = false;
+		}
+		/**
+		* Create a server error for autoStart conflict
+		*/
+		static autoStartConflict(operation) {
+			return new ServerError(`Cannot ${operation} when autoStart is true`, { context: { operation } });
+		}
+		/**
+		* Create a server error for server not started
+		*/
+		static notStarted() {
+			return new ServerError("Server not started. Please start the server first by calling the start() method");
+		}
+		/**
+		* Create a server error for Vite dev server not initialized
+		*/
+		static viteNotInitialized() {
+			return new ServerError("Vite dev server not initialized");
+		}
+		/**
+		* Create a server error for missing client directory
+		*/
+		static clientDirectoryNotFound(searchedPaths) {
+			return new ServerError(`Could not find client directory. Searched for vite.config.ts/js + index.html in: ${searchedPaths.join(", ")}`, { context: { searchedPaths } });
+		}
+	};
+}));
+
+//#endregion
+init_server();
+export { ServerError, init_server };
+//# sourceMappingURL=server.js.map

package/dist/errors/server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.js","names":[],"sources":["../../src/errors/server.ts"],"sourcesContent":["import { AppKitError } from \"./base\";\n\n/**\n * Error thrown when server lifecycle operations fail.\n * Use for server start/stop issues, configuration conflicts, etc.\n *\n * @example\n * ```typescript\n * throw new ServerError(\"Cannot get server when autoStart is true\");\n * throw new ServerError(\"Server not started\");\n * ```\n */\nexport class ServerError extends AppKitError {\n  readonly code = \"SERVER_ERROR\";\n  readonly statusCode = 500;\n  readonly isRetryable = false;\n\n  /**\n   * Create a server error for autoStart conflict\n   */\n  static autoStartConflict(operation: string): ServerError {\n    return new ServerError(`Cannot ${operation} when autoStart is true`, {\n      context: { operation },\n    });\n  }\n\n  /**\n   * Create a server error for server not started\n   */\n  static notStarted(): ServerError {\n    return new ServerError(\n      \"Server not started. Please start the server first by calling the start() method\",\n    );\n  }\n\n  /**\n   * Create a server error for Vite dev server not initialized\n   */\n  static viteNotInitialized(): ServerError {\n    return new ServerError(\"Vite dev server not initialized\");\n  }\n\n  /**\n   * Create a server error for missing client directory\n   */\n  static clientDirectoryNotFound(searchedPaths: string[]): ServerError {\n    return new ServerError(\n      `Could not find client directory. Searched for vite.config.ts/js + index.html in: ${searchedPaths.join(\", \")}`,\n      { context: { searchedPaths } },\n    );\n  }\n}\n"],"mappings":";;;;;;YAAqC;CAYxB,cAAb,MAAa,oBAAoB,YAAY;;;eAC3B;qBACM;sBACC;;;;;EAKvB,OAAO,kBAAkB,WAAgC;AACvD,UAAO,IAAI,YAAY,UAAU,UAAU,0BAA0B,EACnE,SAAS,EAAE,WAAW,EACvB,CAAC;;;;;EAMJ,OAAO,aAA0B;AAC/B,UAAO,IAAI,YACT,kFACD;;;;;EAMH,OAAO,qBAAkC;AACvC,UAAO,IAAI,YAAY,kCAAkC;;;;;EAM3D,OAAO,wBAAwB,eAAsC;AACnE,UAAO,IAAI,YACT,oFAAoF,cAAc,KAAK,KAAK,IAC5G,EAAE,SAAS,EAAE,eAAe,EAAE,CAC/B"}

package/dist/errors/tunnel.d.ts

@@ -0,0 +1,38 @@
+import { AppKitError } from "./base.js";
+
+//#region src/errors/tunnel.d.ts
+
+/**
+ * Error thrown when remote tunnel operations fail.
+ * Use for tunnel connection issues, message parsing failures, etc.
+ *
+ * @example
+ * ```typescript
+ * throw new TunnelError("No tunnel connection available");
+ * throw new TunnelError("Failed to parse WebSocket message", { cause: parseError });
+ * ```
+ */
+declare class TunnelError extends AppKitError {
+  readonly code = "TUNNEL_ERROR";
+  readonly statusCode = 502;
+  readonly isRetryable = true;
+  /**
+   * Create a tunnel error for missing tunnel getter
+   */
+  static getterNotRegistered(): TunnelError;
+  /**
+   * Create a tunnel error for no available connection
+   */
+  static noConnection(): TunnelError;
+  /**
+   * Create a tunnel error for asset fetch failure
+   */
+  static fetchFailed(path: string, cause?: Error): TunnelError;
+  /**
+   * Create a tunnel error for message parsing failure
+   */
+  static parseError(messageType: string, cause?: Error): TunnelError;
+}
+//#endregion
+export { TunnelError };
+//# sourceMappingURL=tunnel.d.ts.map

package/dist/errors/tunnel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tunnel.d.ts","names":[],"sources":["../../src/errors/tunnel.ts"],"sourcesContent":[],"mappings":";;;;;;AAYA;;;;;;;;AAAiC,cAApB,WAAA,SAAoB,WAAA,CAAA;EAAW,SAAA,IAAA,GAAA,cAAA;;;;;;gCAQZ;;;;yBASP;;;;2CAOkB,QAAQ;;;;iDAUF,QAAQ"}

package/dist/errors/tunnel.js

@@ -0,0 +1,51 @@
+import { __esmMin } from "../_virtual/rolldown_runtime.js";
+import { AppKitError, init_base } from "./base.js";
+
+//#region src/errors/tunnel.ts
+var TunnelError;
+var init_tunnel = __esmMin((() => {
+	init_base();
+	TunnelError = class TunnelError extends AppKitError {
+		constructor(..._args) {
+			super(..._args);
+			this.code = "TUNNEL_ERROR";
+			this.statusCode = 502;
+			this.isRetryable = true;
+		}
+		/**
+		* Create a tunnel error for missing tunnel getter
+		*/
+		static getterNotRegistered() {
+			return new TunnelError("Tunnel getter not registered for DevFileReader singleton");
+		}
+		/**
+		* Create a tunnel error for no available connection
+		*/
+		static noConnection() {
+			return new TunnelError("No tunnel connection available for file read");
+		}
+		/**
+		* Create a tunnel error for asset fetch failure
+		*/
+		static fetchFailed(path, cause) {
+			return new TunnelError("Failed to fetch asset", {
+				cause,
+				context: { path }
+			});
+		}
+		/**
+		* Create a tunnel error for message parsing failure
+		*/
+		static parseError(messageType, cause) {
+			return new TunnelError(`Failed to parse ${messageType} message`, {
+				cause,
+				context: { messageType }
+			});
+		}
+	};
+}));
+
+//#endregion
+init_tunnel();
+export { TunnelError, init_tunnel };
+//# sourceMappingURL=tunnel.js.map

package/dist/errors/tunnel.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tunnel.js","names":[],"sources":["../../src/errors/tunnel.ts"],"sourcesContent":["import { AppKitError } from \"./base\";\n\n/**\n * Error thrown when remote tunnel operations fail.\n * Use for tunnel connection issues, message parsing failures, etc.\n *\n * @example\n * ```typescript\n * throw new TunnelError(\"No tunnel connection available\");\n * throw new TunnelError(\"Failed to parse WebSocket message\", { cause: parseError });\n * ```\n */\nexport class TunnelError extends AppKitError {\n  readonly code = \"TUNNEL_ERROR\";\n  readonly statusCode = 502;\n  readonly isRetryable = true;\n\n  /**\n   * Create a tunnel error for missing tunnel getter\n   */\n  static getterNotRegistered(): TunnelError {\n    return new TunnelError(\n      \"Tunnel getter not registered for DevFileReader singleton\",\n    );\n  }\n\n  /**\n   * Create a tunnel error for no available connection\n   */\n  static noConnection(): TunnelError {\n    return new TunnelError(\"No tunnel connection available for file read\");\n  }\n\n  /**\n   * Create a tunnel error for asset fetch failure\n   */\n  static fetchFailed(path: string, cause?: Error): TunnelError {\n    return new TunnelError(\"Failed to fetch asset\", {\n      cause,\n      context: { path },\n    });\n  }\n\n  /**\n   * Create a tunnel error for message parsing failure\n   */\n  static parseError(messageType: string, cause?: Error): TunnelError {\n    return new TunnelError(`Failed to parse ${messageType} message`, {\n      cause,\n      context: { messageType },\n    });\n  }\n}\n"],"mappings":";;;;;;YAAqC;CAYxB,cAAb,MAAa,oBAAoB,YAAY;;;eAC3B;qBACM;sBACC;;;;;EAKvB,OAAO,sBAAmC;AACxC,UAAO,IAAI,YACT,2DACD;;;;;EAMH,OAAO,eAA4B;AACjC,UAAO,IAAI,YAAY,+CAA+C;;;;;EAMxE,OAAO,YAAY,MAAc,OAA4B;AAC3D,UAAO,IAAI,YAAY,yBAAyB;IAC9C;IACA,SAAS,EAAE,MAAM;IAClB,CAAC;;;;;EAMJ,OAAO,WAAW,aAAqB,OAA4B;AACjE,UAAO,IAAI,YAAY,mBAAmB,YAAY,WAAW;IAC/D;IACA,SAAS,EAAE,aAAa;IACzB,CAAC"}

package/dist/errors/validation.d.ts

@@ -0,0 +1,36 @@
+import { AppKitError } from "./base.js";
+
+//#region src/errors/validation.d.ts
+
+/**
+ * Error thrown when input validation fails.
+ * Use for invalid parameters, missing required fields, or type mismatches.
+ *
+ * @example
+ * ```typescript
+ * throw new ValidationError("Statement is required", { context: { field: "statement" } });
+ * throw new ValidationError("maxPoolSize must be at least 1", { context: { value: config.maxPoolSize } });
+ * ```
+ */
+declare class ValidationError extends AppKitError {
+  readonly code = "VALIDATION_ERROR";
+  readonly statusCode = 400;
+  readonly isRetryable = false;
+  /**
+   * Create a validation error for a missing required field
+   */
+  static missingField(fieldName: string): ValidationError;
+  /**
+   * Create a validation error for an invalid field value.
+   * Note: The actual value is not stored in context for security reasons.
+   * Only the value's type is recorded.
+   */
+  static invalidValue(fieldName: string, value: unknown, expected?: string): ValidationError;
+  /**
+   * Create a validation error for missing environment variables
+   */
+  static missingEnvVars(vars: string[]): ValidationError;
+}
+//#endregion
+export { ValidationError };
+//# sourceMappingURL=validation.d.ts.map

package/dist/errors/validation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation.d.ts","names":[],"sources":["../../src/errors/validation.ts"],"sourcesContent":[],"mappings":";;;;;;AAYA;;;;;;;;cAAa,eAAA,SAAwB,WAAA;;;;;;;0CAQK;;;;;;6EAerC;;;;yCAgBoC"}

package/dist/errors/validation.js

@@ -0,0 +1,45 @@
+import { __esmMin } from "../_virtual/rolldown_runtime.js";
+import { AppKitError, init_base } from "./base.js";
+
+//#region src/errors/validation.ts
+var ValidationError;
+var init_validation = __esmMin((() => {
+	init_base();
+	ValidationError = class ValidationError extends AppKitError {
+		constructor(..._args) {
+			super(..._args);
+			this.code = "VALIDATION_ERROR";
+			this.statusCode = 400;
+			this.isRetryable = false;
+		}
+		/**
+		* Create a validation error for a missing required field
+		*/
+		static missingField(fieldName) {
+			return new ValidationError(`Missing required field: ${fieldName}`, { context: { field: fieldName } });
+		}
+		/**
+		* Create a validation error for an invalid field value.
+		* Note: The actual value is not stored in context for security reasons.
+		* Only the value's type is recorded.
+		*/
+		static invalidValue(fieldName, value, expected) {
+			return new ValidationError(expected ? `Invalid value for ${fieldName}: expected ${expected}` : `Invalid value for ${fieldName}`, { context: {
+				field: fieldName,
+				valueType: value === null ? "null" : typeof value,
+				expected
+			} });
+		}
+		/**
+		* Create a validation error for missing environment variables
+		*/
+		static missingEnvVars(vars) {
+			return new ValidationError(`Missing required environment variables: ${vars.join(", ")}`, { context: { missingVars: vars } });
+		}
+	};
+}));
+
+//#endregion
+init_validation();
+export { ValidationError, init_validation };
+//# sourceMappingURL=validation.js.map

package/dist/errors/validation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation.js","names":[],"sources":["../../src/errors/validation.ts"],"sourcesContent":["import { AppKitError } from \"./base\";\n\n/**\n * Error thrown when input validation fails.\n * Use for invalid parameters, missing required fields, or type mismatches.\n *\n * @example\n * ```typescript\n * throw new ValidationError(\"Statement is required\", { context: { field: \"statement\" } });\n * throw new ValidationError(\"maxPoolSize must be at least 1\", { context: { value: config.maxPoolSize } });\n * ```\n */\nexport class ValidationError extends AppKitError {\n  readonly code = \"VALIDATION_ERROR\";\n  readonly statusCode = 400;\n  readonly isRetryable = false;\n\n  /**\n   * Create a validation error for a missing required field\n   */\n  static missingField(fieldName: string): ValidationError {\n    return new ValidationError(`Missing required field: ${fieldName}`, {\n      context: { field: fieldName },\n    });\n  }\n\n  /**\n   * Create a validation error for an invalid field value.\n   * Note: The actual value is not stored in context for security reasons.\n   * Only the value's type is recorded.\n   */\n  static invalidValue(\n    fieldName: string,\n    value: unknown,\n    expected?: string,\n  ): ValidationError {\n    const msg = expected\n      ? `Invalid value for ${fieldName}: expected ${expected}`\n      : `Invalid value for ${fieldName}`;\n    return new ValidationError(msg, {\n      context: {\n        field: fieldName,\n        valueType: value === null ? \"null\" : typeof value,\n        expected,\n      },\n    });\n  }\n\n  /**\n   * Create a validation error for missing environment variables\n   */\n  static missingEnvVars(vars: string[]): ValidationError {\n    return new ValidationError(\n      `Missing required environment variables: ${vars.join(\", \")}`,\n      { context: { missingVars: vars } },\n    );\n  }\n}\n"],"mappings":";;;;;;YAAqC;CAYxB,kBAAb,MAAa,wBAAwB,YAAY;;;eAC/B;qBACM;sBACC;;;;;EAKvB,OAAO,aAAa,WAAoC;AACtD,UAAO,IAAI,gBAAgB,2BAA2B,aAAa,EACjE,SAAS,EAAE,OAAO,WAAW,EAC9B,CAAC;;;;;;;EAQJ,OAAO,aACL,WACA,OACA,UACiB;AAIjB,UAAO,IAAI,gBAHC,WACR,qBAAqB,UAAU,aAAa,aAC5C,qBAAqB,aACO,EAC9B,SAAS;IACP,OAAO;IACP,WAAW,UAAU,OAAO,SAAS,OAAO;IAC5C;IACD,EACF,CAAC;;;;;EAMJ,OAAO,eAAe,MAAiC;AACrD,UAAO,IAAI,gBACT,2CAA2C,KAAK,KAAK,KAAK,IAC1D,EAAE,SAAS,EAAE,aAAa,MAAM,EAAE,CACnC"}

package/dist/index.d.ts

@@ -1,15 +1,23 @@
 import { BasePluginConfig, IAppRouter } from "./shared/src/plugin.js";
+import { CacheConfig } from "./shared/src/cache.js";
 import { StreamExecutionSettings } from "./shared/src/execute.js";
-import { SQLTypeMarker } from "./shared/src/sql/types.js";
 import { isSQLTypeMarker, sql } from "./shared/src/sql/helpers.js";
 import { CacheManager } from "./cache/index.js";
-import { ITelemetry } from "./telemetry/types.js";
+import { ITelemetry, TelemetryConfig } from "./telemetry/types.js";
 import { Counter, Histogram, SeverityNumber, Span, SpanStatusCode } from "./telemetry/index.js";
 import { Plugin } from "./plugin/plugin.js";
 import { toPlugin } from "./plugin/to-plugin.js";
 import { analytics } from "./analytics/analytics.js";
 import { createApp } from "./core/appkit.js";
+import { AppKitError } from "./errors/base.js";
+import { AuthenticationError } from "./errors/authentication.js";
+import { ConfigurationError } from "./errors/configuration.js";
+import { ConnectionError } from "./errors/connection.js";
+import { ExecutionError } from "./errors/execution.js";
+import { InitializationError } from "./errors/initialization.js";
+import { ServerError } from "./errors/server.js";
+import { TunnelError } from "./errors/tunnel.js";
+import { ValidationError } from "./errors/validation.js";
 import { server } from "./server/index.js";
 import { appKitTypesPlugin } from "./type-generator/vite-plugin.js";
-import { getRequestContext } from "./utils/databricks-client-middleware.js";
-export { type BasePluginConfig, CacheManager, type Counter, type Histogram, type IAppRouter, type ITelemetry, Plugin, type SQLTypeMarker, SeverityNumber, type Span, SpanStatusCode, type StreamExecutionSettings, analytics, appKitTypesPlugin, createApp, getRequestContext, isSQLTypeMarker, server, sql, toPlugin };
+export { AppKitError, AuthenticationError, type BasePluginConfig, type CacheConfig, CacheManager, ConfigurationError, ConnectionError, type Counter, ExecutionError, type Histogram, type IAppRouter, type ITelemetry, InitializationError, Plugin, ServerError, SeverityNumber, type Span, SpanStatusCode, type StreamExecutionSettings, type TelemetryConfig, TunnelError, ValidationError, analytics, appKitTypesPlugin, createApp, isSQLTypeMarker, server, sql, toPlugin };

package/dist/index.js

@@ -1,7 +1,15 @@
 import { isSQLTypeMarker, sql } from "./shared/src/sql/helpers.js";
 import { SeverityNumber, SpanStatusCode } from "./telemetry/index.js";
-import { getRequestContext } from "./utils/databricks-client-middleware.js";
-import { init_utils } from "./utils/index.js";
+import { AppKitError } from "./errors/base.js";
+import { AuthenticationError } from "./errors/authentication.js";
+import { ConfigurationError } from "./errors/configuration.js";
+import { ConnectionError } from "./errors/connection.js";
+import { ExecutionError } from "./errors/execution.js";
+import { InitializationError } from "./errors/initialization.js";
+import { ServerError } from "./errors/server.js";
+import { TunnelError } from "./errors/tunnel.js";
+import { ValidationError } from "./errors/validation.js";
+import { init_errors } from "./errors/index.js";
 import { CacheManager } from "./cache/index.js";
 import { Plugin } from "./plugin/plugin.js";
 import { toPlugin } from "./plugin/to-plugin.js";
@@ -14,8 +22,8 @@ import { appKitTypesPlugin } from "./type-generator/vite-plugin.js";
 import { server } from "./server/index.js";
 
 //#region src/index.ts
-init_utils();
+init_errors();
 
 //#endregion
-export { CacheManager, Plugin, SeverityNumber, SpanStatusCode, analytics, appKitTypesPlugin, createApp, getRequestContext, isSQLTypeMarker, server, sql, toPlugin };
+export { AppKitError, AuthenticationError, CacheManager, ConfigurationError, ConnectionError, ExecutionError, InitializationError, Plugin, ServerError, SeverityNumber, SpanStatusCode, TunnelError, ValidationError, analytics, appKitTypesPlugin, createApp, isSQLTypeMarker, server, sql, toPlugin };
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","names":[],"sources":["../src/index.ts"],"sourcesContent":["export type {\n  BasePluginConfig,\n  IAppRouter,\n  SQLTypeMarker,\n  StreamExecutionSettings,\n} from \"shared\";\nexport {\n  isSQLTypeMarker,\n  sql,\n} from \"shared\";\nexport { analytics } from \"./analytics\";\nexport { CacheManager } from \"./cache\";\nexport { createApp } from \"./core\";\nexport { Plugin, toPlugin } from \"./plugin\";\nexport { server } from \"./server\";\nexport type { ITelemetry } from \"./telemetry\";\nexport {\n  type Counter,\n  type Histogram,\n  SeverityNumber,\n  type Span,\n  SpanStatusCode,\n} from \"./telemetry\";\nexport { appKitTypesPlugin } from \"./type-generator/vite-plugin\";\nexport { getRequestContext } from \"./utils\";\n"],"mappings":";;;;;;;;;;;;;;;;YAwB4C"}
+{"version":3,"file":"index.js","names":[],"sources":["../src/index.ts"],"sourcesContent":["// Types from shared\nexport type {\n  BasePluginConfig,\n  CacheConfig,\n  IAppRouter,\n  StreamExecutionSettings,\n} from \"shared\";\nexport { isSQLTypeMarker, sql } from \"shared\";\nexport { analytics } from \"./analytics\";\nexport { CacheManager } from \"./cache\";\nexport { createApp } from \"./core\";\n// Errors\nexport {\n  AppKitError,\n  AuthenticationError,\n  ConfigurationError,\n  ConnectionError,\n  ExecutionError,\n  InitializationError,\n  ServerError,\n  TunnelError,\n  ValidationError,\n} from \"./errors\";\n// Plugin authoring\nexport { Plugin, toPlugin } from \"./plugin\";\nexport { server } from \"./server\";\n// Telemetry (for advanced custom telemetry)\nexport {\n  type Counter,\n  type Histogram,\n  type ITelemetry,\n  SeverityNumber,\n  type Span,\n  SpanStatusCode,\n  type TelemetryConfig,\n} from \"./telemetry\";\n\n// Vite plugin\nexport { appKitTypesPlugin } from \"./type-generator/vite-plugin\";\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;aAsBkB"}

package/dist/logging/logger.js

@@ -0,0 +1,179 @@
+import { DEFAULT_SAMPLING_CONFIG, shouldSample } from "./sampling.js";
+import { WideEvent } from "./wide-event.js";
+import { WideEventEmitter } from "./wide-event-emitter.js";
+import { trace } from "@opentelemetry/api";
+import { AsyncLocalStorage } from "node:async_hooks";
+import { format } from "node:util";
+import { createDebug } from "obug";
+
+//#region src/logging/logger.ts
+const eventStorage = new AsyncLocalStorage();
+const eventsByRequest = /* @__PURE__ */ new WeakMap();
+const emitter = new WideEventEmitter();
+const MAX_REQUEST_ID_LENGTH = 128;
+/**
+* Sanitize a request ID from user headers
+*/
+function sanitizeRequestId(id) {
+	return id.replace(/[^a-zA-Z0-9_.-]/g, "").slice(0, MAX_REQUEST_ID_LENGTH);
+}
+/**
+* Generate a request ID from the request
+*/
+function generateRequestId(req) {
+	const existingId = req.headers["x-request-id"] || req.headers["x-correlation-id"] || req.headers["x-amzn-trace-id"];
+	if (existingId && typeof existingId === "string" && existingId.length > 0) {
+		const sanitized = sanitizeRequestId(existingId);
+		if (sanitized.length > 0) return sanitized;
+	}
+	return `req_${Date.now()}_${Math.random().toString(36).substring(2, 9)}`;
+}
+/**
+* Create a WideEvent for a request
+*/
+function createEventForRequest(req) {
+	const requestId = generateRequestId(req);
+	const wideEvent = new WideEvent(requestId);
+	const path = (req.path || req.url || req.originalUrl)?.split("?")[0];
+	wideEvent.set("method", req.method).set("path", path);
+	const rawUserId = req.headers["x-forwarded-user"];
+	if (rawUserId && typeof rawUserId === "string" && rawUserId.length > 0) {
+		const userId = rawUserId.replace(/[^a-zA-Z0-9_@.-]/g, "").slice(0, 128);
+		if (userId.length > 0) wideEvent.setUser({ id: userId });
+	}
+	const spanContext = trace.getActiveSpan()?.spanContext();
+	if (spanContext?.traceId) {
+		wideEvent.set("trace_id", spanContext.traceId);
+		createDebug("appkit:logger:event", { useColors: true })("WideEvent created: %s %s (reqId: %s, traceId: %s)", req.method, path, requestId.substring(0, 8), spanContext.traceId.substring(0, 8));
+	}
+	if (wideEvent.data.service) wideEvent.data.service = {
+		...wideEvent.data.service,
+		name: "appkit"
+	};
+	return wideEvent;
+}
+/**
+* Setup response lifecycle handlers for WideEvent finalization
+*/
+function setupResponseHandlers(req, wideEvent) {
+	const res = req.res;
+	if (!res) return;
+	res.once("finish", () => {
+		const finalizedData = wideEvent.finalize(res.statusCode || 200);
+		if (shouldSample(finalizedData, DEFAULT_SAMPLING_CONFIG)) emitter.emit(finalizedData);
+		eventsByRequest.delete(req);
+	});
+	res.once("close", () => {
+		if (!res.writableFinished) eventsByRequest.delete(req);
+	});
+}
+/**
+* Get or create a WideEvent for the given request.
+* If called within wideEventMiddleware context, returns the event from AsyncLocalStorage.
+* Otherwise creates a new event for the request.
+*/
+function getOrCreateEvent(req) {
+	let wideEvent = eventsByRequest.get(req);
+	if (!wideEvent) {
+		const alsEvent = eventStorage.getStore();
+		if (alsEvent) {
+			eventsByRequest.set(req, alsEvent);
+			return alsEvent;
+		}
+		wideEvent = createEventForRequest(req);
+		eventsByRequest.set(req, wideEvent);
+		setupResponseHandlers(req, wideEvent);
+	}
+	return wideEvent;
+}
+/**
+* Get current WideEvent from AsyncLocalStorage or request
+*/
+function getCurrentEvent(req) {
+	if (req) return getOrCreateEvent(req);
+	return eventStorage.getStore();
+}
+/**
+* Check if the first argument is an Express Request
+*/
+function isRequest(arg) {
+	return typeof arg === "object" && arg !== null && "method" in arg && "path" in arg && typeof arg.method === "string";
+}
+/**
+* Create a logger instance for a specific scope
+* @param scope - The scope identifier (e.g., "connectors:lakebase")
+* @returns Logger instance with debug, info, warn, and error methods
+*
+* @example
+* ```typescript
+* const logger = createLogger("connectors:lakebase");
+*
+* // Regular logging (no request tracking)
+* logger.debug("Connection established with pool size: %d", poolSize);
+* logger.info("Server started on port %d", port);
+*
+* // Request-scoped logging (tracks in WideEvent)
+* logger.debug(req, "Processing query: %s", queryId);
+* logger.error(req, "Query failed: %O", error);
+*
+* // Get WideEvent - works in route handlers (with req) or interceptors (from context)
+* const event = logger.event(req);  // In route handler
+* const event = logger.event();     // In interceptor (gets from AsyncLocalStorage)
+* event?.setComponent("analytics", "executeQuery");
+* ```
+*/
+function createLogger(scope) {
+	const debug = createDebug(`appkit:${scope}`, { useColors: true });
+	const prefix = `[appkit:${scope}]`;
+	function debugLog(reqOrMessage, ...args) {
+		if (isRequest(reqOrMessage)) {
+			const req = reqOrMessage;
+			const message = args[0];
+			const logArgs = args.slice(1);
+			const formatted = format(message, ...logArgs);
+			debug(message, ...logArgs);
+			getOrCreateEvent(req).addLog("debug", formatted);
+		} else debug(reqOrMessage, ...args);
+	}
+	function infoLog(reqOrMessage, ...args) {
+		if (isRequest(reqOrMessage)) {
+			const req = reqOrMessage;
+			const message = args[0];
+			const formatted = format(message, ...args.slice(1));
+			console.log(prefix, formatted);
+			getOrCreateEvent(req).addLog("info", formatted);
+		} else console.log(prefix, format(reqOrMessage, ...args));
+	}
+	function warnLog(reqOrMessage, ...args) {
+		if (isRequest(reqOrMessage)) {
+			const req = reqOrMessage;
+			const message = args[0];
+			const formatted = format(message, ...args.slice(1));
+			console.warn(prefix, formatted);
+			getOrCreateEvent(req).addLog("warn", formatted);
+		} else console.warn(prefix, format(reqOrMessage, ...args));
+	}
+	function errorLog(reqOrMessage, ...args) {
+		if (isRequest(reqOrMessage)) {
+			const req = reqOrMessage;
+			const message = args[0];
+			const formatted = format(message, ...args.slice(1));
+			console.error(prefix, formatted);
+			getOrCreateEvent(req).addLog("error", formatted);
+		} else console.error(prefix, format(reqOrMessage, ...args));
+	}
+	function event(req) {
+		return getCurrentEvent(req);
+	}
+	return {
+		debug: debugLog,
+		info: infoLog,
+		warn: warnLog,
+		error: errorLog,
+		event
+	};
+}
+
+//#endregion
+export { createLogger };
+//# sourceMappingURL=logger.js.map

package/dist/logging/logger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.js","names":["createObug"],"sources":["../../src/logging/logger.ts"],"sourcesContent":["import { AsyncLocalStorage } from \"node:async_hooks\";\nimport { format } from \"node:util\";\nimport { trace } from \"@opentelemetry/api\";\nimport type { NextFunction, Request, Response } from \"express\";\nimport { createDebug as createObug } from \"obug\";\nimport { DEFAULT_SAMPLING_CONFIG, shouldSample } from \"./sampling\";\nimport { WideEvent } from \"./wide-event\";\nimport { WideEventEmitter } from \"./wide-event-emitter\";\n\n/**\n * Logger interface for AppKit components\n */\nexport interface Logger {\n  /** Debug output (disabled by default, enable via DEBUG env var) */\n  debug(message: string, ...args: unknown[]): void;\n  debug(req: Request, message: string, ...args: unknown[]): void;\n\n  /** Info output (always visible, for operational messages) */\n  info(message: string, ...args: unknown[]): void;\n  info(req: Request, message: string, ...args: unknown[]): void;\n\n  /** Warning output (always visible, for degraded states) */\n  warn(message: string, ...args: unknown[]): void;\n  warn(req: Request, message: string, ...args: unknown[]): void;\n\n  /** Error output (always visible, for failures) */\n  error(message: string, ...args: unknown[]): void;\n  error(req: Request, message: string, ...args: unknown[]): void;\n\n  /** Get request-scoped WideEvent (from AsyncLocalStorage or explicit req) */\n  event(req?: Request): WideEvent | undefined;\n}\n\n// AsyncLocalStorage for WideEvent context propagation\nconst eventStorage = new AsyncLocalStorage<WideEvent>();\n\n// WeakMap to store WideEvent per request (for explicit req usage)\nconst eventsByRequest = new WeakMap<Request, WideEvent>();\n\n// Global emitter instance\nconst emitter = new WideEventEmitter();\n\nconst MAX_REQUEST_ID_LENGTH = 128;\n\n/**\n * Sanitize a request ID from user headers\n */\nfunction sanitizeRequestId(id: string): string {\n  const sanitized = id.replace(/[^a-zA-Z0-9_.-]/g, \"\");\n  return sanitized.slice(0, MAX_REQUEST_ID_LENGTH);\n}\n\n/**\n * Generate a request ID from the request\n */\nfunction generateRequestId(req: Request): string {\n  const existingId =\n    req.headers[\"x-request-id\"] ||\n    req.headers[\"x-correlation-id\"] ||\n    req.headers[\"x-amzn-trace-id\"];\n\n  if (existingId && typeof existingId === \"string\" && existingId.length > 0) {\n    const sanitized = sanitizeRequestId(existingId);\n    if (sanitized.length > 0) {\n      return sanitized;\n    }\n  }\n\n  return `req_${Date.now()}_${Math.random().toString(36).substring(2, 9)}`;\n}\n\n/**\n * Create a WideEvent for a request\n */\nfunction createEventForRequest(req: Request): WideEvent {\n  const requestId = generateRequestId(req);\n  const wideEvent = new WideEvent(requestId);\n\n  // extract path from request (strip query string)\n  const rawPath = req.path || req.url || req.originalUrl;\n  const path = rawPath?.split(\"?\")[0];\n  wideEvent.set(\"method\", req.method).set(\"path\", path);\n\n  // extract user id from request headers (sanitized)\n  const rawUserId = req.headers[\"x-forwarded-user\"];\n  if (rawUserId && typeof rawUserId === \"string\" && rawUserId.length > 0) {\n    const userId = rawUserId.replace(/[^a-zA-Z0-9_@.-]/g, \"\").slice(0, 128);\n    if (userId.length > 0) {\n      wideEvent.setUser({ id: userId });\n    }\n  }\n\n  // extract trace id from active span for distributed tracing\n  const currentSpan = trace.getActiveSpan();\n  const spanContext = currentSpan?.spanContext();\n  if (spanContext?.traceId) {\n    wideEvent.set(\"trace_id\", spanContext.traceId);\n\n    const debugLogger = createObug(\"appkit:logger:event\", { useColors: true });\n    debugLogger(\n      \"WideEvent created: %s %s (reqId: %s, traceId: %s)\",\n      req.method,\n      path,\n      requestId.substring(0, 8),\n      spanContext.traceId.substring(0, 8),\n    );\n  }\n\n  // Update service scope\n  if (wideEvent.data.service) {\n    wideEvent.data.service = {\n      ...wideEvent.data.service,\n      name: \"appkit\",\n    };\n  }\n\n  return wideEvent;\n}\n\n/**\n * Setup response lifecycle handlers for WideEvent finalization\n */\nfunction setupResponseHandlers(req: Request, wideEvent: WideEvent): void {\n  const res = req.res as Response | undefined;\n  if (!res) return;\n\n  res.once(\"finish\", () => {\n    // finalize the event with status code\n    const finalizedData = wideEvent.finalize(res.statusCode || 200);\n\n    // emit to OpenTelemetry if sampled\n    if (shouldSample(finalizedData, DEFAULT_SAMPLING_CONFIG)) {\n      emitter.emit(finalizedData);\n    }\n\n    // clean up the WeakMap\n    eventsByRequest.delete(req);\n  });\n\n  res.once(\"close\", () => {\n    if (!res.writableFinished) {\n      // request was aborted - just cleanup\n      eventsByRequest.delete(req);\n    }\n  });\n}\n\n/**\n * Express middleware that establishes AsyncLocalStorage context for WideEvent.\n * This properly scopes the context to the entire request lifecycle using run().\n *\n * @example\n * ```typescript\n * import { wideEventMiddleware } from \"@databricks/appkit\";\n *\n * app.use(wideEventMiddleware);\n * ```\n */\nexport function wideEventMiddleware(\n  req: Request,\n  _res: Response,\n  next: NextFunction,\n): void {\n  const wideEvent = createEventForRequest(req);\n  eventsByRequest.set(req, wideEvent);\n  setupResponseHandlers(req, wideEvent);\n\n  // run() scopes the context to this request's entire async chain\n  eventStorage.run(wideEvent, next);\n}\n\n/**\n * Get or create a WideEvent for the given request.\n * If called within wideEventMiddleware context, returns the event from AsyncLocalStorage.\n * Otherwise creates a new event for the request.\n */\nfunction getOrCreateEvent(req: Request): WideEvent {\n  // first check if we already have an event\n  let wideEvent = eventsByRequest.get(req);\n\n  if (!wideEvent) {\n    // check if we are in a middleware context\n    const alsEvent = eventStorage.getStore();\n    if (alsEvent) {\n      // store the event in the WeakMap\n      eventsByRequest.set(req, alsEvent);\n      return alsEvent;\n    }\n\n    // no middleware context - create event directly\n    wideEvent = createEventForRequest(req);\n    eventsByRequest.set(req, wideEvent);\n    setupResponseHandlers(req, wideEvent);\n  }\n\n  return wideEvent;\n}\n\n/**\n * Get current WideEvent from AsyncLocalStorage or request\n */\nfunction getCurrentEvent(req?: Request): WideEvent | undefined {\n  // if req provided, use it\n  if (req) {\n    return getOrCreateEvent(req);\n  }\n\n  // otherwise, get from AsyncLocalStorage\n  return eventStorage.getStore();\n}\n\n/**\n * Check if the first argument is an Express Request\n */\nfunction isRequest(arg: unknown): arg is Request {\n  return (\n    typeof arg === \"object\" &&\n    arg !== null &&\n    \"method\" in arg &&\n    \"path\" in arg &&\n    typeof (arg as Request).method === \"string\"\n  );\n}\n\n/**\n * Create a logger instance for a specific scope\n * @param scope - The scope identifier (e.g., \"connectors:lakebase\")\n * @returns Logger instance with debug, info, warn, and error methods\n *\n * @example\n * ```typescript\n * const logger = createLogger(\"connectors:lakebase\");\n *\n * // Regular logging (no request tracking)\n * logger.debug(\"Connection established with pool size: %d\", poolSize);\n * logger.info(\"Server started on port %d\", port);\n *\n * // Request-scoped logging (tracks in WideEvent)\n * logger.debug(req, \"Processing query: %s\", queryId);\n * logger.error(req, \"Query failed: %O\", error);\n *\n * // Get WideEvent - works in route handlers (with req) or interceptors (from context)\n * const event = logger.event(req);  // In route handler\n * const event = logger.event();     // In interceptor (gets from AsyncLocalStorage)\n * event?.setComponent(\"analytics\", \"executeQuery\");\n * ```\n */\nexport function createLogger(scope: string): Logger {\n  const debug = createObug(`appkit:${scope}`, { useColors: true });\n  const prefix = `[appkit:${scope}]`;\n\n  function debugLog(reqOrMessage: Request | string, ...args: unknown[]): void {\n    if (isRequest(reqOrMessage)) {\n      const req = reqOrMessage;\n      const message = args[0] as string;\n      const logArgs = args.slice(1);\n      const formatted = format(message, ...logArgs);\n\n      debug(message, ...logArgs);\n      getOrCreateEvent(req).addLog(\"debug\", formatted);\n    } else {\n      debug(reqOrMessage, ...args);\n    }\n  }\n\n  function infoLog(reqOrMessage: Request | string, ...args: unknown[]): void {\n    if (isRequest(reqOrMessage)) {\n      const req = reqOrMessage;\n      const message = args[0] as string;\n      const logArgs = args.slice(1);\n      const formatted = format(message, ...logArgs);\n\n      console.log(prefix, formatted);\n      getOrCreateEvent(req).addLog(\"info\", formatted);\n    } else {\n      console.log(prefix, format(reqOrMessage, ...args));\n    }\n  }\n\n  function warnLog(reqOrMessage: Request | string, ...args: unknown[]): void {\n    if (isRequest(reqOrMessage)) {\n      const req = reqOrMessage;\n      const message = args[0] as string;\n      const logArgs = args.slice(1);\n      const formatted = format(message, ...logArgs);\n\n      console.warn(prefix, formatted);\n      getOrCreateEvent(req).addLog(\"warn\", formatted);\n    } else {\n      console.warn(prefix, format(reqOrMessage, ...args));\n    }\n  }\n\n  function errorLog(reqOrMessage: Request | string, ...args: unknown[]): void {\n    if (isRequest(reqOrMessage)) {\n      const req = reqOrMessage;\n      const message = args[0] as string;\n      const logArgs = args.slice(1);\n      const formatted = format(message, ...logArgs);\n\n      console.error(prefix, formatted);\n      getOrCreateEvent(req).addLog(\"error\", formatted);\n    } else {\n      console.error(prefix, format(reqOrMessage, ...args));\n    }\n  }\n\n  function event(req?: Request): WideEvent | undefined {\n    return getCurrentEvent(req);\n  }\n\n  return {\n    debug: debugLog as Logger[\"debug\"],\n    info: infoLog as Logger[\"info\"],\n    warn: warnLog as Logger[\"warn\"],\n    error: errorLog as Logger[\"error\"],\n    event,\n  };\n}\n"],"mappings":"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"}

package/dist/logging/sampling.js

@@ -0,0 +1,56 @@
+import { shouldExcludePath } from "../utils/path-exclusions.js";
+
+//#region src/logging/sampling.ts
+/**
+* Get sample rate from environment variable or default to 1.0 (100%)
+*/
+function getSampleRate() {
+	const envRate = process.env.APPKIT_SAMPLE_RATE;
+	if (envRate) {
+		const parsed = parseFloat(envRate);
+		if (!Number.isNaN(parsed) && parsed >= 0 && parsed <= 1) return parsed;
+	}
+	return 1;
+}
+/**
+* Default sampling configuration
+*/
+const DEFAULT_SAMPLING_CONFIG = {
+	alwaysSampleIf: {
+		hasErrors: true,
+		statusCodeGte: 400,
+		durationGte: 5e3,
+		hasCacheInfo: true
+	},
+	sampleRate: getSampleRate()
+};
+/**
+* Simple hash function for deterministic sampling
+*/
+function hashString(str) {
+	let hash = 0;
+	for (let i = 0; i < str.length; i++) {
+		const char = str.charCodeAt(i);
+		hash = (hash << 5) - hash + char;
+		hash = hash & hash;
+	}
+	return Math.abs(hash);
+}
+/**
+* Determine if a WideEvent should be sampled based on configuration.
+* Uses shared path exclusions from utils/path-exclusions.ts.
+*/
+function shouldSample(event, config = DEFAULT_SAMPLING_CONFIG) {
+	if (shouldExcludePath(event.path)) return false;
+	if (config.alwaysSampleIf.hasErrors && event.error) return true;
+	if (config.alwaysSampleIf.statusCodeGte && event.status_code && event.status_code >= config.alwaysSampleIf.statusCodeGte) return true;
+	if (config.alwaysSampleIf.durationGte && event.duration_ms && event.duration_ms >= config.alwaysSampleIf.durationGte) return true;
+	if (config.alwaysSampleIf.hasCacheInfo && event.execution?.cache_hit !== void 0) return true;
+	if (config.sampleRate >= 1) return true;
+	if (config.sampleRate <= 0) return false;
+	return hashString(event.request_id) % 100 < config.sampleRate * 100;
+}
+
+//#endregion
+export { DEFAULT_SAMPLING_CONFIG, shouldSample };
+//# sourceMappingURL=sampling.js.map

package/dist/logging/sampling.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sampling.js","names":[],"sources":["../../src/logging/sampling.ts"],"sourcesContent":["import { shouldExcludePath } from \"../utils/path-exclusions\";\nimport type { WideEventData } from \"./wide-event\";\n\n/**\n * Sampling configuration for WideEvents\n */\nexport interface SamplingConfig {\n  /** Always sample if any of these conditions are true */\n  alwaysSampleIf: {\n    /** Sample if event has errors */\n    hasErrors: boolean;\n    /** Sample if status code >= this value (e.g., 400) */\n    statusCodeGte: number;\n    /** Sample if duration >= this value in ms (e.g., 5000) */\n    durationGte: number;\n    /** Sample if cache was used (hit or miss tracked) */\n    hasCacheInfo: boolean;\n  };\n\n  /** Sample rate for normal requests (0-1, e.g., 0.1 = 10%) */\n  sampleRate: number;\n}\n\n/**\n * Get sample rate from environment variable or default to 1.0 (100%)\n */\nfunction getSampleRate(): number {\n  const envRate = process.env.APPKIT_SAMPLE_RATE;\n  if (envRate) {\n    const parsed = parseFloat(envRate);\n    if (!Number.isNaN(parsed) && parsed >= 0 && parsed <= 1) {\n      return parsed;\n    }\n  }\n  return 1;\n}\n\n/**\n * Default sampling configuration\n */\nexport const DEFAULT_SAMPLING_CONFIG: SamplingConfig = {\n  alwaysSampleIf: {\n    hasErrors: true,\n    statusCodeGte: 400,\n    durationGte: 5000, // 5 seconds\n    hasCacheInfo: true, // Always sample requests with cache info (hit or miss)\n  },\n  sampleRate: getSampleRate(),\n};\n\n/**\n * Simple hash function for deterministic sampling\n */\nfunction hashString(str: string): number {\n  let hash = 0;\n  for (let i = 0; i < str.length; i++) {\n    const char = str.charCodeAt(i);\n    hash = (hash << 5) - hash + char;\n    hash = hash & hash; // Convert to 32-bit integer\n  }\n  return Math.abs(hash);\n}\n\n/**\n * Determine if a WideEvent should be sampled based on configuration.\n * Uses shared path exclusions from utils/path-exclusions.ts.\n */\nexport function shouldSample(\n  event: WideEventData,\n  config: SamplingConfig = DEFAULT_SAMPLING_CONFIG,\n): boolean {\n  // Check exclusions first using shared path exclusions\n  if (shouldExcludePath(event.path)) {\n    return false;\n  }\n\n  // Always sample if has errors\n  if (config.alwaysSampleIf.hasErrors && event.error) {\n    return true;\n  }\n\n  // Always sample if status code >= threshold\n  if (\n    config.alwaysSampleIf.statusCodeGte &&\n    event.status_code &&\n    event.status_code >= config.alwaysSampleIf.statusCodeGte\n  ) {\n    return true;\n  }\n\n  // Always sample if duration >= threshold\n  if (\n    config.alwaysSampleIf.durationGte &&\n    event.duration_ms &&\n    event.duration_ms >= config.alwaysSampleIf.durationGte\n  ) {\n    return true;\n  }\n\n  // Always sample if cache info is present (cache hit or miss)\n  if (\n    config.alwaysSampleIf.hasCacheInfo &&\n    event.execution?.cache_hit !== undefined\n  ) {\n    return true;\n  }\n\n  // Sample based on sample rate\n  if (config.sampleRate >= 1) {\n    return true;\n  }\n\n  if (config.sampleRate <= 0) {\n    return false;\n  }\n\n  // Deterministic sampling based on request ID\n  const hash = hashString(event.request_id);\n  return hash % 100 < config.sampleRate * 100;\n}\n"],"mappings":";;;;;;AA0BA,SAAS,gBAAwB;CAC/B,MAAM,UAAU,QAAQ,IAAI;AAC5B,KAAI,SAAS;EACX,MAAM,SAAS,WAAW,QAAQ;AAClC,MAAI,CAAC,OAAO,MAAM,OAAO,IAAI,UAAU,KAAK,UAAU,EACpD,QAAO;;AAGX,QAAO;;;;;AAMT,MAAa,0BAA0C;CACrD,gBAAgB;EACd,WAAW;EACX,eAAe;EACf,aAAa;EACb,cAAc;EACf;CACD,YAAY,eAAe;CAC5B;;;;AAKD,SAAS,WAAW,KAAqB;CACvC,IAAI,OAAO;AACX,MAAK,IAAI,IAAI,GAAG,IAAI,IAAI,QAAQ,KAAK;EACnC,MAAM,OAAO,IAAI,WAAW,EAAE;AAC9B,UAAQ,QAAQ,KAAK,OAAO;AAC5B,SAAO,OAAO;;AAEhB,QAAO,KAAK,IAAI,KAAK;;;;;;AAOvB,SAAgB,aACd,OACA,SAAyB,yBAChB;AAET,KAAI,kBAAkB,MAAM,KAAK,CAC/B,QAAO;AAIT,KAAI,OAAO,eAAe,aAAa,MAAM,MAC3C,QAAO;AAIT,KACE,OAAO,eAAe,iBACtB,MAAM,eACN,MAAM,eAAe,OAAO,eAAe,cAE3C,QAAO;AAIT,KACE,OAAO,eAAe,eACtB,MAAM,eACN,MAAM,eAAe,OAAO,eAAe,YAE3C,QAAO;AAIT,KACE,OAAO,eAAe,gBACtB,MAAM,WAAW,cAAc,OAE/B,QAAO;AAIT,KAAI,OAAO,cAAc,EACvB,QAAO;AAGT,KAAI,OAAO,cAAc,EACvB,QAAO;AAKT,QADa,WAAW,MAAM,WAAW,GAC3B,MAAM,OAAO,aAAa"}