spine-framework 0.3.125 → 0.3.126

package/.framework/functions/integration-outbound.ts

@@ -0,0 +1,311 @@
+// CIL[BEGIN chunk_id="integration_outbound_module_header_1784200004" type="module_header" identity="imports" parent="none"]
+// CIL[DOC-MACRO purpose="Outbound integration broker action"]
+// CIL[DOC-RESPONSIBILITY responsibility="Execute outbound HTTP calls through configured integrations and log deliveries"]
+// CIL[DOC-CONTEXT module="integration-outbound" layer="backend_functions" related_files="[".framework/functions/_shared/resolve-credentials.ts",".framework/functions/admin-data.ts",".framework/functions/_shared/audit.ts",".framework/functions/_shared/pipeline-runner.ts",".framework/migrations/051_integration_broker.sql"]"]
+// CIL[DOC-CONTRACT inputs="ctx, body with integration_slug and record_id" outputs="{ success, delivery_id, response_status }" errors="integration_not_found, credential_missing, adapter_error, http_error" side_effects="HTTP request, webhook_deliveries insert/update, optional admin-data update"]
+// CIL[DOC-MICRO logic_summary="Loads integration, resolves credential, loads adapter, builds request, performs HTTP call, and records the result in webhook_deliveries. Supports retry by delivery_id for internal callers." notable_decisions="["Outbound uses integrations.credentials, not api_keys (which are for inbound).","Failures are written to webhook_deliveries for retry by system-cron.","Record updates go through admin-data.","When delivery_id is passed by an internal principal, the existing delivery row is reused."]"]
+// CIL[DOC-CONFIDENCE pass="first" score="0.9" 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/resolve-credentials.ts, .framework/functions/admin-data.ts, .framework/functions/_shared/audit.ts, .framework/functions/_shared/pipeline-runner.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="No configuration dependencies."]
+// CIL[DOC-VECTOR type="constraint" content="Requires integration.slug and a credential field."]
+// CIL[DOC-VECTOR type="implementation_pattern" content="Called as a pipeline action or directly via /.netlify/functions/integration-outbound."]
+// CIL[DOC-VECTOR type="user_journey" content="Spine calls an external service through the broker."]
+
+import { createHandler, CoreContext } from './_shared/middleware'
+import { adminDb } from './_shared/db'
+import { emitLog } from './_shared/audit'
+import { resolveCredential } from './_shared/resolve-credentials'
+import { get as adminDataGet, update as adminDataUpdate } from './admin-data'
+import * as openaiOutbound from './adapters/openai-outbound'
+import * as genericWebhookOutbound from './adapters/generic-webhook-outbound'
+
+interface OutboundRequest {
+  url: string
+  method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE'
+  headers?: Record<string, string>
+  body?: any
+  external_id?: string
+}
+
+interface OutboundAdapterContext {
+  record: any
+  integration: any
+  apiKey?: any
+  accountId: string | null
+  appId: string | null
+  actionConfig: any
+}
+
+function computeNextAttempt(attemptCount: number, baseMs = 30000, maxDelayMs = 3600000): Date {
+  const delay = Math.min(baseMs * Math.pow(2, attemptCount), maxDelayMs)
+  const jitter = Math.floor(Math.random() * delay * 0.2)
+  return new Date(Date.now() + delay + jitter)
+}
+
+export async function execute(ctx: CoreContext, body: any = {}): Promise<any> {
+  let deliveryId = body?.delivery_id
+  let requestBody = body
+  let isRetry = false
+
+  if (deliveryId && ctx.principal?.isInternal) {
+    const { data: delivery, error: deliveryError } = await adminDb
+      .from('webhook_deliveries')
+      .select('*')
+      .eq('id', deliveryId)
+      .single()
+
+    if (deliveryError || !delivery) {
+      throw new Error(`Delivery not found: ${deliveryId}`)
+    }
+
+    requestBody = delivery.payload || {}
+    isRetry = true
+
+    await adminDb
+      .from('webhook_deliveries')
+      .update({ status: 'processing', updated_at: new Date().toISOString() })
+      .eq('id', deliveryId)
+  }
+
+  const { integration_slug, record_id, action_config = {} } = requestBody
+
+  if (!integration_slug) {
+    throw new Error('integration_slug is required')
+  }
+
+  let integration: any = null
+
+  if (ctx.accountId) {
+    const { data: tenant } = await adminDb
+      .from('integrations')
+      .select('*')
+      .eq('slug', integration_slug)
+      .eq('account_id', ctx.accountId)
+      .eq('is_active', true)
+      .maybeSingle()
+    if (tenant) integration = tenant
+  }
+
+  if (!integration) {
+    const { data: system } = await adminDb
+      .from('integrations')
+      .select('*')
+      .eq('slug', integration_slug)
+      .is('account_id', null)
+      .eq('is_active', true)
+      .maybeSingle()
+    if (system) integration = system
+  }
+
+  if (!integration) {
+    throw new Error(`Integration not found: ${integration_slug}`)
+  }
+
+  let record: any = null
+  if (record_id) {
+    const getCtx = { ...ctx, query: { entity: 'items', id: record_id } } as any
+    record = await adminDataGet(getCtx)
+  }
+
+  let deliveryPayload: any
+  if (!deliveryId) {
+    deliveryPayload = {
+      direction: 'outbound',
+      integration_id: integration.id,
+      record_id: record_id || null,
+      action_slug: action_config.action_slug || null,
+      payload: requestBody,
+      status: 'pending',
+      attempt_count: 0,
+      max_attempts: action_config.max_attempts ?? integration.config?.retry_policy?.max_attempts ?? 3,
+      next_attempt_at: null,
+      account_id: ctx.accountId,
+      created_at: new Date().toISOString(),
+      updated_at: new Date().toISOString()
+    }
+
+    const { data: deliveryRow, error: deliveryInsertError } = await adminDb
+      .from('webhook_deliveries')
+      .insert(deliveryPayload)
+      .select('id')
+      .single()
+
+    if (deliveryInsertError || !deliveryRow) {
+      throw new Error('Failed to create outbound delivery record')
+    }
+
+    deliveryId = deliveryRow.id
+  } else {
+    await adminDb
+      .from('webhook_deliveries')
+      .update({ status: 'processing', updated_at: new Date().toISOString() })
+      .eq('id', deliveryId)
+  }
+
+  await emitLog(ctx, 'integration.outbound.started', { type: 'integration', id: integration.id }, undefined, {
+    delivery_id: deliveryId,
+    integration_id: integration.id,
+    record_id,
+    account_id: ctx.accountId,
+    is_retry: isRetry
+  })
+
+  try {
+    const credentialField = action_config.credential_field || 'api_token'
+    const resolved = await resolveCredential(ctx, integration, credentialField)
+
+    const adapterName = action_config.adapter || integration.config?.outbound_adapter
+    if (!adapterName) {
+      throw new Error('No outbound adapter configured for integration ' + integration_slug)
+    }
+
+    const adapter = await loadOutboundAdapter(adapterName)
+    if (!adapter) {
+      throw new Error(`Outbound adapter not found: ${adapterName}`)
+    }
+
+    const adapterCtx: OutboundAdapterContext = {
+      record,
+      integration,
+      apiKey: resolved,
+      accountId: ctx.accountId,
+      appId: (ctx as any).appId || null,
+      actionConfig: action_config
+    }
+
+    const request: OutboundRequest = await adapter.buildRequest(record, adapterCtx)
+    if (!request.url || !request.method) {
+      throw new Error('Outbound adapter must return url and method')
+    }
+
+    const startMs = Date.now()
+    const response = await fetch(request.url, {
+      method: request.method,
+      headers: {
+        'Content-Type': 'application/json',
+        ...(request.headers || {})
+      },
+      body: request.body ? JSON.stringify(request.body) : undefined
+    })
+    const durationMs = Date.now() - startMs
+    const responseBodyText = await response.text()
+    let responseBody: any = null
+    try {
+      responseBody = JSON.parse(responseBodyText)
+    } catch {
+      responseBody = responseBodyText
+    }
+
+    const success = response.ok
+
+    const { data: currentDelivery } = await adminDb
+      .from('webhook_deliveries')
+      .select('attempt_count')
+      .eq('id', deliveryId)
+      .single()
+
+    const attemptCount = (currentDelivery?.attempt_count || 0) + 1
+
+    await adminDb
+      .from('webhook_deliveries')
+      .update({
+        status: success ? 'delivered' : (attemptCount >= (deliveryPayload?.max_attempts || 3) ? 'failed' : 'pending'),
+        attempt_count: attemptCount,
+        next_attempt_at: success ? null : computeNextAttempt(attemptCount).toISOString(),
+        response_status: response.status,
+        response_body: responseBody,
+        duration_ms: durationMs,
+        updated_at: new Date().toISOString()
+      })
+      .eq('id', deliveryId)
+
+    await emitLog(ctx, success ? 'integration.outbound.succeeded' : 'integration.outbound.failed_http', { type: 'integration', id: integration.id }, undefined, {
+      delivery_id: deliveryId,
+      integration_id: integration.id,
+      response_status: response.status,
+      duration_ms: durationMs,
+      account_id: ctx.accountId,
+      is_retry: isRetry
+    })
+
+    if (success && action_config.update_record && record_id) {
+      await adminDataUpdate({ ...ctx, query: { entity: 'items', id: record_id } } as any, {
+        entity: 'items',
+        id: record_id,
+        data: {
+          ...(action_config.update_fields || {}),
+          last_outbound_status: response.status,
+          last_outbound_at: new Date().toISOString()
+        }
+      })
+    }
+
+    if (!success) {
+      throw new Error(`Outbound HTTP ${request.method} to ${request.url} failed with status ${response.status}`)
+    }
+
+    return {
+      success: true,
+      delivery_id: deliveryId,
+      response_status: response.status,
+      response_body: responseBody,
+      is_retry: isRetry
+    }
+  } catch (err: any) {
+    const { data: currentDelivery } = await adminDb
+      .from('webhook_deliveries')
+      .select('attempt_count, max_attempts')
+      .eq('id', deliveryId)
+      .single()
+
+    const attemptCount = (currentDelivery?.attempt_count || 0) + 1
+    const shouldRetry = attemptCount < (currentDelivery?.max_attempts || 3)
+
+    await adminDb
+      .from('webhook_deliveries')
+      .update({
+        status: shouldRetry ? 'pending' : 'failed',
+        attempt_count: attemptCount,
+        next_attempt_at: shouldRetry ? computeNextAttempt(attemptCount).toISOString() : null,
+        last_error: err.message || String(err),
+        updated_at: new Date().toISOString()
+      })
+      .eq('id', deliveryId)
+
+    await emitLog(ctx, 'integration.outbound.error', { type: 'integration', id: integration.id }, undefined, {
+      delivery_id: deliveryId,
+      integration_id: integration.id,
+      error: err.message || String(err),
+      account_id: ctx.accountId,
+      is_retry: isRetry
+    })
+
+    throw err
+  }
+}
+
+const builtInOutboundAdapters: Record<string, any> = {
+  'adapters/openai-outbound': openaiOutbound,
+  'adapters/generic-webhook-outbound': genericWebhookOutbound
+}
+
+async function loadOutboundAdapter(functionName: string): Promise<any | null> {
+  if (builtInOutboundAdapters[functionName]) {
+    return builtInOutboundAdapters[functionName]
+  }
+  try {
+    const module = await import(`./${functionName}`)
+    return module.buildRequest ? module : null
+  } catch (err) {
+    console.error(`[integration-outbound] Failed to load adapter ${functionName}:`, err)
+    return null
+  }
+}
+
+const integrationOutbound = createHandler(execute)
+export default integrationOutbound
+
+// CIL[END chunk_id="integration_outbound_module_header_1784200004"]