@decaf-ts/integrations 0.3.12 → 0.4.1-0

package/lib/types/plugins/contract.d.cts

@@ -0,0 +1,180 @@
+/**
+ * @module integrations/plugins/contract
+ * @summary Shared, DOM-free contract for BI dashboard embed plugins.
+ * @description Defines the message protocol, embed URL options, install
+ * options/result, plugin descriptor, and the `DashboardEmbedPlugin` interface
+ * that both the Kibana and Superset plugins implement with the exact same API.
+ *
+ * This contract is intentionally DOM-free (no `window` / `HTMLIFrameElement`)
+ * so it builds under the Node `lib: ["es2022"]` tsconfig and is consumable from
+ * both Node and the browser. The Angular host supplies a DOM-free
+ * `EmbedMessageTarget` (typically `iframe.contentWindow`).
+ */
+import type { MaybeContextualArg } from "@decaf-ts/core";
+/**
+ * Message type constants shared between the embedded plugin and the host.
+ * The plugin is org-agnostic: there is never space switching; the current
+ * Kibana space comes from the request/session/proxy context.
+ */
+export declare const EMBED_MESSAGE_TYPE: {
+    readonly SWITCH: "ORG_DASHBOARD_EMBED_SWITCH_DASHBOARD";
+    readonly READY: "ORG_DASHBOARD_EMBED_READY";
+    readonly RENDERED: "ORG_DASHBOARD_EMBED_RENDERED";
+    readonly ERROR: "ORG_DASHBOARD_EMBED_ERROR";
+};
+export type EmbedMessageType = (typeof EMBED_MESSAGE_TYPE)[keyof typeof EMBED_MESSAGE_TYPE];
+export interface DashboardQuery {
+    language: "kuery" | "lucene";
+    query: string;
+}
+export interface DashboardTimeRange {
+    from: string;
+    to: string;
+}
+/**
+ * Payload used to switch dashboards at runtime.
+ *
+ * `guestToken` is used by Superset (which requires a dashboard-scoped guest
+ * token for each switch) and ignored by Kibana (which relies on the session
+ * space context). This keeps the payload shape identical across both plugins.
+ */
+export interface SwitchDashboardPayload {
+    dashboardId: string;
+    timeRange?: DashboardTimeRange;
+    query?: DashboardQuery;
+    filters?: unknown[];
+    /** Superset-only: dashboard-scoped guest token. Kibana ignores this. */
+    guestToken?: string;
+}
+export interface SwitchDashboardMessage extends SwitchDashboardPayload {
+    type: typeof EMBED_MESSAGE_TYPE.SWITCH;
+}
+export interface EmbedReadyMessage {
+    type: typeof EMBED_MESSAGE_TYPE.READY;
+    dashboardId: string | null;
+}
+export interface EmbedRenderedMessage {
+    type: typeof EMBED_MESSAGE_TYPE.RENDERED;
+    dashboardId: string;
+}
+export interface EmbedErrorMessage {
+    type: typeof EMBED_MESSAGE_TYPE.ERROR;
+    dashboardId: string | null;
+    message: string;
+}
+/**
+ * Union of messages the embedded plugin posts back to the parent host.
+ */
+export type EmbedParentMessage = EmbedReadyMessage | EmbedRenderedMessage | EmbedErrorMessage;
+/**
+ * DOM-free message target. Both Kibana and Superset use the same interface;
+ * each tool uses a different mechanism:
+ *
+ * - **Kibana:** the Angular host passes `iframe.contentWindow`, which provides
+ *   `postMessage`. `switchDashboard` is unused.
+ * - **Superset:** the Angular host passes the embedded SDK's
+ *   `EmbeddedDashboard` handle (wrapped), which provides `switchDashboard`.
+ *   `postMessage` is unused.
+ *
+ * At least one of the two methods must be present; each plugin checks for the
+ * mechanism it needs and throws an `UnsupportedError` if absent.
+ */
+export interface EmbedMessageTarget {
+    /** Kibana mechanism: post a message to the iframe window. */
+    postMessage?(message: unknown, targetOrigin: string): void;
+    /** Superset mechanism: call the SDK's switchDashboard method. */
+    switchDashboard?(dashboardId: string, guestToken?: string): Promise<unknown>;
+}
+export interface EmbedViewOptions {
+    showTimeFilter?: boolean;
+    showQueryInput?: boolean;
+    showFilterBar?: boolean;
+    hidePanelTitles?: boolean;
+    timeRange?: DashboardTimeRange;
+}
+export interface EmbedUrlOptions {
+    /** Host without protocol, e.g. "ptp.host". */
+    host: string;
+    /** Base path, e.g. "kibana". Defaults to the tool default. */
+    basePath?: string;
+    /** Initial dashboard id to render. */
+    dashboardId: string;
+    /** Parent origin allowlist (comma-separated) passed to the plugin. */
+    parentOrigin: string;
+    /** Optional view overrides. */
+    view?: EmbedViewOptions;
+}
+export type BiTool = "kibana" | "superset";
+export interface DashboardEmbedPluginDescriptor {
+    /** Plugin id (e.g. "orgDashboardEmbed"). */
+    id: string;
+    /** Kibana application id (e.g. "org_dashboard_embed"). */
+    appId: string;
+    /** Plugin version. */
+    version: string;
+    /** Target BI tool version this plugin is built against. */
+    targetVersion: string;
+    /** BI tool this plugin targets. */
+    tool: BiTool;
+}
+export interface PluginInstallOptions {
+    /** Directory to materialize the plugin into. */
+    targetPath: string;
+    /** Overrides `descriptor.targetVersion` when provided. */
+    targetVersion?: string;
+    /** Attempt to build the plugin after writing files (best-effort). */
+    build?: boolean;
+    /** Overwrite an existing plugin directory. */
+    overwrite?: boolean;
+    /** Optional context for tracing/logging. */
+    context?: MaybeContextualArg<any>;
+}
+export interface PluginInstallResult {
+    /** Absolute path to the materialized plugin directory. */
+    pluginPath: string;
+    /** Descriptor used for this install. */
+    descriptor: DashboardEmbedPluginDescriptor;
+    /** Relative file paths written. */
+    files: string[];
+    /** Whether a build was attempted and reported success. */
+    built: boolean;
+    /** Captured build output (stdout/stderr) when `build` was requested. */
+    buildOutput?: string;
+}
+/**
+ * Contract both BI dashboard embed plugins implement. Both Kibana and
+ * Superset plugins expose the exact same API surface.
+ */
+export interface DashboardEmbedPlugin {
+    readonly descriptor: DashboardEmbedPluginDescriptor;
+    /** Build the BI-tool manifest (e.g. kibana.json) for a target version. */
+    manifest(targetVersion?: string): Record<string, unknown>;
+    /** Build the stable iframe embed URL. */
+    buildEmbedUrl(options: EmbedUrlOptions): string;
+    /** Create a switch-dashboard message object. */
+    createSwitchDashboardMessage(payload: SwitchDashboardPayload): SwitchDashboardMessage;
+    /** Send a switch-dashboard message to the embedded plugin via `postMessage`. */
+    sendSwitchDashboardMessage(target: EmbedMessageTarget, payload: SwitchDashboardPayload, targetOrigin: string): void;
+    /** Materialize (and optionally build) the plugin into a target directory. */
+    install(options: PluginInstallOptions): Promise<PluginInstallResult>;
+}
+/**
+ * Type guard for the switch-dashboard message received by the embedded plugin.
+ */
+export declare function isSwitchDashboardMessage(data: unknown): data is SwitchDashboardMessage;
+/**
+ * Type guard for parent-bound messages emitted by the embedded plugin.
+ */
+export declare function isEmbedParentMessage(data: unknown): data is EmbedParentMessage;
+/**
+ * Build a switch-dashboard message from a payload (shared by both plugins).
+ */
+export declare function createSwitchDashboardMessage(payload: SwitchDashboardPayload): SwitchDashboardMessage;
+/**
+ * Send a switch-dashboard message to a DOM-free target.
+ *
+ * If the target supports `postMessage` (Kibana), the message is posted
+ * directly. If the target supports `switchDashboard` (Superset SDK handle),
+ * the SDK method is invoked instead. Both paths use the same payload shape.
+ */
+export declare function sendSwitchDashboardMessage(target: EmbedMessageTarget, payload: SwitchDashboardPayload, targetOrigin: string): void;

