@databricks/appkit 0.82.0 → 0.84.0

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

@@ -1 +1 @@
-{"version":3,"file":"execution-context.js","names":[],"sources":["../../src/context/execution-context.ts"],"sourcesContent":["import { AsyncLocalStorage } from \"node:async_hooks\";\n\nimport { ConfigurationError } from \"../errors\";\nimport { ServiceContext } from \"./service-context\";\nimport {\n  type ExecutionContext,\n  isUserContext,\n  type UserContext,\n} from \"./user-context\";\n\n/**\n * AsyncLocalStorage for execution context.\n * Used to pass user context through the call stack without explicit parameters.\n */\nconst executionContextStorage = new AsyncLocalStorage<UserContext>();\n\n/**\n * Run a function in the context of a user.\n * All calls within the function will have access to the user context.\n *\n * @param userContext - The user context to use\n * @param fn - The function to run\n * @returns The result of the function\n */\nexport function runInUserContext<T>(userContext: UserContext, fn: () => T): T {\n  return executionContextStorage.run(userContext, fn);\n}\n\n/**\n * Get the current execution context.\n *\n * - If running inside a user context (via asUser), returns the user context\n * - Otherwise, returns the service context\n *\n * @throws Error if ServiceContext is not initialized\n */\nexport function getExecutionContext(): ExecutionContext {\n  const userContext = executionContextStorage.getStore();\n  if (userContext) {\n    return userContext;\n  }\n  return ServiceContext.get();\n}\n\n/**\n * Get the current user ID for cache keying and telemetry.\n *\n * Returns the user ID if in user context, otherwise the service user ID.\n */\nexport function getCurrentUserId(): string {\n  const ctx = getExecutionContext();\n  if (isUserContext(ctx)) {\n    return ctx.userId;\n  }\n  return ctx.serviceUserId;\n}\n\n/**\n * Get the WorkspaceClient for the current execution context.\n */\nexport function getWorkspaceClient() {\n  return getExecutionContext().client;\n}\n\n/**\n * Get the warehouse ID promise.\n */\nexport function getWarehouseId(): Promise<string> {\n  const ctx = getExecutionContext();\n  if (!ctx.warehouseId) {\n    throw ConfigurationError.resourceNotFound(\n      \"Warehouse ID\",\n      \"No plugin requires a SQL Warehouse. Add a sql_warehouse resource to your plugin manifest, or set DATABRICKS_WAREHOUSE_ID\",\n    );\n  }\n  return ctx.warehouseId;\n}\n\n/**\n * Get the workspace ID promise.\n */\nexport function getWorkspaceId(): Promise<string> {\n  return getExecutionContext().workspaceId;\n}\n\n/**\n * Check if currently running in a user context.\n */\nexport function isInUserContext(): boolean {\n  const ctx = executionContextStorage.getStore();\n  return ctx !== undefined;\n}\n\n/**\n * Get the user context if one is active, otherwise `undefined`.\n * Unlike `getExecutionContext()`, this does not require `ServiceContext`\n * to be initialized and never throws.\n */\nexport function getUserContext(): UserContext | undefined {\n  return executionContextStorage.getStore();\n}\n"],"mappings":";;;;;;;;;;;AAcA,MAAM,0BAA0B,IAAI,mBAAgC;;;;;;;;;AAUpE,SAAgB,iBAAoB,aAA0B,IAAgB;AAC5E,QAAO,wBAAwB,IAAI,aAAa,GAAG;;;;;;;;;;AAWrD,SAAgB,sBAAwC;CACtD,MAAM,cAAc,wBAAwB,UAAU;AACtD,KAAI,YACF,QAAO;AAET,QAAO,eAAe,KAAK;;;;;;;AAQ7B,SAAgB,mBAA2B;CACzC,MAAM,MAAM,qBAAqB;AACjC,KAAI,cAAc,IAAI,CACpB,QAAO,IAAI;AAEb,QAAO,IAAI;;;;;AAMb,SAAgB,qBAAqB;AACnC,QAAO,qBAAqB,CAAC;;;;;AAM/B,SAAgB,iBAAkC;CAChD,MAAM,MAAM,qBAAqB;AACjC,KAAI,CAAC,IAAI,YACP,OAAM,mBAAmB,iBACvB,gBACA,2HACD;AAEH,QAAO,IAAI;;;;;AAMb,SAAgB,iBAAkC;AAChD,QAAO,qBAAqB,CAAC;;;;;AAM/B,SAAgB,kBAA2B;AAEzC,QADY,wBAAwB,UAAU,KAC/B;;;;;;;AAQjB,SAAgB,iBAA0C;AACxD,QAAO,wBAAwB,UAAU"}
+{"version":3,"file":"execution-context.js","names":[],"sources":["../../src/context/execution-context.ts"],"sourcesContent":["import { AsyncLocalStorage } from \"node:async_hooks\";\n\nimport {\n  IdentityExpiredError,\n  isUnauthorized,\n} from \"../errors/identity-expired\";\nimport {\n  captureWarehouseId,\n  getWarehouseId as getResourceWarehouseId,\n  runWithResourceBindings,\n  type WarehouseBinding,\n} from \"../resources/warehouse\";\nimport { type CallerContext, snapshotCallerContext } from \"./caller-context\";\nimport { warnContextDeprecation } from \"./deprecation\";\nimport { ServiceContext, type ServiceContextState } from \"./service-context\";\nimport {\n  legacyUserContext,\n  toCallerContext,\n  type UserContext,\n} from \"./user-context\";\n\ninterface CallerScope {\n  readonly caller: CallerContext;\n  readonly legacyExecution: boolean;\n}\n\nconst executionContextStorage = new AsyncLocalStorage<CallerScope>();\n\nfunction runInCallerScope<T>(\n  callerContext: CallerContext,\n  fn: () => T,\n  legacyResources?: WarehouseBinding,\n  legacyExecution = false,\n): T {\n  const scope = Object.freeze({\n    caller: snapshotCallerContext(callerContext),\n    // Deprecated entry points cannot disable guards in an existing new scope.\n    legacyExecution:\n      legacyExecution &&\n      (executionContextStorage.getStore()?.legacyExecution ?? true),\n  });\n  return runWithResourceBindings(legacyResources, () =>\n    executionContextStorage.run(scope, () => {\n      try {\n        const result = fn();\n        if (result instanceof Promise) {\n          return result.catch((error) => {\n            throw normalizeIdentityError(error);\n          }) as T;\n        }\n        return result;\n      } catch (error) {\n        throw normalizeIdentityError(error);\n      }\n    }),\n  );\n}\n\n/** Convert downstream 401s before recording or surfacing caller failures. */\nexport function normalizeIdentityError(error: unknown): unknown {\n  const caller = getCallerContext();\n  if (\n    !caller ||\n    error instanceof IdentityExpiredError ||\n    !isUnauthorized(error)\n  )\n    return error;\n  return new IdentityExpiredError(caller.tokenFingerprint);\n}\n\n/**\n * Run a function with an immutable snapshot of the caller context.\n * Nested and concurrent scopes keep their own identities.\n *\n * @param callerContext - The caller context to use\n * @param fn - The function to run\n * @returns The result of the function\n */\nexport function runInCallerContext<T>(\n  callerContext: CallerContext,\n  fn: () => T,\n): T {\n  return runInCallerScope(callerContext, fn);\n}\n\n/** @internal Preserve legacy resource behavior without weakening an enclosing scope. */\nexport function runInLegacyCallerContext<T>(\n  caller: CallerContext,\n  fn: () => T,\n): T {\n  return runInCallerScope(caller, fn, undefined, true);\n}\n\n/** @internal Legacy user entry points retain their established resource routing. */\nexport function isLegacyCallerScope(): boolean {\n  return executionContextStorage.getStore()?.legacyExecution === true;\n}\n\n/** @deprecated Use runInCallerContext. */\nexport function runInUserContext<T>(\n  userContext: UserContext | (CallerContext & Pick<UserContext, \"warehouseId\">),\n  fn: () => T,\n): T {\n  warnContextDeprecation(\"runInUserContext\", \"runInCallerContext\");\n  if (!(\"principal\" in userContext) || \"warehouseId\" in userContext) {\n    return runInCallerScope(\n      toCallerContext(userContext),\n      fn,\n      Object.freeze({ warehouseId: userContext.warehouseId }),\n      true,\n    );\n  }\n  return runInLegacyCallerContext(toCallerContext(userContext), fn);\n}\n\n/**\n * Get the current execution context.\n *\n * - If running inside a caller context (via asUser), returns the caller context\n * - Otherwise, returns the service context\n *\n * @throws Error if ServiceContext is not initialized\n */\nexport function getExecutionContext():\n  | ServiceContextState\n  | (CallerContext & UserContext) {\n  const callerContext = getCallerContext();\n  if (callerContext) {\n    return legacyUserContext(callerContext, captureWarehouseId());\n  }\n  return ServiceContext.get();\n}\n\n/**\n * Get the principal key for future cache keying: `app` or `user:<id>`.\n */\nexport function getCurrentPrincipalKey(): string {\n  const caller = getCallerContext();\n  return caller ? `user:${caller.principal.userId}` : \"app\";\n}\n\n/** The initiating user in a caller scope; no user actor exists in service scope. */\nexport function getCurrentActorId(): string | undefined {\n  return getCallerContext()?.principal.userId;\n}\n\n/** @internal Bare ID of the effective caller or service principal. */\nexport function getCurrentPrincipalId(): string {\n  return getCurrentActorId() ?? ServiceContext.get().serviceUserId;\n}\n\n/**\n * @deprecated Use getCurrentPrincipalKey for new cache keys or getCurrentActorId\n * for audit. Preserves the bare user or service ID for existing callers.\n */\nexport function getCurrentUserId(): string {\n  warnContextDeprecation(\n    \"getCurrentUserId\",\n    \"getCurrentPrincipalKey (cache) or getCurrentActorId (audit)\",\n  );\n  return getCurrentPrincipalId();\n}\n\n/**\n * Get the WorkspaceClient for the current execution context.\n */\nexport function getWorkspaceClient() {\n  return (getCallerContext() ?? ServiceContext.get()).client;\n}\n\n/**\n * @deprecated Import getWarehouseId from @databricks/appkit instead of context.\n */\nexport function getWarehouseId(): Promise<string> {\n  warnContextDeprecation(\n    \"context.getWarehouseId\",\n    \"getWarehouseId() from @databricks/appkit\",\n  );\n  return getResourceWarehouseId();\n}\n\n/**\n * Get the workspace ID promise.\n */\nexport function getWorkspaceId(): Promise<string> {\n  return (getCallerContext() ?? ServiceContext.get()).workspaceId;\n}\n\n/**\n * Check if currently running in a user context.\n */\nexport function isInUserContext(): boolean {\n  const ctx = executionContextStorage.getStore();\n  return ctx !== undefined;\n}\n\n/**\n * @internal Run `fn` with no caller scope, so it executes as the app service\n * principal even inside an on-behalf-of-user run. Used for app-owned\n * state such as the agents thread store.\n */\nexport function runOutsideCallerScope<T>(fn: () => T): T {\n  return executionContextStorage.exit(fn);\n}\n\n/**\n * Get the caller context if one is active, otherwise `undefined`.\n * Unlike `getExecutionContext()`, this does not require `ServiceContext`\n * to be initialized and never throws.\n */\nexport function getCallerContext(): CallerContext | undefined {\n  return executionContextStorage.getStore()?.caller;\n}\n\n/** @deprecated Use getCallerContext and its principal field. */\nexport function getUserContext(): (CallerContext & UserContext) | undefined {\n  warnContextDeprecation(\"getUserContext\", \"getCallerContext\");\n  const caller = getCallerContext();\n  return caller ? legacyUserContext(caller, captureWarehouseId()) : undefined;\n}\n"],"mappings":";;;;;;;;;AA0BA,MAAM,0BAA0B,IAAI,mBAAgC;AAEpE,SAAS,iBACP,eACA,IACA,iBACA,kBAAkB,OACf;CACH,MAAM,QAAQ,OAAO,OAAO;EAC1B,QAAQ,sBAAsB,cAAc;EAE5C,iBACE,oBACC,wBAAwB,UAAU,EAAE,mBAAmB;EAC3D,CAAC;AACF,QAAO,wBAAwB,uBAC7B,wBAAwB,IAAI,aAAa;AACvC,MAAI;GACF,MAAM,SAAS,IAAI;AACnB,OAAI,kBAAkB,QACpB,QAAO,OAAO,OAAO,UAAU;AAC7B,UAAM,uBAAuB,MAAM;KACnC;AAEJ,UAAO;WACA,OAAO;AACd,SAAM,uBAAuB,MAAM;;GAErC,CACH;;;AAIH,SAAgB,uBAAuB,OAAyB;CAC9D,MAAM,SAAS,kBAAkB;AACjC,KACE,CAAC,UACD,iBAAiB,wBACjB,CAAC,eAAe,MAAM,CAEtB,QAAO;AACT,QAAO,IAAI,qBAAqB,OAAO,iBAAiB;;;;;;;;;;AAW1D,SAAgB,mBACd,eACA,IACG;AACH,QAAO,iBAAiB,eAAe,GAAG;;;AAI5C,SAAgB,yBACd,QACA,IACG;AACH,QAAO,iBAAiB,QAAQ,IAAI,QAAW,KAAK;;;AAItD,SAAgB,sBAA+B;AAC7C,QAAO,wBAAwB,UAAU,EAAE,oBAAoB;;;AAIjE,SAAgB,iBACd,aACA,IACG;AACH,wBAAuB,oBAAoB,qBAAqB;AAChE,KAAI,EAAE,eAAe,gBAAgB,iBAAiB,YACpD,QAAO,iBACL,gBAAgB,YAAY,EAC5B,IACA,OAAO,OAAO,EAAE,aAAa,YAAY,aAAa,CAAC,EACvD,KACD;AAEH,QAAO,yBAAyB,gBAAgB,YAAY,EAAE,GAAG;;;;;;;;;;AAWnE,SAAgB,sBAEkB;CAChC,MAAM,gBAAgB,kBAAkB;AACxC,KAAI,cACF,QAAO,kBAAkB,eAAe,oBAAoB,CAAC;AAE/D,QAAO,eAAe,KAAK;;;;;AAM7B,SAAgB,yBAAiC;CAC/C,MAAM,SAAS,kBAAkB;AACjC,QAAO,SAAS,QAAQ,OAAO,UAAU,WAAW;;;AAItD,SAAgB,oBAAwC;AACtD,QAAO,kBAAkB,EAAE,UAAU;;;AAIvC,SAAgB,wBAAgC;AAC9C,QAAO,mBAAmB,IAAI,eAAe,KAAK,CAAC;;;;;;AAOrD,SAAgB,mBAA2B;AACzC,wBACE,oBACA,8DACD;AACD,QAAO,uBAAuB;;;;;AAMhC,SAAgB,qBAAqB;AACnC,SAAQ,kBAAkB,IAAI,eAAe,KAAK,EAAE;;;;;AAiBtD,SAAgB,iBAAkC;AAChD,SAAQ,kBAAkB,IAAI,eAAe,KAAK,EAAE;;;;;AAMtD,SAAgB,kBAA2B;AAEzC,QADY,wBAAwB,UAAU,KAC/B;;;;;;;AAQjB,SAAgB,sBAAyB,IAAgB;AACvD,QAAO,wBAAwB,KAAK,GAAG;;;;;;;AAQzC,SAAgB,mBAA8C;AAC5D,QAAO,wBAAwB,UAAU,EAAE;;;AAI7C,SAAgB,iBAA4D;AAC1E,wBAAuB,kBAAkB,mBAAmB;CAC5D,MAAM,SAAS,kBAAkB;AACjC,QAAO,SAAS,kBAAkB,QAAQ,oBAAoB,CAAC,GAAG"}

