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

package/dist/templates/app/api/v1/blocks/docs.md

@@ -0,0 +1,173 @@
+# Blocks API
+
+Access and validate page builder blocks registered in the application.
+
+## Overview
+
+The Blocks API provides read-only access to block metadata from the block registry. Blocks are reusable content components used in the page builder. This API allows you to list available blocks, retrieve individual block details, and validate block properties against their schemas.
+
+## Authentication
+
+These endpoints are **public** (no authentication required) as block metadata is not sensitive.
+
+## Endpoints
+
+### List Blocks
+`GET /api/v1/blocks`
+
+Returns all registered blocks with their metadata.
+
+**Query Parameters:**
+- `category` (string, optional): Filter by block category (e.g., "hero", "content", "cta")
+- `scope` (string, optional): Filter by allowed scope (e.g., "pages", "posts")
+
+**Example Response:**
+```json
+{
+  "success": true,
+  "data": [
+    {
+      "slug": "hero-simple",
+      "name": "Simple Hero",
+      "description": "A simple hero block with title and subtitle",
+      "category": "hero",
+      "icon": "Layout",
+      "thumbnail": "/blocks/hero-simple.png",
+      "scope": ["pages"],
+      "fieldDefinitions": [
+        {
+          "name": "title",
+          "type": "text",
+          "label": "Title",
+          "required": true
+        },
+        {
+          "name": "subtitle",
+          "type": "text",
+          "label": "Subtitle"
+        }
+      ]
+    }
+  ],
+  "meta": {
+    "categories": ["hero", "content", "cta", "testimonials", "faq"],
+    "total": 15
+  }
+}
+```
+
+### Get Block by Slug
+`GET /api/v1/blocks/[slug]`
+
+Returns detailed metadata for a specific block.
+
+**Path Parameters:**
+- `slug` (string, required): The block identifier (e.g., "hero-simple", "faq-accordion")
+
+**Example Response:**
+```json
+{
+  "slug": "faq-accordion",
+  "name": "FAQ Accordion",
+  "description": "Expandable FAQ section with questions and answers",
+  "category": "faq",
+  "icon": "HelpCircle",
+  "thumbnail": "/blocks/faq-accordion.png",
+  "fieldDefinitions": [
+    {
+      "name": "title",
+      "type": "text",
+      "label": "Section Title"
+    },
+    {
+      "name": "items",
+      "type": "repeater",
+      "label": "FAQ Items",
+      "fields": [
+        { "name": "question", "type": "text", "label": "Question" },
+        { "name": "answer", "type": "richtext", "label": "Answer" }
+      ]
+    }
+  ]
+}
+```
+
+### Validate Block Props
+`POST /api/v1/blocks/validate`
+
+Validates block properties against the block's Zod schema.
+
+**Request Body:**
+```json
+{
+  "blockSlug": "hero-simple",
+  "props": {
+    "title": "Welcome to Our Site",
+    "subtitle": "Discover what we offer"
+  }
+}
+```
+
+**Success Response:**
+```json
+{
+  "valid": true
+}
+```
+
+**Validation Error Response (400):**
+```json
+{
+  "valid": false,
+  "errors": [
+    {
+      "code": "invalid_type",
+      "expected": "string",
+      "received": "undefined",
+      "path": ["title"],
+      "message": "Required"
+    }
+  ]
+}
+```
+
+## Error Responses
+
+| Status | Description |
+|--------|-------------|
+| 400 | Bad Request - Invalid request body or validation failed |
+| 404 | Not Found - Block with specified slug not found |
+| 500 | Server Error - Internal error or missing schema |
+
+## Block Categories
+
+Common block categories include:
+- `hero` - Hero sections and page headers
+- `content` - General content blocks (text, images, galleries)
+- `cta` - Call-to-action sections
+- `testimonials` - Customer testimonials and reviews
+- `faq` - Frequently asked questions
+- `pricing` - Pricing tables and plans
+- `features` - Feature lists and grids
+- `contact` - Contact forms and information
+
+## Field Types
+
+Block field definitions use these types:
+- `text` - Single line text input
+- `textarea` - Multi-line text
+- `richtext` - Rich text editor (HTML)
+- `number` - Numeric input
+- `select` - Dropdown selection
+- `checkbox` - Boolean toggle
+- `image` - Image upload/selection
+- `link` - URL with label
+- `repeater` - Repeatable group of fields
+- `group` - Nested field group
+
+## Usage Notes
+
+- Block slugs are unique identifiers in kebab-case
+- Field definitions describe the editable properties of each block
+- The `scope` property indicates where blocks can be used (pages, posts, etc.)
+- Use the validate endpoint before saving block content to ensure data integrity

