Events Package (BETA)

# Install both base and events addon
pnpm add @fyit/crouton-core @fyit/crouton-events

// nuxt.config.ts
export default defineNuxtConfig({
  extends: [
    '@fyit/crouton-core',    // Base layer (required)
    '@fyit/crouton-events'   // Events addon
  ]
})

export default defineNuxtConfig({
  extends: [
    '@fyit/crouton-core',
    '@fyit/crouton-events'
  ],

  runtimeConfig: {
    public: {
      croutonEvents: {
        // Enable/disable tracking globally
        enabled: true,

        // Store username snapshot for audit trail
        snapshotUserName: true,

        // Error handling configuration
        errorHandling: {
          mode: 'toast',        // 'silent' | 'toast' | 'throw'
          logToConsole: true    // Log errors to console
        },

        // Automatic cleanup of old events
        retention: {
          enabled: true,        // Enable auto-cleanup
          days: 90,            // Keep events for 90 days
          maxEvents: 100000    // Or maximum number of events
        }
      }
    }
  }
})

interface CroutonEvent {
  // Core identification
  id: string
  timestamp: string | Date

  // Operation details
  operation: 'create' | 'update' | 'delete'
  collectionName: string
  itemId: string

  // User attribution
  userId: string
  userName: string  // Snapshot at time of event

  // Field-level changes
  changes: EventChange[]

  // Optional metadata
  metadata?: Record<string, unknown>
}

interface EventChange {
  fieldName: string
  oldValue: string | null  // JSON stringified
  newValue: string | null  // JSON stringified
}

const { track, trackInBackground } = useCroutonEventTracker()

interface TrackEventOptions {
  operation: 'create' | 'update' | 'delete'
  collection: string
  itemId?: string
  itemIds?: string[]
  data?: any           // For create: new item data
  updates?: any        // For update: fields being updated
  result?: any         // Result after operation
  beforeData?: any     // State before operation (for update/delete)
}

// Manual tracking (usually not needed - auto-tracking via plugin)
try {
  await track({
    operation: 'update',
    collection: 'users',
    itemId: 'user-123',
    beforeData: { name: 'John', email: 'john@example.com' },
    result: { name: 'Jane', email: 'john@example.com' }
  })
} catch (error) {
  console.error('Tracking failed:', error)
}

// Non-blocking tracking
trackInBackground({
  operation: 'create',
  collection: 'posts',
  data: { title: 'New Post', content: '...' }
})

const { data, pending, error, refresh } = useCroutonEvents(options)

interface UseCroutonEventsOptions {
  teamId?: string              // Override team context
  enrichUserData?: boolean     // Join with users table (future)
  
  filters?: {
    collectionName?: string    // Filter by collection
    operation?: 'create' | 'update' | 'delete'
    userId?: string            // Filter by user
    dateFrom?: Date            // Events after this date
    dateTo?: Date              // Events before this date
  }
  
  pagination?: {
    page?: number              // Page number (default: 1)
    pageSize?: number          // Items per page (default: 50)
  }
}

// Get all events for current team
const { data: events, pending } = useCroutonEvents()

// Filter by collection
const { data: userEvents } = useCroutonEvents({
  filters: {
    collectionName: 'users'
  }
})

// Get only UPDATE operations
const { data: updates } = useCroutonEvents({
  filters: {
    operation: 'update'
  }
})

// Get events from last 7 days
const sevenDaysAgo = new Date()
sevenDaysAgo.setDate(sevenDaysAgo.getDate() - 7)

const { data: recentEvents } = useCroutonEvents({
  filters: {
    dateFrom: sevenDaysAgo
  }
})

// Complex query: user updates in posts collection, last 30 days
const { data: events } = useCroutonEvents({
  filters: {
    collectionName: 'posts',
    operation: 'update',
    userId: 'user-123',
    dateFrom: new Date(Date.now() - 30 * 24 * 60 * 60 * 1000)
  },
  pagination: {
    page: 1,
    pageSize: 100
  }
})

// Join with users table to get current user data
const { data: enrichedEvents } = useCroutonEvents({
  enrichUserData: true
})

// enrichedEvents[0].userName = "John Smith" (at time of event)
// enrichedEvents[0].user.currentName = "Jane Doe" (current)
// enrichedEvents[0].user.email = "jane@example.com"

interface CroutonEventsHealth {
  total: number           // Total tracking attempts
  failed: number          // Failed tracking attempts
  lastError: string | null
  lastErrorTime: Date | null
}

<script setup lang="ts">
const health = useState<{
  total: number
  failed: number
  lastError: string | null
  lastErrorTime: Date | null
}>('crouton-events-health')

const failureRate = computed(() => {
  if (!health.value?.total) return 0
  return (health.value.failed / health.value.total) * 100
})

const isHealthy = computed(() => failureRate.value < 10)
</script>

<template>
  <div v-if="health">
    <h3>Event Tracking Health</h3>
    <div>Total Events: {{ health.total }}</div>
    <div>Failed: {{ health.failed }}</div>
    <div>Failure Rate: {{ failureRate.toFixed(2) }}%</div>
    <div>Status: {{ isHealthy ? 'Healthy' : 'Degraded' }}</div>

    <div v-if="health.lastError">
      <p>Last Error: {{ health.lastError }}</p>
      <p>Time: {{ health.lastErrorTime }}</p>
    </div>
  </div>
</template>

<template>
  <CroutonActivityLog />
