spine-framework 0.3.17 → 0.3.19

package/.framework/functions/_shared/principal.ts

@@ -32,11 +32,6 @@
 
 import { getUserDb, adminDb } from './db'
 import { createClient } from '@supabase/supabase-js'
-import WebSocket from 'ws'
-
-// WebSocket constructor for Supabase Realtime in Node.js environment
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-const RealtimeWebSocket = WebSocket as any
 
 // ─── AUTH CLIENT ─────────────────────────────────────────────────────────────
 
@@ -51,8 +46,7 @@ const supabase = createClient(
     auth: {
       autoRefreshToken: false,
       persistSession: false
-    },
-    realtime: { transport: RealtimeWebSocket }  // WebSocket for Node.js 20+
+    }
   }
 )
 
@@ -501,7 +495,7 @@ async function resolveHumanPrincipal(token: string, event: any): Promise<Princip
     type: 'human',
     accountId: person.account_id || null,
     roles: roleSlugs,
-    displayName: person.full_name || person.email,
+    displayName: person.display_name || person.email,
     email: person.email,
     provenance: {
       sourceType: 'jwt',
@@ -567,60 +561,8 @@ async function resolveInternalPersonId(authUserId: string, email?: string): Prom
   
   if (byAuthId) return byAuthId.id
   
-  // Not found — auto-create the person (handles cases where auth user pre-existed DB reset
-  // or trigger fired before seed data was in place)
-  const { data: account } = await adminDb
-    .from('accounts')
-    .select('id')
-    .eq('slug', 'spine-system')
-    .single()
-
-  const { data: type } = await adminDb
-    .from('types')
-    .select('id')
-    .eq('kind', 'person')
-    .eq('slug', 'person')
-    .single()
-
-  if (!account || !type) {
-    throw new Error('Cannot auto-create person: spine-system account or person type not found in DB')
-  }
-
-  // First person ever gets system_admin role
-  const { count } = await adminDb
-    .from('people')
-    .select('id', { count: 'exact', head: true })
-
-  let roleId: string | null = null
-  if ((count ?? 0) === 0) {
-    const { data: adminRole } = await adminDb
-      .from('roles')
-      .select('id')
-      .eq('slug', 'system_admin')
-      .single()
-    roleId = adminRole?.id ?? null
-  }
-
-  const { data: newPerson, error: createError } = await adminDb
-    .from('people')
-    .upsert({
-      id: authUserId,
-      auth_uid: authUserId,
-      email: email ?? '',
-      full_name: email ? email.split('@')[0] : 'Unknown',
-      account_id: account.id,
-      type_id: type.id,
-      role_id: roleId,
-      is_active: true
-    }, { onConflict: 'id' })
-    .select('id')
-    .single()
-
-  if (createError || !newPerson) {
-    throw new Error('Failed to auto-create person for auth user ' + authUserId + ': ' + createError?.message)
-  }
-
-  return newPerson.id
+  // Not found - return the auth ID as fallback
+  return authUserId
 }
 
 // ─── HELPER FUNCTIONS ────────────────────────────────────────────────────────

package/.framework/functions/_shared/resolve-ids.ts

@@ -4,12 +4,6 @@
 
 import { adminDb } from './db'
 
-interface ResolvedIds {
-  types: Record<string, string>
-  linkTypes: Record<string, string>
-  accounts: Record<string, string>
-}
-
 // Resolve type IDs by (kind, slug) pairs
 export async function resolveTypeIds(
   pairs: Array<{ kind: string; slug: string }>
@@ -67,6 +61,12 @@ export async function resolveLinkTypeIds(slugs: string[]): Promise<Record<string
   return result
 }
 
+// Resolve a single link type ID — throws if not found
+export async function resolveLinkTypeId(slug: string): Promise<string> {
+  const ids = await resolveLinkTypeIds([slug])
+  return ids[slug]
+}
+
 // Resolve account ID by slug
 export async function resolveAccountId(slug: string): Promise<string> {
   const { data, error } = await adminDb

package/.framework/functions/_shared/webhook-registry.ts

@@ -18,7 +18,7 @@
  * - Multi-tenancy: different tenants can have different handlers
  *
  * @seeAlso integration-routes.ts (uses this registry)
- * @seeAlso webhook-registration.ts (self-registration helper for custom handlers)
+ * @seeAlso custom_webhook-handlers.ts (legacy static registry - being phased out)
  */
 
 import { adminDb } from './db'
@@ -62,6 +62,48 @@ export async function lookupHandler(handlerName: string): Promise<{ functionName
   return { functionName: data.function_name }
 }
 
+/**
+ * Loads a webhook handler function dynamically.
+ * Uses dynamic import to avoid static dependencies.
+ *
+ * @param functionName - The Netlify function name (e.g., "custom_cortex-handler")
+ * @returns The handler function or null if not found
+ */
+export async function loadHandler(functionName: string): Promise<Function | null> {
+  try {
+    // Dynamic import of the handler function
+    // Functions are in the same directory after assembly
+    const module = await import(`../${functionName}`)
+    
+    // Handler should be exported as 'handler' or default
+    const handler = module.handler || module.default
+    
+    if (typeof handler !== 'function') {
+      console.error(`[webhook-registry] Export 'handler' not found in ${functionName}`)
+      return null
+    }
+
+    return handler
+  } catch (err) {
+    console.error(`[webhook-registry] Failed to load ${functionName}:`, err)
+    return null
+  }
+}
+
+/**
+ * Resolves a webhook handler by name.
+ * Combines lookup + load for convenience.
+ *
+ * @param handlerName - The handler identifier
+ * @returns The handler function or null
+ */
+export async function resolveHandler(handlerName: string): Promise<Function | null> {
+  const metadata = await lookupHandler(handlerName)
+  if (!metadata) return null
+
+  return loadHandler(metadata.functionName)
+}
+
 /**
  * Clears the handler cache. Useful for testing or after deployments.
  */

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
+  }
+})