spine-framework 0.3.118 → 0.3.120

package/.framework/functions/_shared/admin-data.ts

@@ -0,0 +1,298 @@
+/**
+ * @module admin-data-shared
+ * @audience both
+ * @layer api-handler
+ * @stability stable
+ *
+ * Shared runtime-record creation used by `admin-data.ts` and by system-level
+ * custom functions that must write runtime records (e.g. CIL links).
+ *
+ * Centralising the insert path guarantees that every runtime record gets a
+ * valid `type_id`, `account_id`, stamped schema, and audit fields.
+ */
+
+import { SupabaseClient } from '@supabase/supabase-js'
+import { adminDb } from './db'
+import { resolveTypeId } from './resolve-ids'
+import { fireCreateTriggers } from './trigger-engine'
+
+const PERMISSIONS_ALL = {
+  record_permissions: { all: ['create', 'read', 'update', 'delete'] },
+  fields: {}
+}
+
+const VALID_ENTITIES = ['accounts', 'people', 'items', 'threads', 'messages', 'links', 'attachments', 'watchers', 'item_progress']
+
+const ENTITY_TO_KIND: Record<string, string> = {
+  items: 'item',
+  threads: 'thread',
+  messages: 'message',
+  links: 'link',
+  attachments: 'attachment',
+  watchers: 'watcher',
+  item_progress: 'item_progress'
+}
+
+export interface CreateRecordOptions {
+  /** Supabase client to use for the insert (adminDb for system ops, ctx.db for user-scoped) */
+  db: SupabaseClient<any, 'public', any>
+  /** Target table */
+  entity: string
+  /** Type slug (e.g. 'link', 'cil_chunk'). Either this or typeId is required. */
+  typeSlug?: string
+  /** Type UUID. Either this or typeSlug is required. */
+  typeId?: string
+  /** Account UUID to stamp on the record. If omitted, inherited from parentRef or falls back to system account. */
+  accountId?: string | null
+  /** Principal ID to stamp as created_by */
+  createdBy?: string | null
+  /** Record fields to insert */
+  data: Record<string, any>
+  /** Optional parent reference for account/scope inheritance */
+  parentRef?: { id: string; table: 'items' | 'threads' }
+  /** If true, skip firing create triggers */
+  skipTriggers?: boolean
+}
+
+export interface CreateRecordResult {
+  id: string
+  record: any
+}
+
+/**
+ * Create a runtime record with full schema stamping and audit fields.
+ *
+ * This is the single shared path for writes to runtime tables. Callers choose
+ * the client (`adminDb` for system/cron operations, `ctx.db` for RLS-scoped
+ * user operations) and the helper handles the rest.
+ */
+export async function createRecord(options: CreateRecordOptions): Promise<CreateRecordResult> {
+  const { db, entity, typeSlug, typeId: explicitTypeId, accountId, createdBy, data: recordData, parentRef, skipTriggers } = options
+
+  if (!entity || !VALID_ENTITIES.includes(entity)) {
+    throw new Error(`Valid entity parameter is required: got ${entity}`)
+  }
+
+  let typeId = explicitTypeId
+  if (!typeId && typeSlug) {
+    const kind = ENTITY_TO_KIND[entity]
+    if (!kind) {
+      throw new Error(`type_slug is not supported for entity: ${entity}`)
+    }
+    typeId = await resolveTypeId(kind, typeSlug)
+  }
+
+  if (!typeId) {
+    throw new Error('type_id or type_slug is required — every runtime record must reference a type')
+  }
+
+  const { data: typeRecord, error: typeErr } = await adminDb
+    .from('types')
+    .select('id, design_schema, validation_schema, is_active')
+    .eq('id', typeId)
+    .single()
+
+  if (typeErr || !typeRecord) {
+    throw new Error(`type_id not found: ${typeId}`)
+  }
+
+  if (!typeRecord.is_active) {
+    throw new Error(`type_id references an inactive type: ${typeId}`)
+  }
+
+  let designSchema = typeRecord.design_schema || {}
+  if (!designSchema.record_permissions) {
+    designSchema = { ...PERMISSIONS_ALL, ...designSchema }
+  }
+
+  let recordAccountId = accountId ?? null
+  if (parentRef) {
+    const { data: parentRecord } = await db
+      .from(parentRef.table)
+      .select('account_id, design_schema')
+      .eq('id', parentRef.id)
+      .maybeSingle()
+    if (!parentRecord) {
+      throw new Error('Parent record not found or not accessible')
+    }
+    recordAccountId = parentRecord.account_id
+    const parentScope = parentRecord.design_schema?.scope
+    if (parentScope) {
+      designSchema = { ...designSchema, scope: parentScope }
+    }
+  }
+
+  const resolvedScope: string = designSchema.scope ?? 'account'
+  if (resolvedScope === 'platform') {
+    const { data: sysAccount } = await adminDb
+      .from('accounts')
+      .select('id')
+      .eq('slug', 'spine-system')
+      .single()
+    if (sysAccount?.id) recordAccountId = sysAccount.id
+  }
+
+  if (!recordAccountId) {
+    throw new Error('account_id is required — could not resolve from caller or parent')
+  }
+
+  const dataToInsert = {
+    ...recordData,
+    type_id: typeId,
+    design_schema: designSchema,
+    validation_schema: typeRecord.validation_schema || {},
+    created_by: createdBy ?? null,
+    account_id: recordAccountId,
+    created_at: new Date().toISOString(),
+    updated_at: new Date().toISOString()
+  }
+
+  const { data, error: err } = await db.from(entity)
+    .insert(dataToInsert)
+    .select()
+    .single()
+
+  if (err) throw err
+  if (!data) throw new Error('Insert succeeded but no record returned')
+
+  if (!skipTriggers) {
+    const entityData = { ...dataToInsert, id: data.id }
+    fireCreateTriggers(entity, data.id, entityData, {
+      principal: { id: createdBy || 'system', type: 'machine', accountId: recordAccountId, provenance: { sourceType: 'manual', createdBy: null, invokedAt: new Date().toISOString() } } as any,
+      accountId: recordAccountId,
+      db,
+      appId: null,
+      query: {},
+      path: ''
+    }).catch(console.error)
+  }
+
+  return { id: data.id, record: data }
+}
+
+export interface BatchRecord {
+  data: Record<string, any>
+  accountId?: string | null
+  parentRef?: { id: string; table: 'items' | 'threads' }
+}
+
+/**
+ * Batch create runtime records with shared schema stamping.
+ *
+ * Useful for system operations that create many links/items at once (e.g. CIL
+ * link extraction). The type is resolved once and applied to every row.
+ */
+export async function createRecords(options: {
+  db: SupabaseClient<any, 'public', any>
+  entity: string
+  typeSlug?: string
+  typeId?: string
+  records: BatchRecord[]
+  skipTriggers?: boolean
+}): Promise<CreateRecordResult[]> {
+  const { db, entity, typeSlug, typeId: explicitTypeId, records, skipTriggers } = options
+
+  if (!entity || !VALID_ENTITIES.includes(entity)) {
+    throw new Error(`Valid entity parameter is required: got ${entity}`)
+  }
+
+  let typeId = explicitTypeId
+  if (!typeId && typeSlug) {
+    const kind = ENTITY_TO_KIND[entity]
+    if (!kind) {
+      throw new Error(`type_slug is not supported for entity: ${entity}`)
+    }
+    typeId = await resolveTypeId(kind, typeSlug)
+  }
+
+  if (!typeId) {
+    throw new Error('type_id or type_slug is required — every runtime record must reference a type')
+  }
+
+  const { data: typeRecord, error: typeErr } = await adminDb
+    .from('types')
+    .select('id, design_schema, validation_schema, is_active')
+    .eq('id', typeId)
+    .single()
+
+  if (typeErr || !typeRecord) {
+    throw new Error(`type_id not found: ${typeId}`)
+  }
+
+  if (!typeRecord.is_active) {
+    throw new Error(`type_id references an inactive type: ${typeId}`)
+  }
+
+  let designSchema = typeRecord.design_schema || {}
+  if (!designSchema.record_permissions) {
+    designSchema = { ...PERMISSIONS_ALL, ...designSchema }
+  }
+
+  const validationSchema = typeRecord.validation_schema || {}
+  const now = new Date().toISOString()
+
+  const rows: any[] = []
+  for (const record of records) {
+    let recordAccountId = record.accountId ?? null
+    if (record.parentRef) {
+      const { data: parentRecord } = await db
+        .from(record.parentRef.table)
+        .select('account_id, design_schema')
+        .eq('id', record.parentRef.id)
+        .maybeSingle()
+      if (!parentRecord) {
+        throw new Error('Parent record not found or not accessible')
+      }
+      recordAccountId = parentRecord.account_id
+      const parentScope = parentRecord.design_schema?.scope
+      if (parentScope) {
+        designSchema = { ...designSchema, scope: parentScope }
+      }
+    }
+
+    const resolvedScope: string = designSchema.scope ?? 'account'
+    if (resolvedScope === 'platform') {
+      const { data: sysAccount } = await adminDb
+        .from('accounts')
+        .select('id')
+        .eq('slug', 'spine-system')
+        .single()
+      if (sysAccount?.id) recordAccountId = sysAccount.id
+    }
+
+    if (!recordAccountId) {
+      throw new Error('account_id is required — could not resolve from caller or parent')
+    }
+
+    rows.push({
+      ...record.data,
+      type_id: typeId,
+      design_schema: designSchema,
+      validation_schema: validationSchema,
+      created_by: null,
+      account_id: recordAccountId,
+      created_at: now,
+      updated_at: now
+    })
+  }
+
+  const { data, error } = await db.from(entity).insert(rows).select()
+  if (error) throw error
+  if (!data) throw new Error('Insert succeeded but no records returned')
+
+  if (!skipTriggers) {
+    for (const row of data) {
+      const entityData = { ...row, id: row.id }
+      fireCreateTriggers(entity, row.id, entityData, {
+        principal: { id: 'system', type: 'machine', accountId: row.account_id, provenance: { sourceType: 'manual', createdBy: null, invokedAt: now } } as any,
+        accountId: row.account_id,
+        db,
+        appId: null,
+        query: {},
+        path: ''
+      }).catch(console.error)
+    }
+  }
+
+  return data.map((row: any) => ({ id: row.id, record: row }))
+}