package/lib/types/plugins/contract.d.mts

@@ -0,0 +1,180 @@
+/**
+ * @module integrations/plugins/contract
+ * @summary Shared, DOM-free contract for BI dashboard embed plugins.
+ * @description Defines the message protocol, embed URL options, install
+ * options/result, plugin descriptor, and the `DashboardEmbedPlugin` interface
+ * that both the Kibana and Superset plugins implement with the exact same API.
+ *
+ * This contract is intentionally DOM-free (no `window` / `HTMLIFrameElement`)
+ * so it builds under the Node `lib: ["es2022"]` tsconfig and is consumable from
+ * both Node and the browser. The Angular host supplies a DOM-free
+ * `EmbedMessageTarget` (typically `iframe.contentWindow`).
+ */
+import type { MaybeContextualArg } from "@decaf-ts/core";
+/**
+ * Message type constants shared between the embedded plugin and the host.
+ * The plugin is org-agnostic: there is never space switching; the current
+ * Kibana space comes from the request/session/proxy context.
+ */
+export declare const EMBED_MESSAGE_TYPE: {
+    readonly SWITCH: "ORG_DASHBOARD_EMBED_SWITCH_DASHBOARD";
+    readonly READY: "ORG_DASHBOARD_EMBED_READY";
+    readonly RENDERED: "ORG_DASHBOARD_EMBED_RENDERED";
+    readonly ERROR: "ORG_DASHBOARD_EMBED_ERROR";
+};
+export type EmbedMessageType = (typeof EMBED_MESSAGE_TYPE)[keyof typeof EMBED_MESSAGE_TYPE];
+export interface DashboardQuery {
+    language: "kuery" | "lucene";
+    query: string;
+}
+export interface DashboardTimeRange {
+    from: string;
+    to: string;
+}
+/**
+ * Payload used to switch dashboards at runtime.
+ *
+ * `guestToken` is used by Superset (which requires a dashboard-scoped guest
+ * token for each switch) and ignored by Kibana (which relies on the session
+ * space context). This keeps the payload shape identical across both plugins.
+ */
+export interface SwitchDashboardPayload {
+    dashboardId: string;
+    timeRange?: DashboardTimeRange;
+    query?: DashboardQuery;
+    filters?: unknown[];
+    /** Superset-only: dashboard-scoped guest token. Kibana ignores this. */
+    guestToken?: string;
+}
+export interface SwitchDashboardMessage extends SwitchDashboardPayload {
+    type: typeof EMBED_MESSAGE_TYPE.SWITCH;
+}
+export interface EmbedReadyMessage {
+    type: typeof EMBED_MESSAGE_TYPE.READY;
+    dashboardId: string | null;
+}
+export interface EmbedRenderedMessage {
+    type: typeof EMBED_MESSAGE_TYPE.RENDERED;
+    dashboardId: string;
+}
+export interface EmbedErrorMessage {
+    type: typeof EMBED_MESSAGE_TYPE.ERROR;
+    dashboardId: string | null;
+    message: string;
+}
+/**
+ * Union of messages the embedded plugin posts back to the parent host.
+ */
+export type EmbedParentMessage = EmbedReadyMessage | EmbedRenderedMessage | EmbedErrorMessage;
+/**
+ * DOM-free message target. Both Kibana and Superset use the same interface;
+ * each tool uses a different mechanism:
+ *
+ * - **Kibana:** the Angular host passes `iframe.contentWindow`, which provides
+ *   `postMessage`. `switchDashboard` is unused.
+ * - **Superset:** the Angular host passes the embedded SDK's
+ *   `EmbeddedDashboard` handle (wrapped), which provides `switchDashboard`.
+ *   `postMessage` is unused.
+ *
+ * At least one of the two methods must be present; each plugin checks for the
+ * mechanism it needs and throws an `UnsupportedError` if absent.
+ */
+export interface EmbedMessageTarget {
+    /** Kibana mechanism: post a message to the iframe window. */
+    postMessage?(message: unknown, targetOrigin: string): void;
+    /** Superset mechanism: call the SDK's switchDashboard method. */
+    switchDashboard?(dashboardId: string, guestToken?: string): Promise<unknown>;
+}
+export interface EmbedViewOptions {
+    showTimeFilter?: boolean;
+    showQueryInput?: boolean;
+    showFilterBar?: boolean;
+    hidePanelTitles?: boolean;
+    timeRange?: DashboardTimeRange;
+}
+export interface EmbedUrlOptions {
+    /** Host without protocol, e.g. "ptp.host". */
+    host: string;
+    /** Base path, e.g. "kibana". Defaults to the tool default. */
+    basePath?: string;
+    /** Initial dashboard id to render. */
+    dashboardId: string;
+    /** Parent origin allowlist (comma-separated) passed to the plugin. */
+    parentOrigin: string;
+    /** Optional view overrides. */
+    view?: EmbedViewOptions;
+}
+export type BiTool = "kibana" | "superset";
+export interface DashboardEmbedPluginDescriptor {
+    /** Plugin id (e.g. "orgDashboardEmbed"). */
+    id: string;
+    /** Kibana application id (e.g. "org_dashboard_embed"). */
+    appId: string;
+    /** Plugin version. */
+    version: string;
+    /** Target BI tool version this plugin is built against. */
+    targetVersion: string;
+    /** BI tool this plugin targets. */
+    tool: BiTool;
+}
+export interface PluginInstallOptions {
+    /** Directory to materialize the plugin into. */
+    targetPath: string;
+    /** Overrides `descriptor.targetVersion` when provided. */
+    targetVersion?: string;
+    /** Attempt to build the plugin after writing files (best-effort). */
+    build?: boolean;
+    /** Overwrite an existing plugin directory. */
+    overwrite?: boolean;
+    /** Optional context for tracing/logging. */
+    context?: MaybeContextualArg<any>;
+}
+export interface PluginInstallResult {
+    /** Absolute path to the materialized plugin directory. */
+    pluginPath: string;
+    /** Descriptor used for this install. */
+    descriptor: DashboardEmbedPluginDescriptor;
+    /** Relative file paths written. */
+    files: string[];
+    /** Whether a build was attempted and reported success. */
+    built: boolean;
+    /** Captured build output (stdout/stderr) when `build` was requested. */
+    buildOutput?: string;
+}
+/**
+ * Contract both BI dashboard embed plugins implement. Both Kibana and
+ * Superset plugins expose the exact same API surface.
+ */
+export interface DashboardEmbedPlugin {
+    readonly descriptor: DashboardEmbedPluginDescriptor;
+    /** Build the BI-tool manifest (e.g. kibana.json) for a target version. */
+    manifest(targetVersion?: string): Record<string, unknown>;
+    /** Build the stable iframe embed URL. */
+    buildEmbedUrl(options: EmbedUrlOptions): string;
+    /** Create a switch-dashboard message object. */
+    createSwitchDashboardMessage(payload: SwitchDashboardPayload): SwitchDashboardMessage;
+    /** Send a switch-dashboard message to the embedded plugin via `postMessage`. */
+    sendSwitchDashboardMessage(target: EmbedMessageTarget, payload: SwitchDashboardPayload, targetOrigin: string): void;
+    /** Materialize (and optionally build) the plugin into a target directory. */
+    install(options: PluginInstallOptions): Promise<PluginInstallResult>;
+}
+/**
+ * Type guard for the switch-dashboard message received by the embedded plugin.
+ */
+export declare function isSwitchDashboardMessage(data: unknown): data is SwitchDashboardMessage;
+/**
+ * Type guard for parent-bound messages emitted by the embedded plugin.
+ */
+export declare function isEmbedParentMessage(data: unknown): data is EmbedParentMessage;
+/**
+ * Build a switch-dashboard message from a payload (shared by both plugins).
+ */
+export declare function createSwitchDashboardMessage(payload: SwitchDashboardPayload): SwitchDashboardMessage;
+/**
+ * Send a switch-dashboard message to a DOM-free target.
+ *
+ * If the target supports `postMessage` (Kibana), the message is posted
+ * directly. If the target supports `switchDashboard` (Superset SDK handle),
+ * the SDK method is invoked instead. Both paths use the same payload shape.
+ */
+export declare function sendSwitchDashboardMessage(target: EmbedMessageTarget, payload: SwitchDashboardPayload, targetOrigin: string): void;

