Data Model

interface Tenant {
  id: string;                    // Unique tenant ID
  name: string;                  // Organization name
  email: string;                 // Contact email (unique)
  settings: TenantSettings;      // Configuration
  stats: TenantStats;            // Usage statistics
  status: 'active' | 'suspended' | 'deleted';
  created_at: string;            // ISO 8601 timestamp
  updated_at: string;            // Last update timestamp
}

interface TenantSettings {
  retention_days: number;              // Default: 30
  batch_size: number;                  // Default: 10
  max_conversations_per_user: number;  // Default: 100
  max_users: number;                   // Default: 1000
  encryption_mode: 'platform' | 'byok';
  webhook_url?: string;
  webhook_events?: string[];
}

interface TenantStats {
  user_count: number;
  conversation_count: number;
  total_interactions: number;
  storage_bytes: number;
}

interface ApiKey {
  id: string;             // Unique key ID
  tenant_id: string;      // Parent tenant
  name: string;           // Human-readable name
  secret_hash: string;    // SHA-256 hash of secret
  prefix: string;         // First 8 chars for identification
  scopes: ApiKeyScope[];  // Permissions
  created_at: string;
  last_used_at?: string;
  expires_at?: string;
  revoked: boolean;
}

type ApiKeyScope =
  | 'memory:read'
  | 'memory:write'
  | 'users:read'
  | 'users:write'
  | 'conversations:read'
  | 'conversations:write'
  | 'tenant:read'
  | 'tenant:admin';

interface TenantUser {
  user_id: string;                     // 'usr_xxx' - Raven user ID
  tenant_id: string;                   // Parent tenant
  external_ref?: string;               // Your system's user ID
  display_name?: string;               // Human-readable name
  metadata?: Record<string, unknown>;  // Custom data
  created_at: string;                  // ISO 8601 timestamp
  updated_at?: string;                 // Last update
}

interface Conversation {
  conversation_id: string;             // 'conv_xxx' - Unique ID
  tenant_id: string;                   // Parent tenant
  user_id: string;                     // Owner user
  title?: string;                      // Display title
  metadata?: Record<string, unknown>;  // Custom data
  message_count: number;               // Total interactions
  last_message_at?: string;            // Last activity
  created_at: string;                  // ISO 8601 timestamp
  updated_at: string;                  // Last update
}

interface MemoryBlob {
  schema_version: number;
  metadata: BlobMetadata;
  data: EpisodicData | SemanticData | EmbeddingData;
}

interface BlobMetadata {
  blob_id: string;
  tenant_id: string;
  user_id: string;
  blob_type: 'episodic' | 'semantic' | 'embeddings';
  created_at: string;
  expires_at?: string;
  content_hash?: string;  // SHA-256 of plaintext
}

// Episodic Memory Data
interface EpisodicData {
  blob_type: 'episodic';
  conversations: Array<{
    conversation_id: string;
    timestamp: string;
    user_message: string;
    agent_response: string;
    metadata?: Record<string, unknown>;
  }>;
}

// Semantic Memory Data
interface SemanticData {
  blob_type: 'semantic';
  extracted_facts: string[];
  patterns: Array<{
    pattern: string;
    frequency: number;
    confidence: number;
    first_seen: string;
    last_seen: string;
  }>;
}

// Embedding Data
interface EmbeddingData {
  blob_type: 'embeddings';
  embeddings: Array<{
    id: string;
    text: string;
    vector: number[];
    metadata?: Record<string, unknown>;
  }>;
}

interface EncryptedPayload {
  algorithm: 'AES-256-GCM';
  version: number;           // Key version for rotation
  iv: string;                // Base64-encoded IV (12 bytes)
  auth_tag: string;          // Base64-encoded auth tag (16 bytes)
  ciphertext: string;        // Base64-encoded encrypted data
  key_id?: string;           // Optional key identifier
}

# Tenant data
tenant:{tenant_id}                              # Tenant JSON
tenant:email:{email}                            # Email → tenant_id lookup

# API keys
apikey:hash:{sha256_hash}                       # API key by hash
tenant:{tenant_id}:apikeys                      # List of key IDs

# Users
tenant:{tenant_id}:users                        # Set of user IDs
tenant:{tenant_id}:user:{user_id}               # User JSON
tenant:{tenant_id}:user:external:{ref}          # External ref lookup

# Conversations
tenant:{tenant_id}:user:{user_id}:conversations         # Set of conv IDs
tenant:{tenant_id}:user:{user_id}:conversation:{id}     # Conv JSON

# Memory
tenant:{tenant_id}:user:{user_id}:conversation:{id}:buffer  # Pending interactions
tenant:{tenant_id}:user:{user_id}:episodic:blob_ids         # List of blob IDs
tenant:{tenant_id}:user:{user_id}:semantic:blob_ids         # List of blob IDs