spine-framework 0.1.61 → 0.2.0

package/.framework/functions/admin-funnel.ts

@@ -0,0 +1,104 @@
+/**
+ * @module admin-funnel
+ * @audience system-admin
+ * @layer api-handler
+ * @stability stable
+ *
+ * Admin API for funnel metrics and analytics
+ */
+
+import { createHandler } from './_shared/middleware'
+import { adminDb } from './_shared/db'
+
+// ============================================
+// FUNNEL METRICS
+// ============================================
+
+export const metrics = createHandler(async (ctx, body) => {
+  // Get type IDs
+  const { data: signalType } = await adminDb
+    .from('item_type_registry')
+    .select('id')
+    .eq('slug', 'funnel_signal')
+    .single()
+  
+  const { data: sessionType } = await adminDb
+    .from('item_type_registry')
+    .select('id')
+    .eq('slug', 'anonymous_session')
+    .single()
+  
+  const { data: instanceType } = await adminDb
+    .from('item_type_registry')
+    .select('id')
+    .eq('slug', 'spine_instance')
+    .single()
+
+  if (!signalType || !sessionType || !instanceType) {
+    throw new Error('Required types not found')
+  }
+
+  // Count by stage
+  const { data: stageData } = await adminDb
+    .from('items')
+    .select('data->>stage, account_id')
+    .eq('type_id', signalType.id)
+    .gte('created_at', new Date(Date.now() - 30 * 24 * 60 * 60 * 1000).toISOString())
+
+  const stageCounts = stageData?.reduce((acc, item) => {
+    const stage = item.data?.stage || 'unknown'
+    if (item.account_id) {
+      acc[stage] = (acc[stage] || 0) + 1
+    }
+    return acc
+  }, {} as Record<string, number>)
+
+  const totalStageSignals = Object.values(stageCounts).reduce((sum, count) => sum + count, 0)
+
+  // Anonymous visitors (sessions without account)
+  const { count: anonymousSessions } = await adminDb
+    .from('items')
+    .select('*', { count: 'exact', head: true })
+    .eq('type_id', sessionType.id)
+    .is('data->lifecycle->>stitched_to_account_id', null)
+    .gte('created_at', new Date(Date.now() - 30 * 24 * 60 * 60 * 1000).toISOString())
+
+  // Identified users (unique accounts with signals)
+  const { data: accountData } = await adminDb
+    .from('items')
+    .select('account_id')
+    .eq('type_id', signalType.id)
+    .gte('created_at', new Date(Date.now() - 30 * 24 * 60 * 60 * 1000).toISOString())
+    .not('account_id', 'is', null)
+
+  const uniqueAccounts = new Set(accountData?.map(item => item.account_id)).size
+
+  // Installed instances
+  const { count: installedInstances } = await adminDb
+    .from('items')
+    .select('*', { count: 'exact', head: true })
+    .eq('type_id', instanceType.id)
+    .not('data->>claimed_by_person_id', 'is', null)
+
+  // Stage distribution with percentages
+  const stageDistribution = Object.entries(stageCounts).map(([stage, count]) => ({
+    stage,
+    count,
+    percentage: totalStageSignals > 0 ? (count / totalStageSignals) * 100 : 0
+  }))
+
+  // Conversion rates (simplified)
+  const anonymousToIdentified = anonymousSessions > 0 ? (uniqueAccounts / anonymousSessions) * 100 : 0
+  const identifiedToInstalled = uniqueAccounts > 0 ? (installedInstances / uniqueAccounts) * 100 : 0
+
+  return {
+    anonymous_visitors: anonymousSessions || 0,
+    identified_users: uniqueAccounts,
+    installed_instances: installedInstances || 0,
+    conversion_rates: {
+      anonymous_to_identified: anonymousToIdentified,
+      identified_to_installed: identifiedToInstalled
+    },
+    stage_distribution: stageDistribution
+  }
+})

package/.framework/functions/admin-install-funnel.ts

