@nextsparkjs/theme-blog 0.1.0-beta.1

package/entities/categories/categories.fields.ts

@@ -0,0 +1,115 @@
+/**
+ * Categories Entity Fields Configuration
+ *
+ * Field definitions for blog categories.
+ */
+
+import type { EntityField } from '@nextsparkjs/core/lib/entities/types'
+
+export const categoryFields: EntityField[] = [
+  // ==========================================
+  // BASIC INFORMATION
+  // ==========================================
+  {
+    name: 'name',
+    type: 'text',
+    required: true,
+    display: {
+      label: 'Name',
+      description: 'The name of the category',
+      placeholder: 'Enter category name...',
+      showInList: true,
+      showInDetail: true,
+      showInForm: true,
+      order: 1,
+      columnWidth: 6,
+    },
+    api: {
+      readOnly: false,
+      searchable: true,
+      sortable: true,
+    },
+  },
+  {
+    name: 'slug',
+    type: 'text',
+    required: true,
+    display: {
+      label: 'Slug',
+      description: 'URL-friendly version of the name (auto-generated)',
+      placeholder: 'category-slug',
+      showInList: true,
+      showInDetail: true,
+      showInForm: true,
+      order: 2,
+      columnWidth: 6,
+    },
+    api: {
+      readOnly: false,
+      searchable: false,
+      sortable: true,
+    },
+  },
+  {
+    name: 'description',
+    type: 'textarea',
+    required: false,
+    display: {
+      label: 'Description',
+      description: 'A brief description of this category',
+      placeholder: 'Describe what this category is about...',
+      showInList: false,
+      showInDetail: true,
+      showInForm: true,
+      order: 3,
+      columnWidth: 12,
+    },
+    api: {
+      readOnly: false,
+      searchable: true,
+      sortable: false,
+    },
+  },
+
+  // ==========================================
+  // TIMESTAMPS
+  // ==========================================
+  {
+    name: 'createdAt',
+    type: 'datetime',
+    required: false,
+    display: {
+      label: 'Created At',
+      description: 'When the category was created',
+      showInList: false,
+      showInDetail: true,
+      showInForm: false,
+      order: 98,
+      columnWidth: 6,
+    },
+    api: {
+      readOnly: true,
+      searchable: false,
+      sortable: true,
+    },
+  },
+  {
+    name: 'updatedAt',
+    type: 'datetime',
+    required: false,
+    display: {
+      label: 'Updated At',
+      description: 'When the category was last modified',
+      showInList: false,
+      showInDetail: true,
+      showInForm: false,
+      order: 99,
+      columnWidth: 6,
+    },
+    api: {
+      readOnly: true,
+      searchable: false,
+      sortable: true,
+    },
+  },
+]

package/entities/categories/categories.service.ts

