@nextsparkjs/theme-default 0.1.0-beta.1

package/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/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/entities/tasks/messages/en.json

@@ -0,0 +1,204 @@
+{
+  "title": "My Tasks",
+  "subtitle": "Organize your work and keep control of your projects.",
+  "description": "Organize your work and keep control of your projects.",
+  "stats": {
+    "active": "Active",
+    "completed": "Completed",
+    "total": "Total Tasks",
+    "totalDescription": "All tasks in the system",
+    "pending": "Pending",
+    "pendingDescription": "Tasks waiting to be completed",
+    "overdue": "Overdue"
+  },
+  "form": {
+    "addTitle": "Add New Task",
+    "addDescription": "Create a new task to keep track of what needs to be done",
+    "titleLabel": "Task title",
+    "titlePlaceholder": "What needs to be done?",
+    "titleDescription": "Enter the title of the new task. This field is required.",
+    "descriptionLabel": "Task description (optional)",
+    "descriptionPlaceholder": "Add a description (optional)",
+    "descriptionHelp": "Optional description to provide more details about the task.",
+    "addButton": "Add Task",
+    "adding": "Adding...",
+    "enterTitle": "Enter a title to enable the create task button",
+    "creating": "Creating task, please wait",
+    "pressToCreate": "Press to create the new task",
+    "addSuccess": "Task added successfully!",
+    "addError": "Failed to add task",
+    "tryAgain": "Please try again later",
+    "taskCreated": "Task \"{title}\" created successfully",
+    "createError": "Error creating task \"{title}\""
+  },
+  "task": {
+    "completed": "completed",
+    "active": "active",
+    "deleteConfirm": "Are you sure you want to delete this task?",
+    "deleteSuccess": "Task deleted successfully",
+    "toggleSuccess": "Task status updated"
+  },
+  "overview": {
+    "title": "Tasks Overview",
+    "label": "Tasks summary",
+    "activeTasks": "{count} active tasks",
+    "completedTasks": "{count} completed tasks",
+    "totalTasks": "{count} total tasks"
+  },
+  "actions": {
+    "completed": "Task completed!",
+    "reactivated": "Task reactivated!",
+    "deleted": "Task deleted",
+    "markCompleted": "completed",
+    "markPending": "pending",
+    "taskStatusChanged": "Task \"{title}\" {action}",
+    "taskDeleted": "Task \"{title}\" deleted",
+    "toggleError": "Error changing status of task \"{title}\"",
+    "deleteError": "Error deleting task",
+    "updateError": "Error updating task"
+  },
+  "status": {
+    "completed": "Completed",
+    "pending": "Pending",
+    "active": "Active",
+    "todo": "To Do",
+    "in-progress": "In Progress",
+    "review": "In Review",
+    "done": "Done",
+    "blocked": "Blocked"
+  },
+  "priority": {
+    "low": "Low",
+    "medium": "Medium",
+    "high": "High",
+    "urgent": "Urgent"
+  },
+  "fields": {
+    "status": "Status",
+    "priority": "Priority",
+    "tags": "Tags",
+    "dueDate": "Due Date",
+    "estimatedHours": "Estimated Hours",
+    "tagsPlaceholder": "Add tags...",
+    "dueDatePlaceholder": "Select due date...",
+    "estimatedHoursPlaceholder": "0",
+    "statusDescription": "Current task status",
+    "priorityDescription": "Task priority level",
+    "tagsDescription": "Task tags for categorization",
+    "dueDateDescription": "Task deadline",
+    "estimatedHoursDescription": "Estimated time to complete (in hours)"
+  },
+  "sections": {
+    "activeTasks": "Active Tasks",
+    "completedTasks": "Completed Tasks"
+  },
+  "empty": {
+    "title": "No tasks yet",
+    "description": "Add your first task above to get started!"
+  },
+  "accessibility": {
+    "taskCard": "Task: {title}. {status}. Press Enter to view details.",
+    "completedTaskCard": "Completed task: {title}. Press Enter to view details.",
+    "toggleTask": "Mark task \"{title}\" as {action}",
+    "reactivateTask": "Reactivate completed task \"{title}\"",
+    "deleteTask": "Delete task \"{title}\"",
+    "deleteCompletedTask": "Delete completed task \"{title}\"",
+    "createdDate": "Created on {date}",
+    "completedDate": "Completed on {date}"
+  },
+  "time": {
+    "daysAgo": "{count} day{count, plural, one {} other {s}} ago",
+    "hoursAgo": "{count} hour{count, plural, one {} other {s}} ago",
+    "minutesAgo": "{count} minute{count, plural, one {} other {s}} ago",
+    "justNow": "Just now"
+  },
+  "page": {
+    "statsAriaLabel": "Task statistics",
+    "listTitle": "Tasks List",
+    "listDescription": "Manage your pending tasks and get better organized",
+    "today": "Today"
+  },
+  "list": {
+    "title": "Tasks List",
+    "description": "Manage all your tasks in one place",
+    "allTasks": "All Tasks"
+  },
+  "detail": {
+    "loading": {
+      "message": "Loading task details",
+      "ariaLabel": "Loading task details",
+      "srText": "Loading task details..."
+    },
+    "navigation": {
+      "backToTasks": "Back to Tasks",
+      "backAriaLabel": "Back to task list",
+      "returnNavigation": "Return navigation",
+      "viewAllTasks": "View all tasks",
+      "viewAllDescription": "Navigate back to the complete task list"
+    },
+    "error": {
+      "notFound": "Could not find the requested task. It may have been deleted or you don't have permissions to view it.",
+      "title": "Task not found"
+    },
+    "status": {
+      "completed": "Completed",
+      "pending": "Pending",
+      "active": "In progress",
+      "completedAriaLabel": "Task completed",
+      "pendingAriaLabel": "Task pending"
+    },
+    "priority": {
+      "high": "High",
+      "medium": "Medium",
+      "low": "Low",
+      "label": "Priority"
+    },
+    "categories": {
+      "design": "Design",
+      "development": "Development",
+      "meetings": "Meetings",
+      "documentation": "Documentation",
+      "testing": "Testing",
+      "general": "General"
+    },
+    "sections": {
+      "description": "Description",
+      "actions": "Actions",
+      "information": "Information",
+      "classification": "Classification",
+      "metadata": "Task metadata"
+    },
+    "actions": {
+      "title": "Actions",
+      "description": "Manage the status and options for this task. Keyboard shortcuts: Cmd+Enter to complete, Cmd+Backspace to delete.",
+      "markPending": "Mark Pending",
+      "markCompleted": "Mark Completed",
+      "delete": "Delete",
+      "markPendingAriaLabel": "Mark task \"{title}\" as pending. Shortcut: Cmd+Enter",
+      "markCompletedAriaLabel": "Mark task \"{title}\" as completed. Shortcut: Cmd+Enter",
+      "deleteAriaLabel": "Permanently delete task \"{title}\". Shortcut: Cmd+Backspace"
+    },
+    "info": {
+      "created": "Created",
+      "lastUpdate": "Last update",
+      "status": "Status",
+      "priority": "Priority", 
+      "category": "Category",
+      "taskId": "Task ID",
+      "noDescription": "No description available for this task.",
+      "inferredInfo": "Automatically inferred information"
+    },
+    "messages": {
+      "taskCompleted": "Task \"{title}\" completed successfully",
+      "taskReactivated": "Task \"{title}\" reactivated successfully",
+      "taskDeleted": "Task \"{title}\" deleted successfully",
+      "toggleError": "Error changing status of task \"{title}\"",
+      "deleteError": "Error deleting task \"{title}\"",
+      "completedToast": "Task completed",
+      "reactivatedToast": "Task reactivated",
+      "deletedToast": "Task deleted",
+      "updateErrorToast": "Error updating task",
+      "deleteErrorToast": "Error deleting task"
+    }
+  }
+}