@nextsparkjs/core 0.1.0-beta.7 → 0.1.0-beta.70

package/templates/contents/themes/starter/entities/posts/posts.fields.ts

@@ -0,0 +1,116 @@
+/**
+ * Posts Entity Fields Configuration
+ *
+ * Fields required for builder-enabled posts with sidebar support.
+ * Note: 'blocks' field is NOT in fields[] - it's managed by the builder view automatically.
+ * Note: 'categories' is managed by taxonomies system, not a regular field.
+ */
+
+import type { EntityField } from '@nextsparkjs/core/lib/entities/types'
+
+export const postsFields: EntityField[] = [
+  {
+    name: 'title',
+    type: 'text',
+    required: true,
+    display: {
+      label: 'Title',
+      description: 'Post title',
+      placeholder: 'Enter post title...',
+      showInList: true,
+      showInDetail: true,
+      showInForm: true,
+      order: 1,
+    },
+    api: {
+      searchable: true,
+      sortable: true,
+      readOnly: false,
+    },
+  },
+  {
+    name: 'slug',
+    type: 'text',
+    required: true,
+    display: {
+      label: 'Slug',
+      description: 'URL-friendly identifier',
+      placeholder: 'post-slug',
+      showInList: true,
+      showInDetail: true,
+      showInForm: true,
+      order: 2,
+    },
+    api: {
+      searchable: true,
+      sortable: true,
+      readOnly: false,
+    },
+  },
+  {
+    name: 'status',
+    type: 'select',
+    required: true,
+    defaultValue: 'draft',
+    options: [
+      { value: 'draft', label: 'Draft' },
+      { value: 'published', label: 'Published' },
+      { value: 'scheduled', label: 'Scheduled' },
+      { value: 'archived', label: 'Archived' },
+    ],
+    display: {
+      label: 'Status',
+      description: 'Publication status',
+      showInList: true,
+      showInDetail: true,
+      showInForm: true,
+      order: 3,
+    },
+    api: {
+      searchable: false,
+      sortable: true,
+      filterable: true,
+      readOnly: false,
+    },
+  },
+  {
+    name: 'excerpt',
+    type: 'textarea',
+    required: false,
+    display: {
+      label: 'Excerpt',
+      description: 'Short summary of the post',
+      placeholder: 'Brief description...',
+      showInList: false,
+      showInDetail: true,
+      showInForm: true, // Shown in builder sidebar
+      order: 4,
+    },
+    api: {
+      searchable: true,
+      sortable: false,
+      readOnly: false,
+    },
+  },
+  {
+    name: 'featuredImage',
+    type: 'image',
+    required: false,
+    display: {
+      label: 'Featured Image',
+      description: 'Main image for the post',
+      showInList: false,
+      showInDetail: true,
+      showInForm: true, // Shown in builder sidebar
+      order: 5,
+    },
+    api: {
+      searchable: false,
+      sortable: false,
+      readOnly: false,
+    },
+  },
+  // Note: 'categories' is managed by taxonomies system, not a regular field
+  // Note: SEO fields (seoTitle, seoDescription, etc.) are managed by the builder SEO panel
+  // Note: 'blocks' field is a system field for builder-enabled entities - NOT defined here
+]

package/templates/contents/themes/starter/entities/posts/posts.service.ts

