@nextsparkjs/core 0.1.0-beta.1 → 0.1.0-beta.3

package/dist/templates/features/blog/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/dist/templates/features/blog/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/dist/templates/features/pages/entities/pages/messages/en.json

@@ -0,0 +1,41 @@
+{
+  "entity": {
+    "singular": "Page",
+    "plural": "Pages"
+  },
+  "fields": {
+    "title": {
+      "label": "Title",
+      "placeholder": "Enter page title...",
+      "description": "Page title displayed in browser and navigation"
+    },
+    "slug": {
+      "label": "Slug",
+      "placeholder": "page-slug",
+      "description": "URL-friendly identifier (e.g., 'about' for /about)"
+    },
+    "status": {
+      "label": "Status",
+      "description": "Publication status",
+      "options": {
+        "draft": "Draft",
+        "published": "Published",
+        "scheduled": "Scheduled",
+        "archived": "Archived"
+      }
+    }
+  },
+  "actions": {
+    "create": "Create Page",
+    "edit": "Edit Page",
+    "delete": "Delete Page",
+    "publish": "Publish",
+    "unpublish": "Unpublish"
+  },
+  "messages": {
+    "created": "Page created successfully",
+    "updated": "Page updated successfully",
+    "deleted": "Page deleted successfully",
+    "published": "Page published successfully"
+  }
+}

package/dist/templates/features/pages/entities/pages/messages/es.json

@@ -0,0 +1,41 @@
+{
+  "entity": {
+    "singular": "Pagina",
+    "plural": "Paginas"
+  },
+  "fields": {
+    "title": {
+      "label": "Titulo",
+      "placeholder": "Ingresa el titulo de la pagina...",
+      "description": "Titulo de la pagina mostrado en el navegador y navegacion"
+    },
+    "slug": {
+      "label": "Slug",
+      "placeholder": "slug-pagina",
+      "description": "Identificador amigable para URL (ej: 'acerca' para /acerca)"
+    },
+    "status": {
+      "label": "Estado",
+      "description": "Estado de publicacion",
+      "options": {
+        "draft": "Borrador",
+        "published": "Publicado",
+        "scheduled": "Programado",
+        "archived": "Archivado"
+      }
+    }
+  },
+  "actions": {
+    "create": "Crear Pagina",
+    "edit": "Editar Pagina",
+    "delete": "Eliminar Pagina",
+    "publish": "Publicar",
+    "unpublish": "Despublicar"
+  },
+  "messages": {
+    "created": "Pagina creada exitosamente",
+    "updated": "Pagina actualizada exitosamente",
+    "deleted": "Pagina eliminada exitosamente",
+    "published": "Pagina publicada exitosamente"
+  }
+}

package/dist/templates/features/pages/entities/pages/migrations/001_pages_table.sql

