spine-framework-cortex 0.1.19 → 0.2.0

package/functions/custom_funnel-signal.ts

@@ -1,446 +0,0 @@
-// Funnel Signal Handler
-// Ingests, scores, and persists funnel signals end-to-end.
-//
-// Handler Signature (per integration-routes.ts):
-// scriptHandler(sanitizedData, scriptContext, scriptEvent)
-// - sanitizedData: request body (sanitized by integration-routes)
-// - scriptContext: { integrationId, accountId, slug, principal, requestId, headers }
-// - scriptEvent: { httpMethod, headers, body, path, queryStringParameters }
-//
-// Uses adminDb for type-resolution lookups and all CRUD writes.
-// Scoring is inline — the Core trigger/pipeline engine cannot directly invoke
-// a custom function, so scoring is done synchronously here.
-
-import { adminDb } from './_shared/db'
-import {
-  calculateEngagement,
-  calculateRecency,
-  calculateRawScore,
-  inferOpportunityType,
-  categorizeReferrer,
-} from './custom_funnel-scoring'
-
-// ============================================
-// SIGNAL HANDLER (Integration Routes Compatible)
-// ============================================
-
-export default async function handler(
-  sanitizedData: any,
-  scriptContext: any,
-  _scriptEvent: any
-) {
-  return processSignal(sanitizedData, scriptContext, _scriptEvent)
-}
-
-export async function processSignal(
-  sanitizedData: any,
-  scriptContext: any,
-  _scriptEvent: any
-) {
-  const receivedAt = new Date().toISOString()
-
-  // 1. VALIDATE
-  const validation = validateSignalPayload(sanitizedData)
-  if (!validation.valid) {
-    return { status: 'error', error: (validation as { valid: false; error: string }).error }
-  }
-  const payload = validation.data
-
-  // 2. RESOLVE IDs (read-only type/account lookups)
-  const [signalTypeId, sessionTypeId, queueTypeId, signalLinkTypeId, opportunityLinkTypeId, sessionLinkTypeId, unidentifiedAccountId] =
-    await Promise.all([
-      resolveTypeId('funnel_signal'),
-      resolveTypeId('anonymous_session'),
-      resolveTypeId('opportunity_queue'),
-      resolveLinkTypeId('account_signals'),
-      resolveLinkTypeId('account_opportunities'),
-      resolveLinkTypeId('session_signals'),
-      resolveUnidentifiedAccountId(),
-    ])
-
-  if (!signalTypeId) {
-    return { status: 'error', error: 'funnel_signal type not found — run install-app cortex' }
-  }
-
-  // 3. ENRICH — fetch prior signals for this identity
-  const priorSignals = await fetchPriorSignals(payload, signalTypeId)
-
-  // 4. SCORE
-  const occurredAt = payload.occurred_at ? new Date(payload.occurred_at) : new Date()
-  const referrerDomain = extractDomain(payload.referrer)
-  const referrerCategory = categorizeReferrer(referrerDomain)
-  const engagement = calculateEngagement(priorSignals, payload.session_id || 'default', occurredAt.toISOString(), payload.stage)
-  const recency = calculateRecency(occurredAt, new Date(), payload.stage)
-  const scoring = recency.divisor === null
-    ? { calculated: 0, max_possible: 25, rating: 1 as const }
-    : calculateRawScore(payload.action_value, engagement.type, recency.divisor)
-  const scoredAt = new Date().toISOString()
-
-  // 5. INSERT SIGNAL ITEM
-  const signalData = {
-    identity: {
-      anonymous_id: payload.anonymous_id || null,
-      person_id: payload.person_id || null,
-      account_id: payload.account_id || null,
-      session_id: payload.session_id || null,
-    },
-    classification: {
-      stage: payload.stage,
-      source: payload.source,
-      pipeline_slug: payload.pipeline_slug || null,
-    },
-    action: {
-      action_type: payload.action_type,
-      action_value: payload.action_value,
-      action_description: payload.action_description || null,
-      url: payload.url || null,
-    },
-    // Scoring - flattened to match schema field names
-    raw_score_calculated: scoring.calculated,
-    raw_score_max_possible: scoring.max_possible,
-    raw_score_rating: scoring.rating,
-    engagement_type: engagement.type,
-    engagement_context: engagement.context,
-    engagement_session_depth: engagement.session_depth,
-    engagement_prior_session_count: engagement.prior_session_count || 0,
-    recency_divisor: recency.divisor,
-    recency_age_days: recency.age_days,
-    recency_window: recency.window,
-    attribution: {
-      immediate_referrer: payload.referrer || null,
-      first_touch_referrer_domain: referrerDomain,
-      utm_source: payload.utm_source || null,
-      utm_medium: payload.utm_medium || null,
-      utm_campaign: payload.utm_campaign || null,
-    },
-    processing: {
-      received_at: receivedAt,
-      enriched_at: scoredAt,
-      scored_at: scoredAt,
-      stitched_at: null,
-      stitched_to_account_id: null,
-    },
-    source_metadata: {
-      instance_id: payload.instance_id || null,
-      environment: payload.environment || null,
-    },
-  }
-
-  const { data: signalItem, error: signalErr } = await adminDb
-    .from('items')
-    .insert({
-      type_id: signalTypeId,
-      title: `${payload.action_type} - ${payload.action_value}`,
-      account_id: payload.account_id || unidentifiedAccountId,
-      data: signalData,
-    })
-    .select('id')
-    .single()
-
-  if (signalErr || !signalItem) {
-    console.error('[FunnelSignal] Failed to insert signal:', signalErr?.message)
-    return { status: 'error', error: 'Failed to create signal record' }
-  }
-
-  const signalId = signalItem.id
-
-  // 6. UPDATE ACCOUNT or UPSERT ANONYMOUS SESSION
-  if (payload.account_id) {
-    await updateAccountFunnel(payload.account_id, payload.stage, scoring, payload.pipeline_slug, referrerDomain, referrerCategory, scoredAt)
-    if (signalLinkTypeId) {
-      await createLink(signalLinkTypeId, 'account', payload.account_id, 'item', signalId)
-    }
-  } else if (payload.anonymous_id && sessionTypeId && unidentifiedAccountId) {
-    await upsertAnonymousSession(payload, sessionTypeId, unidentifiedAccountId, signalId, scoring, engagement, referrerDomain, referrerCategory, scoredAt, sessionLinkTypeId)
-  }
-
-  // 7. EVALUATE QUEUE — if rating >= 4
-  if (scoring.rating >= 4 && queueTypeId) {
-    await evaluateQueueEntry(payload, queueTypeId, opportunityLinkTypeId, signalId, scoring, scoredAt)
-  }
-
-  return {
-    status: 'success',
-    signal_id: signalId,
-    rating: scoring.rating,
-    raw_score: scoring.calculated,
-  }
-}
-
-// ============================================
-// VALIDATION
-// ============================================
-
-interface SignalPayload {
-  anonymous_id?: string
-  person_id?: string
-  account_id?: string
-  session_id?: string
-  stage: 'anonymous' | 'identified' | 'installed'
-  source: 'mar' | 'int' | 'use' | 'manual'
-  action_type: string
-  action_value: 1 | 2 | 5
-  action_description?: string
-  occurred_at?: string
-  url?: string
-  path?: string
-  referrer?: string
-  user_agent?: string
-  utm_source?: string
-  utm_medium?: string
-  utm_campaign?: string
-  instance_id?: string
-  environment?: 'dev' | 'staging' | 'production'
-  pipeline_slug?: string
-}
-
-function validateSignalPayload(body: any): { valid: true; data: SignalPayload } | { valid: false; error: string } {
-  if (!body) return { valid: false, error: 'Missing request body' }
-  if (!body.stage || !['anonymous', 'identified', 'installed'].includes(body.stage)) return { valid: false, error: 'Invalid or missing stage' }
-  if (!body.source || !['mar', 'int', 'use', 'manual'].includes(body.source)) return { valid: false, error: 'Invalid or missing source' }
-  if (!body.action_type) return { valid: false, error: 'Missing action_type' }
-  if (!body.action_value || ![1, 2, 5].includes(body.action_value)) return { valid: false, error: 'Invalid action_value (must be 1, 2, or 5)' }
-  if (!body.anonymous_id && !body.person_id && !body.account_id) return { valid: false, error: 'Must provide anonymous_id, person_id, or account_id' }
-  if (body.source === 'mar' && !body.session_id) return { valid: false, error: 'session_id required for marketing signals' }
-  return { valid: true, data: body as SignalPayload }
-}
-
-// ============================================
-// ID RESOLUTION HELPERS
-// ============================================
-
-async function resolveUnidentifiedAccountId(): Promise<string | null> {
-  const { data } = await adminDb.from('accounts').select('id').eq('slug', 'unidentified-visitors').maybeSingle()
-  return data?.id || null
-}
-
-async function resolveTypeId(slug: string): Promise<string | null> {
-  const { data } = await adminDb.from('types').select('id').eq('slug', slug).eq('is_active', true).maybeSingle()
-  return data?.id || null
-}
-
-async function resolveLinkTypeId(slug: string): Promise<string | null> {
-  const { data } = await adminDb.from('link_types').select('id').eq('slug', slug).maybeSingle()
-  return data?.id || null
-}
-
-// ============================================
-// ENRICHMENT
-// ============================================
-
-async function fetchPriorSignals(payload: SignalPayload, signalTypeId: string): Promise<Array<{ session_id: string; occurred_at: string }>> {
-  let query = adminDb.from('items').select('data').eq('type_id', signalTypeId).order('created_at', { ascending: true }).limit(100)
-  if (payload.anonymous_id) {
-    query = query.eq('data->identity->>anonymous_id' as any, payload.anonymous_id)
-  } else if (payload.account_id) {
-    query = query.eq('account_id', payload.account_id)
-  } else {
-    return []
-  }
-  const { data } = await query
-  return (data || []).map((r: any) => ({
-    session_id: r.data?.identity?.session_id || 'default',
-    occurred_at: r.data?.processing?.received_at || r.data?.processing?.scored_at || new Date().toISOString(),
-  }))
-}
-
-// ============================================
-// ACCOUNT UPDATE
-// ============================================
-
-async function updateAccountFunnel(
-  accountId: string, stage: string,
-  scoring: { calculated: number; max_possible: number; rating: number },
-  pipelineSlug: string | undefined, referrerDomain: string, referrerCategory: string, now: string
-): Promise<void> {
-  const { data: account } = await adminDb.from('accounts').select('data').eq('id', accountId).single()
-  if (!account) return
-
-  const currentData = account.data || {}
-  const temperature = ratingToTemperature(scoring.rating)
-  const ratingEntry = { rating: scoring.rating, raw_score: scoring.calculated, calculated_at: now }
-
-  const updatedRatings: Record<string, any> = { ...(currentData.ratings || {}) }
-  const currentStageRating = updatedRatings[stage]?.rating || 0
-  if (scoring.rating > currentStageRating) updatedRatings[stage] = ratingEntry
-  if (pipelineSlug) {
-    const currentPipelineRating = updatedRatings[pipelineSlug]?.rating || 0
-    if (scoring.rating >= currentPipelineRating) updatedRatings[pipelineSlug] = ratingEntry
-  }
-
-  const attribution = currentData.attribution || {
-    first_touch_referrer_domain: referrerDomain,
-    first_touch_referrer_category: referrerCategory,
-    first_touch_occurred_at: now,
-  }
-
-  await adminDb.from('accounts').update({
-    data: {
-      ...currentData,
-      lifecycle_stage: stage,
-      lead_score: scoring.calculated,
-      temperature,
-      last_signal_at: now,
-      ratings: updatedRatings,
-      attribution,
-    },
-  }).eq('id', accountId)
-}
-
-// ============================================
-// ANONYMOUS SESSION UPSERT
-// ============================================
-
-async function upsertAnonymousSession(
-  payload: SignalPayload, sessionTypeId: string, accountId: string, signalId: string,
-  scoring: { calculated: number; max_possible: number; rating: number },
-  engagement: any, referrerDomain: string, referrerCategory: string, now: string,
-  sessionLinkTypeId: string | null
-): Promise<void> {
-  const { data: existing } = await adminDb
-    .from('items')
-    .select('id, data')
-    .eq('type_id', sessionTypeId)
-    .eq('data->>anonymous_id' as any, payload.anonymous_id!)
-    .order('created_at', { ascending: false })
-    .limit(1)
-    .maybeSingle()
-
-  if (existing) {
-    const d = existing.data || {}
-    const shouldUpdate = scoring.rating > (d.scoring_rating || 0)
-    await adminDb.from('items').update({
-      data: {
-        ...d,
-        current_referrer_referrer_domain: referrerDomain,
-        current_referrer_referrer_url: payload.referrer || null,
-        current_referrer_occurred_at: now,
-        scoring_signal_count: (d.scoring_signal_count || 0) + 1,
-        lifecycle_last_activity_at: now,
-        ...(shouldUpdate ? {
-          scoring_rating: scoring.rating,
-          scoring_raw_score: scoring.calculated,
-          scoring_calculated_at: now,
-          scoring_best_signal_id: signalId,
-          temperature: ratingToTemperature(scoring.rating),
-        } : {}),
-      },
-    }).eq('id', existing.id)
-    // Link existing session to new signal
-    if (sessionLinkTypeId) {
-      await createLink(sessionLinkTypeId, 'item', existing.id, 'item', signalId)
-    }
-  } else {
-    const { data: newSession } = await adminDb.from('items').insert({
-      type_id: sessionTypeId,
-      account_id: accountId,
-      title: `Anonymous: ${payload.anonymous_id!.slice(0, 8)}`,
-      data: {
-        anonymous_id: payload.anonymous_id,
-        temperature: ratingToTemperature(scoring.rating),
-        current_stage: 'anonymous',
-        scoring_rating: scoring.rating,
-        scoring_raw_score: scoring.calculated,
-        scoring_signal_count: 1,
-        scoring_calculated_at: now,
-        scoring_best_signal_id: signalId,
-        first_touch_referrer_domain: referrerDomain,
-        first_touch_referrer_category: referrerCategory,
-        first_touch_referrer_url: payload.referrer || null,
-        first_touch_landing_page: payload.url || null,
-        first_touch_occurred_at: now,
-        first_touch_utm_source: payload.utm_source || null,
-        first_touch_utm_medium: payload.utm_medium || null,
-        first_touch_utm_campaign: payload.utm_campaign || null,
-        current_referrer_referrer_domain: referrerDomain,
-        current_referrer_referrer_url: payload.referrer || null,
-        current_referrer_occurred_at: now,
-        lifecycle_created_at: now,
-        lifecycle_last_activity_at: now,
-        retention_retention_days: 90,
-        retention_purge_after: new Date(Date.now() + 90 * 24 * 60 * 60 * 1000).toISOString(),
-      },
-    }).select('id').single()
-    // Link new session to signal
-    if (sessionLinkTypeId && newSession) {
-      await createLink(sessionLinkTypeId, 'item', newSession.id, 'item', signalId)
-    }
-  }
-}
-
-// ============================================
-// LINK CREATION
-// ============================================
-
-async function createLink(
-  linkTypeId: string, sourceType: string, sourceId: string, targetType: string, targetId: string
-): Promise<void> {
-  await adminDb.from('links').insert({
-    link_type_id: linkTypeId,
-    source_type: sourceType,
-    source_id: sourceId,
-    target_type: targetType,
-    target_id: targetId,
-  }).catch((err: any) => console.error('[FunnelSignal] Link insert failed:', err.message))
-}
-
-// ============================================
-// QUEUE ENTRY EVALUATION
-// ============================================
-
-async function evaluateQueueEntry(
-  payload: SignalPayload, queueTypeId: string, opportunityLinkTypeId: string | null,
-  signalId: string, scoring: { calculated: number; max_possible: number; rating: number }, now: string
-): Promise<void> {
-  const inference = inferOpportunityType(
-    [{ action: { action_type: payload.action_type } }],
-    payload.stage, scoring.rating
-  )
-
-  const { data: queueItem } = await adminDb.from('items').insert({
-    type_id: queueTypeId,
-    title: `${inference.type} - ${inference.confidence} priority`,
-    account_id: payload.account_id || null,
-    data: {
-      identity_account_id: payload.account_id || null,
-      trigger_source_signal_id: signalId,
-      trigger_trigger_stage: payload.stage,
-      trigger_trigger_rating: scoring.rating,
-      trigger_trigger_raw_score: scoring.calculated,
-      trigger_trigger_reason: `High engagement: ${inference.type}`,
-      recommendation_opportunity_type: inference.type,
-      recommendation_confidence: inference.confidence,
-      recommendation_suggested_priority: Math.min(scoring.rating, 5),
-      review_status: 'pending',
-      notes_auto_reason: `Auto-generated: ${inference.type} opportunity detected with confidence ${inference.confidence}`,
-    },
-  }).select('id').single().then((r: { data: { id: string } | null }) => r.data).catch(() => null)
-
-  if (payload.account_id && queueItem?.id) {
-    const { data: acct } = await adminDb.from('accounts').select('data').eq('id', payload.account_id).single()
-    if (acct) {
-      await adminDb.from('accounts').update({
-        data: { ...(acct.data || {}), queue: { pending_opportunity_id: queueItem.id } },
-      }).eq('id', payload.account_id)
-    }
-    if (opportunityLinkTypeId) {
-      await createLink(opportunityLinkTypeId, 'account', payload.account_id, 'item', queueItem.id)
-    }
-  }
-}
-
-// ============================================
-// UTILITIES
-// ============================================
-
-function extractDomain(url: string | undefined): string {
-  if (!url) return 'direct'
-  try { return new URL(url).hostname.replace(/^www\./, '') } catch { return url }
-}
-
-function ratingToTemperature(rating: number): 'cold' | 'warm' | 'hot' | 'on_fire' {
-  if (rating <= 2) return 'cold'
-  if (rating <= 3) return 'warm'
-  if (rating <= 4) return 'hot'
-  return 'on_fire'
-}