@decaf-ts/integrations 0.4.0 → 0.4.1-0

package/lib/types/nest/keycloakAuthHandler.d.mts

@@ -1,30 +1,9 @@
-/**
- * @module integrations/nest/keycloakAuthHandler
- * @summary Keycloak request auth handler.
- * @description Translates Keycloak JWT payloads into Decaf-friendly auth data.
- * Extends the framework-agnostic {@link AuthHandler} from `@decaf-ts/for-http/server`.
- *
- * Only overrides the two extension points:
- * - {@link KeycloakAuthHandler.extractFromAuth} — decodes the JWT and returns auth data (no validation).
- *   Returns empty data for public routes without requiring a token.
- * - {@link KeycloakAuthHandler.validate} — validates the JWT via {@link AuthService.assertValidToken},
- *   then delegates to the base class for route-level and model-level role checks.
- *   Skips entirely for public routes.
- *
- * Does NOT override `bindToContext` — the base class default `ctx.accumulate(data)`
- * is sufficient. Does NOT override `authorize`.
- */
-import type { Constructor } from "@decaf-ts/decoration";
-import { Context, ContextualArgs } from "@decaf-ts/core";
 import { AuthHandler, AuthData } from "@decaf-ts/for-http/server";
-import { AuthService, type AuthServiceOptions } from "./authService.d.mts";
-import type { AuthExecutionContextLike } from "./types.d.mts";
-import { getClientRoles } from "./utils.d.mts";
+import type { Context } from "@decaf-ts/core";
+import { JwtService } from "@decaf-ts/crypto/integration/services/jwt";
+import type { AuthExecutionContextLike, AuthRequestLike } from "./types.d.mts";
 /**
- * Auth data returned by {@link KeycloakAuthHandler.extractFromAuth}.
- *
- * Carries the raw JWT `token` so that {@link KeycloakAuthHandler.validate} can
- * validate it against the Keycloak instance (signature, expiry, revocation, etc.).
+ * Auth data returned by {@link KeycloakAuthHandler.extractFromRequest}.
  */
 export interface KeycloakAuthData extends AuthData {
     /** The raw JWT extracted from the request. Empty for public routes. */
@@ -33,21 +12,19 @@ export interface KeycloakAuthData extends AuthData {
     isPublic: boolean;
 }
 export declare class KeycloakAuthHandler extends AuthHandler<AuthExecutionContextLike, Context, KeycloakAuthData> {
-    /**
-     * @param authService  An {@link AuthService} configured with JWKS verification
-     *                     options.  When omitted a default decode-only service is
-     *                     used.
-     * @param authServiceOptions  Convenience: if `authService` is omitted, these
-     *                     options are used to construct one.
-     */
-    constructor(authService?: AuthService, authServiceOptions?: AuthServiceOptions);
-    protected readonly authService: AuthService;
-    protected extractFromAuth(ctx: AuthExecutionContextLike): KeycloakAuthData;
-    /**
-     * Validates the JWT against the Keycloak instance (signature, expiry, etc.)
-     * via {@link AuthService.assertValidToken}, then delegates to the base class
-     * for route-level and model-level role checks. Skips entirely for public routes.
-     */
-    protected validate(data: KeycloakAuthData, routeRoles: string[] | undefined, model: string | Constructor, ...args: ContextualArgs<Context>): Promise<void>;
+    constructor();
+    protected readonly jwtService?: JwtService;
+    protected jwt(): JwtService;
+    protected requestFromContext(ctx: AuthExecutionContextLike): AuthRequestLike;
+    protected isPublicRequest(request: AuthRequestLike): boolean;
+    protected parseFromRequest(request: AuthRequestLike): KeycloakAuthData;
+    protected extractFromRequest(request: AuthRequestLike): KeycloakAuthData;
+    protected validateAuth(data: KeycloakAuthData, _request: AuthRequestLike): Promise<void>;
+}
+/**
+ * Keycloak handler variant that also extracts namespace scopes from the token.
+ */
+export declare class KeycloakNamespaceAuthHandler extends KeycloakAuthHandler {
+    protected parseFromRequest(request: AuthRequestLike): KeycloakAuthData;
 }
-export { getClientRoles };
+export { getClientRoles } from "./utils.d.mts";

package/lib/types/nest/keycloakModule.d.cts

@@ -1,15 +1,13 @@
 /**
  * @module integrations/nest/keycloakModule
  * @summary Nest module wiring for Keycloak auth.
- * @description Exposes the Nest module setup for the integration auth service and Keycloak handler.
+ * @description Exposes the Nest module setup for the Keycloak auth handlers.
  */
-import { AuthService, type AuthServiceOptions } from "./authService.d.cts";
 import { KeycloakAuthHandler } from "./keycloakAuthHandler.d.cts";
 export declare class KeycloakModule {
-    readonly authService: AuthService;
     readonly authHandler: KeycloakAuthHandler;
-    constructor(authService: AuthService, authHandler: KeycloakAuthHandler);
-    static create(options?: AuthServiceOptions): KeycloakModule;
+    constructor(authHandler: KeycloakAuthHandler);
+    static create(): KeycloakModule;
 }
 export declare class AuthModule extends KeycloakModule {
 }

package/lib/types/nest/keycloakModule.d.mts

@@ -1,15 +1,13 @@
 /**
  * @module integrations/nest/keycloakModule
  * @summary Nest module wiring for Keycloak auth.
- * @description Exposes the Nest module setup for the integration auth service and Keycloak handler.
+ * @description Exposes the Nest module setup for the Keycloak auth handlers.
  */
-import { AuthService, type AuthServiceOptions } from "./authService.d.mts";
 import { KeycloakAuthHandler } from "./keycloakAuthHandler.d.mts";
 export declare class KeycloakModule {
-    readonly authService: AuthService;
     readonly authHandler: KeycloakAuthHandler;
-    constructor(authService: AuthService, authHandler: KeycloakAuthHandler);
-    static create(options?: AuthServiceOptions): KeycloakModule;
+    constructor(authHandler: KeycloakAuthHandler);
+    static create(): KeycloakModule;
 }
 export declare class AuthModule extends KeycloakModule {
 }

package/lib/types/nest/types.d.cts

@@ -35,6 +35,8 @@ export interface KeycloakAccessTokenPayload {
     iss?: string;
     aud?: string;
     azp?: string;
+    namespace?: string | string[];
+    namespaces?: string[];
     realm_access?: {
         roles?: string[];
     };

package/lib/types/nest/types.d.mts

@@ -35,6 +35,8 @@ export interface KeycloakAccessTokenPayload {
     iss?: string;
     aud?: string;
     azp?: string;
+    namespace?: string | string[];
+    namespaces?: string[];
     realm_access?: {
         roles?: string[];
     };

package/lib/types/nest/utils.d.cts

@@ -3,10 +3,11 @@
  * @summary Nest integration utilities.
  * @description Helper functions used by the Nest auth and request-context adapters.
  */
-import type { KeycloakAccessTokenPayload, KeycloakUser } from "./types.d.cts";
+import type { KeycloakAccessTokenPayload } from "./types.d.cts";
 export declare const DECAF_ADAPTER_OPTIONS: unique symbol;
-export declare function getTokenPayload(jwt: string): KeycloakAccessTokenPayload | null;
 export declare function extractKeycloakRoles(payload: KeycloakAccessTokenPayload | null): string[];
+export declare function extractKeycloakNamespaces(payload: KeycloakAccessTokenPayload | null | undefined): string[];
+export declare function getRealmFromIssuer(jwt: string): string;
 /**
  * Extracts roles from the `resource_access` claim only, optionally excluding
  * specified client IDs (e.g. `"account"`).  Unlike {@link extractKeycloakRoles}
@@ -16,5 +17,3 @@ export declare function extractKeycloakRoles(payload: KeycloakAccessTokenPayload
  * @param excluded  Client IDs to skip.  @default ["account"]
  */
 export declare function getClientRoles(payload: KeycloakAccessTokenPayload | null, excluded?: string[]): string[];
-export declare function getUser(jwt: string): KeycloakUser | undefined;
-export declare function getRealmFromIssuer(jwt: string): string;

package/lib/types/nest/utils.d.mts

@@ -3,10 +3,11 @@
  * @summary Nest integration utilities.
  * @description Helper functions used by the Nest auth and request-context adapters.
  */
-import type { KeycloakAccessTokenPayload, KeycloakUser } from "./types.d.mts";
+import type { KeycloakAccessTokenPayload } from "./types.d.mts";
 export declare const DECAF_ADAPTER_OPTIONS: unique symbol;
-export declare function getTokenPayload(jwt: string): KeycloakAccessTokenPayload | null;
 export declare function extractKeycloakRoles(payload: KeycloakAccessTokenPayload | null): string[];
+export declare function extractKeycloakNamespaces(payload: KeycloakAccessTokenPayload | null | undefined): string[];
+export declare function getRealmFromIssuer(jwt: string): string;
 /**
  * Extracts roles from the `resource_access` claim only, optionally excluding
  * specified client IDs (e.g. `"account"`).  Unlike {@link extractKeycloakRoles}
@@ -16,5 +17,3 @@ export declare function extractKeycloakRoles(payload: KeycloakAccessTokenPayload
  * @param excluded  Client IDs to skip.  @default ["account"]
  */
 export declare function getClientRoles(payload: KeycloakAccessTokenPayload | null, excluded?: string[]): string[];
-export declare function getUser(jwt: string): KeycloakUser | undefined;
-export declare function getRealmFromIssuer(jwt: string): string;

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";