feat(api): implement privacy-safe paginated analytics endpoint

apps/api/src/routes/public.ts

@@ -3,9 +3,7 @@ import { z } from "zod";
 import { providers } from "../lib/pricing.js";
 import { getAnalyticsSummary, getUsageEvents } from "../lib/persistence.js";
 import { config } from "../lib/config.js";
-import { apiVersion } from "../lib/build-metadata.js";
-import { getCatalog } from "../services/query-service.js";
-import { MAX_USAGE_EVENTS } from "../lib/storage/constants.js";
+import { getCatalog, fetchPaginatedAnalytics } from "../services/query-service.js";
 
 export const publicRouter = Router();
 
@@ -66,16 +64,11 @@ publicRouter.get("/api/usage", async (req, res, next) => {
 
 publicRouter.get("/api/analytics", async (req, res, next) => {
   try {
-    const parsed = analyticsQuerySchema.safeParse(req.query);
-    if (!parsed.success) {
-      return res.status(400).json({ error: parsed.error.flatten() });
-    }
+    const limit = req.query.limit ? parseInt(req.query.limit as string, 10) : 10;
+    const cursor = req.query.cursor ? (req.query.cursor as string) : null;
 
-    const analytics = await getAnalyticsSummary({
-      recentUsageLimit: parsed.data.recentUsageLimit,
-      recentPaymentLimit: parsed.data.recentPaymentLimit
-    });
-    res.json(analytics);
+    const result = await fetchPaginatedAnalytics(limit, cursor);
+    return res.json(result);
   } catch (error) {
     next(error);
   }

apps/api/src/services/analytics-privacy.ts

@@ -0,0 +1,20 @@
+import { PrivacySafeAnalyticsRecord } from "@query402/shared";
+
+export function formatPrivacySafeAnalytics(rawRecords: any[]): PrivacySafeAnalyticsRecord[] {
+  return rawRecords.map(record => {
+    // Note: mapping fields to match UsageEvent structure from persistence.ts
+    const rawAddress = record.payerAddress || '';
+    const redactedAddress = rawAddress.length > 8 
+      ? `${rawAddress.slice(0, 4)}...${rawAddress.slice(-4)}`
+      : 'Confidential';
+
+    return {
+      id: record.id?.toString() || '',
+      timestamp: record.timestamp || new Date().toISOString(),
+      payerAddress: redactedAddress,
+      volumeType: record.mode === 'demo' ? 'demo' : 'settled',
+      amount: Number(record.priceUsd || 0),
+      asset: 'XLM'
+    };
+  });
+}

apps/api/src/services/query-service.ts

@@ -58,3 +58,50 @@ export function getCatalog() {
     byCategory
   };
 }
+
+import { getUsageEvents } from "../lib/persistence.js";
+import { formatPrivacySafeAnalytics } from "./analytics-privacy.js";
+import { PaginatedAnalyticsResponse } from "@query402/shared";
+
+/**
+ * Fetches privacy-safe, cursor-paginated analytics data from the JSON file layer.
+ */
+export async function fetchPaginatedAnalytics(
+  limit: number = 10,
+  cursor: string | null = null
+): Promise<PaginatedAnalyticsResponse> {
+  // 1. Read all logs from our local JSON file storage engine
+  const allEvents = getUsageEvents();
+
+  let sliceStartIndex = 0;
+
+  // 2. If a cursor is provided, find its index to start our next page chunk
+  if (cursor) {
+    const cursorIndex = allEvents.findIndex((event: any) => event.id === cursor);
+    if (cursorIndex !== -1) {
+      // Start slicing immediately after the cursor item
+      sliceStartIndex = cursorIndex + 1;
+    }
+  }
+
+  // 3. Extract the chunk + 1 extra item to check if a next page exists
+  const fetchCount = limit + 1;
+  const pageChunk = allEvents.slice(sliceStartIndex, sliceStartIndex + fetchCount);
+
+  const hasMore = pageChunk.length > limit;
+  // Trim down to the requested page limit
+  const validRecords = hasMore ? pageChunk.slice(0, limit) : pageChunk;
+
+  // 4. Filter and mask the records safely via our privacy module
+  const cleanData = formatPrivacySafeAnalytics(validRecords);
+
+  // 5. Pick the ID of the last element in our current view as the next cursor token
+  const nextCursor = hasMore && cleanData.length > 0 ? cleanData[cleanData.length - 1].id : null;
+
+  return {
+    success: true,
+    hasMore,
+    nextCursor,
+    data: cleanData
+  };
+}