Core Plugins Reference

{
  name: 'core-auth',
  version: '1.0.0-beta.1',
  settings: {
    tokenExpiration: 3600,      // Token TTL in seconds (1 hour)
    refreshExpiration: 604800,   // Refresh token TTL (7 days)
    sessionTracking: true,       // Enable session tracking
    rateLimitWindow: 900,        // Rate limit window (15 minutes)
    rateLimitMaxAttempts: 5      // Max login attempts per window
  }
}

curl -X POST http://localhost:8787/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "password123"
  }'

const response = await fetch('http://localhost:8787/api/auth/login', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    email: 'user@example.com',
    password: 'password123',
  }),
})

const { token, refreshToken, user } = await response.json()

// Available auth service methods
const authService = {
  // Validate JWT token
  validateToken(token: string): { valid: boolean; userId: number }

  // Generate new JWT token
  generateToken(userId: number): string

  // Hash password for storage
  hashPassword(password: string): string

  // Verify password against hash
  verifyPassword(password: string, hash: string): boolean
}

{
  name: 'email',
  version: '1.0.0-beta.1',
  settings: {
    apiKey: 're_...',              // Resend API key
    fromEmail: 'noreply@yourdomain.com',  // From email address
    fromName: 'Your App Name',     // From name
    replyTo: 'support@yourdomain.com',    // Reply-to address (optional)
    logoUrl: 'https://yourdomain.com/logo.png'  // Logo URL (optional)
  }
}

// Get email plugin instance
const emailPlugin = context.plugins.get('email')

// Send a custom email
await emailPlugin.sendEmail({
  to: 'user@example.com',
  subject: 'Welcome to CatCMS',
  html: '<h1>Welcome!</h1><p>Thanks for signing up.</p>',
})

// Send using built-in templates
await emailPlugin.sendVerificationEmail({
  to: 'user@example.com',
  verificationUrl: 'https://yoursite.com/verify?token=...',
})

await emailPlugin.sendPasswordResetEmail({
  to: 'user@example.com',
  resetUrl: 'https://yoursite.com/reset?token=...',
})

await emailPlugin.sendOneTimeCodeEmail({
  to: 'user@example.com',
  code: '123456',
  expiryMinutes: 10,
})

{
  name: 'magic-link-auth',
  version: '1.0.0',
  dependencies: ['email'],
  settings: {
    linkExpiryMinutes: 15,         // Magic link expiry time
    rateLimitPerHour: 5,           // Max requests per hour per email
    allowNewUsers: false,          // Auto-create users who don't exist
    requireEmailVerification: true // Require verified emails
  }
}

curl -X POST http://localhost:8787/auth/magic-link/request \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com"
  }'

const response = await fetch('http://localhost:8787/auth/magic-link/request', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    email: 'user@example.com',
  }),
})

const result = await response.json()
// result: { message: 'If an account exists...' }

{
  "message": "If an account exists for this email, you will receive a magic link shortly."
}

CREATE TABLE magic_links (
  id TEXT PRIMARY KEY,
  user_email TEXT NOT NULL,
  token TEXT NOT NULL UNIQUE,
  expires_at INTEGER NOT NULL,
  used INTEGER DEFAULT 0,
  used_at INTEGER,
  created_at INTEGER NOT NULL,
  ip_address TEXT,
  user_agent TEXT
)

<form id="magicLinkForm">
  <label>Email Address</label>
  <input type="email" name="email" required />
  <button type="submit">Send Magic Link</button>
</form>

<script>
  document.getElementById('magicLinkForm').addEventListener('submit', async (e) => {
    e.preventDefault()
    const email = new FormData(e.target).get('email')

    const response = await fetch('/auth/magic-link/request', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ email }),
    })

    if (response.ok) {
      alert('Check your email for a magic link!')
    }
  })
</script>

{
  name: 'core-media',
  version: '1.0.0-beta.1',
  settings: {
    maxFileSize: 10485760,        // Max file size (10MB)
    allowedTypes: [                // Allowed MIME types
      'image/jpeg',
      'image/png',
      'image/gif',
      'image/webp',
      'video/mp4',
      'application/pdf'
    ],
    thumbnailSize: { width: 300, height: 300 },
    storageProvider: 'r2',        // Storage backend
    autoGenerateThumbnails: true
  }
}

curl "http://localhost:8787/api/media?page=1&limit=20&type=image"

const response = await fetch('http://localhost:8787/api/media?page=1&limit=20&type=image')
const { data, pagination } = await response.json()

const formData = new FormData()
formData.append('file', fileInput.files[0])
formData.append('folder', 'images')