@@ -0,0 +1,376 @@
+/**
+ * Posts Service
+ *
+ * Provides data access methods for posts, separating public queries
+ * (without RLS) from authenticated queries (with RLS).
+ *
+ * @module PostsService
+ */
+
+import { query, queryOne, queryOneWithRLS } from '@nextsparkjs/core/lib/db'
+import type {
+  PostPublic,
+  PostMetadata,
+  PostListOptions,
+  PostListResult,
+  Block,
+  PostCategory,
+} from './posts.types'
+
+// Database row type for post with categories
+interface DbPostWithCategories {
+  id: string
+  slug: string
+  title: string
+  excerpt: string | null
+  featuredImage: string | null
+  blocks: Block[]
+  status: string
+  createdAt: string
+  categories: PostCategory[]
+}
+
+// Database row type for metadata query
+interface DbPostMetadata {
+  title: string
+  excerpt: string | null
+  seoTitle: string | null
+  seoDescription: string | null
+  ogImage: string | null
+  featuredImage: string | null
+}
+
+export class PostsService {
+  // ============================================
+  // PUBLIC METHODS (sin RLS)
+  // ============================================
+
+  /**
+   * Get a published post by slug with categories
+   *
+   * Fetches the full post data including blocks and taxonomy relations.
+   * Only returns published posts.
+   *
+   * @param slug - Post slug
+   * @returns Post data or null if not found/not published
+   *
+   * @example
+   * const post = await PostsService.getPublishedBySlug('my-post-slug')
+   * if (!post) notFound()
+   */
+  static async getPublishedBySlug(slug: string): Promise<PostPublic | null> {
+    try {
+      if (!slug || slug.trim() === '') {
+        throw new Error('Post slug is required')
+      }
+
+      const post = await queryOne<DbPostWithCategories>(
+        `
+        SELECT
+          p.id,
+          p.slug,
+          p.title,
+          p.excerpt,
+          p."featuredImage",
+          p.blocks,
+          p.status,
+          p."createdAt",
+          COALESCE(
+            json_agg(
+              json_build_object(
+                'id', t.id,
+                'name', t.name,
+                'slug', t.slug,
+                'color', t.color
+              )
+            ) FILTER (WHERE t.id IS NOT NULL),
+            '[]'::json
+          ) as categories
+        FROM posts p
+        LEFT JOIN entity_taxonomy_relations etr ON p.id::text = etr."entityId" AND etr."entityType" = 'posts'
+        LEFT JOIN taxonomies t ON etr."taxonomyId" = t.id AND t."isActive" = true AND t."deletedAt" IS NULL
+        WHERE p.slug = $1 AND p.status = 'published'
+        GROUP BY p.id, p.slug, p.title, p.excerpt, p."featuredImage", p.blocks, p.status, p."createdAt"
+        `,
+        [slug]
+      )
+
+      if (!post) {
+        return null
+      }
+
+      return {
+        id: post.id,
+        slug: post.slug,
+        title: post.title,
+        excerpt: post.excerpt ?? undefined,
+        featuredImage: post.featuredImage ?? undefined,
+        blocks: post.blocks,
+        createdAt: post.createdAt,
+        categories: post.categories,
+      }
+    } catch (error) {
+      console.error('PostsService.getPublishedBySlug error:', error)
+      throw new Error(
+        error instanceof Error ? error.message : 'Failed to fetch post'
+      )
+    }
+  }
+
+  /**
+   * Get post metadata for SEO/head tags
+   *
+   * Lightweight query that only fetches SEO-related fields.
+   * Used in generateMetadata for better performance.
+   *
+   * @param slug - Post slug
+   * @returns Metadata or null if not found/not published
+   *
+   * @example
+   * const metadata = await PostsService.getPublishedMetadata('my-post')
+   * return { title: metadata?.seoTitle || metadata?.title }
+   */
+  static async getPublishedMetadata(slug: string): Promise<PostMetadata | null> {
+    try {
+      if (!slug || slug.trim() === '') {
+        throw new Error('Post slug is required')
+      }
+
+      const result = await query<DbPostMetadata>(
+        `
+        SELECT
+          title,
+          excerpt,
+          "seoTitle",
+          "seoDescription",
+          "ogImage",
+          "featuredImage"
+        FROM posts
+        WHERE slug = $1 AND status = 'published'
+        `,
+        [slug]
+      )
+
+      if (result.rows.length === 0) {
+        return null
+      }
+
+      const post = result.rows[0]
+
+      return {
+        title: post.title,
+        excerpt: post.excerpt ?? undefined,
+        seoTitle: post.seoTitle ?? undefined,
+        seoDescription: post.seoDescription ?? undefined,
+        ogImage: post.ogImage ?? undefined,
+        featuredImage: post.featuredImage ?? undefined,
+      }
+    } catch (error) {
+      console.error('PostsService.getPublishedMetadata error:', error)
+      throw new Error(
+        error instanceof Error ? error.message : 'Failed to fetch post metadata'
+      )
+    }
+  }
+
+  /**
+   * List published posts with pagination and filtering
+   *
+   * Used for archive pages like /blog.
+   *
+   * @param options - List options (limit, offset, categorySlug, orderBy, orderDir)
+   * @returns Object with posts array and total count
+   *
+   * @example
+   * const { posts, total } = await PostsService.listPublished({
+   *   limit: 10,
+   *   offset: 0,
+   *   categorySlug: 'news'
+   * })
+   */
+  static async listPublished(
+    options: PostListOptions = {}
+  ): Promise<PostListResult> {
+    try {
+      const {
+        limit = 10,
+        offset = 0,
+        categorySlug,
+        orderBy = 'createdAt',
+        orderDir = 'desc',
+      } = options
+
+      // Build WHERE clause
+      const conditions = ['p.status = $1']
+      const params: unknown[] = ['published']
+      let paramIndex = 2
+
+      // Category filter with subquery
+      if (categorySlug) {
+        conditions.push(`
+          EXISTS (
+            SELECT 1 FROM entity_taxonomy_relations etr
+            JOIN taxonomies t ON etr."taxonomyId" = t.id
+            WHERE etr."entityId" = p.id::text
+              AND etr."entityType" = 'posts'
+              AND t.slug = $${paramIndex}
+              AND t."isActive" = true
+              AND t."deletedAt" IS NULL
+          )
+        `)
+        params.push(categorySlug)
+        paramIndex++
+      }
+
+      const whereClause = conditions.join(' AND ')
+
+      // Validate orderBy to prevent SQL injection
+      const validOrderBy = ['createdAt', 'title'].includes(orderBy) ? orderBy : 'createdAt'
+      const validOrderDir = orderDir === 'asc' ? 'ASC' : 'DESC'
+      const orderColumn = validOrderBy === 'createdAt' ? '"createdAt"' : 'title'
+
+      // Get total count
+      const countResult = await query<{ count: string }>(
+        `SELECT COUNT(*)::text as count FROM posts p WHERE ${whereClause}`,
+        params
+      )
+      const total = parseInt(countResult.rows[0]?.count || '0', 10)
+
+      // Get posts with categories
+      params.push(limit, offset)
+      const postsResult = await query<DbPostWithCategories>(
+        `
+        SELECT
+          p.id,
+          p.slug,
+          p.title,
+          p.excerpt,
+          p."featuredImage",
+          p.blocks,
+          p.status,
+          p."createdAt",
+          COALESCE(
+            json_agg(
+              json_build_object(
+                'id', t.id,
+                'name', t.name,
+                'slug', t.slug,
+                'color', t.color
+              )
+            ) FILTER (WHERE t.id IS NOT NULL),
+            '[]'::json
+          ) as categories
+        FROM posts p
+        LEFT JOIN entity_taxonomy_relations etr ON p.id::text = etr."entityId" AND etr."entityType" = 'posts'
+        LEFT JOIN taxonomies t ON etr."taxonomyId" = t.id AND t."isActive" = true AND t."deletedAt" IS NULL
+        WHERE ${whereClause}
+        GROUP BY p.id, p.slug, p.title, p.excerpt, p."featuredImage", p.blocks, p.status, p."createdAt"
+        ORDER BY p.${orderColumn} ${validOrderDir}
+        LIMIT $${paramIndex} OFFSET $${paramIndex + 1}
+        `,
+        params
+      )
+
+      const posts: PostPublic[] = postsResult.rows.map((post) => ({
+        id: post.id,
+        slug: post.slug,
+        title: post.title,
+        excerpt: post.excerpt ?? undefined,
+        featuredImage: post.featuredImage ?? undefined,
+        blocks: post.blocks,
+        createdAt: post.createdAt,
+        categories: post.categories,
+      }))
+
+      return { posts, total }
+    } catch (error) {
+      console.error('PostsService.listPublished error:', error)
+      throw new Error(
+        error instanceof Error ? error.message : 'Failed to list posts'
+      )
+    }
+  }
+
+  // ============================================
+  // AUTHENTICATED METHODS (con RLS)
+  // ============================================
+
+  /**
+   * Get a post by ID (authenticated)
+   *
+   * For dashboard/admin views. Respects RLS policies.
+   *
+   * @param id - Post ID
+   * @param userId - Current user ID for RLS
+   * @returns Post data or null if not found/not authorized
+   *
+   * @example
+   * const post = await PostsService.getById('post-uuid', currentUserId)
+   */
+  static async getById(
+    id: string,
+    userId: string
+  ): Promise<PostPublic | null> {
+    try {
+      if (!id || id.trim() === '') {
+        throw new Error('Post ID is required')
+      }
+
+      if (!userId || userId.trim() === '') {
+        throw new Error('User ID is required for authentication')
+      }
+
+      const post = await queryOneWithRLS<DbPostWithCategories>(
+        `
+        SELECT
+          p.id,
+          p.slug,
+          p.title,
+          p.excerpt,
+          p."featuredImage",
+          p.blocks,
+          p.status,
+          p."createdAt",
+          COALESCE(
+            json_agg(
+              json_build_object(
+                'id', t.id,
+                'name', t.name,
+                'slug', t.slug,
+                'color', t.color
+              )
+            ) FILTER (WHERE t.id IS NOT NULL),
+            '[]'::json
+          ) as categories
+        FROM posts p
+        LEFT JOIN entity_taxonomy_relations etr ON p.id::text = etr."entityId" AND etr."entityType" = 'posts'
+        LEFT JOIN taxonomies t ON etr."taxonomyId" = t.id AND t."isActive" = true AND t."deletedAt" IS NULL
+        WHERE p.id = $1
+        GROUP BY p.id, p.slug, p.title, p.excerpt, p."featuredImage", p.blocks, p.status, p."createdAt"
+        `,
+        [id],
+        userId
+      )
+
+      if (!post) {
+        return null
+      }
+
+      return {
+        id: post.id,
+        slug: post.slug,
+        title: post.title,
+        excerpt: post.excerpt ?? undefined,
+        featuredImage: post.featuredImage ?? undefined,
+        blocks: post.blocks,
+        createdAt: post.createdAt,
+        categories: post.categories,
+      }
+    } catch (error) {
+      console.error('PostsService.getById error:', error)
+      throw new Error(
+        error instanceof Error ? error.message : 'Failed to fetch post'
+      )
+    }
+  }
+}

