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

package/dist/templates/contents/themes/starter/entities/tasks/tasks.service.ts

@@ -0,0 +1,390 @@
+/**
+ * Tasks Service - Starter Theme
+ *
+ * Provides data access methods for tasks.
+ * Tasks is a private entity with shared: false - users only see their own tasks.
+ *
+ * All methods require authentication (use RLS with userId filter).
+ *
+ * @module TasksService
+ */
+
+import { queryOneWithRLS, queryWithRLS } from '@nextsparkjs/core/lib/db'
+import type {
+  Task,
+  TaskListOptions,
+  TaskListResult,
+  TaskStatus,
+} from './tasks.types'
+
+// Database row type for task
+interface DbTask {
+  id: string
+  title: string
+  description: string | null
+  status: TaskStatus
+  priority: string
+  tags: string[] | null
+  dueDate: string | null
+  estimatedHours: number | null
+  completed: boolean | null
+  createdAt: string
+  updatedAt: string
+}
+
+export class TasksService {
+  // ============================================
+  // AUTHENTICATED METHODS (with RLS)
+  // ============================================
+
+  /**
+   * Get a task by ID
+   *
+   * Respects RLS policies. Since tasks has shared: false,
+   * only the task owner can access it.
+   *
+   * @param id - Task ID
+   * @param userId - Current user ID for RLS
+   * @returns Task data or null if not found/not authorized
+   *
+   * @example
+   * const task = await TasksService.getById('task-uuid', currentUserId)
+   */
+  static async getById(id: string, userId: string): Promise<Task | null> {
+    try {
+      if (!id || id.trim() === '') {
+        throw new Error('Task ID is required')
+      }
+
+      if (!userId || userId.trim() === '') {
+        throw new Error('User ID is required for authentication')
+      }
+
+      const task = await queryOneWithRLS<DbTask>(
+        `
+        SELECT
+          id,
+          title,
+          description,
+          status,
+          priority,
+          tags,
+          "dueDate",
+          "estimatedHours",
+          completed,
+          "createdAt",
+          "updatedAt"
+        FROM tasks
+        WHERE id = $1
+        `,
+        [id],
+        userId
+      )
+
+      if (!task) {
+        return null
+      }
+
+      return {
+        id: task.id,
+        title: task.title,
+        description: task.description ?? undefined,
+        status: task.status,
+        priority: task.priority as Task['priority'],
+        tags: task.tags ?? undefined,
+        dueDate: task.dueDate ?? undefined,
+        estimatedHours: task.estimatedHours ?? undefined,
+        completed: task.completed ?? undefined,
+        createdAt: task.createdAt,
+        updatedAt: task.updatedAt,
+      }
+    } catch (error) {
+      console.error('TasksService.getById error:', error)
+      throw new Error(
+        error instanceof Error ? error.message : 'Failed to fetch task'
+      )
+    }
+  }
+
+  /**
+   * List tasks with pagination and filtering
+   *
+   * @param userId - Current user ID for RLS
+   * @param options - List options (limit, offset, status, priority, orderBy, orderDir)
+   * @returns Object with tasks array and total count
+   *
+   * @example
+   * const { tasks, total } = await TasksService.list(currentUserId, {
+   *   status: 'todo',
+   *   limit: 10
+   * })
+   */
+  static async list(
+    userId: string,
+    options: TaskListOptions = {}
+  ): Promise<TaskListResult> {
+    try {
+      if (!userId || userId.trim() === '') {
+        throw new Error('User ID is required for authentication')
+      }
+
+      const {
+        limit = 10,
+        offset = 0,
+        status,
+        priority,
+        orderBy = 'createdAt',
+        orderDir = 'desc',
+      } = options
+
+      // Build WHERE clause
+      const conditions: string[] = []
+      const params: unknown[] = []
+      let paramIndex = 1
+
+      if (status) {
+        conditions.push(`status = $${paramIndex}`)
+        params.push(status)
+        paramIndex++
+      }
+
+      if (priority) {
+        conditions.push(`priority = $${paramIndex}`)
+        params.push(priority)
+        paramIndex++
+      }
+
+      const whereClause =
+        conditions.length > 0 ? `WHERE ${conditions.join(' AND ')}` : ''
+
+      // Validate orderBy to prevent SQL injection
+      const validOrderBy = [
+        'title',
+        'status',
+        'priority',
+        'dueDate',
+        'createdAt',
+      ].includes(orderBy)
+        ? orderBy
+        : 'createdAt'
+      const validOrderDir = orderDir === 'asc' ? 'ASC' : 'DESC'
+
+      // Map field names to database columns
+      const orderColumnMap: Record<string, string> = {
+        title: 'title',
+        status: 'status',
+        priority: 'priority',
+        dueDate: '"dueDate"',
+        createdAt: '"createdAt"',
+      }
+      const orderColumn = orderColumnMap[validOrderBy] || '"createdAt"'
+
+      // Get total count
+      const countResult = await queryWithRLS<{ count: string }>(
+        `SELECT COUNT(*)::text as count FROM tasks ${whereClause}`,
+        params,
+        userId
+      )
+      const total = parseInt(countResult[0]?.count || '0', 10)
+
+      // Get tasks
+      params.push(limit, offset)
+      const tasks = await queryWithRLS<DbTask>(
+        `
+        SELECT
+          id,
+          title,
+          description,
+          status,
+          priority,
+          tags,
+          "dueDate",
+          "estimatedHours",
+          completed,
+          "createdAt",
+          "updatedAt"
+        FROM tasks
+        ${whereClause}
+        ORDER BY ${orderColumn} ${validOrderDir}
+        LIMIT $${paramIndex} OFFSET $${paramIndex + 1}
+        `,
+        params,
+        userId
+      )
+
+      return {
+        tasks: tasks.map((task) => ({
+          id: task.id,
+          title: task.title,
+          description: task.description ?? undefined,
+          status: task.status,
+          priority: task.priority as Task['priority'],
+          tags: task.tags ?? undefined,
+          dueDate: task.dueDate ?? undefined,
+          estimatedHours: task.estimatedHours ?? undefined,
+          completed: task.completed ?? undefined,
+          createdAt: task.createdAt,
+          updatedAt: task.updatedAt,
+        })),
+        total,
+      }
+    } catch (error) {
+      console.error('TasksService.list error:', error)
+      throw new Error(
+        error instanceof Error ? error.message : 'Failed to list tasks'
+      )
+    }
+  }
+
+  /**
+   * Get tasks by status
+   *
+   * Convenience method to fetch all tasks with a specific status.
+   *
+   * @param userId - Current user ID for RLS
+   * @param status - Task status to filter by
+   * @returns Array of tasks with the given status
+   *
+   * @example
+   * const todoTasks = await TasksService.getByStatus(currentUserId, 'todo')
+   */
+  static async getByStatus(userId: string, status: TaskStatus): Promise<Task[]> {
+    try {
+      const { tasks } = await this.list(userId, {
+        status,
+        limit: 1000, // Large limit to get all matching tasks
+        orderBy: 'priority',
+        orderDir: 'desc',
+      })
+
+      return tasks
+    } catch (error) {
+      console.error('TasksService.getByStatus error:', error)
+      throw new Error(
+        error instanceof Error
+          ? error.message
+          : 'Failed to fetch tasks by status'
+      )
+    }
+  }
+
+  /**
+   * Get overdue tasks
+   *
+   * Fetches tasks that are past their due date and not completed.
+   *
+   * @param userId - Current user ID for RLS
+   * @returns Array of overdue tasks
+   *
+   * @example
+   * const overdueTasks = await TasksService.getOverdue(currentUserId)
+   */
+  static async getOverdue(userId: string): Promise<Task[]> {
+    try {
+      if (!userId || userId.trim() === '') {
+        throw new Error('User ID is required for authentication')
+      }
+
+      const tasks = await queryWithRLS<DbTask>(
+        `
+        SELECT
+          id,
+          title,
+          description,
+          status,
+          priority,
+          tags,
+          "dueDate",
+          "estimatedHours",
+          completed,
+          "createdAt",
+          "updatedAt"
+        FROM tasks
+        WHERE "dueDate" < CURRENT_DATE
+          AND status != 'done'
+          AND (completed IS NULL OR completed = false)
+        ORDER BY "dueDate" ASC
+        `,
+        [],
+        userId
+      )
+
+      return tasks.map((task) => ({
+        id: task.id,
+        title: task.title,
+        description: task.description ?? undefined,
+        status: task.status,
+        priority: task.priority as Task['priority'],
+        tags: task.tags ?? undefined,
+        dueDate: task.dueDate ?? undefined,
+        estimatedHours: task.estimatedHours ?? undefined,
+        completed: task.completed ?? undefined,
+        createdAt: task.createdAt,
+        updatedAt: task.updatedAt,
+      }))
+    } catch (error) {
+      console.error('TasksService.getOverdue error:', error)
+      throw new Error(
+        error instanceof Error ? error.message : 'Failed to fetch overdue tasks'
+      )
+    }
+  }
+
+  /**
+   * Get tasks due today
+   *
+   * @param userId - Current user ID for RLS
+   * @returns Array of tasks due today
+   */
+  static async getDueToday(userId: string): Promise<Task[]> {
+    try {
+      if (!userId || userId.trim() === '') {
+        throw new Error('User ID is required for authentication')
+      }
+
+      const tasks = await queryWithRLS<DbTask>(
+        `
+        SELECT
+          id,
+          title,
+          description,
+          status,
+          priority,
+          tags,
+          "dueDate",
+          "estimatedHours",
+          completed,
+          "createdAt",
+          "updatedAt"
+        FROM tasks
+        WHERE "dueDate" = CURRENT_DATE
+          AND status != 'done'
+        ORDER BY priority DESC, "createdAt" ASC
+        `,
+        [],
+        userId
+      )
+
+      return tasks.map((task) => ({
+        id: task.id,
+        title: task.title,
+        description: task.description ?? undefined,
+        status: task.status,
+        priority: task.priority as Task['priority'],
+        tags: task.tags ?? undefined,
+        dueDate: task.dueDate ?? undefined,
+        estimatedHours: task.estimatedHours ?? undefined,
+        completed: task.completed ?? undefined,
+        createdAt: task.createdAt,
+        updatedAt: task.updatedAt,
+      }))
+    } catch (error) {
+      console.error('TasksService.getDueToday error:', error)
+      throw new Error(
+        error instanceof Error
+          ? error.message
+          : 'Failed to fetch tasks due today'
+      )
+    }
+  }
+}

