@nextsparkjs/core 0.1.0-beta.8 → 0.1.0-beta.82

package/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/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/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/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/templates/app/api/v1/devtools/docs/route.ts

@@ -0,0 +1,150 @@
+/**
+ * DevTools API Documentation Endpoint
+ *
+ * Serves markdown documentation files for API endpoints.
+ * Used by the API Explorer to display endpoint documentation.
+ *
+ * Supports both monorepo and npm modes:
+ * - Monorepo: themes at repo root (themes/{theme}/...)
+ * - NPM: themes in contents directory (contents/themes/{theme}/...)
+ *
+ * GET /api/v1/devtools/docs?path={path}
+ */
+
+import { NextRequest, NextResponse } from 'next/server'
+import { readFile } from 'fs/promises'
+import { join, dirname } from 'path'
+import { existsSync } from 'fs'
+
+/**
+ * Valid path patterns for documentation files
+ * Supports both monorepo mode (themes/) and npm mode (contents/themes/)
+ */
+const VALID_PATH_PATTERNS = [
+  // Entity folders
+  /^(contents\/)?themes\/[\w-]+\/entities\/[\w-]+\/api\/docs\.md$/,
+  // Theme routes
+  /^(contents\/)?themes\/[\w-]+\/app\/api\/.*\/docs\.md$/,
+  // Core routes (monorepo mode)
+  /^packages\/core\/templates\/app\/api\/.*\/docs\.md$/,
+  // Core routes (NPM mode)
+  /^node_modules\/@nextsparkjs\/core\/templates\/app\/api\/.*\/docs\.md$/,
+  // Legacy devtools/api location (for backwards compatibility)
+  /^(contents\/)?themes\/[\w-]+\/devtools\/api\/[\w-]+\.md$/
+]
+
+/**
+ * Validate that a path matches one of the allowed patterns
+ */
+function isValidPath(path: string): boolean {
+  return VALID_PATH_PATTERNS.some(pattern => pattern.test(path))
+}
+
+/**
+ * Detect monorepo root by searching for pnpm-workspace.yaml
+ */
+function detectMonorepoRoot(startDir: string): string | null {
+  let dir = startDir
+  const maxDepth = 10
+  let depth = 0
+
+  while (dir !== '/' && depth < maxDepth) {
+    if (existsSync(join(dir, 'pnpm-workspace.yaml'))) {
+      return dir
+    }
+    dir = dirname(dir)
+    depth++
+  }
+
+  return null
+}
+
+/**
+ * Get all possible base paths for resolving doc files
+ * Handles both monorepo and npm modes
+ */
+function getBasePaths(): string[] {
+  const cwd = process.cwd()
+  const paths: string[] = []
+
+  // Always try cwd first (works for npm mode with contents/)
+  paths.push(cwd)
+
+  // Check if we're in monorepo mode
+  const monorepoRoot = detectMonorepoRoot(cwd)
+  if (monorepoRoot && monorepoRoot !== cwd) {
+    // In monorepo, themes are at repo root
+    paths.push(monorepoRoot)
+  }
+
+  return paths
+}
+
+export async function GET(request: NextRequest) {
+  const searchParams = request.nextUrl.searchParams
+  const docPath = searchParams.get('path')
+
+  if (!docPath) {
+    return NextResponse.json(
+      { error: 'Missing path parameter' },
+      { status: 400 }
+    )
+  }
+
+  // Validate path to prevent directory traversal
+  if (docPath.includes('..')) {
+    return NextResponse.json(
+      { error: 'Invalid path: directory traversal not allowed' },
+      { status: 400 }
+    )
+  }
+
+  // Validate path matches allowed patterns
+  if (!isValidPath(docPath)) {
+    return NextResponse.json(
+      { error: 'Invalid path: does not match allowed patterns' },
+      { status: 400 }
+    )
+  }
+
+  // Only allow .md files
+  if (!docPath.endsWith('.md')) {
+    return NextResponse.json(
+      { error: 'Only markdown files are allowed' },
+      { status: 400 }
+    )
+  }
+
+  try {
+    // Try all possible base paths
+    const basePaths = getBasePaths()
+
+    let fullPath: string | null = null
+    for (const base of basePaths) {
+      const testPath = join(base, docPath)
+      if (existsSync(testPath)) {
+        fullPath = testPath
+        break
+      }
+    }
+
+    // Check if file exists
+    if (!fullPath) {
+      return NextResponse.json(
+        { error: 'Document not found' },
+        { status: 404 }
+      )
+    }
+
+    // Read the markdown file
+    const content = await readFile(fullPath, 'utf-8')
+
+    return NextResponse.json({ content })
+  } catch (error) {
+    console.error('Error reading documentation:', error)
+    return NextResponse.json(
+      { error: 'Failed to read document' },
+      { status: 500 }
+    )
+  }
+}