@@ -0,0 +1,112 @@
+-- Migration: 008_pages_table.sql
+-- Description: Create pages table for dynamic page builder system with blocks
+-- Date: 2025-01-21
+-- Updated: 2025-12-17 (Add userId, teamId system fields + team isolation RLS)
+
+-- ============================================
+-- TABLE: pages
+-- ============================================
+DROP TABLE IF EXISTS public.pages CASCADE;
+
+CREATE TABLE IF NOT EXISTS public.pages (
+  id              UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+
+  -- Relational Fields (at the beginning)
+  "userId"        TEXT NOT NULL REFERENCES public."users"(id) ON DELETE CASCADE,
+  "teamId"        TEXT NOT NULL REFERENCES public."teams"(id) ON DELETE CASCADE,
+
+  slug            VARCHAR(255) NOT NULL,
+  title           VARCHAR(255) NOT NULL,
+  blocks          JSONB NOT NULL DEFAULT '[]'::JSONB,
+  locale          VARCHAR(10) NOT NULL DEFAULT 'en',
+
+  -- SEO fields
+  "seoTitle"       VARCHAR(255),
+  "seoDescription" TEXT,
+  "seoKeywords"    TEXT,
+  "ogImage"        TEXT,
+  noindex          BOOLEAN DEFAULT FALSE,
+  nofollow         BOOLEAN DEFAULT FALSE,
+
+  -- Meta fields
+  published        BOOLEAN DEFAULT FALSE,
+  "authorId"       TEXT REFERENCES public."users"(id) ON DELETE SET NULL,
+  "createdAt"      TIMESTAMPTZ NOT NULL DEFAULT now(),
+  "updatedAt"      TIMESTAMPTZ NOT NULL DEFAULT now(),
+
+  -- Constraints
+  CONSTRAINT unique_slug_locale UNIQUE(slug, locale),
+  CONSTRAINT valid_slug CHECK (slug ~ '^[a-z0-9\-]+$'),
+  CONSTRAINT valid_locale CHECK (locale ~ '^[a-z]{2}(-[A-Z]{2})?$'),
+  CONSTRAINT slug_length CHECK (LENGTH(slug) >= 2 AND LENGTH(slug) <= 100),
+  CONSTRAINT title_not_empty CHECK (LENGTH(TRIM(title)) > 0)
+);
+
+-- ============================================
+-- COMMENTS
+-- ============================================
+COMMENT ON TABLE  public.pages                  IS 'Dynamic pages created via block editor system';
+COMMENT ON COLUMN public.pages."userId"         IS 'User who created this page';
+COMMENT ON COLUMN public.pages."teamId"         IS 'Team context for isolation';
+COMMENT ON COLUMN public.pages.blocks           IS 'Array of block instances with props (JSONB)';
+COMMENT ON COLUMN public.pages.slug             IS 'URL-friendly identifier (lowercase, hyphens only)';
+COMMENT ON COLUMN public.pages.locale           IS 'Language/locale code (e.g., en, es, en-US)';
+
+-- ============================================
+-- TRIGGER: updatedAt
+-- ============================================
+DROP TRIGGER IF EXISTS pages_set_updated_at ON public.pages;
+CREATE TRIGGER pages_set_updated_at
+BEFORE UPDATE ON public.pages
+FOR EACH ROW EXECUTE FUNCTION public.set_updated_at();
+
+-- ============================================
+-- INDEXES
+-- ============================================
+CREATE INDEX IF NOT EXISTS idx_pages_user_id            ON public.pages("userId");
+CREATE INDEX IF NOT EXISTS idx_pages_team_id            ON public.pages("teamId");
+CREATE INDEX IF NOT EXISTS idx_pages_slug               ON public.pages(slug);
+CREATE INDEX IF NOT EXISTS idx_pages_locale             ON public.pages(locale);
+CREATE INDEX IF NOT EXISTS idx_pages_published          ON public.pages(published);
+CREATE INDEX IF NOT EXISTS idx_pages_author             ON public.pages("authorId");
+CREATE INDEX IF NOT EXISTS idx_pages_created            ON public.pages("createdAt" DESC);
+CREATE INDEX IF NOT EXISTS idx_pages_slug_locale        ON public.pages(slug, locale);
+CREATE INDEX IF NOT EXISTS idx_pages_published_locale   ON public.pages(published, locale) WHERE published = TRUE;
+CREATE INDEX IF NOT EXISTS idx_pages_blocks_gin         ON public.pages USING GIN (blocks);
+CREATE INDEX IF NOT EXISTS idx_pages_team_created       ON public.pages("teamId", "createdAt" DESC);
+
+-- ============================================
+-- RLS
+-- ============================================
+ALTER TABLE public.pages ENABLE ROW LEVEL SECURITY;
+
+DROP POLICY IF EXISTS "pages public can select" ON public.pages;
+DROP POLICY IF EXISTS "pages auth can do all"   ON public.pages;
+DROP POLICY IF EXISTS "Pages team can do all"   ON public.pages;
+
+-- Public can read published pages
+CREATE POLICY "pages public can select"
+ON public.pages
+FOR SELECT TO anon
+USING (published = TRUE);
+
+-- ============================
+-- RLS: TEAM ISOLATION ONLY
+-- ============================
+-- IMPORTANT: RLS only verifies team membership
+-- access.shared logic (user isolation) is handled at APP LEVEL
+CREATE POLICY "Pages team can do all"
+ON public.pages
+FOR ALL TO authenticated
+USING (
+  -- Superadmin bypass
+  public.is_superadmin()
+  OR
+  -- Team isolation only: user must be member of the team
+  "teamId" = ANY(public.get_user_team_ids())
+)
+WITH CHECK (
+  public.is_superadmin()
+  OR
+  "teamId" = ANY(public.get_user_team_ids())
+);

