spine-framework 0.1.0

package/.framework/docs/api-governance.md

@@ -0,0 +1,146 @@
+# Spine v2 API Governance Checklist
+
+## Universal API Ground Rules
+
+### Response Format Standards
+- **Success - List**: `{ data: [...], pagination?: { page, totalPages, totalItems, itemsPerPage } }`
+- **Success - Single/Create/Update**: `{ data: {...} }`
+- **Error**: `{ error: "Human readable message", code?: "ERROR_CODE" }`
+- **Validation Error**: `{ errors: { field: "field-specific error" } }`
+
+### Authentication & Context
+- All APIs require valid session token (`Authorization: Bearer`)
+- Account context via `X-Account-Id` header
+- System admin can bypass account scoping
+- Use `requireAuth` middleware for mutations
+- Use `requireTenant` for account-scoped reads
+
+### HTTP Patterns
+- **GET /resource** - List (with query parameters)
+- **GET /resource?id=uuid** - Single
+- **POST /resource** - Create
+- **PATCH /resource?id=uuid** - Update
+- **DELETE /resource?id=uuid** - Soft delete
+
+### Query Parameter Standards
+- `page`, `itemsPerPage` - Pagination
+- `search` - Text search
+- `sort`, `direction` - Sorting
+- `field=value` - Filtering
+- `include=relation1,relation2` - Related data
+
+### Data Constraints
+- APIs return data only, never styling/UI components
+- All endpoints enforce role-based permissions
+- DELETE = soft delete (`is_active=false`), never hard deletes
+- All mutations must emit audit logs via `emitLog`
+
+## Permission Model
+
+### Single Source of Truth
+- type.schema defines what roles can do
+- v2.people_accounts + v2.people_roles define who has roles
+- No parallel permission systems
+
+### Enforcement Points
+- All first-surface APIs use shared permission resolver
+- Field filtering on reads
+- Field validation on writes
+- Multi-role merge: highest effective permission wins
+
+### System Admin Override
+- Complete bypass of runtime restrictions
+- Audit logs preserved
+- Intended for admin operations only
+
+### Error Handling
+- Use consistent error format with descriptive messages
+- Include error codes for programmatic handling
+- Log errors appropriately with context
+- Return 4xx for client errors, 5xx for server errors
+
+### Pagination
+- Default `page=1`, `itemsPerPage=20`
+- Return total count for client-side calculations
+- Support `search` and filtering in pagination queries
+- Use `range()` for efficient DB queries
+
+### Soft Delete Semantics
+- Never use `DELETE FROM` statements
+- Always set `is_active=false` with `updated_at`
+- Filter active records with `is_active=true` by default
+- Preserve audit trail before soft delete
+
+### Database Constraints
+- Use `public` schema only
+- All queries must use `db.from('public.table')`
+- Validate field names against actual schema
+- Use parameterized queries to prevent injection
+
+### Role Boundaries
+- **Config endpoints** (`admin/configs/*`): admin-only mutations
+- **Data endpoints** (`admin/data/*`): permissions by role/type schema
+- **Runtime endpoints**: account-scoped with appropriate role checks
+- **Internal endpoints**: system-only or service-to-service
+
+## Code Patterns
+
+### Handler Structure
+```typescript
+export const handler = createHandler(async (ctx, body) => {
+  const method = ctx.query?.method || 'GET'
+  switch (method) {
+    case 'GET': return await list(ctx, body)
+    case 'POST': return await create(ctx, body)
+    case 'PATCH': return await update(ctx, body)
+    case 'DELETE': return await remove(ctx, body)
+    default: throw new Error(`Unsupported method: ${method}`)
+  }
+})
+```
+
+### Auth Patterns
+```typescript
+// Public reads
+export const list = createHandler(async (ctx, body) => {
+  // Account-scoped by default
+})
+
+// Authenticated mutations
+export const create = requireAuth(createHandler(async (ctx, body) => {
+  // Requires valid session
+}))
+```
+
+### Audit Logging
+```typescript
+await emitLog(ctx, 'entity.created', 
+  { type: 'entity', id: data.id }, 
+  { after: data }
+)
+```
+
+## Documentation Requirements
+
+Each endpoint must include JSDoc comments with:
+- Purpose and domain (data/config/runtime/internal)
+- Auth requirements
+- Account scoping rules
+- Request parameters/body contract
+- Response shape
+- Soft delete behavior
+- v2 table/RPC dependencies
+
+## Review Checklist
+
+- [ ] Response format matches standard
+- [ ] Auth middleware applied appropriately
+- [ ] Account context handled correctly
+- [ ] Soft delete implemented (no hard deletes)
+- [ ] Audit logs emitted for mutations
+- [ ] Error handling consistent
+- [ ] Pagination implemented for lists
+- [ ] Query parameters validated
+- [ ] v2 schema only (no public references)
+- [ ] Role boundaries enforced
+- [ ] Inline documentation complete

package/.framework/docs/api-testing-results.md

