@oneuptime/common 14.0.1 → 14.0.2

package/Types/Monitor/DatabaseMonitor/SqlServerPlatform.ts

@@ -0,0 +1,117 @@
+/*
+ * Which Microsoft SQL Server platform a Database Health monitor is talking
+ * to, and the grant each one needs.
+ *
+ * SQL Server, Azure SQL Managed Instance and Azure SQL Database all speak the
+ * same protocol and answer the same DMV queries, but they do not share a
+ * permission model. On SQL Server and Managed Instance the DMVs are gated by
+ * the SERVER-level VIEW SERVER STATE. Azure SQL Database has no server-level
+ * permissions a customer can grant - `GRANT VIEW SERVER STATE` fails there -
+ * so the same DMVs are gated by the DATABASE-level VIEW DATABASE STATE
+ * instead. Telling an Azure SQL Database operator to run the SQL Server grant
+ * sends them to a statement that errors (issue #3913).
+ *
+ * The probe reads SERVERPROPERTY('EngineEdition') to decide, rather than
+ * the version: Azure SQL Database reports ProductVersion 12.0.2000.8
+ * whatever it actually runs, which reads as SQL Server 2014.
+ *
+ * The grant strings live here, not in the probe, so the probe's per-group
+ * remediation, the monitor form's setup block and the documentation can be
+ * checked against one another instead of drifting apart.
+ */
+
+/*
+ * SERVERPROPERTY('EngineEdition'), as documented by Microsoft. Only the
+ * values the monitor behaves differently for are named; every other value
+ * is treated as SQL Server.
+ */
+export enum SqlServerEngineEdition {
+  AzureSqlDatabase = 5,
+  AzureSqlManagedInstance = 8,
+  AzureSqlEdge = 9,
+}
+
+/*
+ * SQL Server and Azure SQL Managed Instance. VIEW SERVER STATE covers every
+ * DMV the monitor reads on every supported version; on SQL Server 2022 and
+ * later the narrower VIEW SERVER PERFORMANCE STATE is enough (verified on
+ * 2022 with each grant alone). A server-scope grant only runs while the
+ * current database is master: anywhere else it fails with Msg 4621
+ * (verified on 2017 and 2022).
+ */
+export const SQL_SERVER_MONITORING_GRANT: string =
+  "GRANT VIEW SERVER STATE TO [<monitoring_login>];";
+
+/*
+ * Azure SQL Database, run in the MONITORED database (it cannot be granted in
+ * master). Microsoft documents it as enough for every DMV the monitor reads
+ * on vCore and on DTU S2 and above.
+ */
+export const AZURE_SQL_DATABASE_MONITORING_GRANT: string =
+  "GRANT VIEW DATABASE STATE TO [<monitoring_user>];";
+
+/*
+ * Azure SQL Database on Basic, S0 and S1, and any database in an elastic
+ * pool: there the DMVs admit only the server admin, the Microsoft Entra
+ * admin or a member of this server role, whatever the database grants say
+ * (the Permissions section of sys.dm_os_sys_info, sys.dm_os_waiting_tasks,
+ * sys.dm_os_performance_counters, sys.dm_tran_* and sys.dm_db_*_space_usage).
+ * Run in master, by the server admin, for a server LOGIN - the role reaches
+ * each database where that login has a user. It is also the grant that
+ * works on every tier, which is why it is the fallback when the database
+ * grant turns out not to be enough.
+ */
+export const AZURE_SQL_DATABASE_SERVER_STATE_READER_GRANT: string =
+  "ALTER SERVER ROLE ##MS_ServerStateReader## ADD MEMBER [<monitoring_login>];";
+
+/*
+ * What the probe attaches to a SQL Server permission failure. The operator
+ * reading it is usually connected to the monitored database, where the
+ * statement fails - hence where to run it.
+ */
+export const SQL_SERVER_MONITORING_REMEDIATION: string = `${SQL_SERVER_MONITORING_GRANT} -- run in master`;
+
+/*
+ * What the probe attaches to the same failure on Azure SQL Database: two
+ * statements for two databases, one per line, each under a comment line
+ * saying where it runs. Not one line with the fallback trailing in a `--`
+ * comment - the summary renders a remediation as copyable code, and a
+ * statement inside a comment is one that never runs when copied. Every line
+ * is either a comment or a complete statement, so the block is valid SQL as
+ * a whole; the view shows each statement separately.
+ */
+export const AZURE_SQL_DATABASE_MONITORING_REMEDIATION: string = [
+  "-- In the monitored database:",
+  AZURE_SQL_DATABASE_MONITORING_GRANT,
+  "-- Basic, S0, S1, elastic pools, or if that is not enough: in master, for the login:",
+  AZURE_SQL_DATABASE_SERVER_STATE_READER_GRANT,
+].join("\n");
+
+export default class SqlServerPlatformUtil {
+  public static isAzureSqlDatabase(
+    engineEdition: number | null | undefined,
+  ): boolean {
+    return engineEdition === SqlServerEngineEdition.AzureSqlDatabase;
+  }
+
+  /*
+   * The product name shown next to the version on the monitor summary.
+   * Anything unrecognised - including no value at all, from a probe query
+   * that did not carry the edition - is SQL Server, which is what the
+   * version number alone always implied.
+   */
+  public static getPlatformName(
+    engineEdition: number | null | undefined,
+  ): string {
+    switch (engineEdition) {
+      case SqlServerEngineEdition.AzureSqlDatabase:
+        return "Azure SQL Database";
+      case SqlServerEngineEdition.AzureSqlManagedInstance:
+        return "Azure SQL Managed Instance";
+      case SqlServerEngineEdition.AzureSqlEdge:
+        return "Azure SQL Edge";
+      default:
+        return "SQL Server";
+    }
+  }
+}

