@databricks/appkit 0.29.0 → 0.30.1

package/dist/appkit/package.js

@@ -1,6 +1,6 @@
 //#region package.json
 var name = "@databricks/appkit";
-var version = "0.29.0";
+var version = "0.30.1";
 
 //#endregion
 export { name, version };

package/dist/connectors/lakebase-v1/client.js

@@ -1,4 +1,5 @@
 import { createLogger } from "../../logging/logger.js";
+import { init_errors } from "../../errors/index.js";
 import "../../telemetry/index.js";
 import "../../context/index.js";
 import { randomUUID } from "node:crypto";
@@ -6,6 +7,7 @@ import "@databricks/sdk-experimental";
 import "pg";
 
 //#region src/connectors/lakebase-v1/client.ts
+init_errors();
 const logger = createLogger("connectors:lakebase-v1");
 
 //#endregion

package/dist/connectors/lakebase-v1/client.js.map

@@ -1 +1 @@
-{"version":3,"file":"client.js","names":[],"sources":["../../../src/connectors/lakebase-v1/client.ts"],"sourcesContent":["import { randomUUID } from \"node:crypto\";\nimport type { WorkspaceClient } from \"@databricks/sdk-experimental\";\nimport { ApiClient, Config } from \"@databricks/sdk-experimental\";\nimport pg from \"pg\";\nimport {\n  AppKitError,\n  AuthenticationError,\n  ConfigurationError,\n  ConnectionError,\n  ValidationError,\n} from \"../../errors\";\nimport { createLogger } from \"../../logging/logger\";\nimport {\n  type Counter,\n  type Histogram,\n  SpanStatusCode,\n  TelemetryManager,\n  type TelemetryProvider,\n} from \"../../telemetry\";\nimport { deepMerge } from \"../../utils\";\nimport { lakebaseV1Defaults } from \"./defaults\";\nimport type {\n  LakebaseV1Config,\n  LakebaseV1ConnectionConfig,\n  LakebaseV1Credentials,\n} from \"./types\";\n\nconst logger = createLogger(\"connectors:lakebase-v1\");\n\n/**\n * Enterprise-grade connector for Databricks Lakebase Provisioned\n *\n * @deprecated This connector is for Lakebase Provisioned only.\n * For new projects, use Lakebase Autoscaling instead: https://docs.databricks.com/aws/en/oltp/projects/\n *\n * This connector is compatible with Lakebase Provisioned: https://docs.databricks.com/aws/en/oltp/instances/\n *\n * Lakebase Autoscaling offers:\n * - Automatic compute scaling\n * - Scale-to-zero for cost optimization\n * - Database branching for development\n * - Instant restore capabilities\n *\n * Use the new LakebaseConnector (coming in a future release) for Lakebase Autoscaling support.\n *\n * @example Simplest - everything from env/context\n * ```typescript\n * const connector = new LakebaseV1Connector();\n * await connector.query('SELECT * FROM users');\n * ```\n *\n * @example With explicit connection string\n * ```typescript\n * const connector = new LakebaseV1Connector({\n *   connectionString: 'postgresql://...'\n * });\n * ```\n */\nexport class LakebaseV1Connector {\n  private readonly name: string = \"lakebase-v1\";\n  private readonly CACHE_BUFFER_MS = 2 * 60 * 1000;\n  private readonly config: LakebaseV1Config;\n  private readonly connectionConfig: LakebaseV1ConnectionConfig;\n  private pool: pg.Pool | null = null;\n  private credentials: LakebaseV1Credentials | null = null;\n\n  // telemetry\n  private readonly telemetry: TelemetryProvider;\n  private readonly telemetryMetrics: {\n    queryCount: Counter;\n    queryDuration: Histogram;\n  };\n\n  constructor(userConfig?: Partial<LakebaseV1Config>) {\n    this.config = deepMerge(lakebaseV1Defaults, userConfig);\n    this.connectionConfig = this.parseConnectionConfig();\n\n    this.telemetry = TelemetryManager.getProvider(\n      this.name,\n      this.config.telemetry,\n    );\n    this.telemetryMetrics = {\n      queryCount: this.telemetry\n        .getMeter()\n        .createCounter(\"lakebase.v1.query.count\", {\n          description: \"Total number of queries executed\",\n          unit: \"1\",\n        }),\n      queryDuration: this.telemetry\n        .getMeter()\n        .createHistogram(\"lakebase.v1.query.duration\", {\n          description: \"Duration of queries executed\",\n          unit: \"ms\",\n        }),\n    };\n\n    // validate configuration\n    if (this.config.maxPoolSize < 1) {\n      throw ValidationError.invalidValue(\n        \"maxPoolSize\",\n        this.config.maxPoolSize,\n        \"at least 1\",\n      );\n    }\n  }\n\n  /**\n   * Execute a SQL query\n   *\n   * @example\n   * ```typescript\n   * const users = await connector.query('SELECT * FROM users');\n   * const user = await connector.query('SELECT * FROM users WHERE id = $1', [123]);\n   * ```\n   */\n  async query<T extends pg.QueryResultRow>(\n    sql: string,\n    params?: any[],\n    retryCount: number = 0,\n  ): Promise<pg.QueryResult<T>> {\n    const startTime = Date.now();\n\n    return this.telemetry.startActiveSpan(\n      \"lakebase.v1.query\",\n      {\n        attributes: {\n          \"db.system\": \"lakebase-v1\",\n          \"db.statement\": sql.substring(0, 500),\n          \"db.retry_count\": retryCount,\n        },\n      },\n      async (span) => {\n        try {\n          const pool = await this.getPool();\n          const result = await pool.query<T>(sql, params);\n          span.setAttribute(\"db.rows_affected\", result.rowCount ?? 0);\n          span.setStatus({ code: SpanStatusCode.OK });\n          return result;\n        } catch (error) {\n          // retry on auth failure\n          if (this.isAuthError(error)) {\n            span.addEvent(\"auth_error_retry\");\n            await this.rotateCredentials();\n            const newPool = await this.getPool();\n            const result = await newPool.query<T>(sql, params);\n            span.setAttribute(\"db.rows_affected\", result.rowCount ?? 0);\n            span.setStatus({ code: SpanStatusCode.OK });\n            return result;\n          }\n\n          // retry on transient errors, but only once\n          if (this.isTransientError(error) && retryCount < 1) {\n            span.addEvent(\"transient_error_retry\");\n            await new Promise((resolve) => setTimeout(resolve, 100));\n            return await this.query<T>(sql, params, retryCount + 1);\n          }\n\n          span.recordException(error as Error);\n          span.setStatus({ code: SpanStatusCode.ERROR });\n\n          logger.error(\n            \"Query execution failed: %s (code=%s)\",\n            error instanceof Error ? error.message : String(error),\n            (error as any)?.code,\n          );\n\n          if (error instanceof AppKitError) {\n            throw error;\n          }\n          throw ConnectionError.queryFailed(error as Error);\n        } finally {\n          const duration = Date.now() - startTime;\n          this.telemetryMetrics.queryCount.add(1);\n          this.telemetryMetrics.queryDuration.record(duration);\n          span.end();\n        }\n      },\n    );\n  }\n\n  /**\n   * Execute a transaction\n   *\n   * COMMIT and ROLLBACK are automatically managed by the transaction function.\n   *\n   * @param callback - Callback function to execute within the transaction context\n   * @example\n   * ```typescript\n   * await connector.transaction(async (client) => {\n   *   await client.query('INSERT INTO accounts (name) VALUES ($1)', ['Alice']);\n   *   await client.query('INSERT INTO logs (action) VALUES ($1)', ['Created Alice']);\n   * });\n   * ```\n   */\n  async transaction<T>(\n    callback: (client: pg.PoolClient) => Promise<T>,\n    retryCount: number = 0,\n  ): Promise<T> {\n    const startTime = Date.now();\n    return this.telemetry.startActiveSpan(\n      \"lakebase.v1.transaction\",\n      {\n        attributes: {\n          \"db.system\": \"lakebase-v1\",\n          \"db.retry_count\": retryCount,\n        },\n      },\n      async (span) => {\n        const pool = await this.getPool();\n        const client = await pool.connect();\n        try {\n          await client.query(\"BEGIN\");\n          const result = await callback(client);\n          await client.query(\"COMMIT\");\n          span.setStatus({ code: SpanStatusCode.OK });\n          return result;\n        } catch (error) {\n          try {\n            await client.query(\"ROLLBACK\");\n          } catch {}\n          // retry on auth failure\n          if (this.isAuthError(error)) {\n            span.addEvent(\"auth_error_retry\");\n            client.release();\n            await this.rotateCredentials();\n            const newPool = await this.getPool();\n            const retryClient = await newPool.connect();\n            try {\n              await client.query(\"BEGIN\");\n              const result = await callback(retryClient);\n              await client.query(\"COMMIT\");\n              span.setStatus({ code: SpanStatusCode.OK });\n              return result;\n            } catch (retryError) {\n              try {\n                await retryClient.query(\"ROLLBACK\");\n              } catch {}\n              throw retryError;\n            } finally {\n              retryClient.release();\n            }\n          }\n\n          // retry on transient errors, but only once\n          if (this.isTransientError(error) && retryCount < 1) {\n            span.addEvent(\"transaction_error_retry\");\n            client.release();\n            await new Promise((resolve) => setTimeout(resolve, 100));\n            return await this.transaction<T>(callback, retryCount + 1);\n          }\n          span.recordException(error as Error);\n          span.setStatus({ code: SpanStatusCode.ERROR });\n\n          logger.error(\n            \"Transaction execution failed: %s (code=%s)\",\n            error instanceof Error ? error.message : String(error),\n            (error as any)?.code,\n          );\n\n          if (error instanceof AppKitError) {\n            throw error;\n          }\n          throw ConnectionError.transactionFailed(error as Error);\n        } finally {\n          client.release();\n          const duration = Date.now() - startTime;\n          this.telemetryMetrics.queryCount.add(1);\n          this.telemetryMetrics.queryDuration.record(duration);\n          span.end();\n        }\n      },\n    );\n  }\n\n  /** Check if database connection is healthy */\n  async healthCheck(): Promise<boolean> {\n    return this.telemetry.startActiveSpan(\n      \"lakebase.v1.healthCheck\",\n      {},\n      async (span) => {\n        try {\n          const result = await this.query<{ result: number }>(\n            \"SELECT 1 as result\",\n          );\n          const healthy = result.rows[0]?.result === 1;\n          span.setAttribute(\"db.healthy\", healthy);\n          span.setStatus({ code: SpanStatusCode.OK });\n          return healthy;\n        } catch {\n          span.setAttribute(\"db.healthy\", false);\n          span.setStatus({ code: SpanStatusCode.ERROR });\n          return false;\n        } finally {\n          span.end();\n        }\n      },\n    );\n  }\n\n  /** Close connection pool (call on shutdown) */\n  async close(): Promise<void> {\n    if (this.pool) {\n      await this.pool.end().catch((error: unknown) => {\n        logger.error(\"Error closing connection pool: %O\", error);\n      });\n      this.pool = null;\n    }\n    this.credentials = null;\n  }\n\n  /** Setup graceful shutdown to close connection pools */\n  shutdown(): void {\n    process.on(\"SIGTERM\", () => this.close());\n    process.on(\"SIGINT\", () => this.close());\n    this.close();\n  }\n\n  /** Get Databricks workspace client - from config or execution context */\n  private getWorkspaceClient(): WorkspaceClient {\n    if (this.config.workspaceClient) {\n      return this.config.workspaceClient;\n    }\n\n    try {\n      const { getWorkspaceClient: getClient } = require(\"../../context\");\n      const client = getClient();\n\n      // cache it for subsequent calls\n      this.config.workspaceClient = client;\n      return client;\n    } catch (_error) {\n      throw ConnectionError.clientUnavailable(\n        \"Databricks workspace client\",\n        \"Either pass it in config or ensure ServiceContext is initialized\",\n      );\n    }\n  }\n\n  /** Get or create connection pool */\n  private async getPool(): Promise<pg.Pool> {\n    if (!this.connectionConfig) {\n      throw ConfigurationError.invalidConnection(\n        \"Lakebase\",\n        \"Set PGHOST, PGDATABASE, PGAPPNAME env vars, provide a connectionString, or pass explicit config\",\n      );\n    }\n\n    if (!this.pool) {\n      const creds = await this.getCredentials();\n      this.pool = this.createPool(creds);\n    }\n    return this.pool;\n  }\n\n  /** Create PostgreSQL pool */\n  private createPool(credentials: {\n    username: string;\n    password: string;\n  }): pg.Pool {\n    const { host, database, port, sslMode } = this.connectionConfig;\n\n    const pool = new pg.Pool({\n      host,\n      port,\n      database,\n      user: credentials.username,\n      password: credentials.password,\n      max: this.config.maxPoolSize,\n      idleTimeoutMillis: this.config.idleTimeoutMs,\n      connectionTimeoutMillis: this.config.connectionTimeoutMs,\n      ssl: sslMode === \"require\" ? { rejectUnauthorized: true } : false,\n    });\n\n    pool.on(\"error\", (error: Error & { code?: string }) => {\n      logger.error(\n        \"Connection pool error: %s (code: %s)\",\n        error.message,\n        error.code,\n      );\n    });\n\n    return pool;\n  }\n\n  /** Get or fetch credentials with caching */\n  private async getCredentials(): Promise<{\n    username: string;\n    password: string;\n  }> {\n    const now = Date.now();\n\n    // return cached if still valid\n    if (\n      this.credentials &&\n      now < this.credentials.expiresAt - this.CACHE_BUFFER_MS\n    ) {\n      return this.credentials;\n    }\n\n    // fetch new credentials\n    const username = await this.fetchUsername();\n    const { token, expiresAt } = await this.fetchPassword();\n\n    this.credentials = {\n      username,\n      password: token,\n      expiresAt,\n    };\n\n    return { username, password: token };\n  }\n\n  /** Rotate credentials and recreate pool */\n  private async rotateCredentials(): Promise<void> {\n    // clear cached credentials\n    this.credentials = null;\n\n    if (this.pool) {\n      const oldPool = this.pool;\n      this.pool = null;\n      oldPool.end().catch((error: unknown) => {\n        logger.error(\n          \"Error closing old connection pool during rotation: %O\",\n          error,\n        );\n      });\n    }\n  }\n\n  /** Fetch username from Databricks */\n  private async fetchUsername(): Promise<string> {\n    const workspaceClient = this.getWorkspaceClient();\n    const user = await workspaceClient.currentUser.me();\n    if (!user.userName) {\n      throw AuthenticationError.userLookupFailed();\n    }\n    return user.userName;\n  }\n\n  /** Fetch password (OAuth token) from Databricks */\n  private async fetchPassword(): Promise<{ token: string; expiresAt: number }> {\n    const workspaceClient = this.getWorkspaceClient();\n    const config = new Config({ host: workspaceClient.config.host });\n    const apiClient = new ApiClient(config);\n\n    if (!this.connectionConfig.appName) {\n      throw ConfigurationError.resourceNotFound(\"Database app name\");\n    }\n\n    const credentials = await apiClient.request({\n      path: `/api/2.0/database/credentials`,\n      method: \"POST\",\n      headers: new Headers(),\n      raw: false,\n      payload: {\n        instance_names: [this.connectionConfig.appName],\n        request_id: randomUUID(),\n      },\n    });\n\n    if (!this.validateCredentials(credentials)) {\n      throw AuthenticationError.credentialsFailed(\n        this.connectionConfig.appName,\n      );\n    }\n\n    const expiresAt = new Date(credentials.expiration_time).getTime();\n\n    return { token: credentials.token, expiresAt };\n  }\n\n  /** Check if error is auth failure */\n  private isAuthError(error: unknown): boolean {\n    return (\n      typeof error === \"object\" &&\n      error !== null &&\n      \"code\" in error &&\n      (error as any).code === \"28P01\"\n    );\n  }\n\n  /** Check if error is transient */\n  private isTransientError(error: unknown): boolean {\n    if (typeof error !== \"object\" || error === null || !(\"code\" in error)) {\n      return false;\n    }\n\n    const code = (error as any).code;\n    return (\n      code === \"ECONNRESET\" ||\n      code === \"ECONNREFUSED\" ||\n      code === \"ETIMEDOUT\" ||\n      code === \"57P01\" || // admin_shutdown\n      code === \"57P03\" || // cannot_connect_now\n      code === \"08006\" || // connection_failure\n      code === \"08003\" || // connection_does_not_exist\n      code === \"08000\" // connection_exception\n    );\n  }\n\n  /** Type guard for credentials */\n  private validateCredentials(\n    value: unknown,\n  ): value is { token: string; expiration_time: string } {\n    if (typeof value !== \"object\" || value === null) {\n      return false;\n    }\n\n    const credentials = value as { token: string; expiration_time: string };\n    return (\n      \"token\" in credentials &&\n      typeof credentials.token === \"string\" &&\n      \"expiration_time\" in credentials &&\n      typeof credentials.expiration_time === \"string\" &&\n      new Date(credentials.expiration_time).getTime() > Date.now()\n    );\n  }\n\n  /** Parse connection configuration from config or environment */\n  private parseConnectionConfig(): LakebaseV1ConnectionConfig {\n    if (this.config.connectionString) {\n      return this.parseConnectionString(this.config.connectionString);\n    }\n\n    // get connection from config\n    if (this.config.host && this.config.database && this.config.appName) {\n      return {\n        host: this.config.host,\n        database: this.config.database,\n        port: this.config.port ?? 5432,\n        sslMode: this.config.sslMode ?? \"require\",\n        appName: this.config.appName,\n      };\n    }\n\n    // get connection from environment variables\n    const pgHost = process.env.PGHOST;\n    const pgDatabase = process.env.PGDATABASE;\n    const pgAppName = process.env.PGAPPNAME;\n    if (!pgHost || !pgDatabase || !pgAppName) {\n      throw ConfigurationError.invalidConnection(\n        \"Lakebase\",\n        \"Required env vars: PGHOST, PGDATABASE, PGAPPNAME. Optional: PGPORT (default: 5432), PGSSLMODE (default: require)\",\n      );\n    }\n    const pgPort = process.env.PGPORT;\n    const port = pgPort ? parseInt(pgPort, 10) : 5432;\n\n    if (Number.isNaN(port)) {\n      throw ValidationError.invalidValue(\"port\", pgPort, \"a number\");\n    }\n\n    const pgSSLMode = process.env.PGSSLMODE;\n    const sslMode =\n      (pgSSLMode as \"require\" | \"disable\" | \"prefer\") || \"require\";\n\n    return {\n      host: pgHost,\n      database: pgDatabase,\n      port,\n      sslMode,\n      appName: pgAppName,\n    };\n  }\n\n  private parseConnectionString(\n    connectionString: string,\n  ): LakebaseV1ConnectionConfig {\n    const url = new URL(connectionString);\n    const appName = url.searchParams.get(\"appName\");\n    if (!appName) {\n      throw ConfigurationError.missingConnectionParam(\"appName\");\n    }\n\n    return {\n      host: url.hostname,\n      database: url.pathname.slice(1), // remove leading slash\n      port: url.port ? parseInt(url.port, 10) : 5432,\n      sslMode:\n        (url.searchParams.get(\"sslmode\") as \"require\" | \"disable\" | \"prefer\") ??\n        \"require\",\n      appName: appName,\n    };\n  }\n}\n"],"mappings":";;;;;;;;AA2BA,MAAM,SAAS,aAAa,yBAAyB"}
+{"version":3,"file":"client.js","names":[],"sources":["../../../src/connectors/lakebase-v1/client.ts"],"sourcesContent":["import { randomUUID } from \"node:crypto\";\nimport type { WorkspaceClient } from \"@databricks/sdk-experimental\";\nimport { ApiClient, Config } from \"@databricks/sdk-experimental\";\nimport pg from \"pg\";\nimport {\n  AppKitError,\n  AuthenticationError,\n  ConfigurationError,\n  ConnectionError,\n  ValidationError,\n} from \"../../errors\";\nimport { createLogger } from \"../../logging/logger\";\nimport {\n  type Counter,\n  type Histogram,\n  SpanStatusCode,\n  TelemetryManager,\n  type TelemetryProvider,\n} from \"../../telemetry\";\nimport { deepMerge } from \"../../utils\";\nimport { lakebaseV1Defaults } from \"./defaults\";\nimport type {\n  LakebaseV1Config,\n  LakebaseV1ConnectionConfig,\n  LakebaseV1Credentials,\n} from \"./types\";\n\nconst logger = createLogger(\"connectors:lakebase-v1\");\n\n/**\n * Enterprise-grade connector for Databricks Lakebase Provisioned\n *\n * @deprecated This connector is for Lakebase Provisioned only.\n * For new projects, use Lakebase Autoscaling instead: https://docs.databricks.com/aws/en/oltp/projects/\n *\n * This connector is compatible with Lakebase Provisioned: https://docs.databricks.com/aws/en/oltp/instances/\n *\n * Lakebase Autoscaling offers:\n * - Automatic compute scaling\n * - Scale-to-zero for cost optimization\n * - Database branching for development\n * - Instant restore capabilities\n *\n * Use the new LakebaseConnector (coming in a future release) for Lakebase Autoscaling support.\n *\n * @example Simplest - everything from env/context\n * ```typescript\n * const connector = new LakebaseV1Connector();\n * await connector.query('SELECT * FROM users');\n * ```\n *\n * @example With explicit connection string\n * ```typescript\n * const connector = new LakebaseV1Connector({\n *   connectionString: 'postgresql://...'\n * });\n * ```\n */\nexport class LakebaseV1Connector {\n  private readonly name: string = \"lakebase-v1\";\n  private readonly CACHE_BUFFER_MS = 2 * 60 * 1000;\n  private readonly config: LakebaseV1Config;\n  private readonly connectionConfig: LakebaseV1ConnectionConfig;\n  private pool: pg.Pool | null = null;\n  private credentials: LakebaseV1Credentials | null = null;\n\n  // telemetry\n  private readonly telemetry: TelemetryProvider;\n  private readonly telemetryMetrics: {\n    queryCount: Counter;\n    queryDuration: Histogram;\n  };\n\n  constructor(userConfig?: Partial<LakebaseV1Config>) {\n    this.config = deepMerge(lakebaseV1Defaults, userConfig);\n    this.connectionConfig = this.parseConnectionConfig();\n\n    this.telemetry = TelemetryManager.getProvider(\n      this.name,\n      this.config.telemetry,\n    );\n    this.telemetryMetrics = {\n      queryCount: this.telemetry\n        .getMeter()\n        .createCounter(\"lakebase.v1.query.count\", {\n          description: \"Total number of queries executed\",\n          unit: \"1\",\n        }),\n      queryDuration: this.telemetry\n        .getMeter()\n        .createHistogram(\"lakebase.v1.query.duration\", {\n          description: \"Duration of queries executed\",\n          unit: \"ms\",\n        }),\n    };\n\n    // validate configuration\n    if (this.config.maxPoolSize < 1) {\n      throw ValidationError.invalidValue(\n        \"maxPoolSize\",\n        this.config.maxPoolSize,\n        \"at least 1\",\n      );\n    }\n  }\n\n  /**\n   * Execute a SQL query\n   *\n   * @example\n   * ```typescript\n   * const users = await connector.query('SELECT * FROM users');\n   * const user = await connector.query('SELECT * FROM users WHERE id = $1', [123]);\n   * ```\n   */\n  async query<T extends pg.QueryResultRow>(\n    sql: string,\n    params?: any[],\n    retryCount: number = 0,\n  ): Promise<pg.QueryResult<T>> {\n    const startTime = Date.now();\n\n    return this.telemetry.startActiveSpan(\n      \"lakebase.v1.query\",\n      {\n        attributes: {\n          \"db.system\": \"lakebase-v1\",\n          \"db.statement\": sql.substring(0, 500),\n          \"db.retry_count\": retryCount,\n        },\n      },\n      async (span) => {\n        try {\n          const pool = await this.getPool();\n          const result = await pool.query<T>(sql, params);\n          span.setAttribute(\"db.rows_affected\", result.rowCount ?? 0);\n          span.setStatus({ code: SpanStatusCode.OK });\n          return result;\n        } catch (error) {\n          // retry on auth failure\n          if (this.isAuthError(error)) {\n            span.addEvent(\"auth_error_retry\");\n            await this.rotateCredentials();\n            const newPool = await this.getPool();\n            const result = await newPool.query<T>(sql, params);\n            span.setAttribute(\"db.rows_affected\", result.rowCount ?? 0);\n            span.setStatus({ code: SpanStatusCode.OK });\n            return result;\n          }\n\n          // retry on transient errors, but only once\n          if (this.isTransientError(error) && retryCount < 1) {\n            span.addEvent(\"transient_error_retry\");\n            await new Promise((resolve) => setTimeout(resolve, 100));\n            return await this.query<T>(sql, params, retryCount + 1);\n          }\n\n          span.recordException(error as Error);\n          span.setStatus({ code: SpanStatusCode.ERROR });\n\n          logger.error(\n            \"Query execution failed: %s (code=%s)\",\n            error instanceof Error ? error.message : String(error),\n            (error as any)?.code,\n          );\n\n          if (error instanceof AppKitError) {\n            throw error;\n          }\n          throw ConnectionError.queryFailed(error as Error);\n        } finally {\n          const duration = Date.now() - startTime;\n          this.telemetryMetrics.queryCount.add(1);\n          this.telemetryMetrics.queryDuration.record(duration);\n          span.end();\n        }\n      },\n    );\n  }\n\n  /**\n   * Execute a transaction\n   *\n   * COMMIT and ROLLBACK are automatically managed by the transaction function.\n   *\n   * @param callback - Callback function to execute within the transaction context\n   * @example\n   * ```typescript\n   * await connector.transaction(async (client) => {\n   *   await client.query('INSERT INTO accounts (name) VALUES ($1)', ['Alice']);\n   *   await client.query('INSERT INTO logs (action) VALUES ($1)', ['Created Alice']);\n   * });\n   * ```\n   */\n  async transaction<T>(\n    callback: (client: pg.PoolClient) => Promise<T>,\n    retryCount: number = 0,\n  ): Promise<T> {\n    const startTime = Date.now();\n    return this.telemetry.startActiveSpan(\n      \"lakebase.v1.transaction\",\n      {\n        attributes: {\n          \"db.system\": \"lakebase-v1\",\n          \"db.retry_count\": retryCount,\n        },\n      },\n      async (span) => {\n        const pool = await this.getPool();\n        const client = await pool.connect();\n        try {\n          await client.query(\"BEGIN\");\n          const result = await callback(client);\n          await client.query(\"COMMIT\");\n          span.setStatus({ code: SpanStatusCode.OK });\n          return result;\n        } catch (error) {\n          try {\n            await client.query(\"ROLLBACK\");\n          } catch {}\n          // retry on auth failure\n          if (this.isAuthError(error)) {\n            span.addEvent(\"auth_error_retry\");\n            client.release();\n            await this.rotateCredentials();\n            const newPool = await this.getPool();\n            const retryClient = await newPool.connect();\n            try {\n              await client.query(\"BEGIN\");\n              const result = await callback(retryClient);\n              await client.query(\"COMMIT\");\n              span.setStatus({ code: SpanStatusCode.OK });\n              return result;\n            } catch (retryError) {\n              try {\n                await retryClient.query(\"ROLLBACK\");\n              } catch {}\n              throw retryError;\n            } finally {\n              retryClient.release();\n            }\n          }\n\n          // retry on transient errors, but only once\n          if (this.isTransientError(error) && retryCount < 1) {\n            span.addEvent(\"transaction_error_retry\");\n            client.release();\n            await new Promise((resolve) => setTimeout(resolve, 100));\n            return await this.transaction<T>(callback, retryCount + 1);\n          }\n          span.recordException(error as Error);\n          span.setStatus({ code: SpanStatusCode.ERROR });\n\n          logger.error(\n            \"Transaction execution failed: %s (code=%s)\",\n            error instanceof Error ? error.message : String(error),\n            (error as any)?.code,\n          );\n\n          if (error instanceof AppKitError) {\n            throw error;\n          }\n          throw ConnectionError.transactionFailed(error as Error);\n        } finally {\n          client.release();\n          const duration = Date.now() - startTime;\n          this.telemetryMetrics.queryCount.add(1);\n          this.telemetryMetrics.queryDuration.record(duration);\n          span.end();\n        }\n      },\n    );\n  }\n\n  /** Check if database connection is healthy */\n  async healthCheck(): Promise<boolean> {\n    return this.telemetry.startActiveSpan(\n      \"lakebase.v1.healthCheck\",\n      {},\n      async (span) => {\n        try {\n          const result = await this.query<{ result: number }>(\n            \"SELECT 1 as result\",\n          );\n          const healthy = result.rows[0]?.result === 1;\n          span.setAttribute(\"db.healthy\", healthy);\n          span.setStatus({ code: SpanStatusCode.OK });\n          return healthy;\n        } catch {\n          span.setAttribute(\"db.healthy\", false);\n          span.setStatus({ code: SpanStatusCode.ERROR });\n          return false;\n        } finally {\n          span.end();\n        }\n      },\n    );\n  }\n\n  /** Close connection pool (call on shutdown) */\n  async close(): Promise<void> {\n    if (this.pool) {\n      await this.pool.end().catch((error: unknown) => {\n        logger.error(\"Error closing connection pool: %O\", error);\n      });\n      this.pool = null;\n    }\n    this.credentials = null;\n  }\n\n  /** Setup graceful shutdown to close connection pools */\n  shutdown(): void {\n    process.on(\"SIGTERM\", () => this.close());\n    process.on(\"SIGINT\", () => this.close());\n    this.close();\n  }\n\n  /** Get Databricks workspace client - from config or execution context */\n  private getWorkspaceClient(): WorkspaceClient {\n    if (this.config.workspaceClient) {\n      return this.config.workspaceClient;\n    }\n\n    try {\n      const { getWorkspaceClient: getClient } = require(\"../../context\");\n      const client = getClient();\n\n      // cache it for subsequent calls\n      this.config.workspaceClient = client;\n      return client;\n    } catch (_error) {\n      throw ConnectionError.clientUnavailable(\n        \"Databricks workspace client\",\n        \"Either pass it in config or ensure ServiceContext is initialized\",\n      );\n    }\n  }\n\n  /** Get or create connection pool */\n  private async getPool(): Promise<pg.Pool> {\n    if (!this.connectionConfig) {\n      throw ConfigurationError.invalidConnection(\n        \"Lakebase\",\n        \"Set PGHOST, PGDATABASE, PGAPPNAME env vars, provide a connectionString, or pass explicit config\",\n      );\n    }\n\n    if (!this.pool) {\n      const creds = await this.getCredentials();\n      this.pool = this.createPool(creds);\n    }\n    return this.pool;\n  }\n\n  /** Create PostgreSQL pool */\n  private createPool(credentials: {\n    username: string;\n    password: string;\n  }): pg.Pool {\n    const { host, database, port, sslMode } = this.connectionConfig;\n\n    const pool = new pg.Pool({\n      host,\n      port,\n      database,\n      user: credentials.username,\n      password: credentials.password,\n      max: this.config.maxPoolSize,\n      idleTimeoutMillis: this.config.idleTimeoutMs,\n      connectionTimeoutMillis: this.config.connectionTimeoutMs,\n      ssl: sslMode === \"require\" ? { rejectUnauthorized: true } : false,\n    });\n\n    pool.on(\"error\", (error: Error & { code?: string }) => {\n      logger.error(\n        \"Connection pool error: %s (code: %s)\",\n        error.message,\n        error.code,\n      );\n    });\n\n    return pool;\n  }\n\n  /** Get or fetch credentials with caching */\n  private async getCredentials(): Promise<{\n    username: string;\n    password: string;\n  }> {\n    const now = Date.now();\n\n    // return cached if still valid\n    if (\n      this.credentials &&\n      now < this.credentials.expiresAt - this.CACHE_BUFFER_MS\n    ) {\n      return this.credentials;\n    }\n\n    // fetch new credentials\n    const username = await this.fetchUsername();\n    const { token, expiresAt } = await this.fetchPassword();\n\n    this.credentials = {\n      username,\n      password: token,\n      expiresAt,\n    };\n\n    return { username, password: token };\n  }\n\n  /** Rotate credentials and recreate pool */\n  private async rotateCredentials(): Promise<void> {\n    // clear cached credentials\n    this.credentials = null;\n\n    if (this.pool) {\n      const oldPool = this.pool;\n      this.pool = null;\n      oldPool.end().catch((error: unknown) => {\n        logger.error(\n          \"Error closing old connection pool during rotation: %O\",\n          error,\n        );\n      });\n    }\n  }\n\n  /** Fetch username from Databricks */\n  private async fetchUsername(): Promise<string> {\n    const workspaceClient = this.getWorkspaceClient();\n    const user = await workspaceClient.currentUser.me();\n    if (!user.userName) {\n      throw AuthenticationError.userLookupFailed();\n    }\n    return user.userName;\n  }\n\n  /** Fetch password (OAuth token) from Databricks */\n  private async fetchPassword(): Promise<{ token: string; expiresAt: number }> {\n    const workspaceClient = this.getWorkspaceClient();\n    const config = new Config({ host: workspaceClient.config.host });\n    const apiClient = new ApiClient(config);\n\n    if (!this.connectionConfig.appName) {\n      throw ConfigurationError.resourceNotFound(\"Database app name\");\n    }\n\n    const credentials = await apiClient.request({\n      path: `/api/2.0/database/credentials`,\n      method: \"POST\",\n      headers: new Headers(),\n      raw: false,\n      payload: {\n        instance_names: [this.connectionConfig.appName],\n        request_id: randomUUID(),\n      },\n    });\n\n    if (!this.validateCredentials(credentials)) {\n      throw AuthenticationError.credentialsFailed(\n        this.connectionConfig.appName,\n      );\n    }\n\n    const expiresAt = new Date(credentials.expiration_time).getTime();\n\n    return { token: credentials.token, expiresAt };\n  }\n\n  /** Check if error is auth failure */\n  private isAuthError(error: unknown): boolean {\n    return (\n      typeof error === \"object\" &&\n      error !== null &&\n      \"code\" in error &&\n      (error as any).code === \"28P01\"\n    );\n  }\n\n  /** Check if error is transient */\n  private isTransientError(error: unknown): boolean {\n    if (typeof error !== \"object\" || error === null || !(\"code\" in error)) {\n      return false;\n    }\n\n    const code = (error as any).code;\n    return (\n      code === \"ECONNRESET\" ||\n      code === \"ECONNREFUSED\" ||\n      code === \"ETIMEDOUT\" ||\n      code === \"57P01\" || // admin_shutdown\n      code === \"57P03\" || // cannot_connect_now\n      code === \"08006\" || // connection_failure\n      code === \"08003\" || // connection_does_not_exist\n      code === \"08000\" // connection_exception\n    );\n  }\n\n  /** Type guard for credentials */\n  private validateCredentials(\n    value: unknown,\n  ): value is { token: string; expiration_time: string } {\n    if (typeof value !== \"object\" || value === null) {\n      return false;\n    }\n\n    const credentials = value as { token: string; expiration_time: string };\n    return (\n      \"token\" in credentials &&\n      typeof credentials.token === \"string\" &&\n      \"expiration_time\" in credentials &&\n      typeof credentials.expiration_time === \"string\" &&\n      new Date(credentials.expiration_time).getTime() > Date.now()\n    );\n  }\n\n  /** Parse connection configuration from config or environment */\n  private parseConnectionConfig(): LakebaseV1ConnectionConfig {\n    if (this.config.connectionString) {\n      return this.parseConnectionString(this.config.connectionString);\n    }\n\n    // get connection from config\n    if (this.config.host && this.config.database && this.config.appName) {\n      return {\n        host: this.config.host,\n        database: this.config.database,\n        port: this.config.port ?? 5432,\n        sslMode: this.config.sslMode ?? \"require\",\n        appName: this.config.appName,\n      };\n    }\n\n    // get connection from environment variables\n    const pgHost = process.env.PGHOST;\n    const pgDatabase = process.env.PGDATABASE;\n    const pgAppName = process.env.PGAPPNAME;\n    if (!pgHost || !pgDatabase || !pgAppName) {\n      throw ConfigurationError.invalidConnection(\n        \"Lakebase\",\n        \"Required env vars: PGHOST, PGDATABASE, PGAPPNAME. Optional: PGPORT (default: 5432), PGSSLMODE (default: require)\",\n      );\n    }\n    const pgPort = process.env.PGPORT;\n    const port = pgPort ? parseInt(pgPort, 10) : 5432;\n\n    if (Number.isNaN(port)) {\n      throw ValidationError.invalidValue(\"port\", pgPort, \"a number\");\n    }\n\n    const pgSSLMode = process.env.PGSSLMODE;\n    const sslMode =\n      (pgSSLMode as \"require\" | \"disable\" | \"prefer\") || \"require\";\n\n    return {\n      host: pgHost,\n      database: pgDatabase,\n      port,\n      sslMode,\n      appName: pgAppName,\n    };\n  }\n\n  private parseConnectionString(\n    connectionString: string,\n  ): LakebaseV1ConnectionConfig {\n    const url = new URL(connectionString);\n    const appName = url.searchParams.get(\"appName\");\n    if (!appName) {\n      throw ConfigurationError.missingConnectionParam(\"appName\");\n    }\n\n    return {\n      host: url.hostname,\n      database: url.pathname.slice(1), // remove leading slash\n      port: url.port ? parseInt(url.port, 10) : 5432,\n      sslMode:\n        (url.searchParams.get(\"sslmode\") as \"require\" | \"disable\" | \"prefer\") ??\n        \"require\",\n      appName: appName,\n    };\n  }\n}\n"],"mappings":";;;;;;;;;aAUsB;AAiBtB,MAAM,SAAS,aAAa,yBAAyB"}

