mcp-sunsama 0.2.0

package/src/utils/client-resolver.ts

@@ -0,0 +1,23 @@
+import { SunsamaClient } from "sunsama-api";
+import { getGlobalSunsamaClient } from "../auth/stdio.js";
+import type { SessionData } from "../auth/types.js";
+import { getTransportConfig } from "../config/transport.js";
+
+/**
+ * Gets the appropriate SunsamaClient instance based on transport type
+ * @param session - Session data for HTTP transport (null for stdio)
+ * @returns Authenticated SunsamaClient instance
+ * @throws {Error} If session is not available for HTTP transport or global client not initialized for stdio
+ */
+export function getSunsamaClient(session: SessionData | null): SunsamaClient {
+  const transportConfig = getTransportConfig();
+  
+  if (transportConfig.transportType === "httpStream") {
+    if (!session?.sunsamaClient) {
+      throw new Error("Session not available. Authentication may have failed.");
+    }
+    return session.sunsamaClient;
+  }
+  
+  return getGlobalSunsamaClient();
+}

package/src/utils/task-filters.ts

@@ -0,0 +1,49 @@
+import type { Task } from "sunsama-api";
+import type { CompletionFilter } from "../schemas.js";
+
+/**
+ * Filters an array of tasks based on completion status.
+ *
+ * @param tasks - Array of Task objects to filter
+ * @param filter - Completion filter mode:
+ *   - "all": Return all tasks (no filtering)
+ *   - "incomplete": Return only tasks where completed is false
+ *   - "completed": Return only tasks where completed is true
+ * @returns Filtered array of tasks
+ * @throws {Error} If an invalid filter value is provided
+ *
+ * @example
+ * ```typescript
+ * const allTasks = await sunsamaClient.getTasksByDay("2024-01-15", "UTC");
+ *
+ * // Get only incomplete tasks for focused work
+ * const incompleteTasks = filterTasksByCompletion(allTasks, "incomplete");
+ *
+ * // Get only completed tasks for review
+ * const completedTasks = filterTasksByCompletion(allTasks, "completed");
+ *
+ * // Get all tasks (no filtering)
+ * const allTasksFiltered = filterTasksByCompletion(allTasks, "all");
+ * ```
+ */
+export function filterTasksByCompletion(tasks: Task[], filter: CompletionFilter): Task[] {
+  // Validate filter parameter
+  if (!["all", "incomplete", "completed"].includes(filter)) {
+    throw new Error(`Invalid completion filter: ${filter}. Must be 'all', 'incomplete', or 'completed'.`);
+  }
+
+  switch (filter) {
+    case "all":
+      return tasks; // No filtering - return all tasks
+
+    case "incomplete":
+      return tasks.filter(task => !task.completed);
+
+    case "completed":
+      return tasks.filter(task => task.completed);
+
+    default:
+      // TypeScript exhaustiveness check - should never reach here
+      throw new Error(`Unhandled completion filter: ${filter satisfies never}`);
+  }
+}

package/src/utils/task-trimmer.ts

@@ -0,0 +1,81 @@
+import type { Task } from "sunsama-api";
+
+/**
+ * Trimmed task type containing only essential properties for API responses.
+ * Reduces response size by 60-80% while preserving core task information.
+ * 
+ * Extends core Task properties with simplified versions of complex fields:
+ * - integration: Service name only (instead of full nested object)
+ * - subtasks: Array of titles only (instead of full subtask objects)
+ */
+export type TrimmedTask = Pick<Task, 
+  | '_id' 
+  | 'text' 
+  | 'completed' 
+  | 'assigneeId' 
+  | 'createdAt' 
+  | 'lastModified'
+  | 'objectiveId'
+  | 'completeDate' 
+  | 'timeEstimate' 
+  | 'dueDate' 
+  | 'notes' 
+  | 'streamIds'
+> & {
+  /** Integration service name (e.g., 'website', 'googleCalendar') or null */
+  integration: string | null;
+  /** Array of subtask titles only (simplified from full subtask objects) */
+  subtasks: string[];
+};
+
+/**
+ * Trims a task object to include only essential properties for API responses.
+ * 
+ * Included properties:
+ * - Core identifiers: _id, assigneeId, objectiveId
+ * - Content: text, notes 
+ * - Status: completed, completeDate
+ * - Timestamps: createdAt, lastModified
+ * - Planning: timeEstimate, dueDate, streamIds
+ * - Simplified integration: service name only (not full nested object)
+ * - Simplified subtasks: titles only (not full objects with metadata)
+ * 
+ * Excluded properties (for size reduction):
+ * - Internal metadata: notesChecksum, editorVersion, collabSnapshot, __typename
+ * - Complex nested objects: full integration objects, sequence, ritual, eventInfo, runDate, timeHorizon
+ * - Large arrays: comments, orderings, backlogOrderings, actualTime, scheduledTime, full subtask objects
+ * - UI state: subtasksCollapsed, seededEventIds, followers
+ * - Redundant fields: completedBy, completeOn, recommendedTimeEstimate, recommendedStreamId, notesMarkdown
+ * - Metadata: groupId, taskType, private, deleted, createdBy, archivedAt, duration
+ * 
+ * @param task - Full task object from Sunsama API
+ * @returns Trimmed task object with only essential properties
+ */
+export function trimTaskForResponse(task: Task): TrimmedTask {
+  return {
+    _id: task._id,
+    assigneeId: task.assigneeId,
+    completeDate: task.completeDate,
+    completed: task.completed,
+    createdAt: task.createdAt,
+    dueDate: task.dueDate,
+    integration: task.integration?.service || null,
+    lastModified: task.lastModified,
+    notes: task.notes,
+    objectiveId: task.objectiveId,
+    streamIds: task.streamIds,
+    subtasks: task.subtasks.map((st) => st.title),
+    text: task.text,
+    timeEstimate: task.timeEstimate
+  };
+}
+
+/**
+ * Trims an array of task objects to include only essential properties.
+ * 
+ * @param tasks - Array of full task objects from Sunsama API
+ * @returns Array of trimmed task objects
+ */
+export function trimTasksForResponse(tasks: Task[]): TrimmedTask[] {
+  return tasks.map(trimTaskForResponse);
+}

