@nextsparkjs/core 0.1.0-beta.84 → 0.1.0-beta.85

package/templates/app/api/v1/devtools/scheduled-actions/route.ts

@@ -0,0 +1,120 @@
+/**
+ * DevTools Scheduled Actions API
+ *
+ * GET /api/v1/devtools/scheduled-actions
+ *
+ * Returns scheduled actions with filtering and pagination.
+ * Requires superadmin or developer user role.
+ */
+
+import { NextRequest, NextResponse } from 'next/server'
+import { authenticateRequest } from '@nextsparkjs/core/lib/api/auth/dual-auth'
+import {
+  canAccessDevtoolsApi,
+  createDevtoolsAccessDeniedResponse,
+  createDevtoolsUnauthorizedResponse,
+} from '@nextsparkjs/core/lib/api/auth/devtools-auth'
+import { queryWithRLS } from '@nextsparkjs/core/lib/db'
+import type { ScheduledAction, ScheduledActionStatus } from '@nextsparkjs/core/lib/scheduled-actions/types'
+import { getAllRegisteredActions } from '@nextsparkjs/core/lib/scheduled-actions/registry'
+
+export async function GET(request: NextRequest) {
+  // Authenticate request
+  const authResult = await authenticateRequest(request)
+
+  if (!authResult.success) {
+    return createDevtoolsUnauthorizedResponse()
+  }
+
+  // Check DevTools access permission
+  if (!canAccessDevtoolsApi(authResult)) {
+    return createDevtoolsAccessDeniedResponse()
+  }
+
+  // Extract query parameters
+  const searchParams = request.nextUrl.searchParams
+  const status = searchParams.get('status') as ScheduledActionStatus | null
+  const actionType = searchParams.get('action_type')
+  const page = parseInt(searchParams.get('page') || '1', 10)
+  const limit = parseInt(searchParams.get('limit') || '20', 10)
+
+  // Build query
+  const conditions: string[] = []
+  const params: unknown[] = []
+  let paramIndex = 1
+
+  if (status) {
+    conditions.push(`status = $${paramIndex++}`)
+    params.push(status)
+  }
+
+  if (actionType) {
+    conditions.push(`"actionType" = $${paramIndex++}`)
+    params.push(actionType)
+  }
+
+  const whereClause = conditions.length > 0 ? `WHERE ${conditions.join(' AND ')}` : ''
+
+  // Query total count
+  const countQuery = `
+    SELECT COUNT(*) as count
+    FROM "scheduled_actions"
+    ${whereClause}
+  `
+  const countResult = await queryWithRLS<{ count: string }>(countQuery, params, null)
+  const total = parseInt(countResult[0]?.count || '0', 10)
+
+  // Query actions with pagination
+  const offset = (page - 1) * limit
+  const actionsQuery = `
+    SELECT
+      id,
+      "actionType",
+      status,
+      payload,
+      "teamId",
+      "scheduledAt",
+      "startedAt",
+      "completedAt",
+      "errorMessage",
+      attempts,
+      "recurringInterval",
+      "createdAt",
+      "updatedAt"
+    FROM "scheduled_actions"
+    ${whereClause}
+    ORDER BY "createdAt" DESC
+    LIMIT $${paramIndex++}
+    OFFSET $${paramIndex}
+  `
+  const actionsResult = await queryWithRLS<ScheduledAction>(actionsQuery, [...params, limit, offset], null)
+
+  // Get all registered action types
+  const registeredActions = getAllRegisteredActions()
+
+  return NextResponse.json({
+    success: true,
+    data: {
+      actions: actionsResult,
+      pagination: {
+        total,
+        page,
+        limit,
+        totalPages: Math.ceil(total / limit),
+      },
+      meta: {
+        registeredActionTypes: registeredActions,
+      },
+    },
+  })
+}
+
+export async function OPTIONS() {
+  return new NextResponse(null, {
+    status: 204,
+    headers: {
+      'Access-Control-Allow-Methods': 'GET, OPTIONS',
+      'Access-Control-Allow-Headers': 'Content-Type, Authorization, x-api-key',
+    },
+  })
+}