</template>

<template>
  <CroutonActivityTimeline :events="events" @event-click="handleClick" />
</template>

// Events can be queried like any other collection
const { data: events, pending } = await useCollectionQuery('collectionEvents', {
  teamId: currentTeam.id,
  filters: { collectionName: 'users', operation: 'create' }
})

// GET /api/teams/:teamId/crouton-events — query tracked events
const response = await $fetch(`/api/teams/${teamId}/crouton-events`, {
  params: {
    collectionName: 'users',
    operation: 'update',
    page: 1,
    pageSize: 50
  }
})

// POST /api/teams/:teamId/crouton-collection-events — manual event tracking only
const response = await $fetch(`/api/teams/${teamId}/crouton-collection-events`, {
  method: 'POST',
  body: {
    operation: 'update',
    collection: 'users',
    itemId: 'user-123'
  }
})

// Runs automatically - no configuration needed
nuxtApp.hooks.hook('crouton:mutation', async (event) => {
  // Track event in background
  await track({
    operation: event.operation,
    collection: event.collection,
    itemId: event.itemId,
    data: event.data,
    result: event.result,
    beforeData: event.beforeData
  })
})

⚠️ Event tracking failed
Description: Network error or validation failure

export default defineNuxtConfig({
  runtimeConfig: {
    public: {
      croutonEvents: {
        errorHandling: {
          mode: 'toast',        // Development-friendly
          logToConsole: true
        }
      }
    }
  }
})

// Options for mode:
// 'silent'  - No UI feedback, console logging only
// 'toast'   - Show toast in dev, silent in prod
// 'throw'   - Throw errors (not recommended - blocks operations)

// Server-side utility (auto-imported in Nuxt server context)
const result = await cleanupOldEvents()

console.log(result)
// {
//   deletedCount: 5234,
//   oldestRemaining: Date('2025-08-18T...'),
//   totalRemaining: 94766
// }

interface CleanupOptions {
  retentionDays?: number   // Override config setting
  maxEvents?: number       // Override config setting
  dryRun?: boolean        // Preview without deleting
}

// Dry run to see what would be deleted
const preview = await cleanupOldEvents({ dryRun: true })

// Custom retention (keep only 30 days)
const result = await cleanupOldEvents({ retentionDays: 30 })

// Limit by count (keep max 50k events)
const result = await cleanupOldEvents({ maxEvents: 50000 })

// Cleanup process
1. Count total events: 125,000
2. Delete events > 90 days: -20,000 (105,000 remaining)
3. Check max limit: 105,000 > 100,000
4. Delete 5,000 oldest events: -5,000 (100,000 remaining)
5. Result: 25,000 deleted, 100,000 remaining

// server/tasks/cleanup-events.ts
export default defineTask({
  meta: {
    name: 'cleanup-old-events',
    description: 'Remove old event tracking data'
  },
  
  // Run daily at 3 AM
  run: async () => {
    const result = await cleanupOldEvents()
    
    return {
      result: 'success',
      deletedCount: result.deletedCount,
      remaining: result.totalRemaining
    }
  }
})

const config = useRuntimeConfig()
console.log(config.public.croutonEvents?.enabled)  // Should be true

const { user } = useUserSession()
console.log(user.value)  // Should exist

<script setup lang="ts">
const health = useState('crouton-events-health')
</script>

<template>
  <div v-if="health">
    Failed: {{ health.failed }} / {{ health.total }}
    Last error: {{ health.lastError }}
  </div>
</template>

// Enable console logging
croutonEvents: {
  errorHandling: {
    logToConsole: true
  }
}

// Check browser console for errors
// Check network tab for failed API calls

const { getTeamId } = useTeamContext()
console.log(getTeamId())  // Should match event teamId

// Remove filters to see all events
const { data } = useCroutonEvents({
  filters: {}  // No filters
})

// In server endpoint or task
const result = await cleanupOldEvents()

croutonEvents: {
  retention: {
    days: 30,         // Shorter retention
    maxEvents: 10000  // Lower limit
  }
}

// Core event type
interface CroutonEvent {
  id: string
  timestamp: string | Date
  operation: 'create' | 'update' | 'delete'
  collectionName: string
  itemId: string
  userId: string
  userName: string
  changes: EventChange[]
  metadata?: Record<string, unknown>
}

// Change record
interface EventChange {
  fieldName: string
  oldValue: string | null  // JSON stringified
  newValue: string | null  // JSON stringified
}

// Tracking options
interface TrackEventOptions {
  operation: 'create' | 'update' | 'delete'
  collection: string
  itemId?: string
  itemIds?: string[]
  data?: any
  updates?: any
  result?: any
  beforeData?: any
}

// Query options
interface UseCroutonEventsOptions {
  teamId?: string
  enrichUserData?: boolean
  filters?: {
    collectionName?: string
    operation?: 'create' | 'update' | 'delete'
    userId?: string
    dateFrom?: Date
    dateTo?: Date
  }
  pagination?: {
    page?: number
    pageSize?: number
  }
}

// Cleanup options
interface CleanupOptions {
  retentionDays?: number
  maxEvents?: number
  dryRun?: boolean
}

// Cleanup result
interface CleanupResult {
  deletedCount: number
  oldestRemaining: Date | null
  totalRemaining: number
}

// Health monitoring
interface CroutonEventsHealth {
  total: number
  failed: number
  lastError: string | null
  lastErrorTime: Date | null
}