@prmichaelsen/task-mcp 0.2.0

package/src/constant/collections.ts

@@ -0,0 +1,128 @@
+/**
+ * Firestore Collection Path Helpers
+ * 
+ * Helper functions to generate consistent Firestore collection paths
+ * for user-scoped data access.
+ */
+
+/**
+ * Get the tasks collection path for a specific user
+ * 
+ * @param userId - The user's ID
+ * @returns Firestore collection path: users/{userId}/tasks
+ * 
+ * @example
+ * const tasksPath = getUserTasks('user123')
+ * // Returns: 'users/user123/tasks'
+ */
+export function getUserTasks(userId: string): string {
+  if (!userId) {
+    throw new Error('userId is required')
+  }
+  return `users/${userId}/tasks`
+}
+
+/**
+ * Get a specific task document path for a user
+ * 
+ * @param userId - The user's ID
+ * @param taskId - The task's ID
+ * @returns Firestore document path: users/{userId}/tasks/{taskId}
+ * 
+ * @example
+ * const taskPath = getUserTask('user123', 'task456')
+ * // Returns: 'users/user123/tasks/task456'
+ */
+export function getUserTask(userId: string, taskId: string): string {
+  if (!userId) {
+    throw new Error('userId is required')
+  }
+  if (!taskId) {
+    throw new Error('taskId is required')
+  }
+  return `${getUserTasks(userId)}/${taskId}`
+}
+
+/**
+ * Get the messages subcollection path for a specific task
+ * 
+ * @param userId - The user's ID
+ * @param taskId - The task's ID
+ * @returns Firestore collection path: users/{userId}/tasks/{taskId}/messages
+ * 
+ * @example
+ * const messagesPath = getUserTaskMessages('user123', 'task456')
+ * // Returns: 'users/user123/tasks/task456/messages'
+ */
+export function getUserTaskMessages(userId: string, taskId: string): string {
+  if (!userId) {
+    throw new Error('userId is required')
+  }
+  if (!taskId) {
+    throw new Error('taskId is required')
+  }
+  return `${getUserTask(userId, taskId)}/messages`
+}
+
+/**
+ * Get a specific task message document path
+ * 
+ * @param userId - The user's ID
+ * @param taskId - The task's ID
+ * @param messageId - The message's ID
+ * @returns Firestore document path: users/{userId}/tasks/{taskId}/messages/{messageId}
+ * 
+ * @example
+ * const messagePath = getUserTaskMessage('user123', 'task456', 'msg789')
+ * // Returns: 'users/user123/tasks/task456/messages/msg789'
+ */
+export function getUserTaskMessage(userId: string, taskId: string, messageId: string): string {
+  if (!userId) {
+    throw new Error('userId is required')
+  }
+  if (!taskId) {
+    throw new Error('taskId is required')
+  }
+  if (!messageId) {
+    throw new Error('messageId is required')
+  }
+  return `${getUserTaskMessages(userId, taskId)}/${messageId}`
+}
+
+/**
+ * Get the task events collection path for a specific user
+ * 
+ * @param userId - The user's ID
+ * @returns Firestore collection path: users/{userId}/task_events
+ * 
+ * @example
+ * const eventsPath = getUserTaskEvents('user123')
+ * // Returns: 'users/user123/task_events'
+ */
+export function getUserTaskEvents(userId: string): string {
+  if (!userId) {
+    throw new Error('userId is required')
+  }
+  return `users/${userId}/task_events`
+}
+
+/**
+ * Get a specific task event document path
+ * 
+ * @param userId - The user's ID
+ * @param eventId - The event's ID
+ * @returns Firestore document path: users/{userId}/task_events/{eventId}
+ * 
+ * @example
+ * const eventPath = getUserTaskEvent('user123', 'event789')
+ * // Returns: 'users/user123/task_events/event789'
+ */
+export function getUserTaskEvent(userId: string, eventId: string): string {
+  if (!userId) {
+    throw new Error('userId is required')
+  }
+  if (!eventId) {
+    throw new Error('eventId is required')
+  }
+  return `${getUserTaskEvents(userId)}/${eventId}`
+}

package/src/dto/index.ts

@@ -0,0 +1,47 @@
+/**
+ * DTO Module Exports
+ * 
+ * Exports all API Response DTOs and transformation functions.
+ * Use these types and functions when building REST API endpoints.
+ */
+
+// Export all DTO types
+export type {
+  // Status enums
+  TaskStatus,
+  MilestoneStatus,
+  TaskItemStatus,
+  MessageRole,
+  
+  // Response DTOs
+  TaskItemApiResponse,
+  MilestoneApiResponse,
+  TaskProgressApiResponse,
+  TaskConfigApiResponse,
+  TaskMetadataApiResponse,
+  TaskApiResponse,
+  TaskListApiResponse,
+  TaskMessageApiResponse,
+  TaskMessageListApiResponse,
+  
+  // Input DTOs
+  CreateTaskDto,
+  UpdateTaskDto,
+  CreateMessageDto,
+  UpdateProgressDto,
+  CreateMilestoneDto,
+  CreateTaskItemDto
+} from './task-api.dto.js'
+
+// Export all transformer functions
+export {
+  toTaskItemApiResponse,
+  toMilestoneApiResponse,
+  toTaskProgressApiResponse,
+  toTaskConfigApiResponse,
+  toTaskMetadataApiResponse,
+  toTaskApiResponse,
+  toTaskMessageApiResponse,
+  toTaskListApiResponse,
+  toTaskMessageListApiResponse
+} from './transformers.js'

package/src/dto/task-api.dto.ts

