@nextsparkjs/theme-default 0.1.0-beta.1

package/lib/langchain/tools/tasks.ts

@@ -0,0 +1,167 @@
+import { z } from 'zod'
+import { ToolDefinition } from '@/plugins/langchain/lib/tools-builder'
+import { TasksService } from '@/themes/default/entities/tasks/tasks.service'
+import { TaskStatus, TaskPriority } from '@/themes/default/entities/tasks/tasks.types'
+
+/**
+ * Tool context for task operations
+ */
+export interface TaskToolContext {
+    userId: string
+    teamId: string
+}
+
+/**
+ * Create task management tools for the AI agent
+ *
+ * @param context - User and team context for RLS
+ * @returns Array of task-related tool definitions
+ *
+ * @example
+ * ```typescript
+ * const tools = createTaskTools({ userId: 'user-123', teamId: 'team-456' })
+ * const agent = await createAgent({
+ *     systemPrompt: loadSystemPrompt('task-assistant'),
+ *     tools,
+ * })
+ * ```
+ */
+export function createTaskTools(context: TaskToolContext): ToolDefinition<any>[] {
+    const { userId, teamId } = context
+
+    return [
+        {
+            name: 'list_tasks',
+            description: 'List all tasks assigned to the user. Optionally filter by status and/or priority.',
+            schema: z.object({
+                status: z.enum(['todo', 'in-progress', 'review', 'done', 'blocked'])
+                    .optional()
+                    .describe('Filter tasks by status'),
+                priority: z.enum(['low', 'medium', 'high', 'urgent'])
+                    .optional()
+                    .describe('Filter tasks by priority level'),
+            }),
+            func: async ({ status, priority }) => {
+                try {
+                    const result = await TasksService.list(userId, {
+                        status: status as TaskStatus,
+                        limit: 50,
+                        teamId,
+                    })
+                    // Filter by priority if specified
+                    let tasks = result.tasks
+                    if (priority) {
+                        tasks = tasks.filter(t => t.priority === priority)
+                    }
+                    return JSON.stringify(tasks.map(t => ({
+                        id: t.id,
+                        title: t.title,
+                        status: t.status,
+                        priority: t.priority,
+                        dueDate: t.dueDate,
+                    })), null, 2)
+                } catch (error) {
+                    return `Error listing tasks: ${error instanceof Error ? error.message : 'Unknown error'}`
+                }
+            },
+        },
+        {
+            name: 'search_tasks',
+            description: 'Search tasks by keyword in title or description.',
+            schema: z.object({
+                query: z.string().describe('Search keyword'),
+            }),
+            func: async ({ query }) => {
+                try {
+                    const result = await TasksService.list(userId, { limit: 100, teamId })
+                    const filtered = result.tasks.filter(t =>
+                        t.title.toLowerCase().includes(query.toLowerCase()) ||
+                        t.description?.toLowerCase().includes(query.toLowerCase())
+                    )
+                    return JSON.stringify(filtered.slice(0, 10).map(t => ({
+                        id: t.id,
+                        title: t.title,
+                        status: t.status,
+                        priority: t.priority,
+                    })), null, 2)
+                } catch (error) {
+                    return `Error searching tasks: ${error instanceof Error ? error.message : 'Unknown error'}`
+                }
+            },
+        },
+        {
+            name: 'get_task_details',
+            description: 'Get full details of a specific task by ID.',
+            schema: z.object({
+                taskId: z.string().describe('The task ID'),
+            }),
+            func: async ({ taskId }) => {
+                try {
+                    const task = await TasksService.getById(taskId, userId)
+                    if (!task) {
+                        return JSON.stringify({ error: 'Task not found' })
+                    }
+                    return JSON.stringify(task, null, 2)
+                } catch (error) {
+                    return `Error getting task: ${error instanceof Error ? error.message : 'Unknown error'}`
+                }
+            },
+        },
+        {
+            name: 'create_task',
+            description: 'Create a new task.',
+            schema: z.object({
+                title: z.string().describe('Task title'),
+                description: z.string().optional().describe('Task description'),
+                priority: z.enum(['low', 'medium', 'high'])
+                    .optional()
+                    .default('medium')
+                    .describe('Task priority'),
+                dueDate: z.string().optional().describe('Due date in ISO format (YYYY-MM-DD)'),
+            }),
+            func: async (data) => {
+                try {
+                    const task = await TasksService.create(userId, {
+                        title: data.title,
+                        description: data.description,
+                        priority: data.priority as TaskPriority,
+                        dueDate: data.dueDate,
+                        status: 'todo' as TaskStatus,
+                        teamId,
+                    })
+                    return JSON.stringify(task, null, 2)
+                } catch (error) {
+                    return `Error creating task: ${error instanceof Error ? error.message : 'Unknown error'}`
+                }
+            },
+        },
+        {
+            name: 'update_task',
+            description: 'Update an existing task.',
+            schema: z.object({
+                taskId: z.string().describe('The task ID to update'),
+                title: z.string().optional().describe('New title'),
+                description: z.string().optional().describe('New description'),
+                status: z.enum(['todo', 'in-progress', 'review', 'done', 'blocked'])
+                    .optional()
+                    .describe('New status'),
+                priority: z.enum(['low', 'medium', 'high'])
+                    .optional()
+                    .describe('New priority'),
+                dueDate: z.string().optional().describe('New due date in ISO format'),
+            }),
+            func: async ({ taskId, ...updates }) => {
+                try {
+                    const task = await TasksService.update(userId, taskId, {
+                        ...updates,
+                        status: updates.status as TaskStatus,
+                        priority: updates.priority as TaskPriority,
+                    })
+                    return JSON.stringify(task, null, 2)
+                } catch (error) {
+                    return `Error updating task: ${error instanceof Error ? error.message : 'Unknown error'}`
+                }
+            },
+        },
+    ]
+}

