@oneuptime/common 12.0.5 → 12.0.7

package/Tests/__mocks__/i18next-browser-languagedetector.js

@@ -0,0 +1,21 @@
+"use strict";
+
+/*
+ * The real detector is only installed in the frontend feature sets. Tests that
+ * render status page components import Utils/i18n, which registers this plugin,
+ * so a minimal stand-in that always resolves to English is enough.
+ */
+class LanguageDetector {
+  init() {}
+
+  detect() {
+    return "en";
+  }
+
+  cacheUserLanguage() {}
+}
+
+LanguageDetector.type = "languageDetector";
+
+module.exports = LanguageDetector;
+module.exports.default = LanguageDetector;

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/AI/FixPullRequestCiStatus.ts

@@ -3,7 +3,7 @@ import CodeFixTaskType from "./CodeFixTaskType";
 /*
  * The rolled-up CI conclusion recorded on an AI fix pull request
  * (AIAgentTaskPullRequest.ciStatus) — B4 Tier 1: verification via the
- * customer's OWN CI on the draft PRs. We read check-run conclusions through
+ * customer's OWN CI on the fix PRs. We read check-run conclusions through
  * the GitHub App; we never re-run or gate the customer's CI.
  *
  * G9 honesty rule: only Green and ExpectedFailureObserved ever count as

package/Types/AI/FixVerificationStatus.ts

@@ -7,8 +7,8 @@
  *   - Passed: every configured command (setup, build, test) exited 0 —
  *     possibly after bounded agent repair attempts.
  *   - Failed: a configured command still failed after the repair attempts
- *     were exhausted. The PR still opens (as a draft, clearly labeled) so
- *     the work is not lost — the human reviewer decides.
+ *     were exhausted. The PR still opens, with the failure clearly labeled
+ *     in its body, so the work is not lost — the human reviewer decides.
  *   - Skipped: the repository has no verification commands configured, so
  *     nothing could be verified.
  */

package/Types/API/Hostname.ts

@@ -5,6 +5,27 @@ import Port from "../Port";
 import Typeof from "../Typeof";
 import { FindOperator } from "typeorm";
 