package/lib/types/plugins/index.d.cts

@@ -0,0 +1,17 @@
+/**
+ * @module integrations/plugins
+ * @summary BI dashboard embed plugin surface.
+ * @description Aggregates the shared DOM-free contract and both BI tool
+ * plugins (Kibana + Superset). Both plugins implement the exact same
+ * `DashboardEmbedPlugin` API.
+ *
+ * - **Kibana:** generated plugin source + installer (writes files, optional build).
+ * - **Superset:** patch-and-build strategy (patches Superset's internal source,
+ *   builds SDK + frontend + optionally Docker image).
+ *
+ * Both are org-agnostic: there is never space switching. The current BI space
+ * comes from the request/session/proxy context, not from the plugin.
+ */
+export * from "./contract.d.cts";
+export * from "./kibana/index.d.cts";
+export * from "./superset/index.d.cts";

package/lib/types/plugins/index.d.mts

@@ -0,0 +1,17 @@
+/**
+ * @module integrations/plugins
+ * @summary BI dashboard embed plugin surface.
+ * @description Aggregates the shared DOM-free contract and both BI tool
+ * plugins (Kibana + Superset). Both plugins implement the exact same
+ * `DashboardEmbedPlugin` API.
+ *
+ * - **Kibana:** generated plugin source + installer (writes files, optional build).
+ * - **Superset:** patch-and-build strategy (patches Superset's internal source,
+ *   builds SDK + frontend + optionally Docker image).
+ *
+ * Both are org-agnostic: there is never space switching. The current BI space
+ * comes from the request/session/proxy context, not from the plugin.
+ */
+export * from "./contract.d.mts";
+export * from "./kibana/index.d.mts";
+export * from "./superset/index.d.mts";

