spine-framework 0.3.124 → 0.3.126

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

@@ -1,53 +1,35 @@
-/**
- * @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)
- */
 
+// CIL[BEGIN chunk_id="account-nodes_module_header_1784019432" type="module_header" identity="imports" parent="none"]
+// CIL[DOC-MACRO purpose="Import dependencies for account hierarchy traversal"]
+// CIL[DOC-RESPONSIBILITY responsibility="Provide middleware for request handling"]
+// CIL[DOC-CONTEXT module="account-nodes" layer="api-handler" related_files="[\"custom/apps/cortex/pages/operations/OperationsDashboard.tsx\",\".framework/src/pages/admin/TypeDetailPage.tsx\",\".framework/functions/_shared/principal.ts\",\".framework/functions/_shared/schema-utils.ts\",\"custom/apps/portal/pages/ContentPage.tsx\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="imported_modules" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Imports required modules for account node operations" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-AUDIENCE audience="developer"]
+// CIL[DOC-VECTOR type="context" content="Layer: api-handler. Direct callers: 0. Direct calls: 0. Related files: custom/apps/cortex/pages/operations/OperationsDashboard.tsx, .framework/src/pages/admin/TypeDetailPage.tsx, .framework/functions/_shared/principal.ts, .framework/functions/_shared/schema-utils.ts, custom/apps/portal/pages/ContentPage.tsx, \."]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
+// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
+// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
 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