@@ -0,0 +1,219 @@
+/**
+ * API Response DTOs
+ * 
+ * These DTOs define the structure of REST API responses.
+ * They exclude internal fields and match agentbase.me expectations.
+ * 
+ * Based on design document: agent/design/api-dto-design.md
+ */
+
+// ============================================================================
+// Status Enums
+// ============================================================================
+
+export type TaskStatus = 'not_started' | 'in_progress' | 'paused' | 'completed' | 'failed'
+export type MilestoneStatus = 'not_started' | 'in_progress' | 'completed'
+export type TaskItemStatus = 'not_started' | 'in_progress' | 'completed'
+export type MessageRole = 'user' | 'assistant' | 'system'
+
+// ============================================================================
+// Nested DTOs
+// ============================================================================
+
+/**
+ * Task Item API Response
+ * Represents a granular work item within a milestone
+ */
+export interface TaskItemApiResponse {
+  id: string
+  name: string
+  description: string
+  status: TaskItemStatus
+  estimated_hours?: number
+  completed_at?: string  // ISO 8601 timestamp
+  notes?: string
+}
+
+/**
+ * Milestone API Response
+ * Represents a major phase in task execution
+ */
+export interface MilestoneApiResponse {
+  id: string
+  name: string
+  description: string
+  status: MilestoneStatus
+  progress: number  // 0-100
+  tasks_completed: number
+  tasks_total: number
+  started_at?: string  // ISO 8601 timestamp
+  completed_at?: string  // ISO 8601 timestamp
+}
+
+/**
+ * Task Progress API Response
+ * Tracks overall progress and milestone/task completion
+ */
+export interface TaskProgressApiResponse {
+  current_milestone: string
+  current_task: string
+  overall_percentage: number  // 0-100
+  milestones: MilestoneApiResponse[]
+  tasks: Record<string, TaskItemApiResponse[]>  // Keyed by milestone ID
+}
+
+/**
+ * Task Configuration API Response
+ * Configuration for task execution behavior
+ * Note: Model is configured globally by the tenant platform, not per-task
+ */
+export interface TaskConfigApiResponse {
+  system_prompt: string
+  auto_approve: boolean
+  max_iterations?: number
+}
+
+/**
+ * Task Metadata API Response
+ * Optional metadata for task organization and tracking
+ */
+export interface TaskMetadataApiResponse {
+  conversation_id?: string
+  parent_task_id?: string
+  tags?: string[]
+}
+
+// ============================================================================
+// Main Task DTO
+// ============================================================================
+
+/**
+ * Task API Response
+ * Complete task representation for REST API responses
+ * 
+ * Note: execution field is EXCLUDED from API responses
+ * Internal fields (api_messages, tool_results) are not exposed
+ */
+export interface TaskApiResponse {
+  id: string
+  user_id: string
+  title: string
+  description: string
+  status: TaskStatus
+  created_at: string  // ISO 8601 timestamp
+  updated_at: string  // ISO 8601 timestamp
+  started_at?: string  // ISO 8601 timestamp
+  completed_at?: string  // ISO 8601 timestamp
+  
+  progress: TaskProgressApiResponse
+  config: TaskConfigApiResponse
+  metadata?: TaskMetadataApiResponse
+  
+  // Note: execution field is EXCLUDED from API responses
+  // Internal fields (api_messages, tool_results) are not exposed
+}
+
+// ============================================================================
+// List Response DTO
+// ============================================================================
+
+/**
+ * Task List API Response
+ * Response for listing multiple tasks
+ */
+export interface TaskListApiResponse {
+  tasks: TaskApiResponse[]
+  total: number
+}
+
+// ============================================================================
+// Message DTOs
+// ============================================================================
+
+/**
+ * Task Message API Response
+ * Represents a message in the task conversation thread
+ */
+export interface TaskMessageApiResponse {
+  id: string
+  task_id: string
+  role: MessageRole
+  content: string
+  timestamp: string  // ISO 8601 timestamp
+  metadata?: any
+}
+
+/**
+ * Task Message List API Response
+ * Response for listing task messages
+ */
+export interface TaskMessageListApiResponse {
+  messages: TaskMessageApiResponse[]
+  total: number
+}
+
+// ============================================================================
+// Input DTOs (for write operations)
+// ============================================================================
+
+/**
+ * Create Task Input DTO
+ * Request body for creating a new task
+ */
+export interface CreateTaskDto {
+  title: string
+  description: string
+  config?: Partial<TaskConfigApiResponse>
+  metadata?: TaskMetadataApiResponse
+}
+
+/**
+ * Update Task Input DTO
+ * Request body for updating a task
+ */
+export interface UpdateTaskDto {
+  title?: string
+  description?: string
+  status?: TaskStatus
+  config?: Partial<TaskConfigApiResponse>
+  metadata?: TaskMetadataApiResponse
+}
+
+/**
+ * Create Message Input DTO
+ * Request body for adding a message to a task
+ */
+export interface CreateMessageDto {
+  role: MessageRole
+  content: string
+  metadata?: any
+}
+
+/**
+ * Update Progress Input DTO
+ * Request body for updating task progress
+ */
+export interface UpdateProgressDto {
+  percentage: number  // 0-100
+}
+
+/**
+ * Create Milestone Input DTO
+ * Request body for creating a milestone
+ */
+export interface CreateMilestoneDto {
+  milestone_id: string
+  name: string
+  description: string
+}
+
+/**
+ * Create Task Item Input DTO
+ * Request body for creating a task item
+ */
+export interface CreateTaskItemDto {
+  task_item_id: string
+  name: string
+  description: string
+  estimated_hours?: number
+}