package/lib/types/plugins/kibana/host.d.cts

@@ -0,0 +1,18 @@
+/**
+ * @module integrations/plugins/kibana/host
+ * @summary Angular host-side helpers for the Kibana embed plugin.
+ * @description DOM-free convenience helpers the Angular host uses to build the
+ * stable iframe URL and send switch-dashboard messages to the embedded plugin.
+ */
+import { type EmbedMessageTarget, type EmbedUrlOptions, type SwitchDashboardPayload } from "../contract.d.cts";
+import { buildKibanaEmbedUrl } from "./installer.d.cts";
+export { buildKibanaEmbedUrl };
+/**
+ * Send a switch-dashboard message to the embedded Kibana plugin.
+ *
+ * The Angular host passes `iframe.contentWindow` (which satisfies
+ * `EmbedMessageTarget`) and the Kibana origin as `targetOrigin`.
+ */
+export declare function sendKibanaSwitchDashboardMessage(target: EmbedMessageTarget, payload: SwitchDashboardPayload, targetOrigin: string): void;
+/** Re-export the URL options type for host convenience. */
+export type { EmbedUrlOptions };

package/lib/types/plugins/kibana/host.d.mts

@@ -0,0 +1,18 @@
+/**
+ * @module integrations/plugins/kibana/host
+ * @summary Angular host-side helpers for the Kibana embed plugin.
+ * @description DOM-free convenience helpers the Angular host uses to build the
+ * stable iframe URL and send switch-dashboard messages to the embedded plugin.
+ */
+import { type EmbedMessageTarget, type EmbedUrlOptions, type SwitchDashboardPayload } from "../contract.d.mts";
+import { buildKibanaEmbedUrl } from "./installer.d.mts";
+export { buildKibanaEmbedUrl };
+/**
+ * Send a switch-dashboard message to the embedded Kibana plugin.
+ *
+ * The Angular host passes `iframe.contentWindow` (which satisfies
+ * `EmbedMessageTarget`) and the Kibana origin as `targetOrigin`.
+ */
+export declare function sendKibanaSwitchDashboardMessage(target: EmbedMessageTarget, payload: SwitchDashboardPayload, targetOrigin: string): void;
+/** Re-export the URL options type for host convenience. */
+export type { EmbedUrlOptions };

