@oneuptime/common 12.0.5 → 12.0.6

package/Tests/Utils/Telemetry/CaptureSpanExportGating.test.ts

@@ -0,0 +1,288 @@
+import { describe, expect, jest, test, beforeEach } from "@jest/globals";
+
+/*
+ * Contract under test — @CaptureSpan's export gating.
+ *
+ * The decorator wraps ~hundreds of methods, some of which sit on per-record
+ * telemetry ingest paths. It must be a plain method call (no span, no
+ * attribute flattening, no AsyncLocalStorage transition) whenever no span
+ * exporter is installed — spans that are never exported are pure overhead —
+ * and only build the attribute object when there is actually something to
+ * attach. When an exporter IS installed it must keep the full original
+ * behavior: named span, OK status on success, recorded exception + rethrow
+ * on failure, for both sync and async methods.
+ */
+
+type JestMock = ReturnType<typeof jest.fn>;
+
+type FakeSpan = {
+  setStatus: JestMock;
+  end: JestMock;
+};
+
+const fakeSpan: FakeSpan = {
+  setStatus: jest.fn(),
+  end: jest.fn(),
+};
+
+let spanExportEnabled: boolean = false;
+
+const startActiveSpanMock: JestMock = jest.fn((data: any) => {
+  return data.fn(fakeSpan);
+});
+const recordExceptionMock: JestMock = jest.fn();
+
+jest.mock("../../../Server/Utils/Telemetry", () => {
+  return {
+    __esModule: true,
+    default: {
+      isSpanExportEnabled: (): boolean => {
+        return spanExportEnabled;
+      },
+      startActiveSpan: (data: unknown): unknown => {
+        return startActiveSpanMock(data);
+      },
+      recordExceptionMarkSpanAsErrorAndEndSpan: (data: unknown): unknown => {
+        return recordExceptionMock(data);
+      },
+    },
+  };
+});
+
+jest.mock("../../../Server/EnvironmentConfig", () => {
+  const actual: Record<string, unknown> = jest.requireActual(
+    "../../../Server/EnvironmentConfig",
+  ) as Record<string, unknown>;
+  return {
+    ...actual,
+    DisableTelemetry: false,
+  };
+});
+
+import CaptureSpan from "../../../Server/Utils/Telemetry/CaptureSpan";
+
+/*
+ * Apply the decorator exactly the way TypeScript does for a static method,
+ * without relying on decorator syntax support in the test transform.
+ */
+function decorate(
+  data: Parameters<typeof CaptureSpan>[0] | undefined,
+  fn: (...args: Array<any>) => any,
+  methodName: string = "method",
+): (...args: Array<any>) => any {
+  class Host {}
+  const descriptor: TypedPropertyDescriptor<any> = { value: fn };
+  CaptureSpan(data)(Host, methodName, descriptor);
+  return descriptor.value;
+}
+
+beforeEach(() => {
+  spanExportEnabled = false;
+  startActiveSpanMock.mockClear();
+  recordExceptionMock.mockClear();
+  fakeSpan.setStatus.mockClear();
+  fakeSpan.end.mockClear();
+});
+
+describe("CaptureSpan with no span exporter installed", () => {
+  test("calls the original method directly and creates no span", () => {
+    const original: JestMock = jest.fn().mockReturnValue("result");
+    const wrapped: (...args: Array<any>) => any = decorate(undefined, original);
+
+    expect(wrapped("a", 1)).toBe("result");
+    expect(original).toHaveBeenCalledWith("a", 1);
+    expect(startActiveSpanMock).not.toHaveBeenCalled();
+  });
+
+  test("preserves `this` binding", () => {
+    const wrapped: (...args: Array<any>) => any = decorate(
+      undefined,
+      function (this: { value: number }): number {
+        return this.value;
+      },
+    );
+
+    expect(wrapped.call({ value: 42 })).toBe(42);
+  });
+
+  test("async results and rejections pass through untouched", async () => {
+    const wrappedOk: (...args: Array<any>) => any = decorate(
+      undefined,
+      async (): Promise<string> => {
+        return "async-result";
+      },
+    );
+    await expect(wrappedOk()).resolves.toBe("async-result");
+
+    const boom: Error = new Error("boom");
+    const wrappedFail: (...args: Array<any>) => any = decorate(
+      undefined,
+      async (): Promise<never> => {
+        throw boom;
+      },
+    );
+    await expect(wrappedFail()).rejects.toBe(boom);
+    expect(startActiveSpanMock).not.toHaveBeenCalled();
+  });
+
+  test("sync throws pass through untouched", () => {
+    const boom: Error = new Error("sync-boom");
+    const wrapped: (...args: Array<any>) => any = decorate(undefined, () => {
+      throw boom;
+    });
+
+    expect(() => {
+      return wrapped();
+    }).toThrow(boom);
+    expect(startActiveSpanMock).not.toHaveBeenCalled();
+  });
+});
+
+describe("CaptureSpan with a span exporter installed", () => {
+  beforeEach(() => {
+    spanExportEnabled = true;
+  });
+
+  test("creates a span named Class.method and returns the result", () => {
+    const wrapped: (...args: Array<any>) => any = decorate(
+      undefined,
+      () => {
+        return "spanned";
+      },
+      "doWork",
+    );
+
+    expect(wrapped()).toBe("spanned");
+    expect(startActiveSpanMock).toHaveBeenCalledTimes(1);
+
+    const callData: any = startActiveSpanMock.mock.calls[0]![0];
+    expect(callData.name).toBe("Host.doWork");
+    expect(fakeSpan.setStatus).toHaveBeenCalledWith({ code: 1 }); // OK
+    expect(fakeSpan.end).toHaveBeenCalledTimes(1);
+  });
+
+  test("bare @CaptureSpan() attaches no attributes (flattening skipped)", () => {
+    const wrapped: (...args: Array<any>) => any = decorate(undefined, () => {
+      return "x";
+    });
+    wrapped("argument-that-must-not-be-captured");
+
+    const callData: any = startActiveSpanMock.mock.calls[0]![0];
+    expect(callData.options).toEqual({});
+  });
+
+  test("captureArguments flattens call arguments into span attributes", () => {
+    const wrapped: (...args: Array<any>) => any = decorate(
+      { captureArguments: true },
+      () => {
+        return "x";
+      },
+    );
+    wrapped("first", { nested: { key: "v" } });
+
+    const callData: any = startActiveSpanMock.mock.calls[0]![0];
+    expect(callData.options.attributes["arg0"]).toBe("first");
+    expect(callData.options.attributes["arg1.nested.key"]).toBe("v");
+  });
+
+  test("static attributes are attached", () => {
+    const wrapped: (...args: Array<any>) => any = decorate(
+      { attributes: { component: "test" } },
+      () => {
+        return "x";
+      },
+    );
+    wrapped();
+
+    const callData: any = startActiveSpanMock.mock.calls[0]![0];
+    expect(callData.options.attributes["component"]).toBe("test");
+  });
+
+  test("async success marks the span OK and ends it", async () => {
+    const wrapped: (...args: Array<any>) => any = decorate(
+      undefined,
+      async (): Promise<string> => {
+        return "ok";
+      },
+    );
+
+    await expect(wrapped()).resolves.toBe("ok");
+    expect(fakeSpan.setStatus).toHaveBeenCalledWith({ code: 1 });
+    expect(fakeSpan.end).toHaveBeenCalledTimes(1);
+  });
+
+  test("async failure records the exception, rethrows, and ends the span", async () => {
+    const boom: Error = new Error("async-span-boom");
+    const wrapped: (...args: Array<any>) => any = decorate(
+      undefined,
+      async (): Promise<never> => {
+        throw boom;
+      },
+    );
+
+    await expect(wrapped()).rejects.toBe(boom);
+    expect(recordExceptionMock).toHaveBeenCalledTimes(1);
+    expect(recordExceptionMock.mock.calls[0]![0]).toMatchObject({
+      exception: boom,
+    });
+    expect(fakeSpan.end).toHaveBeenCalledTimes(1);
+  });
+
+  test("sync failure records the exception and rethrows", () => {
+    const boom: Error = new Error("sync-span-boom");
+    const wrapped: (...args: Array<any>) => any = decorate(undefined, () => {
+      throw boom;
+    });
+
+    expect(() => {
+      return wrapped();
+    }).toThrow(boom);
+    expect(recordExceptionMock).toHaveBeenCalledTimes(1);
+  });
+});
+
+describe("export flag is consulted at call time, not decoration time", () => {
+  /*
+   * Decorators run at class-definition (import) time, long before
+   * Telemetry.init() installs an exporter and flips the flag. If the wrapper
+   * captured the flag when it was applied instead of reading it per call,
+   * every span in the process would be silently lost — decoration always
+   * happens while the flag is still false.
+   */
+  test("a method decorated before the exporter exists starts spanning once export turns on", () => {
+    const wrapped: (...args: Array<any>) => any = decorate(undefined, () => {
+      return "x";
+    });
+
+    expect(wrapped()).toBe("x");
+    expect(startActiveSpanMock).not.toHaveBeenCalled();
+
+    spanExportEnabled = true;
+    expect(wrapped()).toBe("x");
+    expect(startActiveSpanMock).toHaveBeenCalledTimes(1);
+  });
+
+  test("a method decorated while export was on drops to passthrough when it turns off", () => {
+    spanExportEnabled = true;
+    const wrapped: (...args: Array<any>) => any = decorate(undefined, () => {
+      return "y";
+    });
+
+    expect(wrapped()).toBe("y");
+    expect(startActiveSpanMock).toHaveBeenCalledTimes(1);
+
+    spanExportEnabled = false;
+    expect(wrapped()).toBe("y");
+    expect(startActiveSpanMock).toHaveBeenCalledTimes(1);
+  });
+});
+
+describe("Telemetry.isSpanExportEnabled (real module)", () => {
+  test("defaults to false before init installs a trace exporter", () => {
+    const RealTelemetry: any = (
+      jest.requireActual("../../../Server/Utils/Telemetry") as any
+    ).default;
+
+    expect(RealTelemetry.isSpanExportEnabled()).toBe(false);
+  });
+});

