Skip to content
SlashClone
DiscoverUse in ClaudeSubmit a link
Sign in
Made by@usagemetrics

Saas usage dashboard

@usagemetrics/saas-usage-dashboard

Turn a product events CSV (timestamp, account_id, user_id, event) into one self-contained HTML dashboard: DAU, WAU, MAU, stickiness, active accounts, top features, activation rate, weekly retention, and accounts trending down. No external scripts; open it in any browser or attach it to an email.

SkillDatav1.0.0 (latest)Tested
Use in Claude Save Like Clone Comment
Activity
New: be the first to try it
  1. 1#!/usr/bin/env node
  2. 2// SaaS usage dashboard: events CSV in, one self-contained HTML file out (inline SVG, no external scripts).
  3. 3// Usage: node scripts/usage-dashboard.mjs <events.csv> [--out out/usage-dashboard.html] [--as-of 2026-10-31]
  4. 4// [--activation-event created_report] [--activation-days 14] [--ignore login,page_view] [--title "Acme usage"]
  5. 5// Columns: timestamp, account_id, user_id, event. Extra columns are ignored.
  6. 6import { DAY_MS, dayKey, fail, parseArgs, parseDate, pct, readCsv, round, weekKey, writeOut } from "./lib.mjs";
  7. 7import { barChart, card, flag, heatmap, lineChart, page, table, tiles } from "./html.mjs";
  8. 8
  9. 9const args = parseArgs(process.argv.slice(2));
  10. 10const input = args._[0];
  11. 11const outHtml = args.out || "out/usage-dashboard.html";
  12. 12const outJson = outHtml.replace(/\.html?$/i, "") + ".json";
  13. 13if (!input) fail("usage: node scripts/usage-dashboard.mjs <events.csv> [--out out/usage-dashboard.html]");
  14. 14const activationEvent = args["activation-event"] || null;
  15. 15const activationDays = Number(args["activation-days"] ?? 14);
  16. 16const ignore = new Set(String(args.ignore ?? "login,logout,session_start,page_view,signup,signed_up").split(",").map((s) => s.trim().toLowerCase()).filter(Boolean));
  17. 17
  18. 18const raw = readCsv(input, "events CSV", ["timestamp", "account_id", "user_id", "event"]);
  19. 19const events = [];
  20. 20let skipped = 0;
  21. 21for (const r of raw) {
  22. 22 const d = parseDate(r.timestamp);
  23. 23 if (!d || !r.user_id || !r.event) {
  24. 24 skipped++;
  25. 25 continue;
  26. 26 }
  27. 27 events.push({ t: d.getTime(), day: dayKey(d), account: r.account_id || "(no account)", user: r.user_id, event: r.event.toLowerCase() });
  28. 28}
  29. 29if (!events.length) fail(`no usable events in ${input}.`);
  30. 30events.sort((a, b) => a.t - b.t);
  31. 31
  32. 32const lastDay = args["as-of"] ? dayKey(parseDate(args["as-of"]) || fail("--as-of must be a date.")) : events[events.length - 1].day;
  33. 33const asOf = Date.parse(lastDay);
  34. 34const dayOffset = (day) => Math.round((asOf - Date.parse(day)) / DAY_MS); // 0 = as-of day
  35. 35const inWindow = (e, days) => {
  36. 36 const o = dayOffset(e.day);
  37. 37 return o >= 0 && o < days;
  38. 38};
  39. 39
  40. 40// Users and accounts active per day
  41. 41const usersByDay = new Map();
  42. 42const accountsByDay = new Map();
  43. 43const firstSeen = new Map();
  44. 44const userAccount = new Map();
  45. 45for (const e of events) {
  46. 46 if (dayOffset(e.day) < 0) continue;
  47. 47 if (!usersByDay.has(e.day)) usersByDay.set(e.day, new Set());
  48. 48 usersByDay.get(e.day).add(e.user);
  49. 49 if (!accountsByDay.has(e.day)) accountsByDay.set(e.day, new Set());
  50. 50 accountsByDay.get(e.day).add(e.account);
  51. 51 if (!firstSeen.has(e.user)) firstSeen.set(e.user, e.day);
  52. 52 userAccount.set(e.user, e.account);
  53. 53}
  54. 54const activeUsers = (endOffset, days) => {
  55. 55 const s = new Set();
  56. 56 for (let o = endOffset; o < endOffset + days; o++) for (const u of usersByDay.get(dayKey(new Date(asOf - o * DAY_MS))) || []) s.add(u);
  57. 57 return s;
  58. 58};
  59. 59const activeAccounts = (endOffset, days) => {
  60. 60 const s = new Set();
  61. 61 for (let o = endOffset; o < endOffset + days; o++) for (const a of accountsByDay.get(dayKey(new Date(asOf - o * DAY_MS))) || []) s.add(a);
  62. 62 return s;
  63. 63};
  64. 64
  65. 65const dau = (usersByDay.get(lastDay) || new Set()).size;
  66. 66const wau = activeUsers(0, 7).size;
  67. 67const mau = activeUsers(0, 30).size;
  68. 68let dauSum = 0;
  69. 69for (let o = 0; o < 30; o++) dauSum += (usersByDay.get(dayKey(new Date(asOf - o * DAY_MS))) || new Set()).size;
  70. 70const avgDau30 = dauSum / 30;
  71. 71const stickiness = mau ? avgDau30 / mau : 0;
  72. 72const mauPrev = activeUsers(30, 30).size;
  73. 73const accounts30 = activeAccounts(0, 30).size;
  74. 74const accountsPrev30 = activeAccounts(30, 30).size;
  75. 75
  76. 76// Series: daily active users for 90 days, weekly active users and accounts for 12 weeks
  77. 77const dayLabels = [];
  78. 78const dauSeries = [];
  79. 79for (let o = 89; o >= 0; o--) {
  80. 80 const k = dayKey(new Date(asOf - o * DAY_MS));
  81. 81 dayLabels.push(k.slice(5));
  82. 82 dauSeries.push((usersByDay.get(k) || new Set()).size);
  83. 83}
  84. 84const weekLabels = [];
  85. 85const wauSeries = [];
  86. 86const wacSeries = [];
  87. 87for (let w = 11; w >= 0; w--) {
  88. 88 weekLabels.push(dayKey(new Date(asOf - (w * 7 + 6) * DAY_MS)).slice(5));
  89. 89 wauSeries.push(activeUsers(w * 7, 7).size);
  90. 90 wacSeries.push(activeAccounts(w * 7, 7).size);
  91. 91}
  92. 92
  93. 93// Top features in the last 30 days
  94. 94const feat = new Map();
  95. 95for (const e of events) {
  96. 96 if (!inWindow(e, 30) || ignore.has(e.event)) continue;
  97. 97 const f = feat.get(e.event) || { event: e.event, count: 0, users: new Set(), accounts: new Set() };
  98. 98 f.count++;
  99. 99 f.users.add(e.user);
  100. 100 f.accounts.add(e.account);
  101. 101 feat.set(e.event, f);
  102. 102}
  103. 103const features = [...feat.values()]
  104. 104 .map((f) => ({ event: f.event, events: f.count, users: f.users.size, accounts: f.accounts.size, share_of_mau: mau ? round(f.users.size / mau, 4) : 0 }))
  105. 105 .sort((a, b) => b.users - a.users || b.events - a.events);
  106. 106
  107. 107// Activation: new users first seen 14..104 days before as-of (so each had the full window to activate)
  108. 108const userEvents = new Map();
  109. 109for (const e of events) {
  110. 110 if (!userEvents.has(e.user)) userEvents.set(e.user, []);
  111. 111 userEvents.get(e.user).push(e);
  112. 112}
  113. 113function activated(user) {
  114. 114 const start = Date.parse(firstSeen.get(user));
  115. 115 const end = start + activationDays * DAY_MS;
  116. 116 const evs = userEvents.get(user).filter((e) => Date.parse(e.day) < end);
  117. 117 if (activationEvent) return evs.some((e) => e.event === activationEvent.toLowerCase());
  118. 118 return new Set(evs.map((e) => e.day)).size >= 3;
  119. 119}
  120. 120const activationCohorts = new Map();
  121. 121let actN = 0;
  122. 122let actYes = 0;
  123. 123for (const [user, day] of firstSeen) {
  124. 124 const o = dayOffset(day);
  125. 125 if (o < activationDays || o >= activationDays + 90) continue;
  126. 126 const wk = weekKey(new Date(Date.parse(day)));
  127. 127 const c = activationCohorts.get(wk) || { week: wk, users: 0, activated: 0 };
  128. 128 c.users++;
  129. 129 actN++;
  130. 130 if (activated(user)) {
  131. 131 c.activated++;
  132. 132 actYes++;
  133. 133 }
  134. 134 activationCohorts.set(wk, c);
  135. 135}
  136. 136const activationRate = actN ? actYes / actN : null;
  137. 137const activationRows = [...activationCohorts.values()].sort((a, b) => (a.week < b.week ? -1 : 1));
  138. 138
  139. 139// Weekly retention: cohorts by first-seen week, last 8 full cohorts, weeks 0..7
  140. 140const asOfWeek = weekKey(new Date(asOf));
  141. 141const weekIndex = (day) => Math.round((Date.parse(weekKey(new Date(Date.parse(day)))) - Date.parse(asOfWeek)) / (7 * DAY_MS));
  142. 142const cohortUsers = new Map();
  143. 143for (const [user, day] of firstSeen) {
  144. 144 const wi = weekIndex(day);
  145. 145 if (wi < -8 || wi > -1) continue;
  146. 146 if (!cohortUsers.has(wi)) cohortUsers.set(wi, new Set());
  147. 147 cohortUsers.get(wi).add(user);
  148. 148}
  149. 149const userWeeks = new Map();
  150. 150for (const e of events) {
  151. 151 if (dayOffset(e.day) < 0) continue;
  152. 152 if (!userWeeks.has(e.user)) userWeeks.set(e.user, new Set());
  153. 153 userWeeks.get(e.user).add(weekIndex(e.day));
  154. 154}
  155. 155const cohortKeys = [...cohortUsers.keys()].sort((a, b) => a - b);
  156. 156const retention = cohortKeys.map((wi) => {
  157. 157 const users = cohortUsers.get(wi);
  158. 158 const row = [];
  159. 159 for (let k = 0; k < 8; k++) {
  160. 160 const target = wi + k;
  161. 161 if (target >= 0) row.push(null); // the current week is not complete yet
  162. 162 else row.push(round([...users].filter((u) => userWeeks.get(u)?.has(target)).length / users.size, 4));
  163. 163 }
  164. 164 return { cohort: dayKey(new Date(Date.parse(asOfWeek) + wi * 7 * DAY_MS)), users: users.size, weeks: row };
  165. 165});
  166. 166
  167. 167// Accounts trending down: last 28 days vs the 28 before
  168. 168const acct = new Map();
  169. 169for (const e of events) {
  170. 170 const o = dayOffset(e.day);
  171. 171 if (o < 0 || o >= 56) continue;
  172. 172 const a = acct.get(e.account) || { account: e.account, recent_events: 0, prior_events: 0, recent_users: new Set(), prior_users: new Set(), last_seen: e.day };
  173. 173 if (o < 28) {
  174. 174 a.recent_events++;
  175. 175 a.recent_users.add(e.user);
  176. 176 } else {
  177. 177 a.prior_events++;
  178. 178 a.prior_users.add(e.user);
  179. 179 }
  180. 180 if (e.day > a.last_seen) a.last_seen = e.day;
  181. 181 acct.set(e.account, a);
  182. 182}
  183. 183const trending = [...acct.values()]
  184. 184 .filter((a) => a.prior_events >= 20)
  185. 185 .map((a) => {
  186. 186 const evChange = (a.recent_events - a.prior_events) / a.prior_events;
  187. 187 const userChange = a.prior_users.size ? (a.recent_users.size - a.prior_users.size) / a.prior_users.size : 0;
  188. 188 const daysQuiet = dayOffset(a.last_seen);
  189. 189 return { account: a.account, prior_events: a.prior_events, recent_events: a.recent_events, events_change: round(evChange, 4), prior_users: a.prior_users.size, recent_users: a.recent_users.size, users_change: round(userChange, 4), days_since_last_event: daysQuiet };
  190. 190 })
  191. 191 .filter((a) => a.events_change <= -0.3 || a.users_change <= -0.3 || a.days_since_last_event >= 14)
  192. 192 .sort((a, b) => a.events_change - b.events_change);
  193. 193
  194. 194const summary = {
  195. 195 source: input,
  196. 196 as_of: lastDay,
  197. 197 events: events.length,
  198. 198 skipped_rows: skipped,
  199. 199 users: firstSeen.size,
  200. 200 accounts: new Set(events.map((e) => e.account)).size,
  201. 201 dau,
  202. 202 wau,
  203. 203 mau,
  204. 204 avg_dau_30d: round(avgDau30, 2),
  205. 205 stickiness: round(stickiness, 4),
  206. 206 mau_change: mauPrev ? round((mau - mauPrev) / mauPrev, 4) : null,
  207. 207 active_accounts_30d: accounts30,
  208. 208 active_accounts_prev_30d: accountsPrev30,
  209. 209 activation: { definition: activationEvent ? `did "${activationEvent}" within ${activationDays} days of first event` : `active on 3+ distinct days within ${activationDays} days of first event`, new_users: actN, activated: actYes, rate: activationRate === null ? null : round(activationRate, 4), by_week: activationRows },
  210. 210 top_features: features.slice(0, 15),
  211. 211 retention,
  212. 212 accounts_trending_down: trending,
  213. 213};
  214. 214writeOut(outJson, JSON.stringify(summary, null, 2) + "\n");
  215. 215
  216. 216// HTML
  217. 217const n0 = (v) => Math.round(v).toLocaleString("en-US");
  218. 218const delta = (v) => (v === null ? "" : `${v >= 0 ? "+" : ""}${(v * 100).toFixed(0)}% vs prior 30 days`);
  219. 219const title = args.title || "Product usage";
  220. 220const body = [
  221. 221 tiles([
  222. 222 { label: "DAU", value: n0(dau), hint: `on ${lastDay}` },
  223. 223 { label: "WAU", value: n0(wau), hint: "last 7 days" },
  224. 224 { label: "MAU", value: n0(mau), hint: delta(summary.mau_change) },
  225. 225 { label: "Stickiness (DAU/MAU)", value: pct(stickiness, 0), hint: `avg DAU ${avgDau30.toFixed(1)}` },
  226. 226 { label: "Active accounts", value: n0(accounts30), hint: `last 30 days (prior ${accountsPrev30})` },
  227. 227 { label: "Activation rate", value: activationRate === null ? "n/a" : pct(activationRate, 0), hint: `${actYes} of ${actN} new users` },
  228. 228 ]),
  229. 229 `<div class="grid">`,
  230. 230 card("Daily active users, last 90 days", lineChart(dayLabels, [{ name: "DAU", values: dauSeries }], n0)),
  231. 231 card("Weekly active users and accounts", lineChart(weekLabels, [{ name: "Active users", values: wauSeries }, { name: "Active accounts", values: wacSeries }], n0), "Each point is the 7 days ending on that week's last day."),
  232. 232 `</div><div class="grid">`,
  233. 233 card(
  234. 234 "Top features, last 30 days (by users)",
  235. 235 features.length ? barChart(features.slice(0, 10).map((f) => ({ label: f.event, value: f.users })), n0) : "<p>No feature events.</p>",
  236. 236 `Ignored: ${[...ignore].join(", ") || "nothing"}.`,
  237. 237 ),
  238. 238 card(
  239. 239 "Feature detail",
  240. 240 table(
  241. 241 [{ label: "Event" }, { label: "Users", numeric: true }, { label: "% of MAU", numeric: true }, { label: "Accounts", numeric: true }, { label: "Events", numeric: true }],
  242. 242 features.slice(0, 10).map((f) => [f.event, n0(f.users), pct(f.share_of_mau, 0), n0(f.accounts), n0(f.events)]),
  243. 243 ),
  244. 244 ),
  245. 245 `</div>`,
  246. 246 card(
  247. 247 "Weekly retention by first-seen week",
  248. 248 retention.length ? heatmap(retention.map((r) => r.cohort), Array.from({ length: 8 }, (_, i) => `W${i}`), retention.map((r) => r.weeks), { label: "Users", values: retention.map((r) => String(r.users)) }) : "<p>Not enough history.</p>",
  249. 249 "Share of each cohort active in each week after their first event. The current, partial week is left blank.",
  250. 250 ),
  251. 251 `<div style="height:16px"></div><div class="grid">`,
  252. 252 card(
  253. 253 "Activation by signup week",
  254. 254 table(
  255. 255 [{ label: "Week" }, { label: "New users", numeric: true }, { label: "Activated", numeric: true }, { label: "Rate", numeric: true }],
  256. 256 activationRows.map((r) => [r.week, n0(r.users), n0(r.activated), pct(r.users ? r.activated / r.users : 0, 0)]),
  257. 257 ),
  258. 258 `Activated = ${summary.activation.definition}.`,
  259. 259 ),
  260. 260 card(
  261. 261 "Accounts trending down",
  262. 262 trending.length
  263. 263 ? table(
  264. 264 [{ label: "Account" }, { label: "Events (prior 28d to last 28d)", numeric: true }, { label: "Change", numeric: true }, { label: "Users", numeric: true }, { label: "Signal" }],
  265. 265 trending.map((a) => [a.account, `${n0(a.prior_events)} to ${n0(a.recent_events)}`, pct(a.events_change, 0), `${a.prior_users} to ${a.recent_users}`, a.days_since_last_event >= 14 ? flag("bad", `quiet ${a.days_since_last_event} days`) : flag("warn", "usage down")]),
  266. 266 { html: true },
  267. 267 )
  268. 268 : "<p>No account dropped 30% or more.</p>",
  269. 269 "Accounts with 20+ events in the prior 28 days whose events or active users fell 30% or more, or with no events in 14 days.",
  270. 270 ),
  271. 271 `</div>`,
  272. 272 `<p class="note">Source: ${input.replace(/[<>&"]/g, "")}. ${n0(events.length)} events, ${n0(summary.users)} users, ${n0(summary.accounts)} accounts, as of ${lastDay}.${skipped ? ` Skipped ${skipped} rows.` : ""}</p>`,
  273. 273].join("\n");
  274. 274writeOut(outHtml, page(title, `As of ${lastDay}`, body));
  275. 275
  276. 276process.stdout.write(`Wrote ${outHtml} and ${outJson}\n`);
  277. 277process.stdout.write(`DAU ${dau}, WAU ${wau}, MAU ${mau}, stickiness ${pct(stickiness, 0)}, activation ${activationRate === null ? "n/a" : pct(activationRate, 0)}, ${trending.length} account(s) trending down.\n`);
Sign in to comment on a line