@dbx-tools/appkit-mastra-shared 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Wire-format types and URL helpers shipped by `@dbx-tools/appkit-mastra`'s
+ * `clientConfig()` surface.
+ *
+ * Kept dependency-free (no `pg`, no `fastembed`, no Mastra runtime) so
+ * the React client and any browser bundle can import these types
+ * without dragging in server-only dependencies. The server-side plugin
+ * publishes resolved paths through this contract; the client reads
+ * them back via `usePluginClientConfig<MastraClientConfig>("mastra")`
+ * and composes URLs with {@link chatUrl}.
+ */
+export * from "./src/protocol.js";

package/dist/index.js

@@ -0,0 +1,12 @@
+/**
+ * Wire-format types and URL helpers shipped by `@dbx-tools/appkit-mastra`'s
+ * `clientConfig()` surface.
+ *
+ * Kept dependency-free (no `pg`, no `fastembed`, no Mastra runtime) so
+ * the React client and any browser bundle can import these types
+ * without dragging in server-only dependencies. The server-side plugin
+ * publishes resolved paths through this contract; the client reads
+ * them back via `usePluginClientConfig<MastraClientConfig>("mastra")`
+ * and composes URLs with {@link chatUrl}.
+ */
+export * from "./src/protocol.js";

package/dist/src/protocol.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Shape of the data published by {@link MastraPlugin.clientConfig} plus
+ * a tiny URL helper. Kept dependency-free so the React client can
+ * import it without dragging in `pg`, `fastembed`, or Mastra itself.
+ *
+ * Server-side, `MastraPlugin` derives every path from the plugin mount
+ * (AppKit conventionally serves plugin `foo` at `/api/foo`). Publishing
+ * the resolved paths lets the client compute URLs without hard-coding
+ * `/api/mastra` anywhere - rename the plugin and the React client
+ * keeps working.
+ *
+ * @example
+ * ```tsx
+ * import { usePluginClientConfig } from "@databricks/appkit-ui/react";
+ * import { chatUrl, type MastraClientConfig } from "@dbx-tools/appkit-mastra-shared";
+ *
+ * const config = usePluginClientConfig<MastraClientConfig>("mastra");
+ * const transport = new DefaultChatTransport({
+ *   api: chatUrl(config, selectedAgentId),
+ * });
+ * ```
+ */
+/** JSON-safe descriptor published by the Mastra plugin's `clientConfig()`. */
+export interface MastraClientConfig {
+    /** Plugin mount path. Always `/api/<pluginName>`. */
+    basePath: string;
+    /**
+     * Chat endpoint for the **default** agent, i.e.
+     * `${basePath}/route/chat`. Equivalent to `chatUrl(config)`.
+     */
+    chatPath: string;
+    /**
+     * Template form used by the route handler:
+     * `${basePath}/route/chat/:agentId`. Provided for documentation /
+     * tools that want the OpenAPI-style placeholder; clients should
+     * normally call {@link chatUrl} instead.
+     */
+    chatPathTemplate: string;
+    /** Models catalogue endpoint: `${basePath}/models`. */
+    modelsPath: string;
+    /** Agent id `chatRoute` binds to when the client doesn't name one. */
+    defaultAgent: string;
+    /** Every registered agent id in registration order. */
+    agents: string[];
+}
+/**
+ * Minimal descriptor for a Databricks Model Serving endpoint. Mirrors
+ * the server-side `ServingEndpointSummary` from `serving.ts` and is
+ * kept here so the React client can type the `/models` response
+ * without importing the full plugin (which would pull in `pg`,
+ * `fastembed`, and Mastra itself).
+ */
+export interface ServingEndpointSummary {
+    /** Endpoint name as listed by the Model Serving REST API. */
+    name: string;
+    /** Task hint (e.g. `"llm/v1/chat"`). Useful for filtering. */
+    task?: string;
+    /** Ready / updating / failed state. */
+    state?: string;
+    /** Free-form description; mostly informational. */
+    description?: string;
+}
+/** JSON payload returned by `GET ${basePath}/models`. */
+export interface ServingEndpointsResponse {
+    endpoints: ServingEndpointSummary[];
+}
+/**
+ * Compute the chat URL for a given agent, falling back to the default
+ * when `agentId` is omitted. Returns `config.chatPath` directly for
+ * the default agent (the `chatRoute` mount that does not require an
+ * `:agentId` segment).
+ */
+export declare function chatUrl(config: Pick<MastraClientConfig, "chatPath" | "defaultAgent">, agentId?: string): string;

package/dist/src/protocol.js

@@ -0,0 +1,34 @@
+/**
+ * Shape of the data published by {@link MastraPlugin.clientConfig} plus
+ * a tiny URL helper. Kept dependency-free so the React client can
+ * import it without dragging in `pg`, `fastembed`, or Mastra itself.
+ *
+ * Server-side, `MastraPlugin` derives every path from the plugin mount
+ * (AppKit conventionally serves plugin `foo` at `/api/foo`). Publishing
+ * the resolved paths lets the client compute URLs without hard-coding
+ * `/api/mastra` anywhere - rename the plugin and the React client
+ * keeps working.
+ *
+ * @example
+ * ```tsx
+ * import { usePluginClientConfig } from "@databricks/appkit-ui/react";
+ * import { chatUrl, type MastraClientConfig } from "@dbx-tools/appkit-mastra-shared";
+ *
+ * const config = usePluginClientConfig<MastraClientConfig>("mastra");
+ * const transport = new DefaultChatTransport({
+ *   api: chatUrl(config, selectedAgentId),
+ * });
+ * ```
+ */
+/**
+ * Compute the chat URL for a given agent, falling back to the default
+ * when `agentId` is omitted. Returns `config.chatPath` directly for
+ * the default agent (the `chatRoute` mount that does not require an
+ * `:agentId` segment).
+ */
+export function chatUrl(config, agentId) {
+    const id = agentId ?? config.defaultAgent;
+    if (!id || id === config.defaultAgent)
+        return config.chatPath;
+    return `${config.chatPath}/${encodeURIComponent(id)}`;
+}