package/Types/Monitor/KubernetesAlertTemplates.ts

@@ -401,11 +401,12 @@ const crashLoopBackOffTemplate: KubernetesAlertTemplate = {
          * cumulative, and the alert therefore clears on pod replacement
          * rather than when the crashing stops.
          *
-         * No angle-bracket placeholders in here. Incident.description is a
-         * Markdown column, and the subscriber path runs it through
-         * Markdown.convertToPlainText, which strips /<[^>]*>/g BEFORE it
-         * strips code-span backticks — so `<pod>` would silently vanish from
-         * every SMS.
+         * No bare angle-bracket placeholders in here. Incident.description
+         * is a Markdown column, and the subscriber path runs it through
+         * Markdown.convertToPlainText, which strips a tag-shaped <pod> as
+         * HTML — so outside backticks it would silently vanish from every
+         * SMS. Inside a code span it is safe: `<pod>` is held back before
+         * tags are stripped and reaches the SMS intact.
          *
          * This template is GROUPED (namespace + pod + container), so it does
          * NOT send the reader to the root cause for identity: a grouped

package/Types/Monitor/MonitorStepExceptionMonitor.ts

@@ -16,6 +16,15 @@ export default interface MonitorStepExceptionMonitor {
    * undefined.
    */
   entityKeys?: Array<string> | undefined;
+  /*
+   * Deployment environments (the `deployment.environment` resource attribute,
+   * stored on each occurrence's `environment` column). Matched exactly, like
+   * the Exception Explorer's `env:` filter, so an occurrence with no
+   * environment never matches a scoped monitor. Optional: monitors saved
+   * before this field existed have it undefined, which means every
+   * environment.
+   */
+  environments?: Array<string> | undefined;
   exceptionTypes: Array<string>;
   message: string;
   includeResolved: boolean;
@@ -46,6 +55,15 @@ export class MonitorStepExceptionMonitorUtil {
       query.entityKeys = new Includes(monitorStepExceptionMonitor.entityKeys);
     }
 
+    const environments: Array<string> =
+      MonitorStepExceptionMonitorUtil.normalizeEnvironments(
+        monitorStepExceptionMonitor.environments,
+      );
+
+    if (environments.length > 0) {
+      query.environment = new Includes(environments);
+    }
+
     if (
       monitorStepExceptionMonitor.exceptionTypes &&
       monitorStepExceptionMonitor.exceptionTypes.length > 0
@@ -71,10 +89,42 @@ export class MonitorStepExceptionMonitorUtil {
     return query;
   }
 
+  /*
+   * Steps written through the API are stored without passing through
+   * fromJSON, so this accepts what a caller might plausibly send — a list, or
+   * a single environment as a bare string — and drops blanks and duplicates.
+   * Values are trimmed but otherwise kept as-is: matching is exact and
+   * case-sensitive, the same as the Explorer.
+   */
+  public static normalizeEnvironments(environments: unknown): Array<string> {
+    const values: Array<unknown> = Array.isArray(environments)
+      ? environments
+      : typeof environments === "string"
+        ? [environments]
+        : [];
+
+    const normalized: Array<string> = [];
+
+    for (const value of values) {
+      if (typeof value !== "string") {
+        continue;
+      }
+
+      const environment: string = value.trim();
+
+      if (environment && !normalized.includes(environment)) {
+        normalized.push(environment);
+      }
+    }
+
+    return normalized;
+  }
+
   public static getDefault(): MonitorStepExceptionMonitor {
     return {
       telemetryServiceIds: [],
       entityKeys: [],
+      environments: [],
       exceptionTypes: [],
       message: "",
       includeResolved: false,
@@ -89,6 +139,9 @@ export class MonitorStepExceptionMonitorUtil {
         (json["telemetryServiceIds"] as Array<JSONObject>) || [],
       ),
       entityKeys: (json["entityKeys"] as Array<string>) || [],
+      environments: MonitorStepExceptionMonitorUtil.normalizeEnvironments(
+        json["environments"],
+      ),
       exceptionTypes: (json["exceptionTypes"] as Array<string>) || [],
       message: (json["message"] as string) || "",
       includeResolved: Boolean(json["includeResolved"]) || false,
@@ -102,6 +155,9 @@ export class MonitorStepExceptionMonitorUtil {
     return {
       telemetryServiceIds: ObjectID.toJSONArray(monitor.telemetryServiceIds),
       entityKeys: monitor.entityKeys || [],
+      environments: MonitorStepExceptionMonitorUtil.normalizeEnvironments(
+        monitor.environments,
+      ),
       exceptionTypes: monitor.exceptionTypes,
       message: monitor.message,
       includeResolved: monitor.includeResolved,

package/Types/Monitor/MonitorUptimeSummary.ts

@@ -0,0 +1,113 @@
+import ObjectID from "../ObjectID";
+import {
+  UptimeDayBucket,
+  UptimeStatusDuration,
+} from "../StatusPage/UptimeDailyAggregate";
+
+/*
+ * The uptime history of ONE monitor, as the monitor overview reads it from
+ * GET /api/monitor/uptime-summary/:monitorId.
+ *
+ * WHY IT IS A SERVER AGGREGATE
+ *
+ * The overview used to fetch the monitor's 90-day MonitorStatusTimeline rows
+ * under a 10,000-row cap and add them up in the browser. A flapping monitor
+ * blows through that cap in days, and the rows that fall off are the OLD ones,
+ * so the oldest bars were painted from nothing - and "nothing" rendered as
+ * 100% uptime. The aggregate is sized by days x statuses, not by status
+ * changes, so a flapping monitor cannot truncate it.
+ *
+ * Every window carries `coveredSeconds` next to `windowSeconds`. A window
+ * with no recorded time is "No data", never 100%.
+ */
+
+/*
+ * One bar per calendar day. The server starts the strip at local midnight
+ * 89 days before now, so the strip is exactly this many buckets and the last
+ * bar is today.
+ */
+export const MONITOR_UPTIME_HISTORY_DAYS: number = 90;
+
+export enum MonitorUptimeWindowKey {
+  Last24Hours = "24h",
+  Last7Days = "7d",
+  Last30Days = "30d",
+  Last90Days = "90d",
+}
+
+export interface MonitorUptimeRollingWindow {
+  key: MonitorUptimeWindowKey;
+  seconds: number;
+  label: string;
+}
+
+/*
+ * The rolling windows the stat bar shows. They end at now and are exact
+ * (86,400 seconds is 24 hours, not "since midnight"). The 90-day figure is
+ * not here: it is summed from the bars so it always agrees with the strip.
+ */
+export const MONITOR_UPTIME_ROLLING_WINDOWS: Array<MonitorUptimeRollingWindow> =
+  [
+    {
+      key: MonitorUptimeWindowKey.Last24Hours,
+      seconds: 86400,
+      label: "24 hours",
+    },
+    {
+      key: MonitorUptimeWindowKey.Last7Days,
+      seconds: 604800,
+      label: "7 days",
+    },
+    {
+      key: MonitorUptimeWindowKey.Last30Days,
+      seconds: 2592000,
+      label: "30 days",
+    },
+  ];
+
+export interface MonitorUptimeWindowTotal {
+  key: MonitorUptimeWindowKey;
+  startDate: Date;
+  endDate: Date;
+  // Wall-clock seconds in the window.
+  windowSeconds: number;
+  // Seconds of the window actually covered by a timeline row.
+  coveredSeconds: number;
+  // Seconds per status, largest first.
+  statusDurations: Array<UptimeStatusDuration>;
+}
+
+/*
+ * The project's statuses, shipped with the summary so the page does not need
+ * a MonitorStatus list request (a ReadMonitorStatusTimeline holder may not be
+ * able to read that table directly, but the timeline already exposes these
+ * columns).
+ */
+export interface MonitorUptimeSummaryStatus {
+  id: ObjectID;
+  name: string;
+  color: string;
+  isOperationalState: boolean;
+  isOfflineState: boolean;
+  priority: number | null;
+}
+
+export interface MonitorUptimeSummary {
+  monitorId: ObjectID;
+  // The IANA zone the day buckets were cut in.
+  timezone: string;
+  generatedAt: Date;
+  // Start of the first bar (local midnight, 89 days before now).
+  startDate: Date;
+  // Now, when the summary was generated.
+  endDate: Date;
+  buckets: Array<UptimeDayBucket>;
+  windows: Array<MonitorUptimeWindowTotal>;
+  /*
+   * False when the server could not vouch for the whole strip. Bars before
+   * `completeFrom` are then shown as incomplete rather than guessed at.
+   */
+  isComplete: boolean;
+  completeFrom: Date | null;
+  statuses: Array<MonitorUptimeSummaryStatus>;
+}

package/Types/Monitor/Recommendation/MonitorRecommendationUtil.ts

@@ -3,6 +3,7 @@ import MetricsViewConfig from "../../Metrics/MetricsViewConfig";
 import MetricQueryConfigData from "../../Metrics/MetricQueryConfigData";
 import MetricFormulaConfigData from "../../Metrics/MetricFormulaConfigData";
 import MonitorStep from "../MonitorStep";
+import { MonitorStepExceptionMonitorUtil } from "../MonitorStepExceptionMonitor";
 import MonitorSteps from "../MonitorSteps";
 import MonitorCriteriaInstance from "../MonitorCriteriaInstance";
 import { CriteriaIncident } from "../CriteriaIncident";
@@ -39,6 +40,7 @@ interface RecommendationMonitorStepConfig {
   entityKeys?: Array<string> | undefined;
   lastXSecondsOfSpans?: number | undefined;
   exceptionTypes?: Array<string> | undefined;
+  environments?: Array<string> | undefined;
   message?: string | undefined;
   includeResolved?: boolean | undefined;
   includeArchived?: boolean | undefined;
@@ -519,6 +521,15 @@ export default class MonitorRecommendationUtil {
     if (configKind === "exceptionMonitor") {
       values.push(
         `exceptionTypes=${(config.exceptionTypes || []).slice().sort().join(",")}`,
+        /*
+         * A production-only monitor does not cover an every-environment
+         * recommendation for the same service.
+         */
+        `environments=${MonitorStepExceptionMonitorUtil.normalizeEnvironments(
+          config.environments,
+        )
+          .sort()
+          .join(",")}`,
         `message=${config.message || ""}`,
         `entityKeys=${(config.entityKeys || []).slice().sort().join(",")}`,
         `includeResolved=${String(Boolean(config.includeResolved))}`,

package/Types/Rum/SessionReplay.ts

@@ -187,8 +187,61 @@ export const SESSION_REPLAY_KEEPALIVE_MAX_BYTES: number = 56 * 1024;
  */
 export const SESSION_REPLAY_MAX_FLUSH_FAILURES: number = 3;
 
-/* Content type carried on every chunk POST. */
-export const SESSION_REPLAY_CONTENT_TYPE: string =
+/*
+ * Offline mode: how long a recorder may hold a chunk it could not upload.
+ *
+ * A device that loses its connection keeps recording, queues what it
+ * records (in memory, and in IndexedDB or AsyncStorage so a closed tab or a
+ * killed app does not lose it) and uploads the backlog when the network
+ * returns. Past this age a queued chunk is discarded on the device instead.
+ *
+ * The server uses the same bound from the other side: a chunk's
+ * clientSendUnixMs minus its end is how long it sat in that queue, measured
+ * on the device's own clock, and ingest allows exactly that much extra
+ * lateness before it stops trusting the recording's start time (see
+ * SessionIdentity.getClientQueueDelayMs). Without it every chunk that
+ * arrived more than four hours after it was recorded was pinned to "four
+ * hours before it arrived".
+ *
+ * Three days: long enough for a flight, a weekend without signal or a
+ * device left in a drawer, and deliberately well inside the seven days an
+ * erasure tombstone lives, so a chunk of a session somebody asked to erase
+ * can never outlive the tombstone that refuses it.
+ */
+export const SESSION_REPLAY_MAX_OFFLINE_DELAY_MS: number =
+  3 * 24 * 60 * 60 * 1000;
+
+/*
+ * Content type carried on every chunk POST.
+ *
+ * application/octet-stream because customers put a web application
+ * firewall in front of OneUptime, and the OWASP Core Rule Set - and the
+ * managed rulesets built on it, Azure's DRS 2.x among them - blocks any
+ * Content-Type outside a fixed allowlist (rule 920420). Of the types on
+ * CRS 3.3's list, octet-stream is the one that honestly describes a body
+ * that is not JSON, XML, a form or text; text/plain would claim text, and
+ * Azure's older DRS 1.x inspects text/plain bodies as if they were forms.
+ * No firewall parses an octet-stream body, so the envelope's URLs and trait
+ * values are never handed to the injection rules as ARGS. See
+ * Common/Utils/Rum/SessionReplayWireEncoding for the rest of what makes a
+ * chunk pass.
+ *
+ * The body really is opaque bytes to anything in between: an envelope line
+ * and a gzip or JSON payload that only the ingest parser splits apart.
+ *
+ * The server never branches on this header - the body reader is chosen by
+ * route - so it accepts the vendor type below from every recorder that
+ * predates this change: pinned browser artifacts and shipped mobile builds.
+ */
+export const SESSION_REPLAY_CONTENT_TYPE: string = "application/octet-stream";
+
+/*
+ * What chunk POSTs carried before they switched to octet-stream. A WAF on
+ * the OWASP Core Rule Set refuses it outright (920420: "Request content
+ * type is not allowed by policy"). Kept so tests can prove the server still
+ * takes chunks from recorders that send it.
+ */
+export const SESSION_REPLAY_LEGACY_CONTENT_TYPE: string =
   "application/vnd.oneuptime.session-replay.v1";
 
 /* Header carrying the RUM application identifier, needed pre-decode. */

package/Types/Rum/SessionReplayApi.ts

@@ -6,7 +6,7 @@ import {
 /*
  * Wire contract between the Dashboard and the session-replay read routes
  * in Common/Server/API/TelemetryAPI.ts (/list, /manifest, /chunks,
- * /heartbeat, /views, /for-exception, /ingest-status). Everything here is
+ * /heartbeat, /views, /for-exception, /resolve, /ingest-status). Everything here is
  * the JSON as it
  * crosses HTTP, which is why:
  *
@@ -625,6 +625,49 @@ export interface SessionReplayForExceptionResponseDto {
   isApplicationScopeTruncated: boolean;
 }
 
+/* ---- /summaries and /resolve: batches of session ids ---- */
+
+/*
+ * Caps on a batch of session ids. The server refuses a request over either
+ * one with a 400 for the whole batch, so the Dashboard splits and filters to
+ * the same figures rather than let one oversized page of occurrences fail
+ * every id on it. A session id is 32 hex characters minted in the browser;
+ * the length cap is generous because older recorders and hand-written API
+ * callers exist, and every replay read route applies it.
+ */
+export const SESSION_REPLAY_SESSION_ID_BATCH_MAX: number = 200;
+export const SESSION_REPLAY_SESSION_ID_MAX_LENGTH: number = 128;
+
+/* ---- /resolve ---- */
+
+/*
+ * Session id -> the application that recorded it, for the replay links on
+ * log, span and exception surfaces, none of which carry the application.
+ * Project-wide: the caller does not know the application, which is the
+ * question being asked.
+ */
+export interface SessionReplayResolveRequestDto {
+  sessionIds: Array<string>;
+}
+
+export interface SessionReplayResolvedSessionDto {
+  sessionId: string;
+  rumApplicationId: string;
+  startTime: string;
+  startTimeUnixMs: number;
+}
+
+export interface SessionReplayResolveResponseDto {
+  /*
+   * Only the sessions the caller may list, and only ids recorded under
+   * exactly one application. An id missing from the answer has no
+   * recording this caller can open.
+   */
+  sessions: Array<SessionReplayResolvedSessionDto>;
+  /* The accessible-application scan has a ceiling; true when it was hit. */
+  isApplicationScopeTruncated: boolean;
+}
+
 /* ---- /ingest-status ---- */
 
 export interface SessionReplayIngestStatusRequestDto {

package/Types/Rum/UserFlow.ts

@@ -0,0 +1,187 @@
+import {
+  readDtoBoolean,
+  readDtoNumber,
+  readDtoString,
+} from "./SessionReplayApi";
+
+/*
+ * Wire contract for the User Flows page:
+ * POST /telemetry/rum/session-replay/user-flow.
+ *
+ * The endpoint answers with the ordered page JOURNEY of each recorded
+ * session in the window, not with a finished graph. Every view on the page -
+ * the flow map from the session start, the paths into or out of one page,
+ * grouping /product/8842 as /product/:id, hiding a page, filtering to
+ * frustrated sessions - is then a pure fold over the same journeys
+ * (Common/Utils/Rum/UserFlow.ts), so a control change re-draws instantly
+ * instead of re-running a ClickHouse read.
+ *
+ * Pages travel as a dictionary: `pages` holds each distinct scrubbed URL
+ * once and a journey is a list of indexes into it. A few thousand sessions
+ * share a few dozen pages, so this is what keeps the response small.
+ */
+
+/*
+ * Newest sessions read per request. The journeys of this many sessions fit
+ * in a response of a few hundred kilobytes, and a flow map drawn from them
+ * is already stable; the response says when the window held more.
+ */
+export const USER_FLOW_DEFAULT_MAX_SESSIONS: number = 5000;
+export const USER_FLOW_MAX_SESSIONS: number = 10000;
+
+/*
+ * Pages kept per journey. A session that navigates more than this is still
+ * counted; its tail is dropped. Far more than any flow map draws.
+ */
+export const USER_FLOW_MAX_PAGES_PER_JOURNEY: number = 100;
+
+/* One recorded session, reduced to what the flow map needs. */
+export interface UserFlowSessionDto {
+  sessionId: string;
+  startUnixMs: number;
+  durationMs: number;
+  deviceType: string;
+  browserName: string;
+  countryCode: string;
+  /* Session totals, from the header. */
+  errorCount: number;
+  frustrationCount: number;
+  /*
+   * The pages visited, in order, as indexes into the response's `pages`.
+   * A page repeated back to back (a reload, a chunk boundary) appears once;
+   * a return to a page after another one appears again.
+   */
+  pages: Array<number>;
+  /*
+   * Where the session's errors and frustration signals happened, as
+   * [pageIndex, errorCount, frustrationCount]. Attributed to the page a
+   * recording chunk was flushed from, so it is per page, never per visit.
+   * Pages with nothing to report are left out.
+   */
+  pageSignals: Array<[number, number, number]>;
+}
+
+export interface UserFlowJourneysResponseDto {
+  /* Distinct scrubbed page URLs ("https://shop.example.com/cart"). */
+  pages: Array<string>;
+  /* Newest first. */
+  sessions: Array<UserFlowSessionDto>;
+  /* Recorded sessions that started in the window. */
+  sessionsInWindow: number;
+  /* True when sessionsInWindow is larger than the sessions returned. */
+  isSampled: boolean;
+  maxSessions: number;
+  startUnixMs: number;
+  endUnixMs: number;
+}
+
+function readIndexArray(value: unknown, pageCount: number): Array<number> {
+  if (!Array.isArray(value)) {
+    return [];
+  }
+
+  const indexes: Array<number> = [];
+
+  for (const entry of value) {
+    const index: number = Number(entry);
+
+    if (Number.isInteger(index) && index >= 0 && index < pageCount) {
+      indexes.push(index);
+    }
+  }
+
+  return indexes;
+}
+
+function readSignalTriples(
+  value: unknown,
+  pageCount: number,
+): Array<[number, number, number]> {
+  if (!Array.isArray(value)) {
+    return [];
+  }
+
+  const triples: Array<[number, number, number]> = [];
+
+  for (const entry of value) {
+    if (!Array.isArray(entry) || entry.length < 3) {
+      continue;
+    }
+
+    const index: number = Number(entry[0]);
+    const errors: number = Number(entry[1]);
+    const frustration: number = Number(entry[2]);
+
+    if (!Number.isInteger(index) || index < 0 || index >= pageCount) {
+      continue;
+    }
+
+    triples.push([
+      index,
+      Number.isFinite(errors) && errors > 0 ? errors : 0,
+      Number.isFinite(frustration) && frustration > 0 ? frustration : 0,
+    ]);
+  }
+
+  return triples;
+}
+
+/*
+ * Parses the endpoint's JSON without trusting it: an index outside the
+ * dictionary is dropped rather than rendered as "undefined", and every
+ * number is coerced because ClickHouse quotes 64-bit integers.
+ */
+export function readUserFlowJourneysResponse(
+  value: unknown,
+): UserFlowJourneysResponseDto {
+  const row: Record<string, unknown> =
+    value && typeof value === "object"
+      ? (value as Record<string, unknown>)
+      : {};
+
+  const pages: Array<string> = Array.isArray(row["pages"])
+    ? (row["pages"] as Array<unknown>).map((page: unknown): string => {
+        return typeof page === "string" ? page : String(page ?? "");
+      })
+    : [];
+
+  const sessions: Array<UserFlowSessionDto> = [];
+
+  if (Array.isArray(row["sessions"])) {
+    for (const entry of row["sessions"] as Array<unknown>) {
+      if (!entry || typeof entry !== "object") {
+        continue;
+      }
+
+      const session: Record<string, unknown> = entry as Record<string, unknown>;
+      const sessionId: string = readDtoString(session, "sessionId");
+
+      if (!sessionId) {
+        continue;
+      }
+
+      sessions.push({
+        sessionId: sessionId,
+        startUnixMs: readDtoNumber(session, "startUnixMs"),
+        durationMs: readDtoNumber(session, "durationMs"),
+        deviceType: readDtoString(session, "deviceType"),
+        browserName: readDtoString(session, "browserName"),
+        countryCode: readDtoString(session, "countryCode"),
+        errorCount: readDtoNumber(session, "errorCount"),
+        frustrationCount: readDtoNumber(session, "frustrationCount"),
+        pages: readIndexArray(session["pages"], pages.length),
+        pageSignals: readSignalTriples(session["pageSignals"], pages.length),
+      });
+    }
+  }
+
+  return {
+    pages: pages,
+    sessions: sessions,
+    sessionsInWindow: readDtoNumber(row, "sessionsInWindow"),
+    isSampled: readDtoBoolean(row, "isSampled"),
+    maxSessions: readDtoNumber(row, "maxSessions"),
+    startUnixMs: readDtoNumber(row, "startUnixMs"),
+    endUnixMs: readDtoNumber(row, "endUnixMs"),
+  };
+}