@nextsparkjs/core 0.1.0-beta.92 → 0.1.0-beta.94

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

@@ -0,0 +1,110 @@
+/**
+ * DevTools Scheduled Actions Run API
+ *
+ * POST /api/v1/devtools/scheduled-actions/run
+ *
+ * Executes a pending action immediately.
+ * 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 } from '@nextsparkjs/core/lib/scheduled-actions/types'
+import { withRateLimitTier } from '@nextsparkjs/core/lib/api/rate-limit'
+import { executeAction } from '@nextsparkjs/core/lib/scheduled-actions/processor'
+
+export const POST = withRateLimitTier(async (request: NextRequest) => {
+  // Authenticate request
+  const authResult = await authenticateRequest(request)
+
+  if (!authResult.success) {
+    return createDevtoolsUnauthorizedResponse()
+  }
+
+  // Check DevTools access permission
+  if (!canAccessDevtoolsApi(authResult)) {
+    return createDevtoolsAccessDeniedResponse()
+  }
+
+  // Parse request body
+  const body = await request.json()
+  const { actionId } = body
+
+  if (!actionId) {
+    return NextResponse.json({
+      success: false,
+      error: 'actionId is required'
+    }, { status: 400 })
+  }
+
+  // Fetch the pending action
+  const actions = await queryWithRLS<ScheduledAction>(
+    `SELECT
+      id,
+      "actionType",
+      status,
+      payload,
+      "teamId",
+      "scheduledAt",
+      attempts,
+      "maxRetries",
+      "recurringInterval",
+      "recurrenceType",
+      "lockGroup"
+    FROM "scheduled_actions"
+    WHERE id = $1`,
+    [actionId],
+    null
+  )
+
+  if (actions.length === 0) {
+    return NextResponse.json({
+      success: false,
+      error: 'Action not found'
+    }, { status: 404 })
+  }
+
+  const action = actions[0]
+
+  // Only allow running pending actions
+  if (action.status !== 'pending') {
+    return NextResponse.json({
+      success: false,
+      error: 'Only pending actions can be executed'
+    }, { status: 400 })
+  }
+
+  try {
+    // Execute the action immediately
+    await executeAction(action)
+
+    return NextResponse.json({
+      success: true,
+      data: {
+        executed: true
+      }
+    })
+  } catch (error) {
+    console.error('[DevTools] Failed to execute action:', error)
+    return NextResponse.json({
+      success: false,
+      error: error instanceof Error ? error.message : 'Failed to execute action'
+    }, { status: 500 })
+  }
+}, 'write');
+
+export async function OPTIONS() {
+  return new NextResponse(null, {
+    status: 204,
+    headers: {
+      'Access-Control-Allow-Methods': 'POST, OPTIONS',
+      'Access-Control-Allow-Headers': 'Content-Type, Authorization, x-api-key',
+    },
+  })
+}

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

@@ -20,8 +20,9 @@ import {
   FEATURE_REGISTRY,
   FLOW_REGISTRY,
 } from '@nextsparkjs/registries/testing-registry'
+import { withRateLimitTier } from '@nextsparkjs/core/lib/api/rate-limit'
 
-export async function GET(request: NextRequest) {
+export const GET = withRateLimitTier(async (request: NextRequest) => {
   // Authenticate request
   const authResult = await authenticateRequest(request)
 
@@ -69,7 +70,7 @@ export async function GET(request: NextRequest) {
       },
     },
   })
-}
+}, 'read');
 
 export async function OPTIONS() {
   return new NextResponse(null, {

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

@@ -0,0 +1,144 @@
+import { NextRequest } from 'next/server'
+import { authenticateRequest, hasRequiredScope } from '@nextsparkjs/core/lib/api/auth/dual-auth'
+import { createApiResponse, createApiError } from '@nextsparkjs/core/lib/api/helpers'
+import { withRateLimitTier } from '@nextsparkjs/core/lib/api/rate-limit'
+import { MediaService } from '@nextsparkjs/core/lib/services/media.service'
+import { updateMediaSchema } from '@nextsparkjs/core/lib/media/schemas'
+
+/**
+ * GET /api/v1/media/:id
+ *
+ * Get a single media item by ID.
+ *
+ * Authentication: Requires valid session or API key with media:read scope
+ * RLS: Returns only media from teams the user is a member of
+ */
+export const GET = withRateLimitTier(async (
+  request: NextRequest,
+  { params }: { params: Promise<{ id: string }> }
+) => {
+  try {
+    // 1. Authenticate
+    const authResult = await authenticateRequest(request)
+    if (!authResult.success) {
+      return createApiError('Unauthorized', 401)
+    }
+
+    // 2. Check permissions
+    if (!hasRequiredScope(authResult, 'media:read')) {
+      return createApiError('Insufficient permissions', 403)
+    }
+
+    // 3. Get media ID from params
+    const { id } = await params
+
+    // 4. Fetch media with RLS
+    const media = await MediaService.getById(id, authResult.user!.id)
+
+    if (!media) {
+      return createApiError('Media not found', 404)
+    }
+
+    return createApiResponse(media)
+  } catch (error) {
+    console.error('[Media API] Error fetching media:', error)
+    return createApiError('Failed to fetch media', 500)
+  }
+}, 'read')
+
+/**
+ * PATCH /api/v1/media/:id
+ *
+ * Update media metadata (alt text and caption).
+ * File properties (url, filename, size, dimensions) are immutable.
+ *
+ * Request Body:
+ * - alt: Alt text for accessibility (max 500 characters, optional)
+ * - caption: Caption or description (max 1000 characters, optional)
+ *
+ * Authentication: Requires valid session or API key with media:write scope
+ * RLS: Can only update media from teams the user is a member of
+ */
+export const PATCH = withRateLimitTier(async (
+  request: NextRequest,
+  { params }: { params: Promise<{ id: string }> }
+) => {
+  try {
+    // 1. Authenticate
+    const authResult = await authenticateRequest(request)
+    if (!authResult.success) {
+      return createApiError('Unauthorized', 401)
+    }
+
+    // 2. Check permissions
+    if (!hasRequiredScope(authResult, 'media:write')) {
+      return createApiError('Insufficient permissions', 403)
+    }
+
+    // 3. Get media ID from params
+    const { id } = await params
+
+    // 4. Parse and validate request body
+    const body = await request.json()
+    const parsed = updateMediaSchema.safeParse(body)
+
+    if (!parsed.success) {
+      return createApiError('Validation failed', 400, {
+        errors: parsed.error.issues,
+      })
+    }
+
+    // 5. Update media with RLS
+    const media = await MediaService.update(id, authResult.user!.id, parsed.data)
+
+    return createApiResponse(media)
+  } catch (error) {
+    console.error('[Media API] Error updating media:', error)
+    return createApiError(
+      error instanceof Error ? error.message : 'Failed to update media',
+      500
+    )
+  }
+}, 'write')
+
+/**
+ * DELETE /api/v1/media/:id
+ *
+ * Soft delete a media item (sets status to 'deleted').
+ * The file remains in storage but is hidden from queries.
+ *
+ * Authentication: Requires valid session or API key with media:delete scope
+ * RLS: Can only delete media from teams the user is a member of
+ */
+export const DELETE = withRateLimitTier(async (
+  request: NextRequest,
+  { params }: { params: Promise<{ id: string }> }
+) => {
+  try {
+    // 1. Authenticate
+    const authResult = await authenticateRequest(request)
+    if (!authResult.success) {
+      return createApiError('Unauthorized', 401)
+    }
+
+    // 2. Check permissions
+    if (!hasRequiredScope(authResult, 'media:delete')) {
+      return createApiError('Insufficient permissions', 403)
+    }
+
+    // 3. Get media ID from params
+    const { id } = await params
+
+    // 4. Soft delete media with RLS
+    const deleted = await MediaService.softDelete(id, authResult.user!.id)
+
+    if (!deleted) {
+      return createApiError('Media not found', 404)
+    }
+
+    return createApiResponse({ message: 'Media deleted successfully' })
+  } catch (error) {
+    console.error('[Media API] Error deleting media:', error)
+    return createApiError('Failed to delete media', 500)
+  }
+}, 'write')