package/dist/context/index.d.ts

@@ -1,3 +1,4 @@
+import { UserContext, isUserContext } from "./user-context.js";
 import { ServiceContext } from "./service-context.js";
-import { UserContext } from "./user-context.js";
-import { getExecutionContext } from "./execution-context.js";
+import { CallerContext, CallerPrincipal, ExecutionContext } from "./caller-context.js";
+import { getCallerContext, getCurrentActorId, getCurrentPrincipalKey, getCurrentUserId, getExecutionContext, getUserContext, isInUserContext, runInCallerContext, runInUserContext } from "./execution-context.js";

package/dist/context/index.js

@@ -1,4 +1,6 @@
+import { isCallerContext } from "./caller-context.js";
+import { isUserContext } from "./user-context.js";
 import { ServiceContext } from "./service-context.js";
-import { getCurrentUserId, getExecutionContext, getWarehouseId, getWorkspaceClient, getWorkspaceId, runInUserContext } from "./execution-context.js";
+import { getCallerContext, getCurrentActorId, getCurrentPrincipalId, getCurrentPrincipalKey, getCurrentUserId, getExecutionContext, getUserContext, getWorkspaceClient, getWorkspaceId, isInUserContext, runInCallerContext, runInUserContext } from "./execution-context.js";
 
 export { getWorkspaceClient };