package/Tests/Utils/Telemetry/IngestionTimestamp.test.ts

@@ -0,0 +1,170 @@
+import {
+  IngestionStamp,
+  getIngestionStamp,
+  getRetentionDateDb,
+} from "../../../Server/Utils/Telemetry/IngestionTimestamp";
+import OneUptimeDate from "../../../Types/Date";
+import {
+  afterEach,
+  beforeEach,
+  describe,
+  expect,
+  jest,
+  test,
+} from "@jest/globals";
+
+/*
+ * Minimal structural view of a jest spy — the @jest/globals and @types/jest
+ * spy types disagree in this repo, so annotate with just the surface this
+ * test reads.
+ */
+type SpyLike = {
+  mock: { calls: Array<Array<unknown>> };
+  mockRestore: () => void;
+};
+
+/*
+ * Contract under test — the per-second memo behind every ingested row's
+ * createdAt / retentionDate stamps.
+ *
+ * The Otel logs / traces / metrics row builders used to derive these per
+ * row (current Date + ClickHouse format + moment add-days + second format,
+ * per log record / span / metric datapoint). The memo must hand out values
+ * IDENTICAL to that per-row derivation — same second → same strings — and
+ * roll over crisply on the second boundary, or rows would carry stale
+ * createdAt / retention stamps.
+ */
+
+describe("getIngestionStamp", () => {
+  beforeEach(() => {
+    jest.useFakeTimers();
+  });
+
+  afterEach(() => {
+    jest.useRealTimers();
+  });
+
+  test("db string matches toClickhouseDateTime of the stamp's date", () => {
+    jest.setSystemTime(new Date("2026-08-10T13:45:59.700Z"));
+
+    const stamp: IngestionStamp = getIngestionStamp();
+
+    expect(stamp.db).toBe(OneUptimeDate.toClickhouseDateTime(stamp.date));
+    expect(stamp.db).toBe("2026-08-10 13:45:59");
+  });
+
+  test("date is truncated to the second", () => {
+    jest.setSystemTime(new Date("2026-08-10T13:45:59.999Z"));
+
+    const stamp: IngestionStamp = getIngestionStamp();
+
+    expect(stamp.date.getMilliseconds()).toBe(0);
+    expect(stamp.date.getTime()).toBe(
+      new Date("2026-08-10T13:45:59.000Z").getTime(),
+    );
+  });
+
+  test("same second returns the identical stamp object (memo hit)", () => {
+    jest.setSystemTime(new Date("2026-08-10T13:45:59.100Z"));
+    const first: IngestionStamp = getIngestionStamp();
+
+    jest.setSystemTime(new Date("2026-08-10T13:45:59.900Z"));
+    const second: IngestionStamp = getIngestionStamp();
+
+    expect(second).toBe(first);
+  });
+
+  test("rolls over when the second changes", () => {
+    jest.setSystemTime(new Date("2026-08-10T13:45:59.900Z"));
+    const first: IngestionStamp = getIngestionStamp();
+
+    jest.setSystemTime(new Date("2026-08-10T13:46:00.000Z"));
+    const second: IngestionStamp = getIngestionStamp();
+
+    expect(second).not.toBe(first);
+    expect(first.db).toBe("2026-08-10 13:45:59");
+    expect(second.db).toBe("2026-08-10 13:46:00");
+  });
+});
+
+describe("getRetentionDateDb", () => {
+  beforeEach(() => {
+    jest.useFakeTimers();
+    jest.setSystemTime(new Date("2026-08-10T13:45:59.700Z"));
+  });
+
+  afterEach(() => {
+    jest.useRealTimers();
+  });
+
+  test("equals the per-row derivation it replaced (addRemoveDays + format)", () => {
+    const stamp: IngestionStamp = getIngestionStamp();
+
+    for (const days of [1, 15, 30, 90, 365]) {
+      expect(getRetentionDateDb(stamp, days)).toBe(
+        OneUptimeDate.toClickhouseDateTime(
+          OneUptimeDate.addRemoveDays(stamp.date, days),
+        ),
+      );
+    }
+  });
+
+  test("distinct retention windows produce distinct dates", () => {
+    const stamp: IngestionStamp = getIngestionStamp();
+
+    expect(getRetentionDateDb(stamp, 15)).toBe(
+      OneUptimeDate.toClickhouseDateTime(
+        OneUptimeDate.addRemoveDays(stamp.date, 15),
+      ),
+    );
+    expect(getRetentionDateDb(stamp, 30)).toBe(
+      OneUptimeDate.toClickhouseDateTime(
+        OneUptimeDate.addRemoveDays(stamp.date, 30),
+      ),
+    );
+    expect(getRetentionDateDb(stamp, 15)).not.toBe(
+      getRetentionDateDb(stamp, 30),
+    );
+  });
+
+  test("memoizes per retention window: addRemoveDays runs once per (second, days)", () => {
+    const stamp: IngestionStamp = getIngestionStamp();
+    const addRemoveDaysSpy: SpyLike = jest.spyOn(
+      OneUptimeDate,
+      "addRemoveDays",
+    ) as unknown as SpyLike;
+
+    const first: string = getRetentionDateDb(stamp, 15);
+    const callsAfterFirst: number = addRemoveDaysSpy.mock.calls.length;
+
+    for (let i: number = 0; i < 50; i++) {
+      expect(getRetentionDateDb(stamp, 15)).toBe(first);
+    }
+
+    expect(addRemoveDaysSpy.mock.calls.length).toBe(callsAfterFirst);
+    addRemoveDaysSpy.mockRestore();
+  });
+
+  test("stays consistent with the stamp's own second, not the current clock", () => {
+    const stamp: IngestionStamp = getIngestionStamp();
+    const expected: string = getRetentionDateDb(stamp, 15);
+
+    // Clock moves on; a held stamp must keep answering for ITS second.
+    jest.setSystemTime(new Date("2026-08-10T13:46:30.000Z"));
+
+    expect(getRetentionDateDb(stamp, 15)).toBe(expected);
+  });
+
+  test("computes correctly for a bare stamp that never went through the memo", () => {
+    const bareStamp: IngestionStamp = {
+      date: new Date("2026-01-01T00:00:00.000Z"),
+      db: "2026-01-01 00:00:00",
+    };
+
+    expect(getRetentionDateDb(bareStamp, 15)).toBe(
+      OneUptimeDate.toClickhouseDateTime(
+        OneUptimeDate.addRemoveDays(bareStamp.date, 15),
+      ),
+    );
+  });
+});