@@ -0,0 +1,333 @@
+/**
+ * Categories Service
+ *
+ * Provides data access methods for blog categories.
+ * Categories is a private entity - users only see categories in their team.
+ *
+ * All methods require authentication (use RLS with userId filter).
+ *
+ * @module CategoriesService
+ */
+
+import { queryOneWithRLS, queryWithRLS, mutateWithRLS } from '@nextsparkjs/core/lib/db'
+
+// Category interface
+export interface Category {
+  id: string
+  name: string
+  slug: string
+  description?: string
+  createdAt: string
+  updatedAt: string
+}
+
+// List options
+export interface CategoryListOptions {
+  limit?: number
+  offset?: number
+  orderBy?: 'name' | 'slug' | 'createdAt'
+  orderDir?: 'asc' | 'desc'
+  teamId?: string
+}
+
+// List result
+export interface CategoryListResult {
+  categories: Category[]
+  total: number
+}
+
+// Create data
+export interface CategoryCreateData {
+  name: string
+  slug: string
+  description?: string
+  teamId: string
+}
+
+// Update data
+export interface CategoryUpdateData {
+  name?: string
+  slug?: string
+  description?: string
+}
+
+// Database row type
+interface DbCategory {
+  id: string
+  name: string
+  slug: string
+  description: string | null
+  createdAt: string
+  updatedAt: string
+}
+
+export class CategoriesService {
+  // ============================================
+  // READ METHODS
+  // ============================================
+
+  /**
+   * Get a category by ID
+   */
+  static async getById(id: string, userId: string): Promise<Category | null> {
+    try {
+      if (!id?.trim()) throw new Error('Category ID is required')
+      if (!userId?.trim()) throw new Error('User ID is required')
+
+      const category = await queryOneWithRLS<DbCategory>(
+        `SELECT id, name, slug, description, "createdAt", "updatedAt"
+         FROM categories WHERE id = $1`,
+        [id],
+        userId
+      )
+
+      if (!category) return null
+
+      return {
+        id: category.id,
+        name: category.name,
+        slug: category.slug,
+        description: category.description ?? undefined,
+        createdAt: category.createdAt,
+        updatedAt: category.updatedAt,
+      }
+    } catch (error) {
+      console.error('CategoriesService.getById error:', error)
+      throw new Error(error instanceof Error ? error.message : 'Failed to fetch category')
+    }
+  }
+
+  /**
+   * Get a category by slug
+   */
+  static async getBySlug(slug: string, userId: string): Promise<Category | null> {
+    try {
+      if (!slug?.trim()) throw new Error('Slug is required')
+      if (!userId?.trim()) throw new Error('User ID is required')
+
+      const category = await queryOneWithRLS<DbCategory>(
+        `SELECT id, name, slug, description, "createdAt", "updatedAt"
+         FROM categories WHERE slug = $1`,
+        [slug],
+        userId
+      )
+
+      if (!category) return null
+
+      return {
+        id: category.id,
+        name: category.name,
+        slug: category.slug,
+        description: category.description ?? undefined,
+        createdAt: category.createdAt,
+        updatedAt: category.updatedAt,
+      }
+    } catch (error) {
+      console.error('CategoriesService.getBySlug error:', error)
+      throw new Error(error instanceof Error ? error.message : 'Failed to fetch category')
+    }
+  }
+
+  /**
+   * List categories with pagination
+   */
+  static async list(userId: string, options: CategoryListOptions = {}): Promise<CategoryListResult> {
+    try {
+      if (!userId?.trim()) throw new Error('User ID is required')
+
+      const {
+        limit = 50,
+        offset = 0,
+        orderBy = 'name',
+        orderDir = 'asc',
+        teamId,
+      } = options
+
+      // Build WHERE clause
+      const conditions: string[] = []
+      const params: unknown[] = []
+      let paramIndex = 1
+
+      if (teamId) {
+        conditions.push(`"teamId" = $${paramIndex++}`)
+        params.push(teamId)
+      }
+
+      const whereClause = conditions.length > 0 ? `WHERE ${conditions.join(' AND ')}` : ''
+
+      // Validate orderBy
+      const validOrderBy = ['name', 'slug', 'createdAt'].includes(orderBy) ? orderBy : 'name'
+      const validOrderDir = orderDir === 'desc' ? 'DESC' : 'ASC'
+      const orderColumnMap: Record<string, string> = {
+        name: 'name',
+        slug: 'slug',
+        createdAt: '"createdAt"',
+      }
+      const orderColumn = orderColumnMap[validOrderBy] || 'name'
+
+      // Get total count
+      const countResult = await queryWithRLS<{ count: string }>(
+        `SELECT COUNT(*)::text as count FROM categories ${whereClause}`,
+        params,
+        userId
+      )
+      const total = parseInt(countResult[0]?.count || '0', 10)
+
+      // Get categories
+      params.push(limit, offset)
+      const categories = await queryWithRLS<DbCategory>(
+        `SELECT id, name, slug, description, "createdAt", "updatedAt"
+         FROM categories ${whereClause}
+         ORDER BY ${orderColumn} ${validOrderDir}
+         LIMIT $${paramIndex} OFFSET $${paramIndex + 1}`,
+        params,
+        userId
+      )
+
+      return {
+        categories: categories.map((cat) => ({
+          id: cat.id,
+          name: cat.name,
+          slug: cat.slug,
+          description: cat.description ?? undefined,
+          createdAt: cat.createdAt,
+          updatedAt: cat.updatedAt,
+        })),
+        total,
+      }
+    } catch (error) {
+      console.error('CategoriesService.list error:', error)
+      throw new Error(error instanceof Error ? error.message : 'Failed to list categories')
+    }
+  }
+
+  /**
+   * Get all categories (no pagination)
+   */
+  static async getAll(userId: string): Promise<Category[]> {
+    const { categories } = await this.list(userId, { limit: 1000 })
+    return categories
+  }
+
+  // ============================================
+  // WRITE METHODS
+  // ============================================
+
+  /**
+   * Create a new category
+   */
+  static async create(userId: string, data: CategoryCreateData): Promise<Category> {
+    try {
+      if (!userId?.trim()) throw new Error('User ID is required')
+      if (!data.name?.trim()) throw new Error('Name is required')
+      if (!data.slug?.trim()) throw new Error('Slug is required')
+      if (!data.teamId?.trim()) throw new Error('Team ID is required')
+
+      const id = crypto.randomUUID()
+      const now = new Date().toISOString()
+
+      const result = await mutateWithRLS<DbCategory>(
+        `INSERT INTO categories (id, "userId", "teamId", name, slug, description, "createdAt", "updatedAt")
+         VALUES ($1, $2, $3, $4, $5, $6, $7, $8)
+         RETURNING id, name, slug, description, "createdAt", "updatedAt"`,
+        [
+          id,
+          userId,
+          data.teamId,
+          data.name,
+          data.slug,
+          data.description || null,
+          now,
+          now,
+        ],
+        userId
+      )
+
+      if (!result.rows[0]) throw new Error('Failed to create category')
+
+      const category = result.rows[0]
+      return {
+        id: category.id,
+        name: category.name,
+        slug: category.slug,
+        description: category.description ?? undefined,
+        createdAt: category.createdAt,
+        updatedAt: category.updatedAt,
+      }
+    } catch (error) {
+      console.error('CategoriesService.create error:', error)
+      throw new Error(error instanceof Error ? error.message : 'Failed to create category')
+    }
+  }
+
+  /**
+   * Update an existing category
+   */
+  static async update(userId: string, id: string, data: CategoryUpdateData): Promise<Category> {
+    try {
+      if (!userId?.trim()) throw new Error('User ID is required')
+      if (!id?.trim()) throw new Error('Category ID is required')
+
+      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 (updates.length === 0) throw new Error('No fields to update')
+
+      updates.push(`"updatedAt" = $${paramIndex++}`)
+      values.push(new Date().toISOString())
+      values.push(id)
+
+      const result = await mutateWithRLS<DbCategory>(
+        `UPDATE categories SET ${updates.join(', ')} WHERE id = $${paramIndex}
+         RETURNING id, name, slug, description, "createdAt", "updatedAt"`,
+        values,
+        userId
+      )
+
+      if (!result.rows[0]) throw new Error('Category not found or update failed')
+
+      const category = result.rows[0]
+      return {
+        id: category.id,
+        name: category.name,
+        slug: category.slug,
+        description: category.description ?? undefined,
+        createdAt: category.createdAt,
+        updatedAt: category.updatedAt,
+      }
+    } catch (error) {
+      console.error('CategoriesService.update error:', error)
+      throw new Error(error instanceof Error ? error.message : 'Failed to update category')
+    }
+  }
+
+  /**
+   * Delete a category
+   */
+  static async delete(userId: string, id: string): Promise<boolean> {
+    try {
+      if (!userId?.trim()) throw new Error('User ID is required')
+      if (!id?.trim()) throw new Error('Category ID is required')
+
+      const result = await mutateWithRLS(`DELETE FROM categories WHERE id = $1`, [id], userId)
+      return result.rowCount > 0
+    } catch (error) {
+      console.error('CategoriesService.delete error:', error)
+      throw new Error(error instanceof Error ? error.message : 'Failed to delete category')
+    }
+  }
+}