package/dist/context/request-scope.d.ts

@@ -0,0 +1,2 @@
+import "./service-context.js";
+import "express";

package/dist/context/request-scope.js

@@ -0,0 +1,39 @@
+import { AuthenticationError } from "../errors/authentication.js";
+import "../errors/index.js";
+import { createLogger } from "../logging/logger.js";
+import { ServiceContext } from "./service-context.js";
+import { runInCallerContext, runInLegacyCallerContext } from "./execution-context.js";
+import { hasOboResource } from "./resource-capabilities.js";
+import { context, createContextKey } from "@opentelemetry/api";
+
+//#region src/context/request-scope.ts
+const logger = createLogger("execution-context");
+const DEV_OBO_FALLBACK_KEY = createContextKey("appkit.devOboFallback");
+function isDevOboFallback() {
+	return context.active().getValue(DEV_OBO_FALLBACK_KEY) === true;
+}
+/** Build the caller once from the trusted Apps proxy headers. */
+function createRequestScope(req, resourceTypes = [], options = {}) {
+	const token = req.header("x-forwarded-access-token")?.trim();
+	const userId = req.header("x-forwarded-user")?.trim();
+	const userEmail = req.header("x-forwarded-email");
+	const isDev = process.env.NODE_ENV === "development";
+	if (!token && isDev) {
+		logger.warn("asUser() called without user token in development mode. Skipping user impersonation.");
+		return { run: (fn) => context.with(context.active().setValue(DEV_OBO_FALLBACK_KEY, true), fn) };
+	}
+	if (!token) {
+		if (hasOboResource(resourceTypes)) {
+			const message = "This resource is OBO-capable but no user token was forwarded. The app is likely deployed service-principal-only. Enable user authorization and forward x-forwarded-access-token.";
+			throw new AuthenticationError(message, { clientMessage: message });
+		}
+		throw AuthenticationError.missingToken("user token");
+	}
+	if (!userId && !isDev) throw AuthenticationError.missingUserId();
+	const caller = (options.createCaller ?? ServiceContext.createCallerContext)(token, userId || "dev-user", void 0, userEmail);
+	return { run: (fn) => options.legacy ? runInLegacyCallerContext(caller, fn) : runInCallerContext(caller, fn) };
+}
+
+//#endregion
+export { createRequestScope, isDevOboFallback };
+//# sourceMappingURL=request-scope.js.map

package/dist/context/request-scope.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"request-scope.js","names":["otelContext"],"sources":["../../src/context/request-scope.ts"],"sourcesContent":["import { createContextKey, context as otelContext } from \"@opentelemetry/api\";\nimport type { Request } from \"express\";\n\nimport { AuthenticationError } from \"../errors\";\nimport { createLogger } from \"../logging/logger\";\nimport {\n  runInCallerContext,\n  runInLegacyCallerContext,\n} from \"./execution-context\";\nimport { hasOboResource } from \"./resource-capabilities\";\nimport { ServiceContext } from \"./service-context\";\n\nconst logger = createLogger(\"execution-context\");\nconst DEV_OBO_FALLBACK_KEY = createContextKey(\"appkit.devOboFallback\");\n\n/** Internal scope shared by shorthand calls and the whole run block. */\nexport interface RequestScope {\n  run<T>(fn: () => T): T;\n}\n\nexport function isDevOboFallback(): boolean {\n  return otelContext.active().getValue(DEV_OBO_FALLBACK_KEY) === true;\n}\n\n/** Build the caller once from the trusted Apps proxy headers. */\nexport function createRequestScope(\n  req: Request,\n  resourceTypes: readonly string[] = [],\n  options: {\n    createCaller?: typeof ServiceContext.createCallerContext;\n    legacy?: boolean;\n  } = {},\n): RequestScope {\n  const token = req.header(\"x-forwarded-access-token\")?.trim();\n  const userId = req.header(\"x-forwarded-user\")?.trim();\n  const userEmail = req.header(\"x-forwarded-email\");\n  const isDev = process.env.NODE_ENV === \"development\";\n\n  if (!token && isDev) {\n    logger.warn(\n      \"asUser() called without user token in development mode. Skipping user impersonation.\",\n    );\n    return {\n      run: (fn) =>\n        otelContext.with(\n          otelContext.active().setValue(DEV_OBO_FALLBACK_KEY, true),\n          fn,\n        ),\n    };\n  }\n  if (!token) {\n    if (hasOboResource(resourceTypes)) {\n      const message =\n        \"This resource is OBO-capable but no user token was forwarded. The app is likely deployed service-principal-only. Enable user authorization and forward x-forwarded-access-token.\";\n      throw new AuthenticationError(message, { clientMessage: message });\n    }\n    throw AuthenticationError.missingToken(\"user token\");\n  }\n  if (!userId && !isDev) throw AuthenticationError.missingUserId();\n\n  const caller = (options.createCaller ?? ServiceContext.createCallerContext)(\n    token,\n    userId || \"dev-user\",\n    undefined,\n    userEmail,\n  );\n  return {\n    run: (fn) =>\n      options.legacy\n        ? runInLegacyCallerContext(caller, fn)\n        : runInCallerContext(caller, fn),\n  };\n}\n"],"mappings":";;;;;;;;;AAYA,MAAM,SAAS,aAAa,oBAAoB;AAChD,MAAM,uBAAuB,iBAAiB,wBAAwB;AAOtE,SAAgB,mBAA4B;AAC1C,QAAOA,QAAY,QAAQ,CAAC,SAAS,qBAAqB,KAAK;;;AAIjE,SAAgB,mBACd,KACA,gBAAmC,EAAE,EACrC,UAGI,EAAE,EACQ;CACd,MAAM,QAAQ,IAAI,OAAO,2BAA2B,EAAE,MAAM;CAC5D,MAAM,SAAS,IAAI,OAAO,mBAAmB,EAAE,MAAM;CACrD,MAAM,YAAY,IAAI,OAAO,oBAAoB;CACjD,MAAM,QAAQ,QAAQ,IAAI,aAAa;AAEvC,KAAI,CAAC,SAAS,OAAO;AACnB,SAAO,KACL,uFACD;AACD,SAAO,EACL,MAAM,OACJA,QAAY,KACVA,QAAY,QAAQ,CAAC,SAAS,sBAAsB,KAAK,EACzD,GACD,EACJ;;AAEH,KAAI,CAAC,OAAO;AACV,MAAI,eAAe,cAAc,EAAE;GACjC,MAAM,UACJ;AACF,SAAM,IAAI,oBAAoB,SAAS,EAAE,eAAe,SAAS,CAAC;;AAEpE,QAAM,oBAAoB,aAAa,aAAa;;AAEtD,KAAI,CAAC,UAAU,CAAC,MAAO,OAAM,oBAAoB,eAAe;CAEhE,MAAM,UAAU,QAAQ,gBAAgB,eAAe,qBACrD,OACA,UAAU,YACV,QACA,UACD;AACD,QAAO,EACL,MAAM,OACJ,QAAQ,SACJ,yBAAyB,QAAQ,GAAG,GACpC,mBAAmB,QAAQ,GAAG,EACrC"}