package/Types/AI/AIInsightEvidence.ts

@@ -30,6 +30,12 @@ export interface ExceptionInsightEvidence {
   spikeMultiplier?: number | undefined;
   // Lifetime occurrence count of the exception.
   totalOccurrenceCount?: number | undefined;
+  /*
+   * How many distinct TelemetryException groups (i.e. stack-trace variants of
+   * the same type + normalized message) this finding rolls up. 1 for the
+   * ordinary case; higher when one throw site surfaces on several call paths.
+   */
+  distinctExceptionGroupCount?: number | undefined;
   // ISO-8601 — when the exception was first ever seen.
   firstSeenAt?: string | undefined;
 }

package/Types/Analytics/RevenueEvent.ts

@@ -0,0 +1,31 @@
+import { JSONObject } from "../JSON";
+
+/**
+ * Stable, versioned events used to measure the self-serve revenue funnel.
+ *
+ * Event names are intentionally GA4-compatible snake_case. Additive property
+ * changes are safe; breaking semantic changes require a new schema version.
+ */
+export enum RevenueEventName {
+  SignupStarted = "signup_started",
+  SignupCompleted = "sign_up",
+  WorkspaceCreated = "workspace_created",
+  MonitorCreated = "monitor_created",
+  TeammateInvited = "teammate_invited",
+  SubscriptionUpgraded = "subscription_upgraded",
+  SubscriptionDowngraded = "subscription_downgraded",
+}
+
+export enum RevenueFunnelStage {
+  Acquisition = "acquisition",
+  Signup = "signup",
+  Activation = "activation",
+  Collaboration = "collaboration",
+  Revenue = "revenue",
+}
+
+export interface RevenueEventProperties extends JSONObject {
+  funnel_stage: RevenueFunnelStage;
+}
+
+export const REVENUE_EVENT_SCHEMA_VERSION: number = 1;