const response = await fetch('http://localhost:8787/api/media/upload', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${token}`,
  },
  body: formData,
})

const { data } = await response.json()
// data: { id, filename, url, size, type }

const mediaService = {
  // Upload file to storage
  uploadFile(file: File, options?: UploadOptions): Promise<MediaFile>

  // Delete file from storage
  deleteFile(id: string): Promise<boolean>

  // Process image with operations
  processImage(id: string, operations: Operation[]): Promise<Job>

  // Extract file metadata
  getMetadata(id: string): Promise<Metadata>
}

CREATE TABLE media_files (
  id INTEGER PRIMARY KEY,
  filename TEXT NOT NULL,
  original_name TEXT NOT NULL,
  mime_type TEXT NOT NULL,
  size INTEGER NOT NULL,
  url TEXT NOT NULL,
  thumbnail_url TEXT,
  metadata TEXT,
  uploaded_by INTEGER,
  tags TEXT,
  created_at INTEGER NOT NULL,
  updated_at INTEGER
)

{
  name: 'cache',
  version: '1.0.0-alpha.1',
  settings: {
    memoryEnabled: true,          // Enable in-memory cache
    kvEnabled: false,             // Enable KV cache
    defaultTTL: 3600,             // Default TTL (1 hour)
    maxMemorySize: 50,            // Max memory cache size (MB)
    namespaces: {
      content: { ttl: 3600 },     // Content cache (1 hour)
      user: { ttl: 900 },          // User cache (15 minutes)
      api: { ttl: 300 }            // API response cache (5 minutes)
    }
  }
}

curl http://localhost:8787/admin/cache/stats

{
  "success": true,
  "data": {
    "global": {
      "totalRequests": 15234,
      "memoryHits": 12450,
      "kvHits": 1892,
      "dbHits": 892,
      "hitRate": 94.1
    },
    "byNamespace": {
      "content": {
        "memoryHits": 8234,
        "kvHits": 892,
        "hitRate": 96.2
      },
      "user": {
        "memoryHits": 2891,
        "kvHits": 567,
        "hitRate": 92.8
      }
    }
  }
}

curl -X POST http://localhost:8787/admin/cache/invalidate \
  -H "Content-Type: application/json" \
  -d '{
    "pattern": "content:*",
    "namespace": "content"
  }'

import { getCacheService } from 'catcms-core'

// Get cache service for your namespace
const cache = getCacheService({
  namespace: 'my-plugin',
  ttl: 600,
  memoryEnabled: true,
  kvEnabled: false,
  invalidateOn: ['my-plugin:update'],
  version: 'v1',
})

// Get value from cache
const data = await cache.get('key')

// Set value in cache
await cache.set('key', data)

// Get or set pattern
const result = await cache.getOrSet('key', async () => {
  return await fetchExpensiveData()
})

// Invalidate by pattern
await cache.invalidate('user:*')

// Get statistics
const stats = cache.getStats()

{
  name: 'database-tools-plugin',
  version: '1.0.0',
  settings: {
    enableQueryConsole: true,     // Enable SQL query console
    maxQueryRows: 1000,           // Max rows returned
    enableBackups: true,          // Enable backup functionality
    autoMigration: true           // Auto-run migrations on startup
  }
}

curl -X POST http://localhost:8787/admin/database/query \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${token}" \
  -d '{
    "query": "SELECT * FROM content LIMIT 10"
  }'

const databaseService = {
  // List all tables
  getTables(): Promise<Table[]>

  // Get table schema
  getTableSchema(tableName: string): Promise<Schema>

  // Execute query
  executeQuery(sql: string, params?: any[]): Promise<Result>

  // Run migrations
  runMigrations(): Promise<MigrationResult[]>

  // Create backup
  createBackup(): Promise<Backup>
}

{
  name: 'seed-data-plugin',
  version: '1.0.0',
  settings: {
    enabled: false,               // Disable in production
    autoSeed: false,             // Auto-seed on first run
    contentCount: 50,            // Number of content items
    userCount: 10,               // Number of test users
    mediaCount: 20               // Number of media files
  }
}

curl -X POST http://localhost:8787/admin/seed-data/generate \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${token}" \
  -d '{
    "contentCount": 50,
    "userCount": 10,
    "mediaCount": 20,
    "clearExisting": false
  }'

import { generateSeedData } from 'catcms-core'

// Generate seed data programmatically
await generateSeedData({
  content: {
    count: 50,
    collections: ['blog_posts', 'pages'],
  },
  users: {
    count: 10,
    roles: ['admin', 'editor', 'author'],
  },
  media: {
    count: 20,
    types: ['image', 'video', 'document'],
  },
})