package/templates/contents/themes/starter/entities/posts/posts.types.ts

@@ -0,0 +1,74 @@
+/**
+ * Posts Service Types
+ *
+ * Type definitions for the PostsService.
+ * Separates public types (for rendering) from internal types.
+ *
+ * @module PostsTypes
+ */
+
+/**
+ * Block structure for page builder content
+ */
+export interface Block {
+  id: string
+  blockSlug: string
+  props: Record<string, unknown>
+}
+
+/**
+ * Category attached to a post (from taxonomy relations)
+ */
+export interface PostCategory {
+  id: string
+  name: string
+  slug: string
+  color?: string
+}
+
+/**
+ * Post data for public rendering
+ * Includes blocks and categories for full page display
+ */
+export interface PostPublic {
+  id: string
+  slug: string
+  title: string
+  excerpt?: string
+  featuredImage?: string
+  blocks: Block[]
+  createdAt: string
+  categories?: PostCategory[]
+}
+
+/**
+ * Lightweight post metadata for SEO/head tags
+ * Does not include blocks or categories
+ */
+export interface PostMetadata {
+  title: string
+  excerpt?: string
+  seoTitle?: string
+  seoDescription?: string
+  ogImage?: string
+  featuredImage?: string
+}
+
+/**
+ * Options for listing published posts
+ */
+export interface PostListOptions {
+  limit?: number
+  offset?: number
+  categorySlug?: string
+  orderBy?: 'createdAt' | 'title'
+  orderDir?: 'asc' | 'desc'
+}
+
+/**
+ * Result of listing posts with pagination
+ */
+export interface PostListResult {
+  posts: PostPublic[]
+  total: number
+}

