Reference základních pluginů

{
  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."
}

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 ) ```
</CodeGroup>

### Bezpečnostní funkce

**Generování tokenů**Tokeny jsou generovány dvojitým použitím crypto.randomUUID() a zřetězením pro maximální entropii

**Omezení počtu požadavků**Omezuje uživatele na 5 žádostí o magický odkaz za hodinu, aby se předešlo zneužití

**Vypršení platnosti**Odkazy automaticky vyprší po 15 minutách

**Jednorázové použití**Každý odkaz lze použít pouze jednou - je označen jako použitý ihned po ověření

**Sledování IP adres**IP adresy a user agenty jsou zaznamenávány pro bezpečnostní audit

### Příklad použití

<CodeGroup title="Adding Magic Link to Login Page">
```html
<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>
}

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 ) ```
</CodeGroup>

### Hooky

- `media:upload` - Spustí se při nahrání souboru (automaticky generuje náhledy)
- `media:delete` - Spustí se při smazání souboru (vyčistí související soubory)
- `content:save` - Sleduje reference na média v obsahu

### Administrační stránky

- **/admin/media** - Prohlížeč knihovny médií
- **/admin/media/upload** - Rozhraní pro nahrávání souborů
- **/admin/media/settings** - Konfigurace zpracování médií

---

## Plugin pro cache

Plugin pro cache implementuje propracovaný tříúrovňový systém cachování pro optimální výkon.

### Funkce

- **Tříúrovňové cachování** - Paměť, Cloudflare KV a databáze D1
- **Automatická invalidace** - Invalidace cache založená na událostech
- **Jmenné prostory cache** - Oddělené cache pro různé typy dat
- **Metriky výkonu** - Míra úspěšnosti (hit rate), latence a statistiky použití
- **Zahřívání cache** - Předvyplnění cache často přistupovanými daty
- **Invalidace podle vzoru** - Invalidace pomocí zástupných znaků (wildcard)
- **Správa TTL** - Konfigurovatelná doba platnosti (time-to-live) pro každý jmenný prostor

### Architektura

Request ↓ Memory Cache? ──Yes──→ Return (< 1ms) ↓ No KV Cache? ──Yes──→ Populate Memory → Return (10-50ms) ↓ No Database ──→ Populate KV → Populate Memory → Return (100-200ms)

### Konfigurace

<CodeGroup title="Cache Configuration">
  ```typescript
  {
    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']
}
})