spine-framework 0.1.0

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

@@ -0,0 +1,168 @@
+/**
+ * @module webhook-registration
+ * @audience custom-developer
+ * @layer shared-util
+ * @stability stable
+ *
+ * Helper utilities for custom webhook handlers to self-register.
+ * Use this in your custom Netlify functions to register as webhook handlers.
+ *
+ * **Usage in a custom function:**
+ * ```ts
+ * import { createHandler } from '../_shared/middleware'
+ * import { registerWebhookHandler } from '../_shared/webhook-registration'
+ * import { adminDb } from '../_shared/db'
+ *
+ * export const handler = createHandler(async (event, ctx) => {
+ *   // Your webhook logic here
+ * })
+ *
+ * // Self-register on first load (idempotent)
+ * registerWebhookHandler({
+ *   name: 'my-custom-handler',
+ *   functionName: 'custom_my-webhook',
+ *   description: 'Handles my custom integration events',
+ *   events: ['user.created', 'item.updated'],
+ *   db: adminDb
+ * }).catch(console.error)
+ * ```
+ *
+ * @seeAlso webhook-registry.ts (core lookup service)
+ * @seeAlso 014_webhook_registry.sql (database table)
+ */
+
+import { adminDb } from './db'
+
+export interface WebhookHandlerRegistration {
+  /** Unique handler identifier (e.g., 'cortex-handler') */
+  name: string
+  
+  /** Netlify function name (e.g., 'custom_cortex-handler') */
+  functionName: string
+  
+  /** Human-readable description */
+  description?: string
+  
+  /** Events this handler subscribes to */
+  events?: string[]
+  
+  /** Account ID (null for system handlers) */
+  accountId?: string | null
+  
+  /** Database client (defaults to adminDb) */
+  db?: typeof adminDb
+}
+
+/**
+ * Registers a webhook handler in the database registry.
+ * Idempotent - safe to call multiple times.
+ *
+ * @param config - Handler registration configuration
+ * @returns Promise that resolves when registration completes
+ *
+ * @example
+ * ```ts
+ * await registerWebhookHandler({
+ *   name: 'slack-webhook',
+ *   functionName: 'custom_slack-integration',
+ *   description: 'Posts notifications to Slack',
+ *   events: ['item.created', 'item.updated']
+ * })
+ * ```
+ */
+export async function registerWebhookHandler(
+  config: WebhookHandlerRegistration
+): Promise<void> {
+  const db = config.db || adminDb
+  
+  try {
+    const { error } = await db
+      .from('webhook_handlers')
+      .upsert({
+        name: config.name,
+        function_name: config.functionName,
+        description: config.description || `${config.name} webhook handler`,
+        events: config.events || [],
+        account_id: config.accountId || null,
+        is_active: true,
+        is_deleted: false,
+        updated_at: new Date().toISOString()
+      }, {
+        onConflict: 'name'
+      })
+
+    if (error) {
+      console.error(`[webhook-registration] Failed to register ${config.name}:`, error)
+      throw error
+    }
+
+    console.log(`[webhook-registration] Registered handler: ${config.name}`)
+  } catch (err) {
+    console.error(`[webhook-registration] Error registering ${config.name}:`, err)
+    throw err
+  }
+}
+
+/**
+ * Deregisters a webhook handler (soft delete).
+ *
+ * @param name - Handler identifier to deregister
+ * @param db - Optional database client
+ */
+export async function deregisterWebhookHandler(
+  name: string,
+  db: typeof adminDb = adminDb
+): Promise<void> {
+  try {
+    const { error } = await db
+      .from('webhook_handlers')
+      .update({
+        is_active: false,
+        is_deleted: true,
+        deleted_at: new Date().toISOString()
+      })
+      .eq('name', name)
+
+    if (error) {
+      console.error(`[webhook-registration] Failed to deregister ${name}:`, error)
+      throw error
+    }
+
+    console.log(`[webhook-registration] Deregistered handler: ${name}`)
+  } catch (err) {
+    console.error(`[webhook-registration] Error deregistering ${name}:`, err)
+    throw err
+  }
+}
+
+/**
+ * Checks if a handler is registered.
+ *
+ * @param name - Handler identifier to check
+ * @param db - Optional database client
+ * @returns True if handler exists and is active
+ */
+export async function isHandlerRegistered(
+  name: string,
+  db: typeof adminDb = adminDb
+): Promise<boolean> {
+  try {
+    const { data, error } = await db
+      .from('webhook_handlers')
+      .select('name')
+      .eq('name', name)
+      .eq('is_active', true)
+      .eq('is_deleted', false)
+      .maybeSingle()
+
+    if (error) {
+      console.error(`[webhook-registration] Error checking ${name}:`, error)
+      return false
+    }
+
+    return !!data
+  } catch (err) {
+    console.error(`[webhook-registration] Exception checking ${name}:`, err)
+    return false
+  }
+}

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

