@databricks/appkit 0.20.3 → 0.22.0

package/CLAUDE.md

@@ -36,6 +36,7 @@ npx @databricks/appkit docs <query>
 - [Local development](./docs/development/local-development.md): Once your app is bootstrapped according to the Manual quick start guide, you can start the development server with hot reload for both UI and backend code.
 - [Project setup](./docs/development/project-setup.md): This guide covers the recommended project structure and scaffolding for AppKit applications.
 - [Remote Bridge](./docs/development/remote-bridge.md): Remote bridge allows you to develop against a deployed backend while keeping your UI and queries local. This is useful for testing against production data or debugging deployed backend code without redeploying your app.
+- [Templates](./docs/development/templates.md): AppKit uses a template system powered by the Databricks CLI's databricks apps init command. Templates define the project structure, and .tmpl files are processed with Go's text/template engine to generate customized output.
 - [Type generation](./docs/development/type-generation.md): AppKit can automatically generate TypeScript types for your SQL queries, providing end-to-end type safety from database to UI.
 
 ## Plugins

package/README.md

@@ -2,17 +2,6 @@
 
 Build Databricks Apps faster with our brand-new Node.js + React SDK. Built for humans and AI.
 
-> [!WARNING]  
-> PREVIEW - NOT FOR PRODUCTION USE
-
-> **This SDK is in preview and is subject to change without notice.**
->
-> - ❌ **Do NOT use in production environments**
-> - ⚠️ **Breaking changes may occur at any time**
-> - 🔬 **APIs are experimental and unstable**
-> - 📝 **Use for development and testing only**
->
-
 ## Introduction
 
 AppKit is a TypeScript SDK for building production-ready Databricks applications with a plugin-based architecture. It provides opinionated defaults, built-in observability, and seamless integration with Databricks services.
@@ -29,16 +18,10 @@ AppKit simplifies building data applications on Databricks by providing:
 
 AppKit's power comes from its plugin system. Each plugin adds a focused capability to your app with minimal configuration.
 
-### Available now
-
-- **Analytics Plugin** — Query your Lakehouse data directly from your app. Define SQL queries as files, execute them against Databricks SQL Warehouses, and get automatic caching, parameterization, and on-behalf-of user execution out of the box. Perfect for building apps that surface insights from your Lakehouse.
+- **Analytics Plugin** — Query your Lakehouse data directly from your app. Define SQL queries as files, execute them against Databricks SQL Warehouses, and get automatic caching, parameterization, and on-behalf-of user execution out of the box.
 - **Genie Plugin** — Conversational AI interface powered by Databricks AI/BI Genie. Let users ask natural language questions against your data and get answers with automatic chart inference and visualization.