package/templates/app/api/v1/devtools/testing/route.ts

@@ -0,0 +1,82 @@
+/**
+ * DevTools Testing API
+ *
+ * GET /api/v1/devtools/testing
+ *
+ * Returns the complete tags registry with test coverage statistics.
+ * Requires superadmin or developer user role.
+ */
+
+import { NextRequest, NextResponse } from 'next/server'
+import { authenticateRequest } from '@nextsparkjs/core/lib/api/auth/dual-auth'
+import {
+  canAccessDevtoolsApi,
+  createDevtoolsAccessDeniedResponse,
+  createDevtoolsUnauthorizedResponse,
+} from '@nextsparkjs/core/lib/api/auth/devtools-auth'
+import {
+  TAGS_REGISTRY,
+  COVERAGE_SUMMARY,
+  FEATURE_REGISTRY,
+  FLOW_REGISTRY,
+} from '@nextsparkjs/registries/testing-registry'
+
+export async function GET(request: NextRequest) {
+  // Authenticate request
+  const authResult = await authenticateRequest(request)
+
+  if (!authResult.success) {
+    return createDevtoolsUnauthorizedResponse()
+  }
+
+  // Check DevTools access permission
+  if (!canAccessDevtoolsApi(authResult)) {
+    return createDevtoolsAccessDeniedResponse()
+  }
+
+  // Count total tags across all categories
+  let totalTags = 0
+  const categorySummary: Record<string, number> = {}
+
+  for (const [category, tags] of Object.entries(TAGS_REGISTRY)) {
+    const tagCount = Object.keys(tags).length
+    totalTags += tagCount
+    categorySummary[category] = tagCount
+  }
+
+  return NextResponse.json({
+    success: true,
+    data: {
+      tags: TAGS_REGISTRY,
+      summary: {
+        totalTags,
+        testFiles: COVERAGE_SUMMARY.tags.testFiles,
+        byCategory: categorySummary,
+        features: {
+          total: Object.keys(FEATURE_REGISTRY).length,
+          withTests: COVERAGE_SUMMARY.features.withTests,
+          withoutTests: COVERAGE_SUMMARY.features.withoutTests,
+        },
+        flows: {
+          total: Object.keys(FLOW_REGISTRY).length,
+          withTests: COVERAGE_SUMMARY.flows.withTests,
+          withoutTests: COVERAGE_SUMMARY.flows.withoutTests,
+        },
+      },
+      meta: {
+        theme: COVERAGE_SUMMARY.theme,
+        generatedAt: COVERAGE_SUMMARY.generatedAt,
+      },
+    },
+  })
+}
+
+export async function OPTIONS() {
+  return new NextResponse(null, {
+    status: 204,
+    headers: {
+      'Access-Control-Allow-Methods': 'GET, OPTIONS',
+      'Access-Control-Allow-Headers': 'Content-Type, Authorization, x-api-key',
+    },
+  })
+}

package/templates/app/api/v1/media/docs.md

