spine-framework 0.3.124 → 0.3.126

package/.framework/functions/integrations.ts

@@ -1,59 +1,55 @@
-/**
- * @module integrations
- * @audience core-contributor
- * @layer api-handler
- * @stability stable
- *
- * CRUD API for the `integrations` table. Integration records describe
- * third-party service connections (API credentials, provider, version,
- * configuration). Each integration is scoped to an account and optionally
- * to an app. `is_configured` tracks whether credentials have been set.
- *
- * **Routed by:** `GET/POST/PATCH/DELETE /.netlify/functions/integrations`
- *
- * **Standard CRUD — routes directly by HTTP method (no ?action switch):**
- * | method | condition | handler |
- * |--------|-----------|---------|
- * | GET    | ?id       | get     |
- * | GET    | (default) | list    |
- * | POST   | —         | create  |
- * | PATCH  | —         | update  |
- * | DELETE | —         | remove (soft) |
- *
- * **Authorization:** All operations use `ctx.db` (RLS-scoped). Authenticated
- * principal required for writes.
- *
- * INVARIANT: `remove` is a soft delete (sets `is_active = false`). Hard deletes
- *   are not supported to preserve audit trails on integration-linked data.
- * INVARIANT: `update` only patches the explicit allowlist of fields.
- *
- * @seeAlso api-keys.ts (api_keys belong to integrations)
- * @seeAlso trigger-engine.ts (integration webhooks trigger pipelines)
- * @seeAlso audit.ts (emitLog for integration.* events)
- */
 
+
+
+
+
+
+// CIL[BEGIN chunk_id="integrations_moduleheader_1783968140" type="module_header" identity="imports" parent="none"]
+// CIL[DOC-MACRO purpose="Import dependencies for integration CRUD API"]
+// CIL[DOC-RESPONSIBILITY responsibility="Import handler utilities and database access"]
+// CIL[DOC-CONTEXT module="integrations" layer="api-handler" related_files="[\".framework/src/pages/admin/IntegrationsPage.tsx\",\"custom/apps/cortex/pages/operations/OperationsDashboard.tsx\",\".framework/src/pages/admin/TypeDetailPage.tsx\",\".framework/functions/_shared/principal.ts\",\".framework/functions/_shared/schema-utils.ts\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="Imported modules" errors="Import failures" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Imports createHandler, joins, emitLog, sanitizeRecordData" 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: .framework/src/pages/admin/IntegrationsPage.tsx, custom/apps/cortex/pages/operations/OperationsDashboard.tsx, .framework/src/pages/admin/TypeDetailPage.tsx, .framework/functions/_shared/principal.ts, .framework/functions/_shared/schema-utils.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"]
 import { createHandler } from './_shared/middleware'
 import { joins } from './_shared/db'
 import { emitLog } from './_shared/audit'
 import { sanitizeRecordData } from './_shared/permissions'
 
