@stacksjs/ts-analytics 0.1.6

package/src/handlers/sessions.ts

@@ -0,0 +1,413 @@
+/**
+ * Session handlers
+ */
+
+import { querySessionItemsInRange, queryAllItems, dynamodb, TABLE_NAME, unmarshall } from '../lib/dynamodb'
+import { readDimRollupPrefix } from '../lib/rollups'
+import { parseDateRange, formatDuration } from '../utils/date'
+import { jsonResponse, errorResponse } from '../utils/response'
+import { getQueryParams } from '../../deploy/lambda-adapter'
+
+/**
+ * GET /api/sites/{siteId}/sessions
+ */
+export async function handleGetSessions(request: Request, siteId: string): Promise<Response> {
+  try {
+    const query = getQueryParams(request)
+    const { startDate, endDate } = parseDateRange(query)
+    const limit = Math.min(Number(query.limit) || 50, 200)
+    const filter = query.filter || ''
+
+    // Time-keyed GSI query (#171): date-bounded and startedAt-DESC ordered
+    // (the raw sk is random-id order, so "recent" was arbitrary before).
+    const result = await queryAllItems({
+      TableName: TABLE_NAME,
+      IndexName: 'GSI1',
+      KeyConditionExpression: 'gsi1pk = :pk AND gsi1sk BETWEEN :start AND :end',
+      ExpressionAttributeValues: {
+        ':pk': { S: `SITE#${siteId}#SESSIONS` },
+        ':start': { S: startDate.toISOString() },
+        ':end': { S: `${endDate.toISOString()}~` },
+      },
+      ScanIndexForward: false,
+      Limit: limit * 2,
+    }, limit * 2) as { Items?: any[] }
+
+    let sessions = (result.Items || []).map(unmarshall).filter((s: any) => {
+      const sessionTime = new Date(s.startedAt || s.endedAt || s.timestamp)
+      return sessionTime >= startDate && sessionTime <= endDate
+    })
+
+    if (filter) {
+      const f = filter.toLowerCase()
+      sessions = sessions.filter((s: any) =>
+        (s.country?.toLowerCase().includes(f)) ||
+        (s.browser?.toLowerCase().includes(f)) ||
+        (s.deviceType?.toLowerCase().includes(f)) ||
+        (s.os?.toLowerCase().includes(f)) ||
+        (s.referrerSource?.toLowerCase().includes(f))
+      )
+    }
+
+    sessions = sessions.slice(0, limit)
+
+    const formattedSessions = sessions.map((s: any) => ({
+      id: s.id || s.sessionId,
+      visitorId: s.visitorId,
+      startedAt: s.startedAt,
+      endedAt: s.endedAt,
+      duration: s.duration,
+      durationFormatted: formatDuration(s.duration || 0),
+      pageViewCount: s.pageViewCount || 0,
+      eventCount: s.eventCount || 0,
+      isBounce: s.isBounce,
+      entryPage: s.entryPage,
+      exitPage: s.exitPage,
+      referrerSource: s.referrerSource || 'direct',
+      country: s.country,
+      region: s.region,
+      city: s.city,
+      deviceType: s.deviceType,
+      browser: s.browser,
+      os: s.os,
+      utmSource: s.utmSource,
+      utmMedium: s.utmMedium,
+      utmCampaign: s.utmCampaign,
+    }))
+
+    return jsonResponse({
+      sessions: formattedSessions,
+      total: formattedSessions.length,
+      dateRange: {
+        start: startDate.toISOString(),
+        end: endDate.toISOString(),
+      },
+    })
+  }
+catch (error) {
+    console.error('Get sessions error:', error)
+    return errorResponse('Failed to fetch sessions')
+  }
+}
+
+/**
+ * GET /api/sites/{siteId}/sessions/{sessionId}
+ */
+export async function handleGetSessionDetail(request: Request, siteId: string, sessionId: string): Promise<Response> {
+  try {
+    const query = getQueryParams(request)
+    const includeEvents = query.includeEvents !== 'false'
+    const includePageviews = query.includePageviews !== 'false'
+
+    // Get session
+    const sessionResult = await dynamodb.query({
+      TableName: TABLE_NAME,
+      KeyConditionExpression: 'pk = :pk AND sk = :sk',
+      ExpressionAttributeValues: {
+        ':pk': { S: `SITE#${siteId}` },
+        ':sk': { S: `SESSION#${sessionId}` },
+      },
+    }) as { Items?: any[] }
+
+    if (!sessionResult.Items || sessionResult.Items.length === 0) {
+      return jsonResponse({ error: 'Session not found' }, 404)
+    }
+
+    const session = unmarshall(sessionResult.Items[0])
+
+    // The session timeline was PERMANENTLY EMPTY (#171): these queries used
+    // gsi1pk = SESSION#{id}, but pageviews/events write DATE-keyed gsi1pk
+    // values — the key could never match (and the index name was the wrong
+    // case). Query the session's own time window on the main table instead
+    // and filter by sessionId.
+    const windowStart = typeof session.startedAt === 'string' ? session.startedAt : new Date(session.startedAt).toISOString()
+    const windowEnd = session.endedAt
+      ? (typeof session.endedAt === 'string' ? session.endedAt : new Date(session.endedAt).toISOString())
+      : new Date().toISOString()
+
+    const itemsInWindow = async (prefix: string): Promise<any[]> => {
+      const res = await queryAllItems({
+        TableName: TABLE_NAME,
+        KeyConditionExpression: 'pk = :pk AND sk BETWEEN :start AND :end',
+        ExpressionAttributeValues: {
+          ':pk': { S: `SITE#${siteId}` },
+          ':start': { S: `${prefix}${windowStart}` },
+          ':end': { S: `${prefix}${windowEnd}~` },
+        },
+      })
+      return (res.Items || []).map(unmarshall)
+        .filter(item => item.sessionId === sessionId)
+        .sort((a, b) => new Date(a.timestamp).getTime() - new Date(b.timestamp).getTime())
+    }
+
+    // Get pageviews for this session
+    let pageviews: any[] = []
+    if (includePageviews) {
+      pageviews = await itemsInWindow('PAGEVIEW#')
+    }
+
+    // Get events for this session
+    let events: any[] = []
+    if (includeEvents) {
+      events = await itemsInWindow('EVENT#')
+    }
+
+    // Build timeline of all activities
+    const timeline = [
+      ...pageviews.map(pv => ({
+        type: 'pageview' as const,
+        timestamp: pv.timestamp,
+        path: pv.path,
+        title: pv.title,
+        referrer: pv.referrer,
+      })),
+      ...events.map(e => ({
+        type: 'event' as const,
+        timestamp: e.timestamp,
+        eventName: e.eventName,
+        properties: e.properties,
+      })),
+    ].sort((a, b) => new Date(a.timestamp).getTime() - new Date(b.timestamp).getTime())
+
+    return jsonResponse({
+      session: {
+        id: session.id || session.sessionId,
+        visitorId: session.visitorId,
+        startedAt: session.startedAt,
+        endedAt: session.endedAt,
+        duration: session.duration,
+        durationFormatted: formatDuration(session.duration || 0),
+        pageViewCount: session.pageViewCount || pageviews.length,
+        eventCount: session.eventCount || events.length,
+        isBounce: session.isBounce,
+        entryPage: session.entryPage,
+        exitPage: session.exitPage,
+        referrerSource: session.referrerSource || 'direct',
+        referrer: session.referrer,
+        country: session.country,
+        region: session.region,
+        city: session.city,
+        deviceType: session.deviceType,
+        browser: session.browser,
+        os: session.os,
+        screenSize: session.screenSize,
+        language: session.language,
+        utmSource: session.utmSource,
+        utmMedium: session.utmMedium,
+        utmCampaign: session.utmCampaign,
+        utmContent: session.utmContent,
+        utmTerm: session.utmTerm,
+      },
+      pageviews,
+      events,
+      timeline,
+    })
+  }
+catch (error) {
+    console.error('Get session detail error:', error)
+    return errorResponse('Failed to fetch session detail')
+  }
+}
+
+/**
+ * GET /api/sites/{siteId}/flow
+ */
+export async function handleGetUserFlow(request: Request, siteId: string): Promise<Response> {
+  try {
+    const query = getQueryParams(request)
+    const { startDate, endDate } = parseDateRange(query)
+    const depth = Math.min(Number(query.depth) || 5, 10)
+
+    // Query sessions
+    const result = await querySessionItemsInRange(siteId, startDate, endDate) as { Items?: any[] }
+
+    const sessions = (result.Items || []).map(unmarshall).filter(s => {
+      const sessionStart = new Date(s.startedAt)
+      return sessionStart >= startDate && sessionStart <= endDate
+    })
+
+    // Build flow data from entry/exit pages and page sequences
+    const flows: Record<string, { from: string; to: string; count: number }> = {}
+    const entryPages: Record<string, number> = {}
+    const exitPages: Record<string, number> = {}
+
+    for (const session of sessions) {
+      // Track entry pages
+      if (session.entryPage) {
+        entryPages[session.entryPage] = (entryPages[session.entryPage] || 0) + 1
+      }
+
+      // Track exit pages
+      if (session.exitPage) {
+        exitPages[session.exitPage] = (exitPages[session.exitPage] || 0) + 1
+      }
+
+      // Track page flows if we have page sequence
+      const pageSequence = session.pageSequence || []
+      for (let i = 0; i < Math.min(pageSequence.length - 1, depth); i++) {
+        const key = `${pageSequence[i]}|${pageSequence[i + 1]}`
+        if (!flows[key]) {
+          flows[key] = { from: pageSequence[i], to: pageSequence[i + 1], count: 0 }
+        }
+        flows[key].count++
+      }
+    }
+
+    const flowData = Object.values(flows)
+      .sort((a, b) => b.count - a.count)
+      .slice(0, 100)
+
+    const topEntryPages = Object.entries(entryPages)
+      .map(([path, count]) => ({ path, count }))
+      .sort((a, b) => b.count - a.count)
+      .slice(0, 10)
+
+    const topExitPages = Object.entries(exitPages)
+      .map(([path, count]) => ({ path, count }))
+      .sort((a, b) => b.count - a.count)
+      .slice(0, 10)
+
+    return jsonResponse({
+      flows: flowData,
+      entryPages: topEntryPages,
+      exitPages: topExitPages,
+      totalSessions: sessions.length,
+      dateRange: {
+        start: startDate.toISOString(),
+        end: endDate.toISOString(),
+      },
+    })
+  }
+catch (error) {
+    console.error('Get user flow error:', error)
+    return errorResponse('Failed to fetch user flow')
+  }
+}
+
+/**
+ * GET /api/sites/{siteId}/entry-exit
+ */
+export async function handleGetEntryExitPages(request: Request, siteId: string): Promise<Response> {
+  try {
+    const query = getQueryParams(request)
+    const { startDate, endDate } = parseDateRange(query)
+    const limit = Math.min(Number(query.limit) || 10, 100)
+
+    // Rolled prefix (#172): settled days from ROLLUP#DIMS survive the raw TTL.
+    const { days: rolled, rawWindowStart } = await readDimRollupPrefix(siteId, startDate, endDate)
+
+    const result = rawWindowStart <= endDate
+      ? await querySessionItemsInRange(siteId, rawWindowStart, endDate) as { Items?: any[] }
+      : { Items: [] }
+
+    const sessions = (result.Items || []).map(unmarshall).filter(s => {
+      const sessionStart = new Date(s.startedAt)
+      return sessionStart >= startDate && sessionStart <= endDate
+    })
+
+    const entryStats: Record<string, { sessions: number; bounces: number }> = {}
+    const exitStats: Record<string, { sessions: number }> = {}
+
+    for (const session of sessions) {
+      // Sessions store entryPath/exitPath — this handler read the nonexistent
+      // entryPage/exitPage fields, so the report was ALWAYS empty (#172 audit).
+      if (session.entryPath) {
+        if (!entryStats[session.entryPath]) {
+          entryStats[session.entryPath] = { sessions: 0, bounces: 0 }
+        }
+        entryStats[session.entryPath].sessions++
+        if (session.isBounce) entryStats[session.entryPath].bounces++
+      }
+
+      if (session.exitPath) {
+        if (!exitStats[session.exitPath]) {
+          exitStats[session.exitPath] = { sessions: 0 }
+        }
+        exitStats[session.exitPath].sessions++
+      }
+    }
+
+    // Merge the rolled prefix.
+    for (const dayR of rolled) {
+      for (const [path, cell] of Object.entries(dayR.entries || {})) {
+        const e = (entryStats[path] ||= { sessions: 0, bounces: 0 })
+        e.sessions += cell.s
+        e.bounces += cell.b
+      }
+      for (const [path, cell] of Object.entries(dayR.exits || {})) {
+        const x = (exitStats[path] ||= { sessions: 0 })
+        x.sessions += cell.s
+      }
+    }
+
+    const entryPages = Object.entries(entryStats)
+      .map(([path, stats]) => ({
+        path,
+        sessions: stats.sessions,
+        bounceRate: stats.sessions > 0 ? Math.round((stats.bounces / stats.sessions) * 100) : 0,
+      }))
+      .sort((a, b) => b.sessions - a.sessions)
+      .slice(0, limit)
+
+    const exitPages = Object.entries(exitStats)
+      .map(([path, stats]) => ({
+        path,
+        sessions: stats.sessions,
+      }))
+      .sort((a, b) => b.sessions - a.sessions)
+      .slice(0, limit)
+
+    return jsonResponse({ entryPages, exitPages })
+  }
+catch (error) {
+    console.error('Get entry/exit pages error:', error)
+    return errorResponse('Failed to fetch entry/exit pages')
+  }
+}
+
+/**
+ * GET /api/sites/{siteId}/live
+ */
+export async function handleGetLiveView(request: Request, siteId: string): Promise<Response> {
+  try {
+    const query = getQueryParams(request)
+    const minutes = Number(query.minutes) || 5
+    const cutoff = new Date(Date.now() - minutes * 60 * 1000)
+
+    const result = await dynamodb.query({
+      TableName: TABLE_NAME,
+      KeyConditionExpression: 'pk = :pk AND sk BETWEEN :start AND :end',
+      ExpressionAttributeValues: {
+        ':pk': { S: `SITE#${siteId}` },
+        ':start': { S: `PAGEVIEW#${cutoff.toISOString()}` },
+        ':end': { S: 'PAGEVIEW#Z' },
+      },
+      ScanIndexForward: false,
+      Limit: 100,
+    }) as { Items?: any[] }
+
+    const pageviews = (result.Items || []).map(unmarshall)
+
+    const liveVisitors = pageviews.map(pv => ({
+      visitorId: pv.visitorId?.substring(0, 8) + '...',
+      path: pv.path,
+      timestamp: pv.timestamp,
+      country: pv.country,
+      deviceType: pv.deviceType,
+      browser: pv.browser,
+    }))
+
+    const uniqueVisitors = new Set(pageviews.map(pv => pv.visitorId)).size
+
+    return jsonResponse({
+      visitors: liveVisitors,
+      count: uniqueVisitors,
+      pageviews: pageviews.length,
+      lastUpdated: new Date().toISOString(),
+    })
+  }
+catch (error) {
+    console.error('Get live view error:', error)
+    return errorResponse('Failed to fetch live view')
+  }
+}