package/templates/contents/themes/starter/entities/tasks/api/docs.md

@@ -0,0 +1,132 @@
+# Tasks API
+
+Manage tasks with status tracking, priorities, and metadata support. Tasks are team-scoped private entities.
+
+## Overview
+
+The Tasks API allows you to create, read, update, and delete task records. Tasks support status workflows, priority levels, due dates, and metadata. Each task belongs to a team and is filtered based on the authenticated user's team context.
+
+## Authentication
+
+All endpoints require authentication via:
+- **Session cookie** (for browser-based requests)
+- **API Key** header (for server-to-server requests)
+
+## Endpoints
+
+### List Tasks
+`GET /api/v1/tasks`
+
+Returns a paginated list of tasks for the current team.
+
+**Query Parameters:**
+- `limit` (number, optional): Maximum records to return. Default: 20
+- `offset` (number, optional): Number of records to skip. Default: 0
+- `status` (string, optional): Filter by status (todo, in-progress, review, done, blocked)
+- `priority` (string, optional): Filter by priority (low, medium, high, urgent)
+- `search` (string, optional): Search term for title/description
+- `sortBy` (string, optional): Field to sort by
+- `sortOrder` (string, optional): Sort direction (asc, desc)
+
+**Example Response:**
+```json
+{
+  "data": [
+    {
+      "id": "task_123",
+      "title": "Implement new feature",
+      "description": "Add user authentication flow",
+      "status": "in-progress",
+      "priority": "high",
+      "dueDate": "2024-02-01",
+      "estimatedHours": 8,
+      "tags": ["feature", "auth"],
+      "createdAt": "2024-01-15T10:30:00Z"
+    }
+  ],
+  "pagination": {
+    "total": 42,
+    "limit": 20,
+    "offset": 0
+  }
+}
+```
+
+### Get Single Task
+`GET /api/v1/tasks/[id]`
+
+Returns a single task by ID.
+
+**Path Parameters:**
+- `id` (string, required): Task ID
+
+### Create Task
+`POST /api/v1/tasks`
+
+Create a new task record.
+
+**Request Body:**
+```json
+{
+  "title": "New Task",
+  "description": "Task details here",
+  "status": "todo",
+  "priority": "medium",
+  "dueDate": "2024-02-15",
+  "estimatedHours": 4,
+  "tags": ["development"]
+}
+```
+
+### Update Task
+`PATCH /api/v1/tasks/[id]`
+
+Update an existing task.
+
+**Path Parameters:**
+- `id` (string, required): Task ID
+
+**Request Body:**
+Any fields to update (partial update supported).
+
+### Delete Task
+`DELETE /api/v1/tasks/[id]`
+
+Delete a task record.
+
+**Path Parameters:**
+- `id` (string, required): Task ID
+
+## Fields
+
+| Field | Type | Required | Default | Description |
+|-------|------|----------|---------|-------------|
+| title | text | Yes | - | Task title |
+| description | textarea | No | - | Detailed description |
+| status | select | No | todo | todo, in-progress, review, done, blocked |
+| priority | select | No | medium | low, medium, high, urgent |
+| tags | tags | No | [] | Task tags for categorization |
+| dueDate | date | No | - | Task deadline |
+| estimatedHours | number | No | - | Estimated time to complete |
+
+## Metadata Support
+
+Tasks support the metadata system. Use the metadata endpoints to store additional custom data:
+- `POST /api/v1/tasks/[id]/meta` - Add metadata
+- `GET /api/v1/tasks/[id]/meta` - Get metadata
+
+## Error Responses
+
+| Status | Description |
+|--------|-------------|
+| 400 | Bad Request - Invalid parameters |
+| 401 | Unauthorized - Missing or invalid auth |
+| 403 | Forbidden - Insufficient permissions |
+| 404 | Not Found - Task doesn't exist |
+| 422 | Validation Error - Invalid data |
+
+## Related APIs
+
+- **[Dynamic Entity API](/api/v1/{entity})** - Generic entity operations documentation
+- **[Teams](/api/v1/teams)** - Tasks are team-scoped
+- **[Media](/api/v1/media)** - Upload attachments for tasks