package/lib/types/plugins/kibana/index.d.cts

@@ -0,0 +1,13 @@
+/**
+ * @module integrations/plugins/kibana
+ * @summary Kibana dashboard embed plugin surface.
+ * @description Org-agnostic multi-tenant Kibana dashboard embed plugin,
+ * installer, and host helpers. There is never space switching; the current
+ * Kibana space comes from the request/session/proxy context.
+ */
+export * from "../contract.d.cts";
+export * from "./types.d.cts";
+export * from "./manifest.d.cts";
+export * from "./templates.d.cts";
+export { KibanaDashboardEmbedPlugin, kibanaDashboardEmbedPlugin, createKibanaDashboardEmbedPlugin, buildKibanaEmbedUrl, KIBANA_DEFAULT_BASE_PATH, } from "./installer.d.cts";
+export { sendKibanaSwitchDashboardMessage, } from "./host.d.cts";

package/lib/types/plugins/kibana/index.d.mts

@@ -0,0 +1,13 @@
+/**
+ * @module integrations/plugins/kibana
+ * @summary Kibana dashboard embed plugin surface.
+ * @description Org-agnostic multi-tenant Kibana dashboard embed plugin,
+ * installer, and host helpers. There is never space switching; the current
+ * Kibana space comes from the request/session/proxy context.
+ */
+export * from "../contract.d.mts";
+export * from "./types.d.mts";
+export * from "./manifest.d.mts";
+export * from "./templates.d.mts";
+export { KibanaDashboardEmbedPlugin, kibanaDashboardEmbedPlugin, createKibanaDashboardEmbedPlugin, buildKibanaEmbedUrl, KIBANA_DEFAULT_BASE_PATH, } from "./installer.d.mts";
+export { sendKibanaSwitchDashboardMessage, } from "./host.d.mts";

