@commonpub/layer 0.61.0 → 0.62.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@commonpub/layer",
-  "version": "0.61.0",
+  "version": "0.62.0",
   "type": "module",
   "main": "./nuxt.config.ts",
   "files": [
@@ -54,15 +54,15 @@
     "vue-router": "^4.3.0",
     "zod": "^4.3.6",
     "@commonpub/auth": "0.8.0",
-    "@commonpub/editor": "0.7.11",
     "@commonpub/config": "0.19.0",
+    "@commonpub/explainer": "0.7.15",
+    "@commonpub/docs": "0.6.3",
     "@commonpub/protocol": "0.13.0",
+    "@commonpub/server": "2.82.0",
+    "@commonpub/editor": "0.7.11",
     "@commonpub/learning": "0.5.2",
-    "@commonpub/server": "2.81.0",
     "@commonpub/ui": "0.9.2",
-    "@commonpub/explainer": "0.7.15",
-    "@commonpub/schema": "0.34.0",
-    "@commonpub/docs": "0.6.3"
+    "@commonpub/schema": "0.35.0"
   },
   "devDependencies": {
     "@testing-library/jest-dom": "^6.9.1",

package/server/api/public/v1/metrics/timeseries.get.ts

@@ -0,0 +1,41 @@
+import { getMetricsTimeseries, TIMESERIES_METRICS } from '@commonpub/server';
+import { z } from 'zod';
+
+const DAY = /^\d{4}-\d{2}-\d{2}$/;
+const DAY_MS = 86_400_000;
+
+const querySchema = z.object({
+  metric: z.enum(Object.keys(TIMESERIES_METRICS) as [string, ...string[]]),
+  interval: z.enum(['day', 'week', 'month']).default('day'),
+  from: z.string().regex(DAY).optional(),
+  to: z.string().regex(DAY).optional(),
+});
+
+/**
+ * GET /api/public/v1/metrics/timeseries
+ *
+ * Scope: read:analytics. Daily time-series from the `metrics_daily` rollups.
+ * `metric` is one of the registered series (users.total/new, content.total/new/
+ * views/likes/comments); `interval` buckets day|week|month. Defaults to the last
+ * 90 days. Engagement (views/likes/comments) series begin at the first rollup,
+ * surfaced via `since`.
+ */
+export default defineEventHandler(async (event) => {
+  requireApiScope(event, 'read:analytics');
+  const parsed = querySchema.safeParse(getQuery(event));
+  if (!parsed.success) {
+    throw createError({ statusCode: 400, statusMessage: 'Invalid query parameters', data: parsed.error.flatten() });
+  }
+  const { metric, interval } = parsed.data;
+
+  // Default to the last 90 days; clamp the span to 2 years to bound the scan.
+  const todayMs = Date.now();
+  const to = parsed.data.to ?? new Date(todayMs).toISOString().slice(0, 10);
+  let from = parsed.data.from ?? new Date(todayMs - 90 * DAY_MS).toISOString().slice(0, 10);
+  if (from > to) from = to;
+  const minFrom = new Date(new Date(`${to}T00:00:00Z`).getTime() - 730 * DAY_MS).toISOString().slice(0, 10);
+  if (from < minFrom) from = minFrom;
+
+  const db = useDB();
+  return await getMetricsTimeseries(db, { metric, interval, from, to });
+});

package/server/api/public/v1/openapi.json.get.ts

@@ -379,6 +379,9 @@ export default defineEventHandler((event) => {
       '/metrics/engagement': {
         get: { summary: 'Aggregate engagement ratios and funnels', security: [{ bearer: ['read:analytics'] }], responses: { '200': { description: 'OK', content: { 'application/json': { schema: { type: 'object' } } } } } },
       },
+      '/metrics/timeseries': {
+        get: { summary: 'Daily time-series from rollups', security: [{ bearer: ['read:analytics'] }], parameters: [{ name: 'metric', in: 'query', required: true, schema: { type: 'string', enum: ['users.total', 'users.new', 'content.total', 'content.new', 'content.views', 'content.likes', 'content.comments'] } }, { name: 'interval', in: 'query', schema: { type: 'string', enum: ['day', 'week', 'month'] } }, { name: 'from', in: 'query', schema: { type: 'string', format: 'date' } }, { name: 'to', in: 'query', schema: { type: 'string', format: 'date' } }], responses: { '200': { description: 'OK', content: { 'application/json': { schema: { type: 'object' } } } } } },
+      },
       '/metrics/federation': {
         get: { summary: 'Federation reach (opt-in; read:federation)', security: [{ bearer: ['read:federation'] }], parameters: [{ name: 'limit', in: 'query', schema: { type: 'integer' } }], responses: { '200': { description: 'OK', content: { 'application/json': { schema: { type: 'object' } } } }, '404': { description: 'Federation reach metrics not enabled', content: { 'application/json': { schema: { $ref: '#/components/schemas/Error' } } } } } },
       },

package/server/plugins/metrics-rollup.ts

@@ -0,0 +1,54 @@
+/**
+ * Daily analytics rollup worker (Phase 3).
+ *
+ * When `features.publicApi` is on, snapshots aggregate metrics into
+ * `metrics_daily` so `GET /api/public/v1/metrics/timeseries` has history. On the
+ * first ever run (empty table) it backfills the deterministic count-based series
+ * from timestamps. Runs are idempotent (upsert per day), so the periodic
+ * interval just refreshes today's row. Aggregates only — no per-user data.
+ */
+import { runDailyRollup, backfillMetricsDaily } from '@commonpub/server';
+import { metricsDaily } from '@commonpub/schema';
+
+const ROLLUP_INTERVAL_MS = 6 * 60 * 60 * 1000; // every 6h; refreshes today's snapshot
+
+export default defineNitroPlugin((nitro) => {
+  if (process.env.NODE_ENV === 'test') return;
+
+  let interval: ReturnType<typeof setInterval> | null = null;
+
+  const startupTimer = setTimeout(() => {
+    try {
+      const config = useConfig();
+      if (!config.features.publicApi) return; // no public API ⇒ no rollups needed
+      console.log(`[metrics-rollup] worker started (interval: ${ROLLUP_INTERVAL_MS}ms)`);
+      runRollup();
+      interval = setInterval(runRollup, ROLLUP_INTERVAL_MS);
+    } catch (err) {
+      console.error('[metrics-rollup] failed to start:', err instanceof Error ? err.message : err);
+    }
+  }, 15_000); // stagger after federation/registry workers
+
+  async function runRollup(): Promise<void> {
+    try {
+      const db = useDB();
+      const today = new Date().toISOString().slice(0, 10); // YYYY-MM-DD (UTC)
+      const [existing] = await db.select({ id: metricsDaily.id }).from(metricsDaily).limit(1);
+      if (!existing) {
+        const n = await backfillMetricsDaily(db);
+        console.log(`[metrics-rollup] backfilled ${n} historical rows`);
+      }
+      await runDailyRollup(db, today);
+    } catch (err) {
+      console.error('[metrics-rollup] run error:', err instanceof Error ? err.message : err);
+    }
+  }
+
+  nitro.hooks.hook('close', () => {
+    clearTimeout(startupTimer);
+    if (interval) {
+      clearInterval(interval);
+      interval = null;
+    }
+  });
+});