package/dist/templates/app/api/v1/blocks/presets.ts

@@ -0,0 +1,121 @@
+/**
+ * API Presets for Blocks
+ *
+ * These presets appear in the DevTools API Explorer's "Presets" tab.
+ */
+
+import { defineApiEndpoint } from '@nextsparkjs/core/types/api-presets'
+
+export default defineApiEndpoint({
+  endpoint: '/api/v1/blocks',
+  summary: 'Access and validate page builder blocks',
+  presets: [
+    // List blocks
+    {
+      id: 'list-all',
+      title: 'List All Blocks',
+      description: 'Fetch all registered blocks with metadata',
+      method: 'GET',
+      tags: ['read', 'list']
+    },
+    {
+      id: 'list-hero-blocks',
+      title: 'List Hero Blocks',
+      description: 'Filter blocks by hero category',
+      method: 'GET',
+      queryParams: {
+        category: 'hero'
+      },
+      tags: ['read', 'list', 'filter']
+    },
+    {
+      id: 'list-content-blocks',
+      title: 'List Content Blocks',
+      description: 'Filter blocks by content category',
+      method: 'GET',
+      queryParams: {
+        category: 'content'
+      },
+      tags: ['read', 'list', 'filter']
+    },
+    {
+      id: 'list-page-blocks',
+      title: 'List Page Blocks',
+      description: 'Filter blocks available for pages',
+      method: 'GET',
+      queryParams: {
+        scope: 'pages'
+      },
+      tags: ['read', 'list', 'filter']
+    },
+
+    // Get specific block
+    {
+      id: 'get-hero-simple',
+      title: 'Get Hero Simple',
+      description: 'Fetch hero-simple block metadata',
+      method: 'GET',
+      path: '/hero-simple',
+      tags: ['read', 'single']
+    },
+    {
+      id: 'get-faq-accordion',
+      title: 'Get FAQ Accordion',
+      description: 'Fetch faq-accordion block metadata',
+      method: 'GET',
+      path: '/faq-accordion',
+      tags: ['read', 'single']
+    },
+
+    // Validate
+    {
+      id: 'validate-hero',
+      title: 'Validate Hero Props',
+      description: 'Validate hero block properties',
+      method: 'POST',
+      path: '/validate',
+      payload: {
+        blockSlug: 'hero-simple',
+        props: {
+          title: 'Welcome to Our Site',
+          subtitle: 'Discover amazing features'
+        }
+      },
+      tags: ['write', 'validate']
+    },
+    {
+      id: 'validate-faq',
+      title: 'Validate FAQ Props',
+      description: 'Validate FAQ block with items',
+      method: 'POST',
+      path: '/validate',
+      payload: {
+        blockSlug: 'faq-accordion',
+        props: {
+          title: 'Frequently Asked Questions',
+          items: [
+            {
+              question: 'How does it work?',
+              answer: 'It works seamlessly with your existing workflow.'
+            }
+          ]
+        }
+      },
+      tags: ['write', 'validate']
+    },
+    {
+      id: 'validate-invalid',
+      title: 'Validate Invalid Props',
+      description: 'Test validation error response (missing required field)',
+      method: 'POST',
+      path: '/validate',
+      payload: {
+        blockSlug: 'hero-simple',
+        props: {
+          subtitle: 'Missing required title field'
+        }
+      },
+      tags: ['write', 'validate', 'error']
+    }
+  ]
+})

package/dist/templates/app/api/v1/blocks/route.ts

@@ -0,0 +1,45 @@
+import { NextRequest, NextResponse } from 'next/server'
+import { BLOCK_REGISTRY, BLOCK_CATEGORIES } from '@nextsparkjs/registries/block-registry'
+
+export async function GET(request: NextRequest) {
+  try {
+    const { searchParams } = new URL(request.url)
+    const category = searchParams.get('category')
+    const scope = searchParams.get('scope')
+
+    let blocks = Object.values(BLOCK_REGISTRY)
+
+    // Filter by category
+    if (category) {
+      blocks = blocks.filter(block => block.category === category)
+    }
+
+    // Filter by scope (pages, posts, etc.)
+    if (scope) {
+      blocks = blocks.filter(block => block.scope?.includes(scope))
+    }
+
+    const blocksMetadata = blocks.map(block => ({
+      slug: block.slug,
+      name: block.name,
+      description: block.description,
+      category: block.category,
+      icon: block.icon,
+      thumbnail: block.thumbnail,
+      fieldDefinitions: block.fieldDefinitions,
+      scope: block.scope
+    }))
+
+    return NextResponse.json({
+      success: true,
+      data: blocksMetadata,
+      meta: {
+        categories: BLOCK_CATEGORIES,
+        total: blocksMetadata.length
+      }
+    })
+  } catch (err) {
+    console.error('Error listing blocks:', err)
+    return NextResponse.json({ success: false, error: 'Internal server error' }, { status: 500 })
+  }
+}