package/dist/context/service-context.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"service-context.d.ts","names":[],"sources":["../../src/context/service-context.ts"],"mappings":";;;;;;AAqBA;;UAAiB,mBAAA;EAEP;EAAR,MAAA,EAAQ,eAAA;EAMK;EAJb,aAAA;EAIoB;EAFpB,WAAA,GAAc,OAAA;EAJN;EAMR,WAAA,EAAa,OAAA;AAAA"}
+{"version":3,"file":"service-context.d.ts","names":[],"sources":["../../src/context/service-context.ts"],"mappings":";;;;;;AAsBA;;UAAiB,mBAAA;EAEP;EAAR,MAAA,EAAQ,eAAA;EAMK;EAJb,aAAA;EAIoB;EAFpB,WAAA,GAAc,OAAA;EAJN;EAMR,WAAA,EAAa,OAAA;AAAA"}

package/dist/context/service-context.js

@@ -4,7 +4,7 @@ import { ConfigurationError } from "../errors/configuration.js";
 import { InitializationError } from "../errors/initialization.js";
 import { init_errors } from "../errors/index.js";
 import { name, version } from "../appkit/package.js";
-import { WorkspaceClient } from "@databricks/sdk-experimental";
+import { ConfigError, WorkspaceClient } from "@databricks/sdk-experimental";
 import { coerce } from "semver";
 
 //#region src/context/service-context.ts