package/dist/templates/contents/themes/starter/entities/tasks/tasks.types.ts

@@ -0,0 +1,82 @@
+/**
+ * Tasks Service Types - Starter Theme
+ *
+ * Type definitions for the TasksService.
+ * Tasks is a private entity with shared: false - users only see their own tasks.
+ *
+ * @module TasksTypes
+ */
+
+/**
+ * Task status values
+ */
+export type TaskStatus = 'todo' | 'in-progress' | 'review' | 'done' | 'blocked'
+
+/**
+ * Task priority values
+ */
+export type TaskPriority = 'low' | 'medium' | 'high' | 'urgent'
+
+/**
+ * Task entity
+ */
+export interface Task {
+  id: string
+  title: string
+  description?: string
+  status: TaskStatus
+  priority: TaskPriority
+  tags?: string[]
+  dueDate?: string
+  estimatedHours?: number
+  completed?: boolean
+  createdAt?: string
+  updatedAt?: string
+}
+
+/**
+ * Options for listing tasks
+ */
+export interface TaskListOptions {
+  limit?: number
+  offset?: number
+  status?: TaskStatus
+  priority?: TaskPriority
+  orderBy?: 'title' | 'status' | 'priority' | 'dueDate' | 'createdAt'
+  orderDir?: 'asc' | 'desc'
+}
+
+/**
+ * Result of listing tasks with pagination
+ */
+export interface TaskListResult {
+  tasks: Task[]
+  total: number
+}
+
+/**
+ * Create task input
+ */
+export interface CreateTaskInput {
+  title: string
+  description?: string
+  status?: TaskStatus
+  priority?: TaskPriority
+  tags?: string[]
+  dueDate?: string
+  estimatedHours?: number
+}
+
+/**
+ * Update task input
+ */
+export interface UpdateTaskInput {
+  title?: string
+  description?: string
+  status?: TaskStatus
+  priority?: TaskPriority
+  tags?: string[]
+  dueDate?: string
+  estimatedHours?: number
+  completed?: boolean
+}

