@crowdstrike/logscale-dashboard 1.126.0--build-684--sha-1de8e2885c1117489d131c478ebf5a572b6881cf

package/index.d.ts

@@ -0,0 +1,553 @@
+/**
+ * @crowdstrike/logscale-dashboard
+ *
+ * This packages allows you to embed a LogScale Dashboard as a WebComponent.
+ *
+ * ```ts
+ * // Importing the module defines the "logscale-dashboard" custom element as a side-effect.
+ * import * as LogScaleDashboard from "@crowdstrike/logscale-dashboard";
+ *
+ * // See documentation for `createElement`
+ * const element : LogScaleDashboard.Dashboard = LogScaleDashboard.createElement(options);
+ * document.body.appendChild(element);
+ * ```
+ *
+ * @packageDocumentation
+ */
+
+/** Common options shared by all LogScale Webcomponents
+ * @public
+ */
+export declare interface CommonOptions {
+    /** The current unix time as millisecs. Defaults to `Date.now` if not set. */
+    currentTime?: number;
+    /** Allows you to open the webcomponent's internal shadow DOM.
+     *
+     * This is useful for writing E2E tests where you want to inspect the internal DOM of the WebComponent.
+     * Do this sparingly, since the internal DOM elements can change between releases of
+     * the webcomponents.
+     */
+    shadowRootMode?: "open" | "closed";
+    /** Names of experimental features to be enabled. The names of features are provided by LogScale on a case-by-case basis.
+     * Should be left empty or undefined by default.
+     */
+    featureFlags?: Array<string> | Record<string, boolean>;
+}
+
+/**
+ * The primary way of embedding a Dashboard.
+ * This function that creates a `logscale-dashboard` webcomponent and initializes it with the provided options.
+ *
+ * ```ts
+ * const options : Options = {
+ *   apiURL: "https://...",
+ *   theme: "dark",
+ *   repoOrViewName: "my-repo",
+ *   dashboard: { name: "my-dashboard" },
+ *   // ...
+ * };
+ *
+ * const element : Dashboard = createElement(options);
+ * ```
+ *
+ * ## Callbacks
+ * Methods for registering callbacks for events happening within a LogScale Dashboard are exposed on the Dashboard class.
+ *
+ * ```ts
+ * element.onDashboardStateChanged((dashboardState: DashboardNavigationTargetInfo) => {
+ *   console.log("dashboard state changed: ", dashboardState);
+ * });
+ * ```
+ * ## Updating the Dashboard
+ * A Dashboard can be updated after initialization through methods on the Dashboard class.
+ *
+ * ```ts
+ * // update parameter args and apply immediately, executing all dependent queries
+ * element.setParameterValues({method: 'POST'}, {apply: true});
+ * ```
+ *
+ * @public
+ */
+export declare function createElement(options: Options): Dashboard;
+
+/**
+ * Custom Link interaction type.
+ *
+ * @public
+ */
+export declare type CustomLinkInteraction = {
+    type: "customLink";
+    urlTemplate: string;
+    openInNewTab?: boolean;
+    urlEncodeArgs?: boolean;
+} & SharedInteractionProperties;
+
+/**
+ * A NavigationTarget for LogScale Dashboard.
+ *
+ * @public
+ */
+export declare type DashbboardNavigationTarget = {
+    type: "dashboard";
+    targetInfo: DashboardNavigationTargetInfo;
+};
+
+/**
+ * Custom element that embeds the LogScale Dashboard.
+ *
+ * @public
+ */
+export declare class Dashboard extends WebcomponentBase<Options> {
+    /**
+     * Set parameter values on dashboard.
+     *
+     * @param parameterValues
+     * @param options - used to specify behaviour when setting parameters, i.e. if they should be applied immediately.
+     *
+     * @public
+     */
+    setParameterValues(parameterValues: ParameterValues, options?: SetParametersOptions): void;
+    /**
+     * Implement this hook to receive notifications about changes to the state of the Dashboard.
+     *
+     * Use this if you e.g. want to serialize / keep local state of Dashboard.
+     * @param callback
+     *
+     * @public
+     */
+    onDashboardStateChanged(callback: (dashboardState: DashboardNavigationTargetInfo) => void | null): void;
+}
+
+/**
+ * Used to prefix queries on a LogScale Dashboard.
+ *
+ * @public
+ */
+export declare type DashboardFilter = string | {
+    /** Id of an existing filter on the dashboard. */
+    id: string;
+};
+
+/**
+ * Dashboard Link interaction type.
+ * If `onNavigationTargetChange` hook is implemented, these interactions will
+ * trigger a navigation target change, triggering the `onNavigationTargetChange` hook
+ * passing a `DashboardNavigationTarget` as the argument.
+ *
+ * @public
+ */
+export declare type DashboardLinkInteraction = {
+    type: "dashboardLink";
+    dashboardName: string;
+    package?: string;
+    dashboardRepo?: string;
+    dashboardId?: string;
+    arguments?: Record<string, string> | null;
+    openInNewTab?: boolean;
+    useWidgetTimeWindow?: boolean;
+} & SharedInteractionProperties;
+
+/**
+ * The Dashboard state as set by the source of the NavigationTarget.
+ * This can be used to load a LogScale Dashboard in a specific state.
+ *
+ * @public
+ */
+export declare type DashboardNavigationTargetInfo = DashboardParams & {
+    repoOrViewName: string;
+    timezone?: string;
+};
+
+/**
+ * Configuration of LogScale Dashboard.
+ * This also overlaps with `DashboardNavigationTarget.targetInfo`.
+ * This means that `DashboardParams` can be created from the targetInfo of a `DashboardNavigationTarget`.
+ *
+ * @public
+ */
+export declare interface DashboardParams {
+    /**
+     * A reference to a dashboard.
+     */
+    dashboard: DashboardReference;
+    /** A map of arguments for dashboard parameters */
+    parameterArgs?: ParameterValues;
+    /**
+     * Optional filter which will prefix all dashboard queries.
+     */
+    filter?: DashboardFilter;
+    /**
+     * Start time used for dashboard queries.
+     * Note: this will only be used when querying if `sharedTime` is set to `true`.
+     */
+    start?: string;
+    /**
+     * End time used for dashboard queries.
+     * Note: this will only be used when querying if `sharedTime` is set to `true`.
+     */
+    end?: string;
+    /** Set to true to make the dashboard `live`. Defaults to `false` */
+    isLive?: boolean;
+    /**
+     * Set to `true` to make all dashboard queries use `start` and `end` as time window.
+     */
+    sharedTime?: boolean;
+}
+
+/**
+ * A reference to a LogScale Dashboard.
+ *
+ * @public
+ */
+export declare type DashboardReference = {
+    name: string;
+    /**
+     * Package containing the dashboard. E.g. "my-org/dashboards".
+     * If omitted the dashboard will be found in dashboards that have no package.
+     */
+    package?: string;
+} | {
+    id: string;
+};
+
+/**
+ * Search view Edit state.
+ * Use this when you need to load / put a LogScale Search view in an edit state to allow editing of LogScale assets
+ * from the Search view.
+ *
+ * @public
+ */
+export declare type EditState = {
+    savedQueryId: string;
+} | {
+    dashboardId: string;
+    widgetId?: string;
+} | {
+    alertId: string;
+} | {
+    filterAlertId: string;
+} | {
+    scheduledSearchId: string;
+};
+
+/**
+ * LogScale Interactions.
+ * See [documentation](https://library.humio.com/data-analysis/dashboards-interactions.html) for more information.
+ *
+ * @public
+ */
+export declare type Interaction = CustomLinkInteraction | SearchLinkInteraction | DashboardLinkInteraction | UpdateParametersInteraction;
+
+/**
+ * Configure conditions to control when an interaction should be available.
+ *
+ * @public
+ */
+export declare type InteractionCondition = {
+    "operator": "present" | "not-present";
+    "fieldName": string;
+} | {
+    "operator": "starts-with" | "ends-with" | "equal" | "not-equal" | "contains" | "not-contains";
+    "fieldName": string;
+    "argument": string;
+};
+
+/**
+ * The NavigationTarget type specifies the target of a LogScale navigation event.
+ * These are handled by the `onNavigationTargetChange` hook. Sources of Navigation targets are:
+ * - Internal LogScale links
+ * - LogScale Interactions
+ *
+ * @public
+ */
+export declare type NavigationTarget = SearchNavigationTarget | DashbboardNavigationTarget;
+
+/**
+ * Initialization options.
+ *
+ * @public
+ */
+export declare interface Options extends CommonOptions, DashboardParams {
+    /** Base URL where the LogScale cluster is accessed. */
+    apiURL: string;
+    /** Name of LogScale repository or view */
+    repoOrViewName: string;
+    /** If the LSP websocket server is accessed from a different URL than the `apiUrl`, you can set this. */
+    lspURL?: string;
+    /** If provided, this token will be passed in the Authentication header as a Bearer token.
+     * This can be a user's personal API token or an OICD token.
+     *
+     * This method of setting the authentication token is not recommended, since it exposes the authorization token to be read from JavaScript.
+     * Consider using a secure HTTP-only cookie instead.
+     */
+    authToken?: string;
+    /** If provided, HTTP calls will have the "X-CSRF-Token" header set to this value. */
+    csrfToken?: string;
+    /** Will initialize the webcomponent in light or dark mode. The theme can be switched through the `setTheme()` method after initialization. */
+    theme: 'light' | 'dark';
+    /** Language to start the webcomponent in. */
+    locale?: "jp" | "en";
+    /** Advanced feature: Set the language version to be used. This depends on the backend configuration and might crash if set inappropriately. */
+    languageVersion?: string;
+    /**
+     * Set a custom date time format to be used when formatting timestamps in Event list and Table widgets.
+     * See [documentation](https://library.humio.com/data-analysis/functions-formattime.html#query-function-formattime-formattime-format)
+     * to get more information.
+     *
+     * Defaults to `"%F %T.%L"`
+     */
+    dateTimeFormat?: string;
+    /**
+     * Set this to enable automatic links for showing events for groupBy fields.
+     * Default to `false`.
+     */
+    enableGroupEventInteractionInTable?: boolean;
+    /** Set a custom time zone. */
+    timezone?: TimeZone;
+    /**
+     * Set LogScale interactions to be available on widgets.
+     * See [interactions documentation](https://library.humio.com/data-analysis/dashboards-interactions.html) for more information.
+     *
+     * Note: `hostInteractions` can only be configured through the host application and will not be configurable through the
+     * interactions panel inside LogScale.
+     */
+    hostInteractions?: Array<Interaction>;
+    /**
+     * Hook for handling LogScale navigation targets, e.g. navigating from SearchView to Dashboard or vice versa.
+     *
+     * ### IMPORTANT
+     * #### If ommitted
+     * This component instance will essentially work in isolation. This means that:
+     * - Internal LogScale links to other views will not work.
+     * - Interactions with a target to another view type will be excluded.
+     *
+     * @param navigationTarget
+     */
+    onNavigationTargetChange?: (navigationTarget: NavigationTarget) => void;
+    /**
+     * Optional flag to show title bar on dashboards.
+     * Defaults to `false`.
+     * Note: this is necessary to allow editing of dashboards.
+     */
+    showTitleBar?: boolean;
+}
+
+/**
+ * A value for a visualization configuration option.
+ *
+ * @public
+ */
+export declare type OptionValue = string | number | boolean | Array<OptionValue> | OptionValues;
+
+/**
+ * Options for visualization configuration.
+ *
+ * @public
+ */
+export declare type OptionValues = {
+    [key: string]: OptionValue;
+};
+
+/**
+ * LogScale parameter values is a map with parameter ids as keys,
+ * and either a string or a string array as single / multi value parameter args, respectively.
+ *
+ * @public
+ */
+export declare type ParameterValues = Record<string, string | string[]>;
+
+/**
+ * LogScale query.
+ *
+ * @public
+ */
+export declare type Query = {
+    queryString: string;
+    /** Arguments for parameters in `query`. */
+    arguments?: {
+        [key: string]: string;
+    };
+    start: string;
+    end?: string;
+    isLive: boolean;
+    around?: QueryPaginationOptions;
+};
+
+/**
+ * Options to specify what events to include in a result for a query around an event.
+ *
+ * @public
+ */
+export declare type QueryPaginationOptions = {
+    /** The id of the event to center query around. */
+    eventId: String;
+    /** Needs to match the @timestamp field value for the event matching `eventId`. */
+    timestamp: number;
+    /** The amound of events to query for before the event matching `eventId` */
+    numberOfEventsBefore: number;
+    /** The amound of events to query for after the event matching `eventId` */
+    numberOfEventsAfter: number;
+};
+
+/**
+ * Search Link interaction type.
+ * If `onNavigationTargetChange` hook is implemented, these interactions will
+ * trigger a navigation target change, triggering the `onNavigationTargetChange` hook
+ * passing a `SearchNavigationTarget` as the argument.
+ *
+ * @public
+ */
+export declare type SearchLinkInteraction = {
+    type: "searchLink";
+    queryString: string;
+    repoOrViewName?: string | null;
+    arguments?: Record<string, string> | null;
+    openInNewTab?: boolean;
+    useWidgetTimeWindow?: boolean;
+} & SharedInteractionProperties;
+
+/**
+ * A NavigationTarget for LogScale Search view.
+ *
+ * @public
+ */
+export declare type SearchNavigationTarget = {
+    type: "search";
+    targetInfo: SearchNavigationTargetInfo;
+};
+
+/**
+ * The Search state as set by the source of the NavigationTarget.
+ * This can be used to load a LogScale Search view in a specific state.
+ *
+ * @public
+ */
+export declare type SearchNavigationTargetInfo = SearchViewParams & {
+    repoOrViewName: string;
+    timezone?: string;
+};
+
+/**
+ * Configuration of LogScale Search view.
+ * This also overlaps with `SearchNavigationTarget.targetInfo`.
+ * This means that `SearchViewParams` can be created from the targetInfo of a `SearchNavigationTarget`.
+ *
+ * @public
+ */
+export declare interface SearchViewParams {
+    /** The query string set in the query editor. */
+    query?: string;
+    /** Start of time window used when querying. */
+    start?: string;
+    /** End of time window used when querying. */
+    end?: string;
+    /** Query for events around a certain event. */
+    around?: QueryPaginationOptions;
+    /** Set to `true` to execute query as live. Defaults to `false`. */
+    live?: boolean;
+    /**
+     * Set the visualisation to be used when visulising query result.
+     * If omitted a visualisation fitting the data in the query result will be used automatically.
+     */
+    visualization?: SearchViewVisualization;
+    /**
+     * Set LogScale interactions to be available on widgets.
+     * See [interactions documentation](https://library.humio.com/data-analysis/dashboards-interactions.html) for more information.
+     *
+     * Note: `dynamicInteractions` can be changed through the interaction panel inside LogScale, if enabled.
+     */
+    dynamicInteractions?: Array<Interaction>;
+    /**
+     * Set the Search view in an edit state, allowing editation of certain LogScale assets.
+     * This is primarily useful in conjunction with `NavigationTarget`, allowing a `NavigationTarget` to set an editState
+     * from a previous context.
+     */
+    editState?: EditState;
+    /** Arguments for parameters in `query`. */
+    parameterArgs?: {
+        [key: string]: string;
+    };
+}
+
+/**
+ * A LogScale widget with configuration.
+ *
+ * @public */
+export declare type SearchViewVisualization = {
+    type?: WidgetType;
+    /** The configuration options of a LogScale visualization. */
+    options?: OptionValues;
+};
+
+/**
+ * Options to use when setting parameter args.
+ *
+ * @public
+ */
+export declare type SetParametersOptions = {
+    /** Used to control whether parameters should be applied immediately. */
+    apply?: boolean;
+};
+
+/**
+ * The shared properties of all interaction types.
+ *
+ * @public
+ */
+export declare type SharedInteractionProperties = {
+    name: string;
+    titleTemplate?: string | null;
+    conditions?: Array<InteractionCondition> | null;
+};
+
+/**
+ * `name` should be a timezone name in the format `<Continent>/<City>` (Ex: `Asia/Tokyo`).
+ * For timezones that are not relative to a continent, the first part is `Etc` (Ex: `Etc/GMT-3`).
+ *
+ * If the `name` is unknown to the component, then the `fallback` timezone is chosen.
+ *
+ * @public
+ */
+export declare type TimeZone = {
+    name: string;
+    fallback: "GMT+0" | "GMT+1" | "GMT+2" | "GMT+3" | "GMT+4" | "GMT+5" | "GMT+6" | "GMT+7" | "GMT+8" | "GMT+9" | "GMT+10" | "GMT+11" | "GMT+12" | "GMT-1" | "GMT-2" | "GMT-3" | "GMT-4" | "GMT-5" | "GMT-6" | "GMT-7" | "GMT-8" | "GMT-9" | "GMT-10" | "GMT-11" | "GMT-12" | "GMT-13" | "GMT-14";
+};
+
+/**
+ * Update Parameters interaction type.
+ * If `onNavigationTargetChange` hook is implemented, these interactions will
+ * trigger a navigation target change, triggering the `onNavigationTargetChange` hook
+ * passing a `NavigationTarget` matching the LogScale component type as the argument,
+ * i.e. a `SearchNavigationTarget` when in Search view and a `DashboardNavigationTarget` when in Dashboard.
+ *
+ * @public
+ */
+export declare type UpdateParametersInteraction = {
+    type: "updateParameters";
+    arguments?: Record<string, string> | null;
+    useWidgetTimeWindow?: boolean;
+} & SharedInteractionProperties;
+
+/** Base class for LogScale's webcomponents.
+ * @public */
+export declare abstract class WebcomponentBase<Opts extends CommonOptions> extends HTMLElement {
+    /** Initializes the webcomponent with options.
+     *
+     * This should be called only once per webcomponent.
+     * You should not need to call this if you are using the `createElement` helper function.
+     * @public
+     */
+    init(options: Opts): void;
+    /** Set the UI theme to dark or light.
+     * @public */
+    setTheme(theme: "dark" | "light"): void;
+}
+
+/**
+ * LogScale widget types
+ *
+ * @public
+ */
+export declare type WidgetType = "list-view" | "table-view" | "time-chart" | "pie-chart" | "bar-chart" | "scatter-chart" | "raw" | "world-map" | "sankey" | "heat-map" | "single-value" | "gauge";
+
+export { }