@@ -85,17 +85,25 @@ var init_service_context = __esmMin((() => {
 			return getClientOptions();
 		}
 		static async createContext(options, client) {
-			const wsClient = client ?? new WorkspaceClient({}, getClientOptions());
-			const warehouseId = options?.warehouseId ? ServiceContext.getWarehouseId(wsClient) : void 0;
-			const workspaceId = ServiceContext.getWorkspaceId(wsClient);
-			const currentUser = await wsClient.currentUser.me();
-			if (!currentUser.id) throw ConfigurationError.resourceNotFound("Service user ID");
-			return {
-				client: wsClient,
-				serviceUserId: currentUser.id,
-				warehouseId,
-				workspaceId
-			};
+			try {
+				const wsClient = client ?? new WorkspaceClient({}, getClientOptions());
+				const [resolvedWorkspaceId, currentUser, resolvedWarehouseId] = await Promise.all([
+					ServiceContext.getWorkspaceId(wsClient),
+					wsClient.currentUser.me(),
+					options?.warehouseId ? ServiceContext.getWarehouseId(wsClient) : Promise.resolve(void 0)
+				]);
+				if (!currentUser.id) throw ConfigurationError.resourceNotFound("Service user ID");
+				const warehouseId = options?.warehouseId && resolvedWarehouseId !== void 0 ? Promise.resolve(resolvedWarehouseId) : void 0;
+				return {
+					client: wsClient,
+					serviceUserId: currentUser.id,
+					warehouseId,
+					workspaceId: Promise.resolve(resolvedWorkspaceId)
+				};
+			} catch (e) {
+				if (e instanceof ConfigError) throw ConfigurationError.databricksAuthenticationSetupFailed(e.baseMessage, { cause: e });
+				throw e;
+			}
 		}
 		static async getWorkspaceId(client) {
 			if (process.env.DATABRICKS_WORKSPACE_ID) return process.env.DATABRICKS_WORKSPACE_ID;

package/dist/context/service-context.js.map

@@ -1 +1 @@
-{"version":3,"file":"service-context.js","names":["productName","productVersion"],"sources":["../../src/context/service-context.ts"],"sourcesContent":["import {\n  type ClientOptions,\n  type sql,\n  WorkspaceClient,\n} from \"@databricks/sdk-experimental\";\nimport { coerce } from \"semver\";\nimport {\n  name as productName,\n  version as productVersion,\n} from \"../../package.json\";\nimport {\n  AuthenticationError,\n  ConfigurationError,\n  InitializationError,\n} from \"../errors\";\nimport type { UserContext } from \"./user-context\";\n\n/**\n * Service context holds the service principal client and shared resources.\n * This is initialized once at app startup and shared across all requests.\n */\nexport interface ServiceContextState {\n  /** WorkspaceClient authenticated as the service principal */\n  client: WorkspaceClient;\n  /** The service principal's user ID */\n  serviceUserId: string;\n  /** Promise that resolves to the warehouse ID (only present when a plugin requires `SQL_WAREHOUSE` resource) */\n  warehouseId?: Promise<string>;\n  /** Promise that resolves to the workspace ID */\n  workspaceId: Promise<string>;\n}\n\nfunction getClientOptions(): ClientOptions {\n  const isDev = process.env.NODE_ENV === \"development\";\n  const semver = coerce(productVersion);\n  const normalizedVersion = (semver?.version ??\n    productVersion) as ClientOptions[\"productVersion\"];\n\n  return {\n    product: productName,\n    productVersion: normalizedVersion,\n    ...(isDev && { userAgentExtra: { mode: \"dev\" } }),\n  };\n}\n\n/**\n * ServiceContext is a singleton that manages the service principal's\n * WorkspaceClient and shared resources like warehouse/workspace IDs.\n *\n * It's initialized once at app startup and provides the foundation\n * for both service principal and user context execution.\n */\nexport class ServiceContext {\n  private static instance: ServiceContextState | null = null;\n  private static initPromise: Promise<ServiceContextState> | null = null;\n\n  /**\n   * Initialize the service context. Should be called once at app startup.\n   * Safe to call multiple times - will return the same instance.\n   *\n   * @param options - Which shared resources to resolve (derived from plugin manifests).\n   * @param client - Optional pre-configured WorkspaceClient to use instead\n   *   of creating one from environment credentials.\n   */\n  static async initialize(\n    options?: { warehouseId?: boolean },\n    client?: WorkspaceClient,\n  ): Promise<ServiceContextState> {\n    if (ServiceContext.instance) {\n      return ServiceContext.instance;\n    }\n\n    if (ServiceContext.initPromise) {\n      return ServiceContext.initPromise;\n    }\n\n    ServiceContext.initPromise = ServiceContext.createContext(options, client);\n    ServiceContext.instance = await ServiceContext.initPromise;\n    return ServiceContext.instance;\n  }\n\n  /**\n   * Get the initialized service context.\n   * @throws Error if not initialized\n   */\n  static get(): ServiceContextState {\n    if (!ServiceContext.instance) {\n      throw InitializationError.notInitialized(\n        \"ServiceContext\",\n        \"Call ServiceContext.initialize() first\",\n      );\n    }\n    return ServiceContext.instance;\n  }\n\n  /**\n   * Check if the service context has been initialized.\n   */\n  static isInitialized(): boolean {\n    return ServiceContext.instance !== null;\n  }\n\n  /**\n   * Create a user context from request headers.\n   *\n   * @param token - The user's access token from x-forwarded-access-token header\n   * @param userId - The user's ID from x-forwarded-user header\n   * @param userName - Optional user name\n   * @throws Error if token is not provided\n   */\n  static createUserContext(\n    token: string,\n    userId: string,\n    userName?: string,\n  ): UserContext {\n    if (!token) {\n      throw AuthenticationError.missingToken(\"user token\");\n    }\n\n    const host = process.env.DATABRICKS_HOST;\n    if (!host) {\n      throw ConfigurationError.missingEnvVar(\"DATABRICKS_HOST\");\n    }\n\n    const serviceCtx = ServiceContext.get();\n\n    // Create user client with the OAuth token from Databricks Apps\n    // Note: We use authType: \"pat\" because the token is passed as a Bearer token\n    // just like a PAT, even though it's technically an OAuth token\n    const userClient = new WorkspaceClient(\n      {\n        token,\n        host,\n        authType: \"pat\",\n      },\n      getClientOptions(),\n    );\n\n    return {\n      client: userClient,\n      userId,\n      userName,\n      warehouseId: serviceCtx.warehouseId,\n      workspaceId: serviceCtx.workspaceId,\n      isUserContext: true,\n    };\n  }\n\n  /**\n   * Get the client options for WorkspaceClient.\n   * Exposed for testing purposes.\n   */\n  static getClientOptions(): ClientOptions {\n    return getClientOptions();\n  }\n\n  private static async createContext(\n    options?: { warehouseId?: boolean },\n    client?: WorkspaceClient,\n  ): Promise<ServiceContextState> {\n    const wsClient = client ?? new WorkspaceClient({}, getClientOptions());\n\n    const warehouseId = options?.warehouseId\n      ? ServiceContext.getWarehouseId(wsClient)\n      : undefined;\n\n    const workspaceId = ServiceContext.getWorkspaceId(wsClient);\n    const currentUser = await wsClient.currentUser.me();\n\n    if (!currentUser.id) {\n      throw ConfigurationError.resourceNotFound(\"Service user ID\");\n    }\n\n    return {\n      client: wsClient,\n      serviceUserId: currentUser.id,\n      warehouseId,\n      workspaceId,\n    };\n  }\n\n  private static async getWorkspaceId(\n    client: WorkspaceClient,\n  ): Promise<string> {\n    if (process.env.DATABRICKS_WORKSPACE_ID) {\n      return process.env.DATABRICKS_WORKSPACE_ID;\n    }\n\n    const response = (await client.apiClient.request({\n      path: \"/api/2.0/preview/scim/v2/Me\",\n      method: \"GET\",\n      headers: new Headers(),\n      raw: false,\n      query: {},\n      responseHeaders: [\"x-databricks-org-id\"],\n    })) as { \"x-databricks-org-id\": string };\n\n    if (!response[\"x-databricks-org-id\"]) {\n      throw ConfigurationError.resourceNotFound(\"Workspace ID\");\n    }\n\n    return response[\"x-databricks-org-id\"];\n  }\n\n  private static async getWarehouseId(\n    client: WorkspaceClient,\n  ): Promise<string> {\n    if (process.env.DATABRICKS_WAREHOUSE_ID) {\n      return process.env.DATABRICKS_WAREHOUSE_ID;\n    }\n\n    if (process.env.NODE_ENV === \"development\") {\n      const response = (await client.apiClient.request({\n        path: \"/api/2.0/sql/warehouses\",\n        method: \"GET\",\n        headers: new Headers(),\n        raw: false,\n        query: {\n          skip_cannot_use: \"true\",\n        },\n      })) as { warehouses: sql.EndpointInfo[] };\n\n      const priorities: Record<sql.State, number> = {\n        RUNNING: 0,\n        STOPPED: 1,\n        STARTING: 2,\n        STOPPING: 3,\n        DELETED: 99,\n        DELETING: 99,\n      };\n\n      const warehouses = (response.warehouses || []).sort((a, b) => {\n        return (\n          priorities[a.state as sql.State] - priorities[b.state as sql.State]\n        );\n      });\n\n      if (response.warehouses.length === 0) {\n        throw ConfigurationError.resourceNotFound(\n          \"Warehouse ID\",\n          \"Please configure the DATABRICKS_WAREHOUSE_ID environment variable\",\n        );\n      }\n\n      const firstWarehouse = warehouses[0];\n      if (\n        firstWarehouse.state === \"DELETED\" ||\n        firstWarehouse.state === \"DELETING\" ||\n        !firstWarehouse.id\n      ) {\n        throw ConfigurationError.resourceNotFound(\n          \"Warehouse ID\",\n          \"Please configure the DATABRICKS_WAREHOUSE_ID environment variable\",\n        );\n      }\n\n      return firstWarehouse.id;\n    }\n\n    throw ConfigurationError.resourceNotFound(\n      \"Warehouse ID\",\n      \"Please configure the DATABRICKS_WAREHOUSE_ID environment variable\",\n    );\n  }\n\n  /**\n   * Reset the service context. Only for testing purposes.\n   */\n  static reset(): void {\n    ServiceContext.instance = null;\n    ServiceContext.initPromise = null;\n  }\n}\n"],"mappings":"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"}
+{"version":3,"file":"service-context.js","names":["productName","productVersion"],"sources":["../../src/context/service-context.ts"],"sourcesContent":["import {\n  type ClientOptions,\n  ConfigError,\n  type sql,\n  WorkspaceClient,\n} from \"@databricks/sdk-experimental\";\nimport { coerce } from \"semver\";\nimport {\n  name as productName,\n  version as productVersion,\n} from \"../../package.json\";\nimport {\n  AuthenticationError,\n  ConfigurationError,\n  InitializationError,\n} from \"../errors\";\nimport type { UserContext } from \"./user-context\";\n\n/**\n * Service context holds the service principal client and shared resources.\n * This is initialized once at app startup and shared across all requests.\n */\nexport interface ServiceContextState {\n  /** WorkspaceClient authenticated as the service principal */\n  client: WorkspaceClient;\n  /** The service principal's user ID */\n  serviceUserId: string;\n  /** Promise that resolves to the warehouse ID (only present when a plugin requires `SQL_WAREHOUSE` resource) */\n  warehouseId?: Promise<string>;\n  /** Promise that resolves to the workspace ID */\n  workspaceId: Promise<string>;\n}\n\nfunction getClientOptions(): ClientOptions {\n  const isDev = process.env.NODE_ENV === \"development\";\n  const semver = coerce(productVersion);\n  const normalizedVersion = (semver?.version ??\n    productVersion) as ClientOptions[\"productVersion\"];\n\n  return {\n    product: productName,\n    productVersion: normalizedVersion,\n    ...(isDev && { userAgentExtra: { mode: \"dev\" } }),\n  };\n}\n\n/**\n * ServiceContext is a singleton that manages the service principal's\n * WorkspaceClient and shared resources like warehouse/workspace IDs.\n *\n * It's initialized once at app startup and provides the foundation\n * for both service principal and user context execution.\n */\nexport class ServiceContext {\n  private static instance: ServiceContextState | null = null;\n  private static initPromise: Promise<ServiceContextState> | null = null;\n\n  /**\n   * Initialize the service context. Should be called once at app startup.\n   * Safe to call multiple times - will return the same instance.\n   *\n   * @param options - Which shared resources to resolve (derived from plugin manifests).\n   * @param client - Optional pre-configured WorkspaceClient to use instead\n   *   of creating one from environment credentials.\n   */\n  static async initialize(\n    options?: { warehouseId?: boolean },\n    client?: WorkspaceClient,\n  ): Promise<ServiceContextState> {\n    if (ServiceContext.instance) {\n      return ServiceContext.instance;\n    }\n\n    if (ServiceContext.initPromise) {\n      return ServiceContext.initPromise;\n    }\n\n    ServiceContext.initPromise = ServiceContext.createContext(options, client);\n    ServiceContext.instance = await ServiceContext.initPromise;\n    return ServiceContext.instance;\n  }\n\n  /**\n   * Get the initialized service context.\n   * @throws Error if not initialized\n   */\n  static get(): ServiceContextState {\n    if (!ServiceContext.instance) {\n      throw InitializationError.notInitialized(\n        \"ServiceContext\",\n        \"Call ServiceContext.initialize() first\",\n      );\n    }\n    return ServiceContext.instance;\n  }\n\n  /**\n   * Check if the service context has been initialized.\n   */\n  static isInitialized(): boolean {\n    return ServiceContext.instance !== null;\n  }\n\n  /**\n   * Create a user context from request headers.\n   *\n   * @param token - The user's access token from x-forwarded-access-token header\n   * @param userId - The user's ID from x-forwarded-user header\n   * @param userName - Optional user name\n   * @throws Error if token is not provided\n   */\n  static createUserContext(\n    token: string,\n    userId: string,\n    userName?: string,\n  ): UserContext {\n    if (!token) {\n      throw AuthenticationError.missingToken(\"user token\");\n    }\n\n    const host = process.env.DATABRICKS_HOST;\n    if (!host) {\n      throw ConfigurationError.missingEnvVar(\"DATABRICKS_HOST\");\n    }\n\n    const serviceCtx = ServiceContext.get();\n\n    // Create user client with the OAuth token from Databricks Apps\n    // Note: We use authType: \"pat\" because the token is passed as a Bearer token\n    // just like a PAT, even though it's technically an OAuth token\n    const userClient = new WorkspaceClient(\n      {\n        token,\n        host,\n        authType: \"pat\",\n      },\n      getClientOptions(),\n    );\n\n    return {\n      client: userClient,\n      userId,\n      userName,\n      warehouseId: serviceCtx.warehouseId,\n      workspaceId: serviceCtx.workspaceId,\n      isUserContext: true,\n    };\n  }\n\n  /**\n   * Get the client options for WorkspaceClient.\n   * Exposed for testing purposes.\n   */\n  static getClientOptions(): ClientOptions {\n    return getClientOptions();\n  }\n\n  private static async createContext(\n    options?: { warehouseId?: boolean },\n    client?: WorkspaceClient,\n  ): Promise<ServiceContextState> {\n    try {\n      const wsClient = client ?? new WorkspaceClient({}, getClientOptions());\n\n      const [resolvedWorkspaceId, currentUser, resolvedWarehouseId] =\n        await Promise.all([\n          ServiceContext.getWorkspaceId(wsClient),\n          wsClient.currentUser.me(),\n          options?.warehouseId\n            ? ServiceContext.getWarehouseId(wsClient)\n            : Promise.resolve(undefined as string | undefined),\n        ]);\n\n      if (!currentUser.id) {\n        throw ConfigurationError.resourceNotFound(\"Service user ID\");\n      }\n\n      const warehouseId =\n        options?.warehouseId && resolvedWarehouseId !== undefined\n          ? Promise.resolve(resolvedWarehouseId)\n          : undefined;\n\n      return {\n        client: wsClient,\n        serviceUserId: currentUser.id,\n        warehouseId,\n        workspaceId: Promise.resolve(resolvedWorkspaceId),\n      };\n    } catch (e) {\n      if (e instanceof ConfigError) {\n        throw ConfigurationError.databricksAuthenticationSetupFailed(\n          e.baseMessage,\n          { cause: e },\n        );\n      }\n      throw e;\n    }\n  }\n\n  private static async getWorkspaceId(\n    client: WorkspaceClient,\n  ): Promise<string> {\n    if (process.env.DATABRICKS_WORKSPACE_ID) {\n      return process.env.DATABRICKS_WORKSPACE_ID;\n    }\n\n    const response = (await client.apiClient.request({\n      path: \"/api/2.0/preview/scim/v2/Me\",\n      method: \"GET\",\n      headers: new Headers(),\n      raw: false,\n      query: {},\n      responseHeaders: [\"x-databricks-org-id\"],\n    })) as { \"x-databricks-org-id\": string };\n\n    if (!response[\"x-databricks-org-id\"]) {\n      throw ConfigurationError.resourceNotFound(\"Workspace ID\");\n    }\n\n    return response[\"x-databricks-org-id\"];\n  }\n\n  private static async getWarehouseId(\n    client: WorkspaceClient,\n  ): Promise<string> {\n    if (process.env.DATABRICKS_WAREHOUSE_ID) {\n      return process.env.DATABRICKS_WAREHOUSE_ID;\n    }\n\n    if (process.env.NODE_ENV === \"development\") {\n      const response = (await client.apiClient.request({\n        path: \"/api/2.0/sql/warehouses\",\n        method: \"GET\",\n        headers: new Headers(),\n        raw: false,\n        query: {\n          skip_cannot_use: \"true\",\n        },\n      })) as { warehouses: sql.EndpointInfo[] };\n\n      const priorities: Record<sql.State, number> = {\n        RUNNING: 0,\n        STOPPED: 1,\n        STARTING: 2,\n        STOPPING: 3,\n        DELETED: 99,\n        DELETING: 99,\n      };\n\n      const warehouses = (response.warehouses || []).sort((a, b) => {\n        return (\n          priorities[a.state as sql.State] - priorities[b.state as sql.State]\n        );\n      });\n\n      if (response.warehouses.length === 0) {\n        throw ConfigurationError.resourceNotFound(\n          \"Warehouse ID\",\n          \"Please configure the DATABRICKS_WAREHOUSE_ID environment variable\",\n        );\n      }\n\n      const firstWarehouse = warehouses[0];\n      if (\n        firstWarehouse.state === \"DELETED\" ||\n        firstWarehouse.state === \"DELETING\" ||\n        !firstWarehouse.id\n      ) {\n        throw ConfigurationError.resourceNotFound(\n          \"Warehouse ID\",\n          \"Please configure the DATABRICKS_WAREHOUSE_ID environment variable\",\n        );\n      }\n\n      return firstWarehouse.id;\n    }\n\n    throw ConfigurationError.resourceNotFound(\n      \"Warehouse ID\",\n      \"Please configure the DATABRICKS_WAREHOUSE_ID environment variable\",\n    );\n  }\n\n  /**\n   * Reset the service context. Only for testing purposes.\n   */\n  static reset(): void {\n    ServiceContext.instance = null;\n    ServiceContext.initPromise = null;\n  }\n}\n"],"mappings":"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"}

package/dist/errors/configuration.d.ts

@@ -31,6 +31,17 @@ declare class ConfigurationError extends AppKitError {
    * Create a configuration error for missing connection string parameter
    */
   static missingConnectionParam(param: string): ConfigurationError;
+  /**
+   * Databricks CLI / token auth failed while creating the workspace client.
+   *
+   * By default the message is short; key lines use **picocolors** when the
+   * terminal supports it (also respects `NO_COLOR`). `console.error` won’t show
+   * stacks or `{ code, context, … }`. Set `APPKIT_VERBOSE_AUTH_ERRORS=1` for full
+   * `cause`, stack, and the raw SDK message (verbose appendix is unstyled).
+   */
+  static databricksAuthenticationSetupFailed(detail: string, options?: {
+    cause?: Error;
+  }): ConfigurationError;
 }
 //#endregion
 export { ConfigurationError };

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

@@ -1 +1 @@
-{"version":3,"file":"configuration.d.ts","names":[],"sources":["../../src/errors/configuration.ts"],"mappings":";;;;;AAYA;;;;;;;;cAAa,kBAAA,SAA2B,WAAA;EAAA,SAC7B,IAAA;EAAA,SACA,UAAA;EAAA,SACA,WAAA;EADA;;;EAAA,OAMF,aAAA,CAAc,OAAA,WAAkB,kBAAA;EAAA;;;EAAA,OAUhC,gBAAA,CAAiB,QAAA,UAAkB,IAAA,YAAgB,kBAAA;EAAA;;;EAAA,OAUnD,iBAAA,CACL,OAAA,UACA,OAAA,YACC,kBAAA;EAAA;;;EAAA,OAUI,sBAAA,CAAuB,KAAA,WAAgB,kBAAA;AAAA"}
+{"version":3,"file":"configuration.d.ts","names":[],"sources":["../../src/errors/configuration.ts"],"mappings":";;;;;AA2CA;;;;;;;;cAAa,kBAAA,SAA2B,WAAA;EAAA,SAC7B,IAAA;EAAA,SACA,UAAA;EAAA,SACA,WAAA;EAH6B;;;EAAA,OAQ/B,aAAA,CAAc,OAAA,WAAkB,kBAAA;EAAhC;;;EAAA,OAUA,gBAAA,CAAiB,QAAA,UAAkB,IAAA,YAAgB,kBAAA;EAAlC;;;EAAA,OAUjB,iBAAA,CACL,OAAA,UACA,OAAA,YACC,kBAAA;EAFD;;;EAAA,OAYK,sBAAA,CAAuB,KAAA,WAAgB,kBAAA;EAAhB;;;;;;;;EAAA,OAevB,mCAAA,CACL,MAAA,UACA,OAAA;IAAY,KAAA,GAAQ,KAAA;EAAA,IACnB,kBAAA;AAAA"}

package/dist/errors/configuration.js

@@ -1,7 +1,31 @@
 import { __esmMin } from "../_virtual/_rolldown/runtime.js";
 import { AppKitError, init_base } from "./base.js";
+import pc from "picocolors";
 
 //#region src/errors/configuration.ts
+function authSetupVerbose() {
+	return process.env.APPKIT_VERBOSE_AUTH_ERRORS === "1" || process.env.APPKIT_VERBOSE_AUTH_ERRORS === "true";
+}
+/** Pulls ` $ databricks ...` from SDK text when present. */
+function suggestedDatabricksCliCommand(detail) {
+	return detail.match(/\$\s*(databricks[^\n]+)/)?.[1]?.trim();
+}
+/** Makes `console.error` show only the message (no stack, no extra fields). */
+function pinUserFacingAuthError(err) {
+	Object.defineProperty(err, "stack", {
+		value: "",
+		configurable: true,
+		enumerable: false,
+		writable: true
+	});
+	Object.defineProperty(err, Symbol.for("nodejs.util.inspect.custom"), {
+		value: function() {
+			return this.message;
+		},
+		enumerable: false,
+		configurable: true
+	});
+}
 var ConfigurationError;
 var init_configuration = __esmMin((() => {
 	init_base();
@@ -33,6 +57,35 @@ var init_configuration = __esmMin((() => {
 		static missingConnectionParam(param) {
 			return new ConfigurationError(`Connection string must include ${param} parameter`, { context: { parameter: param } });
 		}
+		/**
+		* Databricks CLI / token auth failed while creating the workspace client.
+		*
+		* By default the message is short; key lines use **picocolors** when the
+		* terminal supports it (also respects `NO_COLOR`). `console.error` won’t show
+		* stacks or `{ code, context, … }`. Set `APPKIT_VERBOSE_AUTH_ERRORS=1` for full
+		* `cause`, stack, and the raw SDK message (verbose appendix is unstyled).
+		*/
+		static databricksAuthenticationSetupFailed(detail, options) {
+			const verbose = authSetupVerbose();
+			const host = process.env.DATABRICKS_HOST ?? "(not set)";
+			const warehouseId = process.env.DATABRICKS_WAREHOUSE_ID;
+			const d = detail.trim();
+			const cli = suggestedDatabricksCliCommand(d);
+			const lines = [
+				pc.bold(pc.red("Databricks authentication failed.")),
+				"",
+				cli ? `${pc.bold("Run this, then try again:")}\n  ${pc.cyan(cli)}` : pc.yellow("Log in with the Databricks CLI (for example, databricks auth login for this workspace), then try again."),
+				"",
+				pc.dim("Or set DATABRICKS_TOKEN and DATABRICKS_HOST instead of CLI-based auth."),
+				"",
+				`${pc.green("DATABRICKS_HOST")}: ${host}`
+			];
+			if (warehouseId) lines.push(`${pc.green("DATABRICKS_WAREHOUSE_ID")}: ${warehouseId}`);
+			if (verbose) lines.push("", d);
+			const err = new ConfigurationError(lines.join("\n"), { cause: verbose ? options?.cause : void 0 });
+			if (!verbose) pinUserFacingAuthError(err);
+			return err;
+		}
 	};
 }));
 

package/dist/errors/configuration.js.map

@@ -1 +1 @@
-{"version":3,"file":"configuration.js","names":[],"sources":["../../src/errors/configuration.ts"],"sourcesContent":["import { AppKitError } from \"./base\";\n\n/**\n * Error thrown when configuration is missing or invalid.\n * Use for missing environment variables, invalid settings, or setup issues.\n *\n * @example\n * ```typescript\n * throw new ConfigurationError(\"DATABRICKS_HOST environment variable is required\");\n * throw new ConfigurationError(\"Warehouse ID not found\", { context: { env: \"production\" } });\n * ```\n */\nexport class ConfigurationError extends AppKitError {\n  readonly code = \"CONFIGURATION_ERROR\";\n  readonly statusCode = 500;\n  readonly isRetryable = false;\n\n  /**\n   * Create a configuration error for missing environment variable\n   */\n  static missingEnvVar(varName: string): ConfigurationError {\n    return new ConfigurationError(\n      `${varName} environment variable is required`,\n      { context: { envVar: varName } },\n    );\n  }\n\n  /**\n   * Create a configuration error for missing resource\n   */\n  static resourceNotFound(resource: string, hint?: string): ConfigurationError {\n    const message = hint\n      ? `${resource} not found. ${hint}`\n      : `${resource} not found`;\n    return new ConfigurationError(message, { context: { resource } });\n  }\n\n  /**\n   * Create a configuration error for invalid connection config\n   */\n  static invalidConnection(\n    service: string,\n    details?: string,\n  ): ConfigurationError {\n    const message = details\n      ? `${service} connection not configured. ${details}`\n      : `${service} connection not configured`;\n    return new ConfigurationError(message, { context: { service } });\n  }\n\n  /**\n   * Create a configuration error for missing connection string parameter\n   */\n  static missingConnectionParam(param: string): ConfigurationError {\n    return new ConfigurationError(\n      `Connection string must include ${param} parameter`,\n      { context: { parameter: param } },\n    );\n  }\n}\n"],"mappings":";;;;;;YAAqC;CAYxB,qBAAb,MAAa,2BAA2B,YAAY;EAClD,AAAS,OAAO;EAChB,AAAS,aAAa;EACtB,AAAS,cAAc;;;;EAKvB,OAAO,cAAc,SAAqC;AACxD,UAAO,IAAI,mBACT,GAAG,QAAQ,oCACX,EAAE,SAAS,EAAE,QAAQ,SAAS,EAAE,CACjC;;;;;EAMH,OAAO,iBAAiB,UAAkB,MAAmC;AAI3E,UAAO,IAAI,mBAHK,OACZ,GAAG,SAAS,cAAc,SAC1B,GAAG,SAAS,aACuB,EAAE,SAAS,EAAE,UAAU,EAAE,CAAC;;;;;EAMnE,OAAO,kBACL,SACA,SACoB;AAIpB,UAAO,IAAI,mBAHK,UACZ,GAAG,QAAQ,8BAA8B,YACzC,GAAG,QAAQ,6BACwB,EAAE,SAAS,EAAE,SAAS,EAAE,CAAC;;;;;EAMlE,OAAO,uBAAuB,OAAmC;AAC/D,UAAO,IAAI,mBACT,kCAAkC,MAAM,aACxC,EAAE,SAAS,EAAE,WAAW,OAAO,EAAE,CAClC"}
+{"version":3,"file":"configuration.js","names":[],"sources":["../../src/errors/configuration.ts"],"sourcesContent":["import pc from \"picocolors\";\nimport { AppKitError } from \"./base\";\n\nfunction authSetupVerbose(): boolean {\n  return (\n    process.env.APPKIT_VERBOSE_AUTH_ERRORS === \"1\" ||\n    process.env.APPKIT_VERBOSE_AUTH_ERRORS === \"true\"\n  );\n}\n\n/** Pulls ` $ databricks ...` from SDK text when present. */\nfunction suggestedDatabricksCliCommand(detail: string): string | undefined {\n  const m = detail.match(/\\$\\s*(databricks[^\\n]+)/);\n  return m?.[1]?.trim();\n}\n\n/** Makes `console.error` show only the message (no stack, no extra fields). */\nfunction pinUserFacingAuthError(err: ConfigurationError): void {\n  Object.defineProperty(err, \"stack\", {\n    value: \"\",\n    configurable: true,\n    enumerable: false,\n    writable: true,\n  });\n  Object.defineProperty(err, Symbol.for(\"nodejs.util.inspect.custom\"), {\n    value: function (this: ConfigurationError): string {\n      return this.message;\n    },\n    enumerable: false,\n    configurable: true,\n  });\n}\n\n/**\n * Error thrown when configuration is missing or invalid.\n * Use for missing environment variables, invalid settings, or setup issues.\n *\n * @example\n * ```typescript\n * throw new ConfigurationError(\"DATABRICKS_HOST environment variable is required\");\n * throw new ConfigurationError(\"Warehouse ID not found\", { context: { env: \"production\" } });\n * ```\n */\nexport class ConfigurationError extends AppKitError {\n  readonly code = \"CONFIGURATION_ERROR\";\n  readonly statusCode = 500;\n  readonly isRetryable = false;\n\n  /**\n   * Create a configuration error for missing environment variable\n   */\n  static missingEnvVar(varName: string): ConfigurationError {\n    return new ConfigurationError(\n      `${varName} environment variable is required`,\n      { context: { envVar: varName } },\n    );\n  }\n\n  /**\n   * Create a configuration error for missing resource\n   */\n  static resourceNotFound(resource: string, hint?: string): ConfigurationError {\n    const message = hint\n      ? `${resource} not found. ${hint}`\n      : `${resource} not found`;\n    return new ConfigurationError(message, { context: { resource } });\n  }\n\n  /**\n   * Create a configuration error for invalid connection config\n   */\n  static invalidConnection(\n    service: string,\n    details?: string,\n  ): ConfigurationError {\n    const message = details\n      ? `${service} connection not configured. ${details}`\n      : `${service} connection not configured`;\n    return new ConfigurationError(message, { context: { service } });\n  }\n\n  /**\n   * Create a configuration error for missing connection string parameter\n   */\n  static missingConnectionParam(param: string): ConfigurationError {\n    return new ConfigurationError(\n      `Connection string must include ${param} parameter`,\n      { context: { parameter: param } },\n    );\n  }\n\n  /**\n   * Databricks CLI / token auth failed while creating the workspace client.\n   *\n   * By default the message is short; key lines use **picocolors** when the\n   * terminal supports it (also respects `NO_COLOR`). `console.error` won’t show\n   * stacks or `{ code, context, … }`. Set `APPKIT_VERBOSE_AUTH_ERRORS=1` for full\n   * `cause`, stack, and the raw SDK message (verbose appendix is unstyled).\n   */\n  static databricksAuthenticationSetupFailed(\n    detail: string,\n    options?: { cause?: Error },\n  ): ConfigurationError {\n    const verbose = authSetupVerbose();\n    const host = process.env.DATABRICKS_HOST ?? \"(not set)\";\n    const warehouseId = process.env.DATABRICKS_WAREHOUSE_ID;\n    const d = detail.trim();\n    const cli = suggestedDatabricksCliCommand(d);\n\n    const title = pc.bold(pc.red(\"Databricks authentication failed.\"));\n    const action = cli\n      ? `${pc.bold(\"Run this, then try again:\")}\\n  ${pc.cyan(cli)}`\n      : pc.yellow(\n          \"Log in with the Databricks CLI (for example, databricks auth login for this workspace), then try again.\",\n        );\n    const tokenHint = pc.dim(\n      \"Or set DATABRICKS_TOKEN and DATABRICKS_HOST instead of CLI-based auth.\",\n    );\n\n    const lines: string[] = [\n      title,\n      \"\",\n      action,\n      \"\",\n      tokenHint,\n      \"\",\n      `${pc.green(\"DATABRICKS_HOST\")}: ${host}`,\n    ];\n    if (warehouseId) {\n      lines.push(`${pc.green(\"DATABRICKS_WAREHOUSE_ID\")}: ${warehouseId}`);\n    }\n    if (verbose) {\n      lines.push(\"\", d);\n    }\n\n    const err = new ConfigurationError(lines.join(\"\\n\"), {\n      cause: verbose ? options?.cause : undefined,\n    });\n\n    if (!verbose) {\n      pinUserFacingAuthError(err);\n    }\n    return err;\n  }\n}\n"],"mappings":";;;;;AAGA,SAAS,mBAA4B;AACnC,QACE,QAAQ,IAAI,+BAA+B,OAC3C,QAAQ,IAAI,+BAA+B;;;AAK/C,SAAS,8BAA8B,QAAoC;AAEzE,QADU,OAAO,MAAM,0BAA0B,GACtC,IAAI,MAAM;;;AAIvB,SAAS,uBAAuB,KAA+B;AAC7D,QAAO,eAAe,KAAK,SAAS;EAClC,OAAO;EACP,cAAc;EACd,YAAY;EACZ,UAAU;EACX,CAAC;AACF,QAAO,eAAe,KAAK,OAAO,IAAI,6BAA6B,EAAE;EACnE,OAAO,WAA4C;AACjD,UAAO,KAAK;;EAEd,YAAY;EACZ,cAAc;EACf,CAAC;;;;YA7BiC;CA0CxB,qBAAb,MAAa,2BAA2B,YAAY;EAClD,AAAS,OAAO;EAChB,AAAS,aAAa;EACtB,AAAS,cAAc;;;;EAKvB,OAAO,cAAc,SAAqC;AACxD,UAAO,IAAI,mBACT,GAAG,QAAQ,oCACX,EAAE,SAAS,EAAE,QAAQ,SAAS,EAAE,CACjC;;;;;EAMH,OAAO,iBAAiB,UAAkB,MAAmC;AAI3E,UAAO,IAAI,mBAHK,OACZ,GAAG,SAAS,cAAc,SAC1B,GAAG,SAAS,aACuB,EAAE,SAAS,EAAE,UAAU,EAAE,CAAC;;;;;EAMnE,OAAO,kBACL,SACA,SACoB;AAIpB,UAAO,IAAI,mBAHK,UACZ,GAAG,QAAQ,8BAA8B,YACzC,GAAG,QAAQ,6BACwB,EAAE,SAAS,EAAE,SAAS,EAAE,CAAC;;;;;EAMlE,OAAO,uBAAuB,OAAmC;AAC/D,UAAO,IAAI,mBACT,kCAAkC,MAAM,aACxC,EAAE,SAAS,EAAE,WAAW,OAAO,EAAE,CAClC;;;;;;;;;;EAWH,OAAO,oCACL,QACA,SACoB;GACpB,MAAM,UAAU,kBAAkB;GAClC,MAAM,OAAO,QAAQ,IAAI,mBAAmB;GAC5C,MAAM,cAAc,QAAQ,IAAI;GAChC,MAAM,IAAI,OAAO,MAAM;GACvB,MAAM,MAAM,8BAA8B,EAAE;GAY5C,MAAM,QAAkB;IAVV,GAAG,KAAK,GAAG,IAAI,oCAAoC,CAAC;IAYhE;IAXa,MACX,GAAG,GAAG,KAAK,4BAA4B,CAAC,MAAM,GAAG,KAAK,IAAI,KAC1D,GAAG,OACD,0GACD;IASH;IARgB,GAAG,IACnB,yEACD;IAQC;IACA,GAAG,GAAG,MAAM,kBAAkB,CAAC,IAAI;IACpC;AACD,OAAI,YACF,OAAM,KAAK,GAAG,GAAG,MAAM,0BAA0B,CAAC,IAAI,cAAc;AAEtE,OAAI,QACF,OAAM,KAAK,IAAI,EAAE;GAGnB,MAAM,MAAM,IAAI,mBAAmB,MAAM,KAAK,KAAK,EAAE,EACnD,OAAO,UAAU,SAAS,QAAQ,QACnC,CAAC;AAEF,OAAI,CAAC,QACH,wBAAuB,IAAI;AAE7B,UAAO"}

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

@@ -1 +1 @@
-{"version":3,"file":"plugin.d.ts","names":[],"sources":["../../src/plugin/plugin.ts"],"mappings":";;;;;;;;;;;;;;;AA+KA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;uBAAsB,MAAA,iBACJ,gBAAA,GAAmB,gBAAA,aACxB,UAAA;EAAA,UA4BW,MAAA,EAAQ,OAAA;EAAA,UA1BpB,OAAA;EAAA,UACA,KAAA,EAAO,YAAA;EAAA,UACP,GAAA,EAAK,UAAA;EAAA,UACL,aAAA,EAAe,aAAA;EAAA,UACf,aAAA,EAAe,aAAA;EAAA,UACf,SAAA,EAAW,UAAA;EA6OM;EAAA,QA1OnB,mBAAA;EA2OG;EAAA,QAxOH,oBAAA;EAyON;;;;;;EAAA,OAjOK,KAAA,EAAO,WAAA;EA0S0B;;;EArSxC,IAAA;cAEsB,MAAA,EAAQ,OAAA;EAc9B,YAAA,CAAa,CAAA,EAAG,OAAA,CAAQ,MAAA;EAIlB,KAAA,CAAA,GAAK,OAAA;EAEX,YAAA,CAAA,GAAgB,iBAAA;EAIhB,uBAAA,CAAA,GAA2B,WAAA;EAI3B,qBAAA,CAAA;EA6TyC;;;;;;;;;;;;;;;;;;;;;;;;EAjSzC,OAAA,CAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAiDA,YAAA,CAAA,GAAgB,MAAA;;;;;;;;;;;YAcN,aAAA,CAAc,GAAA,EAAK,OAAA,CAAQ,OAAA;;;;;;;;;;;EAmBrC,MAAA,CAAO,GAAA,EAAK,OAAA,CAAQ,OAAA;;;;;;UAuDZ,uBAAA;EAAA,UAqBQ,aAAA,GAAA,CACd,GAAA,EAAK,YAAA,EACL,EAAA,EAAI,oBAAA,CAAqB,CAAA,GACzB,OAAA,EAAS,uBAAA,EACT,OAAA,YAAgB,OAAA;;;;;;;;;;YAwEF,OAAA,GAAA,CACd,EAAA,GAAK,MAAA,GAAS,WAAA,KAAgB,OAAA,CAAQ,CAAA,GACtC,OAAA,EAAS,uBAAA,EACT,OAAA,YACC,OAAA,CAAQ,eAAA,CAAgB,CAAA;EAAA,UAmDjB,gBAAA,CAAiB,IAAA,UAAc,IAAA;EAAA,UAI/B,KAAA,YAAA,CACR,MAAA,EAAQ,OAAA,CAAQ,MAAA,EAChB,MAAA,EAAQ,WAAA;EAAA,QAeF,qBAAA;EAAA,QAaA,kBAAA;EAAA,QAqCM,wBAAA;EAAA,QAqBN,iBAAA;AAAA"}
+{"version":3,"file":"plugin.d.ts","names":[],"sources":["../../src/plugin/plugin.ts"],"mappings":";;;;;;;;;;;;;;;AA+KA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;uBAAsB,MAAA,iBACJ,gBAAA,GAAmB,gBAAA,aACxB,UAAA;EAAA,UA4BW,MAAA,EAAQ,OAAA;EAAA,UA1BpB,OAAA;EAAA,UACA,KAAA,EAAO,YAAA;EAAA,UACP,GAAA,EAAK,UAAA;EAAA,UACL,aAAA,EAAe,aAAA;EAAA,UACf,aAAA,EAAe,aAAA;EAAA,UACf,SAAA,EAAW,UAAA;EA6OM;EAAA,QA1OnB,mBAAA;EA2OG;EAAA,QAxOH,oBAAA;EAyON;;;;;;EAAA,OAjOK,KAAA,EAAO,WAAA;EAkT0B;;;EA7SxC,IAAA;cAEsB,MAAA,EAAQ,OAAA;EAc9B,YAAA,CAAa,CAAA,EAAG,OAAA,CAAQ,MAAA;EAIlB,KAAA,CAAA,GAAK,OAAA;EAEX,YAAA,CAAA,GAAgB,iBAAA;EAIhB,uBAAA,CAAA,GAA2B,WAAA;EAI3B,qBAAA,CAAA;EAqUyC;;;;;;;;;;;;;;;;;;;;;;;;EAzSzC,OAAA,CAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAiDA,YAAA,CAAA,GAAgB,MAAA;;;;;;;;;;;YAcN,aAAA,CAAc,GAAA,EAAK,OAAA,CAAQ,OAAA;;;;;;;;;;;EAmBrC,MAAA,CAAO,GAAA,EAAK,OAAA,CAAQ,OAAA;;;;;;UAuDZ,uBAAA;EAAA,UAqBQ,aAAA,GAAA,CACd,GAAA,EAAK,YAAA,EACL,EAAA,EAAI,oBAAA,CAAqB,CAAA,GACzB,OAAA,EAAS,uBAAA,EACT,OAAA,YAAgB,OAAA;;;;;;;;;;YAgFF,OAAA,GAAA,CACd,EAAA,GAAK,MAAA,GAAS,WAAA,KAAgB,OAAA,CAAQ,CAAA,GACtC,OAAA,EAAS,uBAAA,EACT,OAAA,YACC,OAAA,CAAQ,eAAA,CAAgB,CAAA;EAAA,UAmDjB,gBAAA,CAAiB,IAAA,UAAc,IAAA;EAAA,UAI/B,KAAA,YAAA,CACR,MAAA,EAAQ,OAAA,CAAQ,MAAA,EAChB,MAAA,EAAQ,WAAA;EAAA,QAeF,qBAAA;EAAA,QAaA,kBAAA;EAAA,QAqCM,wBAAA;EAAA,QAqBN,iBAAA;AAAA"}

package/dist/plugin/plugin.js

@@ -346,7 +346,7 @@ var Plugin = class {
 			if (self._checkIfGenerator(result)) yield* result;
 			else yield result;
 		};
-		await this.streamManager.stream(res, asyncWrapperFn, streamConfig);
+		await this.streamManager.stream(res, asyncWrapperFn, streamConfig, effectiveUserKey);
 	}
 	/**
 	* Execute a function with the plugin's interceptor chain.

package/dist/plugin/plugin.js.map

@@ -1 +1 @@
-{"version":3,"file":"plugin.js","names":["otelContext","context"],"sources":["../../src/plugin/plugin.ts"],"sourcesContent":["import { createContextKey, context as otelContext } from \"@opentelemetry/api\";\nimport 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 {\n  getCurrentUserId,\n  runInUserContext,\n  ServiceContext,\n  type UserContext,\n} from \"../context\";\nimport { AppKitError, AuthenticationError } from \"../errors\";\nimport { createLogger } from \"../logging/logger\";\nimport { StreamManager } from \"../stream\";\nimport {\n  type ITelemetry,\n  normalizeTelemetryOptions,\n  TelemetryManager,\n} from \"../telemetry\";\nimport { deepMerge } from \"../utils\";\nimport { DevFileReader } from \"./dev-reader\";\nimport type { ExecutionResult } from \"./execution-result\";\nimport { CacheInterceptor } from \"./interceptors/cache\";\nimport { RetryInterceptor } from \"./interceptors/retry\";\nimport { TelemetryInterceptor } from \"./interceptors/telemetry\";\nimport { TimeoutInterceptor } from \"./interceptors/timeout\";\nimport type {\n  ExecutionInterceptor,\n  InterceptorContext,\n} from \"./interceptors/types\";\n\nconst logger = createLogger(\"plugin\");\n\n/**\n * OTel context key for marking OBO dev mode fallback.\n * Set when asUser() is called in development mode without a user token.\n */\nconst DEV_OBO_FALLBACK_KEY = createContextKey(\"appkit.devOboFallback\");\n\n/**\n * Returns true if the current execution is an OBO dev mode fallback\n * (asUser() was called but fell back to service principal due to missing token).\n */\nexport function isDevOboFallback(): boolean {\n  return otelContext.active().getValue(DEV_OBO_FALLBACK_KEY) === true;\n}\n\n/**\n * Narrow an unknown thrown value to an Error that carries a numeric\n * `statusCode` property (e.g. `ApiError` from `@databricks/sdk-experimental`).\n */\nfunction hasHttpStatusCode(\n  error: unknown,\n): error is Error & { statusCode: number } {\n  return (\n    error instanceof Error &&\n    \"statusCode\" in error &&\n    typeof (error as Record<string, unknown>).statusCode === \"number\"\n  );\n}\n\n/**\n * Methods that should not be proxied by asUser().\n * These are lifecycle/internal methods that don't make sense\n * to execute in a user context.\n */\nconst EXCLUDED_FROM_PROXY = new Set([\n  // Lifecycle methods\n  \"setup\",\n  \"shutdown\",\n  \"injectRoutes\",\n  \"getEndpoints\",\n  \"getSkipBodyParsingPaths\",\n  \"abortActiveOperations\",\n  \"clientConfig\",\n  // asUser itself - prevent chaining like .asUser().asUser()\n  \"asUser\",\n  // Internal methods\n  \"constructor\",\n]);\n\n/**\n * Base abstract class for creating AppKit plugins.\n *\n * All plugins must declare a static `manifest` property with their metadata\n * and resource requirements. The manifest defines:\n * - `required` resources: Always needed for the plugin to function\n * - `optional` resources: May be needed depending on plugin configuration\n *\n * ## Static vs Runtime Resource Requirements\n *\n * The manifest is static and doesn't know the plugin's runtime configuration.\n * For resources that become required based on config options, plugins can\n * implement a static `getResourceRequirements(config)` method.\n *\n * At runtime, this method is called with the actual config to determine\n * which \"optional\" resources should be treated as \"required\".\n *\n * @example Basic plugin with static requirements\n * ```typescript\n * import { Plugin, toPlugin, PluginManifest, ResourceType } from '@databricks/appkit';\n *\n * const myManifest: PluginManifest = {\n *   name: 'myPlugin',\n *   displayName: 'My Plugin',\n *   description: 'Does something awesome',\n *   resources: {\n *     required: [\n *       { type: ResourceType.SQL_WAREHOUSE, alias: 'warehouse', ... }\n *     ],\n *     optional: []\n *   }\n * };\n *\n * class MyPlugin extends Plugin<MyConfig> {\n *   static manifest = myManifest;\n * }\n * ```\n *\n * @example Plugin with config-dependent resources\n * ```typescript\n * interface MyConfig extends BasePluginConfig {\n *   enableCaching?: boolean;\n * }\n *\n * const myManifest: PluginManifest = {\n *   name: 'myPlugin',\n *   resources: {\n *     required: [\n *       { type: ResourceType.SQL_WAREHOUSE, alias: 'warehouse', ... }\n *     ],\n *     optional: [\n *       // Database is optional in the static manifest\n *       { type: ResourceType.DATABASE, alias: 'cache', description: 'Required if caching enabled', ... }\n *     ]\n *   }\n * };\n *\n * class MyPlugin extends Plugin<MyConfig> {\n *   static manifest = myManifest<\"myPlugin\">;\n *\n *   // Runtime method: converts optional resources to required based on config\n *   static getResourceRequirements(config: MyConfig) {\n *     const resources = [];\n *     if (config.enableCaching) {\n *       // When caching is enabled, Database becomes required\n *       resources.push({\n *         type: ResourceType.DATABASE,\n *         alias: 'cache',\n *         resourceKey: 'database',\n *         description: 'Cache storage for query results',\n *         permission: 'CAN_CONNECT_AND_CREATE',\n *         fields: {\n *           instance_name: { env: 'DATABRICKS_CACHE_INSTANCE' },\n *           database_name: { env: 'DATABRICKS_CACHE_DB' },\n *         },\n *         required: true  // Mark as required at runtime\n *       });\n *     }\n *     return resources;\n *   }\n * }\n * ```\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\n  /** Registered endpoints for this plugin */\n  private registeredEndpoints: PluginEndpointMap = {};\n\n  /** Paths that opt out of JSON body parsing (e.g. file upload routes) */\n  private skipBodyParsingPaths: Set<string> = new Set();\n\n  /**\n   * Plugin initialization phase.\n   * - 'core': Initialized first (e.g., config plugins)\n   * - 'normal': Initialized second (most plugins)\n   * - 'deferred': Initialized last (e.g., server plugin)\n   */\n  static phase: PluginPhase = \"normal\";\n\n  /**\n   * Plugin name identifier.\n   */\n  name: string;\n\n  constructor(protected config: TConfig) {\n    this.name =\n      config.name ??\n      (this.constructor as { manifest?: { name: string } }).manifest?.name ??\n      \"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  injectRoutes(_: express.Router) {\n    return;\n  }\n\n  async setup() {}\n\n  getEndpoints(): PluginEndpointMap {\n    return this.registeredEndpoints;\n  }\n\n  getSkipBodyParsingPaths(): ReadonlySet<string> {\n    return this.skipBodyParsingPaths;\n  }\n\n  abortActiveOperations(): void {\n    this.streamManager.abortAll();\n  }\n\n  /**\n   * Returns the public exports for this plugin.\n   * Override this to define a custom public API.\n   * By default, returns an empty object.\n   *\n   * The returned object becomes the plugin's public API on the AppKit instance\n   * (e.g. `appkit.myPlugin.method()`). AppKit automatically binds method context\n   * and adds `asUser(req)` for user-scoped execution.\n   *\n   * @example\n   * ```ts\n   * class MyPlugin extends Plugin {\n   *   private getData() { return []; }\n   *\n   *   exports() {\n   *     return { getData: this.getData };\n   *   }\n   * }\n   *\n   * // After registration:\n   * const appkit = await createApp({ plugins: [myPlugin()] });\n   * appkit.myPlugin.getData();\n   * ```\n   */\n  exports(): unknown {\n    return {};\n  }\n\n  /**\n   * Returns startup config to expose to the client.\n   * Override this to surface server-side values that are safe to publish to the\n   * frontend, such as feature flags, resource IDs, or other app boot settings.\n   *\n   * This runs once when the server starts, so it should not depend on\n   * request-scoped or user-specific state.\n   *\n   * String values that match non-public environment variables are redacted\n   * unless you intentionally expose them via a matching `PUBLIC_APPKIT_` env var.\n   *\n   * Values must be JSON-serializable plain data (no functions, Dates, classes,\n   * Maps, Sets, BigInts, or circular references).\n   * By default returns an empty object (plugin contributes nothing to client config).\n   *\n   * On the client, read the config with the `usePluginClientConfig` hook\n   * (React) or the `getPluginClientConfig` function (vanilla JS), both\n   * from `@databricks/appkit-ui`.\n   *\n   * @example\n   * ```ts\n   * // Server — plugin definition\n   * class MyPlugin extends Plugin<MyConfig> {\n   *   clientConfig() {\n   *     return {\n   *       warehouseId: this.config.warehouseId,\n   *       features: { darkMode: true },\n   *     };\n   *   }\n   * }\n   *\n   * // Client — React component\n   * import { usePluginClientConfig } from \"@databricks/appkit-ui/react\";\n   *\n   * interface MyPluginConfig { warehouseId: string; features: { darkMode: boolean } }\n   *\n   * const config = usePluginClientConfig<MyPluginConfig>(\"myPlugin\");\n   * config.warehouseId; // \"abc-123\"\n   *\n   * // Client — vanilla JS\n   * import { getPluginClientConfig } from \"@databricks/appkit-ui/js\";\n   *\n   * const config = getPluginClientConfig<MyPluginConfig>(\"myPlugin\");\n   * ```\n   */\n  clientConfig(): Record<string, unknown> {\n    return {};\n  }\n\n  /**\n   * Resolve the effective user ID from a request.\n   *\n   * Returns the `x-forwarded-user` header when present. In development mode\n   * (`NODE_ENV=development`) falls back to the current context user ID so\n   * that callers outside an active `runInUserContext` scope still get a\n   * consistent value.\n   *\n   * @throws AuthenticationError in production when no user header is present.\n   */\n  protected resolveUserId(req: express.Request): string {\n    const userId = req.header(\"x-forwarded-user\");\n    if (userId) return userId;\n    if (process.env.NODE_ENV === \"development\") return getCurrentUserId();\n    throw AuthenticationError.missingToken(\n      \"Missing x-forwarded-user header. Cannot resolve user ID.\",\n    );\n  }\n\n  /**\n   * Execute operations using the user's identity from the request.\n   * Returns a proxy of this plugin where all method calls execute\n   * with the user's Databricks credentials instead of the service principal.\n   *\n   * @param req - The Express request containing the user token in headers\n   * @returns A proxied plugin instance that executes as the user\n   * @throws AuthenticationError if user token is not available in request headers (production only).\n   *   In development mode (`NODE_ENV=development`), skips user impersonation instead of throwing.\n   */\n  asUser(req: express.Request): this {\n    const token = req.header(\"x-forwarded-access-token\");\n    const userId = req.header(\"x-forwarded-user\");\n    const isDev = process.env.NODE_ENV === \"development\";\n\n    // In local development, skip user impersonation\n    // since there's no user token available\n    if (!token && isDev) {\n      logger.warn(\n        \"asUser() called without user token in development mode. Skipping user impersonation.\",\n      );\n\n      // Return a proxy that marks execution as OBO dev fallback via OTel context,\n      // so telemetry spans can distinguish intended OBO calls from regular SP calls\n      return new Proxy(this, {\n        get: (target, prop, receiver) => {\n          const value = Reflect.get(target, prop, receiver);\n          if (typeof value !== \"function\") return value;\n          if (typeof prop === \"string\" && EXCLUDED_FROM_PROXY.has(prop))\n            return value;\n\n          return (...args: unknown[]) => {\n            const ctx = otelContext\n              .active()\n              .setValue(DEV_OBO_FALLBACK_KEY, true);\n            return otelContext.with(ctx, () => value.apply(target, args));\n          };\n        },\n      }) as this;\n    }\n\n    if (!token) {\n      throw AuthenticationError.missingToken(\"user token\");\n    }\n\n    if (!userId && !isDev) {\n      throw AuthenticationError.missingUserId();\n    }\n\n    const effectiveUserId = userId || \"dev-user\";\n\n    const userContext = ServiceContext.createUserContext(\n      token,\n      effectiveUserId,\n    );\n\n    // Return a proxy that wraps method calls in user context\n    return this._createUserContextProxy(userContext);\n  }\n\n  /**\n   * Creates a proxy that wraps method calls in a user context.\n   * This allows all plugin methods to automatically use the user's\n   * Databricks credentials.\n   */\n  private _createUserContextProxy(userContext: UserContext): this {\n    return new Proxy(this, {\n      get: (target, prop, receiver) => {\n        const value = Reflect.get(target, prop, receiver);\n\n        if (typeof value !== \"function\") {\n          return value;\n        }\n\n        if (typeof prop === \"string\" && EXCLUDED_FROM_PROXY.has(prop)) {\n          return value;\n        }\n\n        return (...args: unknown[]) => {\n          return runInUserContext(userContext, () => value.apply(target, args));\n        };\n      },\n    }) as this;\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    // get user key from context if not provided\n    const effectiveUserKey = userKey ?? getCurrentUserId();\n\n    const self = this;\n    // capture the active OTel context (HTTP span) before entering the async generator,\n    // where it would otherwise be lost across the async boundary\n    const parentOtelContext = otelContext.active();\n\n    // wrapper function to ensure it returns a generator\n    const asyncWrapperFn = async function* (streamSignal?: AbortSignal) {\n      // build execution context\n      const context: InterceptorContext = {\n        signal: streamSignal,\n        metadata: new Map(),\n        userKey: effectiveUserKey,\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, restoring the parent OTel context\n      // so telemetry spans are linked as children of the HTTP request span\n      const result = await otelContext.with(parentOtelContext, () =>\n        self._executeWithInterceptors(\n          wrappedFn as (signal?: AbortSignal) => Promise<T>,\n          interceptors,\n          context,\n        ),\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  /**\n   * Execute a function with the plugin's interceptor chain.\n   *\n   * Returns an {@link ExecutionResult} discriminated union:\n   * - `{ ok: true, data: T }` on success\n   * - `{ ok: false, status: number, message: string }` on failure\n   *\n   * Errors are never thrown — the method is production-safe.\n   */\n  protected async execute<T>(\n    fn: (signal?: AbortSignal) => Promise<T>,\n    options: PluginExecutionSettings,\n    userKey?: string,\n  ): Promise<ExecutionResult<T>> {\n    const executeConfig = this._buildExecutionConfig(options);\n\n    const interceptors = this._buildInterceptors(executeConfig);\n\n    // get user key from context if not provided\n    const effectiveUserKey = userKey ?? getCurrentUserId();\n\n    const context: InterceptorContext = {\n      metadata: new Map(),\n      userKey: effectiveUserKey,\n    };\n\n    try {\n      const data = await this._executeWithInterceptors(\n        fn,\n        interceptors,\n        context,\n      );\n      return { ok: true, data };\n    } catch (error) {\n      logger.error(\"Plugin execution failed\", { error, plugin: this.name });\n\n      if (error instanceof AppKitError) {\n        return {\n          ok: false,\n          status: error.statusCode,\n          message: error.message,\n        };\n      }\n\n      if (hasHttpStatusCode(error)) {\n        const isDev = process.env.NODE_ENV !== \"production\";\n        const isClientError = error.statusCode >= 400 && error.statusCode < 500;\n        return {\n          ok: false,\n          status: error.statusCode,\n          message: isDev || isClientError ? error.message : \"Server error\",\n        };\n      }\n\n      const isDev = process.env.NODE_ENV !== \"production\";\n      return {\n        ok: false,\n        status: 500,\n        message:\n          isDev && error instanceof Error ? error.message : \"Server error\",\n      };\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    const fullPath = `/api/${this.name}${path}`;\n    this.registerEndpoint(name, fullPath);\n\n    if (config.skipBodyParsing) {\n      this.skipBodyParsingPaths.add(fullPath);\n    }\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    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: InterceptorContext,\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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"}
+{"version":3,"file":"plugin.js","names":["otelContext","context"],"sources":["../../src/plugin/plugin.ts"],"sourcesContent":["import { createContextKey, context as otelContext } from \"@opentelemetry/api\";\nimport 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 {\n  getCurrentUserId,\n  runInUserContext,\n  ServiceContext,\n  type UserContext,\n} from \"../context\";\nimport { AppKitError, AuthenticationError } from \"../errors\";\nimport { createLogger } from \"../logging/logger\";\nimport { StreamManager } from \"../stream\";\nimport {\n  type ITelemetry,\n  normalizeTelemetryOptions,\n  TelemetryManager,\n} from \"../telemetry\";\nimport { deepMerge } from \"../utils\";\nimport { DevFileReader } from \"./dev-reader\";\nimport type { ExecutionResult } from \"./execution-result\";\nimport { CacheInterceptor } from \"./interceptors/cache\";\nimport { RetryInterceptor } from \"./interceptors/retry\";\nimport { TelemetryInterceptor } from \"./interceptors/telemetry\";\nimport { TimeoutInterceptor } from \"./interceptors/timeout\";\nimport type {\n  ExecutionInterceptor,\n  InterceptorContext,\n} from \"./interceptors/types\";\n\nconst logger = createLogger(\"plugin\");\n\n/**\n * OTel context key for marking OBO dev mode fallback.\n * Set when asUser() is called in development mode without a user token.\n */\nconst DEV_OBO_FALLBACK_KEY = createContextKey(\"appkit.devOboFallback\");\n\n/**\n * Returns true if the current execution is an OBO dev mode fallback\n * (asUser() was called but fell back to service principal due to missing token).\n */\nexport function isDevOboFallback(): boolean {\n  return otelContext.active().getValue(DEV_OBO_FALLBACK_KEY) === true;\n}\n\n/**\n * Narrow an unknown thrown value to an Error that carries a numeric\n * `statusCode` property (e.g. `ApiError` from `@databricks/sdk-experimental`).\n */\nfunction hasHttpStatusCode(\n  error: unknown,\n): error is Error & { statusCode: number } {\n  return (\n    error instanceof Error &&\n    \"statusCode\" in error &&\n    typeof (error as Record<string, unknown>).statusCode === \"number\"\n  );\n}\n\n/**\n * Methods that should not be proxied by asUser().\n * These are lifecycle/internal methods that don't make sense\n * to execute in a user context.\n */\nconst EXCLUDED_FROM_PROXY = new Set([\n  // Lifecycle methods\n  \"setup\",\n  \"shutdown\",\n  \"injectRoutes\",\n  \"getEndpoints\",\n  \"getSkipBodyParsingPaths\",\n  \"abortActiveOperations\",\n  \"clientConfig\",\n  // asUser itself - prevent chaining like .asUser().asUser()\n  \"asUser\",\n  // Internal methods\n  \"constructor\",\n]);\n\n/**\n * Base abstract class for creating AppKit plugins.\n *\n * All plugins must declare a static `manifest` property with their metadata\n * and resource requirements. The manifest defines:\n * - `required` resources: Always needed for the plugin to function\n * - `optional` resources: May be needed depending on plugin configuration\n *\n * ## Static vs Runtime Resource Requirements\n *\n * The manifest is static and doesn't know the plugin's runtime configuration.\n * For resources that become required based on config options, plugins can\n * implement a static `getResourceRequirements(config)` method.\n *\n * At runtime, this method is called with the actual config to determine\n * which \"optional\" resources should be treated as \"required\".\n *\n * @example Basic plugin with static requirements\n * ```typescript\n * import { Plugin, toPlugin, PluginManifest, ResourceType } from '@databricks/appkit';\n *\n * const myManifest: PluginManifest = {\n *   name: 'myPlugin',\n *   displayName: 'My Plugin',\n *   description: 'Does something awesome',\n *   resources: {\n *     required: [\n *       { type: ResourceType.SQL_WAREHOUSE, alias: 'warehouse', ... }\n *     ],\n *     optional: []\n *   }\n * };\n *\n * class MyPlugin extends Plugin<MyConfig> {\n *   static manifest = myManifest;\n * }\n * ```\n *\n * @example Plugin with config-dependent resources\n * ```typescript\n * interface MyConfig extends BasePluginConfig {\n *   enableCaching?: boolean;\n * }\n *\n * const myManifest: PluginManifest = {\n *   name: 'myPlugin',\n *   resources: {\n *     required: [\n *       { type: ResourceType.SQL_WAREHOUSE, alias: 'warehouse', ... }\n *     ],\n *     optional: [\n *       // Database is optional in the static manifest\n *       { type: ResourceType.DATABASE, alias: 'cache', description: 'Required if caching enabled', ... }\n *     ]\n *   }\n * };\n *\n * class MyPlugin extends Plugin<MyConfig> {\n *   static manifest = myManifest<\"myPlugin\">;\n *\n *   // Runtime method: converts optional resources to required based on config\n *   static getResourceRequirements(config: MyConfig) {\n *     const resources = [];\n *     if (config.enableCaching) {\n *       // When caching is enabled, Database becomes required\n *       resources.push({\n *         type: ResourceType.DATABASE,\n *         alias: 'cache',\n *         resourceKey: 'database',\n *         description: 'Cache storage for query results',\n *         permission: 'CAN_CONNECT_AND_CREATE',\n *         fields: {\n *           instance_name: { env: 'DATABRICKS_CACHE_INSTANCE' },\n *           database_name: { env: 'DATABRICKS_CACHE_DB' },\n *         },\n *         required: true  // Mark as required at runtime\n *       });\n *     }\n *     return resources;\n *   }\n * }\n * ```\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\n  /** Registered endpoints for this plugin */\n  private registeredEndpoints: PluginEndpointMap = {};\n\n  /** Paths that opt out of JSON body parsing (e.g. file upload routes) */\n  private skipBodyParsingPaths: Set<string> = new Set();\n\n  /**\n   * Plugin initialization phase.\n   * - 'core': Initialized first (e.g., config plugins)\n   * - 'normal': Initialized second (most plugins)\n   * - 'deferred': Initialized last (e.g., server plugin)\n   */\n  static phase: PluginPhase = \"normal\";\n\n  /**\n   * Plugin name identifier.\n   */\n  name: string;\n\n  constructor(protected config: TConfig) {\n    this.name =\n      config.name ??\n      (this.constructor as { manifest?: { name: string } }).manifest?.name ??\n      \"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  injectRoutes(_: express.Router) {\n    return;\n  }\n\n  async setup() {}\n\n  getEndpoints(): PluginEndpointMap {\n    return this.registeredEndpoints;\n  }\n\n  getSkipBodyParsingPaths(): ReadonlySet<string> {\n    return this.skipBodyParsingPaths;\n  }\n\n  abortActiveOperations(): void {\n    this.streamManager.abortAll();\n  }\n\n  /**\n   * Returns the public exports for this plugin.\n   * Override this to define a custom public API.\n   * By default, returns an empty object.\n   *\n   * The returned object becomes the plugin's public API on the AppKit instance\n   * (e.g. `appkit.myPlugin.method()`). AppKit automatically binds method context\n   * and adds `asUser(req)` for user-scoped execution.\n   *\n   * @example\n   * ```ts\n   * class MyPlugin extends Plugin {\n   *   private getData() { return []; }\n   *\n   *   exports() {\n   *     return { getData: this.getData };\n   *   }\n   * }\n   *\n   * // After registration:\n   * const appkit = await createApp({ plugins: [myPlugin()] });\n   * appkit.myPlugin.getData();\n   * ```\n   */\n  exports(): unknown {\n    return {};\n  }\n\n  /**\n   * Returns startup config to expose to the client.\n   * Override this to surface server-side values that are safe to publish to the\n   * frontend, such as feature flags, resource IDs, or other app boot settings.\n   *\n   * This runs once when the server starts, so it should not depend on\n   * request-scoped or user-specific state.\n   *\n   * String values that match non-public environment variables are redacted\n   * unless you intentionally expose them via a matching `PUBLIC_APPKIT_` env var.\n   *\n   * Values must be JSON-serializable plain data (no functions, Dates, classes,\n   * Maps, Sets, BigInts, or circular references).\n   * By default returns an empty object (plugin contributes nothing to client config).\n   *\n   * On the client, read the config with the `usePluginClientConfig` hook\n   * (React) or the `getPluginClientConfig` function (vanilla JS), both\n   * from `@databricks/appkit-ui`.\n   *\n   * @example\n   * ```ts\n   * // Server — plugin definition\n   * class MyPlugin extends Plugin<MyConfig> {\n   *   clientConfig() {\n   *     return {\n   *       warehouseId: this.config.warehouseId,\n   *       features: { darkMode: true },\n   *     };\n   *   }\n   * }\n   *\n   * // Client — React component\n   * import { usePluginClientConfig } from \"@databricks/appkit-ui/react\";\n   *\n   * interface MyPluginConfig { warehouseId: string; features: { darkMode: boolean } }\n   *\n   * const config = usePluginClientConfig<MyPluginConfig>(\"myPlugin\");\n   * config.warehouseId; // \"abc-123\"\n   *\n   * // Client — vanilla JS\n   * import { getPluginClientConfig } from \"@databricks/appkit-ui/js\";\n   *\n   * const config = getPluginClientConfig<MyPluginConfig>(\"myPlugin\");\n   * ```\n   */\n  clientConfig(): Record<string, unknown> {\n    return {};\n  }\n\n  /**\n   * Resolve the effective user ID from a request.\n   *\n   * Returns the `x-forwarded-user` header when present. In development mode\n   * (`NODE_ENV=development`) falls back to the current context user ID so\n   * that callers outside an active `runInUserContext` scope still get a\n   * consistent value.\n   *\n   * @throws AuthenticationError in production when no user header is present.\n   */\n  protected resolveUserId(req: express.Request): string {\n    const userId = req.header(\"x-forwarded-user\");\n    if (userId) return userId;\n    if (process.env.NODE_ENV === \"development\") return getCurrentUserId();\n    throw AuthenticationError.missingToken(\n      \"Missing x-forwarded-user header. Cannot resolve user ID.\",\n    );\n  }\n\n  /**\n   * Execute operations using the user's identity from the request.\n   * Returns a proxy of this plugin where all method calls execute\n   * with the user's Databricks credentials instead of the service principal.\n   *\n   * @param req - The Express request containing the user token in headers\n   * @returns A proxied plugin instance that executes as the user\n   * @throws AuthenticationError if user token is not available in request headers (production only).\n   *   In development mode (`NODE_ENV=development`), skips user impersonation instead of throwing.\n   */\n  asUser(req: express.Request): this {\n    const token = req.header(\"x-forwarded-access-token\");\n    const userId = req.header(\"x-forwarded-user\");\n    const isDev = process.env.NODE_ENV === \"development\";\n\n    // In local development, skip user impersonation\n    // since there's no user token available\n    if (!token && isDev) {\n      logger.warn(\n        \"asUser() called without user token in development mode. Skipping user impersonation.\",\n      );\n\n      // Return a proxy that marks execution as OBO dev fallback via OTel context,\n      // so telemetry spans can distinguish intended OBO calls from regular SP calls\n      return new Proxy(this, {\n        get: (target, prop, receiver) => {\n          const value = Reflect.get(target, prop, receiver);\n          if (typeof value !== \"function\") return value;\n          if (typeof prop === \"string\" && EXCLUDED_FROM_PROXY.has(prop))\n            return value;\n\n          return (...args: unknown[]) => {\n            const ctx = otelContext\n              .active()\n              .setValue(DEV_OBO_FALLBACK_KEY, true);\n            return otelContext.with(ctx, () => value.apply(target, args));\n          };\n        },\n      }) as this;\n    }\n\n    if (!token) {\n      throw AuthenticationError.missingToken(\"user token\");\n    }\n\n    if (!userId && !isDev) {\n      throw AuthenticationError.missingUserId();\n    }\n\n    const effectiveUserId = userId || \"dev-user\";\n\n    const userContext = ServiceContext.createUserContext(\n      token,\n      effectiveUserId,\n    );\n\n    // Return a proxy that wraps method calls in user context\n    return this._createUserContextProxy(userContext);\n  }\n\n  /**\n   * Creates a proxy that wraps method calls in a user context.\n   * This allows all plugin methods to automatically use the user's\n   * Databricks credentials.\n   */\n  private _createUserContextProxy(userContext: UserContext): this {\n    return new Proxy(this, {\n      get: (target, prop, receiver) => {\n        const value = Reflect.get(target, prop, receiver);\n\n        if (typeof value !== \"function\") {\n          return value;\n        }\n\n        if (typeof prop === \"string\" && EXCLUDED_FROM_PROXY.has(prop)) {\n          return value;\n        }\n\n        return (...args: unknown[]) => {\n          return runInUserContext(userContext, () => value.apply(target, args));\n        };\n      },\n    }) as this;\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    // get user key from context if not provided\n    const effectiveUserKey = userKey ?? getCurrentUserId();\n\n    const self = this;\n    // capture the active OTel context (HTTP span) before entering the async generator,\n    // where it would otherwise be lost across the async boundary\n    const parentOtelContext = otelContext.active();\n\n    // wrapper function to ensure it returns a generator\n    const asyncWrapperFn = async function* (streamSignal?: AbortSignal) {\n      // build execution context\n      const context: InterceptorContext = {\n        signal: streamSignal,\n        metadata: new Map(),\n        userKey: effectiveUserKey,\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, restoring the parent OTel context\n      // so telemetry spans are linked as children of the HTTP request span\n      const result = await otelContext.with(parentOtelContext, () =>\n        self._executeWithInterceptors(\n          wrappedFn as (signal?: AbortSignal) => Promise<T>,\n          interceptors,\n          context,\n        ),\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. The effective user key is forwarded\n    // to the stream manager so that reconnections to existing streamIds are\n    // bound to the original creator (prevents cross-user stream takeover via\n    // guessed/leaked IDs).\n    await this.streamManager.stream(\n      res,\n      asyncWrapperFn,\n      streamConfig,\n      effectiveUserKey,\n    );\n  }\n\n  /**\n   * Execute a function with the plugin's interceptor chain.\n   *\n   * Returns an {@link ExecutionResult} discriminated union:\n   * - `{ ok: true, data: T }` on success\n   * - `{ ok: false, status: number, message: string }` on failure\n   *\n   * Errors are never thrown — the method is production-safe.\n   */\n  protected async execute<T>(\n    fn: (signal?: AbortSignal) => Promise<T>,\n    options: PluginExecutionSettings,\n    userKey?: string,\n  ): Promise<ExecutionResult<T>> {\n    const executeConfig = this._buildExecutionConfig(options);\n\n    const interceptors = this._buildInterceptors(executeConfig);\n\n    // get user key from context if not provided\n    const effectiveUserKey = userKey ?? getCurrentUserId();\n\n    const context: InterceptorContext = {\n      metadata: new Map(),\n      userKey: effectiveUserKey,\n    };\n\n    try {\n      const data = await this._executeWithInterceptors(\n        fn,\n        interceptors,\n        context,\n      );\n      return { ok: true, data };\n    } catch (error) {\n      logger.error(\"Plugin execution failed\", { error, plugin: this.name });\n\n      if (error instanceof AppKitError) {\n        return {\n          ok: false,\n          status: error.statusCode,\n          message: error.message,\n        };\n      }\n\n      if (hasHttpStatusCode(error)) {\n        const isDev = process.env.NODE_ENV !== \"production\";\n        const isClientError = error.statusCode >= 400 && error.statusCode < 500;\n        return {\n          ok: false,\n          status: error.statusCode,\n          message: isDev || isClientError ? error.message : \"Server error\",\n        };\n      }\n\n      const isDev = process.env.NODE_ENV !== \"production\";\n      return {\n        ok: false,\n        status: 500,\n        message:\n          isDev && error instanceof Error ? error.message : \"Server error\",\n      };\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    const fullPath = `/api/${this.name}${path}`;\n    this.registerEndpoint(name, fullPath);\n\n    if (config.skipBodyParsing) {\n      this.skipBodyParsingPaths.add(fullPath);\n    }\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    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: InterceptorContext,\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/plugins/server/utils.js

@@ -1,7 +1,7 @@
 import crypto from "node:crypto";
+import pc from "picocolors";
 import path from "node:path";
 import fs from "node:fs";
-import pc from "picocolors";
 
 //#region src/plugins/server/utils.ts
 function parseCookies(req) {

package/dist/registry/manifest-loader.d.ts

@@ -35,11 +35,11 @@ declare function getPluginManifest(plugin: PluginConstructor): PluginManifest;
 declare function getResourceRequirements(plugin: PluginConstructor): {
   required: boolean;
   description: string;
-  fields: Record<string, ResourceFieldEntry>;
   type: ResourceType;
+  permission: ResourcePermission;
+  fields: Record<string, ResourceFieldEntry>;
   alias: string;
   resourceKey: string;
-  permission: ResourcePermission;
 }[];
 //#endregion
 export { getPluginManifest, getResourceRequirements };

package/dist/registry/manifest-loader.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"manifest-loader.d.ts","names":[],"sources":["../../src/registry/manifest-loader.ts"],"mappings":";;;;;;;;;;;AA4DA;;;;iBAAgB,iBAAA,CAAkB,MAAA,EAAQ,iBAAA,GAAoB,cAAA;;;;;AA4F9D;;;;;;;;;;;;;;iBAAgB,uBAAA,CAAwB,MAAA,EAAQ,iBAAA;;;yBAAiB,kBAAA"}
+{"version":3,"file":"manifest-loader.d.ts","names":[],"sources":["../../src/registry/manifest-loader.ts"],"mappings":";;;;;;;;;;;AA4DA;;;;iBAAgB,iBAAA,CAAkB,MAAA,EAAQ,iBAAA,GAAoB,cAAA;;;;;AA4F9D;;;;;;;;;;;;;;iBAAgB,uBAAA,CAAwB,MAAA,EAAQ,iBAAA"}

package/dist/stream/stream-manager.d.ts

@@ -10,7 +10,7 @@ declare class StreamManager {
   private maxEventSize;
   private bufferTTL;
   constructor(options?: StreamConfig);
-  stream(res: IAppResponse, handler: (signal: AbortSignal) => AsyncGenerator<any, void, unknown>, options?: StreamConfig): Promise<void>;
+  stream(res: IAppResponse, handler: (signal: AbortSignal) => AsyncGenerator<any, void, unknown>, options?: StreamConfig, ownerKey?: string): Promise<void>;
   abortAll(): void;
   getActiveCount(): number;
   private _attachToExistingStream;

package/dist/stream/stream-manager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"stream-manager.d.ts","names":[],"sources":["../../src/stream/stream-manager.ts"],"mappings":";;;;;cAca,aAAA;EAAA,QACH,gBAAA;EAAA,QACA,cAAA;EAAA,QACA,SAAA;EAAA,QACA,YAAA;EAAA,QACA,SAAA;cAEI,OAAA,GAAU,YAAA;EAWhB,MAAA,CACJ,GAAA,EAAK,YAAA,EACL,OAAA,GAAU,MAAA,EAAQ,WAAA,KAAgB,cAAA,sBAClC,OAAA,GAAU,YAAA,GACT,OAAA;EAyBH,QAAA,CAAA;EAUA,cAAA,CAAA;EAAA,QAKc,uBAAA;EAAA,QAyEA,gBAAA;EAAA,QA2EA,6BAAA;EAAA,QAoFN,eAAA;EAAA,QA6BA,yBAAA;EAAA,QAaA,wBAAA;EAAA,QAkBA,gBAAA;EAAA,QASA,cAAA;EAAA,QAUA,gBAAA;AAAA"}
+{"version":3,"file":"stream-manager.d.ts","names":[],"sources":["../../src/stream/stream-manager.ts"],"mappings":";;;;;cAca,aAAA;EAAA,QACH,gBAAA;EAAA,QACA,cAAA;EAAA,QACA,SAAA;EAAA,QACA,YAAA;EAAA,QACA,SAAA;cAEI,OAAA,GAAU,YAAA;EAWhB,MAAA,CACJ,GAAA,EAAK,YAAA,EACL,OAAA,GAAU,MAAA,EAAQ,WAAA,KAAgB,cAAA,sBAClC,OAAA,GAAU,YAAA,EACV,QAAA,YACC,OAAA;EAsCH,QAAA,CAAA;EAUA,cAAA,CAAA;EAAA,QAKc,uBAAA;EAAA,QAyEA,gBAAA;EAAA,QA6EA,6BAAA;EAAA,QAoFN,eAAA;EAAA,QA6BA,yBAAA;EAAA,QAaA,wBAAA;EAAA,QAkBA,gBAAA;EAAA,QASA,cAAA;EAAA,QAUA,gBAAA;AAAA"}

package/dist/stream/stream-manager.js

@@ -23,15 +23,22 @@ var StreamManager = class {
 		this.bufferTTL = options?.bufferTTL ?? streamDefaults.bufferTTL;
 		this.activeOperations = /* @__PURE__ */ new Set();
 	}
-	async stream(res, handler, options) {
+	async stream(res, handler, options, ownerKey) {
 		const { streamId } = options || {};
 		if (res.writableEnded || res.destroyed) return;
 		this.sseWriter.setupHeaders(res);
 		if (streamId && StreamValidator.validateStreamId(streamId)) {
 			const existingStream = this.streamRegistry.get(streamId);
-			if (existingStream) return this._attachToExistingStream(res, existingStream, options);
+			if (existingStream) {
+				if (existingStream.ownerKey !== ownerKey) {
+					this.sseWriter.writeError(res, randomUUID(), "Stream not found or access denied", SSEErrorCode.STREAM_FORBIDDEN);
+					res.end();
+					return;
+				}
+				return this._attachToExistingStream(res, existingStream, options);
+			}
 		}
-		return this._createNewStream(res, handler, options);
+		return this._createNewStream(res, handler, options, ownerKey);
 	}
 	abortAll() {
 		this.activeOperations.forEach((operation) => {
@@ -81,7 +88,7 @@ var StreamManager = class {
 			clearInterval(heartbeat);
 		}
 	}
-	async _createNewStream(res, handler, options) {
+	async _createNewStream(res, handler, options, ownerKey) {
 		const streamId = options?.streamId ?? randomUUID();
 		if (res.writableEnded || res.destroyed) return;
 		const abortController = new AbortController();
@@ -95,6 +102,7 @@ var StreamManager = class {
 		}
 		const streamEntry = {
 			streamId,
+			ownerKey,
 			generator: handler(combinedSignal),
 			eventBuffer,
 			clients: new Set([res]),