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

package/dist/templates/app/api/v1/post-categories/[id]/route.ts

@@ -0,0 +1,255 @@
+import { NextRequest, NextResponse } from 'next/server'
+import { authenticateRequest } from '@nextsparkjs/core/lib/api/auth/dual-auth'
+import { query as dbQuery } from '@nextsparkjs/core/lib/db'
+import { z } from 'zod'
+
+const updateCategorySchema = z.object({
+  name: z.string().min(1).max(255).optional(),
+  slug: z.string().min(2).max(100).regex(/^[a-z0-9-]+$/, 'Slug must be lowercase alphanumeric with dashes').optional(),
+  description: z.string().optional(),
+  icon: z.string().optional(),
+  color: z.string().optional(),
+  parentId: z.string().optional(),
+  order: z.number().int().optional(),
+  isDefault: z.boolean().optional(),
+  isActive: z.boolean().optional()
+})
+
+// GET /api/v1/post-categories/:id - Get category by ID
+export async function GET(
+  request: NextRequest,
+  { params }: { params: Promise<{ id: string }> }
+): Promise<NextResponse> {
+  try {
+    const { id } = await params
+
+    const result = await dbQuery(
+      `SELECT id, name, slug, description, icon, color, "parentId", "order", "isDefault", "isActive",
+              "createdAt", "updatedAt"
+       FROM taxonomies
+       WHERE id = $1 AND type = 'post_category' AND "deletedAt" IS NULL`,
+      [id]
+    )
+
+    if (result.rows.length === 0) {
+      return NextResponse.json({ success: false, error: 'Category not found' }, { status: 404 })
+    }
+
+    return NextResponse.json({
+      success: true,
+      data: result.rows[0]
+    })
+  } catch (err) {
+    console.error('Error in post-categories API:', err)
+    return NextResponse.json({ success: false, error: 'Internal server error' }, { status: 500 })
+  }
+}
+
+// PUT /api/v1/post-categories/:id - Update category
+export async function PUT(
+  request: NextRequest,
+  { params }: { params: Promise<{ id: string }> }
+): Promise<NextResponse> {
+  try {
+    // Dual authentication: API key or session
+    const authResult = await authenticateRequest(request)
+    if (!authResult.success || !authResult.user) {
+      return NextResponse.json({ success: false, error: 'Unauthorized' }, { status: 401 })
+    }
+
+    const body = await request.json()
+    const data = updateCategorySchema.parse(body)
+    const { id } = await params
+
+    // Verify this is a post_category taxonomy
+    const typeCheck = await dbQuery(
+      'SELECT id FROM taxonomies WHERE id = $1 AND type = \'post_category\'',
+      [id]
+    )
+
+    if (typeCheck.rows.length === 0) {
+      return NextResponse.json({ success: false, error: 'Category not found' }, { status: 404 })
+    }
+
+    // Check slug uniqueness if slug is being updated
+    if (data.slug) {
+      const slugCheck = await dbQuery(
+        'SELECT id FROM taxonomies WHERE type = \'post_category\' AND slug = $1 AND id != $2',
+        [data.slug, id]
+      )
+      if (slugCheck.rows.length > 0) {
+        return NextResponse.json(
+          { success: false, error: 'A category with this slug already exists' },
+          { status: 409 }
+        )
+      }
+    }
+
+    // Verify parentId exists if provided
+    if (data.parentId) {
+      const parentCheck = await dbQuery(
+        'SELECT id FROM taxonomies WHERE id = $1 AND type = \'post_category\'',
+        [data.parentId]
+      )
+      if (parentCheck.rows.length === 0) {
+        return NextResponse.json({
+          success: false,
+          error: 'Parent category not found'
+        }, { status: 400 })
+      }
+
+      // Prevent circular reference
+      if (data.parentId === id) {
+        return NextResponse.json({
+          success: false,
+          error: 'A category cannot be its own parent'
+        }, { status: 400 })
+      }
+    }
+
+    // Build the update query dynamically based on provided fields
+    const updates: string[] = []
+    const values: unknown[] = []
+    let paramIndex = 1
+
+    if (data.name !== undefined) {
+      updates.push(`name = $${paramIndex++}`)
+      values.push(data.name)
+    }
+    if (data.slug !== undefined) {
+      updates.push(`slug = $${paramIndex++}`)
+      values.push(data.slug)
+    }
+    if (data.description !== undefined) {
+      updates.push(`description = $${paramIndex++}`)
+      values.push(data.description || null)
+    }
+    if (data.icon !== undefined) {
+      updates.push(`icon = $${paramIndex++}`)
+      values.push(data.icon || null)
+    }
+    if (data.color !== undefined) {
+      updates.push(`color = $${paramIndex++}`)
+      values.push(data.color || null)
+    }
+    if (data.parentId !== undefined) {
+      updates.push(`"parentId" = $${paramIndex++}`)
+      values.push(data.parentId || null)
+    }
+    if (data.order !== undefined) {
+      updates.push(`"order" = $${paramIndex++}`)
+      values.push(data.order)
+    }
+    if (data.isDefault !== undefined) {
+      updates.push(`"isDefault" = $${paramIndex++}`)
+      values.push(data.isDefault)
+    }
+    if (data.isActive !== undefined) {
+      updates.push(`"isActive" = $${paramIndex++}`)
+      values.push(data.isActive)
+    }
+
+    // Only update if there are fields to update
+    if (updates.length === 0) {
+      // No fields to update, just return current data
+      const current = await dbQuery(
+        `SELECT id, name, slug, description, icon, color, "parentId", "order", "isDefault", "isActive",
+                "createdAt", "updatedAt"
+         FROM taxonomies WHERE id = $1`,
+        [id]
+      )
+      return NextResponse.json({ success: true, data: current.rows[0] })
+    }
+
+    // Add the id as the last parameter
+    values.push(id)
+
+    const query = `UPDATE taxonomies SET ${updates.join(', ')} WHERE id = $${paramIndex} RETURNING *`
+    const result = await dbQuery(query, values)
+
+    if (result.rows.length === 0) {
+      return NextResponse.json({ success: false, error: 'Category not found' }, { status: 404 })
+    }
+
+    return NextResponse.json({
+      success: true,
+      data: result.rows[0]
+    })
+  } catch (err) {
+    console.error('Error in post-categories API PUT:', err)
+    if (err instanceof z.ZodError) {
+      return NextResponse.json({ success: false, error: 'Validation error', details: err.issues }, { status: 400 })
+    }
+    const errorMessage = err instanceof Error ? err.message : 'Internal server error'
+    return NextResponse.json({ success: false, error: errorMessage }, { status: 500 })
+  }
+}
+
+// DELETE /api/v1/post-categories/:id - Delete category
+export async function DELETE(
+  request: NextRequest,
+  { params }: { params: Promise<{ id: string }> }
+): Promise<NextResponse> {
+  try {
+    // Dual authentication: API key or session
+    const authResult = await authenticateRequest(request)
+    if (!authResult.success || !authResult.user) {
+      return NextResponse.json({ success: false, error: 'Unauthorized' }, { status: 401 })
+    }
+
+    const { id } = await params
+
+    // Verify this is a post_category taxonomy
+    const typeCheck = await dbQuery(
+      'SELECT id FROM taxonomies WHERE id = $1 AND type = \'post_category\'',
+      [id]
+    )
+
+    if (typeCheck.rows.length === 0) {
+      return NextResponse.json({ success: false, error: 'Category not found' }, { status: 404 })
+    }
+
+    // Check if category is used by any posts (using entity_taxonomy_relations)
+    let usageCount = 0
+    try {
+      const usageCheck = await dbQuery<{ count: string }>(
+        `SELECT COUNT(*) as count FROM entity_taxonomy_relations
+         WHERE "taxonomyId" = $1 AND "entityType" = 'posts'`,
+        [id]
+      )
+      usageCount = parseInt(usageCheck.rows[0].count)
+    } catch {
+      // Table might not exist yet, assume no usage
+      usageCount = 0
+    }
+
+    // Soft delete if used, hard delete if not used
+    if (usageCount > 0) {
+      // Soft delete: SET deletedAt = now()
+      await dbQuery(
+        'UPDATE taxonomies SET "deletedAt" = now() WHERE id = $1',
+        [id]
+      )
+      return NextResponse.json({
+        success: true,
+        data: { id, deleted: 'soft', message: 'Category soft-deleted (still referenced by posts)' }
+      })
+    } else {
+      // Hard delete: No posts use it
+      const result = await dbQuery<{ id: string }>(
+        'DELETE FROM taxonomies WHERE id = $1 RETURNING id',
+        [id]
+      )
+      if (result.rows.length === 0) {
+        return NextResponse.json({ success: false, error: 'Category not found' }, { status: 404 })
+      }
+      return NextResponse.json({
+        success: true,
+        data: { id: result.rows[0].id, deleted: 'hard' }
+      })
+    }
+  } catch (err) {
+    console.error('Error in post-categories API DELETE:', err)
+    return NextResponse.json({ success: false, error: 'Internal server error' }, { status: 500 })
+  }
+}