@@ -0,0 +1,117 @@
+# Media API
+
+Upload and manage media files.
+
+## Overview
+
+The Media API provides endpoints for uploading images and videos to Vercel Blob storage. All operations require authentication and appropriate scopes.
+
+## Authentication
+
+All endpoints require authentication via:
+- **Session cookie** (for browser-based requests)
+- **API Key** header with `media:write` or `media:read` scope
+
+## Endpoints
+
+### Upload Files
+`POST /api/v1/media/upload`
+
+Upload one or multiple media files.
+
+**Required Scope:** `media:write`
+
+**Request:**
+- Content-Type: `multipart/form-data`
+- Field name: `files`
+
+**Example (cURL):**
+```bash
+curl -X POST /api/v1/media/upload \
+  -H "x-api-key: sk_live_xxx" \
+  -F "files=@image1.jpg" \
+  -F "files=@image2.png"
+```
+
+**Success Response:**
+```json
+{
+  "success": true,
+  "data": {
+    "message": "Files uploaded successfully",
+    "urls": [
+      "https://xxx.public.blob.vercel-storage.com/uploads/temp/123_abc.jpg",
+      "https://xxx.public.blob.vercel-storage.com/uploads/temp/124_def.png"
+    ],
+    "count": 2
+  }
+}
+```
+
+### Get Upload Info
+`GET /api/v1/media/upload`
+
+Get information about the upload endpoint configuration.
+
+**Required Scope:** `media:read`
+
+**Response:**
+```json
+{
+  "success": true,
+  "data": {
+    "message": "Media upload endpoint is active",
+    "storage": "Vercel Blob",
+    "uploadPath": "uploads/temp/",
+    "supportedTypes": ["image/jpeg", "image/png", "image/gif", "image/webp", "video/mp4", "video/webm"],
+    "maxFileSize": "10MB"
+  }
+}
+```
+
+## Supported File Types
+
+### Images
+- JPEG (`.jpg`, `.jpeg`)
+- PNG (`.png`)
+- GIF (`.gif`)
+- WebP (`.webp`)
+
+### Videos
+- MP4 (`.mp4`)
+- MPEG (`.mpeg`)
+- QuickTime (`.mov`)
+- WebM (`.webm`)
+
+## Limitations
+
+| Limit | Value |
+|-------|-------|
+| Maximum file size | 10 MB |
+| Maximum files per request | No limit |
+| Storage | Vercel Blob (public access) |
+
+## File Naming
+
+Files are renamed on upload using the pattern:
+```
+{timestamp}_{randomString}.{extension}
+```
+
+Example: `1704816000000_a1b2c3d4e5f.jpg`
+
+## Error Responses
+
+| Status | Description |
+|--------|-------------|
+| 400 | Bad Request - No files uploaded or invalid file type |
+| 401 | Unauthorized - Authentication required |
+| 403 | Forbidden - Insufficient permissions |
+| 500 | Server Error - Upload to Vercel Blob failed |
+
+## Usage Notes
+
+- Files are uploaded to `uploads/temp/` directory
+- All uploaded files are publicly accessible
+- Consider implementing cleanup for temporary files
+- The API validates file types by MIME type, not just extension

package/templates/app/api/v1/media/presets.ts

@@ -0,0 +1,24 @@
+/**
+ * API Presets for Media
+ *
+ * These presets appear in the DevTools API Explorer's "Presets" tab.
+ * Note: File upload presets cannot include actual files.
+ */
+
+import { defineApiEndpoint } from '@nextsparkjs/core/types/api-presets'
+
+export default defineApiEndpoint({
+  endpoint: '/api/v1/media',
+  summary: 'Upload and manage media files',
+  presets: [
+    // Get upload info
+    {
+      id: 'get-upload-info',
+      title: 'Get Upload Info',
+      description: 'Get media upload endpoint configuration',
+      method: 'GET',
+      path: '/upload',
+      tags: ['read', 'info']
+    }
+  ]
+})

package/templates/app/api/v1/media/upload/route.ts