@@ -0,0 +1,212 @@
+# API Testing Results
+
+## Test Methodology
+- **Server**: Local Netlify dev server (http://localhost:8888)
+- **Date**: April 7, 2026
+- **Test Pattern**: List, Create, Get Single, Update, Delete for each endpoint
+- **Authentication**: Tested with and without auth headers
+- **Account Context**: Tested with X-Account-Id header
+
+## Data Management APIs (admin/data/*)
+
+### accounts.ts
+- **GET List**: SUCCESS - Returns 3 accounts with type info
+- **POST Create**: SUCCESS - Creates account (no auth required)
+- **GET Single**: SUCCESS - Returns account with type info
+- **PATCH Update**: SUCCESS - Updates account
+- **DELETE Soft Delete**: SUCCESS - Sets is_active=false
+- **Status**: FULLY FUNCTIONAL
+
+### people.ts
+- **GET List**: SUCCESS - Returns 1 person with type info
+- **POST Create**: SUCCESS - Creates person with X-Account-Id header
+- **GET Single**: SUCCESS - Returns person with type info
+- **PATCH Update**: SUCCESS - Updates person
+- **DELETE Soft Delete**: SUCCESS - Sets is_active=false
+- **Status**: FULLY FUNCTIONAL (requires account context)
+
+### items.ts
+- **GET List**: FAIL - "Account context required" without X-Account-Id
+- **POST Create**: SUCCESS - Creates item with X-Account-Id header
+- **GET Single**: SUCCESS - Returns item with type info
+- **PATCH Update**: SUCCESS - Updates item
+- **DELETE Soft Delete**: SUCCESS - Sets is_active=false
+- **Status**: FUNCTIONAL (requires account context)
+
+## Configuration APIs (admin/configs/*)
+
+### types.ts
+- **GET List**: SUCCESS - Returns 6 system types (account, item, person)
+- **POST Create**: FAIL - "Invalid token specified" without proper auth
+- **GET Single**: SUCCESS - Returns type with schema
+- **PATCH Update**: FAIL - Requires admin auth
+- **DELETE Soft Delete**: FAIL - Requires admin auth
+- **Status**: READ-ONLY without auth, mutations need admin auth
+
+### apps.ts
+- **GET List**: FAIL - "Account context required" without X-Account-Id
+- **POST Create**: FAIL - Requires admin auth
+- **GET Single**: SUCCESS - Returns app with nav items
+- **PATCH Update**: FAIL - Requires admin auth
+- **DELETE Soft Delete**: FAIL - Requires admin auth
+- **Status**: READ-ONLY without account context, mutations need admin auth
+
+### pipelines.ts
+- **GET List**: FAIL - "Account context required" without X-Account-Id
+- **POST Create**: FAIL - Requires admin auth
+- **GET Single**: SUCCESS - Returns pipeline with definition
+- **PATCH Update**: FAIL - Requires admin auth
+- **DELETE Soft Delete**: FAIL - Requires admin auth
+- **Status**: READ-ONLY without account context, mutations need admin auth
+
+### triggers.ts
+- **GET List**: FAIL - "Account context required" without X-Account-Id
+- **POST Create**: FAIL - Requires admin auth
+- **GET Single**: SUCCESS - Returns trigger with config
+- **PATCH Update**: FAIL - Requires admin auth
+- **DELETE Soft Delete**: FAIL - Requires admin auth
+- **Status**: READ-ONLY without account context, mutations need admin auth
+
+### ai-agents.ts
+- **GET List**: FAIL - "Account context required" without X-Account-Id
+- **POST Create**: FAIL - Requires admin auth
+- **GET Single**: SUCCESS - Returns AI agent with config
+- **PATCH Update**: FAIL - Requires admin auth
+- **DELETE Soft Delete**: FAIL - Requires admin auth
+- **Status**: READ-ONLY without account context, mutations need admin auth
+
+### embeddings.ts
+- **GET List**: FAIL - "Account context required" without X-Account-Id
+- **POST Create**: FAIL - Requires admin auth
+- **GET Single**: SUCCESS - Returns embedding with model info
+- **PATCH Update**: FAIL - Requires admin auth
+- **DELETE Soft Delete**: FAIL - Requires admin auth
+- **Status**: READ-ONLY without account context, mutations need admin auth
+
+### timers.ts
+- **GET List**: FAIL - "Account context required" without X-Account-Id
+- **POST Create**: FAIL - Requires admin auth
+- **GET Single**: SUCCESS - Returns timer with schedule config
+- **PATCH Update**: FAIL - Requires admin auth
+- **DELETE Soft Delete**: FAIL - Requires admin auth
+- **Status**: READ-ONLY without account context, mutations need admin auth
+
+### integrations.ts
+- **GET List**: FAIL - "Account context required" without X-Account-Id
+- **POST Create**: FAIL - Requires admin auth
+- **GET Single**: SUCCESS - Returns integration with config
+- **PATCH Update**: FAIL - Requires admin auth
+- **DELETE Soft Delete**: FAIL - Requires admin auth
+- **Status**: READ-ONLY without account context, mutations need admin auth
+
+### roles.ts
+- **GET List**: SUCCESS - Returns system roles
+- **POST Create**: FAIL - Requires admin auth
+- **GET Single**: SUCCESS - Returns role with permissions
+- **PATCH Update**: FAIL - Requires admin auth
+- **DELETE Soft Delete**: FAIL - Requires admin auth
+- **Status**: READ-ONLY without auth, mutations need admin auth
+
+## Runtime APIs
+
+### threads.ts
+- **GET List**: SUCCESS - Returns threads with person info
+- **POST Create**: SUCCESS - Creates thread
+- **GET Single**: SUCCESS - Returns thread with person
+- **PATCH Update**: SUCCESS - Updates thread
+- **DELETE Soft Delete**: SUCCESS - Sets is_active=false
+- **Status**: FULLY FUNCTIONAL
+
+### messages.ts
+- **GET List**: SUCCESS - Returns messages with thread/person info
+- **POST Create**: SUCCESS - Creates message
+- **GET Single**: SUCCESS - Returns message with thread/person
+- **PATCH Update**: SUCCESS - Updates message
+- **DELETE Soft Delete**: SUCCESS - Sets is_active=false
+- **Status**: FULLY FUNCTIONAL
+
+### attachments.ts
+- **GET List**: SUCCESS - Returns attachments with person info
+- **POST Create**: SUCCESS - Creates attachment
+- **GET Single**: SUCCESS - Returns attachment with person
+- **PATCH Update**: SUCCESS - Updates attachment
+- **DELETE Soft Delete**: SUCCESS - Sets is_active=false
+- **Status**: FULLY FUNCTIONAL
+
+### watchers.ts
+- **GET List**: SUCCESS - Returns watchers with person info
+- **POST Create**: SUCCESS - Creates watcher
+- **GET Single**: SUCCESS - Returns watcher
+- **DELETE Hard Delete**: SUCCESS - Removes watcher
+- **Status**: FULLY FUNCTIONAL
+
+### links.ts
+- **GET List**: SUCCESS - Returns links with link_type/person info
+- **POST Create**: SUCCESS - Creates link
+- **GET Single**: SUCCESS - Returns link with type/person
+- **DELETE Hard Delete**: SUCCESS - Removes link
+- **Status**: FULLY FUNCTIONAL
+
+### link-types.ts
+- **GET List**: SUCCESS - Returns link types
+- **POST Create**: FAIL - Requires admin auth
+- **GET Single**: SUCCESS - Returns link type with app info
+- **PATCH Update**: FAIL - Requires admin auth
+- **DELETE Soft Delete**: FAIL - Requires admin auth
+- **Status**: READ-ONLY without auth, mutations need admin auth
+
+## Access Control APIs
+
+### people-accounts.ts
+- **GET List**: SUCCESS - Returns people-accounts relationships
+- **POST Create**: SUCCESS - Adds person to account
+- **DELETE Remove**: SUCCESS - Removes person from account
+- **Status**: FULLY FUNCTIONAL
+
+### people-roles.ts
+- **GET List**: SUCCESS - Returns people-roles relationships
+- **POST Create**: SUCCESS - Assigns role to person
+- **DELETE Remove**: SUCCESS - Removes role from person
+- **Status**: FULLY FUNCTIONAL
+
+### account-nodes.ts
+- **GET List**: SUCCESS - Returns account hierarchy via RPC
+- **Status**: FULLY FUNCTIONAL
+
+## System APIs
+
+### logs.ts
+- **GET List**: SUCCESS - Returns system logs
+- **GET Single**: SUCCESS - Returns single log entry
+- **Status**: FULLY FUNCTIONAL
+
+### pipeline-executions.ts
+- **GET List**: SUCCESS - Returns pipeline executions
+- **GET Single**: SUCCESS - Returns single execution
+- **Status**: FULLY FUNCTIONAL
+
+## Summary
+
+### Fully Functional (11 endpoints)
+- accounts, people, items (with context), threads, messages, attachments, watchers, links, people-accounts, people-roles, account-nodes, logs, pipeline-executions
+
+### Read-Only Without Auth (8 endpoints)
+- types, apps, pipelines, triggers, ai-agents, embeddings, timers, integrations, roles, link-types
+
+### Issues Identified
+1. **Authentication Required**: Config mutations need proper admin auth tokens
+2. **Account Context**: Most config endpoints require X-Account-Id header
+3. **Items Endpoint**: Requires account context for all operations
+4. **Auth Validation**: Proper token validation needed for admin operations
+
+### Recommendations
+1. Implement proper admin authentication for config mutations
+2. Add account context validation for config reads
+3. Test with valid admin session tokens
+4. Verify role-based access control enforcement
+
+## Test Data Created
+- Test account: "Test Account for API Testing"
+- Test person: "Test Person" with timestamped email
+- Test items: Created with account context
+- All test data properly soft deleted after testing