@@ -0,0 +1,225 @@
+/**
+ * @module admin-install-funnel
+ * @audience system-admin
+ * @layer api-handler
+ * @stability stable
+ *
+ * Admin API for install funnel metrics and analytics
+ */
+
+import { createHandler } from './_shared/middleware'
+import { adminDb } from './_shared/db'
+
+// ============================================
+// INSTALL FUNNEL METRICS
+// ============================================
+
+export const metrics = createHandler(async (ctx, body) => {
+  // Get type IDs
+  const { data: signalType } = await adminDb
+    .from('item_type_registry')
+    .select('id')
+    .eq('slug', 'funnel_signal')
+    .single()
+  
+  if (!signalType) {
+    throw new Error('funnel_signal type not found')
+  }
+
+  // Total downloads (signals with source='inst' and action_type='download')
+  const { count: totalDownloads } = await adminDb
+    .from('items')
+    .select('*', { count: 'exact', head: true })
+    .eq('type_id', signalType.id)
+    .eq('data->>source', 'inst')
+    .eq('data->>action_type', 'download')
+
+  // Unique installers (unique serial numbers from install signals)
+  const { data: installerData } = await adminDb
+    .from('items')
+    .select('data->>serial')
+    .eq('type_id', signalType.id)
+    .eq('data->>source', 'inst')
+    .not('data->>serial', 'is', null)
+
+  const uniqueInstallers = new Set(installerData?.map(item => item.data?.serial)).size
+
+  // Active instances (install signals with serial in last 7 days)
+  const sevenDaysAgo = new Date(Date.now() - 7 * 24 * 60 * 60 * 1000).toISOString()
+  const { count: activeInstances } = await adminDb
+    .from('items')
+    .select('*', { count: 'exact', head: true })
+    .eq('type_id', signalType.id)
+    .eq('data->>source', 'inst')
+    .not('data->>serial', 'is', null)
+    .gte('created_at', sevenDaysAgo)
+
+  // Conversion funnel counts
+  const { count: installations } = await adminDb
+    .from('items')
+    .select('*', { count: 'exact', head: true })
+    .eq('type_id', signalType.id)
+    .eq('data->>source', 'inst')
+    .eq('data->>action_type', 'install')
+
+  const { count: firstUse } = await adminDb
+    .from('items')
+    .select('*', { count: 'exact', head: true })
+    .eq('type_id', signalType.id)
+    .eq('data->>source', 'inst')
+    .eq('data->>action_type', 'first_command')
+
+  const { count: claimed } = await adminDb
+    .from('items')
+    .select('*', { count: 'exact', head: true })
+    .eq('type_id', signalType.id)
+    .eq('data->>source', 'inst')
+    .not('data->>claimed_by_person_id', 'is', null)
+
+  // Recent installs with account info
+  const { data: recentInstalls } = await adminDb
+    .from('items')
+    .select(`
+      id,
+      data->>serial,
+      data->>version,
+      data->>environment,
+      data->>first_seen_at,
+      data->>last_signal_at,
+      data->>claimed_by_person_id,
+      data->>claimed_at,
+      account_id,
+      people(email),
+      accounts(name)
+    `)
+    .eq('type_id', signalType.id)
+    .eq('data->>source', 'inst')
+    .not('data->>serial', 'is', null)
+    .order('created_at', { ascending: false })
+    .limit(20)
+
+  const formattedInstalls = recentInstalls?.map(instance => ({
+    id: instance.id,
+    serial: instance.data?.serial || 'unknown',
+    app_version: instance.data?.version || 'unknown',
+    environment: instance.data?.environment || 'unknown',
+    first_seen_at: instance.data?.first_seen_at || instance.created_at,
+    last_signal_at: instance.data?.last_signal_at || instance.created_at,
+    claimed_by: instance.data?.claimed_by_person_id,
+    claimed_at: instance.data?.claimed_at,
+    account_name: instance.accounts?.name,
+    person_email: instance.people?.email
+  }))
+
+  // Version distribution
+  const { data: versionData } = await adminDb
+    .from('items')
+    .select('data->>version')
+    .eq('type_id', instanceType.id)
+
+  const versionCounts = versionData?.reduce((acc, item) => {
+    const version = item.data?.version || 'unknown'
+    acc[version] = (acc[version] || 0) + 1
+    return acc
+  }, {} as Record<string, number>)
+
+  const totalVersions = Object.values(versionCounts).reduce((sum, count) => sum + count, 0)
+  const topVersions = Object.entries(versionCounts)
+    .sort(([, a], [, b]) => b - a)
+    .slice(0, 10)
+    .map(([version, count]) => ({
+      version,
+      count,
+      percentage: totalVersions > 0 ? (count / totalVersions) * 100 : 0
+    }))
+
+  // Install trends (last 30 days)
+  const thirtyDaysAgo = new Date(Date.now() - 30 * 24 * 60 * 60 * 1000)
+  const installTrends = []
+  
+  for (let i = 29; i >= 0; i--) {
+    const date = new Date(thirtyDaysAgo)
+    date.setDate(date.getDate() + i)
+    const dateStr = date.toISOString().split('T')[0]
+    const nextDateStr = new Date(date.getTime() + 24 * 60 * 60 * 1000).toISOString().split('T')[0]
+    
+    const { count: dailyDownloads } = await adminDb
+      .from('items')
+      .select('*', { count: 'exact', head: true })
+      .eq('type_id', signalType.id)
+      .eq('data->>source', 'inst')
+      .eq('data->>action_type', 'download')
+      .gte('created_at', dateStr)
+      .lt('created_at', nextDateStr)
+
+    const { count: dailyInstalls } = await adminDb
+      .from('items')
+      .select('*', { count: 'exact', head: true })
+      .eq('type_id', signalType.id)
+      .eq('data->>source', 'inst')
+      .eq('data->>action_type', 'install')
+      .gte('created_at', dateStr)
+      .lt('created_at', nextDateStr)
+
+    installTrends.push({
+      date: dateStr,
+      downloads: dailyDownloads || 0,
+      installations: dailyInstalls || 0
+    })
+  }
+
+  return {
+    total_downloads: totalDownloads || 0,
+    unique_installers: uniqueInstallers,
+    active_instances: activeInstances || 0,
+    conversion_funnel: {
+      downloads: totalDownloads || 0,
+      installations: installations || 0,
+      first_use: firstUse || 0,
+      claimed: claimed || 0
+    },
+    install_trends: installTrends,
+    recent_installs: formattedInstalls || [],
+    top_versions: topVersions
+  }
+})
+
+// ============================================
+// INSTALL FUNNEL EXPORT
+// ============================================
+
+export const exportData = createHandler(async (ctx, body) => {
+  // Get type IDs
+  const { data: signalType } = await adminDb
+    .from('item_type_registry')
+    .select('id')
+    .eq('slug', 'funnel_signal')
+    .single()
+
+  if (!signalType) {
+    throw new Error('funnel_signal type not found')
+  }
+
+  // Export all instances with full details
+  const { data: instances } = await adminDb
+    .from('items')
+    .select(`
+      id,
+      created_at,
+      updated_at,
+      data,
+      account_id,
+      people(email),
+      accounts(name)
+    `)
+    .eq('type_id', signalType.id)
+    .eq('data->>source', 'inst')
+    .not('data->>serial', 'is', null)
+    .order('created_at', { ascending: false })
+
+  return {
+    instances: instances || [],
+    exported_at: new Date().toISOString(),
+    total_count: instances?.length || 0
+  }
+})

