Troubleshooting Guide

// Correct format - Authorization header
fetch('/api/content', {
  headers: {
    'Authorization': 'Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...'
  }
})

// Or use cookies (set by login endpoint)
fetch('/api/content', {
  credentials: 'include'  // Include cookies in request
})

// Call refresh endpoint before token expires
const response = await fetch('/auth/refresh', {
  method: 'POST',
  credentials: 'include'
})

if (response.ok) {
  // New token automatically set in cookie
  console.log('Token refreshed')
} else {
  // Redirect to login
  window.location.href = '/admin/login'
}

// Available roles (most to least privileged)
const roles = ['admin', 'editor', 'author', 'viewer']

// Create user with specific role
await db.prepare(`
  INSERT INTO users (email, password, role)
  VALUES (?, ?, ?)
`).bind(email, hashedPassword, 'editor').run()

// SonicJS normalizes emails to lowercase
const normalizedEmail = email.toLowerCase().trim()

// Ensure consistency when checking credentials

// Auto-generate unique slug
function generateUniqueSlug(title: string, existingSlugs: string[]): string {
  let slug = title
    .toLowerCase()
    .replace(/[^a-z0-9]+/g, '-')
    .replace(/(^-|-$)/g, '')

  let counter = 1
  let uniqueSlug = slug

  while (existingSlugs.includes(uniqueSlug)) {
    uniqueSlug = `${slug}-${counter}`
    counter++
  }

  return uniqueSlug
}

// Check before registration
const existing = await db
  .prepare('SELECT id FROM users WHERE email = ? OR username = ?')
  .bind(email.toLowerCase(), username)
  .first()

if (existing) {
  return c.json({ error: 'User already exists' }, 400)
}

try {
  await db.prepare('INSERT INTO users (email) VALUES (?)').bind(email).run()
} catch (error) {
  if (error.message.includes('UNIQUE constraint failed')) {
    // Handle duplicate gracefully
    return c.json({ error: 'Email already exists' }, 400)
  }
  throw error
}

# wrangler.toml - Ensure KV binding exists
[[kv_namespaces]]
binding = "CACHE_KV"
id = "your-kv-namespace-id"

// Verify cache is working
const cacheService = new CacheService(env.CACHE_KV)

// Test cache operations
await cacheService.set('test-key', { value: 'test' }, 60)
const result = await cacheService.get('test-key')

if (!result) {
  console.error('Cache write/read failed')
}

import { CacheInvalidationService } from '@sonicjs-cms/core/plugins'

const invalidation = new CacheInvalidationService(env.CACHE_KV)

// Invalidate content cache
await invalidation.invalidateContent(contentId)

// Invalidate user cache
await invalidation.invalidateUser(userId)

// Invalidate collection cache
await invalidation.invalidateCollection(collectionId)

// Short TTL for frequently changing data
await cache.set('user-session', data, 300)  // 5 minutes

// Longer TTL for stable content
await cache.set('collection-schema', schema, 3600)  // 1 hour

// Very long TTL for static assets
await cache.set('site-config', config, 86400)  // 24 hours

# wrangler.toml
[vars]
DEFAULT_FROM_EMAIL = "[email protected]"
DEFAULT_FROM_NAME = "Your App"

# Set API key as secret
# npx wrangler secret put SENDGRID_API_KEY

// In admin: Plugins > Enable Email Templates
// Or programmatically:
const settings = await getPluginSettings('email-templates')
console.log('Email enabled:', settings.enabled)

// List available templates
const templates = await db
  .prepare('SELECT slug, name, is_active FROM email_templates')
  .all()

console.log('Available templates:', templates.results)

// Ensure template is active
await db
  .prepare('UPDATE email_templates SET is_active = 1 WHERE slug = ?')
  .bind('welcome-email')
  .run()

import { PluginValidator } from '@sonicjs-cms/core/plugins'

const validation = PluginValidator.validate(myPlugin)

if (!validation.valid) {
  console.error('Plugin validation errors:', validation.errors)
  // Fix issues before installing
}

// Valid
'my-plugin'
'analytics-v2'
'custom-auth'

// Invalid
'MyPlugin'      // No uppercase
'my plugin'     // No spaces
'my_plugin'     // No underscores

// Bad - causes recursion
hooks.register('content:save', async (data) => {
  // This triggers content:save again!
  await db.prepare('UPDATE content SET ...').run()
  return data
})

// Good - use flag to prevent recursion
hooks.register('content:save', async (data, context) => {
  if (context.fromHook) return data

  // Safe to update with flag
  await db.prepare('UPDATE content SET ...').run()
  return data
})

import { defineCollection } from '@sonicjs-cms/core'

export default defineCollection({
  name: 'blog_posts',          // Required
  displayName: 'Blog Posts',   // Required
  schema: {                    // Required
    title: { type: 'string', required: true },
    content: { type: 'richtext' }
  }
})

// Valid
'blog_posts'
'user-profiles'
'faq'

// Invalid
'BlogPosts'      // No uppercase
'blog posts'     // No spaces
'blog.posts'     // No dots

// Force re-bootstrap on specific errors
import { runMigrations } from '@sonicjs-cms/core'

// Re-run migrations
await runMigrations(db)

// Re-sync collections
await collectionSync.syncAll()

# Set initial admin via environment
# wrangler.toml or secrets
ADMIN_EMAIL=[email protected]
ADMIN_PASSWORD=your-secure-password

curl -X POST https://your-app.workers.dev/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "your-secure-password",
    "username": "admin"
  }'

import { Logger } from '@sonicjs-cms/core'

const logger = new Logger(db, {
  level: 'debug',  // debug, info, warn, error, fatal
  category: 'my-feature'
})

// Log with context
logger.debug('Processing request', { userId, action })
logger.info('Operation completed', { duration: Date.now() - start })
logger.error('Operation failed', { error: error.message })

// Get recent logs
const logs = await db
  .prepare(`
    SELECT * FROM logs
    WHERE created_at > datetime('now', '-1 hour')
    ORDER BY created_at DESC
    LIMIT 100
  `)
  .all()

// Filter by category
const authLogs = await db
  .prepare(`
    SELECT * FROM logs
    WHERE category = 'auth'
    ORDER BY created_at DESC
  `)
  .all()

# wrangler.toml
[env.development.vars]
ENVIRONMENT = "development"
DEBUG = "true"

// In your plugin
builder.setLogger((msg, level) => {
  console.log(`[Plugin:my-plugin] [${level}] ${msg}`)
})

{
  "error": "Human-readable error message",
  "details": "Technical details (in development)",
  "code": "ERROR_CODE"
}