-// ─── HANDLERS ─────────────────────────────────────────────────────────────────
-
-// ─── CHUNK_START: INTEGRATIONS_LIST ──────────────────────────────────────────────
-/**
- * @chunk-id    INTEGRATIONS_LIST_1_0_0
- * @version     1.0.0
- * @hash        5faf0b7052d9aac5f764d1fc30ddde1485a0296ad2b209cd2e3a73c09061a1fc
- * @macro       Integrations List Handler
- * @micro       Lists integrations with filtering, pagination, and joins
- * @inputs      ctx: CoreContext — Request context with principal and database
- * @inputs      _body: any — Request body (unused for GET)
- * @outputs     Array of sanitized integration records with app/createdBy joins
- * @depends-on  [createHandler, joins, sanitizeRecordData]
- * @depended-by [Netlify function routing]
- * @side-effects [DB queries, permission sanitization]
- * @tags        integrations, list, crud, pagination
- */
+function deriveSlug(name: string, slug?: string): string {
+  return slug || name.toLowerCase().replace(/\s+/g, '-').replace(/[^a-z0-9-]/g, '')
+}
+
+function computeIsConfigured(credentials: Record<string, any> | undefined): boolean {
+  if (!credentials || Object.keys(credentials).length === 0) return false
+  return Object.values(credentials).every((entry: any) => {
+    if (!entry || !entry.source) return false
+    return typeof entry.value === 'string' && entry.value.length > 0
+  })
+}
+// CIL[END chunk_id="integrations_moduleheader_1783968140"]
+// CIL[BEGIN chunk_id="integrations_list_1783968140" type="function" identity="list" parent="none"]
+// CIL[DOC-MACRO purpose="List integrations with filtering and permission sanitization"]
+// CIL[DOC-RESPONSIBILITY responsibility="Query and return sanitized integration records"]
+// CIL[DOC-CONTEXT module="integrations" layer="api-handler" related_files="[\"custom/apps/portal/pages/ContentPage.tsx\",\".framework/src/pages/admin/IntegrationsPage.tsx\",\".framework/functions/_shared/principal.ts\",\"custom/apps/cortex/pages/operations/OperationsDashboard.tsx\",\".framework/src/components/ui/dialog.tsx\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="Array of sanitized integration records" errors="Account context required, DB errors" side_effects="DB read operations"]
+// CIL[DOC-MICRO logic_summary="Builds filtered query with joins, sanitizes each result before returning" 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, .framework/src/pages/admin/IntegrationsPage.tsx, .framework/functions/_shared/principal.ts, custom/apps/cortex/pages/operations/OperationsDashboard.tsx, .framework/src/components/ui/dialog.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"]
 export const list = createHandler(async (ctx, _body) => {
   const { integration_type, provider, is_active, is_configured, limit = 100, offset = 0 } = ctx.query || {}
 
@@ -93,23 +89,21 @@ export const list = createHandler(async (ctx, _body) => {
 
   return sanitized
 })
-// ─── CHUNK_END: INTEGRATIONS_LIST ────────────────────────────────────────────────
-
-// ─── CHUNK_START: INTEGRATIONS_GET ──────────────────────────────────────────────
-/**
- * @chunk-id    INTEGRATIONS_GET_1_0_0
- * @version     1.0.0
- * @hash        975126629cff24c75d2b74328d1ae08dd033ed451d3820d828c62b1f7a27413e
- * @macro       Integration Get Handler
- * @micro       Returns single integration record with joins and sanitization
- * @inputs      ctx: CoreContext — Request context with principal and database
- * @inputs      _body: any — Request body (unused for GET)
- * @outputs     Sanitized integration record with app/createdBy joins
- * @depends-on  [createHandler, joins, sanitizeRecordData]
- * @depended-by [Netlify function routing]
- * @side-effects [DB single row query, permission sanitization]
- * @tags        integrations, get, crud, single-record
- */
+// CIL[END chunk_id="integrations_list_1783968140"]
+// CIL[BEGIN chunk_id="integrations_get_1783968140" type="function" identity="get" parent="none"]
+// CIL[DOC-MACRO purpose="Get single integration record with joins and sanitization"]
+// CIL[DOC-RESPONSIBILITY responsibility="Retrieve and sanitize individual integration"]
+// CIL[DOC-CONTEXT module="integrations" layer="api-handler" related_files="[\".framework/src/pages/admin/IntegrationsPage.tsx\",\"custom/apps/portal/pages/ContentPage.tsx\",\".framework/src/pages/admin/TypeDetailPage.tsx\",\".framework/src/pages/admin/RolesPage.tsx\",\"custom/apps/cortex/pages/operations/OperationsDashboard.tsx\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="Sanitized integration record" errors="Integration ID required, not found, DB errors" side_effects="DB read operation"]
+// CIL[DOC-MICRO logic_summary="Queries by ID with joins, sanitizes result before returning" 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: .framework/src/pages/admin/IntegrationsPage.tsx, custom/apps/portal/pages/ContentPage.tsx, .framework/src/pages/admin/TypeDetailPage.tsx, .framework/src/pages/admin/RolesPage.tsx, custom/apps/cortex/pages/operations/OperationsDashboard.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"]
 export const get = createHandler(async (ctx, _body) => {
   const { id } = ctx.query || {}
 
@@ -127,23 +121,21 @@ export const get = createHandler(async (ctx, _body) => {
 
   return await sanitizeRecordData(ctx, data, 'integration')
 })
-// ─── CHUNK_END: INTEGRATIONS_GET ────────────────────────────────────────────────
-
-// ─── CHUNK_START: INTEGRATIONS_CREATE ──────────────────────────────────────────────
-/**
- * @chunk-id    INTEGRATIONS_CREATE_1_0_0
- * @version     1.0.0
- * @hash        27d2242703930d7eeb33b49bbce4c22681ab891750c4c7a298c1c717a39870d7
- * @macro       Integration Create Handler
- * @micro       Creates integration record with validation and audit logging
- * @inputs      ctx: CoreContext — Request context with principal and database
- * @inputs      body: object — Integration data including name, integration_type, provider
- * @outputs     Inserted integration record
- * @depends-on  [createHandler, emitLog]
- * @depended-by [Netlify function routing]
- * @side-effects [DB insert, audit logging]
- * @tags        integrations, create, crud, audit
- */
+// CIL[END chunk_id="integrations_get_1783968140"]
+// CIL[BEGIN chunk_id="integrations_create_1783968140" type="function" identity="create" parent="none"]
+// CIL[DOC-MACRO purpose="Create new integration record with validation and audit logging"]
+// CIL[DOC-RESPONSIBILITY responsibility="Insert new integration with proper metadata"]
+// CIL[DOC-CONTEXT module="integrations" layer="api-handler" related_files="[\".framework/src/pages/admin/IntegrationsPage.tsx\",\".framework/functions/_shared/schema-utils.ts\",\".framework/src/pages/admin/TypeDetailPage.tsx\",\"custom/apps/portal/pages/ContentPage.tsx\",\".framework/src/components/ui/dialog.tsx\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="Created integration record" errors="Required fields missing, auth required, DB errors" side_effects="DB insert, audit logging"]
+// CIL[DOC-MICRO logic_summary="Validates required fields, creates integration record, logs creation" 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: .framework/src/pages/admin/IntegrationsPage.tsx, .framework/functions/_shared/schema-utils.ts, .framework/src/pages/admin/TypeDetailPage.tsx, custom/apps/portal/pages/ContentPage.tsx, .framework/src/components/ui/dialog.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"]
 export const create = createHandler(async (ctx, body) => {
   const { app_id, name, description, integration_type, provider, version, config, credentials, metadata } = body
 
@@ -155,19 +147,23 @@ export const create = createHandler(async (ctx, body) => {
     throw new Error('User context (person and account) required')
   }
 
+  const safeCredentials = credentials || {}
+
   const { data, error: err } = await ctx.db
     .from('integrations')
     .insert({
       app_id: app_id || null,
       account_id: ctx.accountId,
+      slug: deriveSlug(name, body.slug),
       name,
       description: description || null,
       integration_type,
       provider,
       version: version || '1.0.0',
       config: config || {},
-      credentials: credentials || {},
+      credentials: safeCredentials,
       metadata: metadata || {},
+      is_configured: computeIsConfigured(safeCredentials),
       created_by: ctx.principal.id
     })
     .select()
@@ -182,23 +178,21 @@ export const create = createHandler(async (ctx, body) => {
 
   return data
 })
-// ─── CHUNK_END: INTEGRATIONS_CREATE ────────────────────────────────────────────────
-
-// ─── CHUNK_START: INTEGRATIONS_UPDATE ──────────────────────────────────────────────
-/**
- * @chunk-id    INTEGRATIONS_UPDATE_1_0_0
- * @version     1.0.0
- * @hash        ab5c8404ddec24ff912c55e7e52cd0ecdd220646b0e07f56a49a02ef3288f3e9
- * @macro       Integration Update Handler
- * @micro       Updates integration with field allowlist and audit logging
- * @inputs      ctx: CoreContext — Request context with principal and database
- * @inputs      body: object — Integration updates including id
- * @outputs     Updated integration record
- * @depends-on  [createHandler, emitLog]
- * @depended-by [Netlify function routing]
- * @side-effects [DB update, audit logging]
- * @tags        integrations, update, crud, audit
- */
+// CIL[END chunk_id="integrations_create_1783968140"]
+// CIL[BEGIN chunk_id="integrations_update_1783968140" type="function" identity="update" parent="none"]
+// CIL[DOC-MACRO purpose="Update integration with field allowlist and audit logging"]
+// CIL[DOC-RESPONSIBILITY responsibility="Modify integration records safely"]
+// CIL[DOC-CONTEXT module="integrations" layer="api-handler" related_files="[\".framework/src/pages/admin/IntegrationsPage.tsx\",\"custom/apps/portal/pages/ContentPage.tsx\",\".framework/functions/_shared/schema-utils.ts\",\".framework/functions/_shared/db.ts\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="Updated integration record" errors="Integration ID required, DB errors" side_effects="DB update, audit logging"]
+// CIL[DOC-MICRO logic_summary="Updates only allowed fields, logs changes, returns updated record" 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: .framework/src/pages/admin/IntegrationsPage.tsx, custom/apps/portal/pages/ContentPage.tsx, .framework/functions/_shared/schema-utils.ts, .framework/functions/_shared/db.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 update = createHandler(async (ctx, body) => {
   const id = body?.id || ctx.query?.id
   const { id: _bodyId, ...updates } = body || {}
@@ -207,12 +201,16 @@ export const update = createHandler(async (ctx, body) => {
     throw new Error('Integration ID is required')
   }
 
-  const allowed = ['name', 'description', 'integration_type', 'provider', 'version', 'config', 'credentials', 'metadata', 'is_active', 'is_configured']
+  const allowed = ['name', 'slug', 'description', 'integration_type', 'provider', 'version', 'config', 'credentials', 'metadata', 'is_active']
   const updateData: Record<string, any> = { updated_at: new Date().toISOString() }
   for (const key of allowed) {
     if (updates[key] !== undefined) updateData[key] = updates[key]
   }
 
+  if (updateData.credentials !== undefined) {
+    updateData.is_configured = computeIsConfigured(updateData.credentials)
+  }
+
   const { data, error: err } = await ctx.db
     .from('integrations')
     .update(updateData)
@@ -229,23 +227,21 @@ export const update = createHandler(async (ctx, body) => {
 
   return data
 })
-// ─── CHUNK_END: INTEGRATIONS_UPDATE ────────────────────────────────────────────────
-
-// ─── CHUNK_START: INTEGRATIONS_REMOVE ──────────────────────────────────────────────
-/**
- * @chunk-id    INTEGRATIONS_REMOVE_1_0_0
- * @version     1.0.0
- * @hash        a8b5f084d745d2ce69a1e29d74903832ed39647ccb779d0f651a99157777a08a
- * @macro       Integration Remove Handler
- * @micro       Soft-deletes integration with validation and audit logging
- * @inputs      ctx: CoreContext — Request context with principal and database
- * @inputs      _body: any — Request body (unused for DELETE)
- * @outputs     Updated integration record with is_active: false
- * @depends-on  [createHandler, emitLog]
- * @depended-by [Netlify function routing]
- * @side-effects [DB soft delete, audit logging]
- * @tags        integrations, remove, crud, audit
- */
+// CIL[END chunk_id="integrations_update_1783968140"]
+// CIL[BEGIN chunk_id="integrations_remove_1783968140" type="function" identity="remove" parent="none"]
+// CIL[DOC-MACRO purpose="Soft-delete integration by setting is_active to false"]
+// CIL[DOC-RESPONSIBILITY responsibility="Deactivate integration records while preserving audit trail"]
+// CIL[DOC-CONTEXT module="integrations" layer="api-handler" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="Updated integration record" errors="Integration ID required, not found, DB errors" side_effects="DB soft delete, audit logging"]
+// CIL[DOC-MICRO logic_summary="Sets is_active false, logs deletion, preserves record for audit" 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: none."]
+// 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 remove = createHandler(async (ctx, _body) => {
   const id = ctx.query?.id
 
@@ -277,25 +273,21 @@ export const remove = createHandler(async (ctx, _body) => {
 
   return data
 })
-// ─── CHUNK_END: INTEGRATIONS_REMOVE ────────────────────────────────────────────────
-
-// ─── MAIN HANDLER ────────────────────────────────────────────────────────────
-
-// ─── CHUNK_START: INTEGRATIONS_HANDLER ──────────────────────────────────────────────
-/**
- * @chunk-id    INTEGRATIONS_HANDLER_1_0_0
- * @version     1.0.0
- * @hash        14c00f276a22287ed65c019efe327cbb513f860a408191e299864b05c641833c
- * @macro       Integrations Router
- * @micro       Routes HTTP methods to appropriate handlers (no action switch)
- * @inputs      ctx: CoreContext — Request context with principal and database
- * @inputs      body: any — Request body for POST/PATCH operations
- * @outputs     Varies — Depends on routed handler (list/get/create/update/remove)
- * @depends-on  [createHandler, list, get, create, update, remove]
- * @depended-by [Netlify function routing]
- * @side-effects [Delegates to appropriate handler]
- * @tags        integrations, router, crud, netlify-function
- */
+// CIL[END chunk_id="integrations_remove_1783968140"]
+// CIL[BEGIN chunk_id="integrations_handler_1783968140" type="function" identity="handler" parent="none"]
+// CIL[DOC-MACRO purpose="Route HTTP methods to appropriate integration handlers"]
+// CIL[DOC-RESPONSIBILITY responsibility="Dispatch CRUD requests to correct handler functions"]
+// CIL[DOC-CONTEXT module="integrations" layer="api-handler" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="Varies by method" errors="Unsupported method" side_effects="Delegates to handlers"]
+// CIL[DOC-MICRO logic_summary="Switch statement routes GET/POST/PATCH/DELETE to appropriate handlers" 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: none."]
+// 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 method = ctx.query?.method || 'GET'
 
@@ -316,4 +308,4 @@ export const handler = createHandler(async (ctx, body) => {
       throw new Error(`Unsupported method: ${method}`)
   }
 })
-// ─── CHUNK_END: INTEGRATIONS_HANDLER ────────────────────────────────────────────────
+// CIL[END chunk_id="integrations_handler_1783968140"]