package/dist/templates/app/api/v1/blocks/validate/route.ts

@@ -0,0 +1,45 @@
+import { NextRequest, NextResponse } from 'next/server'
+import { BLOCK_REGISTRY } from '@nextsparkjs/registries/block-registry'
+import { z } from 'zod'
+
+const requestSchema = z.object({
+  blockSlug: z.string(),
+  props: z.record(z.string(), z.unknown())
+})
+
+export async function POST(request: NextRequest) {
+  try {
+    const body = await request.json()
+    const { blockSlug, props } = requestSchema.parse(body)
+
+    const block = BLOCK_REGISTRY[blockSlug]
+
+    if (!block) {
+      return NextResponse.json({ error: 'Block not found' }, { status: 404 })
+    }
+
+    if (!block.schemaPath) {
+      return NextResponse.json({ error: 'Block schema not found' }, { status: 500 })
+    }
+
+    try {
+      // Dynamic import is allowed here (server-side validation, not registry loading)
+      const schemaModule = await import(block.schemaPath)
+      const schema = schemaModule.schema
+
+      schema.parse(props)
+      return NextResponse.json({ valid: true })
+    } catch (error) {
+      if (error instanceof z.ZodError) {
+        return NextResponse.json({
+          valid: false,
+          errors: error.issues
+        }, { status: 400 })
+      }
+      throw error
+    }
+  } catch (err) {
+    console.error('Error validating block:', err)
+    return NextResponse.json({ error: 'Internal server error' }, { status: 500 })
+  }
+}

package/dist/templates/app/api/v1/cron/docs.md

@@ -0,0 +1,116 @@
+# Cron API
+
+Process scheduled actions via external cron service.
+
+## Overview
+
+The Cron API provides an endpoint for processing scheduled actions. This endpoint is designed to be called by an external cron service (e.g., cron-job.org, Vercel Cron, GitHub Actions) at regular intervals.
+
+## Authentication
+
+The endpoint is protected by `CRON_SECRET` header validation. This prevents unauthorized access while allowing external cron services to trigger processing.
+
+**Required Header:**
+```
+x-cron-secret: your_cron_secret_value
+```
+
+## Endpoints
+
+### Process Scheduled Actions
+`GET /api/v1/cron/process`
+
+Process pending scheduled actions and clean up old completed actions.
+
+**Request Headers:**
+```
+x-cron-secret: {CRON_SECRET}
+```
+
+**Success Response:**
+```json
+{
+  "success": true,
+  "data": {
+    "processing": {
+      "processed": 5,
+      "succeeded": 4,
+      "failed": 1,
+      "details": [
+        {
+          "actionId": "action_123",
+          "actionType": "send-email",
+          "status": "completed",
+          "duration": 150
+        }
+      ]
+    },
+    "cleanup": {
+      "deletedCount": 12
+    },
+    "executionTime": 2345
+  },
+  "info": {
+    "timestamp": "2024-01-15T10:00:00.000Z"
+  }
+}
+```
+
+## Configuration
+
+### Environment Variables
+
+| Variable | Description | Required |
+|----------|-------------|----------|
+| `CRON_SECRET` | Secret token for authentication | Yes |
+
+### Recommended Setup
+
+**Vercel Cron (vercel.json):**
+```json
+{
+  "crons": [
+    {
+      "path": "/api/v1/cron/process",
+      "schedule": "* * * * *"
+    }
+  ]
+}
+```
+
+**External Cron Service:**
+- URL: `https://your-domain.com/api/v1/cron/process`
+- Method: GET
+- Header: `x-cron-secret: {your_secret}`
+- Frequency: Every 1 minute
+
+## Processing Details
+
+Each execution:
+1. Validates `CRON_SECRET` header
+2. Processes up to 10 pending actions
+3. Cleans up actions older than 7 days
+4. Returns processing results
+
+## Scheduled Actions
+
+Actions are registered in the `scheduled_actions` table and processed based on:
+- `status = 'pending'`
+- `scheduledAt <= now()`
+
+Each action type has a registered handler that executes the business logic.
+
+## Error Responses
+
+| Status | Code | Description |
+|--------|------|-------------|
+| 401 | INVALID_CRON_SECRET | Missing or invalid cron secret |
+| 500 | CRON_SECRET_NOT_CONFIGURED | CRON_SECRET env var not set |
+| 500 | PROCESSING_ERROR | Error during action processing |
+
+## Security Notes
+
+- Never expose `CRON_SECRET` in client-side code
+- Use HTTPS for the cron endpoint
+- Consider IP allowlisting for additional security
+- Monitor failed authentication attempts

