@debugkit/dashboard 0.7.0 → 0.9.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (62) hide show
  1. package/dist/client/assets/_authed-C29P68T-.js +1 -0
  2. package/dist/client/assets/_authed-D-dYbHoP.js +7 -0
  3. package/dist/client/assets/{charts-XyOWJI9T.js → charts--S1o8iId.js} +6 -6
  4. package/dist/client/assets/copy-button-BJkvWYRY.js +1 -0
  5. package/dist/client/assets/customers-Cwx5qEO1.js +1 -0
  6. package/dist/client/assets/endpoints-zz1TotR2.js +1 -0
  7. package/dist/client/assets/events._eventId-Bx6TfUjv.js +3 -0
  8. package/dist/client/assets/index-COHr_cc3.js +10 -0
  9. package/dist/client/assets/invite._token-DiDJMnQu.js +1 -0
  10. package/dist/client/assets/issues._fingerprint-Cv522h2j.js +1 -0
  11. package/dist/client/assets/login-CKkpc0t5.js +1 -0
  12. package/dist/client/assets/sessions._sessionId-B0NxM46y.js +1 -0
  13. package/dist/client/assets/settings-CIlF10MI.js +1 -0
  14. package/dist/client/assets/src-BKSiJUs3.js +3 -0
  15. package/dist/client/assets/styles-GAsMUS4-.css +2 -0
  16. package/dist/client/assets/team-BRuVQ2bU.js +1 -0
  17. package/dist/client/assets/timeline-BIGo9MCA.js +1 -0
  18. package/dist/client/assets/ui-CaEZB1j2.js +1 -0
  19. package/dist/client/assets/version-banner-VFvyqbPh.js +1 -0
  20. package/dist/server/assets/_authed-BJWDiF9i.js +92 -0
  21. package/dist/server/assets/{_authed-C-sIPXSO.js → _authed-X9u_5JUy.js} +318 -126
  22. package/dist/server/assets/_tanstack-start-manifest_v-C6vaeBdY.js +90 -0
  23. package/dist/server/assets/copy-button-D3RddzTw.js +52 -0
  24. package/dist/server/assets/customers-827fC5I3.js +163 -0
  25. package/dist/server/assets/{demo-BsMMDk_F.js → demo-DDNiXCgj.js} +29 -7
  26. package/dist/server/assets/{dynamodb-Zkk1-mgz.js → dynamodb-Cd4blXkh.js} +98 -17
  27. package/dist/server/assets/endpoints-_T0NSOyA.js +371 -0
  28. package/dist/server/assets/{queries-BJxX3Kjp.js → errors-Po4Tt5zd.js} +893 -66
  29. package/dist/server/assets/events._eventId-Dcsu4oVO.js +765 -0
  30. package/dist/server/assets/{firestore-C52q_vwM.js → firestore-c8Sz2Q4O.js} +26 -6
  31. package/dist/server/assets/{fns-DwGaMi8S.js → fns-BiUOnY1_.js} +27 -3
  32. package/dist/server/assets/fns-CVbk8Gf9.js +1310 -0
  33. package/dist/server/assets/{invite._token-xnpnkdRv.js → invite._token-7DjEeeaD.js} +3 -3
  34. package/dist/server/assets/{issues._fingerprint-e7ubdJf0.js → issues._fingerprint-vc9r3jgg.js} +89 -11
  35. package/dist/server/assets/{login-EopnOJXA.js → login-CwKAx9Bj.js} +3 -3
  36. package/dist/server/assets/{memory-BssaqdZm.js → memory-Bv4C8uyK.js} +431 -28
  37. package/dist/server/assets/router-Dk3XHn7B.js +512 -0
  38. package/dist/server/assets/sessions._sessionId-BvXxK9qF.js +264 -0
  39. package/dist/server/assets/{settings-CaJN69N6.js → settings-B9NLQjl1.js} +221 -5
  40. package/dist/server/assets/{src-D83GYTrp.js → src-oWPSAvXv.js} +1 -1
  41. package/dist/server/assets/{team-B1UcM1jA.js → team-Bsm2wFG0.js} +3 -3
  42. package/dist/server/assets/timeline-MDRNDhiA.js +132 -0
  43. package/dist/server/assets/{ui-BJokJdYa.js → ui-SAkSlP7f.js} +53 -13
  44. package/dist/server/assets/version-banner-nf-yZurq.js +106 -0
  45. package/dist/server/assets/versions-BOlL8jam.js +58 -0
  46. package/dist/server/server.js +41 -21
  47. package/package.json +4 -4
  48. package/dist/client/assets/_authed-BN39b-7H.js +0 -1
  49. package/dist/client/assets/_authed-CspAf0jN.js +0 -7
  50. package/dist/client/assets/index-Bfb2UOzB.js +0 -10
  51. package/dist/client/assets/invite._token-B4HN51-h.js +0 -1
  52. package/dist/client/assets/issues._fingerprint-BV1QrETY.js +0 -1
  53. package/dist/client/assets/login-COlvJ5Je.js +0 -1
  54. package/dist/client/assets/preload-helper-Dscj_TcA.js +0 -3
  55. package/dist/client/assets/settings-Dl4EWeWC.js +0 -1
  56. package/dist/client/assets/styles-DztngwT9.css +0 -2
  57. package/dist/client/assets/team-7Zekz_Er.js +0 -1
  58. package/dist/client/assets/ui-C0HGOza2.js +0 -1
  59. package/dist/server/assets/_authed-CrjuC0O3.js +0 -73
  60. package/dist/server/assets/_tanstack-start-manifest_v-CqaE4wze.js +0 -61
  61. package/dist/server/assets/fns-mbUIXXep.js +0 -529
  62. package/dist/server/assets/router-G99085_Q.js +0 -315
@@ -1,6 +1,6 @@
1
1
  import { a as getCookie, i as deleteCookie, o as getRequestHeader, s as setCookie } from "../server.js";
2
- import { a as SEVERITY_ORDER, c as parseStack, d as severityFromCount, i as DEFAULT_SEVERITY_THRESHOLDS, l as percentileMs, o as compareVersions, r as Envelope, u as releaseKey } from "./memory-BssaqdZm.js";
3
- import { n as TEAM_ROLES, t as MAX_RETENTION_DAYS } from "./src-D83GYTrp.js";
2
+ import { C as CAUSE_INFO, D as cleanFnName, E as OWNER_INFO, O as markLibraryFrames, S as CATEGORY_INFO, _ as severityFromCount, b as normaliseHostMatch, d as SEVERITY_ORDER, f as compareVersions$1, g as releaseKey, h as percentileMs, l as Envelope, m as parseStack, r as compareVersions, u as DEFAULT_SEVERITY_THRESHOLDS, v as hostNameFor, w as IMPACT_INFO, x as validHostNames, y as nameUrlsIn } from "./memory-Bv4C8uyK.js";
3
+ import { n as TEAM_ROLES, t as MAX_RETENTION_DAYS } from "./src-oWPSAvXv.js";
4
4
  import { createHash, createHmac, randomBytes, scryptSync, timingSafeEqual } from "node:crypto";
5
5
  // src/server/config.ts
6
6
  var loaded = false;