package/dist/context/resource-capabilities.js

@@ -0,0 +1,59 @@
+import { APP_ONLY_RESOURCE_TYPES, SCOPE_BY_TYPE } from "../shared/src/schemas/manifest.js";
+import { AppKitError } from "../errors/base.js";
+import { getCallerContext, isLegacyCallerScope } from "./execution-context.js";
+import { scopeApi } from "./scoped-api.js";
+
+//#region src/context/resource-capabilities.ts
+var AppOnlyResourceError = class extends AppKitError {
+	code = "APP_ONLY_RESOURCE";
+	statusCode = 400;
+	isRetryable = false;
+	constructor(type, name = type) {
+		const message = `Resource "${name}" is app-only in this version of AppKit and does not support OBO (on-behalf-of-user) execution. It runs as the service principal. Resource type: ${type}.`;
+		super(message, {
+			clientMessage: message,
+			context: { resourceType: type }
+		});
+	}
+};
+/** Read the same required/bound resource metadata used by provisioning. */
+function getPluginResources(plugin) {
+	const ctor = plugin.constructor;
+	const config = plugin.config;
+	const resources = ctor.manifest?.resources;
+	const optional = resources?.optional?.filter((resource) => Object.values(resource.fields).some((field) => field.env && process.env[field.env]?.trim())) ?? [];
+	const runtime = config && ctor.getResourceRequirements ? ctor.getResourceRequirements(config) : [];
+	return [
+		...resources?.required ?? [],
+		...optional,
+		...runtime.filter((resource) => resource.required)
+	];
+}
+function getPluginResourceTypes(plugin) {
+	return [...new Set(getPluginResources(plugin).map((resource) => resource.type))];
+}
+function hasOboResource(types) {
+	return types.some((type) => Object.hasOwn(SCOPE_BY_TYPE, type));
+}
+function isAppOnly(type) {
+	return APP_ONLY_RESOURCE_TYPES.has(type);
+}
+function assertResourceExecution(type) {
+	if (getCallerContext() && !isLegacyCallerScope() && isAppOnly(type)) throw new AppOnlyResourceError(type);
+}
+function assertPluginExecution(plugin, callerRequested = false) {
+	if (!callerRequested && (!getCallerContext() || isLegacyCallerScope())) return;
+	for (const resource of getPluginResources(plugin)) if (isAppOnly(resource.type)) throw new AppOnlyResourceError(resource.type, resource.alias?.trim() || resource.type);
+}
+/** Cached app handles still check the principal at invocation time. */
+function guardPluginApi(plugin, value) {
+	if (!getPluginResourceTypes(plugin).some(isAppOnly)) return value;
+	return scopeApi(value, { run: (fn) => {
+		assertPluginExecution(plugin);
+		return fn();
+	} }, plugin, true);
+}
+
+//#endregion
+export { assertPluginExecution, assertResourceExecution, getPluginResourceTypes, guardPluginApi, hasOboResource };
+//# sourceMappingURL=resource-capabilities.js.map

package/dist/context/resource-capabilities.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resource-capabilities.js","names":[],"sources":["../../src/context/resource-capabilities.ts"],"sourcesContent":["import {\n  APP_ONLY_RESOURCE_TYPES,\n  SCOPE_BY_TYPE,\n  type BasePluginConfig,\n  type PluginConstructor,\n} from \"shared\";\n\nimport { AppKitError } from \"../errors/base\";\nimport { getCallerContext, isLegacyCallerScope } from \"./execution-context\";\nimport { scopeApi } from \"./scoped-api\";\n\nclass AppOnlyResourceError extends AppKitError {\n  readonly code = \"APP_ONLY_RESOURCE\";\n  readonly statusCode = 400;\n  readonly isRetryable = false;\n  constructor(type: string, name = type) {\n    const message = `Resource \"${name}\" is app-only in this version of AppKit and does not support OBO (on-behalf-of-user) execution. It runs as the service principal. Resource type: ${type}.`;\n    super(message, { clientMessage: message, context: { resourceType: type } });\n  }\n}\n\n/** Read the same required/bound resource metadata used by provisioning. */\nfunction getPluginResources(plugin: object) {\n  const ctor = plugin.constructor as Partial<PluginConstructor>;\n  const config = (plugin as { config?: BasePluginConfig }).config;\n  const resources = ctor.manifest?.resources;\n  const optional =\n    resources?.optional?.filter((resource) =>\n      Object.values(resource.fields).some(\n        (field) => field.env && process.env[field.env]?.trim(),\n      ),\n    ) ?? [];\n  const runtime =\n    config && ctor.getResourceRequirements\n      ? ctor.getResourceRequirements(config)\n      : [];\n  return [\n    ...(resources?.required ?? []),\n    ...optional,\n    ...runtime.filter((resource) => resource.required),\n  ];\n}\n\nexport function getPluginResourceTypes(plugin: object): string[] {\n  return [\n    ...new Set(getPluginResources(plugin).map((resource) => resource.type)),\n  ];\n}\n\nexport function hasOboResource(types: readonly string[]): boolean {\n  return types.some((type) => Object.hasOwn(SCOPE_BY_TYPE, type));\n}\n\nfunction isAppOnly(type: string): boolean {\n  return (APP_ONLY_RESOURCE_TYPES as ReadonlySet<string>).has(type);\n}\n\nexport function assertResourceExecution(type: string): void {\n  if (getCallerContext() && !isLegacyCallerScope() && isAppOnly(type))\n    throw new AppOnlyResourceError(type);\n}\n\nexport function assertPluginExecution(\n  plugin: object,\n  callerRequested = false,\n): void {\n  if (!callerRequested && (!getCallerContext() || isLegacyCallerScope()))\n    return;\n  for (const resource of getPluginResources(plugin)) {\n    if (isAppOnly(resource.type)) {\n      throw new AppOnlyResourceError(\n        resource.type,\n        resource.alias?.trim() || resource.type,\n      );\n    }\n  }\n}\n\n/** Cached app handles still check the principal at invocation time. */\nexport function guardPluginApi<T>(plugin: object, value: T): T {\n  if (!getPluginResourceTypes(plugin).some(isAppOnly)) return value;\n  return scopeApi(\n    value,\n    {\n      run: (fn) => {\n        assertPluginExecution(plugin);\n        return fn();\n      },\n    },\n    plugin,\n    true,\n  );\n}\n"],"mappings":";;;;;;AAWA,IAAM,uBAAN,cAAmC,YAAY;CAC7C,AAAS,OAAO;CAChB,AAAS,aAAa;CACtB,AAAS,cAAc;CACvB,YAAY,MAAc,OAAO,MAAM;EACrC,MAAM,UAAU,aAAa,KAAK,mJAAmJ,KAAK;AAC1L,QAAM,SAAS;GAAE,eAAe;GAAS,SAAS,EAAE,cAAc,MAAM;GAAE,CAAC;;;;AAK/E,SAAS,mBAAmB,QAAgB;CAC1C,MAAM,OAAO,OAAO;CACpB,MAAM,SAAU,OAAyC;CACzD,MAAM,YAAY,KAAK,UAAU;CACjC,MAAM,WACJ,WAAW,UAAU,QAAQ,aAC3B,OAAO,OAAO,SAAS,OAAO,CAAC,MAC5B,UAAU,MAAM,OAAO,QAAQ,IAAI,MAAM,MAAM,MAAM,CACvD,CACF,IAAI,EAAE;CACT,MAAM,UACJ,UAAU,KAAK,0BACX,KAAK,wBAAwB,OAAO,GACpC,EAAE;AACR,QAAO;EACL,GAAI,WAAW,YAAY,EAAE;EAC7B,GAAG;EACH,GAAG,QAAQ,QAAQ,aAAa,SAAS,SAAS;EACnD;;AAGH,SAAgB,uBAAuB,QAA0B;AAC/D,QAAO,CACL,GAAG,IAAI,IAAI,mBAAmB,OAAO,CAAC,KAAK,aAAa,SAAS,KAAK,CAAC,CACxE;;AAGH,SAAgB,eAAe,OAAmC;AAChE,QAAO,MAAM,MAAM,SAAS,OAAO,OAAO,eAAe,KAAK,CAAC;;AAGjE,SAAS,UAAU,MAAuB;AACxC,QAAQ,wBAAgD,IAAI,KAAK;;AAGnE,SAAgB,wBAAwB,MAAoB;AAC1D,KAAI,kBAAkB,IAAI,CAAC,qBAAqB,IAAI,UAAU,KAAK,CACjE,OAAM,IAAI,qBAAqB,KAAK;;AAGxC,SAAgB,sBACd,QACA,kBAAkB,OACZ;AACN,KAAI,CAAC,oBAAoB,CAAC,kBAAkB,IAAI,qBAAqB,EACnE;AACF,MAAK,MAAM,YAAY,mBAAmB,OAAO,CAC/C,KAAI,UAAU,SAAS,KAAK,CAC1B,OAAM,IAAI,qBACR,SAAS,MACT,SAAS,OAAO,MAAM,IAAI,SAAS,KACpC;;;AAMP,SAAgB,eAAkB,QAAgB,OAAa;AAC7D,KAAI,CAAC,uBAAuB,OAAO,CAAC,KAAK,UAAU,CAAE,QAAO;AAC5D,QAAO,SACL,OACA,EACE,MAAM,OAAO;AACX,wBAAsB,OAAO;AAC7B,SAAO,IAAI;IAEd,EACD,QACA,KACD"}