package/lib/scheduled-actions/billing.ts

@@ -0,0 +1,149 @@
+/**
+ * Billing Scheduled Action Handler
+ *
+ * This handler performs daily checks for subscription renewals and updates
+ * subscription statuses for expired subscriptions.
+ *
+ * Uses core billing services for actual subscription lifecycle management.
+ *
+ * @module contents/themes/default/lib/scheduled-actions/billing
+ */
+
+import { registerScheduledAction, scheduleRecurringAction, scheduleAction } from '@nextsparkjs/core/lib/scheduled-actions'
+import type { ScheduledAction } from '@nextsparkjs/core/lib/scheduled-actions'
+import { queryWithRLS } from '@nextsparkjs/core/lib/db'
+import { expireTrials, handlePastDueGracePeriod } from '@nextsparkjs/core/lib/billing/jobs'
+import { SubscriptionService } from '@nextsparkjs/core/lib/services/subscription.service'
+
+/**
+ * Register the billing check action handler
+ *
+ * This function registers the 'billing:check-renewals' action handler that
+ * processes subscription renewals and updates expired subscriptions.
+ *
+ * Uses core billing services:
+ * - expireTrials(): Expire trials that have passed their end date
+ * - handlePastDueGracePeriod(): Expire past_due subscriptions after grace period
+ * - SubscriptionService.listExpiringSoon(): Get subscriptions expiring soon
+ */
+export function registerBillingAction() {
+  registerScheduledAction(
+    'billing:check-renewals',
+    async (_payload: unknown, _action: ScheduledAction) => {
+      console.log('[billing:check-renewals] Starting subscription lifecycle check...')
+
+      try {
+        // 1. Expire trials that have passed their end date
+        const trialsResult = await expireTrials()
+        console.log(`[billing:check-renewals] Trials expired: ${trialsResult.processed}`)
+        if (trialsResult.errors.length > 0) {
+          console.warn('[billing:check-renewals] Trial expiration errors:', trialsResult.errors)
+        }
+
+        // 2. Handle past_due subscriptions after grace period
+        const pastDueResult = await handlePastDueGracePeriod()
+        console.log(`[billing:check-renewals] Past due expired: ${pastDueResult.processed}`)
+        if (pastDueResult.errors.length > 0) {
+          console.warn('[billing:check-renewals] Past due handling errors:', pastDueResult.errors)
+        }
+
+        // 3. Send reminder webhooks for subscriptions expiring in 7 days
+        const expiringSoon = await SubscriptionService.listExpiringSoon(7)
+        console.log(`[billing:check-renewals] Subscriptions expiring in 7 days: ${expiringSoon.length}`)
+
+        // Schedule webhook for each expiring subscription
+        let webhooksScheduled = 0
+        for (const sub of expiringSoon) {
+          const daysUntilExpiry = Math.ceil(
+            (new Date(sub.currentPeriodEnd).getTime() - Date.now()) / (1000 * 60 * 60 * 24)
+          )
+
+          await scheduleAction('webhook:send', {
+            eventType: 'expiring_soon',
+            entityType: 'subscription',
+            entityId: sub.id,
+            data: {
+              subscriptionId: sub.id,
+              teamId: sub.teamId,
+              planSlug: sub.plan.slug,
+              status: sub.status,
+              periodEnd: sub.currentPeriodEnd,
+              daysUntilExpiry,
+            },
+          }, { teamId: sub.teamId })
+
+          webhooksScheduled++
+        }
+
+        if (webhooksScheduled > 0) {
+          console.log(`[billing:check-renewals] Scheduled ${webhooksScheduled} expiring_soon webhooks`)
+        }
+
+        // Log summary
+        console.log('[billing:check-renewals] Check completed successfully:', {
+          trialsExpired: trialsResult.processed,
+          pastDueExpired: pastDueResult.processed,
+          expiringSoon: expiringSoon.length,
+          webhooksScheduled,
+        })
+      } catch (error) {
+        console.error('[billing:check-renewals] Error during check:', error)
+        throw error
+      }
+    },
+    {
+      description: 'Daily subscription lifecycle check',
+      timeout: 60000, // 60 seconds for billing checks
+    }
+  )
+}
+
+/**
+ * Ensure billing action is scheduled as recurring
+ *
+ * This function should be called at app startup to ensure the billing check
+ * is scheduled to run daily. It checks if a recurring action already exists
+ * to avoid duplicates.
+ *
+ * @example
+ * // Call at app startup
+ * await ensureBillingActionScheduled()
+ */
+export async function ensureBillingActionScheduled() {
+  try {
+    // Check if a pending recurring billing action already exists
+    // Only check for pending status - if no pending exists, create a new one
+    const existingQuery = `
+      SELECT id
+      FROM "scheduled_actions"
+      WHERE "actionType" = 'billing:check-renewals'
+        AND "recurringInterval" = 'daily'
+        AND status = 'pending'
+      LIMIT 1
+    `
+
+    const existing = await queryWithRLS<{ id: string }>(
+      existingQuery,
+      [],
+      null // System operation, no user context
+    )
+
+    if (existing.length > 0) {
+      console.log('[billing:check-renewals] Daily recurring action already scheduled')
+      return
+    }
+
+    // Schedule new recurring daily action
+    console.log('[billing:check-renewals] Scheduling new daily recurring action...')
+    const actionId = await scheduleRecurringAction(
+      'billing:check-renewals',
+      {}, // No payload needed
+      'daily'
+    )
+
+    console.log(`[billing:check-renewals] Daily recurring action scheduled with ID: ${actionId}`)
+  } catch (error) {
+    console.error('[billing:check-renewals] Error ensuring action is scheduled:', error)
+    // Don't throw - this is called at startup and shouldn't crash the app
+  }
+}

