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

package/index.d.ts

@@ -0,0 +1,675 @@
+/**
+ * @crowdstrike/logscale-search
+ *
+ * This packages allows you to embed a LogScale Search View as a WebComponent.
+ *
+ * ```ts
+ * // Importing the module defines the "logscale-search-view" custom element as a side-effect.
+ * import * as LogScaleSearchView from "@crowdstrike/logscale-search";
+ *
+ * // See documentation for `createElement`
+ * const element : LogScaleSearchView.SearchView = LogScaleSearchView.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 Search View.
+ * This function that creates a `logscale-search` webcomponent and initializes it with the provided options.
+ *
+ * ```ts
+ * const options : Options = {
+ *   apiURL: "https://...",
+ *   theme: "dark",
+ *   repoOrViewName: "my-repo",
+ *   // ...
+ * };
+ *
+ * const element : SearchView = createElement(options);
+ * ```
+ *
+ * ## Callbacks
+ * Methods for registering callbacks for events happening within a LogScale SearchView are exposed on the SearchView class.
+ *
+ * ```ts
+ * element.onQueryChanged((query: Query) => {
+ *   console.log("query changed: ", query);
+ * });
+ * ```
+ *
+ * ## Updating the SearchView
+ * SearchView can be updated after initialization through methods on the SearchView class.
+ *
+ * ```ts
+ * // update the query string and run the query immediately
+ * element.setQueryString("groupBy(method)", {run: true});
+ * ```
+ *
+ * @public
+ */
+export declare function createElement(options: Options): SearchView;
+
+/**
+ * A column type for inserting links from based on row values.
+ *
+ * @public
+ */
+export declare type CustomLinkColumn = {
+    type: "link";
+    width?: number;
+    header: string;
+    /**
+     * The template describing how to create a href.
+     *
+     * See https://library.humio.com/data-analysis/template-language-expressions.html for information
+     * on how to use the LogScale Template Language
+     */
+    hrefTemplate: string;
+    /**
+     * The template describing how to create the text to be displayed inside the cell.
+     * Defaults to the value of `hrefTemplate`.
+     *
+     * See https://library.humio.com/data-analysis/template-language-expressions.html for information
+     * on how to use the LogScale Template Language
+     */
+    textTemplate?: string;
+    openInNewBrowserTab: boolean;
+    /**
+     * Specify whether to display as a button or a link.
+     */
+    style: "button" | "link";
+};
+
+/**
+ * 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;
+};
+
+/**
+ * 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;
+};
+
+/**
+ * Column defintions for the Event List widget.
+ *
+ * @public */
+export declare type EventListColumn = FieldColumn | CustomLinkColumn | FieldListColumn;
+
+/**
+ * A column type displaying field values as is.
+ *
+ * @public
+ */
+export declare type FieldColumn = {
+    type: "field";
+    width?: number | "content";
+    /** The field for which the column should display values. */
+    fieldName: string;
+    /** Set a custom header for the column. Defaults to the value of `fieldName`. */
+    header?: string;
+};
+
+/**
+ * A column type for displaying all field values.
+ *
+ * @public
+ */
+export declare type FieldListColumn = {
+    type: "fieldList";
+    width?: number;
+    header: string;
+    /** group options with the same prefix together, e.g. user.firstName and user.lastName */
+    groupByPrefix?: boolean;
+};
+
+/**
+ * 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, SearchViewParams {
+    /** Base URL where the LogScale cluster is accessed. */
+    apiURL: string;
+    /** Name of LogScale repository or view */
+    repoOrViewName: string;
+    /** Will initialize the webcomponent in light or dark mode. The theme can be switched through the `setTheme()` method after initialization. */
+    theme: 'light' | 'dark';
+    /** 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;
+    /** 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;
+    /**
+     * List of LogScale repositories and views available for selection in the repository or view selector.
+     */
+    reposAndViews?: RepoOrViewOption[];
+    /**
+     * The default columns that will be shown in the Event List.
+     * Defaults to
+     * ```
+     * [
+     *  { type: "field", fieldName: "@timestamp" },
+     *  { type: "field", fieldName: "@rawstring" },
+     * ]
+     * ```
+     */
+    columns?: Array<EventListColumn>;
+    /**
+     * Control if the fields panel should be open by default.
+     * Defaults to `true`.
+     */
+    canOpenFieldsPanelOnStart?: boolean;
+    /**
+     * Optional flag to show "Dashboard widget" save option in Search view.
+     * Defaults to `false`
+     */
+    showDashboardWidgetSaveOption?: boolean;
+    /**
+     * Optional flag to enable interactions panel in Search view.
+     * This is required to be able to configure `dynamicInteractions` inside LogScale.
+     * Defaults to `false`.
+     */
+    showInteractionsPanel?: 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;
+};
+
+/**
+ * A repository or view option for the LogScale Search view Repository or View selector.
+ *
+ * @public */
+export declare type RepoOrViewOption = {
+    name: string;
+    label: string;
+    type: "repo" | "view";
+};
+
+/**
+ * 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;
+};
+
+/**
+ * Custom element that embeds the LogScale Search view.
+ *
+ * @public
+ */
+export declare class SearchView extends WebcomponentBase<Options> {
+    /**
+     * Set the query string of the SearchView query editor.
+     *
+     * @param queryString - the query string to set.
+     * @param options - optional options to pass when setting the query string to allow to execute query immediately.
+     *
+     * @public
+     */
+    setQueryString(queryString: string, options?: SetQueryStringOptions): void;
+    /**
+     * Implement this hook to receive notifications on changes to the query.
+     *
+     * @param callback - function for handling notifications of query changes.
+     *
+     * @public
+     */
+    onQueryChange(callback: (query: Query) => void | null): void;
+    /**
+     * Implement this hook to receive notifications on query submissions.
+     *
+     * @param callback - function for handling notifications of query submissions.
+     *
+     * @public
+     */
+    onQuerySubmit(callback: (query: Query) => void | null): void;
+    /**
+     * Implement this hook to receive notifications on query results.
+     *
+     * @param callback - function for handling notifications of query results.
+     *
+     * @public
+     */
+    onQueryResult(callback: (filter?: string) => void | null): void;
+    /**
+     * Implement this hook to receive notifications about changes to the state of the Search view.
+     *
+     * Use this if you e.g. want to serialize / keep local state of SearchView.
+     * @param callback - function for handling notifications of changes to Search view state.
+     *
+     * @public
+     */
+    onSearchViewStateChanged(callback: (searchViewState: SearchNavigationTargetInfo) => void | null): void;
+}
+
+/**
+ * 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 query string.
+ *
+ * @public
+ */
+export declare type SetQueryStringOptions = {
+    run?: 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 { }