@stacksjs/ts-analytics 0.1.6

package/src/handlers/experiments.ts

@@ -0,0 +1,138 @@
+/**
+ * A/B Testing / Experiment handlers
+ */
+
+import { generateId } from '../index'
+import { analyzeVariants } from '../lib/significance'
+import { dynamodb, TABLE_NAME, unmarshall, marshall } from '../lib/dynamodb'
+import { jsonResponse, errorResponse } from '../utils/response'
+import { getQueryParams } from '../../deploy/lambda-adapter'
+
+/**
+ * POST /api/sites/{siteId}/experiments
+ */
+export async function handleCreateExperiment(request: Request, siteId: string): Promise<Response> {
+  try {
+    const body = await request.json() as Record<string, any>
+
+    if (!body.name || !body.variants || !Array.isArray(body.variants) || body.variants.length < 2) {
+      return jsonResponse({ error: 'Missing required fields: name, variants (min 2)' }, 400)
+    }
+
+    const experimentId = generateId()
+    const experiment = {
+      pk: `SITE#${siteId}`,
+      sk: `EXPERIMENT#${experimentId}`,
+      id: experimentId,
+      siteId,
+      name: body.name,
+      description: body.description || '',
+      variants: body.variants.map((v: any, i: number) => ({
+        id: v.id || generateId(),
+        name: v.name || `Variant ${i + 1}`,
+        weight: v.weight || Math.floor(100 / body.variants.length),
+        conversions: 0,
+        visitors: 0,
+      })),
+      goalId: body.goalId,
+      status: 'active',
+      createdAt: new Date().toISOString(),
+    }
+
+    await dynamodb.putItem({
+      TableName: TABLE_NAME,
+      Item: marshall(experiment),
+    })
+
+    return jsonResponse({ experiment }, 201)
+  }
+catch (error) {
+    console.error('Create experiment error:', error)
+    return errorResponse('Failed to create experiment')
+  }
+}
+
+/**
+ * GET /api/sites/{siteId}/experiments
+ */
+export async function handleGetExperiments(_request: Request, siteId: string): Promise<Response> {
+  try {
+    const result = await dynamodb.query({
+      TableName: TABLE_NAME,
+      KeyConditionExpression: 'pk = :pk AND begins_with(sk, :prefix)',
+      ExpressionAttributeValues: {
+        ':pk': { S: `SITE#${siteId}` },
+        ':prefix': { S: 'EXPERIMENT#' },
+      },
+    }) as { Items?: any[] }
+
+    const experiments = (result.Items || []).map(unmarshall).map((exp: any) => {
+      const stats = analyzeVariants(exp.variants || [])
+      return { ...exp, variants: (exp.variants || []).map((v: any, i: number) => ({ ...v, ...stats[i] })) }
+    })
+
+    return jsonResponse({ experiments })
+  }
+catch (error) {
+    console.error('Get experiments error:', error)
+    return errorResponse('Failed to fetch experiments')
+  }
+}
+
+/**
+ * POST /api/sites/{siteId}/experiments/event
+ */
+export async function handleRecordExperimentEvent(request: Request, siteId: string): Promise<Response> {
+  try {
+    const body = await request.json() as Record<string, any>
+
+    if (!body.experimentId || !body.variantId || !body.eventType) {
+      return jsonResponse({ error: 'Missing required fields: experimentId, variantId, eventType' }, 400)
+    }
+
+    // Get experiment
+    const result = await dynamodb.query({
+      TableName: TABLE_NAME,
+      KeyConditionExpression: 'pk = :pk AND sk = :sk',
+      ExpressionAttributeValues: {
+        ':pk': { S: `SITE#${siteId}` },
+        ':sk': { S: `EXPERIMENT#${body.experimentId}` },
+      },
+    }) as { Items?: any[] }
+
+    if (!result.Items || result.Items.length === 0) {
+      return jsonResponse({ error: 'Experiment not found' }, 404)
+    }
+
+    const experiment = unmarshall(result.Items[0])
+    const variant = experiment.variants.find((v: any) => v.id === body.variantId)
+
+    if (!variant) {
+      return jsonResponse({ error: 'Variant not found' }, 404)
+    }
+
+    // Update variant stats
+    if (body.eventType === 'view') {
+      variant.visitors = (variant.visitors || 0) + 1
+    }
+else if (body.eventType === 'conversion') {
+      variant.conversions = (variant.conversions || 0) + 1
+    }
+
+    // Save updated experiment
+    await dynamodb.putItem({
+      TableName: TABLE_NAME,
+      Item: marshall({
+        ...experiment,
+        variants: experiment.variants,
+        updatedAt: new Date().toISOString(),
+      }),
+    })
+
+    return jsonResponse({ success: true })
+  }
+catch (error) {
+    console.error('Record experiment event error:', error)
+    return errorResponse('Failed to record experiment event')
+  }
+}