- */
+// CIL[END chunk_id="account-nodes_module_header_1784019432"]
+// CIL[BEGIN chunk_id="account-nodes_handler_1784019432" type="function" identity="handler" parent="none"]
+// CIL[DOC-MACRO purpose="Return account node with ancestors, children, and descendants"]
+// CIL[DOC-RESPONSIBILITY responsibility="Fetch complete account hierarchy for a given node"]
+// CIL[DOC-CONTEXT module="account-nodes" layer="api-handler" related_files="[\"custom/apps/portal/pages/ContentPage.tsx\",\"custom/apps/cortex/pages/operations/OperationsDashboard.tsx\",\"custom/apps/cortex/functions/custom_cil-embeddings.ts\",\".framework/src/components/ui/dialog.tsx\",\".framework/functions/_shared/principal.ts\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="{node,ancestors,children,descendants}" errors="node_id_required,node_not_found" side_effects="database_queries,rpc_calls"]
+// CIL[DOC-MICRO logic_summary="Queries target node, uses RPC for ancestors/descendants, fetches direct children" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: api-handler. Direct callers: 0. Direct calls: 0. Related files: custom/apps/portal/pages/ContentPage.tsx, custom/apps/cortex/pages/operations/OperationsDashboard.tsx, custom/apps/cortex/functions/custom_cil-embeddings.ts, .framework/src/components/ui/dialog.tsx, .framework/functions/_shared/principal.ts, \."]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
+// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
+// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
 export const handler = createHandler(async (ctx, body) => {
   const { node_id } = ctx.query || {}
   
@@ -55,7 +37,6 @@ export const handler = createHandler(async (ctx, body) => {
     throw new Error('node_id is required')
   }
 
-  // Get the account node
   const { data: node, error: nodeError } = await ctx.db
     .from('accounts')
     .select(`
@@ -70,7 +51,6 @@ export const handler = createHandler(async (ctx, body) => {
     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 })
 
@@ -78,7 +58,6 @@ export const handler = createHandler(async (ctx, body) => {
     throw ancestorsError
   }
 
-  // Get children (direct descendants)
   const { data: children, error: childrenError } = await ctx.db
     .from('accounts')
     .select(`
@@ -93,7 +72,6 @@ export const handler = createHandler(async (ctx, body) => {
     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 })
 
@@ -108,4 +86,4 @@ export const handler = createHandler(async (ctx, body) => {
     descendants: descendants || []
   }
 })
-// ─── CHUNK_END: ACCOUNT_NODES_HANDLER ────────────────────────────────────────────────
+// CIL[END chunk_id="account-nodes_handler_1784019432"]

package/.framework/functions/adapters/generic-webhook-inbound.ts

@@ -0,0 +1,56 @@
+// CIL[BEGIN chunk_id="generic_webhook_inbound_module_header_1784200003" type="module_header" identity="imports" parent="none"]
+// CIL[DOC-MACRO purpose="Built-in generic inbound webhook adapter"]
+// CIL[DOC-RESPONSIBILITY responsibility="Capture any webhook payload as a webhook_event item for debugging"]
+// CIL[DOC-CONTEXT module="generic_webhook_inbound" layer="backend_functions" related_files="[".framework/migrations/051_integration_broker.sql",".framework/functions/integration-routes.ts",".framework/functions/_shared/webhook-registry.ts"]"]
+// CIL[DOC-CONTRACT inputs="payload and integration context" outputs="AdapterResult" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Normalizes the raw webhook payload into a webhook_event record. Does not touch the database." notable_decisions="["Never imports adminDb or ctx.db.","Stores the full payload and headers as json fields."]"]
+// CIL[DOC-CONFIDENCE pass="first" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="experimental"]
+// CIL[DOC-AUDIENCE audience="developer"]
+// CIL[DOC-VECTOR type="context" content="Layer: backend_functions. Direct callers: 0. Direct calls: 0. Related files: .framework/migrations/051_integration_broker.sql, .framework/functions/integration-routes.ts, .framework/functions/_shared/webhook-registry.ts."]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
+// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
+// CIL[DOC-VECTOR type="constraint" content="Pure transform only."]
+// CIL[DOC-VECTOR type="implementation_pattern" content="Fallback adapter for any unmapped webhook."]
+// CIL[DOC-VECTOR type="user_journey" content="Admins capture raw webhooks without writing a custom adapter."]
+
+interface InboundAdapterContext {
+  integration: any
+  apiKey: any
+  accountId: string
+  appId?: string
+  event: string | null
+  logger: { info: (msg: string, meta?: any) => void; warn: (msg: string, meta?: any) => void; error: (msg: string, meta?: any) => void }
+}
+
+interface AdapterResult {
+  type_slug: string
+  data: Record<string, any>
+  title?: string
+  status?: string
+  external_id?: string
+  error?: string
+  retryable?: boolean
+}
+
+export async function adapt(payload: any, ctx: InboundAdapterContext): Promise<AdapterResult> {
+  ctx.logger.info('generic-webhook-inbound received payload', {
+    provider: ctx.integration?.provider,
+    event: ctx.event,
+    account_id: ctx.accountId
+  })
+
+  return {
+    type_slug: 'webhook_event',
+    title: `${ctx.integration?.provider || 'unknown'} ${ctx.event || 'webhook'}`,
+    data: {
+      provider: ctx.integration?.provider || 'unknown',
+      event: ctx.event,
+      payload: payload,
+      headers: ctx.apiKey ? {} : {}
+    },
+    external_id: ctx.event
+  }
+}
+
+// CIL[END chunk_id="generic_webhook_inbound_module_header_1784200003"]

package/.framework/functions/adapters/generic-webhook-outbound.ts

@@ -0,0 +1,43 @@
+// CIL[BEGIN chunk_id="generic_webhook_outbound_adapter_module_header_1784700003" type="module_header" identity="module_header" parent="none"]
+// CIL[DOC-MACRO purpose="Generic webhook outbound adapter for arbitrary URLs"]
+// CIL[DOC-RESPONSIBILITY responsibility="Build HTTP requests for pipeline webhook stages"]
+// CIL[DOC-CONTEXT module="generic-webhook-outbound" layer="backend_functions" related_files="[".framework/functions/_shared/pipeline-runner.ts",".framework/functions/integration-outbound.ts",".framework/migrations/051_integration_broker.sql"]"]
+// CIL[DOC-CONTRACT inputs="record, adapter context" outputs="OutboundRequest" errors="missing url" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Builds a request from actionConfig.url, method, headers, and body. Optional apiKey is added as Bearer Authorization." notable_decisions="["Ignores record.","Accepts actionConfig.url as the full URL."]"]
+// CIL[DOC-CONFIDENCE pass="first" score="0.85" flags="none"]
+// CIL[DOC-STABILITY stability="experimental"]
+// CIL[DOC-AUDIENCE audience="developer"]
+// CIL[DOC-VECTOR type="context" content="Layer: backend_functions. Direct callers: 0. Direct calls: 0. Related files: .framework/functions/_shared/pipeline-runner.ts, .framework/functions/integration-outbound.ts, .framework/migrations/051_integration_broker.sql."]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
+// CIL[DOC-VECTOR type="configuration" content="Requires actionConfig.url and method."]
+// CIL[DOC-VECTOR type="constraint" content="No path joining; url is used as-is."]
+// CIL[DOC-VECTOR type="implementation_pattern" content="Called by integration-outbound for the generic-http integration."]
+// CIL[DOC-VECTOR type="user_journey" content="Pipeline webhook stages go through the broker."]
+
+export function buildRequest(_record: any, ctx: any) {
+  const url = ctx?.actionConfig?.url
+  const method = ctx?.actionConfig?.method || 'POST'
+  const body = ctx?.actionConfig?.body
+  const apiKey = ctx?.apiKey?.value
+
+  if (!url) {
+    throw new Error('generic-webhook-outbound adapter requires actionConfig.url')
+  }
+
+  const headers: Record<string, string> = {
+    'Content-Type': 'application/json',
+    ...(ctx?.actionConfig?.headers || {})
+  }
+  if (apiKey) {
+    headers.Authorization = `Bearer ${apiKey}`
+  }
+
+  return {
+    url,
+    method,
+    headers,
+    body
+  }
+}
+
+// CIL[END chunk_id="generic_webhook_outbound_adapter_module_header_1784700003"]

package/.framework/functions/adapters/openai-outbound.ts

@@ -0,0 +1,40 @@
+// CIL[BEGIN chunk_id="openai_outbound_adapter_module_header_1784700001" type="module_header" identity="module_header" parent="none"]
+// CIL[DOC-MACRO purpose="OpenAI outbound adapter for the integration broker"]
+// CIL[DOC-RESPONSIBILITY responsibility="Build HTTP requests for the system OpenAI integration"]
+// CIL[DOC-CONTEXT module="openai-outbound" layer="backend_functions" related_files="[".framework/functions/integration-outbound.ts",".framework/functions/_shared/llm.ts",".framework/migrations/051_integration_broker.sql"]"]
+// CIL[DOC-CONTRACT inputs="record, adapter context" outputs="OutboundRequest" errors="missing endpoint or apiKey" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Combines the OpenAI base URL, endpoint, and resolved api_token into a signed request." notable_decisions="["Authorization header is Bearer <api_token>.","Body is taken directly from actionConfig.body."]"]
+// CIL[DOC-CONFIDENCE pass="first" score="0.85" flags="none"]
+// CIL[DOC-STABILITY stability="experimental"]
+// CIL[DOC-AUDIENCE audience="developer"]
+// CIL[DOC-VECTOR type="context" content="Layer: backend_functions. Direct callers: 0. Direct calls: 0. Related files: .framework/functions/integration-outbound.ts, .framework/functions/_shared/llm.ts, .framework/migrations/051_integration_broker.sql."]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
+// CIL[DOC-VECTOR type="configuration" content="Expects integration config base_url and api_token credential."]
+// CIL[DOC-VECTOR type="constraint" content="actionConfig.body is sent as JSON."]
+// CIL[DOC-VECTOR type="implementation_pattern" content="Loaded by integration-outbound for openai integration."]
+// CIL[DOC-VECTOR type="user_journey" content="Core LLM calls route through the broker."]
+
+export function buildRequest(_record: any, ctx: any) {
+  const baseUrl = ctx?.integration?.config?.base_url || 'https://api.openai.com/v1'
+  const endpoint = ctx?.actionConfig?.endpoint
+  const apiKey = ctx?.apiKey?.value
+
+  if (!endpoint) {
+    throw new Error('OpenAI adapter requires action_config.endpoint')
+  }
+  if (!apiKey) {
+    throw new Error('OpenAI adapter requires api_token credential')
+  }
+
+  return {
+    url: `${baseUrl.replace(/\/$/, '')}${endpoint}`,
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      Authorization: `Bearer ${apiKey}`
+    },
+    body: ctx?.actionConfig?.body || {}
+  }
+}
+
+// CIL[END chunk_id="openai_outbound_adapter_module_header_1784700001"]