@@ -0,0 +1,150 @@
+import { NextRequest } from 'next/server'
+import { put } from '@vercel/blob'
+import { authenticateRequest, hasRequiredScope } from '@nextsparkjs/core/lib/api/auth/dual-auth'
+import { createApiResponse, createApiError } from '@nextsparkjs/core/lib/api/helpers'
+
+export async function POST(request: NextRequest) {
+  try {
+    // 1. Dual Authentication (API Key OR Session)
+    const authResult = await authenticateRequest(request)
+
+    if (!authResult.success) {
+      return createApiError('Unauthorized', 401)
+    }
+
+    // 2. Check permissions for media upload
+    const hasPermission = hasRequiredScope(authResult, 'media:write')
+
+    if (!hasPermission) {
+      return createApiError('Insufficient permissions - media:write scope required', 403)
+    }
+
+    const formData = await request.formData()
+    const files = formData.getAll('files') as File[]
+
+    if (!files || files.length === 0) {
+      return createApiError('No files uploaded', 400)
+    }
+
+    const uploadedUrls: string[] = []
+
+    for (const file of files) {
+      if (!file.size) {
+        continue // Skip empty files
+      }
+
+      // Validate file type (images and videos)
+      const allowedTypes = [
+        'image/jpeg',
+        'image/jpg',
+        'image/png',
+        'image/gif',
+        'image/webp',
+        'video/mp4',
+        'video/mpeg',
+        'video/quicktime',
+        'video/webm'
+      ]
+
+      if (!allowedTypes.includes(file.type)) {
+        return createApiError(
+          `File type ${file.type} not allowed. Only images and videos are supported.`,
+          400,
+          { allowedTypes }
+        )
+      }
+
+      // Validate file size (max 10MB)
+      const maxSize = 10 * 1024 * 1024 // 10MB
+      if (file.size > maxSize) {
+        return createApiError(
+          `File ${file.name} is too large. Maximum size is 10MB.`,
+          400,
+          { maxSize: '10MB', fileSize: `${(file.size / 1024 / 1024).toFixed(2)}MB` }
+        )
+      }
+
+      // Generate unique filename
+      const timestamp = Date.now()
+      const randomString = Math.random().toString(36).substring(2, 15)
+      const extension = file.name.split('.').pop()
+      const fileName = `${timestamp}_${randomString}.${extension}`
+
+      try {
+        // Upload to Vercel Blob
+        const blob = await put(`uploads/temp/${fileName}`, file, {
+          access: 'public',
+          addRandomSuffix: false
+        })
+
+        uploadedUrls.push(blob.url)
+      } catch (fileError) {
+        console.error(`❌ Failed to upload ${file.name} to Vercel Blob:`)
+        console.error(`❌ Error details:`, fileError)
+
+        const errorMessage = fileError instanceof Error ? fileError.message : String(fileError)
+        console.error(`❌ Error message:`, errorMessage)
+
+        if (fileError instanceof Error && fileError.stack) {
+          console.error(`❌ Error stack:`, fileError.stack)
+        }
+
+        return createApiError(
+          `Failed to upload file ${file.name}`,
+          500,
+          { fileName: file.name, error: errorMessage }
+        )
+      }
+    }
+
+    return createApiResponse({
+      message: 'Files uploaded successfully',
+      urls: uploadedUrls,
+      count: uploadedUrls.length
+    })
+
+  } catch (error) {
+    console.error('Error uploading files:', error)
+    return createApiError(
+      'Failed to upload files',
+      500,
+      { error: error instanceof Error ? error.message : String(error) }
+    )
+  }
+}
+
+// Optional: Add a GET endpoint to get upload info
+export async function GET(request: NextRequest) {
+  try {
+    // 1. Dual Authentication (API Key OR Session)
+    const authResult = await authenticateRequest(request)
+
+    if (!authResult.success) {
+      return createApiError('Unauthorized', 401)
+    }
+
+    // 2. Check permissions for media read
+    const hasPermission = hasRequiredScope(authResult, 'media:read')
+
+    if (!hasPermission) {
+      return createApiError('Insufficient permissions - media:read scope required', 403)
+    }
+
+    // This could be used for cleanup or management
+    return createApiResponse({
+      message: 'Media upload endpoint is active',
+      storage: 'Vercel Blob',
+      uploadPath: 'uploads/temp/',
+      supportedTypes: ['image/jpeg', 'image/png', 'image/gif', 'image/webp', 'video/mp4', 'video/webm'],
+      maxFileSize: '10MB'
+    })
+
+  } catch (error) {
+    console.error('Error in media upload GET:', error)
+    return createApiError(
+      'Failed to get upload info',
+      500,
+      { error: error instanceof Error ? error.message : String(error) }
+    )
+  }
+}

package/templates/app/api/v1/patterns/[id]/usages/route.ts