package/src/handlers/sharing.ts

@@ -0,0 +1,198 @@
+/**
+ * Share link handlers
+ */
+
+import { generateId } from '../index'
+import { randomToken } from '../lib/crypto-random'
+import { dynamodb, TABLE_NAME, unmarshall, marshall } from '../lib/dynamodb'
+import { jsonResponse, errorResponse } from '../utils/response'
+import { getQueryParams } from '../../deploy/lambda-adapter'
+
+/**
+ * Generate a secure share token (CSPRNG so tokens aren't guessable — #130).
+ */
+function generateShareToken(): string {
+  return randomToken(24)
+}
+
+/**
+ * POST /api/sites/{siteId}/share
+ */
+export async function handleCreateShareLink(request: Request, siteId: string): Promise<Response> {
+  try {
+    const body = await request.json() as Record<string, any>
+
+    const token = generateShareToken()
+    const shareLink = {
+      pk: `SHARE#${token}`,
+      sk: `SITE#${siteId}`,
+      // Per-site listing (#152) — share rows were unreachable by site before.
+      gsi1pk: `SITE#${siteId}#SHARES`,
+      gsi1sk: new Date().toISOString(),
+      token,
+      siteId,
+      permissions: body.permissions || ['view'],
+      expiresAt: body.expiresAt || null,
+      password: body.password || null,
+      allowedMetrics: body.allowedMetrics || ['all'],
+      createdAt: new Date().toISOString(),
+    }
+
+    await dynamodb.putItem({
+      TableName: TABLE_NAME,
+      Item: marshall(shareLink),
+    })
+
+    return jsonResponse({
+      shareLink: {
+        token,
+        url: `/shared/${token}`,
+        expiresAt: shareLink.expiresAt,
+        createdAt: shareLink.createdAt,
+      },
+    }, 201)
+  }
+catch (error) {
+    console.error('Create share link error:', error)
+    return errorResponse('Failed to create share link')
+  }
+}
+
+/**
+ * Resolve a share token to its link record (60s in-process cache — the guard
+ * consults this on every shared-dashboard API call, #152). Returns null for
+ * unknown or expired tokens.
+ */
+const tokenCache = new Map<string, { link: Record<string, any> | null, at: number }>()
+
+export async function resolveShareToken(token: string): Promise<Record<string, any> | null> {
+  if (!/^[\w-]{16,64}$/.test(token))
+    return null
+  const hit = tokenCache.get(token)
+  if (hit && Date.now() - hit.at < 60_000)
+    return hit.link
+  const result = await dynamodb.query({
+    TableName: TABLE_NAME,
+    KeyConditionExpression: 'pk = :pk',
+    ExpressionAttributeValues: { ':pk': { S: `SHARE#${token}` } },
+  }) as { Items?: any[] }
+  const link = result.Items?.[0] ? unmarshall(result.Items[0]) : null
+  tokenCache.set(token, { link, at: Date.now() })
+  if (!link)
+    return null
+  if (link.expiresAt && new Date(link.expiresAt) < new Date())
+    return null
+  return link
+}
+
+/** Test hook. */
+export function clearShareTokenCache(): void {
+  tokenCache.clear()
+}
+
+/**
+ * GET /api/sites/{siteId}/share — list this site's share links (owner view;
+ * behind the site auth guard like every management endpoint).
+ */
+export async function handleListShareLinks(_request: Request, siteId: string): Promise<Response> {
+  try {
+    const { queryAllItems } = await import('../lib/dynamodb')
+    const result = await queryAllItems({
+      TableName: TABLE_NAME,
+      IndexName: 'GSI1',
+      KeyConditionExpression: 'gsi1pk = :pk',
+      ExpressionAttributeValues: { ':pk': { S: `SITE#${siteId}#SHARES` } },
+    })
+    const links = (result.Items || []).map(unmarshall).map(link => ({
+      token: link.token,
+      url: `/shared/${link.token}`,
+      hasPassword: !!link.password,
+      expiresAt: link.expiresAt || null,
+      createdAt: link.createdAt,
+    }))
+    return jsonResponse({ links })
+  }
+  catch (error) {
+    console.error('List share links error:', error)
+    return errorResponse('Failed to list share links')
+  }
+}
+
+/**
+ * DELETE /api/sites/{siteId}/share/{token} — revoke a share link.
+ */
+export async function handleRevokeShareLink(_request: Request, siteId: string, token: string): Promise<Response> {
+  try {
+    const link = await resolveShareToken(token)
+    if (link && link.siteId !== siteId) {
+      return jsonResponse({ error: 'Share link does not belong to this site' }, 403)
+    }
+    await dynamodb.deleteItem({
+      TableName: TABLE_NAME,
+      Key: { pk: { S: `SHARE#${token}` }, sk: { S: `SITE#${siteId}` } },
+    })
+    tokenCache.delete(token)
+    return jsonResponse({ success: true, token })
+  }
+  catch (error) {
+    console.error('Revoke share link error:', error)
+    return errorResponse('Failed to revoke share link')
+  }
+}
+
+/**
+ * GET /api/share/{token}
+ */
+export async function handleGetSharedDashboard(request: Request, token: string): Promise<Response> {
+  try {
+    // Find share link
+    const result = await dynamodb.query({
+      TableName: TABLE_NAME,
+      KeyConditionExpression: 'pk = :pk',
+      ExpressionAttributeValues: {
+        ':pk': { S: `SHARE#${token}` },
+      },
+    }) as { Items?: any[] }
+
+    if (!result.Items || result.Items.length === 0) {
+      return jsonResponse({ error: 'Invalid or expired share link' }, 404)
+    }
+
+    const shareLink = unmarshall(result.Items[0])
+
+    // Check expiration
+    if (shareLink.expiresAt && new Date(shareLink.expiresAt) < new Date()) {
+      return jsonResponse({ error: 'Share link has expired' }, 410)
+    }
+
+    // Check password if required
+    const query = getQueryParams(request)
+    if (shareLink.password && query.password !== shareLink.password) {
+      return jsonResponse({ error: 'Password required', requiresPassword: true }, 401)
+    }
+
+    // Site display name for the public page header.
+    let siteName = shareLink.siteId
+    try {
+      const siteRes = await dynamodb.getItem({
+        TableName: TABLE_NAME,
+        Key: { pk: { S: 'SITES' }, sk: { S: `SITE#${shareLink.siteId}` } },
+      }) as { Item?: Record<string, any> }
+      if (siteRes.Item)
+        siteName = unmarshall(siteRes.Item).name || siteName
+    }
+    catch {}
+
+    return jsonResponse({
+      valid: true,
+      siteId: shareLink.siteId,
+      siteName,
+      permissions: shareLink.permissions,
+      allowedMetrics: shareLink.allowedMetrics,
+    })
+  }
+catch (error) {
+    console.error('Get shared dashboard error:', error)
+    return errorResponse('Failed to validate share link')
+  }
+}