spine-framework 0.2.1 → 1.0.0

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

@@ -1,168 +0,0 @@
-/**
- * @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

@@ -1,129 +0,0 @@
-/**
- * @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

@@ -1,111 +0,0 @@
-/**
- * @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 ────────────────────────────────────────────────