package/lib/scheduled-actions/index.ts

@@ -0,0 +1,170 @@
+/**
+ * Theme Scheduled Actions - Handler Registration
+ *
+ * This module registers all scheduled action handlers for the default theme.
+ * The core initializer calls these functions at startup.
+ *
+ * @module contents/themes/default/lib/scheduled-actions
+ *
+ * @example
+ * // Called by core/lib/scheduled-actions/initializer.ts
+ * // Do NOT call directly from app code
+ * registerAllHandlers()
+ * await registerRecurringActions()
+ */
+
+import { registerWebhookAction } from './webhook'
+import { registerBillingAction, ensureBillingActionScheduled } from './billing'
+import { addAction } from '@nextsparkjs/core/lib/plugins/hook-system'
+import { scheduleAction } from '@nextsparkjs/core/lib/scheduled-actions'
+
+/**
+ * Register all scheduled action handlers for this theme
+ *
+ * This function registers all action handlers (webhook, billing, etc.).
+ * Called by the core initializer - the guard is handled there.
+ */
+export function registerAllHandlers(): void {
+  console.log('[theme:scheduled-actions] Registering action handlers...')
+
+  registerWebhookAction()
+  registerBillingAction()
+  registerEntityWebhookHooks()
+
+  console.log('[theme:scheduled-actions] All action handlers registered')
+}
+
+/**
+ * Register entity hooks for webhook triggers
+ *
+ * Listens to entity.tasks.created and entity.tasks.updated hooks
+ * and schedules webhook:send actions.
+ */
+function registerEntityWebhookHooks() {
+  console.log('[theme:scheduled-actions] Registering entity webhook hooks...')
+
+  // AC-15: Task create triggers webhook:send
+  addAction('entity.tasks.created', async (hookData: Record<string, unknown>) => {
+    try {
+      console.log('[webhook:trigger] Task created, scheduling webhook...')
+      const entityData = hookData.data as Record<string, unknown> | undefined
+      await scheduleAction('webhook:send', {
+        eventType: 'created',
+        entityType: 'task',
+        entityId: (hookData.id as string) || (entityData?.id as string),
+        data: entityData,
+        teamId: entityData?.teamId as string | undefined,
+      })
+    } catch (error) {
+      console.error('[webhook:trigger] Error scheduling task create webhook:', error)
+    }
+  })
+
+  // AC-16: Task update triggers webhook:send
+  addAction('entity.tasks.updated', async (hookData: Record<string, unknown>) => {
+    try {
+      console.log('[webhook:trigger] Task updated, scheduling webhook...')
+      const entityData = hookData.data as Record<string, unknown> | undefined
+      await scheduleAction('webhook:send', {
+        eventType: 'updated',
+        entityType: 'task',
+        entityId: hookData.id as string,
+        data: entityData,
+        teamId: entityData?.teamId as string | undefined,
+      })
+    } catch (error) {
+      console.error('[webhook:trigger] Error scheduling task update webhook:', error)
+    }
+  })
+
+  // =========================================================================
+  // SUBSCRIPTION WEBHOOK HOOKS
+  // =========================================================================
+  // These hooks listen to subscription lifecycle events from SubscriptionService
+  // and schedule webhook:send actions to notify external systems.
+
+  // Subscription created
+  addAction('subscription.created', async (hookData: Record<string, unknown>) => {
+    try {
+      console.log('[webhook:trigger] Subscription created, scheduling webhook...')
+      const entityData = hookData.data as Record<string, unknown> | undefined
+      await scheduleAction('webhook:send', {
+        eventType: 'created',
+        entityType: 'subscription',
+        entityId: hookData.id as string,
+        data: entityData,
+        teamId: (hookData.teamId as string) || (entityData?.teamId as string),
+        webhookKey: 'subscriptions',
+      })
+    } catch (error) {
+      console.error('[webhook:trigger] Error scheduling subscription created webhook:', error)
+    }
+  })
+
+  // Subscription updated (status change, plan change)
+  addAction('subscription.updated', async (hookData: Record<string, unknown>) => {
+    try {
+      console.log('[webhook:trigger] Subscription updated, scheduling webhook...')
+      const entityData = hookData.data as Record<string, unknown> | undefined
+      await scheduleAction('webhook:send', {
+        eventType: 'updated',
+        entityType: 'subscription',
+        entityId: hookData.id as string,
+        data: {
+          ...entityData,
+          previousStatus: hookData.previousStatus,
+          newStatus: hookData.newStatus,
+          previousPlan: hookData.previousPlan,
+          newPlan: hookData.newPlan,
+          isUpgrade: hookData.isUpgrade,
+        },
+        teamId: (hookData.teamId as string) || (entityData?.teamId as string),
+        webhookKey: 'subscriptions',
+      })
+    } catch (error) {
+      console.error('[webhook:trigger] Error scheduling subscription updated webhook:', error)
+    }
+  })
+
+  // Subscription cancelled
+  addAction('subscription.cancelled', async (hookData: Record<string, unknown>) => {
+    try {
+      console.log('[webhook:trigger] Subscription cancelled, scheduling webhook...')
+      const entityData = hookData.data as Record<string, unknown> | undefined
+      await scheduleAction('webhook:send', {
+        eventType: 'cancelled',
+        entityType: 'subscription',
+        entityId: hookData.id as string,
+        data: {
+          ...entityData,
+          immediate: hookData.immediate,
+          cancelAtPeriodEnd: hookData.cancelAtPeriodEnd,
+        },
+        teamId: entityData?.teamId as string | undefined,
+        webhookKey: 'subscriptions',
+      })
+    } catch (error) {
+      console.error('[webhook:trigger] Error scheduling subscription cancelled webhook:', error)
+    }
+  })
+
+  console.log('[theme:scheduled-actions] Entity webhook hooks registered')
+}
+
+/**
+ * Register recurring scheduled actions for this theme
+ *
+ * This async function ensures all recurring actions are scheduled.
+ * Called by the core initializer after handlers are registered.
+ */
+export async function registerRecurringActions(): Promise<void> {
+  console.log('[theme:scheduled-actions] Registering recurring actions...')
+
+  await ensureBillingActionScheduled()
+
+  console.log('[theme:scheduled-actions] All recurring actions registered')
+}
+
+// Re-export individual functions for direct use
+export { registerWebhookAction } from './webhook'
+export { registerBillingAction, ensureBillingActionScheduled } from './billing'