spine-framework 0.3.145 → 0.4.1

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

@@ -1,18 +1,13 @@
-// 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."]
+// CIL[BEGIN stable_id="~/.framework/functions/adapters/generic-webhook-inbound.ts:InboundAdapterContext:interface" type="interface" identity="InboundAdapterContext" parent="~/.framework/functions/adapters/generic-webhook-inbound.ts"]
+// CIL[DOC-MACRO purpose="Defines the context structure passed to the generic inbound webhook adapter, including integration, credentials, account, app, event, and logger references."]
+// CIL[DOC-RESPONSIBILITY responsibility="Provides the typed shape of inbound webhook adapter context for TypeScript consumers."]
+// CIL[DOC-CONTEXT module="functions/adapters" layer="adapter" related_files=".framework/functions/adapters/generic-webhook-inbound.ts"]
+// CIL[DOC-CONTRACT inputs="none (type definition)" outputs="interface InboundAdapterContext" errors="" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Plain interface declaration with optional and required fields." notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+
+
 
 interface InboundAdapterContext {
   integration: any
@@ -22,7 +17,23 @@ interface InboundAdapterContext {
   event: string | null
   logger: { info: (msg: string, meta?: any) => void; warn: (msg: string, meta?: any) => void; error: (msg: string, meta?: any) => void }
 }
+// CIL[DOC-VECTOR type="context" content="purpose='Defines the context structure passed to the generic inbound webhook adapter, including integration, credentials, account, app, event, and logger references.'; No verified external callers; imports: none"]
+// CIL[DOC-VECTOR type="blast_radius" content="No direct caller data from CIL graph; local impact only"]
+// CIL[DOC-VECTOR type="configuration" content="No environment or build configuration dependencies identified"]
+// CIL[DOC-VECTOR type="constraint" content="Standard runtime; no special invariants documented"]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
+// CIL[END stable_id="~/.framework/functions/adapters/generic-webhook-inbound.ts:InboundAdapterContext:interface"]
 
+
+// CIL[BEGIN stable_id="~/.framework/functions/adapters/generic-webhook-inbound.ts:AdapterResult:interface" type="interface" identity="AdapterResult" parent="~/.framework/functions/adapters/generic-webhook-inbound.ts"]
+// CIL[DOC-MACRO purpose="Defines the standardized result shape returned by the generic inbound webhook adapter."]
+// CIL[DOC-RESPONSIBILITY responsibility="Provides the typed shape of webhook adapter results."]
+// CIL[DOC-CONTEXT module="functions/adapters" layer="adapter" related_files=".framework/functions/adapters/generic-webhook-inbound.ts"]
+// CIL[DOC-CONTRACT inputs="none (type definition)" outputs="interface AdapterResult" errors="" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Plain interface declaration for adapter output fields." notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
 interface AdapterResult {
   type_slug: string
   data: Record<string, any>
@@ -32,7 +43,23 @@ interface AdapterResult {
   error?: string
   retryable?: boolean
 }
+// CIL[DOC-VECTOR type="context" content="purpose='Defines the standardized result shape returned by the generic inbound webhook adapter.'; No verified external callers; imports: none"]
+// CIL[DOC-VECTOR type="blast_radius" content="No direct caller data from CIL graph; local impact only"]
+// CIL[DOC-VECTOR type="configuration" content="No environment or build configuration dependencies identified"]
+// CIL[DOC-VECTOR type="constraint" content="Standard runtime; no special invariants documented"]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
+// CIL[END stable_id="~/.framework/functions/adapters/generic-webhook-inbound.ts:AdapterResult:interface"]
+
 
+// CIL[BEGIN stable_id="~/.framework/functions/adapters/generic-webhook-inbound.ts:adapt:function" type="function" identity="adapt" parent="~/.framework/functions/adapters/generic-webhook-inbound.ts"]
+// CIL[DOC-MACRO purpose="Adapts an incoming generic webhook payload into a normalized AdapterResult for further pipeline processing."]
+// CIL[DOC-RESPONSIBILITY responsibility="Transforms raw webhook payload and context into a standardized record representation."]
+// CIL[DOC-CONTEXT module="functions/adapters" layer="adapter" related_files=".framework/functions/adapters/generic-webhook-inbound.ts"]
+// CIL[DOC-CONTRACT inputs="payload: any, ctx: InboundAdapterContext" outputs="Promise<AdapterResult>" errors="" side_effects="logs receipt via ctx.logger"]
+// CIL[DOC-MICRO logic_summary="Logs receipt, extracts provider/event/account details, builds a title, and returns a normalized webhook_event result." notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
 export async function adapt(payload: any, ctx: InboundAdapterContext): Promise<AdapterResult> {
   ctx.logger.info('generic-webhook-inbound received payload', {
     provider: ctx.integration?.provider,
@@ -52,5 +79,11 @@ export async function adapt(payload: any, ctx: InboundAdapterContext): Promise<A
     external_id: ctx.event
   }
 }
+// CIL[DOC-VECTOR type="context" content="purpose='Adapts an incoming generic webhook payload into a normalized AdapterResult for further pipeline processing.'; No verified external callers; imports: none"]
+// CIL[DOC-VECTOR type="blast_radius" content="No direct caller data from CIL graph; local impact only"]
+// CIL[DOC-VECTOR type="configuration" content="No environment or build configuration dependencies identified"]
+// CIL[DOC-VECTOR type="constraint" content="Standard runtime; no special invariants documented"]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
+// CIL[END stable_id="~/.framework/functions/adapters/generic-webhook-inbound.ts:adapt:function"]
 
-// CIL[END chunk_id="generic_webhook_inbound_module_header_1784200003"]

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

@@ -1,18 +1,13 @@
-// 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."]
+// CIL[BEGIN stable_id="~/.framework/functions/adapters/generic-webhook-outbound.ts:buildRequest:function" type="function" identity="buildRequest" parent="~/.framework/functions/adapters/generic-webhook-outbound.ts"]
+// CIL[DOC-MACRO purpose="Build an outbound HTTP request payload for the generic webhook adapter"]
+// CIL[DOC-RESPONSIBILITY responsibility="Construct the URL, method, headers, and body for a webhook call based on action configuration and API key"]
+// CIL[DOC-CONTEXT module="generic-webhook-outbound" layer="adapter" related_files=".framework/functions/adapters/generic-webhook-outbound.ts"]
+// CIL[DOC-CONTRACT inputs="_record: any, ctx: any" outputs="{ url, method, headers, body }" errors="Throws if actionConfig.url is missing" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Resolve actionConfig URL, optional method defaulting to POST, optional body, and optional apiKey; validate URL presence; merge headers with optional Bearer authorization; return request object" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+
+
 
 export function buildRequest(_record: any, ctx: any) {
   const url = ctx?.actionConfig?.url
@@ -39,5 +34,10 @@ export function buildRequest(_record: any, ctx: any) {
     body
   }
 }
-
-// CIL[END chunk_id="generic_webhook_outbound_adapter_module_header_1784700003"]
+// CIL[DOC-VECTOR type="context" content="purpose='Build an outbound HTTP request payload for the generic webhook adapter'; No verified external callers; imports: none"]
+// CIL[DOC-VECTOR type="blast_radius" content="No direct caller data from CIL graph; local impact only"]
+// CIL[DOC-VECTOR type="configuration" content="No environment or build configuration dependencies identified"]
+// CIL[DOC-VECTOR type="constraint" content="Standard runtime; no special invariants documented"]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
+// CIL[END stable_id="~/.framework/functions/adapters/generic-webhook-outbound.ts:buildRequest:function"]

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

@@ -1,18 +1,11 @@
-// 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."]
+// CIL[BEGIN stable_id="~/.framework/functions/adapters/openai-outbound.ts:buildRequest:function" type="function" identity="buildRequest" parent="~/.framework/functions/adapters/openai-outbound.ts"]
+// CIL[DOC-MACRO purpose="Build an outbound HTTP request for the OpenAI API"]
+// CIL[DOC-RESPONSIBILITY responsibility="Construct the request payload and headers for an OpenAI API call, validating endpoint and apiKey"]
+// CIL[DOC-CONTEXT module="openai-outbound" layer="adapter" related_files=".framework/functions/adapters/openai-outbound.ts"]
+// CIL[DOC-CONTRACT inputs="_record (unused), ctx (execution context with integration config, action config, and apiKey)" outputs="Request object with url, method, headers, and body" errors="Throws if endpoint or apiKey is missing" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Reads base URL, endpoint, and API key from ctx; validates them; builds and returns a POST request object" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
 
 export function buildRequest(_record: any, ctx: any) {
   const baseUrl = ctx?.integration?.config?.base_url || 'https://api.openai.com/v1'
@@ -36,5 +29,11 @@ export function buildRequest(_record: any, ctx: any) {
     body: ctx?.actionConfig?.body || {}
   }
 }
+// CIL[DOC-VECTOR type="context" content="purpose='Build an outbound HTTP request for the OpenAI API'; No verified external callers; imports: none"]
+// CIL[DOC-VECTOR type="blast_radius" content="No direct caller data from CIL graph; local impact only"]
+// CIL[DOC-VECTOR type="configuration" content="No environment or build configuration dependencies identified"]
+// CIL[DOC-VECTOR type="constraint" content="Standard runtime; no special invariants documented"]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
+// CIL[END stable_id="~/.framework/functions/adapters/openai-outbound.ts:buildRequest:function"]
 
-// CIL[END chunk_id="openai_outbound_adapter_module_header_1784700001"]