package/Types/Dashboard/DashboardComponentType.ts

@@ -5,6 +5,17 @@ enum DashboardComponentType {
   Clock = `Clock`,
   Table = `Table`,
   Gauge = `Gauge`,
+  /*
+   * Widgets that read an EXTERNAL Data Source (Prometheus, SQL, ClickHouse,
+   * Loki, Elasticsearch, REST) rather than OneUptime's own telemetry. They
+   * are separate component types — not a mode of the metric widgets above —
+   * so each one can carry the query editor, defaults, and rendering its own
+   * source of data actually needs. Not available on public dashboards.
+   */
+  DataSourceChart = `DataSourceChart`,
+  DataSourceValue = `DataSourceValue`,
+  DataSourceGauge = `DataSourceGauge`,
+  DataSourceTable = `DataSourceTable`,
   LogStream = `LogStream`,
   LogChart = `LogChart`,
   TraceList = `TraceList`,
@@ -44,3 +55,23 @@ enum DashboardComponentType {
 }
 
 export default DashboardComponentType;
+
+/*
+ * Every widget type that reads an EXTERNAL Data Source. Kept next to the
+ * enum so adding a fifth one is a single edit, and consumed by the widget
+ * settings form (which query editor to render) and by anything that has to
+ * treat external-data widgets as a class — notably the public dashboard,
+ * where they are unavailable.
+ */
+export const DataSourceComponentTypes: ReadonlyArray<DashboardComponentType> = [
+  DashboardComponentType.DataSourceChart,
+  DashboardComponentType.DataSourceValue,
+  DashboardComponentType.DataSourceGauge,
+  DashboardComponentType.DataSourceTable,
+];
+
+export function isDataSourceComponentType(
+  componentType: DashboardComponentType,
+): boolean {
+  return DataSourceComponentTypes.includes(componentType);
+}

package/Types/Dashboard/DashboardComponents/DashboardDataSourceChartComponent.ts

@@ -0,0 +1,27 @@
+import DataSourceQueryConfig from "../../DataSource/DataSourceQueryConfig";
+import ObjectID from "../../ObjectID";
+import DashboardComponentType from "../DashboardComponentType";
+import DashboardChartType from "../Chart/ChartType";
+import BaseComponent from "./DashboardBaseComponent";
+
+/*
+ * Time-series chart over one or more EXTERNAL Data Source queries (PromQL /
+ * SQL / LogQL / ES DSL / REST). The OneUptime-metrics chart is a separate
+ * widget (DashboardChartComponent) — this one never touches metric queries,
+ * formulas, or the metric explorer.
+ *
+ * Not available on public dashboards: the anonymous API has no data-source
+ * surface, by design.
+ */
+export default interface DashboardDataSourceChartComponent
+  extends BaseComponent {
+  componentType: DashboardComponentType.DataSourceChart;
+  componentId: ObjectID;
+  arguments: {
+    // Each query becomes one overlaid set of series on the chart.
+    queries?: Array<DataSourceQueryConfig> | undefined;
+    chartTitle?: string | undefined;
+    chartDescription?: string | undefined;
+    chartType?: DashboardChartType | undefined;
+  };
+}

package/Types/Dashboard/DashboardComponents/DashboardDataSourceGaugeComponent.ts

@@ -0,0 +1,32 @@
+import DataSourceQueryConfig from "../../DataSource/DataSourceQueryConfig";
+import ObjectID from "../../ObjectID";
+import DashboardComponentType from "../DashboardComponentType";
+import BaseComponent from "./DashboardBaseComponent";
+import { DataSourceValueReduce } from "./DashboardDataSourceValueComponent";
+
+/*
+ * Radial gauge driven by an EXTERNAL Data Source query. The
+ * OneUptime-metrics equivalent is DashboardGaugeComponent.
+ *
+ * Not available on public dashboards.
+ */
+export default interface DashboardDataSourceGaugeComponent
+  extends BaseComponent {
+  componentType: DashboardComponentType.DataSourceGauge;
+  componentId: ObjectID;
+  arguments: {
+    query?: DataSourceQueryConfig | undefined;
+    gaugeTitle?: string | undefined;
+    // See DashboardDataSourceValueComponent — same reduction, same default.
+    reduce?: DataSourceValueReduce | undefined;
+    /*
+     * Unit suffix for the centre value and the min/max footer. External
+     * queries carry no MetricType to derive one from.
+     */
+    unit?: string | undefined;
+    minValue?: number | undefined;
+    maxValue?: number | undefined;
+    warningThreshold?: number | undefined;
+    criticalThreshold?: number | undefined;
+  };
+}

package/Types/Dashboard/DashboardComponents/DashboardDataSourceTableComponent.ts

@@ -0,0 +1,30 @@
+import DataSourceQueryConfig from "../../DataSource/DataSourceQueryConfig";
+import ObjectID from "../../ObjectID";
+import DashboardComponentType from "../DashboardComponentType";
+import BaseComponent from "./DashboardBaseComponent";
+
+/*
+ * Tabular rows straight from an EXTERNAL Data Source query. Columns come
+ * from the query result, not from widget config — the connector normalizes
+ * every source into DataSourceTableResult. The OneUptime-metrics
+ * equivalent (columns, formulas, group-by) is DashboardTableComponent.
+ *
+ * Not available on public dashboards.
+ */
+export default interface DashboardDataSourceTableComponent
+  extends BaseComponent {
+  componentType: DashboardComponentType.DataSourceTable;
+  componentId: ObjectID;
+  arguments: {
+    query?: DataSourceQueryConfig | undefined;
+    tableTitle?: string | undefined;
+    tableDescription?: string | undefined;
+    /*
+     * Client-side cap on rendered rows, applied after sorting so "top 10 by
+     * this column" works. The connector's own row cap still applies first —
+     * this only trims what the widget draws. Absent ⇒ render every row the
+     * query returned.
+     */
+    maxRows?: number | undefined;
+  };
+}

package/Types/Dashboard/DashboardComponents/DashboardDataSourceValueComponent.ts

@@ -0,0 +1,55 @@
+import DataSourceQueryConfig from "../../DataSource/DataSourceQueryConfig";
+import ObjectID from "../../ObjectID";
+import DashboardComponentType from "../DashboardComponentType";
+import BaseComponent from "./DashboardBaseComponent";
+import { DashboardValueTrendDirection } from "./DashboardValueComponent";
+
+/*
+ * How the points a Data Source query returns over the dashboard's time
+ * window collapse into the single number the widget shows. The metric
+ * Value widget takes this from the metric query's "Aggregate by" picker;
+ * an external query has no such picker, so it is a widget argument here.
+ */
+export enum DataSourceValueReduce {
+  Last = "Last",
+  First = "First",
+  Avg = "Avg",
+  Sum = "Sum",
+  Min = "Min",
+  Max = "Max",
+}
+
+/*
+ * Single big-number stat driven by an EXTERNAL Data Source query. The
+ * OneUptime-metrics equivalent is DashboardValueComponent; the two share a
+ * renderer but not a configuration surface.
+ *
+ * Not available on public dashboards.
+ */
+export default interface DashboardDataSourceValueComponent
+  extends BaseComponent {
+  componentType: DashboardComponentType.DataSourceValue;
+  componentId: ObjectID;
+  arguments: {
+    query?: DataSourceQueryConfig | undefined;
+    title: string;
+    /*
+     * How the returned points reduce to one number. Absent ⇒ Last, which
+     * is what "the current value of this query" means for the overwhelming
+     * majority of external queries (a Prometheus instant-style rate, a SQL
+     * count per bucket).
+     */
+    reduce?: DataSourceValueReduce | undefined;
+    /*
+     * Unit suffix rendered after the number. External queries carry no
+     * OneUptime MetricType, so there is nothing to derive a unit from —
+     * the user names it. Known units also scale the value the same way
+     * metric units do ("Bytes" ⇒ 1.5 MB, "ms" ⇒ 2.4 sec, "%" ⇒ 99.9%).
+     * Empty/undefined ⇒ the raw number with no suffix.
+     */
+    unit?: string | undefined;
+    warningThreshold?: number | undefined;
+    criticalThreshold?: number | undefined;
+    trendDirection?: DashboardValueTrendDirection | undefined;
+  };
+}