package/dist/templates/app/api/v1/post-categories/docs.md

@@ -0,0 +1,134 @@
+# Post Categories API
+
+Manage blog post categories (taxonomies).
+
+## Overview
+
+The Post Categories API provides endpoints for managing blog post categories. Categories are stored in the `taxonomies` table with type `post_category`. Supports hierarchical categories with parent-child relationships.
+
+## Authentication
+
+- **GET** endpoints are public (no authentication required)
+- **POST/PATCH/DELETE** endpoints require authentication via session cookie or API key
+
+## Endpoints
+
+### List Categories
+`GET /api/v1/post-categories`
+
+Returns all active post categories ordered by sort order and name.
+
+**Example Response:**
+```json
+{
+  "success": true,
+  "data": [
+    {
+      "id": "cat_123",
+      "name": "Technology",
+      "slug": "technology",
+      "description": "Tech news and tutorials",
+      "icon": "Cpu",
+      "color": "#3b82f6",
+      "parentId": null,
+      "order": 1,
+      "isDefault": false,
+      "isActive": true,
+      "createdAt": "2024-01-15T10:00:00Z",
+      "updatedAt": "2024-01-15T10:00:00Z"
+    }
+  ]
+}
+```
+
+### Create Category
+`POST /api/v1/post-categories`
+
+Create a new post category.
+
+**Request Body:**
+```json
+{
+  "name": "Technology",
+  "slug": "technology",
+  "description": "Tech news and tutorials",
+  "icon": "Cpu",
+  "color": "#3b82f6",
+  "parentId": null,
+  "order": 1,
+  "isDefault": false
+}
+```
+
+**Parameters:**
+- `name` (string, required): Category display name (1-255 chars)
+- `slug` (string, optional): URL-friendly identifier (auto-generated if not provided)
+- `description` (string, optional): Category description
+- `icon` (string, optional): Lucide icon name
+- `color` (string, optional): Hex color code
+- `parentId` (string, optional): Parent category ID for hierarchical categories
+- `order` (number, optional): Sort order (default: 0)
+- `isDefault` (boolean, optional): Mark as default category (default: false)
+
+**Slug Rules:**
+- Lowercase alphanumeric with dashes only
+- 2-100 characters
+- Pattern: `^[a-z0-9-]+$`
+- Must be unique within post categories
+
+### Get Category
+`GET /api/v1/post-categories/[id]`
+
+Returns a single category by ID.
+
+**Path Parameters:**
+- `id` (string, required): Category ID
+
+### Update Category
+`PATCH /api/v1/post-categories/[id]`
+
+Update an existing category. Partial updates supported.
+
+**Path Parameters:**
+- `id` (string, required): Category ID
+
+**Request Body:**
+Any fields from the create schema (partial update).
+
+### Delete Category
+`DELETE /api/v1/post-categories/[id]`
+
+Soft delete a category (sets `deletedAt`).
+
+**Path Parameters:**
+- `id` (string, required): Category ID
+
+## Hierarchical Categories
+
+Categories support parent-child relationships:
+
+```json
+{
+  "name": "JavaScript",
+  "slug": "javascript",
+  "parentId": "cat_technology"
+}
+```
+
+When listing categories, use `parentId` to build tree structures client-side.
+
+## Error Responses
+
+| Status | Description |
+|--------|-------------|
+| 400 | Bad Request - Validation error or slug already exists |
+| 401 | Unauthorized - Authentication required for write operations |
+| 404 | Not Found - Category or parent category not found |
+| 500 | Server Error - Internal error |
+
+## Usage Notes
+
+- Categories are stored in the `taxonomies` table with `type = 'post_category'`
+- Only active categories (`isActive = true`, `deletedAt IS NULL`) are returned
+- Slugs are auto-generated from name if not provided
+- The `order` field controls sort order in listings

