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

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

@@ -0,0 +1,93 @@
+# Users API
+
+Manage user profiles and account settings.
+
+## Overview
+
+The Users API allows you to view and update user profile information. Users can update their own profile, while admins can manage other users within their team.
+
+## Authentication
+
+All endpoints require authentication via:
+- **Session cookie** (for browser-based requests)
+- **API Key** header (for server-to-server requests)
+
+## Endpoints
+
+### Get Current User
+`GET /api/v1/users/me`
+
+Returns the currently authenticated user's profile.
+
+**Example Response:**
+```json
+{
+  "id": "user_123",
+  "name": "John Doe",
+  "email": "john@example.com",
+  "image": "/uploads/avatar.png",
+  "createdAt": "2024-01-15T10:30:00Z",
+  "teams": [
+    {
+      "id": "team_456",
+      "name": "Acme Corp",
+      "role": "admin"
+    }
+  ]
+}
+```
+
+### Update Current User
+`PATCH /api/v1/users/me`
+
+Update the current user's profile.
+
+**Request Body:**
+```json
+{
+  "name": "John Smith",
+  "image": "/uploads/new-avatar.png"
+}
+```
+
+### List Team Members
+`GET /api/v1/users`
+
+Returns all users in the current team.
+
+**Query Parameters:**
+- `limit` (number, optional): Maximum records to return. Default: 20
+- `offset` (number, optional): Number of records to skip. Default: 0
+- `search` (string, optional): Search by name or email
+
+### Get User by ID
+`GET /api/v1/users/[id]`
+
+Returns a specific user's profile (within the same team).
+
+**Path Parameters:**
+- `id` (string, required): User ID
+
+## User Roles
+
+Team-level roles determine permissions:
+- `member` - Basic team member
+- `admin` - Can manage team settings and members
+- `owner` - Full control of the team
+
+## Error Responses
+
+| Status | Description |
+|--------|-------------|
+| 400 | Bad Request - Invalid parameters |
+| 401 | Unauthorized - Missing or invalid auth |
+| 403 | Forbidden - Insufficient permissions |
+| 404 | Not Found - User doesn't exist |
+| 422 | Validation Error - Invalid data |
+
+## Related APIs
+
+- **[Auth](/api/v1/auth)** - Authentication and session management
+- **[Teams](/api/v1/teams)** - Team membership and roles
+- **[Team Invitations](/api/v1/team-invitations)** - Invite users to teams
+- **[API Keys](/api/v1/api-keys)** - Manage programmatic access

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

