spine-framework 0.3.113 → 0.3.114

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

@@ -1,3 +1,4 @@
+// ─── CHUNK_START: ADMIN_DATA_OVERVIEW ──────────────────────────────────────────────
 /**
  * @module admin-data
  * @audience both
@@ -46,8 +47,38 @@ import { sanitizeRecordData } from './_shared/permissions'
 import { adminDb } from './_shared/db'
 import { resolveTypeId } from './_shared/resolve-ids'
 import { fireCreateTriggers, fireUpdateTriggers, fireDeleteTriggers } from './_shared/trigger-engine'
+// ─── CHUNK_END: ADMIN_DATA_OVERVIEW ──────────────────────────────────────────────
 
-// ─── CONSTANTS ────────────────────────────────────────────────────────────────
+// ─── CHUNK_START: ADMIN_DATA_MODULE_HEADER ──────────────────────────────────────────────
+/**
+ * @chunk-id    ADMIN_DATA_MODULE_HEADER_1_0_0
+ * @version     1.0.0
+ * @hash        TBD
+ * @macro       Module Header
+ * @micro       Module-level documentation with routing table and invariants
+ * @inputs      none
+ * @outputs     none
+ * @depends-on  [none]
+ * @depended-by [all chunks]
+ * @side-effects [none]
+ * @tags        admin, module, routing, invariants
+ */
+// ─── CHUNK_END: ADMIN_DATA_MODULE_HEADER ────────────────────────────────────────────────
+
+// ─── CHUNK_START: ADMIN_DATA_IMPORTS_AND_CONSTANTS ──────────────────────────────────────────────
+/**
+ * @chunk-id    ADMIN_DATA_IMPORTS_AND_CONSTANTS_1_0_0
+ * @version     1.0.0
+ * @hash        TBD
+ * @macro       Imports and Constants
+ * @micro       Module imports and constant definitions
+ * @inputs      none
+ * @outputs     none
+ * @depends-on  [none]
+ * @depended-by [all handlers]
+ * @side-effects [none]
+ * @tags        admin, imports, constants
+ */
 
 const PERMISSIONS_ALL = {
   record_permissions: { all: ['create', 'read', 'update', 'delete'] },
@@ -70,8 +101,23 @@ const ENTITY_TO_KIND: Record<string, string> = {
   watchers: 'watcher',
   item_progress: 'item_progress'
 }
+// ─── CHUNK_END: ADMIN_DATA_IMPORTS_AND_CONSTANTS ────────────────────────────────────────────────
 
-// ─── HANDLERS ─────────────────────────────────────────────────────────────────
+// ─── CHUNK_START: ADMIN_DATA_HANDLERS_SECTION ──────────────────────────────────────────────
+/**
+ * @chunk-id    ADMIN_DATA_HANDLERS_SECTION_1_0_0
+ * @version     1.0.0
+ * @hash        TBD
+ * @macro       Handlers Section Header
+ * @micro       Section marker for CRUD handler functions
+ * @inputs      none
+ * @outputs     none
+ * @depends-on  [none]
+ * @depended-by [none]
+ * @side-effects [none]
+ * @tags        admin, section, handlers
+ */
+// ─── CHUNK_END: ADMIN_DATA_HANDLERS_SECTION ────────────────────────────────────────────────
 
 // ─── CHUNK_START: ADMIN_DATA_LIST ──────────────────────────────────────────────
 /**
@@ -230,32 +276,20 @@ export const get = createHandler(async (ctx, _body) => {
 })
 // ─── CHUNK_END: ADMIN_DATA_GET ────────────────────────────────────────────────
 
+// ─── CHUNK_START: ADMIN_DATA_CREATE ──────────────────────────────────────────────
 /**
- * Creates a new record for an entity. Stamps `design_schema`,
- * `validation_schema`, audit fields, and `account_id` from the resolved type.
- * Fires `*_created` triggers asynchronously after DB insert.
- *
- * Body params:
- *   - `entity` (required) — one of VALID_ENTITIES
- *   - `type_id` (required) — UUID of an active type record
- *   - all other fields are passed through to the insert
- *
- * @returns Sanitized created record
- * @throws Error('Valid entity parameter is required')
- * @throws Error('type_id is required')
- * @throws Error('type_id not found') — if type UUID doesn't exist
- * @throws Error('type_id references an inactive type')
- * @throws PostgREST error on RLS INSERT denial
- * @inputSpec type_id: string — valid UUID of active type record
- * @inputSpec body fields: Record<string, any> — record field values
- * @outputSpec sanitized created record
- * @sideEffects DB write: entity table (INSERT)
- * @sideEffects DB read: types table (type resolution)
- * @sideEffects fire-and-forget: fireCreateTriggers
- * @calledBy handler (POST)
- * @calls sanitizeRecordData, adminDb (type lookup), fireCreateTriggers
- * @testUnit tests/unit/admin-data.test.ts — 'create'
- * @testIntegration tests/integration/admin-data.test.ts — 'create'
+ * @chunk-id    ADMIN_DATA_CREATE_1_0_0
+ * @version     1.0.0
+ * @hash        TBD
+ * @macro       Entity Create Handler
+ * @micro       Creates a new record for an entity with type resolution and triggers
+ * @inputs      ctx: CoreContext — Request context with principal and database
+ * @inputs      body: any — Request body with entity, type_id/type_slug, and record fields
+ * @outputs     Sanitized created record
+ * @depends-on  [createHandler, sanitizeRecordData, adminDb, resolveTypeId, fireCreateTriggers]
+ * @depended-by [Netlify function routing]
+ * @side-effects [DB write, type lookup, async trigger fire]
+ * @tags        admin, crud, create, type-resolution
  */
 export const create = createHandler(async (ctx, body) => {
   const entity = body?.entity || ctx.query?.entity
@@ -361,31 +395,27 @@ export const create = createHandler(async (ctx, body) => {
 
   return await sanitizeRecordData(ctx, data, entity)
 })
+// ─── CHUNK_END: ADMIN_DATA_CREATE ────────────────────────────────────────────────
 
+// ─── CHUNK_START: ADMIN_DATA_UPDATE ──────────────────────────────────────────────
 /**
- * Updates an existing record by ID. Stamps `updated_by` and `updated_at`.
- * Fires `*_updated` triggers asynchronously after DB update.
- *
- * Query params: `entity` (required), `id` (required)
- * Body: partial record fields to update (no schema re-stamping on update)
- *
- * @returns Sanitized updated record
- * @throws Error('Valid entity parameter is required')
- * @throws Error('ID is required for update')
- * @throws PostgREST error on RLS UPDATE denial
- * @inputSpec id: string — valid UUID of existing record
- * @inputSpec body: Partial<Record> — fields to patch
- * @outputSpec sanitized updated record
- * @sideEffects DB write: entity table (UPDATE)
- * @sideEffects fire-and-forget: fireUpdateTriggers
- * @calledBy handler (PATCH)
- * @calls sanitizeRecordData, fireUpdateTriggers
- * @testUnit tests/unit/admin-data.test.ts — 'update'
+ * @chunk-id    ADMIN_DATA_UPDATE_1_0_0
+ * @version     1.0.0
+ * @hash        TBD
+ * @macro       Entity Update Handler
+ * @micro       Updates an existing record by ID with audit fields and triggers
+ * @inputs      ctx: CoreContext — Request context with principal and database
+ * @inputs      body: any — Request body with partial record fields to update
+ * @outputs     Sanitized updated record
+ * @depends-on  [createHandler, sanitizeRecordData, fireUpdateTriggers]
+ * @depended-by [Netlify function routing]
+ * @side-effects [DB write, async trigger fire]
+ * @tags        admin, crud, update
  */
 export const update = createHandler(async (ctx, body) => {
   const { entity, id } = ctx.query || {}
   // Strip server-only fields — client must never override these on update
-  const { design_schema: _ds, validation_schema: _vs, account_id: _ai, type_id: _ti, ...recordData } = body || {}
+  const { design_schema: _ds, validation_schema: _vs, account_id: _ai, type_id: _ti, type_slug: _ts, ...recordData } = body || {}
 
   if (!entity || !VALID_ENTITIES.includes(entity)) {
     throw new Error('Valid entity parameter is required')
@@ -417,31 +447,22 @@ export const update = createHandler(async (ctx, body) => {
 
   return await sanitizeRecordData(ctx, data, entity)
 })
+// ─── CHUNK_END: ADMIN_DATA_UPDATE ────────────────────────────────────────────────
 
+// ─── CHUNK_START: ADMIN_DATA_REMOVE ──────────────────────────────────────────────
 /**
- * Deletes a record by ID. Defaults to soft delete (`is_active = false`) for
- * entities that support it; falls back to hard delete otherwise.
- *
- * Query params:
- *   - `entity` (required) — one of VALID_ENTITIES
- *   - `id` (required) — UUID of the record
- *   - `soft` (default: 'true') — set to 'false' to force hard delete
- *
- * Soft-delete-capable entities: `accounts`, `people`, `items`, `threads`,
- * `messages`, `watchers`. All others always receive a hard delete.
- *
- * @returns `{ deleted: true, soft: true, data }` (soft) or `{ deleted: true, soft: false }` (hard)
- * @throws Error('Valid entity parameter is required')
- * @throws Error('ID is required for delete')
- * @throws PostgREST error on RLS DELETE denial
- * @inputSpec id: string — valid UUID
- * @inputSpec soft: 'true' | 'false'
- * @outputSpec { deleted: boolean, soft: boolean, data?: sanitizedRecord }
- * @sideEffects DB write: UPDATE is_active=false (soft) or DELETE (hard)
- * @sideEffects fire-and-forget: fireDeleteTriggers
- * @calledBy handler (DELETE)
- * @calls sanitizeRecordData, entitySupportsSoftDelete, fireDeleteTriggers
- * @testUnit tests/unit/admin-data.test.ts — 'remove'
+ * @chunk-id    ADMIN_DATA_REMOVE_1_0_0
+ * @version     1.0.0
+ * @hash        TBD
+ * @macro       Entity Delete Handler
+ * @micro       Deletes a record by ID with soft delete support and triggers
+ * @inputs      ctx: CoreContext — Request context with principal and database
+ * @inputs      _body: any — Request body (unused for DELETE)
+ * @outputs     { deleted: boolean, soft: boolean, data?: sanitizedRecord }
+ * @depends-on  [createHandler, sanitizeRecordData, entitySupportsSoftDelete, fireDeleteTriggers]
+ * @depended-by [Netlify function routing]
+ * @side-effects [DB write, async trigger fire]
+ * @tags        admin, crud, delete, soft-delete
  */
 export const remove = createHandler(async (ctx, _body) => {
   const { entity, id, soft = 'true' } = ctx.query || {}
@@ -482,15 +503,24 @@ export const remove = createHandler(async (ctx, _body) => {
     return { deleted: true, soft: false }
   }
 })
+// ─── CHUNK_END: ADMIN_DATA_REMOVE ────────────────────────────────────────────────
 
-// ─── HELPERS ─────────────────────────────────────────────────────────────────
-
+// ─── CHUNK_START: ADMIN_DATA_HELPERS_SECTION ──────────────────────────────────────────────
 /**
- * Returns the primary text field to use for `ilike` search for a given entity.
- * Falls back to 'id' for unmapped entities.
- *
- * @calledBy list (search param handling)
+ * @chunk-id    ADMIN_DATA_HELPERS_SECTION_1_0_0
+ * @version     1.0.0
+ * @hash        TBD
+ * @macro       Helpers Section Header
+ * @micro       Section marker for helper functions
+ * @inputs      none
+ * @outputs     none
+ * @depends-on  [none]
+ * @depended-by [none]
+ * @side-effects [none]
+ * @tags        admin, section, helpers
  */
+// ─── CHUNK_END: ADMIN_DATA_HELPERS_SECTION ────────────────────────────────────────────────
+
 // ─── CHUNK_START: ADMIN_DATA_GET_SEARCH_FIELD ──────────────────────────────────────────────
 /**
  * @chunk-id    ADMIN_DATA_GET_SEARCH_FIELD_1_0_0
@@ -573,7 +603,21 @@ export const stats = createHandler(async (ctx, _body) => {
 })
 // ─── CHUNK_END: ADMIN_DATA_STATS ────────────────────────────────────────────────
 
-// ─── MAIN HANDLER ────────────────────────────────────────────────────────────
+// ─── CHUNK_START: ADMIN_DATA_MAIN_HANDLER_SECTION ──────────────────────────────────────────────
+/**
+ * @chunk-id    ADMIN_DATA_MAIN_HANDLER_SECTION_1_0_0
+ * @version     1.0.0
+ * @hash        TBD
+ * @macro       Main Handler Section Header
+ * @micro       Section marker for the main router handler
+ * @inputs      none
+ * @outputs     none
+ * @depends-on  [none]
+ * @depended-by [none]
+ * @side-effects [none]
+ * @tags        admin, section, main-handler
+ */
+// ─── CHUNK_END: ADMIN_DATA_MAIN_HANDLER_SECTION ────────────────────────────────────────────────
 
 // ─── CHUNK_START: ADMIN_DATA_HANDLER ──────────────────────────────────────────────
 /**
@@ -626,4 +670,4 @@ export const handler = createHandler(async (ctx, body) => {
 
   throw new Error('Invalid action or method')
 })
-// ─── CHUNK_END: ADMIN_DATA_HANDLER ────────────────────────────────────────────────
+// ─── CHUNK_END: ADMIN_DATA_HANDLER ────────────────────────────────────────────────

package/package.json

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