spine-framework 0.3.16 → 0.3.18

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

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

package/.framework/functions/integration-routes.ts

@@ -37,8 +37,7 @@
 
 import { adminDb } from './_shared/db'
 import { resolvePrincipal } from './_shared/principal'
-import { listRegisteredHandlers } from './_shared/webhook-registry'
-import { HANDLER_REGISTRY } from './handler-registry'
+import { resolveHandler, listRegisteredHandlers } from './_shared/webhook-registry'
 
 // ─── TYPES ────────────────────────────────────────────────────────────────
 
@@ -129,7 +128,7 @@ function validateSchema(data: any, schema: any, requestId: string): ValidationRe
     // Validate data type
     if (config.type) {
       const typeValid = validateType(value, config.type, fieldName)
-      if (!typeValid.valid && typeValid.error) {
+      if (!typeValid.valid) {
         errors.push(typeValid.error)
       }
     }
@@ -256,10 +255,7 @@ function sanitizeData(data: any, rules: string = 'strict'): any {
  * @param handlerName - The handler key from integration config (e.g. "webhook-handler")
  */
 async function loadCustomScript(handlerName: string): Promise<Function | null> {
-  const mod = HANDLER_REGISTRY[handlerName]
-  if (!mod) return null
-  const fn = mod.handler || mod.default
-  return typeof fn === 'function' ? fn : null
+  return resolveHandler(handlerName)
 }
 
 // ─── DIAGNOSTIC HANDLER (temporary — full trace in response) ──────────────