package/dist/context/scoped-api.js

@@ -0,0 +1,104 @@
+import { isPlainObject } from "../utils/is-plain-object.js";
+import { Readable } from "node:stream";
+
+//#region src/context/scoped-api.ts
+const EXCLUDED_FROM_PROXY = new Set([
+	"setup",
+	"shutdown",
+	"attachContext",
+	"injectRoutes",
+	"getEndpoints",
+	"getSkipBodyParsingPaths",
+	"abortActiveOperations",
+	"clientConfig",
+	"constructor"
+]);
+const IDENTITY_METHODS = new Set(["asUser"]);
+function isIdentityMethod(key) {
+	return IDENTITY_METHODS.has(key);
+}
+function isNativeStream(value) {
+	return typeof ReadableStream !== "undefined" && value instanceof ReadableStream || value instanceof Readable;
+}
+/**
+* Whether a value can run code later and so must run in the caller scope:
+* a function, a Promise, a non-native async iterable, or a plain object
+* reaching one of those through its own properties. Getter properties count,
+* and are not invoked here. Arrays and other objects are plain data, as before.
+*/
+function needsScope(value, seen = /* @__PURE__ */ new Set()) {
+	if (typeof value === "function" || value instanceof Promise) return true;
+	if (!value || typeof value !== "object" || isNativeStream(value)) return false;
+	if (Symbol.asyncIterator in value) return true;
+	if (!isPlainObject(value) || seen.has(value)) return false;
+	seen.add(value);
+	return Reflect.ownKeys(value).some((key) => {
+		const descriptor = Object.getOwnPropertyDescriptor(value, key);
+		return descriptor?.get !== void 0 || needsScope(descriptor?.value, seen);
+	});
+}
+/** Preserve identity across callable exports, returned handles, and lazy streams. */
+function scopeApi(value, scope, receiver, preserveIdentityMethods = false) {
+	if (typeof value === "function") return new Proxy(value, {
+		apply: (fn, thisArg, args) => {
+			const result = scope.run(() => Reflect.apply(fn, receiver ?? thisArg, args));
+			if (preserveIdentityMethods) return result;
+			return scopeApi(result, scope);
+		},
+		get: (fn, key) => !preserveIdentityMethods && isIdentityMethod(key) ? void 0 : scopeApi(Reflect.get(fn, key), scope, fn, preserveIdentityMethods)
+	});
+	if (value instanceof Promise) return value.then((result) => scopeApi(result, scope, void 0, preserveIdentityMethods));
+	if (isNativeStream(value)) return value;
+	if (value && typeof value === "object" && Symbol.asyncIterator in value) {
+		const iterable = value;
+		const wrapIterator = (iterator) => {
+			const finish = iterator.return?.bind(iterator);
+			const fail = iterator.throw?.bind(iterator);
+			return {
+				[Symbol.asyncIterator]() {
+					return this;
+				},
+				next: (...args) => scope.run(() => iterator.next(...args)),
+				...finish && { return: (result) => scope.run(() => finish(result)) },
+				...fail && { throw: (error) => scope.run(() => fail(error)) }
+			};
+		};
+		if ("next" in value && typeof value.next === "function") return wrapIterator(value);
+		return { [Symbol.asyncIterator]: () => wrapIterator(scope.run(() => iterable[Symbol.asyncIterator]())) };
+	}
+	if (isPlainObject(value)) {
+		if (!needsScope(value)) return value;
+		const result = Object.create(Object.getPrototypeOf(value));
+		for (const key of Reflect.ownKeys(value)) {
+			if (!preserveIdentityMethods && isIdentityMethod(key)) continue;
+			Object.defineProperty(result, key, {
+				enumerable: Object.getOwnPropertyDescriptor(value, key)?.enumerable,
+				configurable: true,
+				get: () => {
+					const member = scope.run(() => Reflect.get(value, key));
+					return needsScope(member) ? scopeApi(member, scope, receiver ?? value, preserveIdentityMethods) : member;
+				},
+				set: (next) => {
+					Reflect.set(value, key, next);
+				}
+			});
+		}
+		return result;
+	}
+	return value;
+}
+/** Compatibility adapter for direct Plugin.asUser callers. */
+function scopePlugin(plugin, scope) {
+	return new Proxy(plugin, { get(target, key) {
+		if (isIdentityMethod(key)) return void 0;
+		const value = Reflect.get(target, key, target);
+		if (typeof key === "string" && EXCLUDED_FROM_PROXY.has(key)) return value;
+		if (key === "exports" && typeof value === "function") return () => scopeApi(scope.run(() => value.call(target)) ?? {}, scope, target);
+		if (typeof value === "function") return (...args) => scope.run(() => Reflect.apply(value, target, args));
+		return scopeApi(value, scope, target);
+	} });
+}
+
+//#endregion
+export { scopeApi, scopePlugin };
+//# sourceMappingURL=scoped-api.js.map