package/entities/categories/categories.types.ts

@@ -0,0 +1,58 @@
+/**
+ * Categories Service Types
+ *
+ * Type definitions for the CategoriesService.
+ * Categories is a private entity - users only see categories in their team.
+ *
+ * @module CategoriesTypes
+ */
+
+/**
+ * Category entity
+ */
+export interface Category {
+  id: string
+  name: string
+  slug: string
+  description?: string
+  createdAt: string
+  updatedAt: string
+}
+
+/**
+ * Options for listing categories
+ */
+export interface CategoryListOptions {
+  limit?: number
+  offset?: number
+  teamId?: string
+  orderBy?: 'name' | 'slug' | 'createdAt'
+  orderDir?: 'asc' | 'desc'
+}
+
+/**
+ * Result of listing categories with pagination
+ */
+export interface CategoryListResult {
+  categories: Category[]
+  total: number
+}
+
+/**
+ * Data required to create a new category
+ */
+export interface CategoryCreateData {
+  name: string
+  slug: string
+  teamId: string
+  description?: string
+}
+
+/**
+ * Data for updating an existing category
+ */
+export interface CategoryUpdateData {
+  name?: string
+  slug?: string
+  description?: string
+}

package/entities/categories/messages/en.json

@@ -0,0 +1,33 @@
+{
+  "entity": {
+    "name": "Category",
+    "namePlural": "Categories",
+    "description": "Organize your blog posts by category"
+  },
+  "fields": {
+    "name": "Name",
+    "slug": "Slug",
+    "description": "Description",
+    "createdAt": "Created At",
+    "updatedAt": "Updated At"
+  },
+  "actions": {
+    "create": "Create Category",
+    "edit": "Edit Category",
+    "delete": "Delete Category",
+    "view": "View Category",
+    "list": "List Categories"
+  },
+  "messages": {
+    "created": "Category created successfully",
+    "updated": "Category updated successfully",
+    "deleted": "Category deleted successfully",
+    "notFound": "Category not found",
+    "listEmpty": "No categories found. Create your first category to organize your posts."
+  },
+  "validation": {
+    "nameRequired": "Category name is required",
+    "slugRequired": "Slug is required",
+    "slugInvalid": "Slug must be URL-friendly (lowercase letters, numbers, and hyphens only)"
+  }
+}