@@ -40,6 +40,8 @@ function config() {
40
40
  /** The ingest function's admin routes (…/admin) and their token, for changing settings. */
41
41
  adminUrl: env.DEBUG_ADMIN_URL?.replace(/\/+$/, ""),
42
42
  adminToken: env.DEBUG_ADMIN_TOKEN,
43
+ /** The CLI environment this dashboard belongs to ("preview"), for commands it suggests (`--env preview`). */
44
+ environment: /^[a-z][a-z0-9-]{0,30}$/.test(env.DEBUG_ENVIRONMENT ?? "") ? env.DEBUG_ENVIRONMENT : void 0,
43
45
  /** The deployment's default retention (what ingest uses before an app has a setting). */
44
46
  retentionDays: num(env.DEBUG_RETENTION_DAYS, 0) || void 0,
45
47
  /** "Create issue" buttons on the issue page. */
@@ -75,22 +77,22 @@ async function create() {
75
77
  case "firestore": {
76
78
  const { initializeApp, getApps } = await import("firebase-admin/app");
77
79
  const { getFirestore } = await import("firebase-admin/firestore");
78
- const { FirestoreStore } = await import("./firestore-C52q_vwM.js");
80
+ const { FirestoreStore } = await import("./firestore-c8Sz2Q4O.js");
79
81
  if (!getApps().length) initializeApp();
80
82
  return new FirestoreStore(getFirestore(), { root: cfg.firestoreRoot });
81
83
  }
82
84
  case "dynamodb": {
83
85
  const { DynamoDBClient } = await import("@aws-sdk/client-dynamodb");
84
86
  const { DynamoDBDocumentClient } = await import("@aws-sdk/lib-dynamodb");
85
- const { DynamoStore } = await import("./dynamodb-Zkk1-mgz.js");
87
+ const { DynamoStore } = await import("./dynamodb-Cd4blXkh.js");
86
88
  return new DynamoStore(DynamoDBDocumentClient.from(new DynamoDBClient({})), { table: cfg.dynamoTable });
87
89
  }
88
90
  case "memory": {
89
- const { MemoryStore } = await import("./memory-BssaqdZm.js").then((n) => n.n);
91
+ const { MemoryStore } = await import("./memory-Bv4C8uyK.js").then((n) => n.n);
90
92
  return new MemoryStore();
91
93
  }
92
94
  default: {
93
- const { seedDemo } = await import("./demo-BsMMDk_F.js");
95
+ const { seedDemo } = await import("./demo-DDNiXCgj.js");
94
96
  return seedDemo();
95
97
  }
96
98
  }
@@ -127,6 +129,7 @@ async function readSettings(app) {
127
129
  retentionDays: out.retentionDays,
128
130
  criticalFlows: out.settings?.criticalFlows ?? [],
129
131
  alerts: out.settings?.alerts ?? {},
132
+ hosts: out.settings?.hosts ?? [],
130
133
  source: out.settings?.retentionDays ? "setting" : "default",
131
134
  updatedAt: out.settings?.updatedAt,
132
135
  writer
@@ -137,6 +140,7 @@ async function readSettings(app) {
137
140
  retentionDays: c.retentionDays ?? null,
138
141
  criticalFlows: [],
139
142
  alerts: {},
143
+ hosts: [],
140
144
  source: c.retentionDays ? "default" : "unknown",
141
145
  writer,
142
146
  note: `Couldn't reach the ingest function: ${err.message}`
@@ -152,12 +156,26 @@ async function readSettings(app) {
152
156
  ...s?.alerts,
153
157
  slackWebhookUrl: hook ? `https://hooks.slack.com/…${hook.slice(-4)}` : void 0
154
158
  },
159
+ hosts: s?.hosts ?? [],
155
160
  source: s?.retentionDays ? "setting" : c.retentionDays || writer === "local" ? "default" : "unknown",
156
161
  updatedAt: s?.updatedAt,
157
162
  writer,
158
163
  note: writer === "none" ? "Changing settings needs DEBUG_ADMIN_URL and DEBUG_ADMIN_TOKEN (npx debugkit init sets them)." : void 0
159
164
  };
160
165
  }
166
+ /** Hosts the app called in the last 30 days, busiest first: suggestions for naming them. */
167
+ async function seenHosts(app, now = Date.now()) {
168
+ const day = (t) => new Date(t).toISOString().slice(0, 10);
169
+ const store = await getStore();
170
+ const [from, to] = [day(now - 2592e6), day(now)];
171
+ const [timed, failed] = await Promise.all([store.getRollups(app, "requests", from, to).catch(() => []), store.getRollups(app, "endpoint", from, to).catch(() => [])]);
172
+ const counts = /* @__PURE__ */ new Map();
173
+ for (const r of [...timed, ...failed]) {
174
+ const host = normaliseHostMatch(r.key.split(" ")[1] ?? "").split("/")[0];
175
+ if (host) counts.set(host, (counts.get(host) ?? 0) + r.events + r.errors);
176
+ }
177
+ return [...counts.entries()].sort((a, b) => b[1] - a[1]).slice(0, 30).map(([h]) => h);
178
+ }
161
179
  function validRetention(days) {
162
180
  const n = Number(days);
163
181
  if (!Number.isInteger(n) || n < 1 || n > 3650) throw new Error(`Retention must be a whole number of days from 1 to ${MAX_RETENTION_DAYS}.`);
@@ -173,7 +191,7 @@ async function writeRetention(app, days) {
173
191
  else throw new Error("Settings can't be changed from this dashboard: DEBUG_ADMIN_URL and DEBUG_ADMIN_TOKEN aren't set.");
174
192
  return readSettings(app);
175
193
  }
176
- /** Change critical flows and/or alert settings. Validation happens in the ingest function (or here, locally). */
194
+ /** Change critical flows, alert settings and/or host names. Validation happens in the ingest function (or here, locally). */
177
195
  async function writeSettings(app, patch) {
178
196
  const writer = settingsWriter();
179
197
  if (writer === "admin") await admin("PUT", "/settings", {
@@ -185,13 +203,16 @@ async function writeSettings(app, patch) {
185
203
  const cur = await store.getSettings(app);
186
204
  const url = patch.alerts?.slackWebhookUrl;
187
205
  if (patch.alerts && url && !url.includes("…") && !/^https:\/\/hooks\.slack\.com\/services\/[A-Za-z0-9/_-]{10,200}$/.test(url)) throw new Error("Use a Slack incoming-webhook URL (https://hooks.slack.com/services/…).");
206
+ const hosts = patch.hosts ? validHostNames(patch.hosts) : void 0;
207
+ if (typeof hosts === "string") throw new Error(hosts);
188
208
  const alerts = patch.alerts ? {
189
209
  ...patch.alerts,
190
210
  slackWebhookUrl: url?.includes("…") ? cur?.alerts?.slackWebhookUrl : url || void 0
191
211
  } : void 0;
192
212
  await store.putSettings(app, {
193
213
  ...patch.criticalFlows ? { criticalFlows: patch.criticalFlows } : {},
194
- ...alerts ? { alerts } : {}
214
+ ...alerts ? { alerts } : {},
215
+ ...hosts ? { hosts } : {}
195
216
  });
196
217
  } else throw new Error("Settings can't be changed from this dashboard: DEBUG_ADMIN_URL and DEBUG_ADMIN_TOKEN aren't set.");
197
218
  return readSettings(app);
@@ -415,12 +436,13 @@ async function sendAlerts(app, outcome, issues, settings, post = defaultPost) {
415
436
  const u = issues.get(fp);
416
437
  if (!u) continue;
417
438
  const link = a.dashboardUrl ? `${a.dashboardUrl.replace(/\/+$/, "")}/issues/${fp}?app=${encodeURIComponent(app)}` : void 0;
439
+ const title = nameUrlsIn(u.title, settings?.hosts);
418
440
  const where = [
419
441
  u.culprit && `\`${u.culprit}\``,
420
442
  u.flow && `flow \`${u.flow}\`${critical.has(u.flow) ? " (critical)" : ""}`,
421
443
  u.version && `version ${u.version}`
422
444
  ].filter(Boolean).join(" · ");
423
- const text = `${kind === "new" ? ":new: New issue" : ":rotating_light: Regressed"} in *${app}*: ${link ? `<${link}|${u.title}>` : u.title}${where ? `\n${where}` : ""}`;
445
+ const text = `${kind === "new" ? ":new: New issue" : ":rotating_light: Regressed"} in *${app}*: ${link ? `<${link}|${title}>` : title}${where ? `\n${where}` : ""}`;
424
446
  try {
425
447
  await post(a.slackWebhookUrl, { text });
426
448
  sent++;
@@ -556,6 +578,287 @@ function countryOf(ctx) {
556
578
  if (tz) return tz;
557
579
  return /[-_]([A-Z]{2})(?:\b|$)/.exec(ctx.locale ?? "")?.[1] ?? "unknown";
558
580
  }
581
+ // ../../packages/ingest/src/classify.ts
582
+ var FOREGROUND = "App came to the foreground";
583
+ var BACKGROUND = "App went to the background";
584
+ var NEVER_SENT_MS = 100;
585
+ /** How long after reopening a failure still counts as "on resume", if nothing has succeeded since. */
586
+ var RESUME_WINDOW_MS = 1e4;
587
+ var CRASH_SOURCES = /* @__PURE__ */ new Set(["global-handler", "uncaughtException"]);
588
+ var REJECTION_SOURCES = /* @__PURE__ */ new Set([
589
+ "unhandled-rejection",
590
+ "unhandledrejection",
591
+ "unhandledRejection"
592
+ ]);
593
+ /** "GET host/path → 200 (93ms)", as the SDK writes network breadcrumbs. */
594
+ var NETWORK_CRUMB = /^\S+ (\S+) → /;
595
+ /** "GET host/path timed out", optionally followed by ": <cause>", as the SDK writes a timed-out request. */
596
+ var TIMED_OUT = /^\S+ \S+ timed out(?::|$)/;
597
+ var hostOf = (url) => url.replace(/^[a-z]+:\/\//i, "").split("/")[0] ?? "";
598
+ function crumbRequest(b) {
599
+ if (b.category !== "network") return void 0;
600
+ const m = NETWORK_CRUMB.exec(b.message);
601
+ if (!m) return void 0;
602
+ const status = typeof b.data?.status === "number" ? b.data.status : void 0;
603
+ return {
604
+ url: m[1],
605
+ status,
606
+ failed: b.level === "error"
607
+ };
608
+ }
609
+ /** A request that got a good answer: 2xx or 3xx. */
610
+ var succeeded = (r) => !r.failed && r.status !== void 0 && r.status < 400;
611
+ /**
612
+ * The breadcrumbs before this error. The SDK records a failed request's own breadcrumb just
613
+ * before reporting it; that one is the error, not something that happened before it. The SDK
614
+ * also merges identical breadcrumbs in a row into one with `data.repeated`: when the error's own
615
+ * breadcrumb says so, the same request had already failed just before.
616
+ */
617
+ function earlierCrumbs(e) {
618
+ const crumbs = e.breadcrumbs ?? [];
619
+ const r = e.request;
620
+ if (!r) return {
621
+ crumbs,
622
+ repeatedFailure: false
623
+ };
624
+ const own = `${r.method} ${r.url} → `.toUpperCase();
625
+ for (let i = crumbs.length - 1; i >= 0; i--) {
626
+ const b = crumbs[i];
627
+ if (b.category === "network" && b.level === "error" && b.message.toUpperCase().startsWith(own)) return {
628
+ crumbs: [...crumbs.slice(0, i), ...crumbs.slice(i + 1)],
629
+ repeatedFailure: Number(b.data?.repeated ?? 1) > 1
630
+ };
631
+ }
632
+ return {
633
+ crumbs,
634
+ repeatedFailure: false
635
+ };
636
+ }
637
+ function category(e) {
638
+ const r = e.request;
639
+ const source = e.tags?.source;
640
+ if (r && r.status === void 0) {
641
+ if (TIMED_OUT.test(e.error.message)) return "network.timeout";
642
+ if (r.durationMs !== void 0 && r.durationMs < NEVER_SENT_MS) return "network.never_sent";
643
+ return "network.failed";
644
+ }
645
+ if (r?.status !== void 0) {
646
+ if (r.status === 401 || r.status === 403) return "auth";
647
+ if (r.status >= 500 && r.status <= 599) return "server";
648
+ if (r.status >= 400 && r.status <= 499) return "client_request";
649
+ }
650
+ if (!e.handled && source && CRASH_SOURCES.has(source) && e.severity === "critical") return "crash";
651
+ if (source === "error-boundary") return "screen_crash";
652
+ if (source && REJECTION_SOURCES.has(source)) return "unhandled_rejection";
653
+ if (!e.handled) return "uncaught";
654
+ if (!r) return "app_reported";
655
+ return "other";
656
+ }
657
+ /** The last foreground/background breadcrumb before the error. */
658
+ function lastLifecycle(crumbs) {
659
+ for (let i = crumbs.length - 1; i >= 0; i--) {
660
+ const b = crumbs[i];
661
+ if (b.category === "ui" && (b.message === FOREGROUND || b.message === BACKGROUND)) return b;
662
+ }
663
+ }
664
+ function gather(e, crumbs, repeatedFailure) {
665
+ const at = Date.parse(e.ts);
666
+ const within = (b, ms) => {
667
+ const d = at - Date.parse(b.ts);
668
+ return d >= 0 && d <= ms;
669
+ };
670
+ const requests = crumbs.map((b) => ({
671
+ b,
672
+ r: crumbRequest(b)
673
+ })).filter((x) => !!x.r);
674
+ const life = lastLifecycle(crumbs);
675
+ const foreground = life?.message === FOREGROUND ? Date.parse(life.ts) : void 0;
676
+ const burst = requests.filter((x) => x.r.failed && within(x.b, 5e3));
677
+ const hosts = new Set(burst.map((x) => hostOf(x.r.url)));
678
+ if (e.request && (burst.length || repeatedFailure)) hosts.add(hostOf(e.request.url));
679
+ const host = e.request ? hostOf(e.request.url) : void 0;
680
+ return {
681
+ durationMs: e.request?.durationMs,
682
+ status: e.request?.status,
683
+ msSinceForeground: foreground !== void 0 && at >= foreground ? at - foreground : void 0,
684
+ workedSinceForeground: foreground !== void 0 && requests.some((x) => Date.parse(x.b.ts) >= foreground && succeeded(x.r)),
685
+ inBackground: life?.message === BACKGROUND,
686
+ failedBefore: burst.length,
687
+ failedHosts: [...hosts],
688
+ repeatedFailure,
689
+ slowRecent: requests.slice(-5).filter((x) => x.b.level === "warning").length,
690
+ sameHostWorkedBefore: !!host && requests.some((x) => hostOf(x.r.url) === host && succeeded(x.r))
691
+ };
692
+ }
693
+ /** Evidence for when there's no error event to measure (e.g. it has expired). */
694
+ var NO_EVIDENCE = {
695
+ workedSinceForeground: false,
696
+ inBackground: false,
697
+ failedBefore: 0,
698
+ failedHosts: [],
699
+ repeatedFailure: false,
700
+ slowRecent: 0,
701
+ sameHostWorkedBefore: false
702
+ };
703
+ /** The evidence behind an error's labels. */
704
+ function evidenceOf(e) {
705
+ const { crumbs, repeatedFailure } = earlierCrumbs(e);
706
+ return gather(e, crumbs, repeatedFailure);
707
+ }
708
+ function eventCauses(cat, ev) {
709
+ const causes = [];
710
+ if (ev.msSinceForeground !== void 0 && ev.msSinceForeground <= RESUME_WINDOW_MS && !ev.workedSinceForeground) causes.push("resumed_from_background");
711
+ if (ev.failedBefore >= 1 || ev.repeatedFailure) causes.push("burst");
712
+ if (ev.slowRecent >= 2) causes.push("slow_network");
713
+ if (cat === "auth" && ev.sameHostWorkedBefore) causes.push("auth_expired");
714
+ return causes;
715
+ }
716
+ function owner(cat, causes, burstHosts) {
717
+ switch (cat) {
718
+ case "network.never_sent":
719
+ case "client_request":
720
+ case "crash":
721
+ case "screen_crash":
722
+ case "unhandled_rejection":
723
+ case "uncaught":
724
+ case "app_reported": return "app";
725
+ case "server": return "backend";
726
+ case "auth": return causes.includes("auth_expired") ? "app" : "unknown";
727
+ case "network.timeout":
728
+ case "network.failed": return causes.includes("burst") && burstHosts.length > 1 ? "infrastructure" : "unknown";
729
+ default: return "unknown";
730
+ }
731
+ }
732
+ /**
733
+ * The owner Settings gives the request's host, where the rules can't tell on their own: server
734
+ * errors (the backend by default, but the host may be a third party's), and failed, timed-out
735
+ * or refused requests the rules leave as unknown. Never overrides "app" (the request didn't reach
736
+ * the server, or the app sent it wrong) or "infrastructure" (many hosts failed at once).
737
+ *
738
+ * Safe to run again on labels it already changed: an owner no rule gives these categories came
739
+ * from a host, so it's reset first. Changing or removing the host's owner later takes effect.
740
+ */
741
+ function hostOwner(labels, url, hosts) {
742
+ const { category, owner } = labels;
743
+ if (!(category === "server" || category === "network.timeout" || category === "network.failed" || category === "auth")) return owner;
744
+ const rule = category === "server" ? "backend" : owner === "app" || owner === "infrastructure" ? owner : "unknown";
745
+ const named = url ? hostNameFor(url, hosts)?.host.owner : void 0;
746
+ return named && (category === "server" || rule === "unknown") ? named : rule;
747
+ }
748
+ function impact(e, cat, ev, critical) {
749
+ if (cat === "crash" || e.flow && critical.has(e.flow)) return "blocked";
750
+ if (ev.inBackground) return "silent";
751
+ if (cat === "app_reported" && !e.flow) return "silent";
752
+ return "degraded";
753
+ }
754
+ /**
755
+ * `e.ts` must be the device's own time, as sent: breadcrumbs carry device time too, and the time
756
+ * rules compare the two. Ingest pins skewed clocks to the server's time for storage; classify
757
+ * before that.
758
+ */
759
+ function classify(e, opts = {}) {
760
+ const ev = evidenceOf(e);
761
+ const cat = category(e);
762
+ const causes = eventCauses(cat, ev);
763
+ return {
764
+ category: cat,
765
+ owner: hostOwner({
766
+ category: cat,
767
+ owner: owner(cat, causes, ev.failedHosts)
768
+ }, e.request?.url, opts.hosts),
769
+ impact: impact(e, cat, ev, new Set(opts.criticalFlows ?? [])),
770
+ causes
771
+ };
772
+ }
773
+ var SINGLE_DEVICE_MIN = 5;
774
+ function issueCauses(f) {
775
+ const causes = [];
776
+ if (f.latestVersion && f.firstVersion === f.latestVersion) causes.push("new_in_release");
777
+ if (f.status === "regressed") causes.push("regressed");
778
+ const models = f.deviceModels ?? [];
779
+ if (models.length >= SINGLE_DEVICE_MIN && models[0] && models.every((m) => m === models[0])) causes.push("single_device");
780
+ return causes;
781
+ }
782
+ /** An error's labels with its issue's causes added, without repeats. */
783
+ function withIssueCauses(labels, f) {
784
+ const extra = issueCauses(f).filter((c) => !labels.causes.includes(c));
785
+ return extra.length ? {
786
+ ...labels,
787
+ causes: [...labels.causes, ...extra]
788
+ } : labels;
789
+ }
790
+ // ../../packages/ingest/src/incidents.ts
791
+ /**
792
+ * Incidents fold issues that fail together for the same reason into one problem: the six
793
+ * requests that failed when the app reopened are one incident, not four issues.
794
+ *
795
+ * An incident is a recurring problem across users and days, not one episode: the key is the
796
+ * cause, the category and the OS, never a fingerprint or a session, so it stays the same across
797
+ * builds and releases ("resumed_from_background|network.never_sent|ios"). Issues stay the unit for
798
+ * resolving and regressions; incidents sit above them.
799
+ */
800
+ /** Causes that tie several errors together, most telling first. */
801
+ var GROUPING_CAUSES = ["resumed_from_background", "burst"];
802
+ var REQUEST_CATEGORIES = /* @__PURE__ */ new Set([
803
+ "network.offline",
804
+ "network.timeout",
805
+ "network.never_sent",
806
+ "network.failed",
807
+ "auth",
808
+ "server",
809
+ "client_request"
810
+ ]);
811
+ /** Categories for a failed request: the only ones a burst makes an incident of. */
812
+ var isRequestCategory = (c) => REQUEST_CATEGORIES.has(c);
813
+ var SEP = "|";
814
+ function incidentKey(labels, os) {
815
+ const cause = GROUPING_CAUSES.find((c) => labels.causes.includes(c) && (c !== "burst" || isRequestCategory(labels.category)));
816
+ if (!cause) return void 0;
817
+ const osPart = os.toLowerCase().replaceAll(SEP, " ").trim() || "unknown";
818
+ return [
819
+ cause,
820
+ labels.category,
821
+ osPart
822
+ ].join(SEP);
823
+ }
824
+ function parseIncidentKey(key) {
825
+ const [cause, category, os, ...rest] = key.split(SEP);
826
+ return cause && category && os && !rest.length ? {
827
+ cause,
828
+ category,
829
+ os
830
+ } : void 0;
831
+ }
832
+ /** "<incident key>|<fingerprint>", the key of the incidentIssue rollup. */
833
+ var incidentIssueKey = (incident, fingerprint) => `${incident}${SEP}${fingerprint}`;
834
+ function parseIncidentIssueKey(key) {
835
+ const cut = key.lastIndexOf(SEP);
836
+ if (cut <= 0 || !parseIncidentKey(key.slice(0, cut))) return void 0;
837
+ return {
838
+ incident: key.slice(0, cut),
839
+ fingerprint: key.slice(cut + 1)
840
+ };
841
+ }
842
+ /**
843
+ * Give each error in one batch its incident. An error's own labels decide first. Then the first
844
+ * failure of a burst, which can't know the others are coming, joins a burst incident of the same
845
+ * category that starts within BURST_WINDOW_MS after it. Only errors whose own incident is a burst
846
+ * pull others in (never a resume incident: an earlier error didn't fail on resume), so the result
847
+ * doesn't depend on the batch's order and never chains.
848
+ */
849
+ function assignIncidents(errors, os) {
850
+ for (const e of errors) e.incident = incidentKey(e.labels, os);
851
+ const anchors = errors.filter((e) => parseIncidentKey(e.incident ?? "")?.cause === "burst").map((e) => ({
852
+ at: Date.parse(e.ts),
853
+ e
854
+ }));
855
+ for (const e of errors) {
856
+ if (e.incident || !isRequestCategory(e.labels.category)) continue;
857
+ const at = Date.parse(e.ts);
858
+ const anchor = anchors.find((a) => a.e.labels.category === e.labels.category && a.at - at >= 0 && a.at - at <= 5e3);
859
+ if (anchor) e.incident = anchor.e.incident;
860
+ }
861
+ }
559
862
  // ../../packages/ingest/src/fingerprint.ts
560
863
  /** Strip volatile parts so "User 123 not found" and "User 456 not found" group together. */
561
864
  function normaliseMessage(msg) {
@@ -586,7 +889,8 @@ function culpritOf(e) {
586
889
  const f = topInAppFrame(e.error.frames);
587
890
  if (!f) return void 0;
588
891
  const loc = normaliseFile(f.file) + (f.line ? `:${f.line}` : "");
589
- return f.fn ? `${f.fn} (${loc})` : loc;
892
+ const fn = cleanFnName(f.fn);
893
+ return fn ? `${fn} (${loc})` : loc;
590
894
  }
591
895
  /**
592
896
  * Fingerprint = error name + top in-app frame (function + file, not line, so small edits
@@ -595,7 +899,7 @@ function culpritOf(e) {
595
899
  function fingerprint(e) {
596
900
  const f = topInAppFrame(e.error.frames);
597
901
  const r = e.request;
598
- const where = r ? `${r.method.toUpperCase()} ${r.url} ${r.status ? `${Math.floor(r.status / 100)}xx` : "failed"}` : f ? `${f.fn ?? "?"}@${normaliseFile(f.file)}` : normaliseMessage(e.error.message);
902
+ const where = r ? `${r.method.toUpperCase()} ${r.url} ${r.status ? `${Math.floor(r.status / 100)}xx` : "failed"}` : f ? `${cleanFnName(f.fn) ?? "?"}@${normaliseFile(f.file)}` : normaliseMessage(e.error.message);
599
903
  return createHash("sha256").update([
600
904
  e.error.name,
601
905
  where,
@@ -605,6 +909,11 @@ function fingerprint(e) {
605
909
  function titleOf(e) {
606
910
  return `${e.error.name}: ${e.error.message}`.slice(0, 200);
607
911
  }
912
+ // ../../packages/ingest/src/version.ts
913
+ /** This ingest's version: the package's, which every release bumps with the SDK's (one changeset group). */
914
+ var INGEST_VERSION = "0.9.0";
915
+ /** Sent on every ingest response, so an SDK (or the CLI) can tell how old the ingest it talks to is. */
916
+ var VERSION_HEADER = "x-debugkit-version";
608
917
  // ../../packages/ingest/src/index.ts
609
918
  /** "pk_abc:megaton-native,pk_def:other-app" → { pk_abc: "megaton-native", ... } */
610
919
  function parseIngestKeys(raw) {
@@ -690,12 +999,31 @@ async function ingest(rawBody, ingestKey, opts) {
690
999
  const issues = /* @__PURE__ */ new Map();
691
1000
  /** Where this envelope's user counts: "app", "crash", "issue:<fp>". */
692
1001
  const scopes = /* @__PURE__ */ new Set();
1002
+ const storedEvent = (day, event, fingerprint, labels) => ({
1003
+ app,
1004
+ day,
1005
+ fingerprint,
1006
+ labels,
1007
+ event,
1008
+ context,
1009
+ user: env.user,
1010
+ sessionId: env.session.id,
1011
+ receivedAt
1012
+ });
1013
+ const settings = env.events.some((e) => e.type === "error") ? await cachedSettings(opts.store, app) : null;
1014
+ const criticalFlows = settings?.criticalFlows ?? [];
1015
+ const hosts = settings?.hosts ?? [];
1016
+ /** This batch's errors, to group into incidents once they're all labelled. */
1017
+ const batchErrors = [];
693
1018
  for (const raw of env.events) {
694
1019
  const event = {
695
1020
  ...raw,
696
1021
  ts: sanitiseTs(raw.ts, now)
697
1022
  };
698
- if (event.type === "error" && !event.error.frames?.length && event.error.stack) event.error.frames = parseStack(event.error.stack);
1023
+ if (event.type === "error") {
1024
+ if (!event.error.frames?.length && event.error.stack) event.error.frames = parseStack(event.error.stack);
1025
+ else if (event.error.frames?.length) event.error.frames = markLibraryFrames(event.error.frames);
1026
+ }
699
1027
  const day = dayOf(event.ts);
700
1028
  if (event.type === "session") {
701
1029
  rollups.push({
@@ -756,19 +1084,25 @@ async function ingest(rawBody, ingestKey, opts) {
756
1084
  by: 1
757
1085
  });
758
1086
  let fp;
1087
+ let labels;
1088
+ let se;
759
1089
  if (event.type === "error") {
760
1090
  fp = fingerprint(event);
1091
+ labels = classify({
1092
+ ...event,
1093
+ ts: raw.ts
1094
+ }, {
1095
+ criticalFlows,
1096
+ hosts
1097
+ });
761
1098
  const cur = issues.get(fp);
762
- const se = {
763
- app,
764
- day,
765
- fingerprint: fp,
766
- event,
767
- context,
768
- user: env.user,
769
- sessionId: env.session.id,
770
- receivedAt
771
- };
1099
+ se = storedEvent(day, event, fp, labels);
1100
+ batchErrors.push({
1101
+ ts: raw.ts,
1102
+ labels,
1103
+ se,
1104
+ fp
1105
+ });
772
1106
  issues.set(fp, {
773
1107
  app,
774
1108
  fingerprint: fp,
@@ -805,17 +1139,47 @@ async function ingest(rawBody, ingestKey, opts) {
805
1139
  if (event.type === "error") {
806
1140
  inc("network", context.network?.type);
807
1141
  inc("country", countryOf(context));
1142
+ if (labels) {
1143
+ inc("category", labels.category);
1144
+ inc("owner", labels.owner);
1145
+ inc("impact", labels.impact);
1146
+ }
808
1147
  }
809
- stored.push({
1148
+ stored.push(se ?? storedEvent(day, event, fp, labels));
1149
+ }
1150
+ assignIncidents(batchErrors, context.os.name);
1151
+ const episodes = /* @__PURE__ */ new Set();
1152
+ for (const err of batchErrors) {
1153
+ if (!err.incident) continue;
1154
+ err.se.incident = err.incident;
1155
+ rollups.push({
810
1156
  app,
811
- day,
812
- fingerprint: fp,
813
- event,
814
- context,
815
- user: env.user,
816
- sessionId: env.session.id,
817
- receivedAt
1157
+ day: err.se.day,
1158
+ dimension: "incident",
1159
+ key: err.incident,
1160
+ kind: "error",
1161
+ by: 1
818
1162
  });
1163
+ rollups.push({
1164
+ app,
1165
+ day: err.se.day,
1166
+ dimension: "incidentIssue",
1167
+ key: incidentIssueKey(err.incident, err.fp),
1168
+ kind: "error",
1169
+ by: 1
1170
+ });
1171
+ if (!episodes.has(err.incident)) {
1172
+ episodes.add(err.incident);
1173
+ rollups.push({
1174
+ app,
1175
+ day: err.se.day,
1176
+ dimension: "incident",
1177
+ key: err.incident,
1178
+ kind: "event",
1179
+ by: 1
1180
+ });
1181
+ }
1182
+ scopes.add(`incident:${err.incident}`);
819
1183
  }
820
1184
  await opts.store.registerApp(app);
821
1185
  const retentionDays = stored.length ? await effectiveRetention(opts.store, app, opts.retentionDays) : void 0;
@@ -823,9 +1187,10 @@ async function ingest(rawBody, ingestKey, opts) {
823
1187
  stored.length ? opts.store.writeEvents(stored, { retentionDays }) : void 0,
824
1188
  opts.store.upsertIssues([...issues.values()]),
825
1189
  opts.store.incrementRollups(rollups),
826
- markUsers(opts.store, app, env.user?.id ?? env.user?.anonymousId ?? env.session.id, scopes, dayOf(receivedAt))
1190
+ markUsers(opts.store, app, env.user?.id ?? env.user?.anonymousId ?? env.session.id, scopes, dayOf(receivedAt)),
1191
+ noteVersions(opts.store, app, env.sdk.version, receivedAt)
827
1192
  ]);
828
- if (outcome && (outcome.created.length || outcome.regressed.length)) await sendAlerts(app, outcome, issues, await cachedSettings(opts.store, app));
1193
+ if (outcome && (outcome.created.length || outcome.regressed.length)) await sendAlerts(app, outcome, issues, settings);
829
1194
  return {
830
1195
  status: 202,
831
1196
  body: {
@@ -834,6 +1199,42 @@ async function ingest(rawBody, ingestKey, opts) {
834
1199
  }
835
1200
  };
836
1201
  }
1202
+ /**
1203
+ * What this instance last recorded (or tried to) per store and app, so a steady app costs one
1204
+ * versions write a day, not one per batch, and a store that's down isn't retried on every batch.
1205
+ */
1206
+ var recordedVersions = /* @__PURE__ */ new WeakMap();
1207
+ var VERSIONS_REFRESH_MS = 864e5;
1208
+ var VERSIONS_RETRY_MS = 6e5;
1209
+ /**
1210
+ * Record the app's SDK version and this ingest's, when the SDK is newer than what this instance last
1211
+ * recorded, or a day has passed. A failure here never fails the envelope; it's tried again in ten minutes.
1212
+ */
1213
+ async function noteVersions(store, app, sdk, at) {
1214
+ let byApp = recordedVersions.get(store);
1215
+ if (!byApp) recordedVersions.set(store, byApp = /* @__PURE__ */ new Map());
1216
+ const had = byApp.get(app);
1217
+ const now = Date.parse(at);
1218
+ if (had && compareVersions(sdk, had.sdk) <= 0 && now - had.at < VERSIONS_REFRESH_MS) return;
1219
+ const newest = compareVersions(sdk, had?.sdk) > 0 ? sdk : had?.sdk;
1220
+ try {
1221
+ await store.recordVersions(app, {
1222
+ sdk,
1223
+ ingest: INGEST_VERSION,
1224
+ at
1225
+ });
1226
+ byApp.set(app, {
1227
+ sdk: newest,
1228
+ at: now
1229
+ });
1230
+ } catch (err) {
1231
+ byApp.set(app, {
1232
+ sdk: newest,
1233
+ at: now - VERSIONS_REFRESH_MS + VERSIONS_RETRY_MS
1234
+ });
1235
+ console.warn("[deBug] couldn't record versions", err);
1236
+ }
1237
+ }
837
1238
  /** Recently written (scope, member, day) marks, so a busy user costs one write per day, not per batch. */
838
1239
  var seenMarks = /* @__PURE__ */ new Set();
839
1240
  /**
@@ -857,11 +1258,14 @@ async function markUsers(store, app, who, scopes, day) {
857
1258
  if (seenMarks.size > 5e4) seenMarks.clear();
858
1259
  if (marks.length) await store.markUsers(app, marks);
859
1260
  }
1261
+ /** On every ingest response: CORS for browser SDKs, and this ingest's version, readable from the browser too. */
860
1262
  var CORS_HEADERS = {
861
1263
  "access-control-allow-origin": "*",
862
1264
  "access-control-allow-methods": "POST, OPTIONS",
863
1265
  "access-control-allow-headers": "content-type, x-debug-key",
864
- "access-control-max-age": "86400"
1266
+ "access-control-expose-headers": VERSION_HEADER,
1267
+ "access-control-max-age": "86400",
1268
+ [VERSION_HEADER]: INGEST_VERSION
865
1269
  };
866
1270
  // src/server/auth.ts
867
1271
  var cookie = () => config().cookieName;
@@ -1012,6 +1416,255 @@ async function authorizeApi(request) {
1012
1416
  const b = Buffer.from(token);
1013
1417
  return a.length === b.length && timingSafeEqual(a, b);
1014
1418
  }
1419
+ // src/server/explain.ts
1420
+ /** Handlers whose name says what the user did. Matched on the cleaned Hermes name. */
1421
+ var USER_ACTIONS = [
1422
+ [/^_?onRefresh$/, "pull to refresh"],
1423
+ [/^_?onPress([A-Z]\w*)?$|^_?handlePress([A-Z]\w*)?$/, "a tap"],
1424
+ [/^_?onLongPress$/, "a long press"],
1425
+ [/^_?onSubmit(Editing)?$|^_?handleSubmit([A-Z]\w*)?$/, "submitting a form"],
1426
+ [/^_?onChangeText$/, "typing"],
1427
+ [/^_?onEndReached$/, "scrolling to the end of a list"],
1428
+ [/^_?onValueChange$/, "changing a setting"]
1429
+ ];
1430
+ /** The first app frame that is a known user-action handler: `_onRefresh` → "pull to refresh". */
1431
+ function userAction(frames) {
1432
+ for (const f of frames ?? []) {
1433
+ if (f.inApp === false) continue;
1434
+ const fn = cleanFnName(f.fn);
1435
+ const known = fn && USER_ACTIONS.find(([re]) => re.test(fn));
1436
+ if (fn && known) return {
1437
+ fn,
1438
+ action: known[1]
1439
+ };
1440
+ }
1441
+ }
1442
+ var seconds = (ms) => ms < 1e3 ? `${Math.round(ms)} ms` : `${(ms / 1e3).toFixed(1)} s`;
1443
+ var plural$1 = (n, word) => `${n.toLocaleString()} ${word}${n === 1 ? "" : "s"}`;
1444
+ var cap = (s) => s.charAt(0).toUpperCase() + s.slice(1);
1445
+ var PLATFORM = {
1446
+ ios: "iPhone",
1447
+ android: "Android",
1448
+ web: "the web",
1449
+ macos: "Mac",
1450
+ windows: "Windows"
1451
+ };
1452
+ var platformName = (os) => PLATFORM[os] ?? os;
1453
+ /** A durations range: "16 ms", or "3–49 ms" across occurrences. */
1454
+ function durationText(ds) {
1455
+ const xs = ds.filter((d) => Number.isFinite(d) && d >= 0);
1456
+ if (!xs.length) return void 0;
1457
+ const lo = Math.min(...xs);
1458
+ const hi = Math.max(...xs);
1459
+ if (lo === hi || hi < 1e3) return lo === hi ? seconds(lo) : `${Math.round(lo)}–${Math.round(hi)} ms`;
1460
+ return `${seconds(lo)}–${seconds(hi)}`;
1461
+ }
1462
+ var VERB = /^(get|fetch|load|list|read|find|create|add|update|set|save|post|put|patch|delete|remove|check|validate|send|submit|sync)(?=[A-Z_-]|$)/;
1463
+ /**
1464
+ * What a request was for, in plain words, from its path: "/api/balance/getBalances" → "balances",
1465
+ * "/api/app-force-update" → "app force update". Undefined when the path says nothing.
1466
+ */
1467
+ function thingOf(url) {
1468
+ const last = url.split("?")[0].split("/").filter((p) => p && p !== ":id" && !/^v\d+$/.test(p)).pop();
1469
+ if (!last || last.includes(".")) return void 0;
1470
+ return last.replace(VERB, "").replace(/([a-z0-9])([A-Z])/g, "$1 $2").replace(/[-_]+/g, " ").trim().toLowerCase() || void 0;
1471
+ }
1472
+ /** "Balances", "Balances (Balance service)", "The app" — the subject of the summary. */
1473
+ function subject(e, service) {
1474
+ const thing = e?.request ? thingOf(e.request.url) : void 0;
1475
+ if (!thing) return {
1476
+ name: service ? `a request to ${service}` : e?.request ? "a request" : "the app",
1477
+ plural: false
1478
+ };
1479
+ return {
1480
+ name: service ? `${thing} (${service})` : thing,
1481
+ plural: /s$/.test(thing) && !/ss$/.test(thing)
1482
+ };
1483
+ }
1484
+ function stillHappening(i, rangeLabel, now) {
1485
+ if (i.status === "resolved") return "It's marked fixed.";
1486
+ if (i.status === "ignored") return "It's marked as ignored.";
1487
+ if (i.count24h > 0) return now - Date.parse(i.lastSeen) < 36e5 ? "It's still happening: last seen within the hour." : `It happened ${plural$1(i.count24h, "time")} in the last 24 hours.`;
1488
+ return `It hasn't happened in the last 24 hours (${plural$1(i.countRange, "time")} in ${rangeLabel}).`;
1489
+ }
1490
+ var PASS_TO = {
1491
+ app: "app team",
1492
+ backend: "backend team",
1493
+ infrastructure: "whoever runs the network and hosting",
1494
+ third_party: "whoever manages that third-party service",
1495
+ unknown: "app team first, to find out whose it is"
1496
+ };
1497
+ var TEMPLATES = {
1498
+ "network.offline": {
1499
+ saw: (n, are) => `${cap(n)} ${are === "are" ? "weren't" : "wasn't"} available`,
1500
+ why: () => "The phone was offline.",
1501
+ diagnosis: () => "No connection when the request was made.",
1502
+ fix: () => "Check connectivity before sending (NetInfo), queue the request until the phone is back online, and show an offline state."
1503
+ },
1504
+ "network.never_sent": {
1505
+ saw: (n) => `${cap(n)} didn't load`,
1506
+ why: (_ev, causes) => causes.includes("resumed_from_background") ? "The app had just been reopened and the phone hadn't reconnected yet. Not a server outage." : "The request failed on the phone before reaching the server. Not a server outage.",
1507
+ diagnosis: (_ev, took) => took ? `No HTTP status after ${took}: too fast to have reached a server.` : "No HTTP status, and too fast to have reached a server.",
1508
+ fix: (_ev, causes) => causes.includes("resumed_from_background") ? "Wait for the connection when the app returns to the foreground (NetInfo `isConnected` on AppState `active`) before sending, or retry idempotent requests once with a short backoff." : "Check connectivity before sending, and retry idempotent requests once with a short backoff."
1509
+ },
1510
+ "network.timeout": {
1511
+ saw: (n) => `${cap(n)} took too long and gave up`,
1512
+ why: () => "The request was sent but no answer came back in time: a slow network or a slow server.",
1513
+ diagnosis: (_ev, took) => `Timed out${took ? ` after ${took}` : ""} with no response.`,
1514
+ fix: () => "Check this endpoint's p95 under Response times. If the server is slow, fix it there; otherwise raise the timeout, retry idempotent requests, and show a retry state."
1515
+ },
1516
+ "network.failed": {
1517
+ saw: (n) => `${cap(n)} couldn't connect`,
1518
+ why: (ev) => ev.failedHosts.length > 1 ? "Several servers were unreachable at once, which points at the network." : "The phone couldn't reach the server.",
1519
+ diagnosis: (_ev, took) => `No HTTP status${took ? ` after ${took}` : ""}: DNS, TLS or a refused connection.`,
1520
+ fix: (ev) => ev.failedHosts.length > 1 ? "Several hosts failed together: check the network path (VPN, proxy, carrier) before the servers." : "Check the host resolves and its certificate is valid from the phone's network, and retry once with backoff."
1521
+ },
1522
+ auth: {
1523
+ saw: (n, are) => `${cap(n)} ${are === "are" ? "were" : "was"} refused`,
1524
+ why: (_ev, causes) => causes.includes("auth_expired") ? "The user's sign-in had expired." : "The server didn't accept the user's sign-in for this.",
1525
+ diagnosis: (ev) => `HTTP ${ev.status ?? "401/403"}.${ev.sameHostWorkedBefore ? " An earlier request to the same server succeeded, so the session ran out." : ""}`,
1526
+ fix: (_ev, causes) => causes.includes("auth_expired") ? "Refresh the token before it expires, or on a 401 refresh it and retry the request once." : "Check the token is sent with this request and is allowed for this endpoint."
1527
+ },
1528
+ server: {
1529
+ saw: (n) => `${cap(n)} failed with a server error`,
1530
+ why: () => "The server received the request and failed. The problem is on the server side.",
1531
+ diagnosis: (ev) => `HTTP ${ev.status ?? "5xx"} from the server.`,
1532
+ fix: () => "Check the backend logs for this endpoint at the times above. In the app, show a friendly error and let the user retry."
1533
+ },
1534
+ client_request: {
1535
+ saw: (n, are) => `${cap(n)} ${are === "are" ? "were" : "was"} rejected`,
1536
+ why: () => "The server refused what the app sent as invalid.",
1537
+ diagnosis: (ev) => `HTTP ${ev.status ?? "4xx"}: the request didn't match what the API expects.`,
1538
+ fix: () => "Compare the request the app sends (fields, types, headers) with what the API expects, and validate input before sending."
1539
+ },
1540
+ crash: {
1541
+ saw: () => "The app closed unexpectedly",
1542
+ why: () => "An error nobody caught closed the app.",
1543
+ diagnosis: () => "Fatal error from the global handler.",
1544
+ fix: () => "Open the culprit below, replay the breadcrumbs to reproduce, and add a guard or an error boundary around it."
1545
+ },
1546
+ screen_crash: {
1547
+ saw: () => "A screen failed to show and the error screen appeared instead",
1548
+ why: () => "Something on that screen broke while drawing. The rest of the app kept working.",
1549
+ diagnosis: () => "Caught by an error boundary while rendering.",
1550
+ fix: () => "Open the culprit below. Usually data the screen expects is missing or not loaded yet: add a loading state or a guard."
1551
+ },
1552
+ unhandled_rejection: {
1553
+ saw: () => "Something in the background failed",
1554
+ why: () => "Background work failed and nothing handled it, so whatever it was doing may not have happened.",
1555
+ diagnosis: () => "Unhandled promise rejection.",
1556
+ fix: () => "Find the promise at the culprit below and add a catch that handles or reports the failure."
1557
+ },
1558
+ uncaught: {
1559
+ saw: () => "Something failed while the user was using the app",
1560
+ why: () => "An error nobody caught. The app kept running.",
1561
+ diagnosis: () => "Uncaught, non-fatal error.",
1562
+ fix: () => "Open the culprit below and handle the error where it's thrown."
1563
+ },
1564
+ app_reported: {
1565
+ saw: () => "The app reported an error",
1566
+ why: () => "The app caught this itself and reported it.",
1567
+ diagnosis: () => "Reported with deBug.error().",
1568
+ fix: () => "See where the app reports it (culprit below) and decide whether the user needs to know."
1569
+ },
1570
+ other: {
1571
+ saw: () => "Something went wrong",
1572
+ why: () => "This error doesn't match a known kind yet.",
1573
+ diagnosis: () => "No category matched.",
1574
+ fix: () => "Start at the culprit below and use the breadcrumbs to replay what the user did."
1575
+ }
1576
+ };
1577
+ /** What each cause adds: a plain sentence for support, a step for the fix. */
1578
+ var CAUSE_LINES = {
1579
+ burst: { summary: () => "Several requests failed at the same moment." },
1580
+ slow_network: {
1581
+ summary: () => "The connection was slow.",
1582
+ fix: "Test on a throttled connection."
1583
+ },
1584
+ new_in_release: {
1585
+ summary: () => "It started in the latest version of the app.",
1586
+ fix: "Look at what changed in the latest release around the culprit."
1587
+ },
1588
+ regressed: {
1589
+ summary: () => "It was marked fixed, but it has come back.",
1590
+ fix: "The earlier fix didn't hold: compare with the release it was resolved in."
1591
+ },
1592
+ single_device: {
1593
+ summary: (x) => `It's only been seen on one phone model${x.model ? ` (${x.model})` : ""}.`,
1594
+ fix: "Reproduce on that model first."
1595
+ }
1596
+ };
1597
+ function explain(input) {
1598
+ const { issue, labels, rangeLabel } = input;
1599
+ const now = input.now ?? Date.now();
1600
+ const ev0 = input.lastEvent?.event;
1601
+ const e = ev0?.type === "error" ? ev0 : void 0;
1602
+ const ev = e ? evidenceOf(e) : NO_EVIDENCE;
1603
+ const t = TEMPLATES[labels.category] ?? TEMPLATES.other;
1604
+ const causes = labels.causes;
1605
+ const model = input.lastEvent?.context.device.model;
1606
+ const service = e?.request ? hostNameFor(e.request.url, input.hosts)?.host.name : void 0;
1607
+ const s = subject(e, service);
1608
+ const who = input.users ? ` for ${plural$1(input.users, "user")}` : "";
1609
+ const platforms = input.platforms?.length ? input.platforms : input.users === 1 && input.lastEvent ? [input.lastEvent.context.os.name] : [];
1610
+ const where = platforms.length ? ` on ${platforms.map(platformName).join(" and ")}` : "";
1611
+ const when = causes.includes("resumed_from_background") ? " right after reopening the app" : "";
1612
+ const action = userAction(e?.error.frames);
1613
+ const doing = action ? ` (after ${action.action})` : "";
1614
+ const causeSentences = causes.flatMap((c) => CAUSE_LINES[c]?.summary?.({ model }) ?? []);
1615
+ const summary = [
1616
+ `${t.saw(s.name, s.plural ? "are" : "is")}${who}${where}${when}${doing}.`,
1617
+ t.why(ev, causes),
1618
+ ...causeSentences,
1619
+ stillHappening(issue, rangeLabel, now),
1620
+ `Pass to: ${PASS_TO[labels.owner] ?? PASS_TO.unknown}${service && (labels.owner === "backend" || labels.owner === "third_party") ? ` (${service})` : ""}.`
1621
+ ].join(" ");
1622
+ const took = durationText(input.durations?.length ? input.durations : ev.durationMs !== void 0 ? [ev.durationMs] : []);
1623
+ const evidence = [t.diagnosis(ev, took)];
1624
+ if (e?.request) evidence.push(`Request: \`${e.request.method.toUpperCase()} ${e.request.url}\`${service ? ` (${service})` : ""}.`);
1625
+ if (causes.includes("resumed_from_background") && ev.msSinceForeground !== void 0) evidence.push(`The app came to the foreground ${seconds(ev.msSinceForeground)} before; no request has succeeded since.`);
1626
+ if (ev.failedBefore > 0) evidence.push(`${plural$1(ev.failedBefore, "other request")} failed in the 5 s before${ev.failedHosts.length > 1 ? `, across ${ev.failedHosts.length} hosts` : ""}.`);
1627
+ else if (ev.repeatedFailure) evidence.push("The same request had already failed just before.");
1628
+ if (causes.includes("slow_network")) evidence.push(`${ev.slowRecent} of the last 5 requests were slow.`);
1629
+ if (ev.inBackground) evidence.push("The app was in the background, so the user probably didn't see it.");
1630
+ for (const c of causes) if (CAUSE_LINES[c]?.fix) evidence.push(`${CAUSE_INFO[c].name}: ${CAUSE_INFO[c].description}`);
1631
+ if (issue.incidentTitle) evidence.push(`Part of the incident "${issue.incidentTitle}".`);
1632
+ const whereParts = [issue.culprit ? `\`${issue.culprit}\`` : void 0, action ? `started by \`${action.fn}\` (${action.action})` : void 0].filter(Boolean);
1633
+ const fixSteps = [t.fix(ev, causes), ...causes.flatMap((c) => CAUSE_LINES[c]?.fix ?? [])];
1634
+ return {
1635
+ summary,
1636
+ technical: {
1637
+ headline: `${CATEGORY_INFO[labels.category]?.name ?? labels.category} · owner: ${OWNER_INFO[labels.owner]?.name ?? labels.owner} · impact: ${IMPACT_INFO[labels.impact]?.name ?? labels.impact}`,
1638
+ evidence,
1639
+ where: whereParts.length ? whereParts.join(", ") : void 0,
1640
+ fix: fixSteps.join(" ")
1641
+ }
1642
+ };
1643
+ }
1644
+ /** The explanation as Markdown lines, without a title: for tickets and prefilled links. */
1645
+ function explanationLines(x) {
1646
+ return [
1647
+ "### What happened",
1648
+ x.summary,
1649
+ "",
1650
+ "### For developers",
1651
+ `**${x.technical.headline}**`,
1652
+ "",
1653
+ ...x.technical.evidence.map((l) => `- ${l}`),
1654
+ ...x.technical.where ? ["", `**Where:** ${x.technical.where}`] : [],
1655
+ "",
1656
+ `**Suggested fix:** ${x.technical.fix}`
1657
+ ];
1658
+ }
1659
+ /** The explanation as Markdown, for pasting into a Jira or Linear ticket by hand. */
1660
+ function explanationMarkdown(title, x, link) {
1661
+ return [
1662
+ `## ${title}`,
1663
+ ...link ? ["", `deBug: ${link}`] : [],
1664
+ "",
1665
+ ...explanationLines(x)
1666
+ ].join("\n");
1667
+ }
1015
1668
  // src/server/range.ts
1016
1669
  /** The date range a dashboard view covers, worked out from the URL (range=7d, or from/to). */
1017
1670
  var RANGE_PRESETS = [
@@ -1111,16 +1764,29 @@ var SUMMARY_FIELDS = {
1111
1764
  "totals.criticalIssues": "Issues whose 24h occurrence count meets the critical threshold.",
1112
1765
  "flows[]": "Parts of the app as tagged by the developer (e.g. auth.login). Sorted by severity, then errors24h, then errorsRange.",
1113
1766
  "flows[].failureRate": "failures/(failures+successes) in the range from events logged with an outcome. null when the app logs no outcomes for that flow.",
1114
- "issues[]": "Grouped errors seen in the range. Sorted by severity, then count24h, then countRange.",
1767
+ "issues[]": "Grouped errors seen in the range. Sorted by severity, then count24h, then countRange. Narrow with ?status=open|resolved|ignored|all (default all), ?flow=, ?category=, ?owner= and ?impact= (ids from breakdowns); an unknown value is a 400. _filter echoes what was applied.",
1115
1768
  "issues[].severity": "Derived from count24h using thresholds critical/high/medium.",
1769
+ "issues[].title": "Error name and message, with hosts named in Settings shown by their names.",
1116
1770
  "issues[].culprit": "Top in-app stack frame: function (file:line).",
1771
+ "incidents[]": "Issues that failed together for the same reason (a cause such as resumed_from_background or burst, a category and an OS), folded into one recurring problem across users and days. Most errors first. Key is stable across builds.",
1772
+ "incidents[].episodes": "Separate times it happened in the range (one per batch of events the SDK sent).",
1773
+ "incidents[].active": "false when every issue in it is resolved or ignored; the overview hides those.",
1774
+ "incidents[].issues": "The issues in the incident with their errors in the range.",
1775
+ "issues[].incident": "Key of the incident the latest occurrence belonged to, if any.",
1776
+ "issues[].explanation.summary": "What happened, in plain words for support: what the user saw, where, how many people, whether it's still happening and who to pass it to.",
1777
+ "issues[].explanation.technical": "For developers: category, owner and impact (headline), the evidence, where in the code and what started it, and a suggested fix.",
1778
+ "issues[].labels": "What kind of problem (category), who likely fixes it (owner), how badly it hurts users (impact: blocked, degraded, silent) and why (causes). Ids and rules: docs/taxonomy.md in the deBug repo.",
1779
+ "breakdowns.category": "Errors in the range by category (e.g. network.never_sent, server, crash).",
1780
+ "breakdowns.owner": "Errors in the range by likely owner: app, backend, infrastructure, third_party, unknown.",
1781
+ "breakdowns.impact": "Errors in the range by user impact: blocked, degraded, silent.",
1117
1782
  "trend[]": "Errors and non-error events per hour (24h), UTC day (up to 90 days) or week (longer).",
1118
- breakdowns: "Errors in the range split by OS, app version and device model.",
1783
+ breakdowns: "Errors in the range split by OS, app version, device model, network, country, and the labels category, owner and impact.",
1119
1784
  narrative: "Plain-language summary of what is going wrong in the range.",
1120
1785
  "health.crashFreeRate": "Share of sessions in the range with no fatal crash. Sessions are recorded automatically by the SDK.",
1121
1786
  "health.errorFreeRate": "Share of sessions in the range with no unhandled error.",
1122
1787
  "health.releases[]": "Crash-free and error-free rates per app version.",
1123
1788
  "health.endpoints[]": "HTTP endpoints whose requests failed most (5xx, timeouts, network errors), from automatic network capture.",
1789
+ "health.endpoints[].label": "The endpoint with its host's name from Settings, when it has one; endpoint stays the raw method and URL. Same for timings[].label.",
1124
1790
  "health.users": "Distinct users active since the start of the range (user id when set, else the install's anonymous id; stored hashed).",
1125
1791
  "health.crashFreeUsersRate": "Share of those users who didn't crash.",
1126
1792
  "issues[].status": "open, resolved, ignored, or regressed (seen again in the fixed release or later).",
@@ -1172,16 +1838,22 @@ async function buildSummary(store, appParam, thresholds, now = Date.now(), opts
1172
1838
  store.getRollups(app, "issueHour", hours(now, 48)[0], hourKey(now)),
1173
1839
  retentionFor(store, app, opts.retentionDays, now)
1174
1840
  ]);
1175
- const [releaseRows, stepRows, requestRows, latencyRows, networkRows, countryRows, appSettings] = await Promise.all([
1841
+ const [releaseRows, stepRows, requestRows, latencyRows, networkRows, countryRows, appSettings, categoryRows, ownerRows, impactRows, incidentRows, incidentIssueRows] = await Promise.all([
1176
1842
  store.getRollups(app, "release", dayKey(Date.parse(`${from}T00:00:00Z`) - 365 * DAY), to),
1177
1843
  store.getRollups(app, "flowStep", from, to),
1178
1844
  store.getRollups(app, "requests", from, to),
1179
1845
  store.getRollups(app, "latency", from, to),
1180
1846
  store.getRollups(app, "network", from, to),
1181
1847
  store.getRollups(app, "country", from, to),
1182
- store.getSettings(app).catch(() => null)
1848
+ store.getSettings(app).catch(() => null),
1849
+ store.getRollups(app, "category", from, to),
1850
+ store.getRollups(app, "owner", from, to),
1851
+ store.getRollups(app, "impact", from, to),
1852
+ store.getRollups(app, "incident", from, to),
1853
+ store.getRollups(app, "incidentIssue", from, to)
1183
1854
  ]);
1184
1855
  const criticalFlows = appSettings?.criticalFlows ?? [];
1856
+ const hosts = appSettings?.hosts ?? [];
1185
1857
  const critical = new Set(criticalFlows);
1186
1858
  const usersSince = hourly ? dayKey(now - DAY) : from;
1187
1859
  const [users, crashedUsers] = await Promise.all([countUsersSafe(store, app, "app", usersSince), countUsersSafe(store, app, "crash", usersSince)]);
@@ -1227,11 +1899,22 @@ async function buildSummary(store, appParam, thresholds, now = Date.now(), opts
1227
1899
  const issueRange = /* @__PURE__ */ new Map();
1228
1900
  for (const r of issueDays) issueRange.set(r.key, (issueRange.get(r.key) ?? 0) + r.errors);
1229
1901
  const rangeStart = hourly ? (/* @__PURE__ */ new Date(now - DAY)).toISOString() : `${from}T00:00:00.000Z`;
1230
- const versionsInRange = [...new Set(sessionRows.map((r) => r.key.split("|")[0]).filter((v) => v && v !== "unknown"))].sort(compareVersions);
1902
+ const versionsInRange = [...new Set(sessionRows.map((r) => r.key.split("|")[0]).filter((v) => v && v !== "unknown"))].sort(compareVersions$1);
1231
1903
  const latestVersion = versionsInRange[versionsInRange.length - 1] ?? null;
1232
- const issueRows = issues.filter((i) => i.lastSeen >= rangeStart && i.firstSeen <= `${to}T23:59:59.999Z`).map((i) => toIssueRow(i, issue24h.get(i.fingerprint) ?? 0, hourly ? issue24h.get(i.fingerprint) ?? 0 : issueRange.get(i.fingerprint) ?? 0, thresholds, latestVersion, critical)).sort(bySeverityThenCount);
1904
+ const issueRows = issues.filter((i) => i.lastSeen >= rangeStart && i.firstSeen <= `${to}T23:59:59.999Z`).map((i) => toIssueRow(i, issue24h.get(i.fingerprint) ?? 0, hourly ? issue24h.get(i.fingerprint) ?? 0 : issueRange.get(i.fingerprint) ?? 0, thresholds, latestVersion, criticalFlows, hosts)).sort(bySeverityThenCount);
1233
1905
  const active = issueRows.filter((i) => i.status !== "ignored" && i.status !== "resolved");
1234
1906
  await Promise.all(active.slice(0, 10).map(async (i) => i.users = await countUsersSafe(store, app, `issue:${i.fingerprint}`, usersSince)));
1907
+ const lastEvents = new Map(issues.map((i) => [i.fingerprint, i.lastEvent]));
1908
+ for (const row of issueRows) if (row.labels) row.explanation = explain({
1909
+ issue: row,
1910
+ labels: row.labels,
1911
+ lastEvent: lastEvents.get(row.fingerprint),
1912
+ users: row.users,
1913
+ hosts,
1914
+ rangeLabel: range.label,
1915
+ now
1916
+ });
1917
+ const incidents = await buildIncidents(incidentRows, incidentIssueRows, issueRows, hourly, (key) => countUsersSafe(store, app, `incident:${key}`, usersSince));
1235
1918
  const firstDay = /* @__PURE__ */ new Map();
1236
1919
  for (const r of releaseRows) {
1237
1920
  const cur = firstDay.get(r.key);
@@ -1310,18 +1993,22 @@ async function buildSummary(store, appParam, thresholds, now = Date.now(), opts
1310
1993
  trend,
1311
1994
  flows,
1312
1995
  issues: issueRows,
1996
+ incidents,
1313
1997
  breakdowns: {
1314
1998
  os: top(os),
1315
1999
  appVersion: top(appVersion),
1316
2000
  deviceModel: top(deviceModel),
1317
2001
  network: top(networkRows),
1318
- country: top(countryRows)
2002
+ country: top(countryRows),
2003
+ category: top(categoryRows),
2004
+ owner: top(ownerRows),
2005
+ impact: top(impactRows)
1319
2006
  },
1320
2007
  steps: buildSteps(stepRows),
1321
- timings: buildTimings(requestRows, latencyRows),
2008
+ timings: buildTimings(requestRows, latencyRows, hosts),
1322
2009
  criticalFlows,
1323
2010
  health: {
1324
- ...buildHealth(sessionRows, endpointRows, dayKey(now)),
2011
+ ...buildHealth(sessionRows, endpointRows, dayKey(now), hosts),
1325
2012
  users,
1326
2013
  crashedUsers,
1327
2014
  crashFreeUsersRate: users > 0 ? Math.max(0, 1 - crashedUsers / users) : null
@@ -1332,8 +2019,83 @@ async function buildSummary(store, appParam, thresholds, now = Date.now(), opts
1332
2019
  summary.narrative = narrate(summary);
1333
2020
  return summary;
1334
2021
  }
2022
+ /** "Requests failed on app resume (iOS)", from an incident key. */
2023
+ function incidentTitle(key) {
2024
+ const k = parseIncidentKey(key);
2025
+ if (!k) return key;
2026
+ const os = k.os === "ios" ? "iOS" : k.os === "android" ? "Android" : k.os;
2027
+ const requests = isRequestCategory(k.category);
2028
+ const what = CATEGORY_INFO[k.category]?.name ?? k.category;
2029
+ if (k.cause === "resumed_from_background") return `${requests ? "Requests failed" : what} on app resume (${os})`;
2030
+ if (k.cause === "burst") return `${what}: several requests at once (${os})`;
2031
+ return `${what}: ${CAUSE_INFO[k.cause]?.name.toLowerCase() ?? k.cause} (${os})`;
2032
+ }
2033
+ async function buildIncidents(rows, issueRows, issues, hourly, users) {
2034
+ const shown = new Map(issues.map((i) => [i.fingerprint, i]));
2035
+ const members = /* @__PURE__ */ new Map();
2036
+ for (const r of issueRows) {
2037
+ const k = parseIncidentIssueKey(r.key);
2038
+ if (!k || !shown.has(k.fingerprint)) continue;
2039
+ const m = members.get(k.incident) ?? /* @__PURE__ */ new Map();
2040
+ m.set(k.fingerprint, (m.get(k.fingerprint) ?? 0) + r.errors);
2041
+ members.set(k.incident, m);
2042
+ }
2043
+ const days = /* @__PURE__ */ new Map();
2044
+ for (const r of rows) {
2045
+ const d = days.get(r.key) ?? {
2046
+ episodes: 0,
2047
+ first: r.day,
2048
+ last: r.day
2049
+ };
2050
+ d.episodes += r.events;
2051
+ if (r.errors > 0 && r.day < d.first) d.first = r.day;
2052
+ if (r.errors > 0 && r.day > d.last) d.last = r.day;
2053
+ days.set(r.key, d);
2054
+ }
2055
+ const out = [];
2056
+ for (const [key, m] of members) {
2057
+ const k = parseIncidentKey(key);
2058
+ if (!k) continue;
2059
+ const list = [...m.entries()].map(([fingerprint, n]) => {
2060
+ const i = shown.get(fingerprint);
2061
+ return {
2062
+ fingerprint,
2063
+ title: i.title,
2064
+ errors: hourly ? Math.min(n, i.count24h) : n,
2065
+ status: i.status
2066
+ };
2067
+ }).filter((i) => i.errors > 0).sort((a, b) => b.errors - a.errors);
2068
+ if (!list.length) continue;
2069
+ const d = days.get(key);
2070
+ out.push({
2071
+ key,
2072
+ title: incidentTitle(key),
2073
+ ...k,
2074
+ errors: list.reduce((a, i) => a + i.errors, 0),
2075
+ episodes: d?.episodes ?? 0,
2076
+ users: 0,
2077
+ firstDay: d?.first ?? "",
2078
+ lastDay: d?.last ?? "",
2079
+ active: list.some((i) => i.status !== "resolved" && i.status !== "ignored"),
2080
+ issues: list.map(({ fingerprint, title, errors }) => ({
2081
+ fingerprint,
2082
+ title,
2083
+ errors
2084
+ }))
2085
+ });
2086
+ }
2087
+ out.sort((a, b) => b.errors - a.errors);
2088
+ const top = out.slice(0, 20);
2089
+ await Promise.all(top.map(async (i) => i.users = await users(i.key)));
2090
+ return top;
2091
+ }
1335
2092
  var rate = (bad, total) => total > 0 ? Math.max(0, 1 - bad / total) : null;
1336
- function buildHealth(sessionRows, endpointRows, today) {
2093
+ /** An endpoint key ("POST host/path") with its host's name, or undefined when the host has none. */
2094
+ function endpointLabel(endpoint, hosts) {
2095
+ const named = nameUrlsIn(endpoint, hosts);
2096
+ return named === endpoint ? void 0 : named;
2097
+ }
2098
+ function buildHealth(sessionRows, endpointRows, today, hosts = []) {
1337
2099
  const byVersion = /* @__PURE__ */ new Map();
1338
2100
  for (const r of sessionRows) {
1339
2101
  const [version = "unknown", status] = r.key.split("|");
@@ -1354,13 +2116,14 @@ function buildHealth(sessionRows, endpointRows, today) {
1354
2116
  ...v,
1355
2117
  crashFreeRate: rate(v.crashed, v.sessions),
1356
2118
  errorFreeRate: rate(v.errored, v.sessions)
1357
- })).filter((v) => v.sessions > 0).sort((a, b) => compareVersions(b.version, a.version)).slice(0, 8);
2119
+ })).filter((v) => v.sessions > 0).sort((a, b) => compareVersions$1(b.version, a.version)).slice(0, 8);
1358
2120
  const sum = (k) => [...byVersion.values()].reduce((a, v) => a + v[k], 0);
1359
2121
  const eps = /* @__PURE__ */ new Map();
1360
2122
  for (const r of endpointRows) {
1361
2123
  let e = eps.get(r.key);
1362
2124
  if (!e) eps.set(r.key, e = {
1363
2125
  endpoint: r.key,
2126
+ label: endpointLabel(r.key, hosts),
1364
2127
  failuresRange: 0,
1365
2128
  failures24h: 0
1366
2129
  });
@@ -1404,7 +2167,11 @@ function buildSteps(rows) {
1404
2167
  failureRate: s.successes + s.failures > 0 ? s.failures / (s.successes + s.failures) : null
1405
2168
  })).sort((a, b) => b.failures - a.failures || (b.failureRate ?? 0) - (a.failureRate ?? 0)).slice(0, 30);
1406
2169
  }
1407
- function buildTimings(requestRows, latencyRows) {
2170
+ function buildTimings(requestRows, latencyRows, hosts = []) {
2171
+ return endpointTimings(requestRows, latencyRows, hosts).sort((a, b) => b.requests - a.requests).slice(0, 10);
2172
+ }
2173
+ /** Requests, failures and p50/p95 per endpoint ("<METHOD> <url>"), from the SDK's per-minute request summaries. */
2174
+ function endpointTimings(requestRows, latencyRows, hosts = []) {
1408
2175
  const totals = /* @__PURE__ */ new Map();
1409
2176
  for (const r of requestRows) {
1410
2177
  const t = totals.get(r.key) ?? {
@@ -1428,24 +2195,50 @@ function buildTimings(requestRows, latencyRows) {
1428
2195
  const b = hist.get(endpoint) ?? [];
1429
2196
  return {
1430
2197
  endpoint,
2198
+ label: endpointLabel(endpoint, hosts),
1431
2199
  requests: t.requests,
1432
2200
  failed: t.failed,
1433
2201
  errorRate: t.requests ? t.failed / t.requests : 0,
1434
2202
  p50: percentileMs(b, .5),
1435
2203
  p95: percentileMs(b, .95)
1436
2204
  };
1437
- }).sort((a, b) => b.requests - a.requests).slice(0, 10);
2205
+ });
2206
+ }
2207
+ /**
2208
+ * An issue's labels: those ingest stored with its latest occurrence, or worked out now for
2209
+ * occurrences stored before the classifier existed, plus the causes that come from the issue.
2210
+ */
2211
+ function issueLabels(i, latestVersion, criticalFlows = [], hosts = []) {
2212
+ const ev = i.lastEvent?.event;
2213
+ const stored = i.lastEvent?.labels ?? (ev?.type === "error" ? classify(ev, {
2214
+ criticalFlows,
2215
+ hosts
2216
+ }) : void 0);
2217
+ if (!stored) return void 0;
2218
+ const owner = hostOwner(stored, ev?.type === "error" ? ev.request?.url : void 0, hosts);
2219
+ return withIssueCauses(owner === stored.owner ? stored : {
2220
+ ...stored,
2221
+ owner
2222
+ }, {
2223
+ status: i.status,
2224
+ firstVersion: i.firstVersion,
2225
+ latestVersion
2226
+ });
1438
2227
  }
1439
- function toIssueRow(i, count24h, countRange, t, latestVersion = null, critical = /* @__PURE__ */ new Set()) {
2228
+ function toIssueRow(i, count24h, countRange, t, latestVersion = null, criticalFlows = [], hosts = []) {
1440
2229
  const base = severityFromCount(count24h, t);
2230
+ const critical = new Set(criticalFlows);
1441
2231
  return {
2232
+ labels: issueLabels(i, latestVersion, criticalFlows, hosts),
2233
+ incident: i.lastEvent?.incident,
2234
+ incidentTitle: i.lastEvent?.incident ? incidentTitle(i.lastEvent.incident) : void 0,
1442
2235
  status: i.status ?? "open",
1443
2236
  resolvedIn: i.resolvedIn,
1444
2237
  firstVersion: i.firstVersion,
1445
2238
  lastVersion: i.lastVersion,
1446
2239
  newInLatest: !!latestVersion && i.firstVersion === latestVersion,
1447
2240
  fingerprint: i.fingerprint,
1448
- title: i.title,
2241
+ title: nameUrlsIn(i.title, hosts),
1449
2242
  culprit: i.culprit,
1450
2243
  flow: i.flow,
1451
2244
  severity: i.flow && critical.has(i.flow) && count24h > 0 ? BUMP[base] : base,
@@ -1489,7 +2282,7 @@ function narrate(s) {
1489
2282
  out.push(`${latest.version} is ${pctOne(latest.crashFreeRate)} crash-free across ${plural(latest.sessions, "session")}${vs}.`);
1490
2283
  }
1491
2284
  const ep = h.endpoints[0];
1492
- if (ep && ep.failuresRange > 0) out.push(`${ep.endpoint} is the most failing endpoint: ${plural(ep.failuresRange, "failed request")} in ${r.label}.`);
2285
+ if (ep && ep.failuresRange > 0) out.push(`${ep.label ?? ep.endpoint} is the most failing endpoint: ${plural(ep.failuresRange, "failed request")} in ${r.label}.`);
1493
2286
  const net = s.breakdowns.network.filter((r) => r.key !== "unknown");
1494
2287
  const netTotal = net.reduce((a, b) => a + b.errors, 0);
1495
2288
  if (net[0] && netTotal >= 20 && net[0].errors / netTotal > .6 && net[0].key !== "wifi") out.push(`${pct(net[0].errors / netTotal)} of errors happen on ${net[0].key}: check timeouts and retries on slow connections.`);
@@ -1507,11 +2300,12 @@ async function buildIssueDetail(store, app, fingerprint, thresholds, now = Date.
1507
2300
  if (!issue) return null;
1508
2301
  const range = resolveRange(opts.range ?? {}, now);
1509
2302
  const hs = hours(now, 48);
1510
- const [hourRows, dayRows, events, retention] = await Promise.all([
2303
+ const [hourRows, dayRows, events, retention, settings] = await Promise.all([
1511
2304
  store.getRollups(app, "issueHour", hs[0], hs[hs.length - 1]),
1512
2305
  store.getRollups(app, "issue", range.from, range.to),
1513
2306
  store.listIssueEvents(app, fingerprint, { limit: 200 }),
1514
- retentionFor(store, app, opts.retentionDays, now)
2307
+ retentionFor(store, app, opts.retentionDays, now),
2308
+ store.getSettings(app).catch(() => null)
1515
2309
  ]);
1516
2310
  const hourly = hs.map((hour) => ({
1517
2311
  hour,
@@ -1544,8 +2338,24 @@ async function buildIssueDetail(store, app, fingerprint, thresholds, now = Date.
1544
2338
  };
1545
2339
  const usersSince = range.preset === "24h" ? dayKey(now - DAY) : range.from;
1546
2340
  const affectedUsers = await countUsersSafe(store, app, `issue:${fingerprint}`, usersSince) || new Set(events.map((e) => e.user?.id ?? e.user?.anonymousId ?? e.sessionId)).size;
1547
- const row = toIssueRow(issue, count24h, countRange, thresholds);
1548
- const hints = hintsFor(issue, breakdowns, events);
2341
+ const criticalFlows = settings?.criticalFlows ?? [];
2342
+ const hosts = settings?.hosts ?? [];
2343
+ const row = toIssueRow(issue, count24h, countRange, thresholds, null, criticalFlows, hosts);
2344
+ if (row.labels) row.labels = withIssueCauses(row.labels, { deviceModels: events.map((e) => e.context.device.model) });
2345
+ const hints = hintsFor(issue, breakdowns, events, !!row.labels && isRequestCategory(row.labels.category), hosts);
2346
+ const errorEvents = events.filter((e) => e.event.type === "error");
2347
+ row.explanation = row.labels ? explain({
2348
+ issue: row,
2349
+ labels: row.labels,
2350
+ lastEvent: issue.lastEvent,
2351
+ users: affectedUsers,
2352
+ hosts,
2353
+ platforms: [...new Set(errorEvents.map((e) => e.context.os.name))],
2354
+ durations: errorEvents.flatMap((e) => e.event.type === "error" && e.event.request?.durationMs !== void 0 ? [e.event.request.durationMs] : []),
2355
+ rangeLabel: range.label,
2356
+ now
2357
+ }) : void 0;
2358
+ const link = issueUrl(opts.trackers?.dashboardUrl, app, fingerprint);
1549
2359
  const detail = {
1550
2360
  app,
1551
2361
  range,
@@ -1558,26 +2368,33 @@ async function buildIssueDetail(store, app, fingerprint, thresholds, now = Date.
1558
2368
  links: {},
1559
2369
  sample: events[0] ?? issue.lastEvent ?? null,
1560
2370
  recent: events.slice(0, 25).map((e) => ({
2371
+ id: e.event.id,
2372
+ type: e.event.type,
1561
2373
  ts: e.event.ts,
1562
2374
  os: `${e.context.os.name} ${e.context.os.version ?? ""}`.trim(),
1563
2375
  appVersion: e.context.app.version,
1564
2376
  device: e.context.device.model,
1565
- message: e.event.type === "error" ? e.event.error.message : e.event.type === "event" ? e.event.name : e.event.type === "session" ? `session ${e.event.status}` : `requests to ${e.event.key}`,
2377
+ message: e.event.type === "error" ? nameUrlsIn(e.event.error.message, hosts) : e.event.type === "event" ? e.event.name : e.event.type === "session" ? `session ${e.event.status}` : `requests to ${e.event.key}`,
1566
2378
  userId: e.user?.id
1567
2379
  })),
1568
- hints
2380
+ hints,
2381
+ ticketMarkdown: row.explanation ? explanationMarkdown(row.title, row.explanation, link) : void 0
1569
2382
  };
1570
2383
  detail.links = trackerLinks(detail, opts.trackers ?? {});
1571
2384
  return detail;
1572
2385
  }
2386
+ var issueUrl = (dashboardUrl, app, fp) => dashboardUrl ? `${dashboardUrl.replace(/\/+$/, "")}/issues/${fp}?app=${encodeURIComponent(app)}` : void 0;
1573
2387
  /** The issue as a ticket: what, where, how often, what to look at. Kept short enough for a URL. */
1574
2388
  function issueStory(d, dashboardUrl) {
1575
2389
  const i = d.issue;
2390
+ const x = i.explanation;
1576
2391
  const top = (rows) => rows.filter((r) => r.key !== "unknown").slice(0, 3).map((r) => `${r.key} (${Math.round(r.share * 100)}%)`).join(", ") || "n/a";
1577
2392
  const frames = d.sample?.event.type === "error" ? (d.sample.event.error.frames ?? []).filter((f) => f.inApp).slice(0, 3) : [];
1578
2393
  const body = [
1579
2394
  `**${i.title}**`,
1580
2395
  i.culprit ? `At \`${i.culprit}\`${i.flow ? ` in flow \`${i.flow}\`` : ""}.` : i.flow ? `In flow \`${i.flow}\`.` : "",
2396
+ ...dashboardUrl ? ["", `deBug: ${issueUrl(dashboardUrl, d.app, i.fingerprint)}`] : [],
2397
+ ...x ? ["", ...explanationLines(x)] : [],
1581
2398
  "",
1582
2399
  `- ${i.countRange.toLocaleString()} occurrences in ${d.range.label}, ${i.count24h} in the last 24h (severity: ${i.severity})`,
1583
2400
  `- ${d.affectedUsers.toLocaleString()} users affected`,
@@ -1591,10 +2408,9 @@ function issueStory(d, dashboardUrl) {
1591
2408
  ] : [],
1592
2409
  ...d.hints.length ? [
1593
2410
  "",
1594
- "What to look at:",
2411
+ x ? "Also worth checking:" : "What to look at:",
1595
2412
  ...d.hints.slice(0, 3).map((h) => `- ${h.title}: ${h.detail}`)
1596
- ] : [],
1597
- ...dashboardUrl ? ["", `deBug: ${dashboardUrl.replace(/\/+$/, "")}/issues/${i.fingerprint}?app=${encodeURIComponent(d.app)}`] : []
2413
+ ] : []
1598
2414
  ].filter((l, n, all) => !(l === "" && all[n - 1] === "")).join("\n");
1599
2415
  return {
1600
2416
  title: `[deBug] ${i.title}`.slice(0, 200),
@@ -1616,7 +2432,7 @@ function trackerLinks(d, t) {
1616
2432
  };
1617
2433
  }
1618
2434
  /** Rule-based "what to look at" hints. Phase 2 replaces/augments these with an LLM over the same data. */
1619
- function hintsFor(issue, b, events) {
2435
+ function hintsFor(issue, b, events, explained = false, hosts = []) {
1620
2436
  const hints = [];
1621
2437
  const text = `${issue.title} ${events[0]?.event.type === "error" ? events[0].event.error.stack ?? "" : ""}`.toLowerCase();
1622
2438
  const crumbs = events.flatMap((e) => e.event.type === "error" ? e.event.breadcrumbs ?? [] : []);
@@ -1634,11 +2450,11 @@ function hintsFor(issue, b, events) {
1634
2450
  title: "A value is missing when the code expects it",
1635
2451
  detail: `Something is null/undefined at ${issue.culprit ?? "the top frame"}. Check the data the previous step returns (API response shape, async state not yet loaded) and add a guard or loading state.`
1636
2452
  });
1637
- if (/network request failed|failed to fetch|networkerror|timeout|timed out|econn|socket/.test(text)) hints.push({
2453
+ if (!explained && /network request failed|failed to fetch|networkerror|timeout|timed out|econn|socket/.test(text)) hints.push({
1638
2454
  title: "Network failure",
1639
2455
  detail: "Check if errors line up with poor connectivity (see the network breakdown), add retries with backoff, and show an offline/timeout state instead of failing."
1640
2456
  });
1641
- if (/\b401\b|\b403\b|unauthori[sz]ed|forbidden|token expired|jwt/.test(text)) hints.push({
2457
+ if (!explained && /\b401\b|\b403\b|unauthori[sz]ed|forbidden|token expired|jwt/.test(text)) hints.push({
1642
2458
  title: "Auth/session problem",
1643
2459
  detail: "Look for expired or missing tokens. Confirm the token refresh runs before this call, and that the clock/expiry handling is right."
1644
2460
  });
@@ -1646,24 +2462,35 @@ function hintsFor(issue, b, events) {
1646
2462
  title: "Bad response body",
1647
2463
  detail: "The app tried to parse something that isn't the JSON it expected — often an HTML error page or an empty 204/5xx. Log the status and content-type before parsing."
1648
2464
  });
1649
- if (/\b5\d\d\b|internal server error|bad gateway|service unavailable/.test(text)) hints.push({
2465
+ if (!explained && /\b5\d\d\b|internal server error|bad gateway|service unavailable/.test(text)) hints.push({
1650
2466
  title: "Server-side failure",
1651
2467
  detail: "The backend returned a 5xx. Correlate the timestamps with your API logs."
1652
2468
  });
1653
2469
  const failingRequests = crumbs.filter((c) => c.category === "network" && (c.level === "error" || /\b[45]\d\d\b/.test(c.message)));
1654
- if (failingRequests.length) {
2470
+ if (failingRequests.length && !explained) {
1655
2471
  const m = /* @__PURE__ */ new Map();
1656
2472
  for (const c of failingRequests) m.set(c.message, (m.get(c.message) ?? 0) + 1);
1657
2473
  const [msg] = [...m.entries()].sort((a, b) => b[1] - a[1])[0];
1658
2474
  hints.push({
1659
2475
  title: "A request fails right before the error",
1660
- detail: `Most common: ${msg}`
2476
+ detail: `Most common: ${nameUrlsIn(msg, hosts)}`
1661
2477
  });
1662
2478
  }
1663
- if (hints.length === 0) hints.push({
2479
+ if (hints.length === 0 && !explained) hints.push({
1664
2480
  title: "Start at the culprit frame",
1665
2481
  detail: `Open ${issue.culprit ?? "the top stack frame"} and use the breadcrumbs below to replay what the user did.`
1666
2482
  });
1667
2483
  return hints;
1668
2484
  }
1669
- export { getLocalWriteStore as A, restampStep as C, writeIssueStatus as D, validRetention as E, config as M, writeRetention as O, readSettings as S, testAlert as T, CORS_HEADERS as _, authorizeApi as a, hashInviteToken as b, demoLoginEnabled as c, forgetMember as d, hashPassword as f, tooManyAttempts as g, startSession as h, DEMO_USER as i, getStore as j, writeSettings as k, endSession as l, recordFailure as m, buildIssueDetail as n, canManage as o, readSession as p, buildSummary as r, checkCredentials as s, SUMMARY_FIELDS as t, envOwnerEmails as u, ingest as v, settingsWriter as w, teamAction as x, parseIngestKeys as y };
2485
+ // src/server/errors.ts
2486
+ /** Firestore answers FAILED_PRECONDITION while an index deBug needs is missing or still building. */
2487
+ function isIndexError(message) {
2488
+ return /FAILED_PRECONDITION|requires an index|index is currently building/i.test(message);
2489
+ }
2490
+ /** A thrown Firestore error saying a composite index is missing (gRPC code 9), on the Firestore store only. */
2491
+ function isMissingIndex(e, store) {
2492
+ if (store !== "firestore") return false;
2493
+ const err = e;
2494
+ return (err?.code === 9 || err?.code === "failed-precondition") && /index/i.test(String(err?.message ?? ""));
2495
+ }
2496
+ export { seenHosts as A, ingest as C, teamAction as D, hashInviteToken as E, writeRetention as F, writeSettings as I, getLocalWriteStore as L, testAlert as M, validRetention as N, readSettings as O, writeIssueStatus as P, getStore as R, CORS_HEADERS as S, isRequestCategory as T, hashPassword as _, buildSummary as a, startSession as b, resolveRange as c, canManage as d, checkCredentials as f, forgetMember as g, envOwnerEmails as h, buildIssueDetail as i, settingsWriter as j, restampStep as k, DEMO_USER as l, endSession as m, isMissingIndex as n, endpointTimings as o, demoLoginEnabled as p, SUMMARY_FIELDS as r, retentionFor as s, isIndexError as t, authorizeApi as u, readSession as v, parseIngestKeys as w, tooManyAttempts as x, recordFailure as y, config as z };