package/index.ts

@@ -0,0 +1,12 @@
+/**
+ * Wire-format types and URL helpers shipped by `@dbx-tools/appkit-mastra`'s
+ * `clientConfig()` surface.
+ *
+ * Kept dependency-free (no `pg`, no `fastembed`, no Mastra runtime) so
+ * the React client and any browser bundle can import these types
+ * without dragging in server-only dependencies. The server-side plugin
+ * publishes resolved paths through this contract; the client reads
+ * them back via `usePluginClientConfig<MastraClientConfig>("mastra")`
+ * and composes URLs with {@link chatUrl}.
+ */
+export * from "./src/protocol.js";

package/package.json

@@ -0,0 +1,34 @@
+{
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "source": "./index.ts",
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "index.ts",
+    "src"
+  ],
+  "license": "Apache-2.0",
+  "homepage": "https://github.com/reggie-db/dbx-tools-appkit#readme",
+  "bugs": {
+    "url": "https://github.com/reggie-db/dbx-tools-appkit/issues"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/reggie-db/dbx-tools-appkit.git",
+    "directory": "packages/mastra-shared"
+  },
+  "name": "@dbx-tools/appkit-mastra-shared",
+  "version": "0.1.0",
+  "module": "index.ts",
+  "type": "module"
+}

package/src/protocol.ts

@@ -0,0 +1,84 @@
+/**
+ * Shape of the data published by {@link MastraPlugin.clientConfig} plus
+ * a tiny URL helper. Kept dependency-free so the React client can
+ * import it without dragging in `pg`, `fastembed`, or Mastra itself.
+ *
+ * Server-side, `MastraPlugin` derives every path from the plugin mount
+ * (AppKit conventionally serves plugin `foo` at `/api/foo`). Publishing
+ * the resolved paths lets the client compute URLs without hard-coding
+ * `/api/mastra` anywhere - rename the plugin and the React client
+ * keeps working.
+ *
+ * @example
+ * ```tsx
+ * import { usePluginClientConfig } from "@databricks/appkit-ui/react";
+ * import { chatUrl, type MastraClientConfig } from "@dbx-tools/appkit-mastra-shared";
+ *
+ * const config = usePluginClientConfig<MastraClientConfig>("mastra");
+ * const transport = new DefaultChatTransport({
+ *   api: chatUrl(config, selectedAgentId),
+ * });
+ * ```
+ */
+
+/** JSON-safe descriptor published by the Mastra plugin's `clientConfig()`. */
+export interface MastraClientConfig {
+  /** Plugin mount path. Always `/api/<pluginName>`. */
+  basePath: string;
+  /**
+   * Chat endpoint for the **default** agent, i.e.
+   * `${basePath}/route/chat`. Equivalent to `chatUrl(config)`.
+   */
+  chatPath: string;
+  /**
+   * Template form used by the route handler:
+   * `${basePath}/route/chat/:agentId`. Provided for documentation /
+   * tools that want the OpenAPI-style placeholder; clients should
+   * normally call {@link chatUrl} instead.
+   */
+  chatPathTemplate: string;
+  /** Models catalogue endpoint: `${basePath}/models`. */
+  modelsPath: string;
+  /** Agent id `chatRoute` binds to when the client doesn't name one. */
+  defaultAgent: string;
+  /** Every registered agent id in registration order. */
+  agents: string[];
+}
+
+/**
+ * Minimal descriptor for a Databricks Model Serving endpoint. Mirrors
+ * the server-side `ServingEndpointSummary` from `serving.ts` and is
+ * kept here so the React client can type the `/models` response
+ * without importing the full plugin (which would pull in `pg`,
+ * `fastembed`, and Mastra itself).
+ */
+export interface ServingEndpointSummary {
+  /** Endpoint name as listed by the Model Serving REST API. */
+  name: string;
+  /** Task hint (e.g. `"llm/v1/chat"`). Useful for filtering. */
+  task?: string;
+  /** Ready / updating / failed state. */
+  state?: string;
+  /** Free-form description; mostly informational. */
+  description?: string;
+}
+
+/** JSON payload returned by `GET ${basePath}/models`. */
+export interface ServingEndpointsResponse {
+  endpoints: ServingEndpointSummary[];
+}
+
+/**
+ * Compute the chat URL for a given agent, falling back to the default
+ * when `agentId` is omitted. Returns `config.chatPath` directly for
+ * the default agent (the `chatRoute` mount that does not require an
+ * `:agentId` segment).
+ */
+export function chatUrl(
+  config: Pick<MastraClientConfig, "chatPath" | "defaultAgent">,
+  agentId?: string,
+): string {
+  const id = agentId ?? config.defaultAgent;
+  if (!id || id === config.defaultAgent) return config.chatPath;
+  return `${config.chatPath}/${encodeURIComponent(id)}`;
+}