spine-framework 0.1.0

package/.framework/docs/apis/admin-data.md

@@ -0,0 +1,272 @@
+# Admin Data APIs
+
+## Overview
+
+Admin Data APIs manage runtime records for accounts, people, and items. These endpoints support full CRUD operations with proper authentication and account scoping.
+
+## Accounts API
+
+**Endpoint:** `/.netlify/functions/accounts`
+
+**Domain:** admin-data (runtime account records)
+
+**Operations:**
+- `GET /functions/accounts` - List all active accounts
+- `GET /functions/accounts?id=uuid` - Get single account
+- `POST /functions/accounts` - Create new account
+- `PATCH /functions/accounts?id=uuid` - Update account
+- `DELETE /functions/accounts?id=uuid` - Soft delete account
+
+**Authentication:**
+- Reads: Account-scoped with field-level permission filtering
+- Mutations: Auth required with schema-driven permissions
+
+**Authorization:**
+- First Surface Operations: User permissions evaluated against type.schema
+- Role-based access from v2.people_accounts + v2.people_roles
+- Field-level permissions respected on reads and writes
+- System admin bypasses all restrictions
+
+**Examples:**
+- Customer can only see their own items (read: "own")
+- Master support can see all client items (read: "all") 
+- Field overrides control specific field access
+
+**Request/Response:**
+
+### List Accounts
+```typescript
+// Request
+GET /functions/accounts?page=1&itemsPerPage=20&search=keyword&type_id=uuid
+
+// Response
+{
+  data: [
+    {
+      id: string,
+      type_id: string,
+      slug: string,
+      display_name: string,
+      description?: string,
+      metadata?: object,
+      parent_id?: string,
+      is_active: true,
+      created_at: string,
+      updated_at: string,
+      created_by: string,
+      account_id: string,
+      type: {
+        id: string,
+        slug: string,
+        name: string,
+        icon?: string,
+        color?: string
+      }
+    }
+  ]
+}
+```
+
+### Create Account
+```typescript
+// Request
+POST /functions/accounts
+{
+  type_id: string,      // required
+  slug: string,         // required
+  display_name: string, // required
+  description?: string,
+  metadata?: object,
+  parent_id?: string
+}
+
+// Response
+{
+  data: { /* created account */ }
+}
+```
+
+## People API
+
+**Endpoint:** `/.netlify/functions/people`
+
+**Domain:** admin-data (runtime person records)
+
+**Operations:**
+- `GET /functions/people` - List all active people
+- `GET /functions/people?id=uuid` - Get single person
+- `POST /functions/people` - Create new person
+- `PATCH /functions/people?id=uuid` - Update person
+- `DELETE /functions/people?id=uuid` - Soft delete person
+
+**Authentication:**
+- Reads: Public (account-scoped)
+- Mutations: Auth required
+
+**Request/Response:**
+
+### List People
+```typescript
+// Request
+GET /functions/people?page=1&itemsPerPage=20&search=keyword&type_id=uuid
+
+// Response
+{
+  data: [
+    {
+      id: string,
+      type_id: string,
+      first_name: string,
+      last_name: string,
+      email?: string,
+      phone?: string,
+      metadata?: object,
+      is_active: true,
+      created_at: string,
+      updated_at: string,
+      created_by: string,
+      account_id: string,
+      type: {
+        id: string,
+        slug: string,
+        name: string,
+        icon?: string,
+        color?: string
+      }
+    }
+  ]
+}
+```
+
+### Create Person
+```typescript
+// Request
+POST /functions/people
+{
+  type_id: string,         // required
+  first_name: string,      // required
+  last_name: string,       // required
+  email?: string,
+  phone?: string,
+  metadata?: object
+}
+
+// Response
+{
+  data: { /* created person */ }
+}
+```
+
+## Items API
+
+**Endpoint:** `/.netlify/functions/items`
+
+**Domain:** admin-data (runtime item records)
+
+**Operations:**
+- `GET /functions/items` - List all active items
+- `GET /functions/items?id=uuid` - Get single item
+- `POST /functions/items` - Create new item
+- `PATCH /functions/items?id=uuid` - Update item
+- `DELETE /functions/items?id=uuid` - Soft delete item
+
+**Authentication:**
+- Reads: Public (account-scoped)
+- Mutations: Auth required
+
+**Request/Response:**
+
+### List Items
+```typescript
+// Request
+GET /functions/items?page=1&itemsPerPage=20&search=keyword&type_id=uuid
+
+// Response
+{
+  data: [
+    {
+      id: string,
+      type_id: string,
+      name: string,
+      description?: string,
+      metadata?: object,
+      is_active: true,
+      created_at: string,
+      updated_at: string,
+      created_by: string,
+      account_id: string,
+      type: {
+        id: string,
+        slug: string,
+        name: string,
+        icon?: string,
+        color?: string
+      }
+    }
+  ]
+}
+```
+
+### Create Item
+```typescript
+// Request
+POST /functions/items
+{
+  type_id: string,      // required
+  name: string,         // required
+  description?: string,
+  metadata?: object
+}
+
+// Response
+{
+  data: { /* created item */ }
+}
+```
+
+## Common Features
+
+### Soft Delete
+All DELETE operations use soft delete:
+- Sets `is_active = false`
+- Updates `updated_at` timestamp
+- Preserves audit trail
+- Never hard deletes records
+
+### Account Scoping
+- System admin can bypass account scoping
+- Regular users only see records from their account
+- Account context via `X-Account-Id` header
+
+### Audit Logging
+All mutations emit audit logs:
+- `entity.created` - On create
+- `entity.updated` - On update
+- `entity.deleted` - On soft delete
+
+### Error Handling
+```typescript
+// Success Response
+{
+  data: T
+}
+
+// Error Response
+{
+  error: "Human readable message",
+  code?: "ERROR_CODE"
+}
+
+// Validation Error
+{
+  errors: {
+    field: "field-specific error"
+  }
+}
+```
+
+### Pagination
+- Default: `page=1`, `itemsPerPage=20`
+- Supports `search` parameter
+- Supports filtering by `type_id`
+- Returns array of records