package/.framework/functions/admin-signals.ts

@@ -0,0 +1,241 @@
+/**
+ * @module admin-signals
+ * @audience system-admin
+ * @layer api-handler
+ * @stability stable
+ *
+ * Admin API for signal analytics and audit functionality
+ */
+
+import { createHandler } from './_shared/middleware'
+import { adminDb } from './_shared/db'
+
+// ============================================
+// SIGNAL METRICS
+// ============================================
+
+export const metrics = createHandler(async (ctx, body) => {
+  const now = new Date()
+  const today = now.toISOString().split('T')[0]
+  const weekAgo = new Date(now.getTime() - 7 * 24 * 60 * 60 * 1000).toISOString()
+  
+  // Get funnel_signal type ID
+  const { data: signalType } = await adminDb
+    .from('item_type_registry')
+    .select('id')
+    .eq('slug', 'funnel_signal')
+    .single()
+  
+  if (!signalType) {
+    throw new Error('funnel_signal type not found')
+  }
+
+  // Total signals
+  const { count: totalSignals } = await adminDb
+    .from('items')
+    .select('*', { count: 'exact', head: true })
+    .eq('type_id', signalType.id)
+
+  // Signals today
+  const { count: signalsToday } = await adminDb
+    .from('items')
+    .select('*', { count: 'exact', head: true })
+    .eq('type_id', signalType.id)
+    .gte('created_at', today)
+
+  // Signals this week
+  const { count: signalsThisWeek } = await adminDb
+    .from('items')
+    .select('*', { count: 'exact', head: true })
+    .eq('type_id', signalType.id)
+    .gte('created_at', weekAgo)
+
+  // Top sources
+  const { data: sourceData } = await adminDb
+    .from('items')
+    .select('data->>source')
+    .eq('type_id', signalType.id)
+    .gte('created_at', weekAgo)
+
+  const sourceCounts = sourceData?.reduce((acc, item) => {
+    const source = item.data?.source || 'unknown'
+    acc[source] = (acc[source] || 0) + 1
+    return acc
+  }, {} as Record<string, number>)
+
+  const topSources = Object.entries(sourceCounts)
+    .sort(([, a], [, b]) => b - a)
+    .slice(0, 10)
+    .map(([source, count]) => ({ source, count }))
+
+  // Recent signals with account info
+  const { data: recentSignals } = await adminDb
+    .from('items')
+    .select(`
+      id,
+      data->>action_type,
+      data->>source,
+      data->>stage,
+      created_at,
+      data->>rating,
+      account_id,
+      accounts(name)
+    `)
+    .eq('type_id', signalType.id)
+    .order('created_at', { ascending: false })
+    .limit(20)
+
+  const formattedSignals = recentSignals?.map(signal => ({
+    id: signal.id,
+    action_type: signal.data?.action_type || 'unknown',
+    source: signal.data?.source || 'unknown',
+    stage: signal.data?.stage || 'unknown',
+    created_at: signal.created_at,
+    account_name: signal.accounts?.name,
+    rating: parseInt(signal.data?.rating || '1')
+  }))
+
+  // Calculate conversion rate (simplified - signals with rating >= 4)
+  const { count: highValueSignals } = await adminDb
+    .from('items')
+    .select('*', { count: 'exact', head: true })
+    .eq('type_id', signalType.id)
+    .gte('data->>rating', '4')
+    .gte('created_at', weekAgo)
+
+  const conversionRate = signalsThisWeek > 0 ? (highValueSignals / signalsThisWeek) * 100 : 0
+
+  return {
+    total_signals: totalSignals || 0,
+    signals_today: signalsToday || 0,
+    signals_this_week: signalsThisWeek || 0,
+    conversion_rate: conversionRate,
+    top_sources: topSources,
+    recent_signals: formattedSignals || []
+  }
+})
+
+// ============================================
+// SIGNAL AUDIT
+// ============================================
+
+export const audit = createHandler(async (ctx, body) => {
+  const {
+    page = '1',
+    limit = '50',
+    date_from,
+    date_to,
+    source,
+    stage,
+    action_type,
+    min_rating,
+    account_id,
+    search,
+    export: exportData
+  } = ctx.query || {}
+
+  // Get funnel_signal type ID
+  const { data: signalType } = await adminDb
+    .from('item_type_registry')
+    .select('id')
+    .eq('slug', 'funnel_signal')
+    .single()
+  
+  if (!signalType) {
+    throw new Error('funnel_signal type not found')
+  }
+
+  // Build query
+  let query = adminDb
+    .from('items')
+    .select(`
+      id,
+      data->>action_type,
+      data->>action_value,
+      data->>stage,
+      data->>source,
+      created_at,
+      data->>rating,
+      data->>raw_score,
+      data->identity->>anonymous_id,
+      data->identity->>session_id,
+      data->attribution->>first_touch_referrer_domain,
+      data->attribution->>utm_source,
+      data->attribution->>utm_medium,
+      data->attribution->>utm_campaign,
+      account_id,
+      people(email),
+      accounts(name)
+    `, { count: 'exact' })
+    .eq('type_id', signalType.id)
+
+  // Apply filters
+  if (date_from) {
+    query = query.gte('created_at', date_from)
+  }
+  if (date_to) {
+    query = query.lte('created_at', date_to)
+  }
+  if (source) {
+    query = query.eq('data->>source', source)
+  }
+  if (stage) {
+    query = query.eq('data->>stage', stage)
+  }
+  if (action_type) {
+    query = query.eq('data->>action_type', action_type)
+  }
+  if (min_rating) {
+    query = query.gte('data->>rating', min_rating)
+  }
+  if (account_id) {
+    query = query.eq('account_id', account_id)
+  }
+  if (search) {
+    query = query.or(`accounts.name.ilike.%${search}%,people.email.ilike.%${search}%,data->attribution->>first_touch_referrer_domain.ilike.%${search}%`)
+  }
+
+  // Order and paginate
+  const offset = (parseInt(page) - 1) * parseInt(limit)
+  query = query.order('created_at', { ascending: false })
+
+  if (!exportData) {
+    query = query.range(offset, offset + parseInt(limit) - 1)
+  }
+
+  const { data, error, count } = await query
+
+  if (error) {
+    throw new Error(`Failed to fetch signals: ${error.message}`)
+  }
+
+  const formattedSignals = data?.map(signal => ({
+    id: signal.id,
+    action_type: signal.data?.action_type || 'unknown',
+    action_value: parseInt(signal.data?.action_value || '1'),
+    stage: signal.data?.stage || 'unknown',
+    source: signal.data?.source || 'unknown',
+    created_at: signal.created_at,
+    account_name: signal.accounts?.name,
+    person_email: signal.people?.email,
+    anonymous_id: signal.data?.identity?.anonymous_id,
+    session_id: signal.data?.identity?.session_id,
+    rating: parseInt(signal.data?.rating || '1'),
+    raw_score: parseFloat(signal.data?.raw_score || '0'),
+    referrer_domain: signal.data?.attribution?.first_touch_referrer_domain,
+    utm_source: signal.data?.attribution?.utm_source,
+    utm_medium: signal.data?.attribution?.utm_medium,
+    utm_campaign: signal.data?.attribution?.utm_campaign
+  }))
+
+  if (exportData) {
+    return formattedSignals
+  }
+
+  return {
+    signals: formattedSignals,
+    total: count || 0,
+    page: parseInt(page),
+    limit: parseInt(limit)
+  }
+})