package/dist/context/scoped-api.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scoped-api.js","names":[],"sources":["../../src/context/scoped-api.ts"],"sourcesContent":["import { Readable } from \"node:stream\";\n\nimport { isPlainObject } from \"../utils/is-plain-object\";\nimport type { RequestScope } from \"./request-scope\";\n\nconst EXCLUDED_FROM_PROXY = new Set([\n  \"setup\",\n  \"shutdown\",\n  \"attachContext\",\n  \"injectRoutes\",\n  \"getEndpoints\",\n  \"getSkipBodyParsingPaths\",\n  \"abortActiveOperations\",\n  \"clientConfig\",\n  \"constructor\",\n]);\n\n// Methods that would re-scope a scoped surface to another identity. Only\n// these are hidden; other `as*` names (asCsv, asArrow) are ordinary exports.\nconst IDENTITY_METHODS: ReadonlySet<PropertyKey> = new Set([\"asUser\"]);\n\nfunction isIdentityMethod(key: PropertyKey): boolean {\n  return IDENTITY_METHODS.has(key);\n}\n\nfunction isNativeStream(value: unknown): boolean {\n  return (\n    (typeof ReadableStream !== \"undefined\" &&\n      value instanceof ReadableStream) ||\n    value instanceof Readable\n  );\n}\n\n/**\n * Whether a value can run code later and so must run in the caller scope:\n * a function, a Promise, a non-native async iterable, or a plain object\n * reaching one of those through its own properties. Getter properties count,\n * and are not invoked here. Arrays and other objects are plain data, as before.\n */\nfunction needsScope(value: unknown, seen = new Set<object>()): boolean {\n  if (typeof value === \"function\" || value instanceof Promise) return true;\n  if (!value || typeof value !== \"object\" || isNativeStream(value)) {\n    return false;\n  }\n  if (Symbol.asyncIterator in value) return true;\n  if (!isPlainObject(value) || seen.has(value)) return false;\n  seen.add(value);\n  return Reflect.ownKeys(value).some((key) => {\n    const descriptor = Object.getOwnPropertyDescriptor(value, key);\n    return descriptor?.get !== undefined || needsScope(descriptor?.value, seen);\n  });\n}\n\n/** Preserve identity across callable exports, returned handles, and lazy streams. */\nexport function scopeApi<T>(\n  value: T,\n  scope: RequestScope,\n  receiver?: unknown,\n  preserveIdentityMethods = false,\n): T {\n  if (typeof value === \"function\") {\n    return new Proxy(value, {\n      apply: (fn, thisArg, args) => {\n        const result = scope.run(() =>\n          Reflect.apply(fn, receiver ?? thisArg, args),\n        );\n        // Ambient resource guards must not change ordinary SP result objects.\n        if (preserveIdentityMethods) return result;\n        return scopeApi(result, scope);\n      },\n      get: (fn, key) =>\n        !preserveIdentityMethods && isIdentityMethod(key)\n          ? undefined\n          : scopeApi(Reflect.get(fn, key), scope, fn, preserveIdentityMethods),\n    });\n  }\n  if (value instanceof Promise) {\n    return value.then((result) =>\n      scopeApi(result, scope, undefined, preserveIdentityMethods),\n    ) as T;\n  }\n  // Native streams pass through unchanged. The authenticated request already\n  // ran inside the caller scope; reading the body is pure data with no\n  // deferred identity work, and wrapping would strip getReader/pipe/cancel.\n  if (isNativeStream(value)) {\n    return value;\n  }\n  if (value && typeof value === \"object\" && Symbol.asyncIterator in value) {\n    const iterable = value as AsyncIterable<unknown>;\n    const wrapIterator = (\n      iterator: AsyncIterator<unknown>,\n    ): AsyncIterableIterator<unknown> => {\n      const finish = iterator.return?.bind(iterator);\n      const fail = iterator.throw?.bind(iterator);\n      return {\n        [Symbol.asyncIterator]() {\n          return this;\n        },\n        next: (...args: [] | [unknown]) =>\n          scope.run(() => iterator.next(...args)),\n        ...(finish && {\n          return: (result?: unknown) => scope.run(() => finish(result)),\n        }),\n        ...(fail && {\n          throw: (error?: unknown) => scope.run(() => fail(error)),\n        }),\n      };\n    };\n    if (\"next\" in value && typeof value.next === \"function\") {\n      return wrapIterator(value as AsyncIterableIterator<unknown>) as T;\n    }\n    return {\n      [Symbol.asyncIterator]: () =>\n        wrapIterator(scope.run(() => iterable[Symbol.asyncIterator]())),\n    } as T;\n  }\n  if (isPlainObject(value)) {\n    // Plain data results come back unchanged: mutable and identity-stable.\n    if (!needsScope(value)) return value;\n    const result = Object.create(Object.getPrototypeOf(value));\n    for (const key of Reflect.ownKeys(value)) {\n      if (!preserveIdentityMethods && isIdentityMethod(key)) continue;\n      Object.defineProperty(result, key, {\n        enumerable: Object.getOwnPropertyDescriptor(value, key)?.enumerable,\n        configurable: true,\n        get: () => {\n          const member = scope.run(() => Reflect.get(value, key));\n          // Data members are returned as-is so repeated reads are identical.\n          return needsScope(member)\n            ? scopeApi(\n                member,\n                scope,\n                receiver ?? value,\n                preserveIdentityMethods,\n              )\n            : member;\n        },\n        set: (next: unknown) => {\n          Reflect.set(value, key, next);\n        },\n      });\n    }\n    return result;\n  }\n  return value;\n}\n\n/** Compatibility adapter for direct Plugin.asUser callers. */\nexport function scopePlugin<T extends object>(\n  plugin: T,\n  scope: RequestScope,\n): T {\n  return new Proxy(plugin, {\n    get(target, key) {\n      if (isIdentityMethod(key)) return undefined;\n      const value = Reflect.get(target, key, target);\n      if (typeof key === \"string\" && EXCLUDED_FROM_PROXY.has(key)) return value;\n      if (key === \"exports\" && typeof value === \"function\") {\n        return () =>\n          scopeApi(scope.run(() => value.call(target)) ?? {}, scope, target);\n      }\n      if (typeof value === \"function\") {\n        return (...args: unknown[]) =>\n          scope.run(() => Reflect.apply(value, target, args));\n      }\n      return scopeApi(value, scope, target);\n    },\n  });\n}\n"],"mappings":"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"}

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

@@ -1,24 +1,28 @@
 import { ClientOptions, WorkspaceClient } from "../workspace-client/index.js";
 import { UserContext } from "./user-context.js";
+import { CallerContext } from "./caller-context.js";
 
 //#region src/context/service-context.d.ts
 /**
- * Service context holds the service principal client and shared resources.
+ * Service context holds the service principal identity and workspace client.
  * This is initialized once at app startup and shared across all requests.
  */
 interface ServiceContextState {
   /** WorkspaceClient authenticated as the service principal */
-  client: WorkspaceClient;
+  readonly client: WorkspaceClient;
   /** The service principal's user ID */
-  serviceUserId: string;
-  /** Promise that resolves to the warehouse ID (only present when a plugin requires `SQL_WAREHOUSE` resource) */
-  warehouseId?: Promise<string>;
+  readonly serviceUserId: string;
+  /**
+   * @deprecated Use getWarehouseId() from @databricks/appkit.
+   * Retained for backward compatibility.
+   */
+  readonly warehouseId?: Promise<string>;
   /** Promise that resolves to the workspace ID */
-  workspaceId: Promise<string>;
+  readonly workspaceId: Promise<string>;
 }
 /**
  * ServiceContext is a singleton that manages the service principal's
- * WorkspaceClient and shared resources like warehouse/workspace IDs.
+ * WorkspaceClient and workspace ID. WarehouseResource owns warehouse bindings.
  *
  * It's initialized once at app startup and provides the foundation
  * for both service principal and user context execution.
@@ -30,12 +34,12 @@ declare class ServiceContext {
    * Initialize the service context. Should be called once at app startup.
    * Safe to call multiple times - will return the same instance.
    *
-   * @param options - Which shared resources to resolve (derived from plugin manifests).
+   * @param options - A resolved warehouse ID, or a boolean enabling discovery.
    * @param client - Optional pre-configured WorkspaceClient to use instead
    *   of creating one from environment credentials.
    */
   static initialize(options?: {
-    warehouseId?: boolean;
+    warehouseId?: boolean | string;
   }, client?: WorkspaceClient): Promise<ServiceContextState>;
   /**
    * Get the initialized service context.
@@ -47,14 +51,17 @@ declare class ServiceContext {
    */
   static isInitialized(): boolean;
   /**
-   * Create a user context from request headers.
+   * Create an immutable caller context from the existing user request headers.
    *
    * @param token - The user's access token from x-forwarded-access-token header
    * @param userId - The user's ID from x-forwarded-user header
    * @param userName - Optional user name
+   * @param userEmail - Optional email from x-forwarded-email
    * @throws Error if token is not provided
    */