@@ -0,0 +1,129 @@
+/**
+ * @module webhook-registry
+ * @audience core-contributor
+ * @layer shared-service
+ * @stability stable
+ *
+ * Dynamic webhook handler registry for runtime handler resolution.
+ * Replaces static imports with database-driven handler lookups.
+ *
+ * **Pattern:**
+ * 1. Custom handlers self-register via `integrations` table or `webhook_handlers` table
+ * 2. Core looks up handler by name at runtime
+ * 3. Dynamic import loads the handler function
+ *
+ * **Benefits:**
+ * - Core has zero hardcoded dependencies on custom handlers
+ * - Handlers can be added/removed without core code changes
+ * - 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)
+ */
+
+import { adminDb } from './db'
+
+// In-memory cache for handler metadata (not the handlers themselves)
+const handlerCache = new Map<string, { functionName: string; loaded: boolean }>()
+
+/**
+ * Looks up a webhook handler in the database registry.
+ * Returns the function name to dynamically import.
+ *
+ * @param handlerName - The handler identifier (e.g., "cortex-handler")
+ * @returns Handler metadata or null if not found
+ */
+export async function lookupHandler(handlerName: string): Promise<{ functionName: string } | null> {
+  // Check cache first
+  const cached = handlerCache.get(handlerName)
+  if (cached) {
+    return { functionName: cached.functionName }
+  }
+
+  // Query database for handler registration
+  const { data, error } = await adminDb
+    .from('webhook_handlers')
+    .select('name, function_name, is_active')
+    .eq('name', handlerName)
+    .eq('is_active', true)
+    .single()
+
+  if (error || !data) {
+    console.log(`[webhook-registry] Handler not found: ${handlerName}`)
+    return null
+  }
+
+  // Cache the result
+  handlerCache.set(handlerName, {
+    functionName: data.function_name,
+    loaded: false
+  })
+
+  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.
+ */
+export function clearHandlerCache(): void {
+  handlerCache.clear()
+}
+
+/**
+ * Lists all registered handlers (for debugging/admin).
+ */
+export async function listRegisteredHandlers(): Promise<string[]> {
+  const { data, error } = await adminDb
+    .from('webhook_handlers')
+    .select('name')
+    .eq('is_active', true)
+
+  if (error) {
+    console.error('[webhook-registry] Failed to list handlers:', error)
+    return []
+  }
+
+  return data?.map(h => h.name) || []
+}

package/.framework/functions/account-nodes.ts

@@ -0,0 +1,111 @@
+/**
+ * @module account-nodes
+ * @audience core-contributor
+ * @layer api-handler
+ * @stability stable
+ *
+ * Account hierarchy traversal endpoint. Given a single `node_id`, returns
+ * the target account record plus three relational views:
+ * - **ancestors** — all nodes from root to this node (via `get_account_ancestors` RPC)
+ * - **children** — direct active children ordered by `display_name`
+ * - **descendants** — all active nodes in the subtree (via `get_account_descendants` RPC)
+ *
+ * **Routed by:** `GET /.netlify/functions/account-nodes`
+ *
+ * **Authorization:** Uses `ctx.db` (RLS-scoped). Only accounts visible to
+ * the authenticated principal are returned. Inactive accounts are excluded
+ * (`is_active = true` filter on node + children queries).
+ *
+ * **Response shape:**
+ * ```ts
+ * {
+ *   node: Account & { type: TypeRecord }
+ *   ancestors: AccountAncestorRow[]
+ *   children: Array<Account & { type: TypeRecord }>
+ *   descendants: AccountDescendantRow[]
+ * }
+ * ```
+ *
+ * @seeAlso auth.ts (context handler also calls get_account_hierarchy RPC)
+ * @seeAlso accounts.ts (CRUD; creates the account nodes)
+ * @seeAlso _shared/db.ts (get_account_ancestors / get_account_descendants RPCs)
+ */
+
+import { createHandler } from './_shared/middleware'
+
+// ─── CHUNK_START: ACCOUNT_NODES_HANDLER ──────────────────────────────────────────────
+/**
+ * @chunk-id    ACCOUNT_NODES_HANDLER_1_0_0
+ * @version     1.0.0
+ * @hash        0778bcec10cfbe1a79177e4352706270194cf80cd0baa39c6ed615c73c7c7695
+ * @macro       Account Hierarchy Handler
+ * @micro       Returns account node with ancestors, children, and descendants
+ * @inputs      ctx: CoreContext — Request context with principal and database
+ * @inputs      body: any — Request body (unused for GET)
+ * @outputs     {node, ancestors, children, descendants} — Complete hierarchy data
+ * @depends-on  [createHandler, get_account_ancestors, get_account_descendants]
+ * @depended-by [Netlify function routing]
+ * @side-effects [DB queries, RPC calls]
+ * @tags        account, hierarchy, netlify-function, api
+ */
+export const handler = createHandler(async (ctx, body) => {
+  const { node_id } = ctx.query || {}
+  
+  if (!node_id) {
+    throw new Error('node_id is required')
+  }
+
+  // Get the account node
+  const { data: node, error: nodeError } = await ctx.db
+    .from('accounts')
+    .select(`
+      *,
+      type:types(id, slug, name, icon, color)
+    `)
+    .eq('id', node_id)
+    .eq('is_active', true)
+    .single()
+
+  if (nodeError || !node) {
+    throw new Error('Account node not found')
+  }
+
+  // Get ancestors using the closure table
+  const { data: ancestors, error: ancestorsError } = await ctx.db
+    .rpc('get_account_ancestors', { account_id: node_id })
+
+  if (ancestorsError) {
+    throw ancestorsError
+  }
+
+  // Get children (direct descendants)
+  const { data: children, error: childrenError } = await ctx.db
+    .from('accounts')
+    .select(`
+      *,
+      type:types(id, slug, name, icon, color)
+    `)
+    .eq('parent_id', node_id)
+    .eq('is_active', true)
+    .order('display_name')
+
+  if (childrenError) {
+    throw childrenError
+  }
+
+  // Get all descendants (optional, for tree view)
+  const { data: descendants, error: descendantsError } = await ctx.db
+    .rpc('get_account_descendants', { account_id: node_id })
+
+  if (descendantsError) {
+    throw descendantsError
+  }
+
+  return {
+    node,
+    ancestors: ancestors || [],
+    children: children || [],
+    descendants: descendants || []
+  }
+})
+// ─── CHUNK_END: ACCOUNT_NODES_HANDLER ────────────────────────────────────────────────