-
-### Coming soon
-
-- **Files Plugin** — Browse, upload, and manage files in Unity Catalog Volumes
-- **Lakebase Plugin** — OLTP database operations with automatic OAuth token management
-- ...and this is just the beginning.
+- **Files Plugin** — Browse, upload, and manage files in Unity Catalog Volumes. Supports multiple volumes, content type validation, and on-behalf-of user access.
+- **Lakebase Plugin** — OLTP database operations against Databricks Lakebase with automatic OAuth token management. Returns a standard `pg.Pool` compatible with Prisma, Drizzle, TypeORM, and other ORMs.
 
 > Missing a plugin? [Open an issue](https://github.com/databricks/appkit/issues/new) and tell us what you need — community input directly shapes the roadmap.
 

package/dist/appkit/package.js

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

package/dist/cli/commands/setup.js

@@ -43,7 +43,7 @@ ${packages.map((pkg) => {
 For enhanced AI assistance with Databricks CLI operations, authentication, data exploration, and app development, install the Databricks skills:
 
 \`\`\`bash
-databricks experimental aitools skills install
+databricks experimental aitools install
 \`\`\`
 ${SECTION_END}`;
 }
@@ -68,7 +68,7 @@ ${packages.map((pkg) => {
 For enhanced AI assistance with Databricks CLI operations, authentication, data exploration, and app development, install the Databricks skills:
 
 \`\`\`bash
-databricks experimental aitools skills install
+databricks experimental aitools install
 \`\`\`
 ${SECTION_END}
 `;

package/dist/cli/commands/setup.js.map

@@ -1 +1 @@
-{"version":3,"file":"setup.js","names":[],"sources":["../../../src/cli/commands/setup.ts"],"sourcesContent":["import fs from \"node:fs\";\nimport path from \"node:path\";\nimport { Command } from \"commander\";\n\nconst PACKAGES = [\n  { name: \"@databricks/appkit\", description: \"Backend SDK\" },\n  {\n    name: \"@databricks/appkit-ui\",\n    description: \"UI Integration, Charts, Tables, SSE, and more.\",\n  },\n];\n\nconst SECTION_START = \"<!-- appkit-instructions-start -->\";\nconst SECTION_END = \"<!-- appkit-instructions-end -->\";\n\n/**\n * Find which AppKit packages are installed by checking for package.json\n */\nfunction findInstalledPackages() {\n  const cwd = process.cwd();\n  const installed = [];\n\n  for (const pkg of PACKAGES) {\n    const packagePath = path.join(\n      cwd,\n      \"node_modules\",\n      pkg.name,\n      \"package.json\",\n    );\n    if (fs.existsSync(packagePath)) {\n      installed.push(pkg);\n    }\n  }\n\n  return installed;\n}\n\n/**\n * Generate the AppKit section content\n */\nfunction generateSection(packages: typeof PACKAGES) {\n  const links = packages\n    .map((pkg) => {\n      const docPath = `./node_modules/${pkg.name}/CLAUDE.md`;\n      return `- **${pkg.name}** (${pkg.description}): [${docPath}](${docPath})`;\n    })\n    .join(\"\\n\");\n\n  return `${SECTION_START}\n## Databricks AppKit\n\nThis project uses Databricks AppKit packages. For AI assistant guidance on using these packages, refer to:\n\n${links}\n\n### Databricks Skills\n\nFor enhanced AI assistance with Databricks CLI operations, authentication, data exploration, and app development, install the Databricks skills:\n\n\\`\\`\\`bash\ndatabricks experimental aitools skills install\n\\`\\`\\`\n${SECTION_END}`;\n}\n\n/**\n * Generate standalone CLAUDE.md content (when no existing file)\n */\nfunction generateStandalone(packages: typeof PACKAGES) {\n  const links = packages\n    .map((pkg) => {\n      const docPath = `./node_modules/${pkg.name}/CLAUDE.md`;\n      return `- **${pkg.name}** (${pkg.description}): [${docPath}](${docPath})`;\n    })\n    .join(\"\\n\");\n\n  return `# AI Assistant Instructions\n\n${SECTION_START}\n## Databricks AppKit\n\nThis project uses Databricks AppKit packages. For AI assistant guidance on using these packages, refer to:\n\n${links}\n\n### Databricks Skills\n\nFor enhanced AI assistance with Databricks CLI operations, authentication, data exploration, and app development, install the Databricks skills:\n\n\\`\\`\\`bash\ndatabricks experimental aitools skills install\n\\`\\`\\`\n${SECTION_END}\n`;\n}\n\n/**\n * Update existing content with AppKit section\n */\nfunction updateContent(existingContent: string, packages: typeof PACKAGES) {\n  const newSection = generateSection(packages);\n\n  // Check if AppKit section already exists\n  const startIndex = existingContent.indexOf(SECTION_START);\n  const endIndex = existingContent.indexOf(SECTION_END);\n\n  if (startIndex !== -1 && endIndex !== -1) {\n    // Replace existing section\n    const before = existingContent.substring(0, startIndex);\n    const after = existingContent.substring(endIndex + SECTION_END.length);\n    return before + newSection + after;\n  }\n\n  // Append section to end\n  return `${existingContent.trimEnd()}\\n\\n${newSection}\\n`;\n}\n\n/**\n * Setup command implementation\n */\nfunction runSetup(options: { write?: boolean }) {\n  const shouldWrite = options.write;\n\n  // Find installed packages\n  const installed = findInstalledPackages();\n\n  if (installed.length === 0) {\n    console.log(\"No @databricks/appkit packages found in node_modules.\");\n    console.log(\"\\nMake sure you've installed at least one of:\");\n    PACKAGES.forEach((pkg) => {\n      console.log(`  - ${pkg.name}`);\n    });\n    process.exit(1);\n  }\n\n  console.log(\"Detected packages:\");\n  installed.forEach((pkg) => {\n    console.log(`  ✓ ${pkg.name}`);\n  });\n\n  const claudePath = path.join(process.cwd(), \"CLAUDE.md\");\n  const existingContent = fs.existsSync(claudePath)\n    ? fs.readFileSync(claudePath, \"utf-8\")\n    : null;\n\n  let finalContent: string;\n  let action: string;\n\n  if (existingContent) {\n    finalContent = updateContent(existingContent, installed);\n    action = existingContent.includes(SECTION_START) ? \"Updated\" : \"Added to\";\n  } else {\n    finalContent = generateStandalone(installed);\n    action = \"Created\";\n  }\n\n  if (shouldWrite) {\n    fs.writeFileSync(claudePath, finalContent);\n    console.log(`\\n✓ ${action} CLAUDE.md`);\n    console.log(`  Path: ${claudePath}`);\n  } else {\n    console.log(\"\\nTo create/update CLAUDE.md, run:\");\n    console.log(\"  npx appkit setup --write\\n\");\n\n    if (existingContent) {\n      console.log(\n        `This will ${\n          existingContent.includes(SECTION_START)\n            ? \"update the existing\"\n            : \"add a new\"\n        } AppKit section.\\n`,\n      );\n    }\n\n    console.log(\"Preview of AppKit section:\\n\");\n    console.log(\"─\".repeat(50));\n    console.log(generateSection(installed));\n    console.log(\"─\".repeat(50));\n  }\n}\n\nexport const setupCommand = new Command(\"setup\")\n  .description(\"Setup CLAUDE.md with AppKit package references\")\n  .option(\"-w, --write\", \"Create or update CLAUDE.md file in current directory\")\n  .action(runSetup);\n"],"mappings":"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"}
+{"version":3,"file":"setup.js","names":[],"sources":["../../../src/cli/commands/setup.ts"],"sourcesContent":["import fs from \"node:fs\";\nimport path from \"node:path\";\nimport { Command } from \"commander\";\n\nconst PACKAGES = [\n  { name: \"@databricks/appkit\", description: \"Backend SDK\" },\n  {\n    name: \"@databricks/appkit-ui\",\n    description: \"UI Integration, Charts, Tables, SSE, and more.\",\n  },\n];\n\nconst SECTION_START = \"<!-- appkit-instructions-start -->\";\nconst SECTION_END = \"<!-- appkit-instructions-end -->\";\n\n/**\n * Find which AppKit packages are installed by checking for package.json\n */\nfunction findInstalledPackages() {\n  const cwd = process.cwd();\n  const installed = [];\n\n  for (const pkg of PACKAGES) {\n    const packagePath = path.join(\n      cwd,\n      \"node_modules\",\n      pkg.name,\n      \"package.json\",\n    );\n    if (fs.existsSync(packagePath)) {\n      installed.push(pkg);\n    }\n  }\n\n  return installed;\n}\n\n/**\n * Generate the AppKit section content\n */\nfunction generateSection(packages: typeof PACKAGES) {\n  const links = packages\n    .map((pkg) => {\n      const docPath = `./node_modules/${pkg.name}/CLAUDE.md`;\n      return `- **${pkg.name}** (${pkg.description}): [${docPath}](${docPath})`;\n    })\n    .join(\"\\n\");\n\n  return `${SECTION_START}\n## Databricks AppKit\n\nThis project uses Databricks AppKit packages. For AI assistant guidance on using these packages, refer to:\n\n${links}\n\n### Databricks Skills\n\nFor enhanced AI assistance with Databricks CLI operations, authentication, data exploration, and app development, install the Databricks skills:\n\n\\`\\`\\`bash\ndatabricks experimental aitools install\n\\`\\`\\`\n${SECTION_END}`;\n}\n\n/**\n * Generate standalone CLAUDE.md content (when no existing file)\n */\nfunction generateStandalone(packages: typeof PACKAGES) {\n  const links = packages\n    .map((pkg) => {\n      const docPath = `./node_modules/${pkg.name}/CLAUDE.md`;\n      return `- **${pkg.name}** (${pkg.description}): [${docPath}](${docPath})`;\n    })\n    .join(\"\\n\");\n\n  return `# AI Assistant Instructions\n\n${SECTION_START}\n## Databricks AppKit\n\nThis project uses Databricks AppKit packages. For AI assistant guidance on using these packages, refer to:\n\n${links}\n\n### Databricks Skills\n\nFor enhanced AI assistance with Databricks CLI operations, authentication, data exploration, and app development, install the Databricks skills:\n\n\\`\\`\\`bash\ndatabricks experimental aitools install\n\\`\\`\\`\n${SECTION_END}\n`;\n}\n\n/**\n * Update existing content with AppKit section\n */\nfunction updateContent(existingContent: string, packages: typeof PACKAGES) {\n  const newSection = generateSection(packages);\n\n  // Check if AppKit section already exists\n  const startIndex = existingContent.indexOf(SECTION_START);\n  const endIndex = existingContent.indexOf(SECTION_END);\n\n  if (startIndex !== -1 && endIndex !== -1) {\n    // Replace existing section\n    const before = existingContent.substring(0, startIndex);\n    const after = existingContent.substring(endIndex + SECTION_END.length);\n    return before + newSection + after;\n  }\n\n  // Append section to end\n  return `${existingContent.trimEnd()}\\n\\n${newSection}\\n`;\n}\n\n/**\n * Setup command implementation\n */\nfunction runSetup(options: { write?: boolean }) {\n  const shouldWrite = options.write;\n\n  // Find installed packages\n  const installed = findInstalledPackages();\n\n  if (installed.length === 0) {\n    console.log(\"No @databricks/appkit packages found in node_modules.\");\n    console.log(\"\\nMake sure you've installed at least one of:\");\n    PACKAGES.forEach((pkg) => {\n      console.log(`  - ${pkg.name}`);\n    });\n    process.exit(1);\n  }\n\n  console.log(\"Detected packages:\");\n  installed.forEach((pkg) => {\n    console.log(`  ✓ ${pkg.name}`);\n  });\n\n  const claudePath = path.join(process.cwd(), \"CLAUDE.md\");\n  const existingContent = fs.existsSync(claudePath)\n    ? fs.readFileSync(claudePath, \"utf-8\")\n    : null;\n\n  let finalContent: string;\n  let action: string;\n\n  if (existingContent) {\n    finalContent = updateContent(existingContent, installed);\n    action = existingContent.includes(SECTION_START) ? \"Updated\" : \"Added to\";\n  } else {\n    finalContent = generateStandalone(installed);\n    action = \"Created\";\n  }\n\n  if (shouldWrite) {\n    fs.writeFileSync(claudePath, finalContent);\n    console.log(`\\n✓ ${action} CLAUDE.md`);\n    console.log(`  Path: ${claudePath}`);\n  } else {\n    console.log(\"\\nTo create/update CLAUDE.md, run:\");\n    console.log(\"  npx appkit setup --write\\n\");\n\n    if (existingContent) {\n      console.log(\n        `This will ${\n          existingContent.includes(SECTION_START)\n            ? \"update the existing\"\n            : \"add a new\"\n        } AppKit section.\\n`,\n      );\n    }\n\n    console.log(\"Preview of AppKit section:\\n\");\n    console.log(\"─\".repeat(50));\n    console.log(generateSection(installed));\n    console.log(\"─\".repeat(50));\n  }\n}\n\nexport const setupCommand = new Command(\"setup\")\n  .description(\"Setup CLAUDE.md with AppKit package references\")\n  .option(\"-w, --write\", \"Create or update CLAUDE.md file in current directory\")\n  .action(runSetup);\n"],"mappings":"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"}

package/dist/connectors/genie/client.js

@@ -208,6 +208,56 @@ var GenieConnector = class {
 			};
 		}
 	}
+	/**
+	* Polls a single message via `getMessage` until it reaches a terminal
+	* state (`COMPLETED` or `FAILED`). Yields the same event types as
+	* `streamSendMessage` so callers can reuse the same SSE processing logic.
+	*/
+	async *streamGetMessage(workspaceClient, spaceId, conversationId, messageId, options) {
+		const pollInterval = options?.pollInterval ?? 3e3;
+		const signal = options?.signal;
+		let lastStatus = "";
+		try {
+			while (true) {
+				if (signal?.aborted) return;
+				const message = await workspaceClient.genie.getMessage({
+					space_id: spaceId,
+					conversation_id: conversationId,
+					message_id: messageId
+				});
+				if (message.status && message.status !== lastStatus) {
+					lastStatus = message.status;
+					yield {
+						type: "status",
+						status: message.status
+					};
+				}
+				if (message.status === "COMPLETED" || message.status === "FAILED") {
+					const messageResponse = toMessageResponse(message);
+					yield {
+						type: "message_result",
+						message: messageResponse
+					};
+					yield* this.emitQueryResults(workspaceClient, spaceId, conversationId, messageId, messageResponse);
+					return;
+				}
+				await new Promise((resolve) => {
+					const timer = setTimeout(resolve, pollInterval);
+					signal?.addEventListener("abort", () => {
+						clearTimeout(timer);
+						resolve();
+					}, { once: true });
+				});
+			}
+		} catch (error) {
+			if (signal?.aborted) return;
+			logger.error("Genie getMessage poll error (spaceId=%s, conversationId=%s, messageId=%s): %O", spaceId, conversationId, messageId, error);
+			yield {
+				type: "error",
+				error: classifyGenieError(error)
+			};
+		}
+	}
 	async sendMessage(workspaceClient, spaceId, content, conversationId) {
 		const { messageWaiter, conversationId: resultConversationId } = await this.startMessage(workspaceClient, spaceId, content, conversationId);
 		return {

package/dist/connectors/genie/client.js.map

@@ -1 +1 @@
-{"version":3,"file":"client.js","names":[],"sources":["../../../src/connectors/genie/client.ts"],"sourcesContent":["import type { WorkspaceClient } from \"@databricks/sdk-experimental\";\nimport * as SDK from \"@databricks/sdk-experimental\";\nimport type { GenieMessage } from \"@databricks/sdk-experimental/dist/apis/dashboards\";\nimport type { Waiter } from \"@databricks/sdk-experimental/dist/wait\";\nimport { createLogger } from \"../../logging\";\nimport { genieConnectorDefaults } from \"./defaults\";\nimport { pollWaiter } from \"./poll-waiter\";\nimport type {\n  GenieAttachmentResponse,\n  GenieConversationHistoryResponse,\n  GenieMessageResponse,\n  GenieStatementResponse,\n  GenieStreamEvent,\n} from \"./types\";\n\nconst { TimeUnits } = SDK;\nconst Time = SDK.Time ?? (SDK as any).default.Time;\n\nconst logger = createLogger(\"connectors:genie\");\n\nconst GenieErrors = {\n  SPACE_ACCESS_DENIED: \"You don't have access to this Genie Space.\",\n  TABLE_PERMISSIONS:\n    \"You may not have access to the data tables. Please verify your table permissions.\",\n  REQUEST_FAILED: \"Genie request failed\",\n  QUERY_RESULT_FAILED: \"Failed to fetch query result\",\n} as const;\n\ntype CreateMessageWaiter = Waiter<GenieMessage, GenieMessage>;\n\ninterface GenieConnectorConfig {\n  timeout?: number;\n  maxMessages?: number;\n}\n\nfunction mapAttachments(message: GenieMessage): GenieAttachmentResponse[] {\n  return (\n    message.attachments?.map((att) => ({\n      attachmentId: att.attachment_id,\n      query: att.query\n        ? {\n            title: att.query.title,\n            description: att.query.description,\n            query: att.query.query,\n            statementId: att.query.statement_id,\n          }\n        : undefined,\n      text: att.text ? { content: att.text.content } : undefined,\n      suggestedQuestions: att.suggested_questions?.questions,\n    })) ?? []\n  );\n}\n\nfunction toMessageResponse(message: GenieMessage): GenieMessageResponse {\n  return {\n    messageId: message.message_id,\n    conversationId: message.conversation_id,\n    spaceId: message.space_id,\n    status: message.status ?? \"COMPLETED\",\n    content: message.content,\n    attachments: mapAttachments(message),\n    error: message.error?.error,\n  };\n}\n\nfunction classifyGenieError(error: unknown): string {\n  const message = error instanceof Error ? error.message : String(error);\n\n  if (message.includes(\"RESOURCE_DOES_NOT_EXIST\")) {\n    return GenieErrors.SPACE_ACCESS_DENIED;\n  }\n\n  if (\n    message.includes(\"failed to reach COMPLETED state\") &&\n    message.includes(\"FAILED\")\n  ) {\n    return GenieErrors.TABLE_PERMISSIONS;\n  }\n\n  return message || GenieErrors.REQUEST_FAILED;\n}\n\nexport class GenieConnector {\n  private readonly config: Required<GenieConnectorConfig>;\n\n  constructor(config: GenieConnectorConfig = {}) {\n    this.config = {\n      timeout: config.timeout ?? genieConnectorDefaults.timeout,\n      maxMessages: config.maxMessages ?? genieConnectorDefaults.maxMessages,\n    };\n  }\n\n  async startMessage(\n    workspaceClient: WorkspaceClient,\n    spaceId: string,\n    content: string,\n    conversationId: string | undefined,\n  ): Promise<{\n    messageWaiter: CreateMessageWaiter;\n    conversationId: string;\n    messageId: string;\n  }> {\n    if (conversationId) {\n      const waiter = await workspaceClient.genie.createMessage({\n        space_id: spaceId,\n        conversation_id: conversationId,\n        content,\n      });\n      return {\n        messageWaiter: waiter,\n        conversationId,\n        messageId: waiter.message_id ?? \"\",\n      };\n    }\n    const start = await workspaceClient.genie.startConversation({\n      space_id: spaceId,\n      content,\n    });\n    return {\n      messageWaiter: start as unknown as CreateMessageWaiter,\n      conversationId: start.conversation_id,\n      messageId: start.message_id,\n    };\n  }\n\n  async waitForMessage(\n    messageWaiter: CreateMessageWaiter,\n    options?: { timeout?: number },\n  ): Promise<GenieMessage> {\n    const timeout = options?.timeout ?? this.config.timeout;\n    const waitOptions =\n      timeout > 0 ? { timeout: new Time(timeout, TimeUnits.milliseconds) } : {};\n    return messageWaiter.wait(waitOptions);\n  }\n\n  async listConversationMessages(\n    workspaceClient: WorkspaceClient,\n    spaceId: string,\n    conversationId: string,\n    options?: { pageSize?: number; pageToken?: string },\n  ): Promise<{\n    messages: GenieMessageResponse[];\n    nextPageToken: string | null;\n  }> {\n    const pageSize =\n      options?.pageSize ?? genieConnectorDefaults.initialPageSize;\n\n    const response = await workspaceClient.genie.listConversationMessages({\n      space_id: spaceId,\n      conversation_id: conversationId,\n      page_size: pageSize,\n      ...(options?.pageToken ? { page_token: options.pageToken } : {}),\n    });\n\n    const messages = (response.messages ?? []).reverse().map(toMessageResponse);\n\n    return {\n      messages,\n      nextPageToken: response.next_page_token ?? null,\n    };\n  }\n\n  async getMessageAttachmentQueryResult(\n    workspaceClient: WorkspaceClient,\n    spaceId: string,\n    conversationId: string,\n    messageId: string,\n    attachmentId: string,\n    _signal?: AbortSignal,\n  ): Promise<GenieStatementResponse> {\n    const response =\n      await workspaceClient.genie.getMessageAttachmentQueryResult({\n        space_id: spaceId,\n        conversation_id: conversationId,\n        message_id: messageId,\n        attachment_id: attachmentId,\n      });\n    return response.statement_response as GenieStatementResponse;\n  }\n\n  async *streamSendMessage(\n    workspaceClient: WorkspaceClient,\n    spaceId: string,\n    content: string,\n    conversationId: string | undefined,\n    options?: { timeout?: number },\n  ): AsyncGenerator<GenieStreamEvent> {\n    try {\n      const {\n        messageWaiter,\n        conversationId: resultConversationId,\n        messageId: resultMessageId,\n      } = await this.startMessage(\n        workspaceClient,\n        spaceId,\n        content,\n        conversationId,\n      );\n\n      yield {\n        type: \"message_start\",\n        conversationId: resultConversationId,\n        messageId: resultMessageId,\n        spaceId,\n      };\n\n      const timeout =\n        options?.timeout != null ? options.timeout : this.config.timeout;\n      const waitOptions =\n        timeout > 0\n          ? { timeout: new Time(timeout, TimeUnits.milliseconds) }\n          : {};\n\n      let completedMessage!: GenieMessage;\n      for await (const event of pollWaiter(messageWaiter, waitOptions)) {\n        if (event.type === \"progress\" && event.value.status) {\n          yield { type: \"status\", status: event.value.status };\n        } else if (event.type === \"completed\") {\n          completedMessage = event.value;\n        }\n      }\n\n      const messageResponse = toMessageResponse(completedMessage);\n      yield { type: \"message_result\", message: messageResponse };\n\n      yield* this.emitQueryResults(\n        workspaceClient,\n        spaceId,\n        resultConversationId,\n        messageResponse.messageId,\n        messageResponse,\n      );\n    } catch (error) {\n      logger.error(\n        \"Genie message error (spaceId=%s, conversationId=%s): %O\",\n        spaceId,\n        conversationId ?? \"new\",\n        error,\n      );\n      yield { type: \"error\", error: classifyGenieError(error) };\n    }\n  }\n\n  private async *emitQueryResults(\n    workspaceClient: WorkspaceClient,\n    spaceId: string,\n    conversationId: string,\n    messageId: string,\n    messageResponse: GenieMessageResponse,\n  ): AsyncGenerator<\n    Extract<GenieStreamEvent, { type: \"query_result\" } | { type: \"error\" }>\n  > {\n    const attachments = messageResponse.attachments ?? [];\n    for (const att of attachments) {\n      if (!att.query?.statementId || !att.attachmentId) continue;\n      try {\n        const data = await this.getMessageAttachmentQueryResult(\n          workspaceClient,\n          spaceId,\n          conversationId,\n          messageId,\n          att.attachmentId,\n        );\n        yield {\n          type: \"query_result\",\n          attachmentId: att.attachmentId,\n          statementId: att.query.statementId,\n          data,\n        };\n      } catch (error) {\n        logger.error(\n          \"Failed to fetch query result for attachment %s: %O\",\n          att.attachmentId,\n          error,\n        );\n        yield {\n          type: \"error\",\n          error: `${GenieErrors.QUERY_RESULT_FAILED} for attachment ${att.attachmentId}`,\n        };\n      }\n    }\n  }\n\n  async *streamConversation(\n    workspaceClient: WorkspaceClient,\n    spaceId: string,\n    conversationId: string,\n    options?: {\n      includeQueryResults?: boolean;\n      pageSize?: number;\n      pageToken?: string;\n    },\n  ): AsyncGenerator<GenieStreamEvent> {\n    const includeQueryResults = options?.includeQueryResults !== false;\n\n    try {\n      const { messages: messageResponses, nextPageToken } =\n        await this.listConversationMessages(\n          workspaceClient,\n          spaceId,\n          conversationId,\n          { pageSize: options?.pageSize, pageToken: options?.pageToken },\n        );\n\n      for (const messageResponse of messageResponses) {\n        yield { type: \"message_result\", message: messageResponse };\n      }\n\n      yield {\n        type: \"history_info\",\n        conversationId,\n        spaceId,\n        nextPageToken,\n        loadedCount: messageResponses.length,\n      };\n\n      if (includeQueryResults) {\n        const queryAttachments: Array<{\n          messageId: string;\n          attachmentId: string;\n          statementId: string;\n        }> = [];\n\n        for (const msg of messageResponses) {\n          for (const att of msg.attachments ?? []) {\n            if (att.query?.statementId && att.attachmentId) {\n              queryAttachments.push({\n                messageId: msg.messageId,\n                attachmentId: att.attachmentId,\n                statementId: att.query.statementId,\n              });\n            }\n          }\n        }\n\n        const results = await Promise.allSettled(\n          queryAttachments.map(async (att) => {\n            const data = await this.getMessageAttachmentQueryResult(\n              workspaceClient,\n              spaceId,\n              conversationId,\n              att.messageId,\n              att.attachmentId,\n            );\n            return {\n              attachmentId: att.attachmentId,\n              statementId: att.statementId,\n              data,\n            };\n          }),\n        );\n\n        for (const result of results) {\n          if (result.status === \"fulfilled\") {\n            yield {\n              type: \"query_result\",\n              attachmentId: result.value.attachmentId,\n              statementId: result.value.statementId,\n              data: result.value.data,\n            };\n          } else {\n            logger.error(\"Failed to fetch query result: %O\", result.reason);\n            yield {\n              type: \"error\",\n              error:\n                result.reason instanceof Error\n                  ? result.reason.message\n                  : GenieErrors.QUERY_RESULT_FAILED,\n            };\n          }\n        }\n      }\n    } catch (error) {\n      logger.error(\n        \"Genie getConversation error (spaceId=%s, conversationId=%s): %O\",\n        spaceId,\n        conversationId,\n        error,\n      );\n      yield { type: \"error\", error: classifyGenieError(error) };\n    }\n  }\n\n  async sendMessage(\n    workspaceClient: WorkspaceClient,\n    spaceId: string,\n    content: string,\n    conversationId: string | undefined,\n  ): Promise<GenieMessageResponse> {\n    const { messageWaiter, conversationId: resultConversationId } =\n      await this.startMessage(\n        workspaceClient,\n        spaceId,\n        content,\n        conversationId,\n      );\n    const completedMessage = await this.waitForMessage(messageWaiter);\n    const messageResponse = toMessageResponse(completedMessage);\n    return {\n      ...messageResponse,\n      conversationId: resultConversationId,\n    };\n  }\n\n  async getConversation(\n    workspaceClient: WorkspaceClient,\n    spaceId: string,\n    conversationId: string,\n  ): Promise<GenieConversationHistoryResponse> {\n    const allMessages: GenieMessageResponse[] = [];\n    let pageToken: string | undefined;\n\n    do {\n      const { messages, nextPageToken } = await this.listConversationMessages(\n        workspaceClient,\n        spaceId,\n        conversationId,\n        {\n          pageSize: genieConnectorDefaults.pageSize,\n          pageToken,\n        },\n      );\n      allMessages.push(...messages);\n      pageToken = nextPageToken ?? undefined;\n    } while (pageToken && allMessages.length < this.config.maxMessages);\n\n    return {\n      conversationId,\n      spaceId,\n      messages: allMessages.slice(0, this.config.maxMessages),\n    };\n  }\n}\n"],"mappings":"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"}
+{"version":3,"file":"client.js","names":[],"sources":["../../../src/connectors/genie/client.ts"],"sourcesContent":["import type { WorkspaceClient } from \"@databricks/sdk-experimental\";\nimport * as SDK from \"@databricks/sdk-experimental\";\nimport type { GenieMessage } from \"@databricks/sdk-experimental/dist/apis/dashboards\";\nimport type { Waiter } from \"@databricks/sdk-experimental/dist/wait\";\nimport { createLogger } from \"../../logging\";\nimport { genieConnectorDefaults } from \"./defaults\";\nimport { pollWaiter } from \"./poll-waiter\";\nimport type {\n  GenieAttachmentResponse,\n  GenieConversationHistoryResponse,\n  GenieMessageResponse,\n  GenieStatementResponse,\n  GenieStreamEvent,\n} from \"./types\";\n\nconst { TimeUnits } = SDK;\nconst Time = SDK.Time ?? (SDK as any).default.Time;\n\nconst logger = createLogger(\"connectors:genie\");\n\nconst GenieErrors = {\n  SPACE_ACCESS_DENIED: \"You don't have access to this Genie Space.\",\n  TABLE_PERMISSIONS:\n    \"You may not have access to the data tables. Please verify your table permissions.\",\n  REQUEST_FAILED: \"Genie request failed\",\n  QUERY_RESULT_FAILED: \"Failed to fetch query result\",\n} as const;\n\ntype CreateMessageWaiter = Waiter<GenieMessage, GenieMessage>;\n\ninterface GenieConnectorConfig {\n  timeout?: number;\n  maxMessages?: number;\n}\n\nfunction mapAttachments(message: GenieMessage): GenieAttachmentResponse[] {\n  return (\n    message.attachments?.map((att) => ({\n      attachmentId: att.attachment_id,\n      query: att.query\n        ? {\n            title: att.query.title,\n            description: att.query.description,\n            query: att.query.query,\n            statementId: att.query.statement_id,\n          }\n        : undefined,\n      text: att.text ? { content: att.text.content } : undefined,\n      suggestedQuestions: att.suggested_questions?.questions,\n    })) ?? []\n  );\n}\n\nfunction toMessageResponse(message: GenieMessage): GenieMessageResponse {\n  return {\n    messageId: message.message_id,\n    conversationId: message.conversation_id,\n    spaceId: message.space_id,\n    status: message.status ?? \"COMPLETED\",\n    content: message.content,\n    attachments: mapAttachments(message),\n    error: message.error?.error,\n  };\n}\n\nfunction classifyGenieError(error: unknown): string {\n  const message = error instanceof Error ? error.message : String(error);\n\n  if (message.includes(\"RESOURCE_DOES_NOT_EXIST\")) {\n    return GenieErrors.SPACE_ACCESS_DENIED;\n  }\n\n  if (\n    message.includes(\"failed to reach COMPLETED state\") &&\n    message.includes(\"FAILED\")\n  ) {\n    return GenieErrors.TABLE_PERMISSIONS;\n  }\n\n  return message || GenieErrors.REQUEST_FAILED;\n}\n\nexport class GenieConnector {\n  private readonly config: Required<GenieConnectorConfig>;\n\n  constructor(config: GenieConnectorConfig = {}) {\n    this.config = {\n      timeout: config.timeout ?? genieConnectorDefaults.timeout,\n      maxMessages: config.maxMessages ?? genieConnectorDefaults.maxMessages,\n    };\n  }\n\n  async startMessage(\n    workspaceClient: WorkspaceClient,\n    spaceId: string,\n    content: string,\n    conversationId: string | undefined,\n  ): Promise<{\n    messageWaiter: CreateMessageWaiter;\n    conversationId: string;\n    messageId: string;\n  }> {\n    if (conversationId) {\n      const waiter = await workspaceClient.genie.createMessage({\n        space_id: spaceId,\n        conversation_id: conversationId,\n        content,\n      });\n      return {\n        messageWaiter: waiter,\n        conversationId,\n        messageId: waiter.message_id ?? \"\",\n      };\n    }\n    const start = await workspaceClient.genie.startConversation({\n      space_id: spaceId,\n      content,\n    });\n    return {\n      messageWaiter: start as unknown as CreateMessageWaiter,\n      conversationId: start.conversation_id,\n      messageId: start.message_id,\n    };\n  }\n\n  async waitForMessage(\n    messageWaiter: CreateMessageWaiter,\n    options?: { timeout?: number },\n  ): Promise<GenieMessage> {\n    const timeout = options?.timeout ?? this.config.timeout;\n    const waitOptions =\n      timeout > 0 ? { timeout: new Time(timeout, TimeUnits.milliseconds) } : {};\n    return messageWaiter.wait(waitOptions);\n  }\n\n  async listConversationMessages(\n    workspaceClient: WorkspaceClient,\n    spaceId: string,\n    conversationId: string,\n    options?: { pageSize?: number; pageToken?: string },\n  ): Promise<{\n    messages: GenieMessageResponse[];\n    nextPageToken: string | null;\n  }> {\n    const pageSize =\n      options?.pageSize ?? genieConnectorDefaults.initialPageSize;\n\n    const response = await workspaceClient.genie.listConversationMessages({\n      space_id: spaceId,\n      conversation_id: conversationId,\n      page_size: pageSize,\n      ...(options?.pageToken ? { page_token: options.pageToken } : {}),\n    });\n\n    const messages = (response.messages ?? []).reverse().map(toMessageResponse);\n\n    return {\n      messages,\n      nextPageToken: response.next_page_token ?? null,\n    };\n  }\n\n  async getMessageAttachmentQueryResult(\n    workspaceClient: WorkspaceClient,\n    spaceId: string,\n    conversationId: string,\n    messageId: string,\n    attachmentId: string,\n    _signal?: AbortSignal,\n  ): Promise<GenieStatementResponse> {\n    const response =\n      await workspaceClient.genie.getMessageAttachmentQueryResult({\n        space_id: spaceId,\n        conversation_id: conversationId,\n        message_id: messageId,\n        attachment_id: attachmentId,\n      });\n    return response.statement_response as GenieStatementResponse;\n  }\n\n  async *streamSendMessage(\n    workspaceClient: WorkspaceClient,\n    spaceId: string,\n    content: string,\n    conversationId: string | undefined,\n    options?: { timeout?: number; signal?: AbortSignal },\n  ): AsyncGenerator<GenieStreamEvent> {\n    try {\n      const {\n        messageWaiter,\n        conversationId: resultConversationId,\n        messageId: resultMessageId,\n      } = await this.startMessage(\n        workspaceClient,\n        spaceId,\n        content,\n        conversationId,\n      );\n\n      yield {\n        type: \"message_start\",\n        conversationId: resultConversationId,\n        messageId: resultMessageId,\n        spaceId,\n      };\n\n      const timeout =\n        options?.timeout != null ? options.timeout : this.config.timeout;\n      const waitOptions =\n        timeout > 0\n          ? { timeout: new Time(timeout, TimeUnits.milliseconds) }\n          : {};\n\n      let completedMessage!: GenieMessage;\n      for await (const event of pollWaiter(messageWaiter, waitOptions)) {\n        if (event.type === \"progress\" && event.value.status) {\n          yield { type: \"status\", status: event.value.status };\n        } else if (event.type === \"completed\") {\n          completedMessage = event.value;\n        }\n      }\n\n      const messageResponse = toMessageResponse(completedMessage);\n      yield { type: \"message_result\", message: messageResponse };\n\n      yield* this.emitQueryResults(\n        workspaceClient,\n        spaceId,\n        resultConversationId,\n        messageResponse.messageId,\n        messageResponse,\n      );\n    } catch (error) {\n      logger.error(\n        \"Genie message error (spaceId=%s, conversationId=%s): %O\",\n        spaceId,\n        conversationId ?? \"new\",\n        error,\n      );\n      yield { type: \"error\", error: classifyGenieError(error) };\n    }\n  }\n\n  private async *emitQueryResults(\n    workspaceClient: WorkspaceClient,\n    spaceId: string,\n    conversationId: string,\n    messageId: string,\n    messageResponse: GenieMessageResponse,\n  ): AsyncGenerator<\n    Extract<GenieStreamEvent, { type: \"query_result\" } | { type: \"error\" }>\n  > {\n    const attachments = messageResponse.attachments ?? [];\n    for (const att of attachments) {\n      if (!att.query?.statementId || !att.attachmentId) continue;\n      try {\n        const data = await this.getMessageAttachmentQueryResult(\n          workspaceClient,\n          spaceId,\n          conversationId,\n          messageId,\n          att.attachmentId,\n        );\n        yield {\n          type: \"query_result\",\n          attachmentId: att.attachmentId,\n          statementId: att.query.statementId,\n          data,\n        };\n      } catch (error) {\n        logger.error(\n          \"Failed to fetch query result for attachment %s: %O\",\n          att.attachmentId,\n          error,\n        );\n        yield {\n          type: \"error\",\n          error: `${GenieErrors.QUERY_RESULT_FAILED} for attachment ${att.attachmentId}`,\n        };\n      }\n    }\n  }\n\n  async *streamConversation(\n    workspaceClient: WorkspaceClient,\n    spaceId: string,\n    conversationId: string,\n    options?: {\n      includeQueryResults?: boolean;\n      pageSize?: number;\n      pageToken?: string;\n      signal?: AbortSignal;\n    },\n  ): AsyncGenerator<GenieStreamEvent> {\n    const includeQueryResults = options?.includeQueryResults !== false;\n\n    try {\n      const { messages: messageResponses, nextPageToken } =\n        await this.listConversationMessages(\n          workspaceClient,\n          spaceId,\n          conversationId,\n          { pageSize: options?.pageSize, pageToken: options?.pageToken },\n        );\n\n      for (const messageResponse of messageResponses) {\n        yield { type: \"message_result\", message: messageResponse };\n      }\n\n      yield {\n        type: \"history_info\",\n        conversationId,\n        spaceId,\n        nextPageToken,\n        loadedCount: messageResponses.length,\n      };\n\n      if (includeQueryResults) {\n        const queryAttachments: Array<{\n          messageId: string;\n          attachmentId: string;\n          statementId: string;\n        }> = [];\n\n        for (const msg of messageResponses) {\n          for (const att of msg.attachments ?? []) {\n            if (att.query?.statementId && att.attachmentId) {\n              queryAttachments.push({\n                messageId: msg.messageId,\n                attachmentId: att.attachmentId,\n                statementId: att.query.statementId,\n              });\n            }\n          }\n        }\n\n        const results = await Promise.allSettled(\n          queryAttachments.map(async (att) => {\n            const data = await this.getMessageAttachmentQueryResult(\n              workspaceClient,\n              spaceId,\n              conversationId,\n              att.messageId,\n              att.attachmentId,\n            );\n            return {\n              attachmentId: att.attachmentId,\n              statementId: att.statementId,\n              data,\n            };\n          }),\n        );\n\n        for (const result of results) {\n          if (result.status === \"fulfilled\") {\n            yield {\n              type: \"query_result\",\n              attachmentId: result.value.attachmentId,\n              statementId: result.value.statementId,\n              data: result.value.data,\n            };\n          } else {\n            logger.error(\"Failed to fetch query result: %O\", result.reason);\n            yield {\n              type: \"error\",\n              error:\n                result.reason instanceof Error\n                  ? result.reason.message\n                  : GenieErrors.QUERY_RESULT_FAILED,\n            };\n          }\n        }\n      }\n    } catch (error) {\n      logger.error(\n        \"Genie getConversation error (spaceId=%s, conversationId=%s): %O\",\n        spaceId,\n        conversationId,\n        error,\n      );\n      yield { type: \"error\", error: classifyGenieError(error) };\n    }\n  }\n\n  /**\n   * Polls a single message via `getMessage` until it reaches a terminal\n   * state (`COMPLETED` or `FAILED`). Yields the same event types as\n   * `streamSendMessage` so callers can reuse the same SSE processing logic.\n   */\n  async *streamGetMessage(\n    workspaceClient: WorkspaceClient,\n    spaceId: string,\n    conversationId: string,\n    messageId: string,\n    options?: { timeout?: number; pollInterval?: number; signal?: AbortSignal },\n  ): AsyncGenerator<GenieStreamEvent> {\n    const pollInterval = options?.pollInterval ?? 3_000;\n    const signal = options?.signal;\n    let lastStatus = \"\";\n\n    try {\n      while (true) {\n        if (signal?.aborted) return;\n\n        const message = await workspaceClient.genie.getMessage({\n          space_id: spaceId,\n          conversation_id: conversationId,\n          message_id: messageId,\n        });\n\n        if (message.status && message.status !== lastStatus) {\n          lastStatus = message.status;\n          yield { type: \"status\", status: message.status };\n        }\n\n        const isTerminal =\n          message.status === \"COMPLETED\" || message.status === \"FAILED\";\n        if (isTerminal) {\n          const messageResponse = toMessageResponse(message);\n          yield { type: \"message_result\", message: messageResponse };\n          yield* this.emitQueryResults(\n            workspaceClient,\n            spaceId,\n            conversationId,\n            messageId,\n            messageResponse,\n          );\n          return;\n        }\n\n        await new Promise<void>((resolve) => {\n          const timer = setTimeout(resolve, pollInterval);\n          signal?.addEventListener(\n            \"abort\",\n            () => {\n              clearTimeout(timer);\n              resolve();\n            },\n            { once: true },\n          );\n        });\n      }\n    } catch (error) {\n      if (signal?.aborted) return;\n      logger.error(\n        \"Genie getMessage poll error (spaceId=%s, conversationId=%s, messageId=%s): %O\",\n        spaceId,\n        conversationId,\n        messageId,\n        error,\n      );\n      yield { type: \"error\", error: classifyGenieError(error) };\n    }\n  }\n\n  async sendMessage(\n    workspaceClient: WorkspaceClient,\n    spaceId: string,\n    content: string,\n    conversationId: string | undefined,\n  ): Promise<GenieMessageResponse> {\n    const { messageWaiter, conversationId: resultConversationId } =\n      await this.startMessage(\n        workspaceClient,\n        spaceId,\n        content,\n        conversationId,\n      );\n    const completedMessage = await this.waitForMessage(messageWaiter);\n    const messageResponse = toMessageResponse(completedMessage);\n    return {\n      ...messageResponse,\n      conversationId: resultConversationId,\n    };\n  }\n\n  async getConversation(\n    workspaceClient: WorkspaceClient,\n    spaceId: string,\n    conversationId: string,\n  ): Promise<GenieConversationHistoryResponse> {\n    const allMessages: GenieMessageResponse[] = [];\n    let pageToken: string | undefined;\n\n    do {\n      const { messages, nextPageToken } = await this.listConversationMessages(\n        workspaceClient,\n        spaceId,\n        conversationId,\n        {\n          pageSize: genieConnectorDefaults.pageSize,\n          pageToken,\n        },\n      );\n      allMessages.push(...messages);\n      pageToken = nextPageToken ?? undefined;\n    } while (pageToken && allMessages.length < this.config.maxMessages);\n\n    return {\n      conversationId,\n      spaceId,\n      messages: allMessages.slice(0, this.config.maxMessages),\n    };\n  }\n}\n"],"mappings":"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"}

package/dist/plugin/plugin.d.ts

@@ -148,6 +148,52 @@ declare abstract class Plugin<TConfig extends BasePluginConfig = BasePluginConfi
    * ```
    */
   exports(): unknown;
+  /**
+   * Returns startup config to expose to the client.
+   * Override this to surface server-side values that are safe to publish to the
+   * frontend, such as feature flags, resource IDs, or other app boot settings.
+   *
+   * This runs once when the server starts, so it should not depend on
+   * request-scoped or user-specific state.
+   *
+   * String values that match non-public environment variables are redacted
+   * unless you intentionally expose them via a matching `PUBLIC_APPKIT_` env var.
+   *
+   * Values must be JSON-serializable plain data (no functions, Dates, classes,
+   * Maps, Sets, BigInts, or circular references).
+   * By default returns an empty object (plugin contributes nothing to client config).
+   *
+   * On the client, read the config with the `usePluginClientConfig` hook
+   * (React) or the `getPluginClientConfig` function (vanilla JS), both
+   * from `@databricks/appkit-ui`.
+   *
+   * @example
+   * ```ts
+   * // Server — plugin definition
+   * class MyPlugin extends Plugin<MyConfig> {
+   *   clientConfig() {
+   *     return {
+   *       warehouseId: this.config.warehouseId,
+   *       features: { darkMode: true },
+   *     };
+   *   }
+   * }
+   *
+   * // Client — React component
+   * import { usePluginClientConfig } from "@databricks/appkit-ui/react";
+   *
+   * interface MyPluginConfig { warehouseId: string; features: { darkMode: boolean } }
+   *
+   * const config = usePluginClientConfig<MyPluginConfig>("myPlugin");
+   * config.warehouseId; // "abc-123"
+   *
+   * // Client — vanilla JS
+   * import { getPluginClientConfig } from "@databricks/appkit-ui/js";
+   *
+   * const config = getPluginClientConfig<MyPluginConfig>("myPlugin");
+   * ```
+   */
+  clientConfig(): Record<string, unknown>;
   /**
    * Resolve the effective user ID from a request.
    *
@@ -167,7 +213,7 @@ declare abstract class Plugin<TConfig extends BasePluginConfig = BasePluginConfi
    * @param req - The Express request containing the user token in headers
    * @returns A proxied plugin instance that executes as the user
    * @throws AuthenticationError if user token is not available in request headers (production only).
-   *   In development mode (`NODE_ENV=development`), falls back to the service principal instead of throwing.
+   *   In development mode (`NODE_ENV=development`), skips user impersonation instead of throwing.
    */
   asUser(req: express.Request): this;
   /**

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

@@ -1 +1 @@
-{"version":3,"file":"plugin.d.ts","names":[],"sources":["../../src/plugin/plugin.ts"],"mappings":";;;;;;;;;;;;;;;;;;;AAgJA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;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;EA4Kf;EAAA,QAzKE,mBAAA;EAyKN;EAAA,QAtKM,oBAAA;EAuKN;;;;;;EAAA,OA/JK,KAAA,EAAO,WAAA;EAiOkB;;;EA5NhC,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;EAuNyC;;;;;;;;;;;;;;;;;;;;;;;;EA3LzC,OAAA,CAAA;;;;;;;;;;;YAcU,aAAA,CAAc,GAAA,EAAK,OAAA,CAAQ,OAAA;;;;;;;;;;;EAmBrC,MAAA,CAAO,GAAA,EAAK,OAAA,CAAQ,OAAA;;;;;;UAuCZ,uBAAA;EAAA,UAqBQ,aAAA,GAAA,CACd,GAAA,EAAK,YAAA,EACL,EAAA,EAAI,oBAAA,CAAqB,CAAA,GACzB,OAAA,EAAS,uBAAA,EACT,OAAA,YAAgB,OAAA;;;;;;;;YAgEF,OAAA,GAAA,CACd,EAAA,GAAK,MAAA,GAAS,WAAA,KAAgB,OAAA,CAAQ,CAAA,GACtC,OAAA,EAAS,uBAAA,EACT,OAAA,YACC,OAAA,CAAQ,CAAA;EAAA,UAsBD,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":";;;;;;;;;;;;;;;;;;;AAiJA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;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;EA2NS;EAAA,QAxNtB,mBAAA;EAyNN;EAAA,QAtNM,oBAAA;EAuNmB;;;;;;EAAA,OA/MpB,KAAA,EAAO,WAAA;EAiRU;;;EA5QxB,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;EAkPW;;;;;;;;;;;;;;;;;;;;;;;;EAtNX,OAAA,CAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAiDA,YAAA,CAAA,GAAgB,MAAA;;;;;;;;;;;YAcN,aAAA,CAAc,GAAA,EAAK,OAAA,CAAQ,OAAA;;;;;;;;;;;EAmBrC,MAAA,CAAO,GAAA,EAAK,OAAA,CAAQ,OAAA;;;;;;UAuCZ,uBAAA;EAAA,UAqBQ,aAAA,GAAA,CACd,GAAA,EAAK,YAAA,EACL,EAAA,EAAI,oBAAA,CAAqB,CAAA,GACzB,OAAA,EAAS,uBAAA,EACT,OAAA,YAAgB,OAAA;;;;;;;;YAgEF,OAAA,GAAA,CACd,EAAA,GAAK,MAAA,GAAS,WAAA,KAAgB,OAAA,CAAQ,CAAA,GACtC,OAAA,EAAS,uBAAA,EACT,OAAA,YACC,OAAA,CAAQ,CAAA;EAAA,UAsBD,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

@@ -34,6 +34,7 @@ const EXCLUDED_FROM_PROXY = new Set([
 	"getEndpoints",
 	"getSkipBodyParsingPaths",
 	"abortActiveOperations",
+	"clientConfig",
 	"asUser",
 	"constructor"
 ]);
@@ -191,6 +192,54 @@ var Plugin = class {
 		return {};
 	}
 	/**
+	* Returns startup config to expose to the client.
+	* Override this to surface server-side values that are safe to publish to the
+	* frontend, such as feature flags, resource IDs, or other app boot settings.
+	*
+	* This runs once when the server starts, so it should not depend on
+	* request-scoped or user-specific state.
+	*
+	* String values that match non-public environment variables are redacted
+	* unless you intentionally expose them via a matching `PUBLIC_APPKIT_` env var.
+	*
+	* Values must be JSON-serializable plain data (no functions, Dates, classes,
+	* Maps, Sets, BigInts, or circular references).
+	* By default returns an empty object (plugin contributes nothing to client config).
+	*
+	* On the client, read the config with the `usePluginClientConfig` hook
+	* (React) or the `getPluginClientConfig` function (vanilla JS), both
+	* from `@databricks/appkit-ui`.
+	*
+	* @example
+	* ```ts
+	* // Server — plugin definition
+	* class MyPlugin extends Plugin<MyConfig> {
+	*   clientConfig() {
+	*     return {
+	*       warehouseId: this.config.warehouseId,
+	*       features: { darkMode: true },
+	*     };
+	*   }
+	* }
+	*
+	* // Client — React component
+	* import { usePluginClientConfig } from "@databricks/appkit-ui/react";
+	*
+	* interface MyPluginConfig { warehouseId: string; features: { darkMode: boolean } }
+	*
+	* const config = usePluginClientConfig<MyPluginConfig>("myPlugin");
+	* config.warehouseId; // "abc-123"
+	*
+	* // Client — vanilla JS
+	* import { getPluginClientConfig } from "@databricks/appkit-ui/js";
+	*
+	* const config = getPluginClientConfig<MyPluginConfig>("myPlugin");
+	* ```
+	*/
+	clientConfig() {
+		return {};
+	}
+	/**
 	* Resolve the effective user ID from a request.
 	*
 	* Returns the `x-forwarded-user` header when present. In development mode
@@ -214,14 +263,14 @@ var Plugin = class {
 	* @param req - The Express request containing the user token in headers
 	* @returns A proxied plugin instance that executes as the user
 	* @throws AuthenticationError if user token is not available in request headers (production only).
-	*   In development mode (`NODE_ENV=development`), falls back to the service principal instead of throwing.
+	*   In development mode (`NODE_ENV=development`), skips user impersonation instead of throwing.
 	*/
 	asUser(req) {
 		const token = req.header("x-forwarded-access-token");
 		const userId = req.header("x-forwarded-user");
 		const isDev = process.env.NODE_ENV === "development";
 		if (!token && isDev) {
-			logger.warn("asUser() called without user token in development mode. Using service principal.");
+			logger.warn("asUser() called without user token in development mode. Skipping user impersonation.");
 			return this;
 		}
 		if (!token) throw AuthenticationError.missingToken("user token");

package/dist/plugin/plugin.js.map

@@ -1 +1 @@
-{"version":3,"file":"plugin.js","names":[],"sources":["../../src/plugin/plugin.ts"],"sourcesContent":["import type express from \"express\";\nimport type {\n  BasePlugin,\n  BasePluginConfig,\n  IAppResponse,\n  PluginEndpointMap,\n  PluginExecuteConfig,\n  PluginExecutionSettings,\n  PluginPhase,\n  RouteConfig,\n  StreamExecuteHandler,\n  StreamExecutionSettings,\n} from \"shared\";\nimport { AppManager } from \"../app\";\nimport { CacheManager } from \"../cache\";\nimport {\n  getCurrentUserId,\n  runInUserContext,\n  ServiceContext,\n  type UserContext,\n} from \"../context\";\nimport { 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 { 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 * 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  // 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   * 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`), falls back to the service principal 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, fall back to service principal\n    // since there's no user token available\n    if (!token && isDev) {\n      logger.warn(\n        \"asUser() called without user token in development mode. Using service principal.\",\n      );\n\n      return 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\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\n      const result = await self._executeWithInterceptors(\n        wrappedFn as (signal?: AbortSignal) => Promise<T>,\n        interceptors,\n        context,\n      );\n\n      // check if result is a generator\n      if (self._checkIfGenerator(result)) {\n        yield* result;\n      } else {\n        yield result;\n      }\n    };\n\n    // stream the result to the client\n    await this.streamManager.stream(res, asyncWrapperFn, streamConfig);\n  }\n\n  /**\n   * Execute a function with the plugin's interceptor chain.\n   *\n   * All errors are caught and `undefined` is returned (production-safe).\n   * Route handlers should check for `undefined` and respond with an\n   * appropriate error status.\n   */\n  protected async execute<T>(\n    fn: (signal?: AbortSignal) => Promise<T>,\n    options: PluginExecutionSettings,\n    userKey?: string,\n  ): Promise<T | undefined> {\n    const executeConfig = this._buildExecutionConfig(options);\n\n    const interceptors = this._buildInterceptors(executeConfig);\n\n    // 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      return await this._executeWithInterceptors(fn, interceptors, context);\n    } catch (error) {\n      // production-safe: swallow all errors, don't crash the app\n      logger.error(\"Plugin execution failed\", { error, plugin: this.name });\n      return undefined;\n    }\n  }\n\n  protected registerEndpoint(name: string, path: string): void {\n    this.registeredEndpoints[name] = path;\n  }\n\n  protected route<_TResponse>(\n    router: express.Router,\n    config: RouteConfig,\n  ): void {\n    const { name, method, path, handler } = config;\n\n    router[method](path, handler);\n\n    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":[],"sources":["../../src/plugin/plugin.ts"],"sourcesContent":["import type express from \"express\";\nimport type {\n  BasePlugin,\n  BasePluginConfig,\n  IAppResponse,\n  PluginEndpointMap,\n  PluginExecuteConfig,\n  PluginExecutionSettings,\n  PluginPhase,\n  RouteConfig,\n  StreamExecuteHandler,\n  StreamExecutionSettings,\n} from \"shared\";\nimport { AppManager } from \"../app\";\nimport { CacheManager } from \"../cache\";\nimport {\n  getCurrentUserId,\n  runInUserContext,\n  ServiceContext,\n  type UserContext,\n} from \"../context\";\nimport { 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 { 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 * 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 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\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\n      const result = await self._executeWithInterceptors(\n        wrappedFn as (signal?: AbortSignal) => Promise<T>,\n        interceptors,\n        context,\n      );\n\n      // check if result is a generator\n      if (self._checkIfGenerator(result)) {\n        yield* result;\n      } else {\n        yield result;\n      }\n    };\n\n    // stream the result to the client\n    await this.streamManager.stream(res, asyncWrapperFn, streamConfig);\n  }\n\n  /**\n   * Execute a function with the plugin's interceptor chain.\n   *\n   * All errors are caught and `undefined` is returned (production-safe).\n   * Route handlers should check for `undefined` and respond with an\n   * appropriate error status.\n   */\n  protected async execute<T>(\n    fn: (signal?: AbortSignal) => Promise<T>,\n    options: PluginExecutionSettings,\n    userKey?: string,\n  ): Promise<T | undefined> {\n    const executeConfig = this._buildExecutionConfig(options);\n\n    const interceptors = this._buildInterceptors(executeConfig);\n\n    // 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      return await this._executeWithInterceptors(fn, interceptors, context);\n    } catch (error) {\n      // production-safe: swallow all errors, don't crash the app\n      logger.error(\"Plugin execution failed\", { error, plugin: this.name });\n      return undefined;\n    }\n  }\n\n  protected registerEndpoint(name: string, path: string): void {\n    this.registeredEndpoints[name] = path;\n  }\n\n  protected route<_TResponse>(\n    router: express.Router,\n    config: RouteConfig,\n  ): void {\n    const { name, method, path, handler } = config;\n\n    router[method](path, handler);\n\n    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/files/plugin.d.ts

@@ -95,6 +95,7 @@ declare class FilesPlugin extends Plugin {
    * ```
    */
   exports(): FilesExport;
+  clientConfig(): Record<string, unknown>;
 }
 /**
  * @internal

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

@@ -1 +1 @@
-{"version":3,"file":"plugin.d.ts","names":[],"sources":["../../../src/plugins/files/plugin.ts"],"mappings":";;;;;;;;;cAmCa,WAAA,SAAoB,MAAA;EAC/B,IAAA;;SAGO,QAAA,EAAuB,cAAA;EAAA,iBACb,WAAA;EAAA,UACC,MAAA,EAAQ,YAAA;EAAA,QAElB,gBAAA;EAAA,QACA,aAAA;EAAA,QACA,UAAA;EAJkB;;;;;EAAA,OAWnB,eAAA,CAAgB,MAAA,EAAQ,YAAA,GAAe,MAAA,SAAe,YAAA;EAkEzC;;;;EAAA,OA3Cb,uBAAA,CAAwB,MAAA,EAAQ,YAAA,GAAe,mBAAA;EAxCvB;;;;EAAA,QA8DvB,mBAAA;EA1DD;;;;EAAA,QAuEC,oBAAA;cAQI,MAAA,EAAQ,YAAA;EA1EZ;;;;EAAA,UA+GE,eAAA,CAAgB,SAAA,WAAoB,SAAA;EAmD9C,YAAA,CAAa,MAAA,EAAQ,UAAA;EA1JwC;;;;EAAA,QAwRrD,cAAA;EA3OA;;;;EAAA,QAkQA,YAAA;EAAA,QAQA,aAAA;EAhNkB;;;;;EAAA,QAgOlB,oBAAA;EAAA,QAiBA,eAAA;EAAA,QA8BM,WAAA;EAAA,QA+BA,WAAA;EAAA,QAoCA,eAAA;EAAA,QAWA,UAAA;EA/CA;;;;;EAAA,QA+DA,UAAA;EAAA,QAgFA,aAAA;EAAA,QAsCA,eAAA;EAAA,QAsCA,cAAA;EAAA,QAoCA,aAAA;EAAA,QA2GA,YAAA;EAAA,QA+CA,aAAA;EAAA,QA6CN,cAAA;EAAA,QAEA,UAAA;EAOF,QAAA,CAAA,GAAY,OAAA;EAgCP;;;AA+Bb;;;;;;;;;;EA/BE,OAAA,CAAA,GAAW,WAAA;AAAA;;;;cA+BA,KAAA,EAAK,QAAA,QAAA,WAAA,EAAA,YAAA"}
+{"version":3,"file":"plugin.d.ts","names":[],"sources":["../../../src/plugins/files/plugin.ts"],"mappings":";;;;;;;;;cAmCa,WAAA,SAAoB,MAAA;EAC/B,IAAA;;SAGO,QAAA,EAAuB,cAAA;EAAA,iBACb,WAAA;EAAA,UACC,MAAA,EAAQ,YAAA;EAAA,QAElB,gBAAA;EAAA,QACA,aAAA;EAAA,QACA,UAAA;EAJkB;;;;;EAAA,OAWnB,eAAA,CAAgB,MAAA,EAAQ,YAAA,GAAe,MAAA,SAAe,YAAA;EAkEzC;;;;EAAA,OA3Cb,uBAAA,CAAwB,MAAA,EAAQ,YAAA,GAAe,mBAAA;EAw4BtC;;;;EAAA,QAl3BR,mBAAA;EA7DR;;;;EAAA,QA0EQ,oBAAA;cAQI,MAAA,EAAQ,YAAA;EA3EZ;;;;EAAA,UAgHE,eAAA,CAAgB,SAAA,WAAoB,SAAA;EAmD9C,YAAA,CAAa,MAAA,EAAQ,UAAA;EA1JyB;;;;EAAA,QAwRtC,cAAA;EAjQ8C;;;;EAAA,QAwR9C,YAAA;EAAA,QAQA,aAAA;EAhNE;;;;;EAAA,QAgOF,oBAAA;EAAA,QAiBA,eAAA;EAAA,QA8BM,WAAA;EAAA,QA+BA,WAAA;EAAA,QAoCA,eAAA;EAAA,QAWA,UAAA;EA9EA;;;;;EAAA,QA8FA,UAAA;EAAA,QAgFA,aAAA;EAAA,QAsCA,eAAA;EAAA,QAsCA,cAAA;EAAA,QAoCA,aAAA;EAAA,QA2GA,YAAA;EAAA,QA+CA,aAAA;EAAA,QA6CN,cAAA;EAAA,QAEA,UAAA;EAOF,QAAA,CAAA,GAAY,OAAA;EAgClB;;;;;;AAmCF;;;;;;;EAnCE,OAAA,CAAA,GAAW,WAAA;EA2BX,YAAA,CAAA,GAAgB,MAAA;AAAA;;;;cAQL,KAAA,EAAK,QAAA,QAAA,WAAA,EAAA,YAAA"}

package/dist/plugins/files/plugin.js

@@ -703,6 +703,9 @@ var FilesPlugin = class FilesPlugin extends Plugin {
 		filesExport.volume = resolveVolume;
 		return filesExport;
 	}
+	clientConfig() {
+		return { volumes: this.volumeKeys };
+	}
 };
 /**
 * @internal