package/dist/templates/app/api/v1/post-categories/presets.ts

@@ -0,0 +1,78 @@
+/**
+ * API Presets for Post Categories
+ *
+ * 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/post-categories',
+  summary: 'Manage blog post categories (taxonomies)',
+  presets: [
+    // List
+    {
+      id: 'list-all',
+      title: 'List All Categories',
+      description: 'Fetch all active post categories',
+      method: 'GET',
+      tags: ['read', 'list']
+    },
+
+    // Create
+    {
+      id: 'create-category',
+      title: 'Create Category',
+      description: 'Create a new post category',
+      method: 'POST',
+      payload: {
+        name: 'Technology',
+        description: 'Tech news and tutorials',
+        icon: 'Cpu',
+        color: '#3b82f6',
+        order: 1
+      },
+      tags: ['write', 'create']
+    },
+    {
+      id: 'create-category-with-slug',
+      title: 'Create with Custom Slug',
+      description: 'Create category with explicit slug',
+      method: 'POST',
+      payload: {
+        name: 'Web Development',
+        slug: 'web-dev',
+        description: 'Web development tutorials and tips',
+        order: 2
+      },
+      tags: ['write', 'create']
+    },
+    {
+      id: 'create-subcategory',
+      title: 'Create Subcategory',
+      description: 'Create child category with parent',
+      method: 'POST',
+      payload: {
+        name: 'JavaScript',
+        slug: 'javascript',
+        parentId: 'parent_category_id_here',
+        description: 'JavaScript tutorials',
+        order: 1
+      },
+      tags: ['write', 'create', 'hierarchy']
+    },
+    {
+      id: 'create-default-category',
+      title: 'Create Default Category',
+      description: 'Create category marked as default',
+      method: 'POST',
+      payload: {
+        name: 'Uncategorized',
+        slug: 'uncategorized',
+        isDefault: true,
+        order: 999
+      },
+      tags: ['write', 'create']
+    }
+  ]
+})

package/dist/templates/app/api/v1/post-categories/route.ts

@@ -0,0 +1,119 @@
+import { NextRequest, NextResponse } from 'next/server'
+import { authenticateRequest } from '@nextsparkjs/core/lib/api/auth/dual-auth'
+import { query as dbQuery } from '@nextsparkjs/core/lib/db'
+import { z } from 'zod'
+
+const createCategorySchema = z.object({
+  name: z.string().min(1).max(255),
+  slug: z.string().min(2).max(100).regex(/^[a-z0-9-]+$/, 'Slug must be lowercase alphanumeric with dashes').optional(),
+  description: z.string().optional(),
+  icon: z.string().optional(),
+  color: z.string().optional(),
+  parentId: z.string().optional(),
+  order: z.number().int().default(0),
+  isDefault: z.boolean().default(false)
+})
+
+// Helper to generate slug from name
+function generateSlug(name: string): string {
+  return name
+    .toLowerCase()
+    .trim()
+    .replace(/[^a-z0-9\s-]/g, '') // Remove special chars
+    .replace(/\s+/g, '-')          // Replace spaces with dashes
+    .replace(/-+/g, '-')           // Replace multiple dashes with single
+    .replace(/^-|-$/g, '')         // Remove leading/trailing dashes
+}
+
+// GET /api/v1/post-categories - List categories (filters taxonomies by type = 'post_category')
+export async function GET() {
+  try {
+    const result = await dbQuery(
+      `SELECT id, name, slug, description, icon, color, "parentId", "order", "isDefault", "isActive",
+              "createdAt", "updatedAt"
+       FROM taxonomies
+       WHERE type = 'post_category' AND "deletedAt" IS NULL AND "isActive" = true
+       ORDER BY "order" ASC, name ASC`
+    )
+
+    return NextResponse.json({
+      success: true,
+      data: result.rows
+    })
+  } catch (error) {
+    console.error('Error fetching post categories:', error)
+    return NextResponse.json({ success: false, error: 'Internal server error' }, { status: 500 })
+  }
+}
+
+// POST /api/v1/post-categories - Create category
+export async function POST(request: NextRequest) {
+  try {
+    // Dual authentication: API key or session
+    const authResult = await authenticateRequest(request)
+    if (!authResult.success || !authResult.user) {
+      return NextResponse.json({ success: false, error: 'Unauthorized' }, { status: 401 })
+    }
+
+    const body = await request.json()
+    const data = createCategorySchema.parse(body)
+
+    // Auto-generate slug if not provided
+    const slug = data.slug || generateSlug(data.name)
+
+    // Check slug uniqueness for this taxonomy type
+    const existing = await dbQuery(
+      'SELECT id FROM taxonomies WHERE type = \'post_category\' AND slug = $1',
+      [slug]
+    )
+
+    if (existing.rows.length > 0) {
+      return NextResponse.json({
+        success: false,
+        error: 'Slug already exists',
+        message: `A category with slug "${slug}" already exists`
+      }, { status: 400 })
+    }
+
+    // Verify parentId exists if provided
+    if (data.parentId) {
+      const parentCheck = await dbQuery(
+        'SELECT id FROM taxonomies WHERE id = $1 AND type = \'post_category\'',
+        [data.parentId]
+      )
+      if (parentCheck.rows.length === 0) {
+        return NextResponse.json({
+          success: false,
+          error: 'Parent category not found'
+        }, { status: 400 })
+      }
+    }
+
+    // Insert category (type is hardcoded to 'post_category')
+    const result = await dbQuery(
+      `INSERT INTO taxonomies (
+        type, slug, name, description, icon, color, "parentId", "order", "isDefault", "userId"
+      ) VALUES ('post_category', $1, $2, $3, $4, $5, $6, $7, $8, $9)
+      RETURNING *`,
+      [
+        slug,
+        data.name,
+        data.description || null,
+        data.icon || null,
+        data.color || null,
+        data.parentId || null,
+        data.order,
+        data.isDefault,
+        authResult.user.id
+      ]
+    )
+
+    return NextResponse.json({ success: true, data: result.rows[0] }, { status: 201 })
+  } catch (error) {
+    if (error instanceof z.ZodError) {
+      return NextResponse.json({ success: false, error: 'Validation error', details: error.issues }, { status: 400 })
+    }
+    console.error('Error creating post category:', error)
+    return NextResponse.json({ success: false, error: 'Internal server error' }, { status: 500 })
+  }
+}