@backstage-community/plugin-cost-insights 0.12.24

package/dist/index.d.ts

@@ -0,0 +1,655 @@
+/// <reference types="react" />
+import * as React from 'react';
+import React__default, { ForwardRefExoticComponent, RefAttributes, ReactNode, PropsWithChildren, Dispatch, SetStateAction } from 'react';
+import * as _backstage_core_plugin_api from '@backstage/core-plugin-api';
+import * as common from '@backstage-community/plugin-cost-insights-common';
+import { Maybe as Maybe$1, ChangeStatistic as ChangeStatistic$1, Group as Group$1, Project as Project$1, Cost as Cost$1, MetricData as MetricData$1, Entity as Entity$1, Metric as Metric$1, Product as Product$1 } from '@backstage-community/plugin-cost-insights-common';
+import { TooltipProps } from 'recharts';
+import { TypographyProps } from '@material-ui/core/Typography';
+import { BackstagePalette, BackstageTheme } from '@backstage/theme';
+import { PaletteOptions } from '@material-ui/core/styles/createPalette';
+
+/** @public */
+declare const costInsightsPlugin: _backstage_core_plugin_api.BackstagePlugin<{
+    root: _backstage_core_plugin_api.RouteRef<undefined>;
+    growthAlerts: _backstage_core_plugin_api.RouteRef<undefined>;
+    unlabeledDataflowAlerts: _backstage_core_plugin_api.RouteRef<undefined>;
+}, {}, {}>;
+/** @public */
+declare const CostInsightsPage: () => React.JSX.Element;
+/**
+ * An extension for displaying costs on an entity page.
+ *
+ * @public
+ */
+declare const EntityCostInsightsContent: () => React.JSX.Element;
+/** @public */
+declare const CostInsightsProjectGrowthInstructionsPage: () => React.JSX.Element;
+/** @public */
+declare const CostInsightsLabelDataflowInstructionsPage: () => React.JSX.Element;
+
+/**
+ * Time periods for cost comparison; slight abuse of ISO 8601 periods. We take P3M to mean
+ * 'last completed quarter', and P30D/P90D to be '[month|quarter] relative to today'. So if
+ * it's September 15, P3M represents costs for Q2 and P30D represents August 16 -
+ * September 15.
+ *
+ * @public
+ */
+declare enum Duration {
+    P7D = "P7D",
+    P30D = "P30D",
+    P90D = "P90D",
+    P3M = "P3M"
+}
+
+/**
+ * Generic alert type with required fields for display. The `element` field will be rendered in
+ * the Cost Insights "Action Items" section. This should use data fetched in the CostInsightsApi
+ * implementation to render an InfoCard or other visualization.
+ *
+ * The alert type exposes hooks which can be used to enable and access various events,
+ * such as when a user dismisses or snoozes an alert. Default forms and buttons
+ * will be rendered if a hook is defined.
+ *
+ * Each default form can be overridden with a custom component. It must be implemented using
+ * React.forwardRef. See https://reactjs.org/docs/forwarding-refs
+ *
+ * Errors thrown within hooks will generate a snackbar error notification.
+ *
+ * @public
+ */
+type Alert = {
+    title: string | JSX.Element;
+    subtitle: string | JSX.Element;
+    element?: JSX.Element;
+    status?: AlertStatus;
+    url?: string;
+    buttonText?: string;
+    SnoozeForm?: Maybe$1<AlertForm>;
+    AcceptForm?: Maybe$1<AlertForm>;
+    DismissForm?: Maybe$1<AlertForm>;
+    onSnoozed?(options: AlertOptions): Promise<Alert[]>;
+    onAccepted?(options: AlertOptions): Promise<Alert[]>;
+    onDismissed?(options: AlertOptions): Promise<Alert[]>;
+};
+/** @public */
+type AlertForm<A extends Alert = any, Data = any> = ForwardRefExoticComponent<AlertFormProps<A, Data> & RefAttributes<HTMLFormElement>>;
+/** @public */
+interface AlertOptions<T = any> {
+    data: T;
+    group: string;
+}
+/**
+ * Default snooze form intervals are expressed using an ISO 8601 repeating interval string.
+ * For example, R1/P7D/2020-09-02 for 1 week or R1/P30D/2020-09-02 for 1 month.
+ *
+ * For example, if a user dismisses an alert on Monday January 01 for 1 week,
+ * it can be re-served on Monday, January 08. 7 calendar days from January 02,
+ * inclusive of the last day.
+ *
+ * https://en.wikipedia.org/wiki/ISO_8601#Repeating_intervals
+ *
+ * @public
+ */
+interface AlertSnoozeFormData {
+    intervals: string;
+}
+/** @public */
+interface AlertDismissFormData {
+    other: Maybe$1<string>;
+    reason: AlertDismissReason;
+    feedback: Maybe$1<string>;
+}
+/** @public */
+declare enum AlertStatus {
+    Snoozed = "snoozed",
+    Accepted = "accepted",
+    Dismissed = "dismissed"
+}
+/** @public */
+type AlertFormProps<A extends Alert, FormData = {}> = {
+    alert: A;
+    onSubmit: (data: FormData) => void;
+    disableSubmit: (isDisabled: boolean) => void;
+};
+/** @public */
+interface AlertDismissOption {
+    label: string;
+    reason: string;
+}
+/** @public */
+declare enum AlertDismissReason {
+    Other = "other",
+    Resolved = "resolved",
+    Expected = "expected",
+    Seasonal = "seasonal",
+    Migration = "migration",
+    NotApplicable = "not-applicable"
+}
+/** @public */
+declare const AlertDismissOptions: AlertDismissOption[];
+/** @public */
+type AlertSnoozeOption = {
+    label: string;
+    duration: Duration;
+};
+/** @public */
+declare const AlertSnoozeOptions: AlertSnoozeOption[];
+/** @public */
+interface AlertCost {
+    id: string;
+    aggregation: [number, number];
+}
+/** @public */
+interface ResourceData {
+    previous: number;
+    current: number;
+    name: Maybe$1<string>;
+}
+/** @public */
+interface BarChartOptions {
+    previousFill: string;
+    currentFill: string;
+    previousName: string;
+    currentName: string;
+}
+/**
+ * @public
+ * @deprecated use BarChartOptions instead
+ */
+interface BarChartData extends BarChartOptions {
+}
+/** @public */
+declare enum DataKey {
+    Previous = "previous",
+    Current = "current",
+    Name = "name"
+}
+/** @public */
+interface ProjectGrowthData {
+    project: string;
+    periodStart: string;
+    periodEnd: string;
+    aggregation: [number, number];
+    change: ChangeStatistic$1;
+    products: Array<AlertCost>;
+}
+/** @public */
+interface UnlabeledDataflowData {
+    periodStart: string;
+    periodEnd: string;
+    projects: Array<UnlabeledDataflowAlertProject>;
+    unlabeledCost: number;
+    labeledCost: number;
+}
+/** @public */
+interface UnlabeledDataflowAlertProject {
+    id: string;
+    unlabeledCost: number;
+    labeledCost: number;
+}
+
+/** @public */
+declare const EngineerThreshold = 0.5;
+/** @public */
+declare enum ChangeThreshold {
+    upper = 0.05,
+    lower = -0.05
+}
+/** @public */
+declare enum GrowthType {
+    Negligible = 0,
+    Savings = 1,
+    Excess = 2
+}
+
+/**
+ * @public
+ */
+type ChartData = {
+    date: number;
+    trend: number;
+    dailyCost: number;
+    [key: string]: number;
+};
+
+/**
+ * @public
+ */
+interface Currency {
+    kind: string | null;
+    label: string;
+    unit: string;
+    prefix?: string;
+    rate?: number;
+}
+
+/** @public */
+declare enum CurrencyType {
+    USD = "USD",
+    CarbonOffsetTons = "CARBON_OFFSET_TONS",
+    Beers = "BEERS",
+    IceCream = "PINTS_OF_ICE_CREAM"
+}
+
+/** @public */
+declare const DEFAULT_DATE_FORMAT = "yyyy-LL-dd";
+
+/**
+ * @public
+ */
+interface PageFilters {
+    group: Maybe$1<string>;
+    project: Maybe$1<string>;
+    duration: Duration;
+    metric: string | null;
+}
+/**
+ * @public
+ */
+type ProductFilters = Array<ProductPeriod>;
+/**
+ * @public
+ */
+interface ProductPeriod {
+    duration: Duration;
+    productType: string;
+}
+
+/** @public */
+type Icon = {
+    kind: string;
+    component: JSX.Element;
+};
+/** @public */
+declare enum IconType {
+    Compute = "compute",
+    Data = "data",
+    Database = "database",
+    Storage = "storage",
+    Search = "search",
+    ML = "ml"
+}
+
+/** @public */
+type Loading = Record<string, boolean>;
+
+/** @public */
+type CostInsightsTooltipOptions = {
+    background: string;
+    color: string;
+};
+/** @public */
+type CostInsightsPaletteAdditions = {
+    blue: string;
+    lightBlue: string;
+    darkBlue: string;
+    magenta: string;
+    yellow: string;
+    tooltip: CostInsightsTooltipOptions;
+    navigationText: string;
+    alertBackground: string;
+    dataViz: string[];
+};
+/** @public */
+type CostInsightsPalette = BackstagePalette & CostInsightsPaletteAdditions;
+/** @public */
+type CostInsightsPaletteOptions = PaletteOptions & CostInsightsPaletteAdditions;
+/** @public */
+interface CostInsightsThemeOptions extends PaletteOptions {
+    palette: CostInsightsPaletteOptions;
+}
+/** @public */
+interface CostInsightsTheme extends BackstageTheme {
+    palette: CostInsightsPalette;
+}
+
+/** @public */
+type TooltipRenderer = (props: TooltipProps<string, string>) => ReactNode;
+
+/**
+ * @deprecated use the same type from `@backstage-community/plugin-cost-insights-common` instead
+ * @public
+ */
+type ChangeStatistic = common.ChangeStatistic;
+/**
+ * @deprecated use the same type from `@backstage-community/plugin-cost-insights-common` instead
+ * @public
+ */
+type Cost = common.Cost;
+/**
+ * @deprecated use the same type from `@backstage-community/plugin-cost-insights-common` instead
+ * @public
+ */
+type DateAggregation = common.DateAggregation;
+/**
+ * @deprecated use the same type from `@backstage-community/plugin-cost-insights-common` instead
+ * @public
+ */
+type Entity = common.Entity;
+/**
+ * @deprecated use the same type from `@backstage-community/plugin-cost-insights-common` instead
+ * @public
+ */
+type Group = common.Group;
+/**
+ * @deprecated use the same type from `@backstage-community/plugin-cost-insights-common` instead
+ * @public
+ */
+type Maybe<T> = common.Maybe<T>;
+/**
+ * @deprecated use the same type from `@backstage-community/plugin-cost-insights-common` instead
+ * @public
+ */
+type Metric = common.Metric;
+/**
+ * @deprecated use the same type from `@backstage-community/plugin-cost-insights-common` instead
+ * @public
+ */
+type MetricData = common.MetricData;
+/**
+ * @deprecated use the same type from `@backstage-community/plugin-cost-insights-common` instead
+ * @public
+ */
+type Product = common.Product;
+/**
+ * @deprecated use the same type from `@backstage-community/plugin-cost-insights-common` instead
+ * @public
+ */
+type Project = common.Project;
+/**
+ * @deprecated use the same type from `@backstage-community/plugin-cost-insights-common` instead
+ * @public
+ */
+type Trendline = common.Trendline;
+
+/** @public */
+type ProductInsightsOptions = {
+    /**
+     * The product from the cost-insights configuration in app-config.yaml
+     */
+    product: string;
+    /**
+     * The group id from getUserGroups or query parameters
+     */
+    group: string;
+    /**
+     * An ISO 8601 repeating interval string, such as R2/P3M/2020-09-01
+     */
+    intervals: string;
+    /**
+     * (optional) The project id from getGroupProjects or query parameters
+     */
+    project: Maybe$1<string>;
+};
+/** @public */
+type CostInsightsApi = {
+    /**
+     * Get the most current date for which billing data is complete, in YYYY-MM-DD format. This helps
+     * define the intervals used in other API methods to avoid showing incomplete cost. The costs for
+     * today, for example, will not be complete. This ideally comes from the cloud provider.
+     */
+    getLastCompleteBillingDate(): Promise<string>;
+    /**
+     * Get a list of groups the given user belongs to. These may be LDAP groups or similar
+     * organizational groups. Cost Insights is designed to show costs based on group membership;
+     * if a user has multiple groups, they are able to switch between groups to see costs for each.
+     *
+     * This method should be removed once the Backstage identity plugin provides the same concept.
+     *
+     * @param userId - The login id for the current user
+     */
+    getUserGroups(userId: string): Promise<Group$1[]>;
+    /**
+     * Get a list of cloud billing entities that belong to this group (projects in GCP, AWS has a
+     * similar concept in billing accounts). These act as filters for the displayed costs, users can
+     * choose whether they see all costs for a group, or those from a particular owned project.
+     *
+     * @param group - The group id from getUserGroups or query parameters
+     */
+    getGroupProjects(group: string): Promise<Project$1[]>;
+    /**
+     * Get daily cost aggregations for a given catalog entity and interval time frame.
+     *
+     * The return type includes an array of daily cost aggregations as well as statistics about the
+     * change in cost over the intervals. Calculating these statistics requires us to bucket costs
+     * into two or more time periods, hence a repeating interval format rather than just a start and
+     * end date.
+     *
+     * The rate of change in this comparison allows teams to reason about their cost growth (or
+     * reduction) and compare it to metrics important to the business.
+     *
+     * Note: implementing this is only required when using the `EntityCostInsightsContent` extension.
+     *
+     * @param catalogEntityRef - A reference to the catalog entity, as described in
+     *   https://backstage.io/docs/features/software-catalog/references
+     * @param intervals - An ISO 8601 repeating interval string, such as R2/P30D/2020-09-01
+     *   https://en.wikipedia.org/wiki/ISO_8601#Repeating_intervals
+     */
+    getCatalogEntityDailyCost?(catalogEntityRef: string, intervals: string): Promise<Cost$1>;
+    /**
+     * Get daily cost aggregations for a given group and interval time frame.
+     *
+     * The return type includes an array of daily cost aggregations as well as statistics about the
+     * change in cost over the intervals. Calculating these statistics requires us to bucket costs
+     * into two or more time periods, hence a repeating interval format rather than just a start and
+     * end date.
+     *
+     * The rate of change in this comparison allows teams to reason about their cost growth (or
+     * reduction) and compare it to metrics important to the business.
+     *
+     * @param group - The group id from getUserGroups or query parameters
+     * @param intervals - An ISO 8601 repeating interval string, such as R2/P30D/2020-09-01
+     *   https://en.wikipedia.org/wiki/ISO_8601#Repeating_intervals
+     */
+    getGroupDailyCost(group: string, intervals: string): Promise<Cost$1>;
+    /**
+     * Get daily cost aggregations for a given billing entity (project in GCP, AWS has a similar
+     * concept in billing accounts) and interval time frame.
+     *
+     * The return type includes an array of daily cost aggregations as well as statistics about the
+     * change in cost over the intervals. Calculating these statistics requires us to bucket costs
+     * into two or more time periods, hence a repeating interval format rather than just a start and
+     * end date.
+     *
+     * The rate of change in this comparison allows teams to reason about the project's cost growth
+     * (or reduction) and compare it to metrics important to the business.
+     *
+     * @param project - The project id from getGroupProjects or query parameters
+     * @param intervals - An ISO 8601 repeating interval string, such as R2/P30D/2020-09-01
+     *   https://en.wikipedia.org/wiki/ISO_8601#Repeating_intervals
+     */
+    getProjectDailyCost(project: string, intervals: string): Promise<Cost$1>;
+    /**
+     * Get aggregations for a particular metric and interval time frame. Teams
+     * can see metrics important to their business in comparison to the growth
+     * (or reduction) of a project or group's daily costs.
+     *
+     * @param metric - A metric from the cost-insights configuration in app-config.yaml.
+     * @param intervals - An ISO 8601 repeating interval string, such as R2/P30D/2020-09-01
+     *   https://en.wikipedia.org/wiki/ISO_8601#Repeating_intervals
+     */
+    getDailyMetricData(metric: string, intervals: string): Promise<MetricData$1>;
+    /**
+     * Get cost aggregations for a particular cloud product and interval time frame. This includes
+     * total cost for the product, as well as a breakdown of particular entities that incurred cost
+     * in this product. The type of entity depends on the product - it may be deployed services,
+     * storage buckets, managed database instances, etc.
+     *
+     * If project is supplied, this should only return product costs for the given billing entity
+     * (project in GCP).
+     *
+     * The time period is supplied as a Duration rather than intervals, since this is always expected
+     * to return data for two bucketed time period (e.g. month vs month, or quarter vs quarter).
+     *
+     * @param options - Options to use when fetching insights for a particular cloud product and
+     *                interval time frame.
+     */
+    getProductInsights(options: ProductInsightsOptions): Promise<Entity$1>;
+    /**
+     * Get current cost alerts for a given group. These show up as Action Items for the group on the
+     * Cost Insights page. Alerts may include cost-saving recommendations, such as infrastructure
+     * migrations, or cost-related warnings, such as an unexpected billing anomaly.
+     */
+    getAlerts(group: string): Promise<Alert[]>;
+};
+/** @public */
+declare const costInsightsApiRef: _backstage_core_plugin_api.ApiRef<CostInsightsApi>;
+
+/** @public */
+declare class ExampleCostInsightsClient implements CostInsightsApi {
+    private request;
+    getLastCompleteBillingDate(): Promise<string>;
+    getUserGroups(userId: string): Promise<Group$1[]>;
+    getGroupProjects(group: string): Promise<Project$1[]>;
+    getDailyMetricData(metric: string, intervals: string): Promise<MetricData$1>;
+    getCatalogEntityDailyCost(entityRef: string, intervals: string): Promise<Cost$1>;
+    getGroupDailyCost(group: string, intervals: string): Promise<Cost$1>;
+    getProjectDailyCost(project: string, intervals: string): Promise<Cost$1>;
+    getProductInsights(options: ProductInsightsOptions): Promise<Entity$1>;
+    getAlerts(group: string): Promise<Alert[]>;
+}
+
+/** @public */
+type BarChartProps = {
+    resources: ResourceData[];
+    responsive?: boolean;
+    displayAmount?: number;
+    options?: Partial<BarChartOptions>;
+    tooltip?: TooltipRenderer;
+    onClick?: (...args: any[]) => void;
+    onMouseMove?: (...args: any[]) => void;
+};
+/** @public */
+declare const BarChart: (props: BarChartProps) => React__default.JSX.Element;
+
+/** @public */
+type BarChartLegendOptions = {
+    previousName: string;
+    previousFill: string;
+    currentName: string;
+    currentFill: string;
+    hideMarker?: boolean;
+};
+/** @public */
+type BarChartLegendProps = {
+    costStart: number;
+    costEnd: number;
+    options?: Partial<BarChartLegendOptions>;
+};
+/** @public */
+declare const BarChartLegend: (props: PropsWithChildren<BarChartLegendProps>) => React__default.JSX.Element;
+
+/** @public */
+type BarChartTooltipProps = {
+    title: string;
+    content?: ReactNode | string;
+    subtitle?: ReactNode;
+    topRight?: ReactNode;
+    actions?: ReactNode;
+};
+/** @public */
+declare const BarChartTooltip: (props: PropsWithChildren<BarChartTooltipProps>) => React__default.JSX.Element;
+
+/** @public */
+type TooltipItem = {
+    fill: string;
+    label?: string;
+    value?: string;
+};
+/** @public */
+type BarChartTooltipItemProps = {
+    item: TooltipItem;
+};
+/** @public */
+declare const BarChartTooltipItem: (props: BarChartTooltipItemProps) => React__default.JSX.Element;
+
+/** @public */
+type CostGrowthProps = {
+    change: ChangeStatistic$1;
+    duration: Duration;
+};
+/** @public */
+declare const CostGrowth: (props: CostGrowthProps) => React__default.JSX.Element;
+
+/** @public */
+type CostGrowthIndicatorProps = TypographyProps & {
+    change: ChangeStatistic$1;
+    formatter?: (change: ChangeStatistic$1, options?: {
+        absolute: boolean;
+    }) => Maybe$1<string>;
+};
+/** @public */
+declare const CostGrowthIndicator: (props: CostGrowthIndicatorProps) => React__default.JSX.Element;
+
+/** @public */
+type LegendItemProps = {
+    title: string;
+    tooltipText?: string;
+    markerColor?: string;
+};
+/** @public */
+declare const LegendItem: (props: PropsWithChildren<LegendItemProps>) => React__default.JSX.Element;
+
+/** @public */
+type ConfigContextProps = {
+    baseCurrency: Intl.NumberFormat;
+    metrics: Metric$1[];
+    products: Product$1[];
+    icons: Icon[];
+    engineerCost: number;
+    engineerThreshold: number;
+    hideTrendLine: boolean;
+    currencies: Currency[];
+};
+
+/** @public */
+type CurrencyContextProps = {
+    currency: Currency;
+    setCurrency: Dispatch<SetStateAction<Currency>>;
+};
+
+/** @public */
+type MockConfigProviderProps = PropsWithChildren<Partial<ConfigContextProps>>;
+/** @public */
+declare const MockConfigProvider: (props: MockConfigProviderProps) => React__default.JSX.Element;
+/** @public */
+type MockCurrencyProviderProps = PropsWithChildren<Partial<CurrencyContextProps>>;
+/** @public */
+declare const MockCurrencyProvider: (props: MockCurrencyProviderProps) => React__default.JSX.Element;
+
+/**
+ * The alert below is an example of an Alert implementation; the CostInsightsApi permits returning
+ * any implementation of the Alert type, so adopters can create their own. The CostInsightsApi
+ * fetches alert data from the backend, then creates Alert classes with the data.
+ *
+ * @public
+ */
+declare class ProjectGrowthAlert implements Alert {
+    data: ProjectGrowthData;
+    constructor(data: ProjectGrowthData);
+    get url(): string;
+    get title(): string;
+    get subtitle(): string;
+    get element(): React__default.JSX.Element;
+}
+
+/**
+ * The alert below is an example of an Alert implementation; the CostInsightsApi permits returning
+ * any implementation of the Alert type, so adopters can create their own. The CostInsightsApi
+ * fetches alert data from the backend, then creates Alert classes with the data.
+ *
+ * @public
+ */
+declare class UnlabeledDataflowAlert implements Alert {
+    data: UnlabeledDataflowData;
+    status?: AlertStatus;
+    constructor(data: UnlabeledDataflowData);
+    get url(): string;
+    get title(): string;
+    get subtitle(): string;
+    get element(): React__default.JSX.Element;
+}
+
+export { type Alert, type AlertCost, type AlertDismissFormData, type AlertDismissOption, AlertDismissOptions, AlertDismissReason, type AlertForm, type AlertFormProps, type AlertOptions, type AlertSnoozeFormData, type AlertSnoozeOption, AlertSnoozeOptions, AlertStatus, BarChart, type BarChartData, BarChartLegend, type BarChartLegendOptions, type BarChartLegendProps, type BarChartOptions, type BarChartProps, BarChartTooltip, BarChartTooltipItem, type BarChartTooltipItemProps, type BarChartTooltipProps, type ChangeStatistic, ChangeThreshold, type ChartData, type ConfigContextProps, type Cost, CostGrowth, CostGrowthIndicator, type CostGrowthIndicatorProps, type CostGrowthProps, type CostInsightsApi, CostInsightsLabelDataflowInstructionsPage, CostInsightsPage, type CostInsightsPalette, type CostInsightsPaletteAdditions, type CostInsightsPaletteOptions, CostInsightsProjectGrowthInstructionsPage, type CostInsightsTheme, type CostInsightsThemeOptions, type CostInsightsTooltipOptions, type Currency, type CurrencyContextProps, CurrencyType, DEFAULT_DATE_FORMAT, DataKey, type DateAggregation, Duration, EngineerThreshold, type Entity, EntityCostInsightsContent, ExampleCostInsightsClient, type Group, GrowthType, type Icon, IconType, LegendItem, type LegendItemProps, type Loading, type Maybe, type Metric, type MetricData, MockConfigProvider, type MockConfigProviderProps, MockCurrencyProvider, type MockCurrencyProviderProps, type PageFilters, type Product, type ProductFilters, type ProductInsightsOptions, type ProductPeriod, type Project, ProjectGrowthAlert, type ProjectGrowthData, type ResourceData, type TooltipItem, type TooltipRenderer, type Trendline, UnlabeledDataflowAlert, type UnlabeledDataflowAlertProject, type UnlabeledDataflowData, costInsightsApiRef, costInsightsPlugin, costInsightsPlugin as plugin };