package/templates/app/api/v1/media/[id]/tags/route.ts

@@ -0,0 +1,154 @@
+import { NextRequest } from 'next/server'
+import { authenticateRequest, hasRequiredScope } from '@nextsparkjs/core/lib/api/auth/dual-auth'
+import { createApiResponse, createApiError } from '@nextsparkjs/core/lib/api/helpers'
+import { withRateLimitTier } from '@nextsparkjs/core/lib/api/rate-limit'
+import { MediaService } from '@nextsparkjs/core/lib/services/media.service'
+import { z } from 'zod'
+
+const addTagSchema = z.object({
+  tagId: z.string().min(1),
+})
+
+const setTagsSchema = z.object({
+  tagIds: z.array(z.string().min(1)),
+})
+
+/**
+ * GET /api/v1/media/{id}/tags
+ *
+ * Get all tags assigned to a media item.
+ */
+export const GET = withRateLimitTier(async (
+  request: NextRequest,
+  { params }: { params: Promise<{ id: string }> }
+) => {
+  try {
+    const authResult = await authenticateRequest(request)
+    if (!authResult.success) {
+      return createApiError('Unauthorized', 401)
+    }
+
+    if (!hasRequiredScope(authResult, 'media:read')) {
+      return createApiError('Insufficient permissions', 403)
+    }
+
+    const { id } = await params
+    const tags = await MediaService.getMediaTags(id, authResult.user!.id)
+    return createApiResponse(tags)
+  } catch (error) {
+    console.error('[Media Tags API] Error getting tags:', error)
+    return createApiError('Failed to get media tags', 500)
+  }
+}, 'read')
+
+/**
+ * POST /api/v1/media/{id}/tags
+ *
+ * Add a tag to a media item.
+ * Body: { tagId: string }
+ */
+export const POST = withRateLimitTier(async (
+  request: NextRequest,
+  { params }: { params: Promise<{ id: string }> }
+) => {
+  try {
+    const authResult = await authenticateRequest(request)
+    if (!authResult.success) {
+      return createApiError('Unauthorized', 401)
+    }
+
+    if (!hasRequiredScope(authResult, 'media:write')) {
+      return createApiError('Insufficient permissions', 403)
+    }
+
+    const { id } = await params
+    const body = await request.json()
+    const parsed = addTagSchema.safeParse(body)
+
+    if (!parsed.success) {
+      return createApiError('Invalid request body', 400, { errors: parsed.error.issues })
+    }
+
+    await MediaService.addTag(id, parsed.data.tagId, authResult.user!.id)
+    const tags = await MediaService.getMediaTags(id, authResult.user!.id)
+
+    return createApiResponse(tags, undefined, 201)
+  } catch (error) {
+    console.error('[Media Tags API] Error adding tag:', error)
+    return createApiError('Failed to add tag', 500)
+  }
+}, 'write')
+
+/**
+ * PUT /api/v1/media/{id}/tags
+ *
+ * Replace all tags for a media item.
+ * Body: { tagIds: string[] }
+ */
+export const PUT = withRateLimitTier(async (
+  request: NextRequest,
+  { params }: { params: Promise<{ id: string }> }
+) => {
+  try {
+    const authResult = await authenticateRequest(request)
+    if (!authResult.success) {
+      return createApiError('Unauthorized', 401)
+    }
+
+    if (!hasRequiredScope(authResult, 'media:write')) {
+      return createApiError('Insufficient permissions', 403)
+    }
+
+    const { id } = await params
+    const body = await request.json()
+    const parsed = setTagsSchema.safeParse(body)
+
+    if (!parsed.success) {
+      return createApiError('Invalid request body', 400, { errors: parsed.error.issues })
+    }
+
+    await MediaService.setTags(id, parsed.data.tagIds, authResult.user!.id)
+    const tags = await MediaService.getMediaTags(id, authResult.user!.id)
+
+    return createApiResponse(tags)
+  } catch (error) {
+    console.error('[Media Tags API] Error setting tags:', error)
+    return createApiError('Failed to set tags', 500)
+  }
+}, 'write')
+
+/**
+ * DELETE /api/v1/media/{id}/tags
+ *
+ * Remove a tag from a media item.
+ * Query parameter: tagId
+ */
+export const DELETE = withRateLimitTier(async (
+  request: NextRequest,
+  { params }: { params: Promise<{ id: string }> }
+) => {
+  try {
+    const authResult = await authenticateRequest(request)
+    if (!authResult.success) {
+      return createApiError('Unauthorized', 401)
+    }
+
+    if (!hasRequiredScope(authResult, 'media:delete')) {
+      return createApiError('Insufficient permissions', 403)
+    }
+
+    const { id } = await params
+    const { searchParams } = new URL(request.url)
+    const tagId = searchParams.get('tagId')
+
+    if (!tagId) {
+      return createApiError('tagId query parameter is required', 400)
+    }
+
+    await MediaService.removeTag(id, tagId, authResult.user!.id)
+    return createApiResponse({ success: true })
+  } catch (error) {
+    console.error('[Media Tags API] Error removing tag:', error)
+    return createApiError('Failed to remove tag', 500)
+  }
+}, 'write')