package/.framework/docs/apis/index.md

@@ -0,0 +1,231 @@
+# Spine v2 API Documentation
+
+## Overview
+
+This directory contains comprehensive API documentation for Spine v2, organized by domain and use case. All APIs follow the Spine v2 governance standards with consistent authentication, error handling, and data contracts.
+
+## API Domains
+
+### [Admin Data APIs](./admin-data.md)
+Runtime record management for accounts, people, and items.
+- **Accounts** - Account record management
+- **People** - Person record management  
+- **Items** - Item record management
+
+### [Admin Configuration APIs](./admin-configs.md)
+System configuration and definition management.
+- **Types** - Type definitions (item/account/person)
+- **Apps** - Application definitions
+- **Pipelines** - Workflow automation
+- **Triggers** - Event triggers
+- **AI Agents** - AI agent configurations
+- **Embeddings** - Embedding vector definitions
+- **Timers** - Scheduled task definitions
+- **Integrations** - External integrations
+- **Roles** - Role and permission definitions
+- **Prompt Configs** - AI prompt configurations
+
+### [Runtime APIs](./runtime.md)
+Application runtime operations.
+- **Threads** - Conversation threads
+- **Messages** - Thread messages
+- **Attachments** - File attachments
+- **Watchers** - Entity subscriptions
+- **Links** - Polymorphic relationships
+- **Link Types** - Relationship type definitions
+- **Access Control** - People-accounts, people-roles
+- **Account Nodes** - Account hierarchy traversal
+- **System** - Logs, pipeline executions
+
+### [Internal APIs](./internal.md)
+System-level and service-to-service operations.
+- **System Operations** - Logs, monitoring
+- **Quarantined Endpoints** - v2-incompatible APIs
+- **Service Patterns** - Background processing, maintenance
+
+## API Standards
+
+### Authentication
+- **Public Reads**: Admin data and config endpoints allow public reads
+- **Authenticated Mutations**: All write operations require valid session
+- **Admin Guards**: Configuration mutations require admin role
+- **Account Scoping**: Runtime endpoints respect account boundaries
+
+### Response Format
+```typescript
+// Success Response
+{
+  data: T | T[]
+}
+
+// Error Response  
+{
+  error: "Human readable message",
+  code?: "ERROR_CODE"
+}
+
+// Validation Error
+{
+  errors: {
+    field: "field-specific error"
+  }
+}
+```
+
+### Common Features
+- **Soft Delete**: All DELETE operations use `is_active=false`
+- **Audit Logging**: Mutations emit audit logs with context
+- **Pagination**: Default `page=1`, `itemsPerPage=20`
+- **Search & Filter**: Text search and field filtering support
+- **v2 Schema**: All endpoints use v2 schema exclusively
+
+## Quick Reference
+
+### Base URL
+```
+https://your-domain.netlify.app
+```
+
+### Endpoint Pattern
+```
+/.netlify/functions/{endpoint}
+```
+
+### Common Query Parameters
+- `page` - Pagination page number
+- `itemsPerPage` - Items per page
+- `search` - Text search
+- `id` - Single record ID
+- Domain-specific filters (e.g., `type_id`, `app_id`)
+
+### Authentication Headers
+```typescript
+// User Session
+Authorization: Bearer {session_token}
+X-Account-Id: {account_id}
+
+// Service-to-Service
+Authorization: Bearer {service_token}
+```
+
+## Error Codes
+
+| Code | Description |
+|------|-------------|
+| `UNAUTHORIZED` | Invalid or missing authentication |
+| `FORBIDDEN` | Insufficient permissions |
+| `NOT_FOUND` | Resource not found |
+| `VALIDATION_ERROR` | Invalid request data |
+| `SYSTEM_ERROR` | Internal server error |
+| `MAINTENANCE` | System under maintenance |
+
+## Rate Limits
+
+| Endpoint Type | Limit |
+|---------------|-------|
+| Public Reads | 100 requests/minute |
+| Authenticated | 500 requests/minute |
+| Admin Operations | 200 requests/minute |
+| Service-to-Service | 1000 requests/minute |
+
+## SDK Integration
+
+### JavaScript/TypeScript
+```typescript
+import { SpineAPI } from '@spine/sdk'
+
+const api = new SpineAPI({
+  baseURL: 'https://your-domain.netlify.app',
+  token: 'your-session-token'
+})
+
+// List accounts
+const accounts = await api.accounts.list()
+
+// Create item
+const item = await api.items.create({
+  type_id: 'uuid',
+  name: 'New Item'
+})
+```
+
+### Python
+```python
+from spine_api import SpineClient
+
+client = SpineClient(
+    base_url='https://your-domain.netlify.app',
+    token='your-session-token'
+)
+
+# List people
+people = client.people.list()
+
+# Create thread
+thread = client.threads.create({
+    'person_id': 'uuid',
+    'title': 'New Thread',
+    'thread_type': 'discussion'
+})
+```
+
+## Development Tools
+
+### API Testing
+- Use Postman collection for endpoint testing
+- Mock server available for development
+- OpenAPI specification available
+
+### Monitoring
+- Real-time API metrics dashboard
+- Error tracking and alerting
+- Performance monitoring
+
+### Debugging
+- Request/response logging
+- Stack trace capture
+- Debug mode for detailed errors
+
+## Migration Guide
+
+### From v1 to v2
+1. Update base URLs to use new endpoint patterns
+2. Migrate authentication to new token format
+3. Update request/response handling for new formats
+4. Implement soft delete handling
+5. Add account context headers
+
+### Breaking Changes
+- All endpoints now use v2 schema
+- Soft delete semantics applied universally
+- Authentication headers updated
+- Response format standardized
+
+## Support
+
+### Documentation
+- [API Governance Checklist](../api-governance.md)
+- [Admin Route Inventory](../admin-routes.md)
+- [UI-to-API Coverage Matrix](../ui-api-coverage.md)
+- [DB Compatibility Audit](../v2-compatibility-audit.md)
+
+### Getting Help
+- Review error messages for specific guidance
+- Check audit logs for operation details
+- Contact support for system issues
+- Community forums for development questions
+
+## Changelog
+
+### v2.0.0
+- Complete API restructure for v2 schema
+- Standardized response formats
+- Added comprehensive documentation
+- Implemented soft delete semantics
+- Enhanced authentication and authorization
+
+### v1.x.x
+- Legacy API structure
+- Mixed response formats
+- Limited documentation
+- Hard delete operations