@debugkit/dashboard 0.6.1 → 0.8.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 (58) hide show
  1. package/dist/client/assets/_authed-CNObwuZh.js +7 -0
  2. package/dist/client/assets/_authed-CuP-He8G.js +1 -0
  3. package/dist/client/assets/{charts-XyOWJI9T.js → charts-CUvev8lV.js} +7 -7
  4. package/dist/client/assets/copy-button-ORgLIh59.js +1 -0
  5. package/dist/client/assets/customers-DTMEprFQ.js +1 -0
  6. package/dist/client/assets/endpoints-lMSO2CdM.js +1 -0
  7. package/dist/client/assets/events._eventId-bWag-i8J.js +3 -0
  8. package/dist/client/assets/index-BNpacHyi.js +10 -0
  9. package/dist/client/assets/invite._token-CxXek2SP.js +1 -0
  10. package/dist/client/assets/issues._fingerprint-BQr85TVY.js +1 -0
  11. package/dist/client/assets/login-Dlk3GyyC.js +1 -0
  12. package/dist/client/assets/sessions._sessionId-3wNImMqM.js +1 -0
  13. package/dist/client/assets/settings-CzbEYB7k.js +1 -0
  14. package/dist/client/assets/src-Dq5mIUf0.js +3 -0
  15. package/dist/client/assets/styles-DPsgRH7g.css +2 -0
  16. package/dist/client/assets/team-Bud2-07A.js +1 -0
  17. package/dist/client/assets/timeline-BSDhQPpY.js +1 -0
  18. package/dist/client/assets/ui-CEv2y56s.js +1 -0
  19. package/dist/server/assets/{_authed-CrjuC0O3.js → _authed-DkkRwdZl.js} +19 -5
  20. package/dist/server/assets/{_authed-C-sIPXSO.js → _authed-DsB8kjZB.js} +318 -126
  21. package/dist/server/assets/_tanstack-start-manifest_v-D1_ErrJK.js +97 -0
  22. package/dist/server/assets/copy-button-D3RddzTw.js +52 -0
  23. package/dist/server/assets/customers-CvSLt_xV.js +163 -0
  24. package/dist/server/assets/{demo-BsMMDk_F.js → demo-BRTkdmQJ.js} +25 -4
  25. package/dist/server/assets/{dynamodb-Zkk1-mgz.js → dynamodb-B0V3ZO20.js} +45 -17
  26. package/dist/server/assets/endpoints-mPQXpH8C.js +371 -0
  27. package/dist/server/assets/{queries-BJxX3Kjp.js → errors-C2KEDL7l.js} +842 -62
  28. package/dist/server/assets/events._eventId-pkQBQ9sL.js +765 -0
  29. package/dist/server/assets/{firestore-C52q_vwM.js → firestore-Jd-LeWZI.js} +15 -6
  30. package/dist/server/assets/fns-B3PHbFwV.js +1295 -0
  31. package/dist/server/assets/{fns-DwGaMi8S.js → fns-Di0vMpkQ.js} +25 -3
  32. package/dist/server/assets/{invite._token-xnpnkdRv.js → invite._token-LwWF5YxP.js} +3 -3
  33. package/dist/server/assets/{issues._fingerprint-e7ubdJf0.js → issues._fingerprint-DAA0QCuA.js} +89 -11
  34. package/dist/server/assets/{login-EopnOJXA.js → login-DqjCU4DJ.js} +3 -3
  35. package/dist/server/assets/{memory-BssaqdZm.js → memory-aqsrtEUn.js} +377 -26
  36. package/dist/server/assets/router-C0Dauj2C.js +510 -0
  37. package/dist/server/assets/sessions._sessionId-D7JPV0M4.js +264 -0
  38. package/dist/server/assets/{settings-CaJN69N6.js → settings-Drjd64d7.js} +165 -5
  39. package/dist/server/assets/{src-D83GYTrp.js → src-C4fNgijW.js} +1 -1
  40. package/dist/server/assets/{team-B1UcM1jA.js → team-D7iXYnSE.js} +3 -3
  41. package/dist/server/assets/timeline-MDRNDhiA.js +132 -0
  42. package/dist/server/assets/{ui-BJokJdYa.js → ui-B_XHlLUQ.js} +53 -13
  43. package/dist/server/server.js +37 -21
  44. package/package.json +4 -4
  45. package/dist/client/assets/_authed-BN39b-7H.js +0 -1
  46. package/dist/client/assets/_authed-CspAf0jN.js +0 -7
  47. package/dist/client/assets/index-Bfb2UOzB.js +0 -10
  48. package/dist/client/assets/invite._token-B4HN51-h.js +0 -1
  49. package/dist/client/assets/issues._fingerprint-BV1QrETY.js +0 -1
  50. package/dist/client/assets/login-COlvJ5Je.js +0 -1
  51. package/dist/client/assets/preload-helper-Dscj_TcA.js +0 -3
  52. package/dist/client/assets/settings-Dl4EWeWC.js +0 -1
  53. package/dist/client/assets/styles-DztngwT9.css +0 -2
  54. package/dist/client/assets/team-7Zekz_Er.js +0 -1
  55. package/dist/client/assets/ui-C0HGOza2.js +0 -1
  56. package/dist/server/assets/_tanstack-start-manifest_v-CqaE4wze.js +0 -61
  57. package/dist/server/assets/fns-mbUIXXep.js +0 -529
  58. 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 cleanFnName, S as OWNER_INFO, _ as validHostNames, a as Envelope, b as IMPACT_INFO, c as compareVersions, d as percentileMs, f as releaseKey, g as normaliseHostMatch, h as nameUrlsIn, m as hostNameFor, o as DEFAULT_SEVERITY_THRESHOLDS, p as severityFromCount, s as SEVERITY_ORDER, u as parseStack, v as CATEGORY_INFO, w as markLibraryFrames, y as CAUSE_INFO } from "./memory-aqsrtEUn.js";
3
+ import { n as TEAM_ROLES, t as MAX_RETENTION_DAYS } from "./src-C4fNgijW.js";
4
4
  import { createHash, createHmac, randomBytes, scryptSync, timingSafeEqual } from "node:crypto";
5
5
  // src/server/config.ts
6
6
  var loaded = false;
@@ -75,22 +75,22 @@ async function create() {
75
75
  case "firestore": {
76
76
  const { initializeApp, getApps } = await import("firebase-admin/app");
77
77
  const { getFirestore } = await import("firebase-admin/firestore");
78
- const { FirestoreStore } = await import("./firestore-C52q_vwM.js");
78
+ const { FirestoreStore } = await import("./firestore-Jd-LeWZI.js");
79
79
  if (!getApps().length) initializeApp();
80
80
  return new FirestoreStore(getFirestore(), { root: cfg.firestoreRoot });
81
81
  }
82
82
  case "dynamodb": {
83
83
  const { DynamoDBClient } = await import("@aws-sdk/client-dynamodb");
84
84
  const { DynamoDBDocumentClient } = await import("@aws-sdk/lib-dynamodb");
85
- const { DynamoStore } = await import("./dynamodb-Zkk1-mgz.js");
85
+ const { DynamoStore } = await import("./dynamodb-B0V3ZO20.js");
86
86
  return new DynamoStore(DynamoDBDocumentClient.from(new DynamoDBClient({})), { table: cfg.dynamoTable });
87
87
  }
88
88
  case "memory": {
89
- const { MemoryStore } = await import("./memory-BssaqdZm.js").then((n) => n.n);
89
+ const { MemoryStore } = await import("./memory-aqsrtEUn.js").then((n) => n.n);
90
90
  return new MemoryStore();
91
91
  }
92
92
  default: {
93
- const { seedDemo } = await import("./demo-BsMMDk_F.js");
93
+ const { seedDemo } = await import("./demo-BRTkdmQJ.js");
94
94
  return seedDemo();
95
95
  }
96
96
  }
@@ -127,6 +127,7 @@ async function readSettings(app) {
127
127
  retentionDays: out.retentionDays,
128
128
  criticalFlows: out.settings?.criticalFlows ?? [],
129
129
  alerts: out.settings?.alerts ?? {},
130
+ hosts: out.settings?.hosts ?? [],
130
131
  source: out.settings?.retentionDays ? "setting" : "default",
131
132
  updatedAt: out.settings?.updatedAt,
132
133
  writer
@@ -137,6 +138,7 @@ async function readSettings(app) {
137
138
  retentionDays: c.retentionDays ?? null,
138
139
  criticalFlows: [],
139
140
  alerts: {},
141
+ hosts: [],
140
142
  source: c.retentionDays ? "default" : "unknown",
141
143
  writer,
142
144
  note: `Couldn't reach the ingest function: ${err.message}`
@@ -152,12 +154,26 @@ async function readSettings(app) {
152
154
  ...s?.alerts,
153
155
  slackWebhookUrl: hook ? `https://hooks.slack.com/…${hook.slice(-4)}` : void 0
154
156
  },
157
+ hosts: s?.hosts ?? [],
155
158
  source: s?.retentionDays ? "setting" : c.retentionDays || writer === "local" ? "default" : "unknown",
156
159
  updatedAt: s?.updatedAt,
157
160
  writer,
158
161
  note: writer === "none" ? "Changing settings needs DEBUG_ADMIN_URL and DEBUG_ADMIN_TOKEN (npx debugkit init sets them)." : void 0
159
162
  };
160
163
  }