package/dist/templates/features/pages/entities/pages/migrations/002_pages_metas.sql

@@ -0,0 +1,56 @@
+-- Migration: 002_pages_metas.sql
+-- Description: Create pages_metas table for flexible key-value metadata storage
+-- Date: 2025-01-25
+
+-- Create pages_metas table
+CREATE TABLE IF NOT EXISTS "pages_metas" (
+  id TEXT PRIMARY KEY DEFAULT gen_random_uuid()::text,
+  "pageId" UUID NOT NULL REFERENCES public."pages"(id) ON DELETE CASCADE,
+  "metaKey" TEXT NOT NULL,
+  "metaValue" JSONB NOT NULL DEFAULT '{}'::jsonb,
+  "dataType" TEXT,
+  "isPublic" BOOLEAN NOT NULL DEFAULT FALSE,
+  "isSearchable" BOOLEAN NOT NULL DEFAULT FALSE,
+  "createdAt" TIMESTAMPTZ NOT NULL DEFAULT now(),
+  "updatedAt" TIMESTAMPTZ NOT NULL DEFAULT now(),
+  CONSTRAINT pages_metas_unique_key UNIQUE ("pageId", "metaKey")
+);
+
+-- Indices
+CREATE INDEX IF NOT EXISTS idx_pages_metas_page_id ON "pages_metas"("pageId");
+CREATE INDEX IF NOT EXISTS idx_pages_metas_key ON "pages_metas"("metaKey");
+CREATE INDEX IF NOT EXISTS idx_pages_metas_composite ON "pages_metas"("pageId", "metaKey", "isPublic");
+CREATE INDEX IF NOT EXISTS idx_pages_metas_searchable ON "pages_metas"("isSearchable") WHERE "isSearchable" = true;
+CREATE INDEX IF NOT EXISTS idx_pages_metas_public ON "pages_metas"("isPublic") WHERE "isPublic" = true;
+CREATE INDEX IF NOT EXISTS idx_pages_metas_value_gin ON "pages_metas" USING GIN ("metaValue");
+
+-- Trigger for updatedAt
+DROP TRIGGER IF EXISTS pages_metas_set_updated_at ON "pages_metas";
+CREATE TRIGGER pages_metas_set_updated_at
+BEFORE UPDATE ON "pages_metas"
+FOR EACH ROW EXECUTE FUNCTION public.set_updated_at();
+
+-- ============================================
+-- RLS POLICIES
+-- ============================================
+ALTER TABLE "pages_metas" ENABLE ROW LEVEL SECURITY;
+
+-- Public can read public metadata
+DROP POLICY IF EXISTS "pages_metas_public_select" ON "pages_metas";
+CREATE POLICY "pages_metas_public_select"
+ON "pages_metas" FOR SELECT TO anon
+USING ("isPublic" = TRUE);
+
+-- Authenticated users can manage all metadata
+DROP POLICY IF EXISTS "pages_metas_auth_all" ON "pages_metas";
+CREATE POLICY "pages_metas_auth_all"
+ON "pages_metas" FOR ALL TO authenticated
+USING (true)
+WITH CHECK (true);
+
+-- Comments
+COMMENT ON TABLE "pages_metas" IS 'Flexible key-value metadata storage for pages';
+COMMENT ON COLUMN "pages_metas"."pageId" IS 'Reference to the parent page';
+COMMENT ON COLUMN "pages_metas"."metaKey" IS 'Unique key identifier for the metadata';
+COMMENT ON COLUMN "pages_metas"."metaValue" IS 'JSONB value for flexible data storage';
+COMMENT ON COLUMN "pages_metas"."isPublic" IS 'If true, this metadata can be read by anyone';