package/src/handlers/funnels.ts

@@ -0,0 +1,216 @@
+/**
+ * Funnel handlers
+ */
+
+import { generateId } from '../index'
+import { querySessionItemsInRange, queryAllItems, dynamodb, TABLE_NAME, unmarshall, marshall } from '../lib/dynamodb'
+import { parseDateRange } from '../utils/date'
+import { jsonResponse, errorResponse } from '../utils/response'
+import { getQueryParams } from '../../deploy/lambda-adapter'
+
+/**
+ * POST /api/sites/{siteId}/funnels
+ */
+export async function handleCreateFunnel(request: Request, siteId: string): Promise<Response> {
+  try {
+    const body = await request.json() as Record<string, any>
+
+    if (!body.name || !body.steps || !Array.isArray(body.steps) || body.steps.length < 2) {
+      return jsonResponse({ error: 'Missing required fields: name, steps (min 2 steps)' }, 400)
+    }
+
+    const funnelId = generateId()
+    const funnel = {
+      pk: `SITE#${siteId}`,
+      sk: `FUNNEL#${funnelId}`,
+      id: funnelId,
+      siteId,
+      name: body.name,
+      steps: body.steps,
+      createdAt: new Date().toISOString(),
+    }
+
+    await dynamodb.putItem({
+      TableName: TABLE_NAME,
+      Item: marshall(funnel),
+    })
+
+    return jsonResponse({ funnel }, 201)
+  }
+catch (error) {
+    console.error('Create funnel error:', error)
+    return errorResponse('Failed to create funnel')
+  }
+}
+
+/**
+ * GET /api/sites/{siteId}/funnels
+ */
+export async function handleGetFunnels(_request: Request, siteId: string): Promise<Response> {
+  try {
+    const result = await queryAllItems({
+      TableName: TABLE_NAME,
+      KeyConditionExpression: 'pk = :pk AND begins_with(sk, :prefix)',
+      ExpressionAttributeValues: {
+        ':pk': { S: `SITE#${siteId}` },
+        ':prefix': { S: 'FUNNEL#' },
+      },
+    }) as { Items?: any[] }
+
+    const funnels = (result.Items || []).map(unmarshall)
+
+    return jsonResponse({ funnels })
+  }
+catch (error) {
+    console.error('Get funnels error:', error)
+    return errorResponse('Failed to fetch funnels')
+  }
+}
+
+/**
+ * GET /api/sites/{siteId}/funnels/{funnelId}
+ */
+export async function handleGetFunnelAnalysis(request: Request, siteId: string, funnelId: string): Promise<Response> {
+  try {
+    const query = getQueryParams(request)
+    const { startDate, endDate } = parseDateRange(query)
+
+    // Get funnel definition
+    const funnelResult = await dynamodb.query({
+      TableName: TABLE_NAME,
+      KeyConditionExpression: 'pk = :pk AND sk = :sk',
+      ExpressionAttributeValues: {
+        ':pk': { S: `SITE#${siteId}` },
+        ':sk': { S: `FUNNEL#${funnelId}` },
+      },
+    }) as { Items?: any[] }
+
+    if (!funnelResult.Items || funnelResult.Items.length === 0) {
+      return jsonResponse({ error: 'Funnel not found' }, 404)
+    }
+
+    const funnel = unmarshall(funnelResult.Items[0])
+
+    // Get sessions for analysis
+    const sessionsResult = await querySessionItemsInRange(siteId, startDate, endDate) as { Items?: any[] }
+
+    const sessions = (sessionsResult.Items || []).map(unmarshall).filter(s => {
+      const sessionStart = new Date(s.startedAt)
+      return sessionStart >= startDate && sessionStart <= endDate
+    })
+
+    // Analyze funnel steps
+    const steps = funnel.steps as Array<{ name: string; pattern: string; type: 'pageview' | 'event' }>
+    const stepResults = steps.map((step, index) => ({
+      name: step.name,
+      pattern: step.pattern,
+      type: step.type,
+      visitors: 0,
+      sessions: 0,
+      conversionRate: 0,
+      dropoffRate: 0,
+      stepIndex: index,
+    }))
+
+    // Track visitors through funnel steps
+    for (const session of sessions) {
+      const pageSequence = session.pageSequence || []
+      const events = session.events || []
+
+      let completedSteps = 0
+      for (let i = 0; i < steps.length; i++) {
+        const step = steps[i]
+        let matched = false
+
+        if (step.type === 'pageview') {
+          matched = pageSequence.some((page: string) => {
+            if (step.pattern.includes('*')) {
+              const regex = new RegExp(`^${step.pattern.replace(/\*/g, '.*')}$`)
+              return regex.test(page)
+            }
+            return page === step.pattern
+          })
+        }
+else {
+          matched = events.some((event: any) => event.name === step.pattern)
+        }
+
+        if (matched) {
+          completedSteps = i + 1
+          stepResults[i].sessions++
+        }
+else {
+          break
+        }
+      }
+    }
+
+    // Calculate unique visitors and rates
+    const totalSessions = sessions.length
+    for (let i = 0; i < stepResults.length; i++) {
+      const step = stepResults[i]
+      const prevStep = i > 0 ? stepResults[i - 1] : null
+
+      step.visitors = step.sessions // Simplified: using sessions as visitors
+      step.conversionRate = totalSessions > 0
+        ? Math.round((step.sessions / totalSessions) * 100)
+        : 0
+
+      if (prevStep) {
+        step.dropoffRate = prevStep.sessions > 0
+          ? Math.round(((prevStep.sessions - step.sessions) / prevStep.sessions) * 100)
+          : 0
+      }
+    }
+
+    // Calculate overall conversion rate
+    const firstStep = stepResults[0]?.sessions || 0
+    const lastStep = stepResults[stepResults.length - 1]?.sessions || 0
+    const overallConversionRate = firstStep > 0
+      ? Math.round((lastStep / firstStep) * 100)
+      : 0
+
+    return jsonResponse({
+      funnel: {
+        id: funnel.id,
+        name: funnel.name,
+      },
+      steps: stepResults,
+      summary: {
+        totalSessions,
+        enteredFunnel: firstStep,
+        completedFunnel: lastStep,
+        overallConversionRate,
+      },
+      dateRange: {
+        start: startDate.toISOString(),
+        end: endDate.toISOString(),
+      },
+    })
+  }
+catch (error) {
+    console.error('Get funnel analysis error:', error)
+    return errorResponse('Failed to fetch funnel analysis')
+  }
+}
+
+/**
+ * DELETE /api/sites/{siteId}/funnels/{funnelId}
+ */
+export async function handleDeleteFunnel(_request: Request, siteId: string, funnelId: string): Promise<Response> {
+  try {
+    await dynamodb.deleteItem({
+      TableName: TABLE_NAME,
+      Key: marshall({
+        pk: `SITE#${siteId}`,
+        sk: `FUNNEL#${funnelId}`,
+      }),
+    })
+
+    return jsonResponse({ success: true })
+  }
+catch (error) {
+    console.error('Delete funnel error:', error)
+    return errorResponse('Failed to delete funnel')
+  }
+}