package/dist/templates/app/api/v1/cron/presets.ts

@@ -0,0 +1,26 @@
+/**
+ * API Presets for Cron
+ *
+ * These presets appear in the DevTools API Explorer's "Presets" tab.
+ * Note: These require CRON_SECRET header which should be configured in environment.
+ */
+
+import { defineApiEndpoint } from '@nextsparkjs/core/types/api-presets'
+
+export default defineApiEndpoint({
+  endpoint: '/api/v1/cron',
+  summary: 'Process scheduled actions via cron',
+  presets: [
+    {
+      id: 'process-actions',
+      title: 'Process Scheduled Actions',
+      description: 'Process pending actions (requires CRON_SECRET header)',
+      method: 'GET',
+      path: '/process',
+      headers: {
+        'x-cron-secret': '{{CRON_SECRET}}'
+      },
+      tags: ['write', 'cron']
+    }
+  ]
+})

package/dist/templates/app/api/v1/cron/process/route.ts

@@ -0,0 +1,108 @@
+/**
+ * Cron Endpoint - Process Scheduled Actions
+ * GET /api/v1/cron/process
+ *
+ * This endpoint is designed to be called by an external cron service
+ * (e.g., cron-job.org, Vercel Cron, GitHub Actions)
+ *
+ * Authentication: Requires CRON_SECRET header
+ * Frequency: Recommended every 1 minute
+ */
+
+import { NextRequest, NextResponse } from 'next/server'
+import {
+  processPendingActions,
+  cleanupOldActions,
+  initializeScheduledActions
+} from '@nextsparkjs/core/lib/scheduled-actions'
+import type { ProcessResult } from '@nextsparkjs/core/lib/scheduled-actions'
+
+/**
+ * Process pending scheduled actions
+ * Protected by CRON_SECRET for security
+ */
+export async function GET(request: NextRequest): Promise<NextResponse> {
+  const startTime = Date.now()
+
+  // Ensure action handlers are registered in this context
+  // (initializeScheduledActions has its own guard against duplicates)
+  initializeScheduledActions()
+
+  try {
+    // Validate CRON_SECRET
+    const cronSecret = request.headers.get('x-cron-secret')
+    const expectedSecret = process.env.CRON_SECRET
+
+    if (!expectedSecret) {
+      console.error('[Cron] CRON_SECRET environment variable is not set')
+      return NextResponse.json(
+        {
+          success: false,
+          error: 'Server configuration error',
+          code: 'CRON_SECRET_NOT_CONFIGURED'
+        },
+        { status: 500 }
+      )
+    }
+
+    if (!cronSecret || cronSecret !== expectedSecret) {
+      console.warn('[Cron] Unauthorized cron request attempt')
+      return NextResponse.json(
+        {
+          success: false,
+          error: 'Unauthorized',
+          code: 'INVALID_CRON_SECRET'
+        },
+        { status: 401 }
+      )
+    }
+
+    console.log('[Cron] Starting scheduled actions processing')
+
+    // Process pending actions (batch of 10 max)
+    const processResult: ProcessResult = await processPendingActions(10)
+
+    // Optionally run cleanup (every 24th run if called every hour)
+    // For now, run cleanup every time (can be optimized later)
+    const cleanupCount = await cleanupOldActions(7)
+
+    const executionTime = Date.now() - startTime
+
+    console.log(`[Cron] Processing complete in ${executionTime}ms`)
+
+    return NextResponse.json(
+      {
+        success: true,
+        data: {
+          processing: processResult,
+          cleanup: {
+            deletedCount: cleanupCount
+          },
+          executionTime
+        },
+        info: {
+          timestamp: new Date().toISOString()
+        }
+      },
+      { status: 200 }
+    )
+  } catch (error) {
+    const executionTime = Date.now() - startTime
+
+    console.error('[Cron] Error processing scheduled actions:', error)
+
+    return NextResponse.json(
+      {
+        success: false,
+        error: 'Internal server error',
+        code: 'PROCESSING_ERROR',
+        details: error instanceof Error ? error.message : 'Unknown error',
+        info: {
+          timestamp: new Date().toISOString(),
+          executionTime
+        }
+      },
+      { status: 500 }
+    )
+  }
+}