package/lib/types/plugins/kibana/installer.d.cts

@@ -0,0 +1,45 @@
+import { type DashboardEmbedPlugin, type DashboardEmbedPluginDescriptor, type EmbedUrlOptions, type PluginInstallOptions, type PluginInstallResult, type SwitchDashboardPayload, type SwitchDashboardMessage, type EmbedMessageTarget } from "../contract.d.cts";
+/** Default Kibana base path when none is provided. */
+export declare const KIBANA_DEFAULT_BASE_PATH = "kibana";
+/**
+ * Build the stable Kibana embed iframe URL.
+ *
+ * @example
+ *   buildKibanaEmbedUrl({ host: "ptp.host", dashboardId: "abc", parentOrigin: "https://app.example.com" })
+ *   // => "//ptp.host/kibana/app/org_dashboard_embed?dashboardId=abc&parentOrigin=https%3A%2F%2Fapp.example.com"
+ */
+export declare function buildKibanaEmbedUrl(options: EmbedUrlOptions): string;
+/**
+ * @class KibanaDashboardEmbedPlugin
+ * @summary Kibana implementation of the `DashboardEmbedPlugin` contract.
+ * @description Org-agnostic multi-tenant dashboard embed plugin for Kibana.
+ */
+export declare class KibanaDashboardEmbedPlugin implements DashboardEmbedPlugin {
+    readonly descriptor: DashboardEmbedPluginDescriptor;
+    constructor(targetVersion?: string);
+    manifest(targetVersion?: string): Record<string, unknown>;
+    buildEmbedUrl(options: EmbedUrlOptions): string;
+    createSwitchDashboardMessage(payload: SwitchDashboardPayload): SwitchDashboardMessage;
+    sendSwitchDashboardMessage(target: EmbedMessageTarget, payload: SwitchDashboardPayload, targetOrigin: string): void;
+    /**
+     * Materialize the generated Kibana plugin into `targetPath/org_dashboard_embed/`.
+     *
+     * Kibana plugins must be built within the Kibana repo against the exact
+     * Kibana version. When `build` is true, this attempts `yarn build` in the
+     * plugin directory (best-effort); real builds require the Kibana plugin
+     * helpers environment.
+     */
+    install(options: PluginInstallOptions): Promise<PluginInstallResult>;
+    /**
+     * Best-effort `yarn build` in the plugin directory. Real builds require the
+     * Kibana plugin helpers environment; failures are captured, not thrown.
+     */
+    protected runBuild(pluginDir: string): Promise<{
+        ok: boolean;
+        output: string;
+    }>;
+}
+/** Default singleton instance. */
+export declare const kibanaDashboardEmbedPlugin: KibanaDashboardEmbedPlugin;
+/** Factory accepting a target Kibana version. */
+export declare function createKibanaDashboardEmbedPlugin(targetVersion: string): KibanaDashboardEmbedPlugin;

