spine-framework-portal 0.1.9 → 0.2.0

package/components/KBGenerator.tsx

@@ -1,5 +1,5 @@
 import { useState } from 'react'
-import { resolveTypeId } from '../../lib/resolveTypeId'
+import { getTypeIdAsync } from '../hooks/useTypeRegistry'
 import { apiFetch } from '@core/lib/api'
 import { Card, CardContent, CardHeader } from '@core/components/ui/card'
 import { Button } from '@core/components/ui/button'
@@ -40,7 +40,7 @@ export function KBGenerator({ ticket, onGenerated, onCancel }: KBGeneratorProps)
   const handleSave = async () => {
     if (!generatedArticle) return
     try {
-      const kbArticleTypeId = await resolveTypeId('kb_article')
+      const kbArticleTypeId = await getTypeIdAsync('kb_article')
       const res = await apiFetch('/.netlify/functions/admin-data', {
         method: 'POST',
         headers: { 'Content-Type': 'application/json' },

package/functions/custom_portal-community-escalation.ts

@@ -1,10 +1,14 @@
-// Portal Community Escalation Handler
-// Converts unanswered community posts to support tickets.
-// Standalone: no dependency on cortex functions.
-// Triggered by cron — see portal seed/triggers.json.
-
-import { createHandler } from './_shared/middleware'
-import { adminDb } from './_shared/db'
+import { createHandler } from '../../../.framework/functions/_shared/middleware'
+import { adminDb } from '../../../.framework/functions/_shared/db'
+
+/**
+ * Portal Community Escalation Handler
+ *
+ * Triggered by cron schedule to convert unanswered community posts to support tickets.
+ * Posts unanswered for 24+ hours are escalated to the AI-first support queue.
+ *
+ * Uses adminDb (service role) for system-level operations across all accounts.
+ */
 
 interface CommunityPost {
   id: string
@@ -94,35 +98,9 @@ async function escalatePostToTicket(post: CommunityPost): Promise<string | null>
       })
       .eq('id', post.id)
 
-    // Attempt to trigger support triage pipeline if present
-    try {
-      const { data: pipeline } = await adminDb
-        .from('pipelines')
-        .select('id')
-        .ilike('name', '%support%triage%')
-        .limit(1)
-        .maybeSingle()
-
-      if (pipeline) {
-        await adminDb.from('pipeline_executions').insert({
-          pipeline_id: pipeline.id,
-          target_type: 'items',
-          target_id: ticketId,
-          status: 'pending',
-          input_context: {
-            ticket_id: ticketId,
-            account_id: post.account_id,
-            title: post.title,
-            description: post.description || '',
-            source: 'community_escalation',
-          },
-        })
-      }
-    } catch (err) {
-      console.error('Failed to trigger triage pipeline:', err)
-    }
+    await triggerTriageAgent(ticketId, post.account_id, post.title, post.description)
 
-    console.log(`Escalated post ${post.id} to ticket ${ticketId}`)
+    console.log(`Successfully escalated post ${post.id} to ticket ${ticketId}`)
     return ticketId
 
   } catch (err) {
@@ -131,6 +109,43 @@ async function escalatePostToTicket(post: CommunityPost): Promise<string | null>
   }
 }
 
+async function triggerTriageAgent(
+  ticketId: string,
+  accountId: string,
+  title: string,
+  content?: string
+): Promise<void> {
+  try {
+    const { data: pipeline } = await adminDb
+      .from('pipelines')
+      .select('id')
+      .ilike('name', '%support%triage%')
+      .limit(1)
+      .maybeSingle()
+
+    if (!pipeline) {
+      console.log('No support triage pipeline found, skipping auto-trigger')
+      return
+    }
+
+    await adminDb.from('pipeline_executions').insert({
+      pipeline_id: pipeline.id,
+      target_type: 'items',
+      target_id: ticketId,
+      status: 'pending',
+      input_context: {
+        ticket_id: ticketId,
+        account_id: accountId,
+        title,
+        description: content || '',
+        source: 'community_escalation',
+      },
+    })
+  } catch (err) {
+    console.error('Failed to trigger triage agent:', err)
+  }
+}
+
 export const checkUnanswered = createHandler(async (_ctx, _body) => {
   console.log('[PortalEscalation] Starting community escalation check...')
 

package/functions/custom_portal-signals.ts

@@ -1,45 +1,21 @@
-// Portal Signal Handler
-// Records portal user actions as funnel signals in the items table.
-// Portal users are always identified — no anonymous session handling.
-// Standalone: no dependency on cortex functions.
-
-import { createHandler } from './_shared/middleware'
-import { adminDb } from './_shared/db'
-import { resolveTypeIds, resolveAccountId } from './_shared/resolve-ids'
-
-async function resolveIds() {
-  const [types, unidentifiedVisitorsAccountId] = await Promise.all([
-    resolveTypeIds([{ kind: 'item', slug: 'funnel_signal' }]),
-    resolveAccountId('unidentified-visitors'),
-  ])
-  return {
-    FUNNEL_SIGNAL_TYPE_ID: types['item/funnel_signal'],
-    UNIDENTIFIED_VISITORS_ACCOUNT_ID: unidentifiedVisitorsAccountId,
-  }
-}
-
-function ratingToTemperature(rating: number): 'cold' | 'warm' | 'hot' {
-  if (rating <= 2) return 'cold'
-  if (rating <= 3) return 'warm'
-  return 'hot'
-}
-
-function calculateSimpleScore(actionValue: number): { calculated: number; rating: 1 | 2 | 3 | 4 | 5 } {
-  const calculated = actionValue
-  let rating: 1 | 2 | 3 | 4 | 5
-  if (calculated <= 1) rating = 1
-  else if (calculated <= 4) rating = 2
-  else if (calculated <= 8) rating = 3
-  else if (calculated <= 15) rating = 4
-  else rating = 5
-  return { calculated, rating }
-}
+import { createHandler } from '../../../.framework/functions/_shared/middleware'
+import { processSignal } from '../../functions/custom_funnel-signal'
 
 export const handler = createHandler(async (ctx, body) => {
-  const { action_type, action_value, action_description, session_id } = body || {}
-
-  if (!action_type || ![1, 2, 5].includes(action_value)) {
-    const err: any = new Error('action_type and action_value (1, 2, or 5) are required')
+  const { 
+    action_type, 
+    action_value, 
+    action_description, 
+    session_id,
+    url,
+    path,
+    referrer,
+    user_agent,
+    anonymous_id
+  } = body || {}
+
+  if (!action_type || typeof action_value !== 'number') {
+    const err: any = new Error('action_type and action_value are required')
     err.statusCode = 400
     throw err
   }
@@ -50,92 +26,30 @@ export const handler = createHandler(async (ctx, body) => {
     throw err
   }
 
-  const ids = await resolveIds()
-  const now = new Date().toISOString()
-  const scoring = calculateSimpleScore(action_value)
-  const resolvedSessionId = session_id || `portal_${ctx.principal.id}_${Date.now()}`
-
-  const signalData = {
-    identity: {
-      anonymous_id: null,
-      person_id: ctx.principal.id,
-      account_id: ctx.accountId,
-      session_id: resolvedSessionId,
-    },
-    classification: {
-      stage: 'identified',
-      source: 'int',
-    },
-    action: {
-      action_type,
-      action_value,
-      action_description: action_description || null,
-    },
-    scoring_components: {
-      raw_score: {
-        calculated: scoring.calculated,
-        max_possible: 25,
-        rating: scoring.rating,
-      },
-    },
-    processing: {
-      received_at: now,
-      enriched_at: now,
-      scored_at: now,
-      stitched_at: null,
-      stitched_to_account_id: null,
-    },
+  const payload = {
+    account_id: ctx.accountId,
+    person_id: ctx.principal.id,
+    session_id: session_id || `portal_${ctx.principal.id}_${Date.now()}`,
+    anonymous_id: anonymous_id || null,
+    stage: 'identified',
+    source: 'port', // Portal-specific source for user engagement tracking
+    action_type,
+    action_value,
+    ...(action_description && { action_description }),
+    ...(url && { url }),
+    ...(path && { path }),
+    ...(referrer && { referrer }),
+    ...(user_agent && { user_agent }),
+    occurred_at: new Date().toISOString()
   }
 
-  const { data, error } = await adminDb
-    .from('items')
-    .insert({
-      type_id: ids.FUNNEL_SIGNAL_TYPE_ID,
-      title: `${action_type} - ${action_value}`,
-      account_id: ctx.accountId,
-      data: signalData,
-    })
-    .select('id')
-    .single()
+  const result = await processSignal(payload, { accountId: ctx.accountId, requestId: ctx.requestId }, {})
 
-  if (error) {
-    throw new Error(`Failed to record portal signal: ${error.message}`)
-  }
-
-  // Update account funnel data
-  const { data: account } = await adminDb
-    .from('accounts')
-    .select('data')
-    .eq('id', ctx.accountId)
-    .single()
-
-  if (account) {
-    const currentRating = account.data?.ratings?.identified?.rating || 0
-    const shouldUpdate = scoring.rating > currentRating
-
-    await adminDb
-      .from('accounts')
-      .update({
-        data: {
-          ...account.data,
-          ...(shouldUpdate && {
-            lead_score: scoring.calculated,
-            temperature: ratingToTemperature(scoring.rating),
-            lifecycle_stage: 'identified',
-            ratings: {
-              ...(account.data?.ratings || {}),
-              identified: {
-                rating: scoring.rating,
-                raw_score: scoring.calculated,
-                calculated_at: now,
-              },
-            },
-          }),
-          last_signal_at: now,
-        },
-      })
-      .eq('id', ctx.accountId)
+  if (result?.status === 'error') {
+    const err: any = new Error(result.error || 'Signal processing failed')
+    err.statusCode = 400
+    throw err
   }
 
-  return { status: 'ok', signal_id: data.id, rating: scoring.rating }
+  return { status: 'ok', signal_id: result?.signal_id }
 })

package/hooks/useCommunity.ts

@@ -0,0 +1,78 @@
+import { useState, useEffect, useCallback } from 'react'
+import { apiFetch } from '@core/lib/api'
+import { getTypeIdAsync } from './useTypeRegistry'
+
+export interface CommunityPost {
+  id: string
+  title: string
+  description?: string
+  status: string
+  created_at: string
+  data?: Record<string, any>
+  design_schema?: Record<string, any>
+}
+
+const BASE = '/.netlify/functions/admin-data?entity=items&type_slug=community_post'
+
+async function fetchJSON(path: string, options?: RequestInit) {
+  const res = await apiFetch(path, {
+    ...options,
+    headers: { 'Content-Type': 'application/json', ...(options?.headers || {}) },
+  })
+  const text = await res.text()
+  let json: any
+  try { json = JSON.parse(text) } catch {
+    throw new Error(`HTTP ${res.status}: ${text.slice(0, 120)}`)
+  }
+  if (!res.ok || json.error) throw new Error(json.error || `HTTP ${res.status}`)
+  return json.data
+}
+
+export function useCommunityPosts() {
+  const [posts, setPosts] = useState<CommunityPost[]>([])
+  const [loading, setLoading] = useState(true)
+  const [error, setError] = useState<string | null>(null)
+
+  const load = useCallback(async () => {
+    setLoading(true)
+    setError(null)
+    try {
+      const data = await fetchJSON(BASE)
+      setPosts(data || [])
+    } catch (e: any) {
+      setError(e.message)
+    } finally {
+      setLoading(false)
+    }
+  }, [])
+
+  useEffect(() => { load() }, [load])
+
+  return { posts, loading, error, refetch: load }
+}
+
+export function useCreatePost() {
+  const [loading, setLoading] = useState(false)
+  const [error, setError] = useState<string | null>(null)
+
+  const createPost = useCallback(async (fields: { title: string; description?: string; data?: Record<string, any> }) => {
+    setLoading(true)
+    setError(null)
+    try {
+      const typeId = await getTypeIdAsync('community_post')
+      if (!typeId) throw new Error('community_post type not found')
+      
+      return await fetchJSON('/.netlify/functions/admin-data', {
+        method: 'POST',
+        body: JSON.stringify({ entity: 'items', type_id: typeId, ...fields }),
+      })
+    } catch (e: any) {
+      setError(e.message)
+      throw e
+    } finally {
+      setLoading(false)
+    }
+  }, [])
+
+  return { createPost, loading, error }
+}

package/hooks/useCourses.ts

@@ -0,0 +1,67 @@
+import { useState, useEffect, useCallback } from 'react'
+import { apiFetch } from '@core/lib/api'
+
+export interface CourseItem {
+  id: string
+  title: string
+  description?: string
+  status: string
+  created_at: string
+  data?: Record<string, any>
+  design_schema?: Record<string, any>
+}
+
+async function fetchJSON(path: string, options?: RequestInit) {
+  const res = await apiFetch(path, {
+    ...options,
+    headers: { 'Content-Type': 'application/json', ...(options?.headers || {}) },
+  })
+  const text = await res.text()
+  let json: any
+  try { json = JSON.parse(text) } catch {
+    throw new Error(`HTTP ${res.status}: ${text.slice(0, 120)}`)
+  }
+  if (!res.ok || json.error) throw new Error(json.error || `HTTP ${res.status}`)
+  return json.data
+}
+
+export function useCourseLessons() {
+  const [lessons, setLessons] = useState<CourseItem[]>([])
+  const [loading, setLoading] = useState(true)
+  const [error, setError] = useState<string | null>(null)
+
+  const load = useCallback(async () => {
+    setLoading(true)
+    setError(null)
+    try {
+      const data = await fetchJSON('/.netlify/functions/admin-data?entity=items&type_slug=course_lesson')
+      setLessons(data || [])
+    } catch (e: any) {
+      setError(e.message)
+    } finally {
+      setLoading(false)
+    }
+  }, [])
+
+  useEffect(() => { load() }, [load])
+
+  return { lessons, loading, error, refetch: load }
+}
+
+export function useCompleteLesson() {
+  const [loading, setLoading] = useState(false)
+
+  const completeLesson = useCallback(async (lessonId: string) => {
+    setLoading(true)
+    try {
+      return await fetchJSON(`/.netlify/functions/admin-data?entity=items&id=${lessonId}`, {
+        method: 'PATCH',
+        body: JSON.stringify({ status: 'completed' }),
+      })
+    } finally {
+      setLoading(false)
+    }
+  }, [])
+
+  return { completeLesson, loading }
+}

package/hooks/useItemProgress.ts

@@ -0,0 +1,114 @@
+import { useState, useEffect, useCallback, useRef } from 'react'
+import { apiFetch } from '@core/lib/api'
+import { ItemProgress } from '@core/types/types'
+
+async function fetchJSON(path: string, options?: RequestInit): Promise<any> {
+  const res = await apiFetch(path, {
+    ...options,
+    headers: { 'Content-Type': 'application/json', ...(options?.headers || {}) },
+  })
+  const text = await res.text()
+  let json: any
+  try { json = JSON.parse(text) } catch {
+    throw new Error(`HTTP ${res.status}: ${text.slice(0, 120)}`)
+  }
+  if (!res.ok || json.error) throw new Error(json.error || `HTTP ${res.status}`)
+  return json.data ?? json
+}
+
+/**
+ * Batch-fetches item_progress records for a set of item IDs for the current person.
+ * Returns a Map<itemId, ItemProgress> for O(1) lookup in components.
+ *
+ * @param personId - The current portal user's person ID
+ * @param itemIds  - Array of item IDs to fetch progress for
+ */
+export function useItemProgress(personId: string | null, itemIds: string[]) {
+  const [progressMap, setProgressMap] = useState<Map<string, ItemProgress>>(new Map())
+  const [loading, setLoading] = useState(false)
+  const [error, setError] = useState<string | null>(null)
+  const prevKey = useRef<string>('')
+
+  const load = useCallback(async () => {
+    if (!personId || itemIds.length === 0) {
+      setProgressMap(new Map())
+      return
+    }
+
+    const key = `${personId}:${itemIds.sort().join(',')}`
+    if (key === prevKey.current) return
+    prevKey.current = key
+
+    setLoading(true)
+    setError(null)
+    try {
+      const ids = itemIds.join(',')
+      const records: ItemProgress[] = await fetchJSON(
+        `/.netlify/functions/item-progress?person_id=${personId}&item_ids=${ids}`
+      )
+      const map = new Map<string, ItemProgress>()
+      for (const r of records || []) map.set(r.item_id, r)
+      setProgressMap(map)
+    } catch (e: any) {
+      setError(e.message)
+    } finally {
+      setLoading(false)
+    }
+  }, [personId, itemIds.join(',')])
+
+  useEffect(() => { load() }, [load])
+
+  return { progressMap, loading, error, refetch: load }
+}
+
+/**
+ * Returns an `upsert` function that creates or updates an item_progress record.
+ * Handles auto-composition of title/description server-side.
+ *
+ * Usage:
+ *   const { upsert, loading } = useUpsertProgress()
+ *   await upsert({ personId, itemId, typeId, accountId, status: 'completed', score: 85 })
+ */
+export function useUpsertProgress() {
+  const [loading, setLoading] = useState(false)
+  const [error, setError] = useState<string | null>(null)
+
+  const upsert = useCallback(async (params: {
+    personId: string
+    itemId: string
+    typeId: string
+    accountId: string
+    appId?: string
+    status?: string
+    score?: number
+    data?: Record<string, any>
+    force?: boolean
+  }): Promise<ItemProgress> => {
+    setLoading(true)
+    setError(null)
+    try {
+      const result = await fetchJSON('/.netlify/functions/item-progress', {
+        method: 'POST',
+        body: JSON.stringify({
+          person_id:  params.personId,
+          item_id:    params.itemId,
+          type_id:    params.typeId,
+          account_id: params.accountId,
+          app_id:     params.appId,
+          status:     params.status,
+          score:      params.score,
+          data:       params.data,
+          force:      params.force,
+        }),
+      })
+      return result
+    } catch (e: any) {
+      setError(e.message)
+      throw e
+    } finally {
+      setLoading(false)
+    }
+  }, [])
+
+  return { upsert, loading, error }
+}

package/hooks/useKBArticles.ts

@@ -0,0 +1,81 @@
+import { useState, useEffect, useCallback } from 'react'
+import { apiFetch } from '@core/lib/api'
+
+export interface KBArticle {
+  id: string
+  title: string
+  description?: string
+  status: string
+  created_at: string
+  data?: Record<string, any>
+  design_schema?: Record<string, any>
+}
+
+async function fetchJSON(path: string, options?: RequestInit) {
+  const res = await apiFetch(path, {
+    ...options,
+    headers: { 'Content-Type': 'application/json', ...(options?.headers || {}) },
+  })
+  const text = await res.text()
+  let json: any
+  try { json = JSON.parse(text) } catch {
+    throw new Error(`HTTP ${res.status}: ${text.slice(0, 120)}`)
+  }
+  if (!res.ok || json.error) throw new Error(json.error || `HTTP ${res.status}`)
+  return json.data
+}
+
+export function useKBArticles(search = '') {
+  const [articles, setArticles] = useState<KBArticle[]>([])
+  const [loading, setLoading] = useState(true)
+  const [error, setError] = useState<string | null>(null)
+
+  const load = useCallback(async () => {
+    setLoading(true)
+    setError(null)
+    try {
+      if (search && search.trim().length >= 2) {
+        // Vector similarity search via embeddings
+        const res = await apiFetch('/api/custom_kb-embeddings?action=search', {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify({ query: search.trim(), limit: 10 }),
+        })
+        const json = await res.json()
+        const results = json.data || json || []
+        setArticles(Array.isArray(results) ? results : [])
+      } else {
+        // No search — show all published articles
+        const data = await fetchJSON(`/.netlify/functions/admin-data?entity=items&type_slug=kb_article&status=published`)
+        const visible = (data || []).filter((a: KBArticle) => a.data?.security_level !== 'restricted')
+        setArticles(visible)
+      }
+    } catch (e: any) {
+      setError(e.message)
+    } finally {
+      setLoading(false)
+    }
+  }, [search])
+
+  useEffect(() => { load() }, [load])
+
+  return { articles, loading, error, refetch: load }
+}
+
+export function useKBArticle(id: string | null) {
+  const [article, setArticle] = useState<KBArticle | null>(null)
+  const [loading, setLoading] = useState(false)
+  const [error, setError] = useState<string | null>(null)
+
+  useEffect(() => {
+    if (!id) { setArticle(null); return }
+    setLoading(true)
+    setError(null)
+    fetchJSON(`/.netlify/functions/admin-data?entity=items&id=${id}`)
+      .then(setArticle)
+      .catch((e: any) => setError(e.message))
+      .finally(() => setLoading(false))
+  }, [id])
+
+  return { article, loading, error }
+}