package/dist/templates/contents/themes/starter/lib/.gitkeep

@@ -0,0 +1 @@
+# Add your theme-specific utilities and helpers here

package/dist/templates/contents/themes/starter/lib/hooks/index.ts

@@ -0,0 +1,2 @@
+export { useTaskStats } from './useTaskStats'
+export { useAnalyticsData } from './useAnalyticsData'

package/dist/templates/contents/themes/starter/lib/hooks/useAnalyticsData.ts

@@ -0,0 +1,41 @@
+'use client'
+
+import { useQuery } from '@tanstack/react-query'
+import { useTeamContext } from '@nextsparkjs/core/contexts/TeamContext'
+
+interface WeeklyProgress {
+  day: string
+  completed: number
+  created: number
+}
+
+interface ActivityItem {
+  id: string
+  action: 'created' | 'completed' | 'updated'
+  task: string
+  time: string
+}
+
+interface AnalyticsData {
+  totalTasks: number
+  completedToday: number
+  overdue: number
+  avgCompletionTime: number
+  weeklyProgress: WeeklyProgress[]
+  recentActivity: ActivityItem[]
+}
+
+export function useAnalyticsData() {
+  const { currentTeam } = useTeamContext()
+
+  return useQuery({
+    queryKey: ['analytics', currentTeam?.id],
+    queryFn: async (): Promise<AnalyticsData> => {
+      const res = await fetch(`/api/v1/analytics?teamId=${currentTeam?.id}`)
+      if (!res.ok) throw new Error('Failed to fetch analytics')
+      return res.json()
+    },
+    enabled: !!currentTeam?.id,
+    staleTime: 1000 * 60 * 5, // 5 minutes
+  })
+}

