Entities & Types

Entities are the core building blocks in Synap - representing everything from tasks and notes to people and events.

What is an Entity?

An entity is any discrete piece of data in your Synap Data Pod:


interface Entity {
  id: string              // Unique identifier
  userId: string          // Owner
  type: EntityType        // Entity type
  title: string           // Display name
  preview?: string        // Short summary
  metadata: object        // Type-specific data
  createdAt: Date
  updatedAt: Date
  deletedAt?: Date        // Soft delete
}

Entity Types

Synap supports 5 core entity types:

1. Task 📋

Work items, todos, action items.


await synap.entities.create({
  type: 'task',
  title: 'Review PR #123',
  metadata: {
    status: 'todo',           // 'todo' | 'in_progress' | 'done' | 'archived'
    priority: 'high',         // 'low' | 'medium' | 'high' | 'urgent'
    dueDate: '2024-12-25',
    completedAt: null,
    assignee: 'user_456',
    estimatedMinutes: 60,
    actualMinutes: null
  }
})

Common Use Cases:

Project management
Personal todos
Team task tracking
Sprint planning

2. Note 📝

Documents, thoughts, knowledge.


await synap.entities.create({
  type: 'note',
  title: 'Meeting Notes - Q4 Planning',
  content: '# Discussion points...',
  metadata: {
    tags: ['planning', 'q4', 'strategy'],
    format: 'markdown',      // 'markdown' | 'plain' | 'rich'
    linkedEntities: ['note_789'],
    isFavorite: true
  }
})

Common Use Cases:

Personal knowledge base
Meeting minutes
Documentation
Journaling

3. Person 👤

Contacts, team members, relationships.


await synap.entities.create({
  type: 'person',
  title: 'Marie Johnson',
  metadata: {
    email: 'marie@example.com',
    phone: '+1-555-0123',
    company: 'Acme Corp',
    role: 'Product Manager',
    linkedIn: 'https://linkedin.com/in/mariej',
    notes: 'Met at conference 2024'
  }
})

Common Use Cases:

CRM systems
Contact management
Team directories
Networking

4. Event 📅

Calendar events, meetings, appointments.


await synap.entities.create({
  type: 'event',
  title: 'Q4 Planning Meeting',
  metadata: {
    startTime: '2024-12-20T14:00:00Z',
    endTime: '2024-12-20T15:30:00Z',
    location: 'Conference Room A',
    attendees: ['user_123', 'user_456'],
    isRecurring: false,
    reminderMinutes: 15
  }
})

Common Use Cases:

Calendar applications
Meeting scheduling
Event tracking
Time blocking

5. File 📁

Documents, images, attachments.


await synap.entities.create({
  type: 'file',
  title: 'Q4-Budget.xlsx',
  metadata: {
    fileType: 'spreadsheet',
    mimeType: 'application/vnd.ms-excel',
    sizeBytes: 45678,
    url: 'https://storage.synap.app/files/...',
    checksum: 'sha256:abc123...',
    uploadedBy: 'user_123'
  }
})

Common Use Cases:

Document management
File storage
Asset libraries
Attachment tracking

TypeScript Types

The SDK provides full type safety:


import { EntityType, EntityMetadata } from '@synap/sdk'
 
// EntityType is a union type
type EntityType = 'task' | 'note' | 'person' | 'event' | 'file'
 
// EntityMetadata is type-checked based on entity type
type EntityMetadata = {
  task: {
    status: 'todo' | 'in_progress' | 'done' | 'archived'
    priority?: 'low' | 'medium' | 'high' | 'urgent'
    // ... more task fields
  }
  note: {
    tags: string[]
    format: 'markdown' | 'plain' | 'rich'
    // ... more note fields
  }
  // ... other types
}
 
// TypeScript knows the metadata shape
const task = await synap.entities.create({
  type: 'task',
  metadata: {
    status: 'todo',      // ✅ Autocomplete & type-checked
    priority: 'high'     // ✅ Autocomplete & type-checked
  }
})

Common Patterns

Create with Relationships


// Create task
const { entityId: taskId } = await synap.entities.create({
  type: 'task',
  title: 'Review budget proposal'
})
 
// Create person
const { entityId: personId } = await synap.entities.create({
  type: 'person',
  title: 'Marie Johnson'
})
 
// Assign task to person
await synap.relations.create(taskId, personId, 'assigned_to')

Query by Type


// Get all tasks
const tasks = await synap.entities.list({
  type: 'task',
  limit: 50
})
 
// Get all people
const people = await synap.entities.list({
  type: 'person'
})

Search Across Types


// Search all entity types
const results = await synap.entities.search({
  query: 'Q4 planning',
  types: ['task', 'note', 'event']
})

Metadata Validation

All metadata is validated against schemas:


// ✅ Valid
await synap.entities.create({
  type: 'task',
  metadata: {
    status: 'done',
    priority: 'high'
  }
})
 
// ❌ Invalid - TypeScript error
await synap.entities.create({
  type: 'task',
  metadata: {
    status: 'invalid',  // Type error!
    priority: 'super'   // Type error!
  }
})

Custom Metadata

Beyond standard fields, you can add custom data:


await synap.entities.create({
  type: 'task',
  metadata: {
    // Standard fields
    status: 'todo',
    priority: 'high',
    
    // Custom fields
    customField1: 'value',
    tags: ['custom', 'fields'],
    internalId: 'ABC-123'
  }
})

Note: Custom fields aren’t type-checked but are stored and returned.

Best Practices

✅ Do’s


// Use descriptive titles
await synap.entities.create({
  type: 'task',
  title: 'Review Q4 budget proposal with finance team'
})
 
// Keep metadata focused
metadata: {
  status: 'todo',
  dueDate: '2024-12-25',
  priority: 'high'
}
 
// Use relationships instead of duplicating data
// ✅ Create relation
await synap.relations.create(taskId, personId, 'assigned_to')
 
// ❌ Don't duplicate person data in task metadata
metadata: {
  assigneeName: 'Marie',  // Bad - use relation instead
  assigneeEmail: 'marie@...' // Bad
}

❌ Don’ts


// Don't store large content in metadata
metadata: {
  largeDocument: '...' // ❌ Use 'content' field or separate file entity
}
 
// Don't create duplicate entities
// Use get/search first to check if entity exists
 
// Don't hardcode entity IDs
// Use search/list to find entities dynamically

Next Steps

Relationships → - Link entities together
Event Sourcing → - Understand the architecture
Entities API → - Complete API reference
Examples → - See entities in action