package/templates/app/api/v1/media/check-duplicates/route.ts

@@ -0,0 +1,56 @@
+import { NextRequest } from 'next/server'
+import { authenticateRequest, hasRequiredScope } from '@nextsparkjs/core/lib/api/auth/dual-auth'
+import { createApiResponse, createApiError } from '@nextsparkjs/core/lib/api/helpers'
+import { withRateLimitTier } from '@nextsparkjs/core/lib/api/rate-limit'
+import { MediaService } from '@nextsparkjs/core/lib/services/media.service'
+
+/**
+ * POST /api/v1/media/check-duplicates
+ *
+ * Check if files with the same name+size already exist in the media library.
+ * Used by the upload zone to warn users before uploading duplicates.
+ *
+ * Body: { files: [{ filename: string, fileSize: number }] }
+ * Returns: { duplicates: [{ filename, fileSize, existing: Media[] }] }
+ */
+export const POST = withRateLimitTier(async (request: NextRequest) => {
+  try {
+    const authResult = await authenticateRequest(request)
+    if (!authResult.success) {
+      return createApiError('Unauthorized', 401)
+    }
+
+    if (!hasRequiredScope(authResult, 'media:read')) {
+      return createApiError('Insufficient permissions - media:read scope required', 403)
+    }
+
+    const body = await request.json()
+    const files = body.files as { filename: string; fileSize: number }[]
+
+    if (!files || !Array.isArray(files) || files.length === 0) {
+      return createApiError('files array is required', 400)
+    }
+
+    const duplicates: { filename: string; fileSize: number; existing: { id: string; url: string; createdAt: string }[] }[] = []
+
+    for (const file of files) {
+      const existing = await MediaService.findDuplicates(
+        authResult.user!.id,
+        file.filename,
+        file.fileSize
+      )
+      if (existing.length > 0) {
+        duplicates.push({
+          filename: file.filename,
+          fileSize: file.fileSize,
+          existing: existing.map(m => ({ id: m.id, url: m.url, createdAt: m.createdAt })),
+        })
+      }
+    }
+
+    return createApiResponse({ duplicates })
+  } catch (error) {
+    console.error('Error checking duplicates:', error)
+    return createApiError('Failed to check duplicates', 500)
+  }
+}, 'read')

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