+/*
+ * A chain of DNS labels (which also covers IPv4 literals). Labels are
+ * alphanumeric plus "-" and "_", may not start or end with "-", and are
+ * capped at 63 characters; a single trailing dot (the fully-qualified form)
+ * is allowed. "_" is permitted because internal and service-discovery names
+ * use it and it is not a URL delimiter.
+ */
+const HOST_REGEX: RegExp =
+  /^[a-zA-Z0-9_](?:[a-zA-Z0-9_-]{0,61}[a-zA-Z0-9_])?(?:\.[a-zA-Z0-9_](?:[a-zA-Z0-9_-]{0,61}[a-zA-Z0-9_])?)*\.?$/;
+
+/*
+ * Anything that is not a URL delimiter. The point is not to validate
+ * credentials, it is to make sure userinfo cannot smuggle a path, a query, a
+ * fragment or a second authority past the host check.
+ */
+const USER_INFO_REGEX: RegExp = /^[^@/?#\s[\]]*$/;
+
+const IPV6_CHARS_REGEX: RegExp = /^[0-9a-fA-F:.]+$/;
+
+const PORT_REGEX: RegExp = /^\d{1,5}$/;
+
 export default class Hostname extends DatabaseProperty {
   private _route: string = "";
   public get hostname(): string {
@@ -31,13 +52,80 @@ export default class Hostname extends DatabaseProperty {
     }
   }
 
+  /*
+   * True when the value is a usable authority: an optional "userinfo@"
+   * prefix, a host (DNS name, IPv4, or IPv6 literal) and an optional ":port".
+   *
+   * The old check was a character allowlist that permitted "/", "?", "#" and
+   * "@" anywhere, which made "169.254.169.254/latest/meta-data/#" a valid
+   * Hostname. Anything that stores a Hostname and later interpolates it into
+   * a URL therefore inherited full control of the host, port and path of the
+   * resulting request. Structure, not a charset, is what rules that out.
+   *
+   * Userinfo is still accepted because "https://user:token@host/path" is a
+   * real thing customers put in webhook URLs, and those values are already in
+   * the database — rejecting them here would fail on read, not just on write.
+   * Callers that need the bare host must not split this string themselves;
+   * SSRFProtection.getBareHostname exists for that.
+   */
   public static isValid(value: string): boolean {
-    const re: RegExp = /^[a-zA-Z-\d!#$&'*+,/:;=?@[\].]*$/;
-    const isValid: boolean = re.test(value);
-    if (!isValid) {
+    const authorityWithUserInfo: string = value.trim();
+
+    /*
+     * 253 for a DNS name, plus room for ":65535" and a userinfo prefix.
+     * A bound here also keeps the label regex from being handed something
+     * pathological.
+     */
+    if (!authorityWithUserInfo || authorityWithUserInfo.length > 512) {
+      return false;
+    }
+
+    /*
+     * Split on the LAST "@": userinfo may itself contain "@" percent-encoded
+     * or not, and everything after the final one is the authority.
+     */
+    const atIndex: number = authorityWithUserInfo.lastIndexOf("@");
+
+    if (atIndex !== -1) {
+      const userInfo: string = authorityWithUserInfo.substring(0, atIndex);
+      if (!USER_INFO_REGEX.test(userInfo)) {
+        return false;
+      }
+    }
+
+    const authority: string = authorityWithUserInfo.substring(atIndex + 1);
+
+    if (!authority) {
       return false;
     }
-    return true;
+
+    // Bracketed IPv6, with or without a port: "[::1]", "[::1]:8080".
+    const bracketedIpv6Match: RegExpMatchArray | null = authority.match(
+      /^\[([0-9a-fA-F:.]+)\](?::(\d{1,5}))?$/,
+    );
+    if (bracketedIpv6Match) {
+      return true;
+    }
+
+    /*
+     * Unbracketed IPv6 literal. Two or more colons cannot be a "host:port",
+     * so the colons must be part of the address itself.
+     */
+    if ((authority.match(/:/g) || []).length > 1) {
+      return IPV6_CHARS_REGEX.test(authority);
+    }
+
+    const colonIndex: number = authority.indexOf(":");
+    const host: string =
+      colonIndex === -1 ? authority : authority.substring(0, colonIndex);
+    const port: string =
+      colonIndex === -1 ? "" : authority.substring(colonIndex + 1);
+
+    if (colonIndex !== -1 && !PORT_REGEX.test(port)) {
+      return false;
+    }
+
+    return HOST_REGEX.test(host);
   }
 
   public constructor(hostname: string, port?: Port | string | number) {

package/Types/API/URL.ts

@@ -131,37 +131,55 @@ export default class URL extends DatabaseProperty {
   public static fromString(url: string): URL {
     let protocol: Protocol = Protocol.HTTPS;
 
-    if (url.startsWith("https://")) {
-      protocol = Protocol.HTTPS;
-      url = url.replace("https://", "");
-    }
-
-    if (url.startsWith("http://")) {
-      protocol = Protocol.HTTP;
-      url = url.replace("http://", "");
-    }
-
-    if (url.startsWith("wss://")) {
-      protocol = Protocol.WSS;
-      url = url.replace("wss://", "");
+    /*
+     * Schemes are case-insensitive (RFC 3986), so match on a lower-cased
+     * copy and strip by length. Matching the literal prefix left "HTTPS://"
+     * in place, which then read as an authority of "HTTPS:".
+     *
+     * Longest-first: "https://" has to be tested before "http://", and only
+     * the first match is stripped.
+     */
+    const schemePrefixes: Array<[string, Protocol]> = [
+      ["https://", Protocol.HTTPS],
+      ["http://", Protocol.HTTP],
+      ["wss://", Protocol.WSS],
+      ["ws://", Protocol.WS],
+      ["mongodb://", Protocol.MONGO_DB],
+      ["mailto:", Protocol.MAIL],
+    ];
+
+    const lowerCasedUrl: string = url.toLowerCase();
+
+    for (const [prefix, prefixProtocol] of schemePrefixes) {
+      if (lowerCasedUrl.startsWith(prefix)) {
+        protocol = prefixProtocol;
+        url = url.substring(prefix.length);
+        break;
+      }
     }
 
-    if (url.startsWith("ws://")) {
-      protocol = Protocol.WS;
-      url = url.replace("ws://", "");
-    }
+    if (protocol === Protocol.MAIL) {
+      /*
+       * Hand the bare address to the constructor so it is recognised as an
+       * Email. Routing it through Hostname instead would ask a host validator
+       * to accept an email address — and "?subject=..." along with it.
+       */
+      const address: string = url.split("?")[0] || "";
+      const mailQueryString: string = url.split("?")[1] || "";
 
-    if (url.startsWith("mongodb://")) {
-      protocol = Protocol.MONGO_DB;
-      url = url.replace("mongodb://", "");
+      return new URL(protocol, address, undefined, mailQueryString);
     }
 
-    if (url.startsWith("mailto:")) {
-      protocol = Protocol.MAIL;
-      url = url.replace("mailto:", "");
-    }
+    /*
+     * The authority ends at the first "/", "?" or "#". Splitting on "/" alone
+     * left the query and fragment glued to the host for URLs with no path
+     * ("https://host?token=x" parsed to a host of "host?token=x"), which both
+     * round-tripped wrong and handed anything that later interpolated the
+     * host a way to smuggle a path.
+     */
+    const authority: string = (url.split("/")[0] || "").split(/[?#]/)[0] || "";
 
-    const hostname: Hostname = new Hostname(url.split("/")[0] || "");
+    const hostname: Hostname = new Hostname(authority);
 
     let route: Route | 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/Billing/BalanceAdjustmentType.ts

@@ -0,0 +1,14 @@
+/*
+ * How a manual balance adjustment is applied. Add and Deduct are relative and
+ * land as a single atomic SQL delta, so they cannot lose a usage charge that
+ * is being written at the same moment. Set is absolute - last writer wins -
+ * and is only there for the case where staff need the balance to read a
+ * specific number regardless of what it holds now.
+ */
+enum BalanceAdjustmentType {
+  Add = "Add",
+  Deduct = "Deduct",
+  Set = "Set",
+}
+
+export default BalanceAdjustmentType;

package/Types/Billing/ProjectBalanceType.ts

@@ -0,0 +1,13 @@
+/*
+ * The prepaid balances a project carries. Each one maps to its own column on
+ * the project and is drawn down by a different kind of usage, so they are
+ * topped up and corrected independently.
+ */
+enum ProjectBalanceType {
+  // Drawn down by SMS, voice calls, WhatsApp messages and incoming numbers.
+  SmsOrCall = "SmsOrCall",
+  // Drawn down by LLM spend - AI agents, investigations and code fixes.
+  AI = "AI",
+}
+
+export default ProjectBalanceType;

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;
+  };
+}

package/Types/DataSource/DataSourceLimits.ts

@@ -0,0 +1,62 @@
+/*
+ * Hard resource bounds applied to every external Data Source query,
+ * regardless of connector. These protect the OneUptime API server (memory,
+ * event loop) and the customer's target system from runaway dashboard
+ * queries — a dashboard with 20 widgets refreshing every minute multiplies
+ * whatever a single query costs.
+ */
+
+// Upper bound on wall-clock time for one connection attempt.
+export const DATA_SOURCE_CONNECT_TIMEOUT_IN_MS: number = 10 * 1000;
+
+// Upper bound on wall-clock time for one query execution.
+export const DATA_SOURCE_QUERY_TIMEOUT_IN_MS: number = 30 * 1000;
+
+/*
+ * Row cap for time-series results. 11k points ≈ 7.5 days at 1-minute
+ * resolution for a single series — beyond that the chart cannot render the
+ * detail anyway. Connectors fetch cap+1 to detect truncation.
+ */
+export const DATA_SOURCE_MAX_TIME_SERIES_ROWS: number = 11000;
+
+// Row cap for tabular results — dashboards render tables, not exports.
+export const DATA_SOURCE_MAX_TABLE_ROWS: number = 1000;
+
+// Cap on distinct series one query may return before truncation.
+export const DATA_SOURCE_MAX_SERIES: number = 100;
+
+/*
+ * Cap on the raw HTTP response body accepted from HTTP-based sources
+ * (Prometheus/Loki/Elasticsearch/REST), before parsing. Prevents a
+ * misconfigured endpoint from ballooning API-server memory.
+ */
+export const DATA_SOURCE_MAX_RESPONSE_SIZE_IN_BYTES: number = 20 * 1024 * 1024;
+
+/*
+ * Default step for range queries when the client does not send one:
+ * aim for ~250 buckets across the selected window, clamped to sane bounds.
+ */
+export const DATA_SOURCE_TARGET_BUCKETS: number = 250;
+export const DATA_SOURCE_MIN_STEP_IN_SECONDS: number = 10;
+export const DATA_SOURCE_MAX_STEP_IN_SECONDS: number = 24 * 60 * 60;
+
+export class DataSourceLimitsUtil {
+  /*
+   * Derive a range-query step (seconds) from a time window: ~TARGET_BUCKETS
+   * buckets, clamped. Used server-side when the widget doesn't specify one
+   * so Prometheus/Loki range queries stay bounded no matter the window.
+   */
+  public static getStepInSeconds(startDate: Date, endDate: Date): number {
+    const rangeSeconds: number = Math.max(
+      Math.floor((endDate.getTime() - startDate.getTime()) / 1000),
+      1,
+    );
+    const rawStep: number = Math.ceil(
+      rangeSeconds / DATA_SOURCE_TARGET_BUCKETS,
+    );
+    return Math.min(
+      Math.max(rawStep, DATA_SOURCE_MIN_STEP_IN_SECONDS),
+      DATA_SOURCE_MAX_STEP_IN_SECONDS,
+    );
+  }
+}

package/Types/DataSource/DataSourceQueryConfig.ts

@@ -0,0 +1,41 @@
+/*
+ * A widget-stored binding to an external Data Source. Persisted inside
+ * `Dashboard.dashboardViewConfig` on chart/value/gauge/table components, so
+ * every field must survive JSON round-trips (plain strings/numbers only —
+ * dataSourceId is a string, not an ObjectID instance).
+ */
+export default interface DataSourceQueryConfig {
+  /*
+   * Stable identity for this query within the widget (mirrors
+   * MetricQueryConfigData.id) so editor UI state survives reorders.
+   */
+  id?: string | undefined;
+
+  // _id of the project's DataSource record this query runs against.
+  dataSourceId: string;
+
+  /*
+   * Query text in the source's native language: PromQL, SQL, LogQL,
+   * Elasticsearch Query DSL JSON, or the REST request descriptor JSON.
+   * SQL queries may use the $__startTime / $__endTime / $__startTimeMs /
+   * $__endTimeMs / $__rangeSeconds macros, replaced server-side with the
+   * dashboard's current time window.
+   */
+  query: string;
+
+  /*
+   * Optional legend template for chart series. Supports {{label}}
+   * placeholders resolved against each series' group keys (e.g. Prometheus
+   * label values). Absent ⇒ series are named from their group keys.
+   */
+  legend?: string | undefined;
+}
+
+/*
+ * What shape of result the widget wants back from the query endpoint.
+ * Charts/values/gauges consume time series; the table widget consumes rows.
+ */
+export enum DataSourceResultKind {
+  TimeSeries = "TimeSeries",
+  Table = "Table",
+}

package/Types/DataSource/DataSourceTableResult.ts

@@ -0,0 +1,38 @@
+import { JSONValue } from "../JSON";
+
+/*
+ * Column type hints let table widgets right-align numbers and format dates
+ * without sniffing every row. Connectors set these from driver metadata when
+ * available and fall back to inspecting the first row.
+ */
+export enum DataSourceTableColumnType {
+  Text = "Text",
+  Number = "Number",
+  Date = "Date",
+  Boolean = "Boolean",
+  Json = "Json",
+}
+
+export interface DataSourceTableColumn {
+  // Row-object key this column reads from.
+  key: string;
+  // Human-facing header; defaults to the key.
+  title: string;
+  type: DataSourceTableColumnType;
+}
+
+/*
+ * Normalized tabular result every connector's queryTable returns. Rows are
+ * plain JSON objects keyed by column key so the payload serializes straight
+ * through the API to the table widget.
+ */
+export default interface DataSourceTableResult {
+  columns: Array<DataSourceTableColumn>;
+  rows: Array<{ [key: string]: JSONValue }>;
+  /*
+   * True when the connector clamped the result at the row cap — the widget
+   * shows a truncation banner so users don't mistake a clamp for the full
+   * result set.
+   */
+  truncated?: boolean | undefined;
+}