package/.framework/functions/admin-data.ts

@@ -46,6 +46,7 @@ import { createHandler } from './_shared/middleware'
 import { sanitizeRecordData } from './_shared/permissions'
 import { adminDb } from './_shared/db'
 import { resolveTypeId } from './_shared/resolve-ids'
+import { createRecord } from './_shared/admin-data'
 import { fireCreateTriggers, fireUpdateTriggers, fireDeleteTriggers } from './_shared/trigger-engine'
 // ─── CHUNK_END: ADMIN_DATA_OVERVIEW ──────────────────────────────────────────────
 
@@ -309,89 +310,22 @@ export const create = createHandler(async (ctx, body) => {
     typeId = await resolveTypeId(kind, body.type_slug)
   }
 
-  // type_id is required on all runtime record creation
-  if (!typeId) {
-    const e: any = new Error('type_id or type_slug is required — every runtime record must reference a type'); e.statusCode = 400; throw e
-  }
-  recordData.type_id = typeId
-
-  // Look up the type to stamp design_schema and validation_schema
-  const { data: typeRecord, error: typeErr } = await adminDb
-    .from('types')
-    .select('id, design_schema, validation_schema, is_active')
-    .eq('id', typeId)
-    .single()
-
-  if (typeErr || !typeRecord) {
-    throw new Error(`type_id not found: ${typeId}`)
-  }
-
-  if (!typeRecord.is_active) {
-    throw new Error(`type_id references an inactive type: ${typeId}`)
-  }
-
-  // Ensure the type has at least permissions=ALL (defensive — migration 062 guarantees this)
-  let designSchema = typeRecord.design_schema || {}
-  if (!designSchema.record_permissions) {
-    designSchema = { ...PERMISSIONS_ALL, ...designSchema }
-  }
-
-  // Resolve account_id and propagate scope via parent inheritance.
-  // Runtime records are the source of truth: the parent record's stamped scope
-  // and account_id are inherited, not re-looked up from the type table.
-  let recordAccountId = ctx.accountId
   const parentRef = recordData.thread_id || recordData.target_id || recordData.parent_id
-  if (parentRef) {
-    const parentTable = recordData.thread_id ? 'threads' : 'items'
-    const { data: parentRecord } = await ctx.db
-      .from(parentTable)
-      .select('account_id, design_schema')
-      .eq('id', parentRef)
-      .maybeSingle()
-    if (!parentRecord) {
-      const e: any = new Error('Parent record not found or not accessible'); e.statusCode = 403; throw e
-    }
-    recordAccountId = parentRecord.account_id
-    const parentScope = parentRecord.design_schema?.scope
-    if (parentScope) {
-      designSchema = { ...designSchema, scope: parentScope }
-    }
-  }
-
-  // Platform-scoped records belong to the system account so they are visible
-  // across all accounts. Child records already inherited the parent's scope above.
-  const resolvedScope: string = designSchema.scope ?? 'account'
-  if (resolvedScope === 'platform') {
-    const { data: sysAccount } = await adminDb
-      .from('accounts')
-      .select('id')
-      .eq('slug', 'spine-system')
-      .single()
-    if (sysAccount?.id) recordAccountId = sysAccount.id
-  }
-
-  // Add audit fields + stamped schema
-  const dataToInsert = {
-    ...recordData,
-    design_schema:     designSchema,
-    validation_schema: typeRecord.validation_schema || {},
-    created_by: ctx.principal?.id,
-    account_id: recordAccountId,
-    created_at: new Date().toISOString(),
-    updated_at: new Date().toISOString()
-  }
-
-  // RLS will check if user has INSERT permission on this account
-  const { data, error: err } = await ctx.db.from(entity)
-    .insert(dataToInsert)
-    .select()
-    .single()
-
-  if (err) throw err
-
-  // Fire triggers asynchronously (don't block response)
-  const entityData = { ...dataToInsert, id: data.id }
-  fireCreateTriggers(entity, data.id, entityData, ctx).catch(console.error)
+  const parentRefObj = parentRef
+    ? { id: parentRef, table: (recordData.thread_id ? 'threads' : 'items') as 'items' | 'threads' }
+    : undefined
+
+  const { record: data } = await createRecord({
+    db: ctx.db,
+    entity,
+    typeId,
+    typeSlug: body?.type_slug,
+    accountId: ctx.accountId,
+    createdBy: ctx.principal?.id,
+    data: recordData,
+    parentRef: parentRefObj,
+    skipTriggers: false
+  })
 
   return await sanitizeRecordData(ctx, data, entity)
 })

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spine-framework",
-  "version": "0.3.118",
+  "version": "0.3.120",
   "description": "Multi-tenant, modular application platform for modern SaaS systems",
   "type": "module",
   "bin": {