package/src/handlers/goals.ts

@@ -0,0 +1,218 @@
+/**
+ * Goal CRUD handlers
+ */
+
+import { generateId } from '../index'
+import { Goal, Conversion } from '../../src/models/orm'
+import { querySessionItemsInRange, queryAllItems, dynamodb, TABLE_NAME, unmarshall } from '../lib/dynamodb'
+import { invalidateGoalCache } from '../utils/cache'
+import { parseDateRange } from '../utils/date'
+import { jsonResponse, errorResponse } from '../utils/response'
+import { getQueryParams } from '../../deploy/lambda-adapter'
+
+/**
+ * POST /api/sites/{siteId}/goals
+ */
+export async function handleCreateGoal(request: Request, siteId: string): Promise<Response> {
+  try {
+    const body = await request.json() as Record<string, any>
+
+    if (!body.name || !body.type) {
+      return jsonResponse({ error: 'Missing required fields: name, type' }, 400)
+    }
+
+    if (!['pageview', 'event', 'duration'].includes(body.type)) {
+      return jsonResponse({ error: 'Invalid type. Must be: pageview, event, or duration' }, 400)
+    }
+
+    if ((body.type === 'pageview' || body.type === 'event') && !body.pattern) {
+      return jsonResponse({ error: 'Pattern is required for pageview and event goals' }, 400)
+    }
+
+    if (body.type === 'duration' && (!body.durationMinutes || body.durationMinutes < 1)) {
+      return jsonResponse({ error: 'durationMinutes is required for duration goals (min: 1)' }, 400)
+    }
+
+    const goal = await Goal.create({
+      id: generateId(),
+      siteId,
+      name: body.name,
+      type: body.type,
+      pattern: body.pattern || '',
+      matchType: body.matchType || 'exact',
+      durationMinutes: body.durationMinutes,
+      value: body.value,
+      isActive: body.isActive ?? true,
+    })
+
+    invalidateGoalCache(siteId)
+    return jsonResponse({ goal }, 201)
+  }
+catch (error) {
+    console.error('Create goal error:', error)
+    return errorResponse('Failed to create goal')
+  }
+}
+
+/**
+ * GET /api/sites/{siteId}/goals
+ */
+export async function handleGetGoals(request: Request, siteId: string): Promise<Response> {
+  try {
+    const query = getQueryParams(request)
+    const includeInactive = query.includeInactive === 'true'
+    const { startDate, endDate } = parseDateRange(query)
+
+    const queryBuilder = Goal.forSite(siteId)
+    if (!includeInactive) {
+      queryBuilder.active()
+    }
+    const goals = await queryBuilder.get()
+
+    const goalsWithStats = await Promise.all(goals.map(async (goal) => {
+      let conversions: Conversion[] = []
+      try {
+        conversions = await Conversion.forGoal(siteId, goal.id)
+          .since(startDate)
+          .until(endDate)
+          .get()
+      }
+catch (e) {
+        console.log('[GetGoals] Conversion query failed:', e)
+      }
+
+      const uniqueVisitors = new Set(conversions.map(c => c.visitorId)).size
+      const totalValue = conversions.reduce((sum, c) => sum + (c.value || 0), 0)
+
+      return {
+        id: goal.id,
+        name: goal.name,
+        type: goal.type,
+        pattern: goal.pattern,
+        matchType: goal.matchType,
+        durationMinutes: goal.durationMinutes,
+        value: goal.value,
+        isActive: goal.isActive,
+        conversions: conversions.length,
+        uniqueConversions: uniqueVisitors,
+        totalValue,
+        createdAt: goal.createdAt,
+      }
+    }))
+
+    return jsonResponse({ goals: goalsWithStats })
+  }
+catch (error) {
+    console.error('Get goals error:', error)
+    return errorResponse('Failed to fetch goals')
+  }
+}
+
+/**
+ * PUT /api/sites/{siteId}/goals/{goalId}
+ */
+export async function handleUpdateGoal(request: Request, siteId: string, goalId: string): Promise<Response> {
+  try {
+    const body = await request.json() as Record<string, any>
+
+    if (body.type && !['pageview', 'event', 'duration'].includes(body.type)) {
+      return jsonResponse({ error: 'Invalid type. Must be: pageview, event, or duration' }, 400)
+    }
+
+    const goal = await Goal.update(siteId, goalId, {
+      name: body.name,
+      type: body.type,
+      pattern: body.pattern,
+      matchType: body.matchType,
+      durationMinutes: body.durationMinutes,
+      value: body.value,
+      isActive: body.isActive,
+    })
+
+    invalidateGoalCache(siteId)
+    return jsonResponse({ goal })
+  }
+catch (error) {
+    console.error('Update goal error:', error)
+    return errorResponse('Failed to update goal')
+  }
+}
+
+/**
+ * DELETE /api/sites/{siteId}/goals/{goalId}
+ */
+export async function handleDeleteGoal(_request: Request, siteId: string, goalId: string): Promise<Response> {
+  try {
+    await Goal.delete(siteId, goalId)
+    invalidateGoalCache(siteId)
+    return jsonResponse({ success: true })
+  }
+catch (error) {
+    console.error('Delete goal error:', error)
+    return errorResponse('Failed to delete goal')
+  }
+}
+
+/**
+ * GET /api/sites/{siteId}/goals/stats
+ */
+export async function handleGetGoalStats(request: Request, siteId: string): Promise<Response> {
+  try {
+    const query = getQueryParams(request)
+    const { startDate, endDate } = parseDateRange(query)
+
+    const goals = await Goal.forSite(siteId).get()
+
+    // Denominator: sessions IN THE REQUESTED RANGE (paginated). The old
+    // single-page COUNT was both truncated at 1MB and all-time, while the
+    // numerator (conversions) was date-bounded — conversion rates were
+    // meaningless on any site with history (#151 residual).
+    const sessionsResult = await querySessionItemsInRange(siteId, startDate, endDate) as { Items?: any[] }
+    const totalSessions = (sessionsResult.Items || []).map(unmarshall).filter((sess) => {
+      const t = new Date(sess.startedAt)
+      return t >= startDate && t <= endDate
+    }).length
+
+    const goalStats = await Promise.all(goals.map(async (goal) => {
+      const conversions = await Conversion.forGoal(siteId, goal.id)
+        .since(startDate)
+        .until(endDate)
+        .get()
+
+      const uniqueVisitors = new Set(conversions.map(c => c.visitorId)).size
+      const totalValue = conversions.reduce((sum, c) => sum + (c.value || 0), 0)
+
+      return {
+        goalId: goal.id,
+        goalName: goal.name,
+        goalType: goal.type,
+        conversions: conversions.length,
+        uniqueConversions: uniqueVisitors,
+        conversionRate: totalSessions > 0
+          ? Math.round((uniqueVisitors / totalSessions) * 10000) / 100
+          : 0,
+        totalValue,
+        isActive: goal.isActive,
+      }
+    }))
+
+    const totalConversions = goalStats.reduce((sum, g) => sum + g.conversions, 0)
+    const totalValue = goalStats.reduce((sum, g) => sum + g.totalValue, 0)
+
+    return jsonResponse({
+      goals: goalStats,
+      summary: {
+        totalGoals: goals.length,
+        activeGoals: goals.filter(g => g.isActive).length,
+        totalConversions,
+        totalValue,
+        totalSessions,
+      },
+      dateRange: { start: startDate.toISOString(), end: endDate.toISOString() },
+    })
+  }
+catch (error) {
+    console.error('Get goal stats error:', error)
+    return errorResponse('Failed to fetch goal stats')
+  }
+}