@@ -0,0 +1,59 @@
+/**
+ * API Presets for Users
+ *
+ * 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/users',
+  summary: 'Manage user profiles and team members',
+  presets: [
+    {
+      id: 'get-me',
+      title: 'Get Current User',
+      description: 'Fetch the currently authenticated user profile',
+      method: 'GET',
+      pathParams: {
+        id: 'me'
+      },
+      tags: ['read', 'profile']
+    },
+    {
+      id: 'list-team-members',
+      title: 'List Team Members',
+      description: 'Fetch all users in the current team',
+      method: 'GET',
+      params: {
+        limit: 20,
+        offset: 0
+      },
+      tags: ['read', 'list']
+    },
+    {
+      id: 'update-profile',
+      title: 'Update My Profile',
+      description: 'Update current user name',
+      method: 'PATCH',
+      pathParams: {
+        id: 'me'
+      },
+      payload: {
+        name: 'Updated Name'
+      },
+      tags: ['write', 'profile']
+    },
+    {
+      id: 'search-users',
+      title: 'Search Team Members',
+      description: 'Search users by name or email',
+      method: 'GET',
+      params: {
+        search: 'john',
+        limit: 10
+      },
+      tags: ['read', 'search']
+    }
+  ]
+})

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

@@ -0,0 +1,197 @@
+import { NextRequest, NextResponse } from 'next/server';
+import { queryWithRLS, mutateWithRLS } from '@nextsparkjs/core/lib/db';
+import { 
+  createApiResponse, 
+  createApiError,
+  parsePaginationParams,
+  createPaginationMeta,
+  parseFilters,
+  withApiLogging,
+  handleCorsPreflightRequest,
+  addCorsHeaders,
+  parseMetaParams,
+  includeEntityMetadata,
+  handleEntityMetadataInResponse,
+  processEntityMetadata
+} from '@nextsparkjs/core/lib/api/helpers';
+import { authenticateRequest } from '@nextsparkjs/core/lib/api/auth/dual-auth';
+import { hasAdminPermission } from '@nextsparkjs/core/lib/api/auth/permissions';
+import { z } from 'zod';
+
+const createUserSchema = z.object({
+  email: z.string().email('Invalid email format'),
+  firstName: z.string().min(1, 'First name is required'),
+  lastName: z.string().min(1, 'Last name is required'),
+  country: z.string().min(2, 'Country is required (minimum 2 characters)'),
+  image: z.string().url('Invalid image URL format').optional(),
+  language: z.string().optional().default('en'),
+  timezone: z.string().optional().default('UTC'),
+  role: z.enum(['member', 'colaborator']).default('member'),
+  metas: z.record(z.string(), z.any()).optional()
+});
+
+
+
+// Handle CORS preflight
+export async function OPTIONS() {
+  return handleCorsPreflightRequest();
+}
+
+// GET /api/v1/users - List users with dual auth
+export const GET = withApiLogging(async (req: NextRequest): 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;
+    }
+
+    // SECURITY: Only superadmins can list all users
+    if (!hasAdminPermission(authResult, 'users:read')) {
+      const response = createApiError('Insufficient permissions. Superadmin access required.', 403);
+      return addCorsHeaders(response);
+    }
+
+    const metaParams = parseMetaParams(req);
+    const { page, limit, offset } = parsePaginationParams(req);
+    const filters = parseFilters(req);
+
+    // Build WHERE clause based on filters
+    let whereClause = 'WHERE 1=1';
+    const queryParams: (string | number)[] = [];
+    let paramCount = 1;
+
+    if (filters.role) {
+      whereClause += ` AND role = $${paramCount}`;
+      queryParams.push(filters.role);
+      paramCount++;
+    }
+
+    // Add pagination params
+    queryParams.push(limit, offset);
+
+    const users = await queryWithRLS(
+      `SELECT id, email, name, "firstName", "lastName", image, country, timezone, language, role, "emailVerified", "createdAt", "updatedAt"
+       FROM "users"
+       ${whereClause}
+       ORDER BY "createdAt" DESC
+       LIMIT $${paramCount++} OFFSET $${paramCount++}`,
+      queryParams,
+      authResult.user!.id
+    );
+
+    // Get total count for pagination
+    const totalResult = await queryWithRLS<{ count: number }>(
+      `SELECT COUNT(*) as count FROM "users" ${whereClause}`,
+      queryParams.slice(0, -2), // Remove limit and offset
+      authResult.user!.id
+    );
+
+    const total = totalResult[0]?.count || 0;
+    const paginationMeta = createPaginationMeta(page, limit, total);
+
+    // Include metadata if requested (usando helper compartido)
+    const usersWithMeta = await includeEntityMetadata('user', users as { id: string }[], metaParams, authResult.user!.id);
+
+    const response = createApiResponse(usersWithMeta, paginationMeta);
+    return addCorsHeaders(response);
+  } catch (error) {
+    console.error('Error fetching users:', error);
+    const response = createApiError('Internal server error', 500);
+    return addCorsHeaders(response);
+  }
+});
+
+// POST /api/v1/users - Create user with dual auth
+export const POST = withApiLogging(async (req: NextRequest): 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;
+    }
+
+    // SECURITY: Only superadmins can create users
+    if (!hasAdminPermission(authResult, 'users:write')) {
+      const response = createApiError('Insufficient permissions. Superadmin access required.', 403);
+      return addCorsHeaders(response);
+    }
+
+    const body = await req.json();
+    const { metas, ...userData } = body;
+    const validatedData = createUserSchema.parse(userData);
+      
+    // Check if email already exists
+    const existingUser = await queryWithRLS(
+      'SELECT id FROM "users" WHERE email = $1',
+      [validatedData.email],
+      authResult.user!.id
+    );
+
+    if (existingUser.length > 0) {
+      const response = createApiError('Email already exists', 409, null, 'EMAIL_EXISTS');
+      return addCorsHeaders(response);
+    }
+
+    const newUserId = globalThis.crypto.randomUUID();
+
+    // Create user
+    const result = await mutateWithRLS(
+      `INSERT INTO "users" (id, email, "firstName", "lastName", country, image, language, timezone, role, "emailVerified")
+       VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, true) RETURNING *`,
+      [
+        newUserId,
+        validatedData.email,
+        validatedData.firstName,
+        validatedData.lastName,
+        validatedData.country,
+        validatedData.image || null,
+        validatedData.language,
+        validatedData.timezone,
+        validatedData.role
+      ],
+      authResult.user!.id
+    );
+
+    const createdUser = result.rows[0];
+
+    // Handle metadata if provided (usando helper compartido)
+    const metadataWasProvided = metas && typeof metas === 'object' && Object.keys(metas).length > 0;
+    
+    if (metadataWasProvided) {
+      await processEntityMetadata('user', newUserId, metas, authResult.user!.id);
+    }
+
+    // Crear respuesta según criterio: incluir metadata solo si se envió en el payload
+    const responseData = await handleEntityMetadataInResponse('user', createdUser as { id: string }, metadataWasProvided, authResult.user!.id);
+    
+    const response = createApiResponse(responseData, { created: true }, 201);
+    return addCorsHeaders(response);
+  } catch (error) {
+    if (error instanceof z.ZodError) {
+      const response = createApiError('Validation error', 400, error.issues, 'VALIDATION_ERROR');
+      return addCorsHeaders(response);
+    }
+    
+    console.error('Error creating user:', error);
+    const response = createApiError('Internal server error', 500);
+    return addCorsHeaders(response);
+  }
+});
+

package/templates/app/dashboard/(main)/[entity]/[id]/edit/page.tsx

@@ -0,0 +1,117 @@
+'use client'
+
+import { notFound, useRouter } from 'next/navigation'
+import { useParams } from 'next/navigation'
+import { useEffect, useState } from 'react'
+import { clientEntityRegistry, ensureClientInitialized, type ClientEntityConfig } from '@nextsparkjs/registries/entity-registry.client'
+import { EntityFormWrapper } from '@nextsparkjs/core/components/entities/wrappers/EntityFormWrapper'
+import { BuilderEditorView } from '@nextsparkjs/core/components/dashboard/block-editor/builder-editor-view'
+import { getTemplateOrDefaultClient } from '@nextsparkjs/registries/template-registry.client'
+import { getEntityData } from '@nextsparkjs/core/lib/api/entities'
+
+function EntityEditPage() {
+  const params = useParams()
+  const router = useRouter()
+  const [entityConfig, setEntityConfig] = useState<ClientEntityConfig | null>(null)
+  const [initialData, setInitialData] = useState<Record<string, unknown> | null>(null)
+  const [loading, setLoading] = useState(true)
+
+  // Extract entity slug and id from params
+  const entitySlug = params.entity as string
+  const entityId = params.id as string
+
+  useEffect(() => {
+    async function loadEntityData() {
+      if (!entitySlug || !entityId) {
+        setLoading(false)
+        return
+      }
+
+      try {
+        // Load entity config (client-safe)
+        await ensureClientInitialized()
+        const config = clientEntityRegistry.getBySlug(entitySlug)
+
+        if (!config) {
+          setEntityConfig(null)
+          setLoading(false)
+          return
+        }
+
+        setEntityConfig(config)
+
+        // For builder-enabled entities, BuilderEditorView handles its own data fetching
+        // For regular entities, fetch data here
+        if (!config.builder?.enabled) {
+          const data = await getEntityData(entitySlug, entityId, true)
+          setInitialData(data as Record<string, unknown>)
+        }
+      } catch (error) {
+        console.error('Error loading entity:', error)
+        setEntityConfig(null)
+        setInitialData(null)
+      } finally {
+        setLoading(false)
+      }
+    }
+
+    loadEntityData()
+  }, [entitySlug, entityId])
+
+  if (loading) {
+    return (
+      <div className="flex items-center justify-center min-h-[400px]">
+        <div className="animate-spin rounded-full h-8 w-8 border-b-2 border-primary" />
+      </div>
+    )
+  }
+
+  if (!entityConfig) {
+    notFound()
+  }
+
+  // For non-builder entities, we need the initial data
+  if (!entityConfig.builder?.enabled && !initialData) {
+    notFound()
+  }
+
+  if (!entityConfig.features?.enabled) {
+    notFound()
+  }
+
+  // Check if entity should be accessible via dashboard route
+  // Entities with showInMenu: false are managed elsewhere (e.g., settings)
+  if (!entityConfig.features?.showInMenu) {
+    notFound()
+  }
+
+  // Use BuilderEditorView for builder-enabled entities
+  if (entityConfig.builder?.enabled) {
+    return (
+      <BuilderEditorView
+        entitySlug={entitySlug}
+        entityConfig={entityConfig}
+        id={entityId}
+        mode="edit"
+      />
+    )
+  }
+
+  // Use EntityFormWrapper for regular entities
+  return (
+    <EntityFormWrapper
+      entityType={entitySlug}
+      id={entityId}
+      mode="edit"
+      onSuccess={() => {
+        // For edit, redirect to the entity detail view
+        router.push(`/dashboard/${entitySlug}/${entityId}`)
+      }}
+      onError={(error) => {
+        console.error(`Error updating ${entityConfig.displayName}:`, error)
+      }}
+    />
+  )
+}
+
+export default getTemplateOrDefaultClient('app/dashboard/(main)/[entity]/[id]/edit/page.tsx', EntityEditPage)

package/templates/app/dashboard/(main)/[entity]/[id]/page.tsx

@@ -0,0 +1,103 @@
+import { notFound, redirect } from 'next/navigation'
+import { getEntity, getEntityRegistry, getChildEntities, setEntityRegistry } from '@nextsparkjs/core/lib/entities/queries'
+import { EntityDetailWrapper } from '@nextsparkjs/core/components/entities/wrappers/EntityDetailWrapper'
+import type { Metadata } from 'next'
+import { TemplateService } from '@nextsparkjs/core/lib/services/template.service'
+import type { EntityConfig, ChildEntityDefinition } from '@nextsparkjs/core/lib/entities/types'
+// Import registry directly - webpack resolves @nextsparkjs/registries alias at compile time
+import { ENTITY_REGISTRY, ENTITY_METADATA } from '@nextsparkjs/registries/entity-registry'
+
+// Initialize registry at module load time (before any component renders)
+setEntityRegistry(ENTITY_REGISTRY, ENTITY_METADATA)
+
+// Type guard to check if entity is a full EntityConfig
+function isEntityConfig(entity: EntityConfig | ChildEntityDefinition): entity is EntityConfig {
+  return 'slug' in entity
+}
+
+interface PageProps {
+  params: Promise<{
+    entity: string
+    id: string
+  }>
+}
+
+async function EntityDetailPage({ params }: PageProps) {
+  const resolvedParams = await params
+  const entitySlug = resolvedParams.entity
+
+  // Check if there's a specific template override for this entity
+  // e.g., app/dashboard/(main)/boards/[id]/page.tsx for boards
+  const specificTemplatePath = `app/dashboard/(main)/${entitySlug}/[id]/page.tsx`
+  if (TemplateService.hasOverride(specificTemplatePath)) {
+    const OverrideComponent = TemplateService.getComponent(specificTemplatePath)
+    if (OverrideComponent) {
+      console.log(`🎨 Entity-specific template override applied for ${specificTemplatePath}`)
+      return <OverrideComponent params={params} />
+    }
+  }
+
+  // Verificar que la entidad existe en el registro
+  if (!(entitySlug in getEntityRegistry())) {
+    notFound()
+  }
+
+  const entityConfig = getEntity(entitySlug as string)
+  if (!entityConfig || !isEntityConfig(entityConfig)) {
+    notFound()
+  }
+
+  // Verificar que la entidad está habilitada
+  if (!entityConfig.enabled) {
+    notFound()
+  }
+
+  // Check if entity should be accessible via dashboard route
+  // Entities with showInMenu: false are managed elsewhere (e.g., settings)
+  if (!entityConfig.ui?.dashboard?.showInMenu) {
+    notFound()
+  }
+
+  // Builder-enabled entities redirect to edit view
+  // Detail view doesn't make sense for entities using the page builder
+  if (entityConfig.builder?.enabled) {
+    redirect(`/dashboard/${entitySlug}/${resolvedParams.id}/edit`)
+  }
+
+  // Get child entities for this parent entity
+  const childEntities = getChildEntities(entitySlug as string)
+  const childEntityNames = childEntities.map(child => child.name)
+
+  return (
+    <EntityDetailWrapper
+      entityType={entityConfig.slug}
+      id={resolvedParams.id}
+      childEntityNames={childEntityNames}
+    />
+  )
+}
+
+export async function generateMetadata({ params }: PageProps): Promise<Metadata> {
+  const resolvedParams = await params
+  const entitySlug = resolvedParams.entity
+
+  if (!(entitySlug in getEntityRegistry())) {
+    return {
+      title: 'Not Found - Dashboard'
+    }
+  }
+
+  const entityConfig = getEntity(entitySlug as string)
+  if (!entityConfig || !isEntityConfig(entityConfig)) {
+    return {
+      title: 'Not Found - Dashboard'
+    }
+  }
+
+  return {
+    title: `${entityConfig.names.plural} #${resolvedParams.id} - Dashboard`,
+    description: `View details for ${entityConfig.names.singular}`
+  }
+}
+
+export default EntityDetailPage

package/templates/app/dashboard/(main)/[entity]/create/page.tsx

@@ -0,0 +1,95 @@
+'use client'
+
+import { notFound, useRouter } from 'next/navigation'
+import { useParams } from 'next/navigation'
+import { useEffect, useState } from 'react'
+import { clientEntityRegistry, ensureClientInitialized, type ClientEntityConfig } from '@nextsparkjs/registries/entity-registry.client'
+import { EntityFormWrapper } from '@nextsparkjs/core/components/entities/wrappers/EntityFormWrapper'
+import { BuilderEditorView } from '@nextsparkjs/core/components/dashboard/block-editor/builder-editor-view'
+import { getTemplateOrDefaultClient } from '@nextsparkjs/registries/template-registry.client'
+
+function EntityCreatePage() {
+  const params = useParams()
+  const router = useRouter()
+  const [entityConfig, setEntityConfig] = useState<ClientEntityConfig | null>(null)
+  const [loading, setLoading] = useState(true)
+
+  // Extract entity slug from params
+  const entitySlug = params.entity as string
+
+  useEffect(() => {
+    async function loadEntityConfig() {
+      if (!entitySlug) {
+        setLoading(false)
+        return
+      }
+
+      try {
+        await ensureClientInitialized()
+        const config = clientEntityRegistry.getBySlug(entitySlug)
+        setEntityConfig(config || null)
+      } catch (error) {
+        console.error('Error loading entity config:', error)
+        setEntityConfig(null)
+      } finally {
+        setLoading(false)
+      }
+    }
+
+    loadEntityConfig()
+  }, [entitySlug])
+
+  if (loading) {
+    return (
+      <div className="flex items-center justify-center min-h-[400px]">
+        <div className="animate-spin rounded-full h-8 w-8 border-b-2 border-primary" />
+      </div>
+    )
+  }
+
+  if (!entityConfig) {
+    notFound()
+  }
+
+  if (!entityConfig.features?.enabled) {
+    notFound()
+  }
+
+  // Check if entity should be accessible via dashboard route
+  // Entities with showInMenu: false are managed elsewhere (e.g., settings)
+  if (!entityConfig.features?.showInMenu) {
+    notFound()
+  }
+
+  // Use BuilderEditorView for builder-enabled entities
+  if (entityConfig.builder?.enabled) {
+    return (
+      <BuilderEditorView
+        entitySlug={entitySlug}
+        entityConfig={entityConfig}
+        mode="create"
+      />
+    )
+  }
+
+  // Use EntityFormWrapper for regular entities
+  return (
+    <EntityFormWrapper
+      entityType={entitySlug}
+      mode="create"
+      onSuccess={(createdId) => {
+        // For create, redirect to the entity detail view if we have the ID, otherwise to list
+        if (createdId) {
+          router.push(`/dashboard/${entitySlug}/${createdId}`)
+        } else {
+          router.push(`/dashboard/${entitySlug}`)
+        }
+      }}
+      onError={(error) => {
+        console.error(`Error creating ${entityConfig.displayName}:`, error)
+      }}
+    />
+  )
+}
+
+export default getTemplateOrDefaultClient('app/dashboard/(main)/[entity]/create/page.tsx', EntityCreatePage)