@oneuptime/common 13.0.5 → 13.0.7

package/Types/Database/EnableAuditLog.ts

@@ -9,10 +9,32 @@ export default (
   },
 ) => {
   return (ctr: GenericFunction) => {
-    ctr.prototype.enableAuditLogOn = {
+    const config: EnableAuditLogOn = {
       create: enableAuditLogOn.create ?? true,
       update: enableAuditLogOn.update ?? true,
       delete: enableAuditLogOn.delete ?? true,
     };
+
+    /*
+     * Only the keys copied here reach the prototype, so every new option has
+     * to be added below or it is silently dropped. The optional ones are set
+     * only when configured: a model that uses none of them keeps exactly the
+     * three-flag shape it always had. They are copied rather than aliased so
+     * nothing can rewrite a model's audit configuration through the object it
+     * was declared with.
+     */
+    if (enableAuditLogOn.rootResource) {
+      config.rootResource = { ...enableAuditLogOn.rootResource };
+    }
+
+    if (enableAuditLogOn.ignoreColumns) {
+      config.ignoreColumns = [...enableAuditLogOn.ignoreColumns];
+    }
+
+    if (enableAuditLogOn.resourceNameRelation) {
+      config.resourceNameRelation = enableAuditLogOn.resourceNameRelation;
+    }
+
+    ctr.prototype.enableAuditLogOn = config;
   };
 };

package/Types/Database/UniqueColumnsTogether.ts

@@ -0,0 +1,55 @@
+import GenericFunction from "../GenericFunction";
+
+/*
+ * Declares that no two rows of a model may share the same values across
+ * `columnNames`. DatabaseService.create looks for an existing row with those
+ * values before inserting and, if there is one, rejects the insert with
+ * `errorMessage` instead of writing a second row.
+ *
+ * WHY THIS EXISTS
+ *
+ * Join rows such as <Resource>OwnerTeam / <Resource>OwnerUser have side effects
+ * on create: each new row writes a feed item and notifies the owner. The
+ * dashboard hides owners that are already attached, but the REST API,
+ * workflows and internal callers all insert directly, so a duplicate row used
+ * to mean a duplicate notification (issue #3394).
+ *
+ * This is the application half of the guarantee. Declare the same columns in
+ * an `@Index([...], { unique: true })` on the entity as well: a check before an
+ * insert cannot stop two concurrent writers, and only the database can.
+ * PostgresErrorTranslator.isUniqueViolation() recognises the rejection from
+ * either layer, so a caller that wants "already there" to be a no-op needs a
+ * single check.
+ *
+ * Only creates are checked. Rows are expected to be re-keyed rarely, if ever,
+ * and the unique index covers updates.
+ */
+
+export interface UniqueColumnsTogetherMetadata {
+  columnNames: Array<string>;
+  errorMessage: string;
+}
+
+export default (columnNames: Array<string>, errorMessage: string) => {
+  return (ctr: GenericFunction) => {
+    /*
+     * Stackable. Read only this class's own list: a subclass must not
+     * append to the list its parent keeps on the parent's prototype.
+     */
+    const existing: Array<UniqueColumnsTogetherMetadata> =
+      Object.prototype.hasOwnProperty.call(
+        ctr.prototype,
+        "uniqueColumnsTogether",
+      )
+        ? ctr.prototype.uniqueColumnsTogether
+        : [];
+
+    ctr.prototype.uniqueColumnsTogether = [
+      ...existing,
+      {
+        columnNames: [...columnNames],
+        errorMessage: errorMessage,
+      },
+    ];
+  };
+};

package/Types/Email/EmailTemplateType.ts

@@ -18,10 +18,12 @@ enum EmailTemplateType {
   EmailChanged = "EmailChanged.hbs",
   SubscribedToStatusPage = "SubscribedToStatusPage.hbs",
   SubscriberAnnouncementCreated = "SubscriberAnnouncementCreated.hbs",
+  SubscriberAnnouncementUpdated = "SubscriberAnnouncementUpdated.hbs",
   SubscriberIncidentCreated = "SubscriberIncidentCreated.hbs",
   SubscriberIncidentPostmortemCreated = "SubscriberIncidentPostmortemCreated.hbs",
   StatusPageSubscriberReport = "StatusPageSubscriberReport.hbs",
   SubscriberIncidentNoteCreated = "SubscriberIncidentNoteCreated.hbs",
+  SubscriberIncidentNoteUpdated = "SubscriberIncidentNoteUpdated.hbs",
   SubscriberIncidentStateChanged = "SubscriberIncidentStateChanged.hbs",
   SubscriberScheduledMaintenanceEventCreated = "SubscriberScheduledMaintenanceEventCreated.hbs",
   ManageExistingStatusPageSubscriberSubscription = "ManageExistingStatusPageSubscriberSubscription.hbs",
@@ -30,6 +32,7 @@ enum EmailTemplateType {
   StatusPagePasswordChanged = "StatusPagePasswordChanged.hbs",
   StatusPageWelcomeEmail = "StatusPageWelcomeEmail.hbs",
   SubscriberScheduledMaintenanceEventNoteCreated = "SubscriberScheduledMaintenanceEventNoteCreated.hbs",
+  SubscriberScheduledMaintenanceEventNoteUpdated = "SubscriberScheduledMaintenanceEventNoteUpdated.hbs",
   SMTPTest = "SMTPTest.hbs",
   MonitorOwnerAdded = "MonitorOwnerAdded.hbs",
   MonitorOwnerResourceCreated = "MonitorOwnerResourceCreated.hbs",
@@ -66,6 +69,7 @@ enum EmailTemplateType {
   SubscriberEpisodeCreated = "SubscriberEpisodeCreated.hbs",
   SubscriberEpisodeStateChanged = "SubscriberEpisodeStateChanged.hbs",
   SubscriberEpisodeNoteCreated = "SubscriberEpisodeNoteCreated.hbs",
+  SubscriberEpisodeNoteUpdated = "SubscriberEpisodeNoteUpdated.hbs",
 
   ScheduledMaintenanceOwnerNotePosted = "ScheduledMaintenanceOwnerNotePosted.hbs",
   ScheduledMaintenanceOwnerAdded = "ScheduledMaintenanceOwnerAdded.hbs",

package/Types/Metrics/MetricQueryConfigData.ts

@@ -1,6 +1,7 @@
 import AggregatedModel from "../BaseDatabase/AggregatedModel";
 import MetricAliasData from "./MetricAliasData";
 import MetricQueryData from "./MetricQueryData";
+import MetricsQuery from "./MetricsQuery";
 
 export enum MetricChartType {
   LINE = "line",
@@ -25,6 +26,13 @@ export default interface MetricQueryConfigData {
   id?: string | undefined;
   metricAliasData?: MetricAliasData | undefined;
   metricQueryData: MetricQueryData;
+  /**
+   * Resource identity for event markers when the metric list is scoped by
+   * entity membership instead of telemetry attributes (e.g. RUM, Inventory).
+   * Kept separate from the metric filter: these identifiers are not stored
+   * in its attributes map. An explicit empty scope suppresses event markers.
+   */
+  eventScope?: MetricsQuery["attributes"] | undefined;
   getSeries?: ((data: AggregatedModel) => ChartSeries) | undefined;
   chartType?: MetricChartType | undefined;
   yAxisValueFormatter?: ((value: number) => string) | undefined;

package/Types/Monitor/CriteriaFilter.ts

@@ -407,6 +407,60 @@ export class CriteriaFilterUtil {
     return true;
   }
 
+  /**
+   * Whether this CheckOn reads a series whose samples are 1 (true) or
+   * 0 (false), such as the online series every probe writes.
+   *
+   * Such a series can only be judged one sample at a time. Its average, sum,
+   * maximum or minimum is a number (0.6, say), and the True / False
+   * comparators never match a number, so EvaluateOverTime turns its samples
+   * and its Treat As Zero substitute into booleans instead.
+   *
+   * Keep this the only list. The dashboard dropdown and the server evaluator
+   * both read it; separate copies drifted before, which left Database Is
+   * Online samples as raw numbers and aggregates on offer for DNS, SNMP and
+   * External Status Page.
+   */
+  public static isBooleanSeries(checkOn: CheckOn | undefined): boolean {
+    return (
+      checkOn === CheckOn.IsOnline ||
+      // No series records this one yet, but it is a true/false value too.
+      checkOn === CheckOn.IsRequestTimeout ||
+      checkOn === CheckOn.DnsIsOnline ||
+      checkOn === CheckOn.SnmpIsOnline ||
+      checkOn === CheckOn.ExternalStatusPageIsOnline ||
+      checkOn === CheckOn.DatabaseIsOnline
+    );
+  }
+
+  /**
+   * The evaluation type a filter is actually judged with.
+   *
+   * This only differs from the saved type on a boolean series that was saved
+   * with Average, Sum, Maximum Value or Minimum Value. The dashboard no
+   * longer offers those there, but older filters, and filters sent through
+   * the API or Terraform, can still carry them. They are judged as All
+   * Values: the stricter of the two choices, so the filter fires only when
+   * the whole window agrees rather than off a single sample.
+   */
+  public static getEffectiveEvaluateOverTimeType(
+    criteriaFilter: CriteriaFilter | undefined,
+  ): EvaluateOverTimeType | undefined {
+    const evaluateOverTimeType: EvaluateOverTimeType | undefined =
+      criteriaFilter?.evaluateOverTimeOptions?.evaluateOverTimeType;
+
+    if (
+      !evaluateOverTimeType ||
+      evaluateOverTimeType === EvaluateOverTimeType.AllValues ||
+      evaluateOverTimeType === EvaluateOverTimeType.AnyValue ||
+      !CriteriaFilterUtil.isBooleanSeries(criteriaFilter?.checkOn)
+    ) {
+      return evaluateOverTimeType;
+    }
+
+    return EvaluateOverTimeType.AllValues;
+  }
+
   public static getEvaluateOverTimeTypeByCriteriaFilter(
     criteriaFilter: CriteriaFilter | undefined,
   ): Array<EvaluateOverTimeType> {
@@ -414,14 +468,7 @@ export class CriteriaFilterUtil {
       return [];
     }
 
-    /*
-     * Boolean series. Averaging or summing an up/down series is meaningless,
-     * so these offer only the two set-shaped choices.
-     */
-    if (
-      criteriaFilter.checkOn === CheckOn.IsOnline ||
-      criteriaFilter.checkOn === CheckOn.DatabaseIsOnline
-    ) {
+    if (CriteriaFilterUtil.isBooleanSeries(criteriaFilter.checkOn)) {
       return [EvaluateOverTimeType.AllValues, EvaluateOverTimeType.AnyValue];
     }
 

package/Types/Monitor/MonitorStep.ts

@@ -92,6 +92,8 @@ import MonitorTemplateSyncFieldUtil from "./MonitorTemplateSyncField";
 /*
  * Caps and defaults for per-step request timeout and retry settings.
  * Users may lower these via the UI; values higher than the cap are clamped.
+ * The retry values count retries AFTER the first attempt, so 0 means exactly
+ * one attempt and 3 means up to four.
  */
 export const MAX_MONITOR_REQUEST_TIMEOUT_IN_MS: number = 60000; // 60 seconds
 export const DEFAULT_MONITOR_REQUEST_TIMEOUT_IN_MS: number = 60000;
@@ -168,8 +170,9 @@ export interface MonitorStepType {
   requestTimeoutInMs?: number | undefined;
 
   /*
-   * Per-step retry count for probe-based monitors when a check fails.
-   * Defaults to and is capped at 3.
+   * Per-step retry count for probe-based monitors when a check fails. It
+   * counts retries after the first attempt: 0 means one attempt, 2 means up
+   * to three. Defaults to and is capped at 3 on the probe.
    */
   retryCount?: number | undefined;
 

package/Types/Monitor/MonitorStepDnsMonitor.ts

@@ -1,5 +1,6 @@
 import { JSONObject } from "../JSON";
 import DnsRecordType from "./DnsMonitor/DnsRecordType";
+import { parseMonitorStepRetries } from "./MonitorStepRetries";
 
 export default interface MonitorStepDnsMonitor {
   queryName: string;
@@ -29,7 +30,8 @@ export class MonitorStepDnsMonitorUtil {
       hostname: (json["hostname"] as string) || undefined,
       port: (json["port"] as number) || 53,
       timeout: (json["timeout"] as number) || 5000,
-      retries: (json["retries"] as number) || 3,
+      // 0 retries is a real answer and must survive the round-trip.
+      retries: parseMonitorStepRetries(json["retries"], 3),
     };
   }
 

package/Types/Monitor/MonitorStepDnssecMonitor.ts

@@ -1,4 +1,5 @@
 import { JSONObject } from "../JSON";
+import { parseMonitorStepRetries } from "./MonitorStepRetries";
 
 export default interface MonitorStepDnssecMonitor {
   domainName: string;
@@ -42,7 +43,8 @@ export class MonitorStepDnssecMonitorUtil {
         (json["signatureExpiryWarningDays"] as number) ||
         defaults.signatureExpiryWarningDays,
       timeout: (json["timeout"] as number) || defaults.timeout,
-      retries: (json["retries"] as number) || defaults.retries,
+      // 0 retries is a real answer and must survive the round-trip.
+      retries: parseMonitorStepRetries(json["retries"], defaults.retries),
     };
   }
 

package/Types/Monitor/MonitorStepDomainMonitor.ts

@@ -1,5 +1,6 @@
 import { JSONObject } from "../JSON";
 import DomainLookupMethod from "./DomainMonitor/DomainLookupMethod";
+import { parseMonitorStepRetries } from "./MonitorStepRetries";
 
 export default interface MonitorStepDomainMonitor {
   domainName: string;
@@ -29,7 +30,8 @@ export class MonitorStepDomainMonitorUtil {
         json["lookupMethod"],
       ),
       timeout: (json["timeout"] as number) || 10000,
-      retries: (json["retries"] as number) || 3,
+      // 0 retries is a real answer and must survive the round-trip.
+      retries: parseMonitorStepRetries(json["retries"], 3),
     };
   }
 

package/Types/Monitor/MonitorStepExternalStatusPageMonitor.ts

@@ -1,5 +1,6 @@
 import { JSONObject } from "../JSON";
 import ExternalStatusPageProviderType from "./ExternalStatusPageProviderType";
+import { parseMonitorStepRetries } from "./MonitorStepRetries";
 
 export default interface MonitorStepExternalStatusPageMonitor {
   statusPageUrl: string;
@@ -33,7 +34,8 @@ export class MonitorStepExternalStatusPageMonitorUtil {
       componentGroupName: (json["componentGroupName"] as string) || undefined,
       componentName: (json["componentName"] as string) || undefined,
       timeout: (json["timeout"] as number) || 10000,
-      retries: (json["retries"] as number) || 3,
+      // 0 retries is a real answer and must survive the round-trip.
+      retries: parseMonitorStepRetries(json["retries"], 3),
     };
   }
 

package/Types/Monitor/MonitorStepRetries.ts

@@ -0,0 +1,59 @@
+/*
+ * One rule for reading the per-type "Retries" value that DNS, DNSSEC, Domain,
+ * External Status Page and SNMP monitor steps keep in their own config.
+ *
+ * Retries count attempts AFTER the first one: 0 runs the check once and does
+ * not retry, 2 runs it up to three times. That makes 0 a real answer, not an
+ * absent one. Both the JSON parsers and the dashboard forms used to read the
+ * value with `||`, which quietly turned a saved or typed 0 back into 3 — so
+ * "no retries" could not be expressed at all.
+ *
+ * These helpers keep 0 and fall back only for values that are not a usable
+ * count, which is how MonitorRetry.resolveRetries resolves the same value on
+ * the probe.
+ */
+
+/*
+ * Reads a stored retries value out of a monitor step's JSON. Missing, null,
+ * non-numeric, NaN and negative values are not counts a user could have meant,
+ * so they take the type's default; everything else is kept, 0 included.
+ */
+export const parseMonitorStepRetries: (
+  value: unknown,
+  defaultRetries: number,
+) => number = (value: unknown, defaultRetries: number): number => {
+  /*
+   * Older rows (and Terraform or API callers) can carry the count as a string.
+   * `||` used to pass those straight through as a fake number, so read them as
+   * the number they spell instead.
+   */
+  const parsed: unknown =
+    typeof value === "string" && value.trim().length > 0
+      ? Number(value.trim())
+      : value;
+
+  // Number.isFinite is false for NaN and for both infinities.
+  if (typeof parsed !== "number" || !Number.isFinite(parsed) || parsed < 0) {
+    return defaultRetries;
+  }
+
+  return Math.floor(parsed);
+};
+
+/*
+ * Reads what a user typed into a "Retries" number input. An empty or
+ * non-numeric box means "I did not choose", so it takes the type's default; a
+ * negative number is read as no retries rather than thrown away.
+ */
+export const parseMonitorStepRetriesInput: (
+  value: string,
+  defaultRetries: number,
+) => number = (value: string, defaultRetries: number): number => {
+  const parsed: number = parseInt(value, 10);
+
+  if (isNaN(parsed)) {
+    return defaultRetries;
+  }
+
+  return parsed < 0 ? 0 : parsed;
+};

package/Types/Monitor/MonitorStepSnmpMonitor.ts

@@ -5,6 +5,7 @@ import SnmpVersion from "./SnmpMonitor/SnmpVersion";
 import SnmpSecurityLevel from "./SnmpMonitor/SnmpSecurityLevel";
 import SnmpAuthProtocol from "./SnmpMonitor/SnmpAuthProtocol";
 import SnmpPrivProtocol from "./SnmpMonitor/SnmpPrivProtocol";
+import { parseMonitorStepRetries } from "./MonitorStepRetries";
 
 export default interface MonitorStepSnmpMonitor {
   snmpVersion: SnmpVersion;
@@ -14,7 +15,12 @@ export default interface MonitorStepSnmpMonitor {
   snmpV3Auth?: SnmpV3Auth | undefined;
   oids: Array<SnmpOid>;
   timeout: number;
-  retries: number;
+  /*
+   * Retries after the first attempt (0 = query once). Absent only on configs
+   * the server builds for Network Devices, which have no retry setting of
+   * their own: the probe then applies its built-in default.
+   */
+  retries?: number | undefined;
   /*
    * When true, the probe walks the IF-MIB interface tables on every check
    * and reports per-interface status, bandwidth, and error metrics.
@@ -51,7 +57,8 @@ export class MonitorStepSnmpMonitorUtil {
         (json["oids"] as Array<JSONObject>) || [],
       ),
       timeout: (json["timeout"] as number) || 5000,
-      retries: (json["retries"] as number) || 3,
+      // 0 retries is a real answer and must survive the round-trip.
+      retries: parseMonitorStepRetries(json["retries"], 3),
       monitorInterfaces: Boolean(json["monitorInterfaces"]),
     };
   }

package/Types/NetworkDevice/NetworkDeviceDiagnosticResult.ts

@@ -0,0 +1,104 @@
+import NetworkPathTrace from "../Monitor/NetworkMonitor/NetworkPathTrace";
+import PingMonitorResponse from "../Monitor/PingMonitor/PingMonitorResponse";
+import NetworkDeviceDiagnosticType from "./NetworkDeviceDiagnosticType";
+
+/*
+ * The shapes shared by the three parties to an on-demand device diagnostic
+ * (OneUptime issue #3745): the server that stores the request and hands it
+ * out, the probe that runs it, and the dashboard that renders the result.
+ *
+ * A diagnostic is a NetworkDeviceDiagnostic row. The dashboard creates one
+ * with a device and a type; the server fills in the hostname and the probe
+ * from the device; the probe's diagnostic job claims it, runs it, and posts
+ * the result; the dashboard polls the row until it settles.
+ */
+
+/*
+ * What a ping diagnostic produces. `pingResponse` reuses the Ping monitor's
+ * packet statistics (min/avg/max RTT, jitter, packet loss) so the vocabulary
+ * matches what the device's poll already charts. It is undefined when ping
+ * itself could not run (no binary, no ICMP privileges, an unusable host) —
+ * then `isOnline` is false and `failureCause` says why.
+ *
+ * A device that answered no echo is NOT a failed diagnostic: it is a
+ * completed one with isOnline false and, usually, a pingResponse showing
+ * 100% loss.
+ */
+export interface NetworkDeviceDiagnosticPingResult {
+  isOnline: boolean;
+  // Empty when the device answered.
+  failureCause: string;
+  pingResponse?: PingMonitorResponse | undefined;
+}
+
+/*
+ * What the probe-ingest list endpoint hands the probe for one claimed
+ * diagnostic — everything the probe needs to run it without another
+ * round trip. Plain strings: it crosses the wire as JSON.
+ */
+export interface NetworkDeviceDiagnosticJob {
+  id: string;
+  projectId: string;
+  networkDeviceId: string;
+  diagnosticType: NetworkDeviceDiagnosticType | string;
+  // The device's hostname or IP literal, copied from the device at create.
+  hostname: string;
+  /*
+   * Ping: the per-reply wait. Traceroute: the deadline for the whole
+   * trace. Always sent, so the probe never has to guess a default.
+   */
+  timeoutInMs: number;
+  // Ping only. Echo requests to send.
+  packetCount?: number | undefined;
+  // Traceroute only. Hop limit.
+  maxHops?: number | undefined;
+}
+
+/*
+ * What the probe posts back for one diagnostic. Exactly one of
+ * `pingResult` / `traceRouteResult` is set on a Completed report, matching
+ * the job's type; a Failed report carries neither and a statusMessage.
+ */
+export interface NetworkDeviceDiagnosticReport {
+  networkDeviceDiagnosticId: string;
+  // NetworkDeviceDiagnosticStatus.Completed or .Failed.
+  status: string;
+  statusMessage?: string | undefined;
+  pingResult?: NetworkDeviceDiagnosticPingResult | undefined;
+  traceRouteResult?: NetworkPathTrace | undefined;
+}
+
+/*
+ * Echo requests per ping diagnostic. Five, like a Ping monitor check: enough
+ * for loss and jitter to mean something, few enough to answer in seconds.
+ */
+export const NETWORK_DEVICE_DIAGNOSTIC_PING_PACKET_COUNT: number = 5;
+
+// Per-reply wait for a ping diagnostic; matches the device poll's default.
+export const NETWORK_DEVICE_DIAGNOSTIC_PING_TIMEOUT_IN_MS: number = 5000;
+
+// Whole-trace deadline for a traceroute diagnostic.
+export const NETWORK_DEVICE_DIAGNOSTIC_TRACEROUTE_TIMEOUT_IN_MS: number = 30000;
+
+export const NETWORK_DEVICE_DIAGNOSTIC_TRACEROUTE_MAX_HOPS: number = 30;
+
+/*
+ * A Pending diagnostic older than this is never claimed. Somebody asked for
+ * it from a screen they have since left — the dashboard gives up waiting
+ * long before this — so running it would spend the probe's time on an
+ * answer nobody reads. The row itself is pruned by the service's retention.
+ */
+export const NETWORK_DEVICE_DIAGNOSTIC_CLAIM_WINDOW_IN_MINUTES: number = 10;
+
+/*
+ * Diagnostics are transient: the answer matters for the minutes somebody is
+ * looking at it. Rows are hard-deleted after this many days, like
+ * MonitorTest rows.
+ */
+export const NETWORK_DEVICE_DIAGNOSTIC_RETENTION_IN_DAYS: number = 2;
+
+/*
+ * How many diagnostics one list request hands a probe. Diagnostics are
+ * interactive and rare; the cap only bounds a burst.
+ */
+export const NETWORK_DEVICE_DIAGNOSTIC_CLAIM_LIMIT: number = 20;

package/Types/NetworkDevice/NetworkDeviceDiagnosticStatus.ts

@@ -0,0 +1,47 @@
+/*
+ * The lifecycle of one on-demand device diagnostic (ping / traceroute), as
+ * the strings its `status` column holds. Mirrors DiscoveryScanStatus: the
+ * column is a ShortText, and the same four words are read by the claim
+ * query, the probe's result report, and the dashboard's poll loop, so they
+ * live in one place.
+ *
+ * Values are NOT a TypeScript enum: they are persisted strings, and a plain
+ * object keeps them readable in a query, in jsonb and in a log line.
+ */
+export const NetworkDeviceDiagnosticStatus: {
+  Pending: string;
+  InProgress: string;
+  Completed: string;
+  Failed: string;
+} = {
+  // Created by the dashboard, waiting for the device's probe to claim it.
+  Pending: "Pending",
+  // Claimed by the probe and running right now.
+  InProgress: "In Progress",
+  // The probe reported a result. `pingResult` / `traceRouteResult` is set.
+  Completed: "Completed",
+  /*
+   * The probe could not run it (unsupported type, unusable hostname, an
+   * exception) — `statusMessage` says why. A device that simply did not
+   * answer is NOT a failure: that is a Completed ping with isOnline false.
+   */
+  Failed: "Failed",
+};
+
+/*
+ * The statuses after which nothing more will be written to the row. The
+ * dashboard stops polling on any of these.
+ */
+export const NETWORK_DEVICE_DIAGNOSTIC_SETTLED_STATUSES: Array<string> = [
+  NetworkDeviceDiagnosticStatus.Completed,
+  NetworkDeviceDiagnosticStatus.Failed,
+];
+
+export function isNetworkDeviceDiagnosticSettled(
+  status: string | undefined | null,
+): boolean {
+  return (
+    typeof status === "string" &&
+    NETWORK_DEVICE_DIAGNOSTIC_SETTLED_STATUSES.includes(status)
+  );
+}

package/Types/NetworkDevice/NetworkDeviceDiagnosticType.ts

@@ -0,0 +1,47 @@
+/*
+ * The kinds of on-demand connectivity check an operator can run against a
+ * registered Network Device from the topology map or the device page
+ * (OneUptime issue #3745).
+ *
+ * Stored as the `diagnosticType` column of NetworkDeviceDiagnostic and sent
+ * to the probe verbatim, so the values are the persisted strings and must
+ * not be renamed.
+ */
+enum NetworkDeviceDiagnosticType {
+  // ICMP echo: reachability, round-trip time, jitter and packet loss.
+  Ping = "Ping",
+  // Hop-by-hop path from the probe to the device.
+  Traceroute = "Traceroute",
+}
+
+export default NetworkDeviceDiagnosticType;
+
+export class NetworkDeviceDiagnosticTypeUtil {
+  public static getAllTypes(): Array<NetworkDeviceDiagnosticType> {
+    return [
+      NetworkDeviceDiagnosticType.Ping,
+      NetworkDeviceDiagnosticType.Traceroute,
+    ];
+  }
+
+  /*
+   * The enum member for a stored or posted string, or undefined when it is
+   * not one. Case-sensitive on purpose: the column holds the enum value
+   * exactly, and the probe branches on it.
+   */
+  public static parse(value: unknown): NetworkDeviceDiagnosticType | undefined {
+    if (typeof value !== "string") {
+      return undefined;
+    }
+
+    return NetworkDeviceDiagnosticTypeUtil.getAllTypes().find(
+      (type: NetworkDeviceDiagnosticType): boolean => {
+        return type === value;
+      },
+    );
+  }
+
+  public static isValid(value: unknown): boolean {
+    return NetworkDeviceDiagnosticTypeUtil.parse(value) !== undefined;
+  }
+}

package/Types/NetworkDevice/NetworkDevicePingMetricNames.ts

@@ -0,0 +1,20 @@
+/*
+ * Ping round-trip time of a network device, in ms.
+ *
+ * Ping monitors write their RTT into MonitorMetricType.ResponseTime, but on
+ * a network device that series is the SNMP walk's time (and is absent on a
+ * ping-only poll), so the RTT needs a series of its own. It sits in the
+ * `oneuptime.monitor.ping.*` namespace beside PacketLossPercent and Jitter,
+ * which ARE reused from the Ping monitor. MonitorMetricType has no member
+ * for it yet; this constant should graduate into that enum (and the device
+ * metric catalog) rather than be duplicated.
+ *
+ * Lives under Common/Types rather than next to the writer in
+ * Common/Server/Utils because the dashboard reads the same series back (the
+ * device drawer's latency trend) and browser code must not import server
+ * modules — NetworkDeviceMetricUtil pulls in the telemetry SDK and the
+ * metric service at load. The server util re-exports it under the same
+ * name, so its existing importers do not move.
+ */
+export const NETWORK_DEVICE_PING_ROUND_TRIP_TIME_METRIC_NAME: string =
+  "oneuptime.monitor.ping.round.trip.time";