package/lib/types/plugins/kibana/installer.d.mts

@@ -0,0 +1,45 @@
+import { type DashboardEmbedPlugin, type DashboardEmbedPluginDescriptor, type EmbedUrlOptions, type PluginInstallOptions, type PluginInstallResult, type SwitchDashboardPayload, type SwitchDashboardMessage, type EmbedMessageTarget } from "../contract.d.mts";
+/** Default Kibana base path when none is provided. */
+export declare const KIBANA_DEFAULT_BASE_PATH = "kibana";
+/**
+ * Build the stable Kibana embed iframe URL.
+ *
+ * @example
+ *   buildKibanaEmbedUrl({ host: "ptp.host", dashboardId: "abc", parentOrigin: "https://app.example.com" })
+ *   // => "//ptp.host/kibana/app/org_dashboard_embed?dashboardId=abc&parentOrigin=https%3A%2F%2Fapp.example.com"
+ */
+export declare function buildKibanaEmbedUrl(options: EmbedUrlOptions): string;
+/**
+ * @class KibanaDashboardEmbedPlugin
+ * @summary Kibana implementation of the `DashboardEmbedPlugin` contract.
+ * @description Org-agnostic multi-tenant dashboard embed plugin for Kibana.
+ */
+export declare class KibanaDashboardEmbedPlugin implements DashboardEmbedPlugin {
+    readonly descriptor: DashboardEmbedPluginDescriptor;
+    constructor(targetVersion?: string);
+    manifest(targetVersion?: string): Record<string, unknown>;
+    buildEmbedUrl(options: EmbedUrlOptions): string;
+    createSwitchDashboardMessage(payload: SwitchDashboardPayload): SwitchDashboardMessage;
+    sendSwitchDashboardMessage(target: EmbedMessageTarget, payload: SwitchDashboardPayload, targetOrigin: string): void;
+    /**
+     * Materialize the generated Kibana plugin into `targetPath/org_dashboard_embed/`.
+     *
+     * Kibana plugins must be built within the Kibana repo against the exact
+     * Kibana version. When `build` is true, this attempts `yarn build` in the
+     * plugin directory (best-effort); real builds require the Kibana plugin
+     * helpers environment.
+     */
+    install(options: PluginInstallOptions): Promise<PluginInstallResult>;
+    /**
+     * Best-effort `yarn build` in the plugin directory. Real builds require the
+     * Kibana plugin helpers environment; failures are captured, not thrown.
+     */
+    protected runBuild(pluginDir: string): Promise<{
+        ok: boolean;
+        output: string;
+    }>;
+}
+/** Default singleton instance. */
+export declare const kibanaDashboardEmbedPlugin: KibanaDashboardEmbedPlugin;
+/** Factory accepting a target Kibana version. */
+export declare function createKibanaDashboardEmbedPlugin(targetVersion: string): KibanaDashboardEmbedPlugin;

package/lib/types/plugins/kibana/manifest.d.cts

@@ -0,0 +1,31 @@
+/**
+ * @module integrations/plugins/kibana/manifest
+ * @summary Kibana embed plugin manifest builder.
+ * @description Builds the `kibana.json` manifest for the org-agnostic
+ * `orgDashboardEmbed` plugin against a target Kibana version.
+ */
+import { EMBED_MESSAGE_TYPE } from "../contract.d.cts";
+export declare const KIBANA_PLUGIN_ID = "orgDashboardEmbed";
+export declare const KIBANA_APP_ID = "org_dashboard_embed";
+export declare const KIBANA_PLUGIN_VERSION = "1.0.0";
+export interface KibanaManifest {
+    id: string;
+    version: string;
+    kibanaVersion: string;
+    server: boolean;
+    ui: boolean;
+    requiredPlugins: string[];
+    optionalPlugins: string[];
+    requiredBundles?: string[];
+}
+/**
+ * Build the `kibana.json` manifest for a target Kibana version.
+ *
+ * @param targetVersion - Kibana version (defaults to "kibana").
+ */
+export declare function buildKibanaManifest(targetVersion?: string): KibanaManifest;
+/**
+ * Message type constants re-exported so the generated plugin templates can
+ * reference the same protocol identifiers as the host helpers.
+ */
+export { EMBED_MESSAGE_TYPE };