@@ -0,0 +1,116 @@
+/**
+ * Pattern Usages API
+ *
+ * GET /api/v1/patterns/[id]/usages - Get detailed usage information for a pattern
+ *
+ * Query Parameters:
+ * - entityType: Filter by entity type (e.g., 'pages', 'posts')
+ * - limit: Number of results per page (default: 50)
+ * - page: Page number (default: 1)
+ *
+ * Response includes:
+ * - usages: Array of usage records with entity info
+ * - counts: Array of counts by entity type
+ * - total: Total number of usages
+ */
+
+import { NextRequest, NextResponse } from 'next/server'
+import {
+  createApiResponse,
+  createApiError,
+  createPaginationMeta,
+  withApiLogging,
+  handleCorsPreflightRequest,
+  addCorsHeaders,
+} from '@nextsparkjs/core/lib/api/helpers'
+import { authenticateRequest, hasRequiredScope } from '@nextsparkjs/core/lib/api/auth/dual-auth'
+import { PatternUsageService } from '@nextsparkjs/core/lib/services'
+import { queryOneWithRLS } from '@nextsparkjs/core/lib/db'
+
+// Handle CORS preflight
+export async function OPTIONS() {
+  return handleCorsPreflightRequest()
+}
+
+// GET /api/v1/patterns/:id/usages - Get pattern usages
+export const GET = withApiLogging(
+  async (req: NextRequest, { params }: { params: Promise<{ id: string }> }): Promise<NextResponse> => {
+    try {
+      // Authenticate using dual auth
+      const authResult = await authenticateRequest(req)
+
+      if (!authResult.success) {
+        return NextResponse.json(
+          { success: false, error: 'Authentication required', code: 'AUTHENTICATION_FAILED' },
+          { status: 401 }
+        )
+      }
+
+      if (authResult.rateLimitResponse) {
+        return authResult.rateLimitResponse as NextResponse
+      }
+
+      // Check required permissions
+      if (!hasRequiredScope(authResult, 'patterns:read')) {
+        const response = createApiError('Insufficient permissions', 403)
+        return addCorsHeaders(response)
+      }
+
+      const { id: patternId } = await params
+      const userId = authResult.user!.id
+
+      // Validate that patternId is not empty
+      if (!patternId || patternId.trim() === '') {
+        const response = createApiError('Pattern ID is required', 400, null, 'MISSING_PATTERN_ID')
+        return addCorsHeaders(response)
+      }
+
+      // Verify pattern exists and user has access
+      const pattern = await queryOneWithRLS<{ id: string }>(
+        'SELECT id FROM "patterns" WHERE id = $1',
+        [patternId],
+        userId
+      )
+
+      if (!pattern) {
+        const response = createApiError('Pattern not found', 404, null, 'PATTERN_NOT_FOUND')
+        return addCorsHeaders(response)
+      }
+
+      // Parse query parameters
+      const url = new URL(req.url)
+      const entityType = url.searchParams.get('entityType') || undefined
+      const limit = Math.min(parseInt(url.searchParams.get('limit') || '50', 10), 100)
+      const page = Math.max(parseInt(url.searchParams.get('page') || '1', 10), 1)
+      const offset = (page - 1) * limit
+
+      // Get usages with entity info
+      const result = await PatternUsageService.getUsagesWithEntityInfo(
+        patternId,
+        userId,
+        { entityType, limit, offset }
+      )
+
+      // Create pagination meta
+      const totalPages = Math.ceil(result.total / limit)
+      const paginationMeta = createPaginationMeta(page, limit, result.total)
+
+      const response = createApiResponse({
+        usages: result.usages,
+        counts: result.counts,
+        total: result.total,
+      }, {
+        ...paginationMeta,
+        totalPages,
+        patternId,
+        entityType: entityType || 'all',
+      })
+
+      return addCorsHeaders(response)
+    } catch (error) {
+      console.error('Error fetching pattern usages:', error)
+      const response = createApiError('Internal server error', 500)
+      return addCorsHeaders(response)
+    }
+  }
+)