package/src/utils/to-tsv.ts

@@ -0,0 +1,73 @@
+import Papa from 'papaparse';
+
+/**
+ * Recursively converts nested objects and arrays to JSON strings
+ * @param obj - The object to process
+ * @returns The object with nested structures converted to strings
+ */
+function stringifyNestedObjects(obj: any): any {
+  if (obj === null || obj === undefined) {
+    return obj;
+  }
+
+  if (Array.isArray(obj)) {
+    return JSON.stringify(obj);
+  }
+
+  if (typeof obj === 'object') {
+    const result: any = {};
+    for (const [key, value] of Object.entries(obj)) {
+      if (value === null || value === undefined) {
+        result[key] = value;
+      } else if (typeof value === 'object') {
+        // Convert nested objects and arrays to JSON strings
+        result[key] = JSON.stringify(value);
+      } else {
+        result[key] = value;
+      }
+    }
+    return result;
+  }
+
+  return obj;
+}
+
+/**
+ * Converts data to TSV (Tab-Separated Values) format
+ * @param data - The data to convert (object or array of objects)
+ * @param fields - Optional array of field names to include in specific order
+ * @returns TSV string representation of the data
+ */
+export function toTsv(data: any, fields?: string[]): string {
+  // Handle null/undefined data
+  if (data === null || data === undefined) {
+    return '';
+  }
+
+  // If data is not an array, wrap it in an array
+  const arrayData = Array.isArray(data) ? data : [data];
+
+  // Handle empty arrays
+  if (arrayData.length === 0) {
+    return '';
+  }
+
+  // Process each item to stringify nested objects
+  const processedData = arrayData.map(item => stringifyNestedObjects(item));
+
+  // Configure papaparse options
+  const parseOptions: any = {
+    delimiter: '\t',     // Use tab as delimiter
+    header: true,        // Include column headers
+    skipEmptyLines: true, // Skip empty rows
+    quotes: true         // Quote fields to handle JSON strings properly
+  };
+
+  // If specific fields are requested, use them to control column order
+  if (fields && fields.length > 0) {
+    parseOptions.columns = fields;
+  }
+
+  // Convert to TSV using papaparse
+  return Papa.unparse(processedData, parseOptions);
+}

package/tsconfig.json

@@ -0,0 +1,36 @@
+{
+  "compilerOptions": {
+    // Environment setup & latest features
+    "lib": ["ESNext"],
+    "target": "ESNext",
+    "module": "ESNext",
+    "moduleDetection": "force",
+    "jsx": "react-jsx",
+    "allowJs": true,
+
+    // Bundler mode
+    "moduleResolution": "bundler",
+    "verbatimModuleSyntax": true,
+    "noEmit": false,
+
+    // Build output configuration
+    "outDir": "dist",
+    "declaration": true,
+    "declarationMap": true,
+
+    // Best practices
+    "strict": true,
+    "skipLibCheck": true,
+    "noFallthroughCasesInSwitch": true,
+    "noUncheckedIndexedAccess": true,
+
+    // Some stricter flags (disabled by default)
+    "noUnusedLocals": false,
+    "noUnusedParameters": false,
+    "noPropertyAccessFromIndexSignature": false
+  },
+  "exclude": [
+    "dist",
+    "node_modules"
+  ]
+}