package/entities/categories/messages/es.json

@@ -0,0 +1,33 @@
+{
+  "entity": {
+    "name": "Categoría",
+    "namePlural": "Categorías",
+    "description": "Organiza tus posts por categoría"
+  },
+  "fields": {
+    "name": "Nombre",
+    "slug": "Slug",
+    "description": "Descripción",
+    "createdAt": "Creado el",
+    "updatedAt": "Actualizado el"
+  },
+  "actions": {
+    "create": "Crear Categoría",
+    "edit": "Editar Categoría",
+    "delete": "Eliminar Categoría",
+    "view": "Ver Categoría",
+    "list": "Listar Categorías"
+  },
+  "messages": {
+    "created": "Categoría creada exitosamente",
+    "updated": "Categoría actualizada exitosamente",
+    "deleted": "Categoría eliminada exitosamente",
+    "notFound": "Categoría no encontrada",
+    "listEmpty": "No se encontraron categorías. Crea tu primera categoría para organizar tus posts."
+  },
+  "validation": {
+    "nameRequired": "El nombre de la categoría es requerido",
+    "slugRequired": "El slug es requerido",
+    "slugInvalid": "El slug debe ser compatible con URLs (solo letras minúsculas, números y guiones)"
+  }
+}

package/entities/posts/messages/en.json

@@ -0,0 +1,100 @@
+{
+  "title": "Posts",
+  "singular": "Post",
+  "plural": "Posts",
+  "description": "Manage your blog posts",
+
+  "fields": {
+    "title": {
+      "label": "Title",
+      "placeholder": "Enter a compelling title...",
+      "description": "The title of your blog post"
+    },
+    "slug": {
+      "label": "Slug",
+      "placeholder": "my-blog-post",
+      "description": "URL-friendly version of the title"
+    },
+    "excerpt": {
+      "label": "Excerpt",
+      "placeholder": "Write a brief summary of your post...",
+      "description": "A short summary shown in post listings"
+    },
+    "content": {
+      "label": "Content",
+      "placeholder": "Start writing your post...",
+      "description": "The main content of your blog post"
+    },
+    "featuredImage": {
+      "label": "Featured Image",
+      "placeholder": "Upload an image...",
+      "description": "Main image displayed with the post"
+    },
+    "category": {
+      "label": "Category",
+      "placeholder": "e.g., Technology, Travel, Food",
+      "description": "Main category for the post"
+    },
+    "tags": {
+      "label": "Tags",
+      "placeholder": "Add tags...",
+      "description": "Keywords to help readers find this post"
+    },
+    "status": {
+      "label": "Status",
+      "placeholder": "Select status...",
+      "description": "Publication status",
+      "options": {
+        "draft": "Draft",
+        "published": "Published",
+        "scheduled": "Scheduled"
+      }
+    },
+    "publishedAt": {
+      "label": "Publish Date",
+      "placeholder": "Select date...",
+      "description": "When the post was/will be published"
+    },
+    "createdAt": {
+      "label": "Created At",
+      "description": "When the post was created"
+    },
+    "updatedAt": {
+      "label": "Updated At",
+      "description": "When the post was last modified"
+    }
+  },
+
+  "actions": {
+    "create": "New Post",
+    "edit": "Edit Post",
+    "delete": "Delete Post",
+    "publish": "Publish",
+    "unpublish": "Unpublish",
+    "saveDraft": "Save Draft",
+    "preview": "Preview"
+  },
+
+  "messages": {
+    "created": "Post created successfully",
+    "updated": "Post updated successfully",
+    "deleted": "Post deleted successfully",
+    "published": "Post published successfully",
+    "unpublished": "Post unpublished",
+    "confirmDelete": "Are you sure you want to delete this post? This action cannot be undone."
+  },
+
+  "empty": {
+    "title": "No posts yet",
+    "description": "Get started by writing your first blog post.",
+    "action": "Write your first post"
+  },
+
+  "filters": {
+    "all": "All Posts",
+    "published": "Published",
+    "draft": "Drafts",
+    "scheduled": "Scheduled"
+  }
+}
+