@@ -0,0 +1,56 @@
+import { NextRequest } from 'next/server'
+import { authenticateRequest, hasRequiredScope } from '@nextsparkjs/core/lib/api/auth/dual-auth'
+import { createApiResponse, createApiError } from '@nextsparkjs/core/lib/api/helpers'
+import { withRateLimitTier } from '@nextsparkjs/core/lib/api/rate-limit'
+import { MediaService } from '@nextsparkjs/core/lib/services/media.service'
+import { mediaListQuerySchema } from '@nextsparkjs/core/lib/media/schemas'
+
+/**
+ * GET /api/v1/media
+ *
+ * List media files with pagination, filtering, and search.
+ * Supports filtering by type (image/video), searching by filename, and sorting.
+ *
+ * Query Parameters:
+ * - limit: Number of items per page (default: 20, max: 100)
+ * - offset: Number of items to skip (default: 0)
+ * - orderBy: Sort field (createdAt|filename|fileSize, default: createdAt)
+ * - orderDir: Sort direction (asc|desc, default: desc)
+ * - type: Filter by type (image|video|all, default: all)
+ * - search: Search by filename (case-insensitive)
+ *
+ * Authentication: Requires valid session or API key with media:read scope
+ * RLS: Returns only media from teams the user is a member of
+ */
+export const GET = withRateLimitTier(async (request: NextRequest) => {
+  try {
+    // 1. Authenticate
+    const authResult = await authenticateRequest(request)
+    if (!authResult.success) {
+      return createApiError('Unauthorized', 401)
+    }
+
+    // 2. Check permissions
+    if (!hasRequiredScope(authResult, 'media:read')) {
+      return createApiError('Insufficient permissions - media:read scope required', 403)
+    }
+
+    // 3. Parse and validate query parameters
+    const { searchParams } = new URL(request.url)
+    const parsed = mediaListQuerySchema.safeParse(Object.fromEntries(searchParams))
+
+    if (!parsed.success) {
+      return createApiError('Invalid query parameters', 400, {
+        errors: parsed.error.issues,
+      })
+    }
+
+    // 4. Query media list with RLS
+    const result = await MediaService.list(authResult.user!.id, parsed.data)
+
+    return createApiResponse(result)
+  } catch (error) {
+    console.error('[Media API] Error listing media:', error)
+    return createApiError('Failed to list media', 500)
+  }
+}, 'read')