164
+ /** Hosts the app called in the last 30 days, busiest first: suggestions for naming them. */
165
+ async function seenHosts(app, now = Date.now()) {
166
+ const day = (t) => new Date(t).toISOString().slice(0, 10);
167
+ const store = await getStore();
168
+ const [from, to] = [day(now - 2592e6), day(now)];
169
+ const [timed, failed] = await Promise.all([store.getRollups(app, "requests", from, to).catch(() => []), store.getRollups(app, "endpoint", from, to).catch(() => [])]);
170
+ const counts = /* @__PURE__ */ new Map();
171
+ for (const r of [...timed, ...failed]) {
172
+ const host = normaliseHostMatch(r.key.split(" ")[1] ?? "").split("/")[0];
173
+ if (host) counts.set(host, (counts.get(host) ?? 0) + r.events + r.errors);
174
+ }
175
+ return [...counts.entries()].sort((a, b) => b[1] - a[1]).slice(0, 30).map(([h]) => h);
176
+ }
161
177
  function validRetention(days) {
162
178
  const n = Number(days);
163
179
  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 +189,7 @@ async function writeRetention(app, days) {
173
189
  else throw new Error("Settings can't be changed from this dashboard: DEBUG_ADMIN_URL and DEBUG_ADMIN_TOKEN aren't set.");
174
190
  return readSettings(app);
175
191
  }
176
- /** Change critical flows and/or alert settings. Validation happens in the ingest function (or here, locally). */
192
+ /** Change critical flows, alert settings and/or host names. Validation happens in the ingest function (or here, locally). */
177
193
  async function writeSettings(app, patch) {
178
194
  const writer = settingsWriter();
179
195
  if (writer === "admin") await admin("PUT", "/settings", {
@@ -185,13 +201,16 @@ async function writeSettings(app, patch) {
185
201
  const cur = await store.getSettings(app);
186
202
  const url = patch.alerts?.slackWebhookUrl;
187
203
  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/…).");
204
+ const hosts = patch.hosts ? validHostNames(patch.hosts) : void 0;
205
+ if (typeof hosts === "string") throw new Error(hosts);
188
206
  const alerts = patch.alerts ? {
189
207
  ...patch.alerts,
190
208
  slackWebhookUrl: url?.includes("…") ? cur?.alerts?.slackWebhookUrl : url || void 0
191
209
  } : void 0;
192
210
  await store.putSettings(app, {
193
211
  ...patch.criticalFlows ? { criticalFlows: patch.criticalFlows } : {},
194
- ...alerts ? { alerts } : {}
212
+ ...alerts ? { alerts } : {},
213
+ ...hosts ? { hosts } : {}
195
214
  });
196
215
  } else throw new Error("Settings can't be changed from this dashboard: DEBUG_ADMIN_URL and DEBUG_ADMIN_TOKEN aren't set.");
197
216
  return readSettings(app);
@@ -415,12 +434,13 @@ async function sendAlerts(app, outcome, issues, settings, post = defaultPost) {
415
434
  const u = issues.get(fp);
416
435
  if (!u) continue;
417
436
  const link = a.dashboardUrl ? `${a.dashboardUrl.replace(/\/+$/, "")}/issues/${fp}?app=${encodeURIComponent(app)}` : void 0;
437
+ const title = nameUrlsIn(u.title, settings?.hosts);
418
438
  const where = [
419
439
  u.culprit && `\`${u.culprit}\``,
420
440
  u.flow && `flow \`${u.flow}\`${critical.has(u.flow) ? " (critical)" : ""}`,
421
441
  u.version && `version ${u.version}`
422
442
  ].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}` : ""}`;
443
+ const text = `${kind === "new" ? ":new: New issue" : ":rotating_light: Regressed"} in *${app}*: ${link ? `<${link}|${title}>` : title}${where ? `\n${where}` : ""}`;
424
444
  try {
425
445
  await post(a.slackWebhookUrl, { text });
426
446
  sent++;
@@ -556,6 +576,287 @@ function countryOf(ctx) {
556
576
  if (tz) return tz;
557
577
  return /[-_]([A-Z]{2})(?:\b|$)/.exec(ctx.locale ?? "")?.[1] ?? "unknown";
558
578
  }
579
+ // ../../packages/ingest/src/classify.ts
580
+ var FOREGROUND = "App came to the foreground";
581
+ var BACKGROUND = "App went to the background";
582
+ var NEVER_SENT_MS = 100;
583
+ /** How long after reopening a failure still counts as "on resume", if nothing has succeeded since. */
584
+ var RESUME_WINDOW_MS = 1e4;
585
+ var CRASH_SOURCES = /* @__PURE__ */ new Set(["global-handler", "uncaughtException"]);
586
+ var REJECTION_SOURCES = /* @__PURE__ */ new Set([
587
+ "unhandled-rejection",
588
+ "unhandledrejection",
589
+ "unhandledRejection"
590
+ ]);
591
+ /** "GET host/path → 200 (93ms)", as the SDK writes network breadcrumbs. */
592
+ var NETWORK_CRUMB = /^\S+ (\S+) → /;
593
+ /** "GET host/path timed out", optionally followed by ": <cause>", as the SDK writes a timed-out request. */
594
+ var TIMED_OUT = /^\S+ \S+ timed out(?::|$)/;
595
+ var hostOf = (url) => url.replace(/^[a-z]+:\/\//i, "").split("/")[0] ?? "";
596
+ function crumbRequest(b) {
597
+ if (b.category !== "network") return void 0;
598
+ const m = NETWORK_CRUMB.exec(b.message);
599
+ if (!m) return void 0;
600
+ const status = typeof b.data?.status === "number" ? b.data.status : void 0;
601
+ return {
602
+ url: m[1],
603
+ status,
604
+ failed: b.level === "error"
605
+ };
606
+ }
607
+ /** A request that got a good answer: 2xx or 3xx. */
608
+ var succeeded = (r) => !r.failed && r.status !== void 0 && r.status < 400;
609
+ /**
610
+ * The breadcrumbs before this error. The SDK records a failed request's own breadcrumb just
611
+ * before reporting it; that one is the error, not something that happened before it. The SDK
612
+ * also merges identical breadcrumbs in a row into one with `data.repeated`: when the error's own
613
+ * breadcrumb says so, the same request had already failed just before.
614
+ */
615
+ function earlierCrumbs(e) {
616
+ const crumbs = e.breadcrumbs ?? [];
617
+ const r = e.request;
618
+ if (!r) return {
619
+ crumbs,
620
+ repeatedFailure: false
621
+ };
622
+ const own = `${r.method} ${r.url} → `.toUpperCase();
623
+ for (let i = crumbs.length - 1; i >= 0; i--) {
624
+ const b = crumbs[i];
625
+ if (b.category === "network" && b.level === "error" && b.message.toUpperCase().startsWith(own)) return {
626
+ crumbs: [...crumbs.slice(0, i), ...crumbs.slice(i + 1)],
627
+ repeatedFailure: Number(b.data?.repeated ?? 1) > 1
628
+ };
629
+ }
630
+ return {
631
+ crumbs,
632
+ repeatedFailure: false
633
+ };
634
+ }
635
+ function category(e) {
636
+ const r = e.request;
637
+ const source = e.tags?.source;
638
+ if (r && r.status === void 0) {
639
+ if (TIMED_OUT.test(e.error.message)) return "network.timeout";
640
+ if (r.durationMs !== void 0 && r.durationMs < NEVER_SENT_MS) return "network.never_sent";
641
+ return "network.failed";
642
+ }
643
+ if (r?.status !== void 0) {
644
+ if (r.status === 401 || r.status === 403) return "auth";
645
+ if (r.status >= 500 && r.status <= 599) return "server";
646
+ if (r.status >= 400 && r.status <= 499) return "client_request";
647
+ }
648
+ if (!e.handled && source && CRASH_SOURCES.has(source) && e.severity === "critical") return "crash";
649
+ if (source === "error-boundary") return "screen_crash";
650
+ if (source && REJECTION_SOURCES.has(source)) return "unhandled_rejection";
651
+ if (!e.handled) return "uncaught";
652
+ if (!r) return "app_reported";
653
+ return "other";
654
+ }
655
+ /** The last foreground/background breadcrumb before the error. */
656
+ function lastLifecycle(crumbs) {
657
+ for (let i = crumbs.length - 1; i >= 0; i--) {
658
+ const b = crumbs[i];
659
+ if (b.category === "ui" && (b.message === FOREGROUND || b.message === BACKGROUND)) return b;
660
+ }
661
+ }
662
+ function gather(e, crumbs, repeatedFailure) {
663
+ const at = Date.parse(e.ts);
664
+ const within = (b, ms) => {
665
+ const d = at - Date.parse(b.ts);
666
+ return d >= 0 && d <= ms;
667
+ };
668
+ const requests = crumbs.map((b) => ({
669
+ b,
670
+ r: crumbRequest(b)
671
+ })).filter((x) => !!x.r);
672
+ const life = lastLifecycle(crumbs);
673
+ const foreground = life?.message === FOREGROUND ? Date.parse(life.ts) : void 0;
674
+ const burst = requests.filter((x) => x.r.failed && within(x.b, 5e3));
675
+ const hosts = new Set(burst.map((x) => hostOf(x.r.url)));
676
+ if (e.request && (burst.length || repeatedFailure)) hosts.add(hostOf(e.request.url));
677
+ const host = e.request ? hostOf(e.request.url) : void 0;
678
+ return {
679
+ durationMs: e.request?.durationMs,
680
+ status: e.request?.status,
681
+ msSinceForeground: foreground !== void 0 && at >= foreground ? at - foreground : void 0,
682
+ workedSinceForeground: foreground !== void 0 && requests.some((x) => Date.parse(x.b.ts) >= foreground && succeeded(x.r)),
683
+ inBackground: life?.message === BACKGROUND,
684
+ failedBefore: burst.length,
685
+ failedHosts: [...hosts],
686
+ repeatedFailure,
687
+ slowRecent: requests.slice(-5).filter((x) => x.b.level === "warning").length,
688
+ sameHostWorkedBefore: !!host && requests.some((x) => hostOf(x.r.url) === host && succeeded(x.r))
689
+ };
690
+ }
691
+ /** Evidence for when there's no error event to measure (e.g. it has expired). */
692
+ var NO_EVIDENCE = {
693
+ workedSinceForeground: false,
694
+ inBackground: false,
695
+ failedBefore: 0,
696
+ failedHosts: [],
697
+ repeatedFailure: false,
698
+ slowRecent: 0,
699
+ sameHostWorkedBefore: false
700
+ };
701
+ /** The evidence behind an error's labels. */
702
+ function evidenceOf(e) {
703
+ const { crumbs, repeatedFailure } = earlierCrumbs(e);
704
+ return gather(e, crumbs, repeatedFailure);
705
+ }
706
+ function eventCauses(cat, ev) {
707
+ const causes = [];
708
+ if (ev.msSinceForeground !== void 0 && ev.msSinceForeground <= RESUME_WINDOW_MS && !ev.workedSinceForeground) causes.push("resumed_from_background");
709
+ if (ev.failedBefore >= 1 || ev.repeatedFailure) causes.push("burst");
710
+ if (ev.slowRecent >= 2) causes.push("slow_network");
711
+ if (cat === "auth" && ev.sameHostWorkedBefore) causes.push("auth_expired");
712
+ return causes;
713
+ }
714
+ function owner(cat, causes, burstHosts) {
715
+ switch (cat) {
716
+ case "network.never_sent":
717
+ case "client_request":
718
+ case "crash":
719
+ case "screen_crash":
720
+ case "unhandled_rejection":
721
+ case "uncaught":
722
+ case "app_reported": return "app";
723
+ case "server": return "backend";
724
+ case "auth": return causes.includes("auth_expired") ? "app" : "unknown";
725
+ case "network.timeout":
726
+ case "network.failed": return causes.includes("burst") && burstHosts.length > 1 ? "infrastructure" : "unknown";
727
+ default: return "unknown";
728
+ }
729
+ }
730
+ /**
731
+ * The owner Settings gives the request's host, where the rules can't tell on their own: server
732
+ * errors (the backend by default, but the host may be a third party's), and failed, timed-out
733
+ * or refused requests the rules leave as unknown. Never overrides "app" (the request didn't reach
734
+ * the server, or the app sent it wrong) or "infrastructure" (many hosts failed at once).
735
+ *
736
+ * Safe to run again on labels it already changed: an owner no rule gives these categories came
737
+ * from a host, so it's reset first. Changing or removing the host's owner later takes effect.
738
+ */
739
+ function hostOwner(labels, url, hosts) {
740
+ const { category, owner } = labels;
741
+ if (!(category === "server" || category === "network.timeout" || category === "network.failed" || category === "auth")) return owner;
742
+ const rule = category === "server" ? "backend" : owner === "app" || owner === "infrastructure" ? owner : "unknown";
743
+ const named = url ? hostNameFor(url, hosts)?.host.owner : void 0;
744
+ return named && (category === "server" || rule === "unknown") ? named : rule;
745
+ }
746
+ function impact(e, cat, ev, critical) {
747
+ if (cat === "crash" || e.flow && critical.has(e.flow)) return "blocked";
748
+ if (ev.inBackground) return "silent";
749
+ if (cat === "app_reported" && !e.flow) return "silent";
750
+ return "degraded";
751
+ }
752
+ /**
753
+ * `e.ts` must be the device's own time, as sent: breadcrumbs carry device time too, and the time
754
+ * rules compare the two. Ingest pins skewed clocks to the server's time for storage; classify
755
+ * before that.
756
+ */
757
+ function classify(e, opts = {}) {
758
+ const ev = evidenceOf(e);
759
+ const cat = category(e);
760
+ const causes = eventCauses(cat, ev);
761
+ return {
762
+ category: cat,
763
+ owner: hostOwner({
764
+ category: cat,
765
+ owner: owner(cat, causes, ev.failedHosts)
766
+ }, e.request?.url, opts.hosts),
767
+ impact: impact(e, cat, ev, new Set(opts.criticalFlows ?? [])),
768
+ causes
769
+ };
770
+ }
771
+ var SINGLE_DEVICE_MIN = 5;
772
+ function issueCauses(f) {
773
+ const causes = [];
774
+ if (f.latestVersion && f.firstVersion === f.latestVersion) causes.push("new_in_release");
775
+ if (f.status === "regressed") causes.push("regressed");
776
+ const models = f.deviceModels ?? [];
777
+ if (models.length >= SINGLE_DEVICE_MIN && models[0] && models.every((m) => m === models[0])) causes.push("single_device");
778
+ return causes;
779
+ }
780
+ /** An error's labels with its issue's causes added, without repeats. */
781
+ function withIssueCauses(labels, f) {
782
+ const extra = issueCauses(f).filter((c) => !labels.causes.includes(c));
783
+ return extra.length ? {
784
+ ...labels,
785
+ causes: [...labels.causes, ...extra]
786
+ } : labels;
787
+ }
788
+ // ../../packages/ingest/src/incidents.ts
789
+ /**
790
+ * Incidents fold issues that fail together for the same reason into one problem: the six
791
+ * requests that failed when the app reopened are one incident, not four issues.
792
+ *
793
+ * An incident is a recurring problem across users and days, not one episode: the key is the
794
+ * cause, the category and the OS, never a fingerprint or a session, so it stays the same across
795
+ * builds and releases ("resumed_from_background|network.never_sent|ios"). Issues stay the unit for
796
+ * resolving and regressions; incidents sit above them.
797
+ */
798
+ /** Causes that tie several errors together, most telling first. */
799
+ var GROUPING_CAUSES = ["resumed_from_background", "burst"];
800
+ var REQUEST_CATEGORIES = /* @__PURE__ */ new Set([
801
+ "network.offline",
802
+ "network.timeout",
803
+ "network.never_sent",
804
+ "network.failed",
805
+ "auth",
806
+ "server",
807
+ "client_request"
808
+ ]);
809
+ /** Categories for a failed request: the only ones a burst makes an incident of. */
810
+ var isRequestCategory = (c) => REQUEST_CATEGORIES.has(c);
811
+ var SEP = "|";
812
+ function incidentKey(labels, os) {
813
+ const cause = GROUPING_CAUSES.find((c) => labels.causes.includes(c) && (c !== "burst" || isRequestCategory(labels.category)));
814
+ if (!cause) return void 0;
815
+ const osPart = os.toLowerCase().replaceAll(SEP, " ").trim() || "unknown";
816
+ return [
817
+ cause,
818
+ labels.category,
819
+ osPart
820
+ ].join(SEP);
821
+ }
822
+ function parseIncidentKey(key) {
823
+ const [cause, category, os, ...rest] = key.split(SEP);
824
+ return cause && category && os && !rest.length ? {
825
+ cause,
826
+ category,
827
+ os
828
+ } : void 0;
829
+ }
830
+ /** "<incident key>|<fingerprint>", the key of the incidentIssue rollup. */
831
+ var incidentIssueKey = (incident, fingerprint) => `${incident}${SEP}${fingerprint}`;
832
+ function parseIncidentIssueKey(key) {
833
+ const cut = key.lastIndexOf(SEP);
834
+ if (cut <= 0 || !parseIncidentKey(key.slice(0, cut))) return void 0;
835
+ return {
836
+ incident: key.slice(0, cut),
837
+ fingerprint: key.slice(cut + 1)
838
+ };
839
+ }
840
+ /**
841
+ * Give each error in one batch its incident. An error's own labels decide first. Then the first
842
+ * failure of a burst, which can't know the others are coming, joins a burst incident of the same
843
+ * category that starts within BURST_WINDOW_MS after it. Only errors whose own incident is a burst
844
+ * pull others in (never a resume incident: an earlier error didn't fail on resume), so the result
845
+ * doesn't depend on the batch's order and never chains.
846
+ */
847
+ function assignIncidents(errors, os) {
848
+ for (const e of errors) e.incident = incidentKey(e.labels, os);
849
+ const anchors = errors.filter((e) => parseIncidentKey(e.incident ?? "")?.cause === "burst").map((e) => ({
850
+ at: Date.parse(e.ts),
851
+ e
852
+ }));
853
+ for (const e of errors) {
854
+ if (e.incident || !isRequestCategory(e.labels.category)) continue;
855
+ const at = Date.parse(e.ts);
856
+ const anchor = anchors.find((a) => a.e.labels.category === e.labels.category && a.at - at >= 0 && a.at - at <= 5e3);
857
+ if (anchor) e.incident = anchor.e.incident;
858
+ }
859
+ }
559
860
  // ../../packages/ingest/src/fingerprint.ts
560
861
  /** Strip volatile parts so "User 123 not found" and "User 456 not found" group together. */
561
862
  function normaliseMessage(msg) {
@@ -586,7 +887,8 @@ function culpritOf(e) {
586
887
  const f = topInAppFrame(e.error.frames);
587
888
  if (!f) return void 0;
588
889
  const loc = normaliseFile(f.file) + (f.line ? `:${f.line}` : "");
589
- return f.fn ? `${f.fn} (${loc})` : loc;
890
+ const fn = cleanFnName(f.fn);
891
+ return fn ? `${fn} (${loc})` : loc;
590
892
  }
591
893
  /**
592
894
  * Fingerprint = error name + top in-app frame (function + file, not line, so small edits
@@ -595,7 +897,7 @@ function culpritOf(e) {
595
897
  function fingerprint(e) {
596
898
  const f = topInAppFrame(e.error.frames);
597
899
  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);
900
+ 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
901
  return createHash("sha256").update([
600
902
  e.error.name,
601
903
  where,
@@ -690,12 +992,31 @@ async function ingest(rawBody, ingestKey, opts) {
690
992
  const issues = /* @__PURE__ */ new Map();
691
993
  /** Where this envelope's user counts: "app", "crash", "issue:<fp>". */
692
994
  const scopes = /* @__PURE__ */ new Set();
995
+ const storedEvent = (day, event, fingerprint, labels) => ({
996
+ app,
997
+ day,
998
+ fingerprint,
999
+ labels,
1000
+ event,
1001
+ context,
1002
+ user: env.user,
1003
+ sessionId: env.session.id,
1004
+ receivedAt
1005
+ });
1006
+ const settings = env.events.some((e) => e.type === "error") ? await cachedSettings(opts.store, app) : null;
1007
+ const criticalFlows = settings?.criticalFlows ?? [];
1008
+ const hosts = settings?.hosts ?? [];
1009
+ /** This batch's errors, to group into incidents once they're all labelled. */
1010
+ const batchErrors = [];
693
1011
  for (const raw of env.events) {
694
1012
  const event = {
695
1013
  ...raw,
696
1014
  ts: sanitiseTs(raw.ts, now)
697
1015
  };
698
- if (event.type === "error" && !event.error.frames?.length && event.error.stack) event.error.frames = parseStack(event.error.stack);
1016
+ if (event.type === "error") {
1017
+ if (!event.error.frames?.length && event.error.stack) event.error.frames = parseStack(event.error.stack);
1018
+ else if (event.error.frames?.length) event.error.frames = markLibraryFrames(event.error.frames);
1019
+ }
699
1020
  const day = dayOf(event.ts);
700
1021
  if (event.type === "session") {
701
1022
  rollups.push({
@@ -756,19 +1077,25 @@ async function ingest(rawBody, ingestKey, opts) {
756
1077
  by: 1
757
1078
  });
758
1079
  let fp;
1080
+ let labels;
1081
+ let se;
759
1082
  if (event.type === "error") {
760
1083
  fp = fingerprint(event);
1084
+ labels = classify({
1085
+ ...event,
1086
+ ts: raw.ts
1087
+ }, {
1088
+ criticalFlows,
1089
+ hosts
1090
+ });
761
1091
  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
- };
1092
+ se = storedEvent(day, event, fp, labels);
1093
+ batchErrors.push({
1094
+ ts: raw.ts,
1095
+ labels,
1096
+ se,
1097
+ fp
1098
+ });
772
1099
  issues.set(fp, {
773
1100
  app,
774
1101
  fingerprint: fp,
@@ -805,17 +1132,47 @@ async function ingest(rawBody, ingestKey, opts) {
805
1132
  if (event.type === "error") {
806
1133
  inc("network", context.network?.type);
807
1134
  inc("country", countryOf(context));
1135
+ if (labels) {
1136
+ inc("category", labels.category);
1137
+ inc("owner", labels.owner);
1138
+ inc("impact", labels.impact);
1139
+ }
808
1140
  }
809
- stored.push({
1141
+ stored.push(se ?? storedEvent(day, event, fp, labels));
1142
+ }
1143
+ assignIncidents(batchErrors, context.os.name);
1144
+ const episodes = /* @__PURE__ */ new Set();
1145
+ for (const err of batchErrors) {
1146
+ if (!err.incident) continue;
1147
+ err.se.incident = err.incident;
1148
+ rollups.push({
810
1149
  app,
811
- day,
812
- fingerprint: fp,
813
- event,
814
- context,
815
- user: env.user,
816
- sessionId: env.session.id,
817
- receivedAt
1150
+ day: err.se.day,
1151
+ dimension: "incident",
1152
+ key: err.incident,
1153
+ kind: "error",
1154
+ by: 1
818
1155
  });
1156
+ rollups.push({
1157
+ app,
1158
+ day: err.se.day,
1159
+ dimension: "incidentIssue",
1160
+ key: incidentIssueKey(err.incident, err.fp),
1161
+ kind: "error",
1162
+ by: 1
1163
+ });
1164
+ if (!episodes.has(err.incident)) {
1165
+ episodes.add(err.incident);
1166
+ rollups.push({
1167
+ app,
1168
+ day: err.se.day,
1169
+ dimension: "incident",
1170
+ key: err.incident,
1171
+ kind: "event",
1172
+ by: 1
1173
+ });
1174
+ }
1175
+ scopes.add(`incident:${err.incident}`);
819
1176
  }
820
1177
  await opts.store.registerApp(app);
821
1178
  const retentionDays = stored.length ? await effectiveRetention(opts.store, app, opts.retentionDays) : void 0;
@@ -825,7 +1182,7 @@ async function ingest(rawBody, ingestKey, opts) {
825
1182
  opts.store.incrementRollups(rollups),
826
1183
  markUsers(opts.store, app, env.user?.id ?? env.user?.anonymousId ?? env.session.id, scopes, dayOf(receivedAt))
827
1184
  ]);
828
- if (outcome && (outcome.created.length || outcome.regressed.length)) await sendAlerts(app, outcome, issues, await cachedSettings(opts.store, app));
1185
+ if (outcome && (outcome.created.length || outcome.regressed.length)) await sendAlerts(app, outcome, issues, settings);
829
1186
  return {
830
1187
  status: 202,
831
1188
  body: {
@@ -1012,6 +1369,255 @@ async function authorizeApi(request) {
1012
1369
  const b = Buffer.from(token);
1013
1370
  return a.length === b.length && timingSafeEqual(a, b);
1014
1371
  }
1372
+ // src/server/explain.ts
1373
+ /** Handlers whose name says what the user did. Matched on the cleaned Hermes name. */
1374
+ var USER_ACTIONS = [
1375
+ [/^_?onRefresh$/, "pull to refresh"],
1376
+ [/^_?onPress([A-Z]\w*)?$|^_?handlePress([A-Z]\w*)?$/, "a tap"],
1377
+ [/^_?onLongPress$/, "a long press"],
1378
+ [/^_?onSubmit(Editing)?$|^_?handleSubmit([A-Z]\w*)?$/, "submitting a form"],
1379
+ [/^_?onChangeText$/, "typing"],
1380
+ [/^_?onEndReached$/, "scrolling to the end of a list"],
1381
+ [/^_?onValueChange$/, "changing a setting"]
1382
+ ];
1383
+ /** The first app frame that is a known user-action handler: `_onRefresh` → "pull to refresh". */
1384
+ function userAction(frames) {
1385
+ for (const f of frames ?? []) {
1386
+ if (f.inApp === false) continue;
1387
+ const fn = cleanFnName(f.fn);
1388
+ const known = fn && USER_ACTIONS.find(([re]) => re.test(fn));
1389
+ if (fn && known) return {
1390
+ fn,
1391
+ action: known[1]
1392
+ };
1393
+ }
1394
+ }
1395
+ var seconds = (ms) => ms < 1e3 ? `${Math.round(ms)} ms` : `${(ms / 1e3).toFixed(1)} s`;
1396
+ var plural$1 = (n, word) => `${n.toLocaleString()} ${word}${n === 1 ? "" : "s"}`;
1397
+ var cap = (s) => s.charAt(0).toUpperCase() + s.slice(1);
1398
+ var PLATFORM = {
1399
+ ios: "iPhone",
1400
+ android: "Android",
1401
+ web: "the web",
1402
+ macos: "Mac",
1403
+ windows: "Windows"
1404
+ };
1405
+ var platformName = (os) => PLATFORM[os] ?? os;
1406
+ /** A durations range: "16 ms", or "3–49 ms" across occurrences. */
1407
+ function durationText(ds) {
1408
+ const xs = ds.filter((d) => Number.isFinite(d) && d >= 0);
1409
+ if (!xs.length) return void 0;
1410
+ const lo = Math.min(...xs);
1411
+ const hi = Math.max(...xs);
1412
+ if (lo === hi || hi < 1e3) return lo === hi ? seconds(lo) : `${Math.round(lo)}–${Math.round(hi)} ms`;
1413
+ return `${seconds(lo)}–${seconds(hi)}`;
1414
+ }
1415
+ 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_-]|$)/;
1416
+ /**
1417
+ * What a request was for, in plain words, from its path: "/api/balance/getBalances" → "balances",
1418
+ * "/api/app-force-update" → "app force update". Undefined when the path says nothing.
1419
+ */
1420
+ function thingOf(url) {
1421
+ const last = url.split("?")[0].split("/").filter((p) => p && p !== ":id" && !/^v\d+$/.test(p)).pop();
1422
+ if (!last || last.includes(".")) return void 0;
1423
+ return last.replace(VERB, "").replace(/([a-z0-9])([A-Z])/g, "$1 $2").replace(/[-_]+/g, " ").trim().toLowerCase() || void 0;
1424
+ }
1425
+ /** "Balances", "Balances (Balance service)", "The app" — the subject of the summary. */
1426
+ function subject(e, service) {
1427
+ const thing = e?.request ? thingOf(e.request.url) : void 0;
1428
+ if (!thing) return {
1429
+ name: service ? `a request to ${service}` : e?.request ? "a request" : "the app",
1430
+ plural: false
1431
+ };
1432
+ return {
1433
+ name: service ? `${thing} (${service})` : thing,
1434
+ plural: /s$/.test(thing) && !/ss$/.test(thing)
1435
+ };
1436
+ }
1437
+ function stillHappening(i, rangeLabel, now) {
1438
+ if (i.status === "resolved") return "It's marked fixed.";
1439
+ if (i.status === "ignored") return "It's marked as ignored.";
1440
+ 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.`;
1441
+ return `It hasn't happened in the last 24 hours (${plural$1(i.countRange, "time")} in ${rangeLabel}).`;
1442
+ }
1443
+ var PASS_TO = {
1444
+ app: "app team",
1445
+ backend: "backend team",
1446
+ infrastructure: "whoever runs the network and hosting",
1447
+ third_party: "whoever manages that third-party service",
1448
+ unknown: "app team first, to find out whose it is"
1449
+ };
1450
+ var TEMPLATES = {
1451
+ "network.offline": {
1452
+ saw: (n, are) => `${cap(n)} ${are === "are" ? "weren't" : "wasn't"} available`,
1453
+ why: () => "The phone was offline.",
1454
+ diagnosis: () => "No connection when the request was made.",
1455
+ fix: () => "Check connectivity before sending (NetInfo), queue the request until the phone is back online, and show an offline state."
1456
+ },
1457
+ "network.never_sent": {
1458
+ saw: (n) => `${cap(n)} didn't load`,
1459
+ 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.",
1460
+ 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.",
1461
+ 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."
1462
+ },
1463
+ "network.timeout": {
1464
+ saw: (n) => `${cap(n)} took too long and gave up`,
1465
+ why: () => "The request was sent but no answer came back in time: a slow network or a slow server.",
1466
+ diagnosis: (_ev, took) => `Timed out${took ? ` after ${took}` : ""} with no response.`,
1467
+ 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."
1468
+ },
1469
+ "network.failed": {
1470
+ saw: (n) => `${cap(n)} couldn't connect`,
1471
+ why: (ev) => ev.failedHosts.length > 1 ? "Several servers were unreachable at once, which points at the network." : "The phone couldn't reach the server.",
1472
+ diagnosis: (_ev, took) => `No HTTP status${took ? ` after ${took}` : ""}: DNS, TLS or a refused connection.`,
1473
+ 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."
1474
+ },
1475
+ auth: {
1476
+ saw: (n, are) => `${cap(n)} ${are === "are" ? "were" : "was"} refused`,
1477
+ 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.",
1478
+ diagnosis: (ev) => `HTTP ${ev.status ?? "401/403"}.${ev.sameHostWorkedBefore ? " An earlier request to the same server succeeded, so the session ran out." : ""}`,
1479
+ 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."
1480
+ },
1481
+ server: {
1482
+ saw: (n) => `${cap(n)} failed with a server error`,
1483
+ why: () => "The server received the request and failed. The problem is on the server side.",
1484
+ diagnosis: (ev) => `HTTP ${ev.status ?? "5xx"} from the server.`,
1485
+ fix: () => "Check the backend logs for this endpoint at the times above. In the app, show a friendly error and let the user retry."
1486
+ },
1487
+ client_request: {
1488
+ saw: (n, are) => `${cap(n)} ${are === "are" ? "were" : "was"} rejected`,
1489
+ why: () => "The server refused what the app sent as invalid.",
1490
+ diagnosis: (ev) => `HTTP ${ev.status ?? "4xx"}: the request didn't match what the API expects.`,
1491
+ fix: () => "Compare the request the app sends (fields, types, headers) with what the API expects, and validate input before sending."
1492
+ },
1493
+ crash: {
1494
+ saw: () => "The app closed unexpectedly",
1495
+ why: () => "An error nobody caught closed the app.",
1496
+ diagnosis: () => "Fatal error from the global handler.",
1497
+ fix: () => "Open the culprit below, replay the breadcrumbs to reproduce, and add a guard or an error boundary around it."
1498
+ },
1499
+ screen_crash: {
1500
+ saw: () => "A screen failed to show and the error screen appeared instead",
1501
+ why: () => "Something on that screen broke while drawing. The rest of the app kept working.",
1502
+ diagnosis: () => "Caught by an error boundary while rendering.",
1503
+ fix: () => "Open the culprit below. Usually data the screen expects is missing or not loaded yet: add a loading state or a guard."
1504
+ },
1505
+ unhandled_rejection: {
1506
+ saw: () => "Something in the background failed",
1507
+ why: () => "Background work failed and nothing handled it, so whatever it was doing may not have happened.",
1508
+ diagnosis: () => "Unhandled promise rejection.",
1509
+ fix: () => "Find the promise at the culprit below and add a catch that handles or reports the failure."
1510
+ },
1511
+ uncaught: {
1512
+ saw: () => "Something failed while the user was using the app",
1513
+ why: () => "An error nobody caught. The app kept running.",
1514
+ diagnosis: () => "Uncaught, non-fatal error.",
1515
+ fix: () => "Open the culprit below and handle the error where it's thrown."
1516
+ },
1517
+ app_reported: {
1518
+ saw: () => "The app reported an error",
1519
+ why: () => "The app caught this itself and reported it.",
1520
+ diagnosis: () => "Reported with deBug.error().",
1521
+ fix: () => "See where the app reports it (culprit below) and decide whether the user needs to know."
1522
+ },
1523
+ other: {
1524
+ saw: () => "Something went wrong",
1525
+ why: () => "This error doesn't match a known kind yet.",
1526
+ diagnosis: () => "No category matched.",
1527
+ fix: () => "Start at the culprit below and use the breadcrumbs to replay what the user did."
1528
+ }
1529
+ };
1530
+ /** What each cause adds: a plain sentence for support, a step for the fix. */
1531
+ var CAUSE_LINES = {
1532
+ burst: { summary: () => "Several requests failed at the same moment." },
1533
+ slow_network: {
1534
+ summary: () => "The connection was slow.",
1535
+ fix: "Test on a throttled connection."
1536
+ },
1537
+ new_in_release: {
1538
+ summary: () => "It started in the latest version of the app.",
1539
+ fix: "Look at what changed in the latest release around the culprit."
1540
+ },
1541
+ regressed: {
1542
+ summary: () => "It was marked fixed, but it has come back.",
1543
+ fix: "The earlier fix didn't hold: compare with the release it was resolved in."
1544
+ },
1545
+ single_device: {
1546
+ summary: (x) => `It's only been seen on one phone model${x.model ? ` (${x.model})` : ""}.`,
1547
+ fix: "Reproduce on that model first."
1548
+ }
1549
+ };
1550
+ function explain(input) {
1551
+ const { issue, labels, rangeLabel } = input;
1552
+ const now = input.now ?? Date.now();
1553
+ const ev0 = input.lastEvent?.event;
1554
+ const e = ev0?.type === "error" ? ev0 : void 0;
1555
+ const ev = e ? evidenceOf(e) : NO_EVIDENCE;
1556
+ const t = TEMPLATES[labels.category] ?? TEMPLATES.other;
1557
+ const causes = labels.causes;
1558
+ const model = input.lastEvent?.context.device.model;
1559
+ const service = e?.request ? hostNameFor(e.request.url, input.hosts)?.host.name : void 0;
1560
+ const s = subject(e, service);
1561
+ const who = input.users ? ` for ${plural$1(input.users, "user")}` : "";
1562
+ const platforms = input.platforms?.length ? input.platforms : input.users === 1 && input.lastEvent ? [input.lastEvent.context.os.name] : [];
1563
+ const where = platforms.length ? ` on ${platforms.map(platformName).join(" and ")}` : "";
1564
+ const when = causes.includes("resumed_from_background") ? " right after reopening the app" : "";
1565
+ const action = userAction(e?.error.frames);
1566
+ const doing = action ? ` (after ${action.action})` : "";
1567
+ const causeSentences = causes.flatMap((c) => CAUSE_LINES[c]?.summary?.({ model }) ?? []);
1568
+ const summary = [
1569
+ `${t.saw(s.name, s.plural ? "are" : "is")}${who}${where}${when}${doing}.`,
1570
+ t.why(ev, causes),
1571
+ ...causeSentences,
1572
+ stillHappening(issue, rangeLabel, now),
1573
+ `Pass to: ${PASS_TO[labels.owner] ?? PASS_TO.unknown}${service && (labels.owner === "backend" || labels.owner === "third_party") ? ` (${service})` : ""}.`
1574
+ ].join(" ");
1575
+ const took = durationText(input.durations?.length ? input.durations : ev.durationMs !== void 0 ? [ev.durationMs] : []);
1576
+ const evidence = [t.diagnosis(ev, took)];
1577
+ if (e?.request) evidence.push(`Request: \`${e.request.method.toUpperCase()} ${e.request.url}\`${service ? ` (${service})` : ""}.`);
1578
+ 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.`);
1579
+ 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` : ""}.`);
1580
+ else if (ev.repeatedFailure) evidence.push("The same request had already failed just before.");
1581
+ if (causes.includes("slow_network")) evidence.push(`${ev.slowRecent} of the last 5 requests were slow.`);
1582
+ if (ev.inBackground) evidence.push("The app was in the background, so the user probably didn't see it.");
1583
+ for (const c of causes) if (CAUSE_LINES[c]?.fix) evidence.push(`${CAUSE_INFO[c].name}: ${CAUSE_INFO[c].description}`);
1584
+ if (issue.incidentTitle) evidence.push(`Part of the incident "${issue.incidentTitle}".`);
1585
+ const whereParts = [issue.culprit ? `\`${issue.culprit}\`` : void 0, action ? `started by \`${action.fn}\` (${action.action})` : void 0].filter(Boolean);
1586
+ const fixSteps = [t.fix(ev, causes), ...causes.flatMap((c) => CAUSE_LINES[c]?.fix ?? [])];
1587
+ return {
1588
+ summary,
1589
+ technical: {
1590
+ headline: `${CATEGORY_INFO[labels.category]?.name ?? labels.category} · owner: ${OWNER_INFO[labels.owner]?.name ?? labels.owner} · impact: ${IMPACT_INFO[labels.impact]?.name ?? labels.impact}`,
1591
+ evidence,
1592
+ where: whereParts.length ? whereParts.join(", ") : void 0,
1593
+ fix: fixSteps.join(" ")
1594
+ }
1595
+ };
1596
+ }
1597
+ /** The explanation as Markdown lines, without a title: for tickets and prefilled links. */
1598
+ function explanationLines(x) {
1599
+ return [
1600
+ "### What happened",
1601
+ x.summary,
1602
+ "",
1603
+ "### For developers",
1604
+ `**${x.technical.headline}**`,
1605
+ "",
1606
+ ...x.technical.evidence.map((l) => `- ${l}`),
1607
+ ...x.technical.where ? ["", `**Where:** ${x.technical.where}`] : [],
1608
+ "",
1609
+ `**Suggested fix:** ${x.technical.fix}`
1610
+ ];
1611
+ }
1612
+ /** The explanation as Markdown, for pasting into a Jira or Linear ticket by hand. */
1613
+ function explanationMarkdown(title, x, link) {
1614
+ return [
1615
+ `## ${title}`,
1616
+ ...link ? ["", `deBug: ${link}`] : [],
1617
+ "",
1618
+ ...explanationLines(x)
1619
+ ].join("\n");
1620
+ }
1015
1621
  // src/server/range.ts
1016
1622
  /** The date range a dashboard view covers, worked out from the URL (range=7d, or from/to). */
1017
1623
  var RANGE_PRESETS = [
@@ -1111,16 +1717,29 @@ var SUMMARY_FIELDS = {
1111
1717
  "totals.criticalIssues": "Issues whose 24h occurrence count meets the critical threshold.",
1112
1718
  "flows[]": "Parts of the app as tagged by the developer (e.g. auth.login). Sorted by severity, then errors24h, then errorsRange.",
1113
1719
  "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.",
1720
+ "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
1721
  "issues[].severity": "Derived from count24h using thresholds critical/high/medium.",
1722
+ "issues[].title": "Error name and message, with hosts named in Settings shown by their names.",
1116
1723
  "issues[].culprit": "Top in-app stack frame: function (file:line).",
1724
+ "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.",
1725
+ "incidents[].episodes": "Separate times it happened in the range (one per batch of events the SDK sent).",
1726
+ "incidents[].active": "false when every issue in it is resolved or ignored; the overview hides those.",
1727
+ "incidents[].issues": "The issues in the incident with their errors in the range.",
1728
+ "issues[].incident": "Key of the incident the latest occurrence belonged to, if any.",
1729
+ "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.",
1730
+ "issues[].explanation.technical": "For developers: category, owner and impact (headline), the evidence, where in the code and what started it, and a suggested fix.",
1731
+ "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.",
1732
+ "breakdowns.category": "Errors in the range by category (e.g. network.never_sent, server, crash).",
1733
+ "breakdowns.owner": "Errors in the range by likely owner: app, backend, infrastructure, third_party, unknown.",
1734
+ "breakdowns.impact": "Errors in the range by user impact: blocked, degraded, silent.",
1117
1735
  "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.",
1736
+ breakdowns: "Errors in the range split by OS, app version, device model, network, country, and the labels category, owner and impact.",
1119
1737
  narrative: "Plain-language summary of what is going wrong in the range.",
1120
1738
  "health.crashFreeRate": "Share of sessions in the range with no fatal crash. Sessions are recorded automatically by the SDK.",
1121
1739
  "health.errorFreeRate": "Share of sessions in the range with no unhandled error.",
1122
1740
  "health.releases[]": "Crash-free and error-free rates per app version.",
1123
1741
  "health.endpoints[]": "HTTP endpoints whose requests failed most (5xx, timeouts, network errors), from automatic network capture.",
1742
+ "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
1743
  "health.users": "Distinct users active since the start of the range (user id when set, else the install's anonymous id; stored hashed).",
1125
1744
  "health.crashFreeUsersRate": "Share of those users who didn't crash.",
1126
1745
  "issues[].status": "open, resolved, ignored, or regressed (seen again in the fixed release or later).",
@@ -1172,16 +1791,22 @@ async function buildSummary(store, appParam, thresholds, now = Date.now(), opts
1172
1791
  store.getRollups(app, "issueHour", hours(now, 48)[0], hourKey(now)),
1173
1792
  retentionFor(store, app, opts.retentionDays, now)
1174
1793
  ]);
1175
- const [releaseRows, stepRows, requestRows, latencyRows, networkRows, countryRows, appSettings] = await Promise.all([
1794
+ const [releaseRows, stepRows, requestRows, latencyRows, networkRows, countryRows, appSettings, categoryRows, ownerRows, impactRows, incidentRows, incidentIssueRows] = await Promise.all([
1176
1795
  store.getRollups(app, "release", dayKey(Date.parse(`${from}T00:00:00Z`) - 365 * DAY), to),
1177
1796
  store.getRollups(app, "flowStep", from, to),
1178
1797
  store.getRollups(app, "requests", from, to),
1179
1798
  store.getRollups(app, "latency", from, to),
1180
1799
  store.getRollups(app, "network", from, to),
1181
1800
  store.getRollups(app, "country", from, to),
1182
- store.getSettings(app).catch(() => null)
1801
+ store.getSettings(app).catch(() => null),
1802
+ store.getRollups(app, "category", from, to),
1803
+ store.getRollups(app, "owner", from, to),
1804
+ store.getRollups(app, "impact", from, to),
1805
+ store.getRollups(app, "incident", from, to),
1806
+ store.getRollups(app, "incidentIssue", from, to)
1183
1807
  ]);
1184
1808
  const criticalFlows = appSettings?.criticalFlows ?? [];
1809
+ const hosts = appSettings?.hosts ?? [];
1185
1810
  const critical = new Set(criticalFlows);
1186
1811
  const usersSince = hourly ? dayKey(now - DAY) : from;
1187
1812
  const [users, crashedUsers] = await Promise.all([countUsersSafe(store, app, "app", usersSince), countUsersSafe(store, app, "crash", usersSince)]);
@@ -1229,9 +1854,20 @@ async function buildSummary(store, appParam, thresholds, now = Date.now(), opts
1229
1854
  const rangeStart = hourly ? (/* @__PURE__ */ new Date(now - DAY)).toISOString() : `${from}T00:00:00.000Z`;
1230
1855
  const versionsInRange = [...new Set(sessionRows.map((r) => r.key.split("|")[0]).filter((v) => v && v !== "unknown"))].sort(compareVersions);
1231
1856
  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);
1857
+ 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
1858
  const active = issueRows.filter((i) => i.status !== "ignored" && i.status !== "resolved");
1234
1859
  await Promise.all(active.slice(0, 10).map(async (i) => i.users = await countUsersSafe(store, app, `issue:${i.fingerprint}`, usersSince)));
1860
+ const lastEvents = new Map(issues.map((i) => [i.fingerprint, i.lastEvent]));
1861
+ for (const row of issueRows) if (row.labels) row.explanation = explain({
1862
+ issue: row,
1863
+ labels: row.labels,
1864
+ lastEvent: lastEvents.get(row.fingerprint),
1865
+ users: row.users,
1866
+ hosts,
1867
+ rangeLabel: range.label,
1868
+ now
1869
+ });
1870
+ const incidents = await buildIncidents(incidentRows, incidentIssueRows, issueRows, hourly, (key) => countUsersSafe(store, app, `incident:${key}`, usersSince));
1235
1871
  const firstDay = /* @__PURE__ */ new Map();
1236
1872
  for (const r of releaseRows) {
1237
1873
  const cur = firstDay.get(r.key);
@@ -1310,18 +1946,22 @@ async function buildSummary(store, appParam, thresholds, now = Date.now(), opts
1310
1946
  trend,
1311
1947
  flows,
1312
1948
  issues: issueRows,
1949
+ incidents,
1313
1950
  breakdowns: {
1314
1951
  os: top(os),
1315
1952
  appVersion: top(appVersion),
1316
1953
  deviceModel: top(deviceModel),
1317
1954
  network: top(networkRows),
1318
- country: top(countryRows)
1955
+ country: top(countryRows),
1956
+ category: top(categoryRows),
1957
+ owner: top(ownerRows),
1958
+ impact: top(impactRows)
1319
1959
  },
1320
1960
  steps: buildSteps(stepRows),
1321
- timings: buildTimings(requestRows, latencyRows),
1961
+ timings: buildTimings(requestRows, latencyRows, hosts),
1322
1962
  criticalFlows,
1323
1963
  health: {
1324
- ...buildHealth(sessionRows, endpointRows, dayKey(now)),
1964
+ ...buildHealth(sessionRows, endpointRows, dayKey(now), hosts),
1325
1965
  users,
1326
1966
  crashedUsers,
1327
1967
  crashFreeUsersRate: users > 0 ? Math.max(0, 1 - crashedUsers / users) : null
@@ -1332,8 +1972,83 @@ async function buildSummary(store, appParam, thresholds, now = Date.now(), opts
1332
1972
  summary.narrative = narrate(summary);
1333
1973
  return summary;
1334
1974
  }
1975
+ /** "Requests failed on app resume (iOS)", from an incident key. */
1976
+ function incidentTitle(key) {
1977
+ const k = parseIncidentKey(key);
1978
+ if (!k) return key;
1979
+ const os = k.os === "ios" ? "iOS" : k.os === "android" ? "Android" : k.os;
1980
+ const requests = isRequestCategory(k.category);
1981
+ const what = CATEGORY_INFO[k.category]?.name ?? k.category;
1982
+ if (k.cause === "resumed_from_background") return `${requests ? "Requests failed" : what} on app resume (${os})`;
1983
+ if (k.cause === "burst") return `${what}: several requests at once (${os})`;
1984
+ return `${what}: ${CAUSE_INFO[k.cause]?.name.toLowerCase() ?? k.cause} (${os})`;
1985
+ }
1986
+ async function buildIncidents(rows, issueRows, issues, hourly, users) {
1987
+ const shown = new Map(issues.map((i) => [i.fingerprint, i]));
1988
+ const members = /* @__PURE__ */ new Map();
1989
+ for (const r of issueRows) {
1990
+ const k = parseIncidentIssueKey(r.key);
1991
+ if (!k || !shown.has(k.fingerprint)) continue;
1992
+ const m = members.get(k.incident) ?? /* @__PURE__ */ new Map();
1993
+ m.set(k.fingerprint, (m.get(k.fingerprint) ?? 0) + r.errors);
1994
+ members.set(k.incident, m);
1995
+ }
1996
+ const days = /* @__PURE__ */ new Map();
1997
+ for (const r of rows) {
1998
+ const d = days.get(r.key) ?? {
1999
+ episodes: 0,
2000
+ first: r.day,
2001
+ last: r.day
2002
+ };
2003
+ d.episodes += r.events;
2004
+ if (r.errors > 0 && r.day < d.first) d.first = r.day;
2005
+ if (r.errors > 0 && r.day > d.last) d.last = r.day;
2006
+ days.set(r.key, d);
2007
+ }
2008
+ const out = [];
2009
+ for (const [key, m] of members) {
2010
+ const k = parseIncidentKey(key);
2011
+ if (!k) continue;
2012
+ const list = [...m.entries()].map(([fingerprint, n]) => {
2013
+ const i = shown.get(fingerprint);
2014
+ return {
2015
+ fingerprint,
2016
+ title: i.title,
2017
+ errors: hourly ? Math.min(n, i.count24h) : n,
2018
+ status: i.status
2019
+ };
2020
+ }).filter((i) => i.errors > 0).sort((a, b) => b.errors - a.errors);
2021
+ if (!list.length) continue;
2022
+ const d = days.get(key);
2023
+ out.push({
2024
+ key,
2025
+ title: incidentTitle(key),
2026
+ ...k,
2027
+ errors: list.reduce((a, i) => a + i.errors, 0),
2028
+ episodes: d?.episodes ?? 0,
2029
+ users: 0,
2030
+ firstDay: d?.first ?? "",
2031
+ lastDay: d?.last ?? "",
2032
+ active: list.some((i) => i.status !== "resolved" && i.status !== "ignored"),
2033
+ issues: list.map(({ fingerprint, title, errors }) => ({
2034
+ fingerprint,
2035
+ title,
2036
+ errors
2037
+ }))
2038
+ });
2039
+ }
2040
+ out.sort((a, b) => b.errors - a.errors);
2041
+ const top = out.slice(0, 20);
2042
+ await Promise.all(top.map(async (i) => i.users = await users(i.key)));
2043
+ return top;
2044
+ }
1335
2045
  var rate = (bad, total) => total > 0 ? Math.max(0, 1 - bad / total) : null;
1336
- function buildHealth(sessionRows, endpointRows, today) {
2046
+ /** An endpoint key ("POST host/path") with its host's name, or undefined when the host has none. */
2047
+ function endpointLabel(endpoint, hosts) {
2048
+ const named = nameUrlsIn(endpoint, hosts);
2049
+ return named === endpoint ? void 0 : named;
2050
+ }
2051
+ function buildHealth(sessionRows, endpointRows, today, hosts = []) {
1337
2052
  const byVersion = /* @__PURE__ */ new Map();
1338
2053
  for (const r of sessionRows) {
1339
2054
  const [version = "unknown", status] = r.key.split("|");
@@ -1361,6 +2076,7 @@ function buildHealth(sessionRows, endpointRows, today) {
1361
2076
  let e = eps.get(r.key);
1362
2077
  if (!e) eps.set(r.key, e = {
1363
2078
  endpoint: r.key,
2079
+ label: endpointLabel(r.key, hosts),
1364
2080
  failuresRange: 0,
1365
2081
  failures24h: 0
1366
2082
  });
@@ -1404,7 +2120,11 @@ function buildSteps(rows) {
1404
2120
  failureRate: s.successes + s.failures > 0 ? s.failures / (s.successes + s.failures) : null
1405
2121
  })).sort((a, b) => b.failures - a.failures || (b.failureRate ?? 0) - (a.failureRate ?? 0)).slice(0, 30);
1406
2122
  }
1407
- function buildTimings(requestRows, latencyRows) {
2123
+ function buildTimings(requestRows, latencyRows, hosts = []) {
2124
+ return endpointTimings(requestRows, latencyRows, hosts).sort((a, b) => b.requests - a.requests).slice(0, 10);
2125
+ }
2126
+ /** Requests, failures and p50/p95 per endpoint ("<METHOD> <url>"), from the SDK's per-minute request summaries. */
2127
+ function endpointTimings(requestRows, latencyRows, hosts = []) {
1408
2128
  const totals = /* @__PURE__ */ new Map();
1409
2129
  for (const r of requestRows) {
1410
2130
  const t = totals.get(r.key) ?? {
@@ -1428,24 +2148,50 @@ function buildTimings(requestRows, latencyRows) {
1428
2148
  const b = hist.get(endpoint) ?? [];
1429
2149
  return {
1430
2150
  endpoint,
2151
+ label: endpointLabel(endpoint, hosts),
1431
2152
  requests: t.requests,
1432
2153
  failed: t.failed,
1433
2154
  errorRate: t.requests ? t.failed / t.requests : 0,
1434
2155
  p50: percentileMs(b, .5),
1435
2156
  p95: percentileMs(b, .95)
1436
2157
  };
1437
- }).sort((a, b) => b.requests - a.requests).slice(0, 10);
2158
+ });
1438
2159
  }
1439
- function toIssueRow(i, count24h, countRange, t, latestVersion = null, critical = /* @__PURE__ */ new Set()) {
2160
+ /**
2161
+ * An issue's labels: those ingest stored with its latest occurrence, or worked out now for
2162
+ * occurrences stored before the classifier existed, plus the causes that come from the issue.
2163
+ */
2164
+ function issueLabels(i, latestVersion, criticalFlows = [], hosts = []) {
2165
+ const ev = i.lastEvent?.event;
2166
+ const stored = i.lastEvent?.labels ?? (ev?.type === "error" ? classify(ev, {
2167
+ criticalFlows,
2168
+ hosts
2169
+ }) : void 0);
2170
+ if (!stored) return void 0;
2171
+ const owner = hostOwner(stored, ev?.type === "error" ? ev.request?.url : void 0, hosts);
2172
+ return withIssueCauses(owner === stored.owner ? stored : {
2173
+ ...stored,
2174
+ owner
2175
+ }, {
2176
+ status: i.status,
2177
+ firstVersion: i.firstVersion,
2178
+ latestVersion
2179
+ });
2180
+ }
2181
+ function toIssueRow(i, count24h, countRange, t, latestVersion = null, criticalFlows = [], hosts = []) {
1440
2182
  const base = severityFromCount(count24h, t);
2183
+ const critical = new Set(criticalFlows);
1441
2184
  return {
2185
+ labels: issueLabels(i, latestVersion, criticalFlows, hosts),
2186
+ incident: i.lastEvent?.incident,
2187
+ incidentTitle: i.lastEvent?.incident ? incidentTitle(i.lastEvent.incident) : void 0,
1442
2188
  status: i.status ?? "open",
1443
2189
  resolvedIn: i.resolvedIn,
1444
2190
  firstVersion: i.firstVersion,
1445
2191
  lastVersion: i.lastVersion,
1446
2192
  newInLatest: !!latestVersion && i.firstVersion === latestVersion,
1447
2193
  fingerprint: i.fingerprint,
1448
- title: i.title,
2194
+ title: nameUrlsIn(i.title, hosts),
1449
2195
  culprit: i.culprit,
1450
2196
  flow: i.flow,
1451
2197
  severity: i.flow && critical.has(i.flow) && count24h > 0 ? BUMP[base] : base,
@@ -1489,7 +2235,7 @@ function narrate(s) {
1489
2235
  out.push(`${latest.version} is ${pctOne(latest.crashFreeRate)} crash-free across ${plural(latest.sessions, "session")}${vs}.`);
1490
2236
  }
1491
2237
  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}.`);
2238
+ 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
2239
  const net = s.breakdowns.network.filter((r) => r.key !== "unknown");
1494
2240
  const netTotal = net.reduce((a, b) => a + b.errors, 0);
1495
2241
  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 +2253,12 @@ async function buildIssueDetail(store, app, fingerprint, thresholds, now = Date.
1507
2253
  if (!issue) return null;
1508
2254
  const range = resolveRange(opts.range ?? {}, now);
1509
2255
  const hs = hours(now, 48);
1510
- const [hourRows, dayRows, events, retention] = await Promise.all([
2256
+ const [hourRows, dayRows, events, retention, settings] = await Promise.all([
1511
2257
  store.getRollups(app, "issueHour", hs[0], hs[hs.length - 1]),
1512
2258
  store.getRollups(app, "issue", range.from, range.to),
1513
2259
  store.listIssueEvents(app, fingerprint, { limit: 200 }),
1514
- retentionFor(store, app, opts.retentionDays, now)
2260
+ retentionFor(store, app, opts.retentionDays, now),
2261
+ store.getSettings(app).catch(() => null)
1515
2262
  ]);
1516
2263
  const hourly = hs.map((hour) => ({
1517
2264
  hour,
@@ -1544,8 +2291,24 @@ async function buildIssueDetail(store, app, fingerprint, thresholds, now = Date.
1544
2291
  };
1545
2292
  const usersSince = range.preset === "24h" ? dayKey(now - DAY) : range.from;
1546
2293
  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);
2294
+ const criticalFlows = settings?.criticalFlows ?? [];
2295
+ const hosts = settings?.hosts ?? [];
2296
+ const row = toIssueRow(issue, count24h, countRange, thresholds, null, criticalFlows, hosts);
2297
+ if (row.labels) row.labels = withIssueCauses(row.labels, { deviceModels: events.map((e) => e.context.device.model) });
2298
+ const hints = hintsFor(issue, breakdowns, events, !!row.labels && isRequestCategory(row.labels.category), hosts);
2299
+ const errorEvents = events.filter((e) => e.event.type === "error");
2300
+ row.explanation = row.labels ? explain({
2301
+ issue: row,
2302
+ labels: row.labels,
2303
+ lastEvent: issue.lastEvent,
2304
+ users: affectedUsers,
2305
+ hosts,
2306
+ platforms: [...new Set(errorEvents.map((e) => e.context.os.name))],
2307
+ durations: errorEvents.flatMap((e) => e.event.type === "error" && e.event.request?.durationMs !== void 0 ? [e.event.request.durationMs] : []),
2308
+ rangeLabel: range.label,
2309
+ now
2310
+ }) : void 0;
2311
+ const link = issueUrl(opts.trackers?.dashboardUrl, app, fingerprint);
1549
2312
  const detail = {
1550
2313
  app,
1551
2314
  range,
@@ -1558,26 +2321,33 @@ async function buildIssueDetail(store, app, fingerprint, thresholds, now = Date.
1558
2321
  links: {},
1559
2322
  sample: events[0] ?? issue.lastEvent ?? null,
1560
2323
  recent: events.slice(0, 25).map((e) => ({
2324
+ id: e.event.id,
2325
+ type: e.event.type,
1561
2326
  ts: e.event.ts,
1562
2327
  os: `${e.context.os.name} ${e.context.os.version ?? ""}`.trim(),
1563
2328
  appVersion: e.context.app.version,
1564
2329
  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}`,
2330
+ 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
2331
  userId: e.user?.id
1567
2332
  })),
1568
- hints
2333
+ hints,
2334
+ ticketMarkdown: row.explanation ? explanationMarkdown(row.title, row.explanation, link) : void 0
1569
2335
  };
1570
2336
  detail.links = trackerLinks(detail, opts.trackers ?? {});
1571
2337
  return detail;
1572
2338
  }
2339
+ var issueUrl = (dashboardUrl, app, fp) => dashboardUrl ? `${dashboardUrl.replace(/\/+$/, "")}/issues/${fp}?app=${encodeURIComponent(app)}` : void 0;
1573
2340
  /** The issue as a ticket: what, where, how often, what to look at. Kept short enough for a URL. */
1574
2341
  function issueStory(d, dashboardUrl) {
1575
2342
  const i = d.issue;
2343
+ const x = i.explanation;
1576
2344
  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
2345
  const frames = d.sample?.event.type === "error" ? (d.sample.event.error.frames ?? []).filter((f) => f.inApp).slice(0, 3) : [];
1578
2346
  const body = [
1579
2347
  `**${i.title}**`,
1580
2348
  i.culprit ? `At \`${i.culprit}\`${i.flow ? ` in flow \`${i.flow}\`` : ""}.` : i.flow ? `In flow \`${i.flow}\`.` : "",
2349
+ ...dashboardUrl ? ["", `deBug: ${issueUrl(dashboardUrl, d.app, i.fingerprint)}`] : [],
2350
+ ...x ? ["", ...explanationLines(x)] : [],
1581
2351
  "",
1582
2352
  `- ${i.countRange.toLocaleString()} occurrences in ${d.range.label}, ${i.count24h} in the last 24h (severity: ${i.severity})`,
1583
2353
  `- ${d.affectedUsers.toLocaleString()} users affected`,
@@ -1591,10 +2361,9 @@ function issueStory(d, dashboardUrl) {
1591
2361
  ] : [],
1592
2362
  ...d.hints.length ? [
1593
2363
  "",
1594
- "What to look at:",
2364
+ x ? "Also worth checking:" : "What to look at:",
1595
2365
  ...d.hints.slice(0, 3).map((h) => `- ${h.title}: ${h.detail}`)
1596
- ] : [],
1597
- ...dashboardUrl ? ["", `deBug: ${dashboardUrl.replace(/\/+$/, "")}/issues/${i.fingerprint}?app=${encodeURIComponent(d.app)}`] : []
2366
+ ] : []
1598
2367
  ].filter((l, n, all) => !(l === "" && all[n - 1] === "")).join("\n");
1599
2368
  return {
1600
2369
  title: `[deBug] ${i.title}`.slice(0, 200),
@@ -1616,7 +2385,7 @@ function trackerLinks(d, t) {
1616
2385
  };
1617
2386
  }
1618
2387
  /** 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) {
2388
+ function hintsFor(issue, b, events, explained = false, hosts = []) {
1620
2389
  const hints = [];
1621
2390
  const text = `${issue.title} ${events[0]?.event.type === "error" ? events[0].event.error.stack ?? "" : ""}`.toLowerCase();
1622
2391
  const crumbs = events.flatMap((e) => e.event.type === "error" ? e.event.breadcrumbs ?? [] : []);
@@ -1634,11 +2403,11 @@ function hintsFor(issue, b, events) {
1634
2403
  title: "A value is missing when the code expects it",
1635
2404
  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
2405
  });
1637
- if (/network request failed|failed to fetch|networkerror|timeout|timed out|econn|socket/.test(text)) hints.push({
2406
+ if (!explained && /network request failed|failed to fetch|networkerror|timeout|timed out|econn|socket/.test(text)) hints.push({
1638
2407
  title: "Network failure",
1639
2408
  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
2409
  });
1641
- if (/\b401\b|\b403\b|unauthori[sz]ed|forbidden|token expired|jwt/.test(text)) hints.push({
2410
+ if (!explained && /\b401\b|\b403\b|unauthori[sz]ed|forbidden|token expired|jwt/.test(text)) hints.push({
1642
2411
  title: "Auth/session problem",
1643
2412
  detail: "Look for expired or missing tokens. Confirm the token refresh runs before this call, and that the clock/expiry handling is right."
1644
2413
  });
@@ -1646,24 +2415,35 @@ function hintsFor(issue, b, events) {
1646
2415
  title: "Bad response body",
1647
2416
  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
2417
  });
1649
- if (/\b5\d\d\b|internal server error|bad gateway|service unavailable/.test(text)) hints.push({
2418
+ if (!explained && /\b5\d\d\b|internal server error|bad gateway|service unavailable/.test(text)) hints.push({
1650
2419
  title: "Server-side failure",
1651
2420
  detail: "The backend returned a 5xx. Correlate the timestamps with your API logs."
1652
2421
  });
1653
2422
  const failingRequests = crumbs.filter((c) => c.category === "network" && (c.level === "error" || /\b[45]\d\d\b/.test(c.message)));
1654
- if (failingRequests.length) {
2423
+ if (failingRequests.length && !explained) {
1655
2424
  const m = /* @__PURE__ */ new Map();
1656
2425
  for (const c of failingRequests) m.set(c.message, (m.get(c.message) ?? 0) + 1);
1657
2426
  const [msg] = [...m.entries()].sort((a, b) => b[1] - a[1])[0];
1658
2427
  hints.push({
1659
2428
  title: "A request fails right before the error",
1660
- detail: `Most common: ${msg}`
2429
+ detail: `Most common: ${nameUrlsIn(msg, hosts)}`
1661
2430
  });
1662
2431
  }
1663
- if (hints.length === 0) hints.push({
2432
+ if (hints.length === 0 && !explained) hints.push({
1664
2433
  title: "Start at the culprit frame",
1665
2434
  detail: `Open ${issue.culprit ?? "the top stack frame"} and use the breadcrumbs below to replay what the user did.`
1666
2435
  });
1667
2436
  return hints;
1668
2437
  }
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 };
2438
+ // src/server/errors.ts
2439
+ /** Firestore answers FAILED_PRECONDITION while an index deBug needs is missing or still building. */
2440
+ function isIndexError(message) {
2441
+ return /FAILED_PRECONDITION|requires an index|index is currently building/i.test(message);
2442
+ }
2443
+ /** A thrown Firestore error saying a composite index is missing (gRPC code 9), on the Firestore store only. */
2444
+ function isMissingIndex(e, store) {
2445
+ if (store !== "firestore") return false;
2446
+ const err = e;
2447
+ return (err?.code === 9 || err?.code === "failed-precondition") && /index/i.test(String(err?.message ?? ""));
2448
+ }
2449
+ 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 };