package/dist/templates/contents/themes/starter/lib/hooks/useTaskStats.ts

@@ -0,0 +1,57 @@
+'use client'
+
+import { useMemo } from 'react'
+import { useQuery } from '@tanstack/react-query'
+import { useTeamContext } from '@nextsparkjs/core/contexts/TeamContext'
+import { calculateTaskStats, type TaskStats } from '../utils'
+
+interface Task {
+  id: string
+  status: string
+  dueDate: string | null
+}
+
+interface UseTaskStatsReturn {
+  stats: TaskStats | null
+  isLoading: boolean
+  error: Error | null
+  refetch: () => void
+}
+
+/**
+ * Hook to fetch and calculate task statistics for the current team
+ */
+export function useTaskStats(): UseTaskStatsReturn {
+  const { currentTeam } = useTeamContext()
+
+  const {
+    data: tasks,
+    isLoading,
+    error,
+    refetch,
+  } = useQuery({
+    queryKey: ['tasks', currentTeam?.id, 'stats'],
+    queryFn: async (): Promise<Task[]> => {
+      const response = await fetch(`/api/v1/tasks?teamId=${currentTeam?.id}&limit=1000`)
+      if (!response.ok) {
+        throw new Error('Failed to fetch tasks')
+      }
+      const data = await response.json()
+      return data.items ?? data
+    },
+    enabled: !!currentTeam?.id,
+    staleTime: 1000 * 60 * 2, // 2 minutes
+  })
+
+  const stats = useMemo(() => {
+    if (!tasks) return null
+    return calculateTaskStats(tasks)
+  }, [tasks])
+
+  return {
+    stats,
+    isLoading,
+    error: error as Error | null,
+    refetch,
+  }
+}

package/dist/templates/contents/themes/starter/lib/index.ts

@@ -0,0 +1,8 @@
+// Utilities
+export * from './utils'
+
+// Hooks
+export * from './hooks'
+
+// Selectors
+export * from './selectors'

package/dist/templates/contents/themes/starter/lib/selectors.ts

@@ -0,0 +1,94 @@
+/**
+ * Theme Block Selectors
+ *
+ * This file defines selectors for block components in the theme.
+ * It's placed in lib/ instead of tests/ so TypeScript can resolve imports.
+ *
+ * Used by:
+ * - Block components (for data-cy attributes)
+ * - Cypress tests (via tests/cypress/src/selectors.ts)
+ */
+
+import { createSelectorHelpers, CORE_SELECTORS } from '@nextsparkjs/core/lib/test'
+
+// =============================================================================
+// BLOCK SELECTORS
+// =============================================================================
+
+/**
+ * Block-specific selectors for the starter theme.
+ * Each block has at minimum a 'container' selector.
+ * Dynamic selectors use {index} placeholder.
+ */
+export const BLOCK_SELECTORS = {
+  hero: {
+    container: 'block-hero',
+    cta: 'hero-cta',
+  },
+} as const
+
+// =============================================================================
+// THEME SELECTORS (CORE + BLOCKS)
+// =============================================================================
+
+/**
+ * Complete theme selectors merging core and blocks.
+ */
+export const THEME_SELECTORS = {
+  ...CORE_SELECTORS,
+  blocks: BLOCK_SELECTORS,
+} as const
+
+// =============================================================================
+// EXPORTS
+// =============================================================================
+
+/**
+ * Create helpers bound to theme selectors
+ */
+const helpers = createSelectorHelpers(THEME_SELECTORS)
+
+/**
+ * Full selectors object (core + theme extensions)
+ */
+export const SELECTORS = helpers.SELECTORS
+
+/**
+ * Get a selector value by path
+ *
+ * @example
+ * sel('auth.login.form') // 'login-form'
+ * sel('blocks.hero.container') // 'block-hero'
+ */
+export const sel = helpers.sel
+
+/**
+ * Alias for sel
+ */
+export const s = helpers.s
+
+/**
+ * Get selector only in dev/test environments
+ */
+export const selDev = helpers.selDev
+
+/**
+ * Get Cypress selector string [data-cy="..."]
+ *
+ * @example
+ * cySelector('blocks.hero.container') // '[data-cy="block-hero"]'
+ */
+export const cySelector = helpers.cySelector
+
+/**
+ * Create entity-specific selector helpers
+ */
+export const entitySelectors = helpers.entitySelectors
+
+/**
+ * Type exports
+ */
+export type ThemeSelectorsType = typeof THEME_SELECTORS
+export type BlockSelectorsType = typeof BLOCK_SELECTORS
+export type { Replacements } from '@nextsparkjs/core/lib/test'
+export { CORE_SELECTORS }