-  static createUserContext(token: string, userId: string, userName?: string, userEmail?: string): UserContext;
+  static createCallerContext(token: string, userId: string, userName?: string, userEmail?: string): CallerContext;
+  /** @deprecated Use ServiceContext.createCallerContext. */
+  static createUserContext(token: string, userId: string, userName?: string, userEmail?: string): CallerContext & UserContext;
   /**
    * Get the client options for WorkspaceClient.
    * Exposed for testing purposes.
@@ -62,7 +69,6 @@ declare class ServiceContext {
   static getClientOptions(): ClientOptions;
   private static createContext;
   private static getWorkspaceId;
-  private static getWarehouseId;
   /**
    * Reset the service context. Only for testing purposes.
    */

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;;;;;;AAUf;;cAAa,cAAA;EAAA,eACI,QAAA;EAAA,eACA,WAAA;EAaZ;;;;;;;;EAAA,OAHU,UAAA,CACX,OAAA;IAAY,WAAA;EAAA,GACZ,MAAA,GAAS,eAAA,GACR,OAAA,CAAQ,mBAAA;EADA;;;;EAAA,OAmBJ,GAAA,CAAA,GAAO,mBAAA;EAAA;;;EAAA,OAaP,aAAA,CAAA;EAcL;;;;;;;;EAAA,OAFK,iBAAA,CACL,KAAA,UACA,MAAA,UACA,QAAA,WACA,SAAA,YACC,WAAA;EAqLI;;;;EAAA,OA1IA,gBAAA,CAAA,GAAoB,aAAA;EAAA,eAIN,aAAA;EAAA,eA2CA,cAAA;EAAA,eAuBA,cAAA;;;;SAoEd,KAAA,CAAA;AAAA"}
+{"version":3,"file":"service-context.d.ts","names":[],"sources":["../../src/context/service-context.ts"],"mappings":";;;;;;;AAuBA;;UAAiB,mBAAA;EAEE;EAAA,SAAR,MAAA,EAAQ,eAAA;EASK;EAAA,SAPb,aAAA;EAOoB;;;;EAAA,SAFpB,WAAA,GAAc,OAAA;EAAA;EAAA,SAEd,WAAA,EAAa,OAAA;AAAA;;;AAUxB;;;;;cAAa,cAAA;EAAA,eACI,QAAA;EAAA,eACA,WAAA;EA4GZ;;;;;;;;EAAA,OAlGU,UAAA,CACX,OAAA;IAAY,WAAA;EAAA,GACZ,MAAA,GAAS,eAAA,GACR,OAAA,CAAQ,mBAAA;EADT;;;;EAAA,OAmBK,GAAA,CAAA,GAAO,mBAAA;EAaP;;;EAAA,OAAA,aAAA,CAAA;EAgBL;;;;;;;;;EAAA,OAHK,mBAAA,CACL,KAAA,UACA,MAAA,UACA,QAAA,WACA,SAAA,YACC,aAAA;EAiEI;EAAA,OAxBA,iBAAA,CACL,KAAA,UACA,MAAA,UACA,QAAA,WACA,SAAA,YACC,aAAA,GAAgB,WAAA;EAuBE;;;;EAAA,OAJd,gBAAA,CAAA,GAAoB,aAAA;EAAA,eAIN,aAAA;EAAA,eA4CA,cAAA;;;;SA0Bd,KAAA,CAAA;AAAA"}

package/dist/context/service-context.js

@@ -5,12 +5,16 @@ import { AuthenticationError } from "../errors/authentication.js";
 import { ConfigurationError } from "../errors/configuration.js";
 import { InitializationError } from "../errors/initialization.js";
 import "../errors/index.js";
+import { WarehouseResource } from "../resources/warehouse.js";
+import { snapshotCallerContext } from "./caller-context.js";
+import { warnContextDeprecation } from "./deprecation.js";
+import { legacyUserContext } from "./user-context.js";
 import { createHash } from "node:crypto";
 
 //#region src/context/service-context.ts
 /**
 * ServiceContext is a singleton that manages the service principal's
-* WorkspaceClient and shared resources like warehouse/workspace IDs.
+* WorkspaceClient and workspace ID. WarehouseResource owns warehouse bindings.
 *
 * It's initialized once at app startup and provides the foundation
 * for both service principal and user context execution.
@@ -22,7 +26,7 @@ var ServiceContext = class ServiceContext {
 	* Initialize the service context. Should be called once at app startup.
 	* Safe to call multiple times - will return the same instance.
 	*
-	* @param options - Which shared resources to resolve (derived from plugin manifests).
+	* @param options - A resolved warehouse ID, or a boolean enabling discovery.
 	* @param client - Optional pre-configured WorkspaceClient to use instead
 	*   of creating one from environment credentials.
 	*/
@@ -48,33 +52,44 @@ var ServiceContext = class ServiceContext {
 		return ServiceContext.instance !== null;
 	}
 	/**
-	* Create a user context from request headers.
+	* Create an immutable caller context from the existing user request headers.
 	*
 	* @param token - The user's access token from x-forwarded-access-token header
 	* @param userId - The user's ID from x-forwarded-user header
 	* @param userName - Optional user name
+	* @param userEmail - Optional email from x-forwarded-email
 	* @throws Error if token is not provided
 	*/
-	static createUserContext(token, userId, userName, userEmail) {
+	static createCallerContext(token, userId, userName, userEmail) {
 		if (!token) throw AuthenticationError.missingToken("user token");
-		const host = process.env.DATABRICKS_HOST;
+		const host = process.env.DATABRICKS_HOST || (process.env.NODE_ENV === "development" && ServiceContext.isInitialized() ? ServiceContext.get().client.config?.host : void 0);
 		if (!host) throw ConfigurationError.missingEnvVar("DATABRICKS_HOST");
 		const serviceCtx = ServiceContext.get();
-		return {
-			client: createWorkspaceClient({
-				token,
-				host,
-				authType: "pat",
-				clientOptions: getClientOptions()
-			}),
-			userId,
-			userName,
-			userEmail,
-			tokenFingerprint: createHash("sha256").update(token).digest("hex").slice(0, 16),
-			warehouseId: serviceCtx.warehouseId,
-			workspaceId: serviceCtx.workspaceId,
-			isUserContext: true
-		};
+		const userClient = createWorkspaceClient({
+			token,
+			host,
+			authType: "pat",
+			clientOptions: getClientOptions()
+		});
+		const tokenFingerprint = createHash("sha256").update(token).digest("hex").slice(0, 16);
+		return snapshotCallerContext({
+			client: userClient,
+			principal: {
+				type: "user",
+				userId,
+				userName,
+				userEmail
+			},
+			tokenFingerprint,
+			workspaceId: serviceCtx.workspaceId
+		});
+	}
+	/** @deprecated Use ServiceContext.createCallerContext. */
+	static createUserContext(token, userId, userName, userEmail) {
+		warnContextDeprecation("ServiceContext.createUserContext", "ServiceContext.createCallerContext");
+		const caller = ServiceContext.createCallerContext(token, userId, userName, userEmail);
+		const warehouseId = WarehouseResource.get()?.warehouseId;
+		return legacyUserContext(caller, () => warehouseId);
 	}
 	/**
 	* Get the client options for WorkspaceClient.
@@ -86,19 +101,22 @@ var ServiceContext = class ServiceContext {
 	static async createContext(options, client) {
 		try {
 			const wsClient = client ?? createWorkspaceClient({ clientOptions: getClientOptions() });
-			const [resolvedWorkspaceId, currentUser, resolvedWarehouseId] = await Promise.all([
+			const [resolvedWorkspaceId, currentUser, resolvedResources] = await Promise.all([
 				ServiceContext.getWorkspaceId(wsClient),
 				wsClient.currentUser.me(),
-				options?.warehouseId ? ServiceContext.getWarehouseId(wsClient) : Promise.resolve(void 0)
+				WarehouseResource.resolve(wsClient, options?.warehouseId)
 			]);
 			if (!currentUser.id) throw ConfigurationError.resourceNotFound("Service user ID");
-			const warehouseId = options?.warehouseId && resolvedWarehouseId !== void 0 ? Promise.resolve(resolvedWarehouseId) : void 0;
-			return {
+			const resources = WarehouseResource.bind(resolvedResources);
+			return Object.freeze({
 				client: wsClient,
 				serviceUserId: currentUser.id,
-				warehouseId,
+				get warehouseId() {
+					warnContextDeprecation("ServiceContextState.warehouseId", "getWarehouseId() from @databricks/appkit");
+					return resources.warehouseId;
+				},
 				workspaceId: Promise.resolve(resolvedWorkspaceId)
-			};
+			});
 		} catch (e) {
 			if (e instanceof ConfigError) throw ConfigurationError.databricksAuthenticationSetupFailed(e.baseMessage, { cause: e });
 			throw e;
@@ -117,41 +135,13 @@ var ServiceContext = class ServiceContext {
 		if (!response["x-databricks-org-id"]) throw ConfigurationError.resourceNotFound("Workspace ID");
 		return response["x-databricks-org-id"];
 	}
-	static async getWarehouseId(client) {
-		if (process.env.DATABRICKS_WAREHOUSE_ID) return process.env.DATABRICKS_WAREHOUSE_ID;
-		const agenticMode = process.env.DATABRICKS_APPS_AGENTIC_MODE === "true" || process.env.DATABRICKS_APPS_AGENTIC_MODE === "1";
-		if (process.env.NODE_ENV === "development" && !agenticMode) {
-			const response = await client.apiClient.request({
-				path: "/api/2.0/sql/warehouses",
-				method: "GET",
-				headers: new Headers(),
-				raw: false,
-				query: { skip_cannot_use: "true" }
-			});
-			const priorities = {
-				RUNNING: 0,
-				STOPPED: 1,
-				STARTING: 2,
-				STOPPING: 3,
-				DELETED: 99,
-				DELETING: 99
-			};
-			const warehouses = (response.warehouses || []).sort((a, b) => {
-				return priorities[a.state] - priorities[b.state];
-			});
-			if (response.warehouses.length === 0) throw ConfigurationError.resourceNotFound("Warehouse ID", "Please configure the DATABRICKS_WAREHOUSE_ID environment variable");
-			const firstWarehouse = warehouses[0];
-			if (firstWarehouse.state === "DELETED" || firstWarehouse.state === "DELETING" || !firstWarehouse.id) throw ConfigurationError.resourceNotFound("Warehouse ID", "Please configure the DATABRICKS_WAREHOUSE_ID environment variable");
-			return firstWarehouse.id;
-		}
-		throw ConfigurationError.resourceNotFound("Warehouse ID", "Please configure the DATABRICKS_WAREHOUSE_ID environment variable");
-	}
 	/**
 	* Reset the service context. Only for testing purposes.
 	*/
 	static reset() {
 		ServiceContext.instance = null;
 		ServiceContext.initPromise = null;
+		WarehouseResource.reset();
 	}
 };
 

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