package/lib/types/plugins/kibana/manifest.d.mts

@@ -0,0 +1,31 @@
+/**
+ * @module integrations/plugins/kibana/manifest
+ * @summary Kibana embed plugin manifest builder.
+ * @description Builds the `kibana.json` manifest for the org-agnostic
+ * `orgDashboardEmbed` plugin against a target Kibana version.
+ */
+import { EMBED_MESSAGE_TYPE } from "../contract.d.mts";
+export declare const KIBANA_PLUGIN_ID = "orgDashboardEmbed";
+export declare const KIBANA_APP_ID = "org_dashboard_embed";
+export declare const KIBANA_PLUGIN_VERSION = "1.0.0";
+export interface KibanaManifest {
+    id: string;
+    version: string;
+    kibanaVersion: string;
+    server: boolean;
+    ui: boolean;
+    requiredPlugins: string[];
+    optionalPlugins: string[];
+    requiredBundles?: string[];
+}
+/**
+ * Build the `kibana.json` manifest for a target Kibana version.
+ *
+ * @param targetVersion - Kibana version (defaults to "kibana").
+ */
+export declare function buildKibanaManifest(targetVersion?: string): KibanaManifest;
+/**
+ * Message type constants re-exported so the generated plugin templates can
+ * reference the same protocol identifiers as the host helpers.
+ */
+export { EMBED_MESSAGE_TYPE };

package/lib/types/plugins/kibana/templates.d.cts

@@ -0,0 +1,12 @@
+export interface KibanaPluginFile {
+    /** Relative path within the plugin directory. */
+    path: string;
+    /** File contents. */
+    content: string;
+}
+/**
+ * Returns the full set of generated plugin files for a target Kibana version.
+ *
+ * @param targetVersion - Kibana version baked into `kibana.json`.
+ */
+export declare function kibanaPluginFiles(targetVersion: string): KibanaPluginFile[];

package/lib/types/plugins/kibana/templates.d.mts

@@ -0,0 +1,12 @@
+export interface KibanaPluginFile {
+    /** Relative path within the plugin directory. */
+    path: string;
+    /** File contents. */
+    content: string;
+}
+/**
+ * Returns the full set of generated plugin files for a target Kibana version.
+ *
+ * @param targetVersion - Kibana version baked into `kibana.json`.
+ */
+export declare function kibanaPluginFiles(targetVersion: string): KibanaPluginFile[];

package/lib/types/plugins/kibana/types.d.cts

@@ -0,0 +1,9 @@
+/**
+ * @module integrations/plugins/kibana/types
+ * @summary Kibana embed plugin types.
+ * @description Re-exports the shared contract types and exposes Kibana-specific
+ * constants/types for the org-agnostic dashboard embed plugin.
+ */
+export * from "../contract.d.cts";
+export { KIBANA_PLUGIN_ID, KIBANA_APP_ID, KIBANA_PLUGIN_VERSION, buildKibanaManifest, type KibanaManifest, } from "./manifest.d.cts";
+export { kibanaPluginFiles, type KibanaPluginFile } from "./templates.d.cts";

package/lib/types/plugins/kibana/types.d.mts

@@ -0,0 +1,9 @@
+/**
+ * @module integrations/plugins/kibana/types
+ * @summary Kibana embed plugin types.
+ * @description Re-exports the shared contract types and exposes Kibana-specific
+ * constants/types for the org-agnostic dashboard embed plugin.
+ */
+export * from "../contract.d.mts";
+export { KIBANA_PLUGIN_ID, KIBANA_APP_ID, KIBANA_PLUGIN_VERSION, buildKibanaManifest, type KibanaManifest, } from "./manifest.d.mts";
+export { kibanaPluginFiles, type KibanaPluginFile } from "./templates.d.mts";