@@ -1 +1 @@
-{"version":3,"file":"service-context.js","names":[],"sources":["../../src/context/service-context.ts"],"sourcesContent":["import { createHash } from \"node:crypto\";\n\nimport {\n  AuthenticationError,\n  ConfigurationError,\n  InitializationError,\n} from \"../errors\";\nimport {\n  type ClientOptions,\n  ConfigError,\n  createWorkspaceClient,\n  type sql,\n  type WorkspaceClient,\n} from \"../workspace-client\";\nimport { getClientOptions } from \"./client-options\";\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\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    userEmail?: 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 = createWorkspaceClient({\n      token,\n      host,\n      authType: \"pat\",\n      clientOptions: getClientOptions(),\n    });\n\n    const tokenFingerprint = createHash(\"sha256\")\n      .update(token)\n      .digest(\"hex\")\n      .slice(0, 16);\n\n    return {\n      client: userClient,\n      userId,\n      userName,\n      userEmail,\n      tokenFingerprint,\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 =\n        client ?? createWorkspaceClient({ clientOptions: 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    const agenticMode =\n      process.env.DATABRICKS_APPS_AGENTIC_MODE === \"true\" ||\n      process.env.DATABRICKS_APPS_AGENTIC_MODE === \"1\";\n\n    if (process.env.NODE_ENV === \"development\" && !agenticMode) {\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":[],"sources":["../../src/context/service-context.ts"],"sourcesContent":["import { createHash } from \"node:crypto\";\n\nimport {\n  AuthenticationError,\n  ConfigurationError,\n  InitializationError,\n} from \"../errors\";\nimport { WarehouseResource } from \"../resources/warehouse\";\nimport {\n  type ClientOptions,\n  ConfigError,\n  createWorkspaceClient,\n  type WorkspaceClient,\n} from \"../workspace-client\";\nimport { type CallerContext, snapshotCallerContext } from \"./caller-context\";\nimport { getClientOptions } from \"./client-options\";\nimport { warnContextDeprecation } from \"./deprecation\";\nimport { legacyUserContext, type UserContext } from \"./user-context\";\n\n/**\n * Service context holds the service principal identity and workspace client.\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  readonly client: WorkspaceClient;\n  /** The service principal's user ID */\n  readonly serviceUserId: string;\n  /**\n   * @deprecated Use getWarehouseId() from @databricks/appkit.\n   * Retained for backward compatibility.\n   */\n  readonly warehouseId?: Promise<string>;\n  /** Promise that resolves to the workspace ID */\n  readonly workspaceId: Promise<string>;\n}\n\n/**\n * ServiceContext is a singleton that manages the service principal's\n * WorkspaceClient and workspace ID. WarehouseResource owns warehouse bindings.\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 - A resolved warehouse ID, or a boolean enabling discovery.\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 | string },\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 an immutable caller context from the existing user 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   * @param userEmail - Optional email from x-forwarded-email\n   * @throws Error if token is not provided\n   */\n  static createCallerContext(\n    token: string,\n    userId: string,\n    userName?: string,\n    userEmail?: string,\n  ): CallerContext {\n    if (!token) {\n      throw AuthenticationError.missingToken(\"user token\");\n    }\n\n    // Local templates can configure only a profile, whose host the SDK resolved.\n    const host =\n      process.env.DATABRICKS_HOST ||\n      (process.env.NODE_ENV === \"development\" && ServiceContext.isInitialized()\n        ? ServiceContext.get().client.config?.host\n        : undefined);\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 = createWorkspaceClient({\n      token,\n      host,\n      authType: \"pat\",\n      clientOptions: getClientOptions(),\n    });\n\n    const tokenFingerprint = createHash(\"sha256\")\n      .update(token)\n      .digest(\"hex\")\n      .slice(0, 16);\n\n    return snapshotCallerContext({\n      client: userClient,\n      principal: { type: \"user\", userId, userName, userEmail },\n      tokenFingerprint,\n      workspaceId: serviceCtx.workspaceId,\n    });\n  }\n\n  /** @deprecated Use ServiceContext.createCallerContext. */\n  static createUserContext(\n    token: string,\n    userId: string,\n    userName?: string,\n    userEmail?: string,\n  ): CallerContext & UserContext {\n    warnContextDeprecation(\n      \"ServiceContext.createUserContext\",\n      \"ServiceContext.createCallerContext\",\n    );\n    const caller = ServiceContext.createCallerContext(\n      token,\n      userId,\n      userName,\n      userEmail,\n    );\n    const warehouseId = WarehouseResource.get()?.warehouseId;\n    return legacyUserContext(caller, () => warehouseId);\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 | string },\n    client?: WorkspaceClient,\n  ): Promise<ServiceContextState> {\n    try {\n      const wsClient =\n        client ?? createWorkspaceClient({ clientOptions: getClientOptions() });\n\n      const [resolvedWorkspaceId, currentUser, resolvedResources] =\n        await Promise.all([\n          ServiceContext.getWorkspaceId(wsClient),\n          wsClient.currentUser.me(),\n          WarehouseResource.resolve(wsClient, options?.warehouseId),\n        ]);\n\n      if (!currentUser.id) {\n        throw ConfigurationError.resourceNotFound(\"Service user ID\");\n      }\n\n      const resources = WarehouseResource.bind(resolvedResources);\n\n      return Object.freeze({\n        client: wsClient,\n        serviceUserId: currentUser.id,\n        get warehouseId() {\n          warnContextDeprecation(\n            \"ServiceContextState.warehouseId\",\n            \"getWarehouseId() from @databricks/appkit\",\n          );\n          return resources.warehouseId;\n        },\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  /**\n   * Reset the service context. Only for testing purposes.\n   */\n  static reset(): void {\n    ServiceContext.instance = null;\n    ServiceContext.initPromise = null;\n    WarehouseResource.reset();\n  }\n}\n"],"mappings":"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"}