motionmcp 2.1.1 → 2.2.1

package/dist/utils/frequencyTransform.js

@@ -0,0 +1,326 @@
+"use strict";
+/**
+ * Utility functions for transforming frequency objects to Motion API string format
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.transformFrequencyToApiString = transformFrequencyToApiString;
+exports.validateFrequencyObject = validateFrequencyObject;
+exports.isValidFrequencyObject = isValidFrequencyObject;
+/**
+ * Maps day numbers (0-6) to Motion API day abbreviations
+ * 0 = Sunday, 1 = Monday, ..., 6 = Saturday
+ */
+const DAY_ABBREVIATIONS = {
+    0: 'SU', // Sunday
+    1: 'MO', // Monday
+    2: 'TU', // Tuesday
+    3: 'WE', // Wednesday
+    4: 'TH', // Thursday
+    5: 'FR', // Friday
+    6: 'SA' // Saturday
+};
+/**
+ * Transforms a frequency object into the Motion API expected string format
+ *
+ * Based on Motion API documentation: https://docs.usemotion.com/cookbooks/frequency/
+ *
+ * Supports all Motion API frequency patterns including:
+ * - Daily: daily_every_day, daily_every_week_day, daily_specific_days_[...]
+ * - Weekly: weekly_any_day, weekly_any_week_day, weekly_specific_days_[...]
+ * - Biweekly: biweekly_first_week_*, biweekly_second_week_*
+ * - Monthly: monthly_1-31, monthly_first_MO, monthly_last_TU, monthly_*_week, etc.
+ * - Quarterly: quarterly_first_day, quarterly_last_FR, quarterly_any_day_first_week, etc.
+ * - Custom: Direct API pattern passthrough
+ *
+ * @param frequency - The frequency object to transform
+ * @returns The Motion API compatible frequency string
+ */
+function transformFrequencyToApiString(frequency) {
+    const { type, daysOfWeek, dayOfMonth, weekOfMonth, monthOfQuarter, interval, customPattern } = frequency;
+    // Custom pattern passthrough
+    if (type === 'custom') {
+        if (!customPattern) {
+            throw new Error('customPattern is required when type is "custom"');
+        }
+        return customPattern;
+    }
+    // Legacy interval mapping: weekly + interval:2 → biweekly
+    if (type === 'weekly' && interval === 2) {
+        return transformBiweeklyPattern(daysOfWeek, 'first'); // Default to first week
+    }
+    switch (type) {
+        case 'daily':
+            return transformDailyPattern(daysOfWeek);
+        case 'weekly':
+            return transformWeeklyPattern(daysOfWeek);
+        case 'biweekly':
+            // Use weekOfMonth to determine which week (first or second)
+            const biweeklyWeek = (weekOfMonth === 'second') ? 'second' : 'first';
+            return transformBiweeklyPattern(daysOfWeek, biweeklyWeek);
+        case 'monthly':
+            return transformMonthlyPattern(daysOfWeek, dayOfMonth, weekOfMonth);
+        case 'quarterly':
+            return transformQuarterlyPattern(daysOfWeek, weekOfMonth, monthOfQuarter);
+        case 'yearly':
+            // Yearly patterns are basic in the API docs
+            return 'yearly';
+        default:
+            throw new Error(`Unsupported frequency type: ${type}`);
+    }
+}
+/**
+ * Transform daily frequency patterns
+ */
+function transformDailyPattern(daysOfWeek) {
+    if (!daysOfWeek || daysOfWeek.length === 0) {
+        return 'daily_every_day';
+    }
+    // Check if it's weekdays only (Mon-Fri)
+    const isWeekdaysOnly = isWeekdaysPattern(daysOfWeek);
+    if (isWeekdaysOnly) {
+        return 'daily_every_week_day';
+    }
+    // Specific days
+    const dayAbbrevs = formatDayAbbreviations(daysOfWeek);
+    return `daily_specific_days_[${dayAbbrevs}]`;
+}
+/**
+ * Transform weekly frequency patterns
+ */
+function transformWeeklyPattern(daysOfWeek) {
+    if (!daysOfWeek || daysOfWeek.length === 0) {
+        return 'weekly_any_day';
+    }
+    // Check if it's weekdays only (Mon-Fri)
+    const isWeekdaysOnly = isWeekdaysPattern(daysOfWeek);
+    if (isWeekdaysOnly) {
+        return 'weekly_any_week_day';
+    }
+    // Specific days
+    const dayAbbrevs = formatDayAbbreviations(daysOfWeek);
+    return `weekly_specific_days_[${dayAbbrevs}]`;
+}
+/**
+ * Transform biweekly frequency patterns
+ */
+function transformBiweeklyPattern(daysOfWeek, week = 'first') {
+    if (!daysOfWeek || daysOfWeek.length === 0) {
+        return `biweekly_${week}_week_any_day`;
+    }
+    // Check if it's weekdays only (Mon-Fri)
+    const isWeekdaysOnly = isWeekdaysPattern(daysOfWeek);
+    if (isWeekdaysOnly) {
+        return `biweekly_${week}_week_any_week_day`;
+    }
+    // Specific days
+    const dayAbbrevs = formatDayAbbreviations(daysOfWeek);
+    return `biweekly_${week}_week_specific_days_[${dayAbbrevs}]`;
+}
+/**
+ * Transform monthly frequency patterns
+ */
+function transformMonthlyPattern(daysOfWeek, dayOfMonth, weekOfMonth) {
+    // Handle monthly with specific day of month
+    if (dayOfMonth && (!daysOfWeek || daysOfWeek.length === 0)) {
+        return `monthly_${dayOfMonth}`;
+    }
+    // Handle monthly with day-of-week patterns
+    if (daysOfWeek && daysOfWeek.length > 0) {
+        if (weekOfMonth) {
+            // Specific week + specific day: monthly_first_MO, monthly_last_TU
+            if (daysOfWeek.length === 1) {
+                const dayAbbrev = DAY_ABBREVIATIONS[daysOfWeek[0]];
+                return `monthly_${weekOfMonth}_${dayAbbrev}`;
+            }
+            // Specific week + multiple days (not supported directly, use week pattern)
+            if (isWeekdaysPattern(daysOfWeek)) {
+                return `monthly_any_week_day_${weekOfMonth}_week`;
+            }
+            return `monthly_any_day_${weekOfMonth}_week`;
+        }
+        else {
+            // No week specified, use general month patterns
+            if (isWeekdaysPattern(daysOfWeek)) {
+                return 'monthly_any_week_day_of_month';
+            }
+            // Multiple specific days without weekOfMonth is not supported
+            throw new Error('Unsupported multi-day monthly pattern without weekOfMonth. Supported patterns include: monthly_1-31 (e.g., monthly_15), monthly_first_MO, monthly_last_TU, monthly_any_week_day_of_month, monthly_any_day_first_week, etc. Please specify weekOfMonth or see https://docs.usemotion.com/cookbooks/frequency/ for more options.');
+        }
+    }
+    // Handle weekOfMonth without daysOfWeek (any day of specified week)
+    if (weekOfMonth && (!daysOfWeek || daysOfWeek.length === 0)) {
+        return `monthly_any_day_${weekOfMonth}_week`;
+    }
+    // Default to first day of month
+    return 'monthly_1';
+}
+/**
+ * Transform quarterly frequency patterns
+ */
+function transformQuarterlyPattern(daysOfWeek, weekOfMonth, monthOfQuarter) {
+    // Handle quarterly with specific day-of-week
+    if (daysOfWeek && daysOfWeek.length === 1) {
+        const dayAbbrev = DAY_ABBREVIATIONS[daysOfWeek[0]];
+        if (weekOfMonth === 'first') {
+            return `quarterly_first_${dayAbbrev}`;
+        }
+        if (weekOfMonth === 'last') {
+            return `quarterly_last_${dayAbbrev}`;
+        }
+        // Default to first if no week specified
+        return `quarterly_first_${dayAbbrev}`;
+    }
+    // Handle quarterly with week patterns
+    if (weekOfMonth) {
+        if (daysOfWeek && isWeekdaysPattern(daysOfWeek)) {
+            return `quarterly_any_week_day_${weekOfMonth}_week`;
+        }
+        return `quarterly_any_day_${weekOfMonth}_week`;
+    }
+    // Handle quarterly with month patterns
+    if (monthOfQuarter) {
+        return `quarterly_any_day_${getMonthOrdinal(monthOfQuarter)}_month`;
+    }
+    // Handle remaining patterns
+    if (daysOfWeek && isWeekdaysPattern(daysOfWeek)) {
+        return 'quarterly_first_week_day';
+    }
+    // Explicitly reject unsupported multi-day selections
+    if (daysOfWeek && daysOfWeek.length > 1 && !isWeekdaysPattern(daysOfWeek)) {
+        throw new Error('Unsupported multi-day selection for quarterly patterns: ' + JSON.stringify(daysOfWeek) +
+            '. Quarterly patterns only support a single day-of-week (e.g., "quarterly_first_MO"), weekdays (Mon-Fri, "quarterly_any_week_day_first_week"), or any day ("quarterly_any_day_first_week"). ' +
+            'Please refer to the Motion API documentation for supported quarterly patterns: https://docs.usemotion.com/cookbooks/frequency/#quarterly-patterns');
+    }
+    // Default pattern
+    return 'quarterly_first_day';
+}
+/**
+ * Helper: Check if daysOfWeek represents weekdays only (Mon-Fri)
+ */
+function isWeekdaysPattern(daysOfWeek) {
+    return daysOfWeek.length === 5 &&
+        daysOfWeek.includes(1) && daysOfWeek.includes(2) &&
+        daysOfWeek.includes(3) && daysOfWeek.includes(4) &&
+        daysOfWeek.includes(5);
+}
+/**
+ * Helper: Format day numbers to abbreviations
+ * Throws error if invalid days are encountered
+ */
+function formatDayAbbreviations(daysOfWeek) {
+    const invalidDays = daysOfWeek.filter(day => day < 0 || day > 6);
+    if (invalidDays.length > 0) {
+        throw new Error(`Invalid day(s) in daysOfWeek: ${invalidDays.join(', ')}`);
+    }
+    return daysOfWeek
+        .map(day => DAY_ABBREVIATIONS[day])
+        .filter(Boolean)
+        .join(', ');
+}
+/**
+ * Helper: Convert month number to ordinal string
+ */
+function getMonthOrdinal(month) {
+    const ordinals = { 1: 'first', 2: 'second', 3: 'third' };
+    return ordinals[month] || 'first';
+}
+/**
+ * Validates that a frequency object is valid for transformation
+ *
+ * @param frequency - The frequency object to validate
+ * @returns Validation result with detailed reason if invalid
+ */
+function validateFrequencyObject(frequency) {
+    if (!frequency.type || !['daily', 'weekly', 'biweekly', 'monthly', 'quarterly', 'yearly', 'custom'].includes(frequency.type)) {
+        return { valid: false, reason: `Invalid frequency type: ${frequency.type}` };
+    }
+    // Custom type requires customPattern
+    if (frequency.type === 'custom') {
+        if (!frequency.customPattern || typeof frequency.customPattern !== 'string' || frequency.customPattern.trim() === '') {
+            return { valid: false, reason: 'Custom frequency type requires a non-empty customPattern' };
+        }
+        return { valid: true }; // Skip other validations for custom patterns
+    }
+    // Validate daysOfWeek if provided
+    if (frequency.daysOfWeek) {
+        if (!Array.isArray(frequency.daysOfWeek)) {
+            return { valid: false, reason: 'daysOfWeek must be an array' };
+        }
+        // Check that all days are valid (0-6)
+        const invalidDays = frequency.daysOfWeek.filter(day => typeof day !== 'number' || day < 0 || day > 6);
+        if (invalidDays.length > 0) {
+            return { valid: false, reason: `Invalid day(s) in daysOfWeek: ${invalidDays.join(', ')}. Days must be numbers 0-6` };
+        }
+    }
+    // Validate dayOfMonth if provided
+    if (frequency.dayOfMonth !== undefined) {
+        if (typeof frequency.dayOfMonth !== 'number' || frequency.dayOfMonth < 1 || frequency.dayOfMonth > 31) {
+            return { valid: false, reason: 'dayOfMonth must be a number between 1 and 31' };
+        }
+    }
+    // Validate weekOfMonth if provided
+    if (frequency.weekOfMonth !== undefined) {
+        if (!['first', 'second', 'third', 'fourth', 'last'].includes(frequency.weekOfMonth)) {
+            return { valid: false, reason: 'weekOfMonth must be one of: first, second, third, fourth, last' };
+        }
+    }
+    // Validate monthOfQuarter if provided
+    if (frequency.monthOfQuarter !== undefined) {
+        if (typeof frequency.monthOfQuarter !== 'number' || frequency.monthOfQuarter < 1 || frequency.monthOfQuarter > 3) {
+            return { valid: false, reason: 'monthOfQuarter must be 1, 2, or 3' };
+        }
+    }
+    // Validate interval if provided (legacy support)
+    if (frequency.interval !== undefined) {
+        if (typeof frequency.interval !== 'number' || frequency.interval < 1) {
+            return { valid: false, reason: 'interval must be a positive number' };
+        }
+    }
+    // Type-specific validations
+    switch (frequency.type) {
+        case 'quarterly':
+            // Quarterly doesn't support dayOfMonth (not implemented in transform logic)
+            if (frequency.dayOfMonth) {
+                return { valid: false, reason: 'dayOfMonth is not supported for quarterly patterns' };
+            }
+            break;
+        case 'biweekly':
+            // Biweekly doesn't use dayOfMonth or monthOfQuarter
+            if (frequency.dayOfMonth) {
+                return { valid: false, reason: 'dayOfMonth is not supported for biweekly patterns' };
+            }
+            if (frequency.monthOfQuarter) {
+                return { valid: false, reason: 'monthOfQuarter is not supported for biweekly patterns' };
+            }
+            // Biweekly only supports 'first' and 'second' week
+            if (frequency.weekOfMonth && !['first', 'second'].includes(frequency.weekOfMonth)) {
+                return { valid: false, reason: 'weekOfMonth for biweekly patterns must be "first" or "second"' };
+            }
+            break;
+        case 'daily':
+        case 'weekly':
+            // Daily/weekly don't use monthOfQuarter or weekOfMonth
+            if (frequency.monthOfQuarter) {
+                return { valid: false, reason: `monthOfQuarter is not supported for ${frequency.type} patterns` };
+            }
+            if (frequency.weekOfMonth) {
+                return { valid: false, reason: `weekOfMonth is not supported for ${frequency.type} patterns` };
+            }
+            break;
+        case 'monthly':
+            // Monthly doesn't use monthOfQuarter
+            if (frequency.monthOfQuarter) {
+                return { valid: false, reason: 'monthOfQuarter is not supported for monthly patterns' };
+            }
+            break;
+    }
+    return { valid: true };
+}
+/**
+ * Legacy boolean validation function for backward compatibility
+ * @deprecated Use validateFrequencyObject instead for detailed error information
+ */
+function isValidFrequencyObject(frequency) {
+    return validateFrequencyObject(frequency).valid;
+}
+//# sourceMappingURL=frequencyTransform.js.map

package/dist/utils/frequencyTransform.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"frequencyTransform.js","sourceRoot":"","sources":["../../src/utils/frequencyTransform.ts"],"names":[],"mappings":"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"}

package/dist/utils/index.d.ts

@@ -6,6 +6,7 @@
  */
 export * from './constants';
 export * from './errorHandling';
+export * from './userFacingErrors';
 export * from './responseFormatters';
 export * from './parameterUtils';
 export { WorkspaceResolver } from './workspaceResolver';

package/dist/utils/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,cAAc,aAAa,CAAC;AAG5B,cAAc,iBAAiB,CAAC;AAGhC,cAAc,sBAAsB,CAAC;AAGrC,cAAc,kBAAkB,CAAC;AAGjC,OAAO,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAGxD,OAAO,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,cAAc,aAAa,CAAC;AAG5B,cAAc,iBAAiB,CAAC;AAGhC,cAAc,oBAAoB,CAAC;AAGnC,cAAc,sBAAsB,CAAC;AAGrC,cAAc,kBAAkB,CAAC;AAGjC,OAAO,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAGxD,OAAO,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC"}

package/dist/utils/index.js

@@ -25,6 +25,8 @@ exports.mcpLog = exports.WorkspaceResolver = void 0;
 __exportStar(require("./constants"), exports);
 // Export error handling utilities
 __exportStar(require("./errorHandling"), exports);
+// Export user-facing error utilities
+__exportStar(require("./userFacingErrors"), exports);
 // Export response formatters
 __exportStar(require("./responseFormatters"), exports);
 // Export parameter utilities

package/dist/utils/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":";AAAA;;;;;GAKG;;;;;;;;;;;;;;;;;AAEH,uBAAuB;AACvB,8CAA4B;AAE5B,kCAAkC;AAClC,kDAAgC;AAEhC,6BAA6B;AAC7B,uDAAqC;AAErC,6BAA6B;AAC7B,mDAAiC;AAEjC,2BAA2B;AAC3B,yDAAwD;AAA/C,sHAAA,iBAAiB,OAAA;AAE1B,gBAAgB;AAChB,mCAAkC;AAAzB,gGAAA,MAAM,OAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":";AAAA;;;;;GAKG;;;;;;;;;;;;;;;;;AAEH,uBAAuB;AACvB,8CAA4B;AAE5B,kCAAkC;AAClC,kDAAgC;AAEhC,qCAAqC;AACrC,qDAAmC;AAEnC,6BAA6B;AAC7B,uDAAqC;AAErC,6BAA6B;AAC7B,mDAAiC;AAEjC,2BAA2B;AAC3B,yDAAwD;AAA/C,sHAAA,iBAAiB,OAAA;AAE1B,gBAAgB;AAChB,mCAAkC;AAAzB,gGAAA,MAAM,OAAA"}

package/dist/utils/pagination.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Pagination Utilities - Shared pagination logic for Motion API calls
+ *
+ * Provides utilities to handle cursor-based and offset-based pagination
+ * consistently across all API endpoints.
+ */
+import { AxiosResponse } from 'axios';
+export interface PaginatedResponse<T> {
+    items: T[];
+    nextCursor?: string;
+    hasMore: boolean;
+    totalFetched: number;
+}
+export interface PaginationMeta {
+    nextCursor?: string;
+    hasMore?: boolean;
+    total?: number;
+    page?: number;
+    limit?: number;
+}
+export interface CursorPaginationOptions {
+    maxPages?: number;
+    pageSize?: number;
+    logProgress?: boolean;
+}
+export interface PaginatedApiResponse<T> {
+    meta?: PaginationMeta;
+    items?: T[];
+    tasks?: T[];
+    projects?: T[];
+    users?: T[];
+    comments?: T[];
+    customFields?: T[];
+    recurringTasks?: T[];
+    schedules?: T[];
+    statuses?: T[];
+}
+/**
+ * Generic cursor-based pagination handler
+ * Automatically fetches all pages or up to maxPages limit
+ */
+export declare function fetchAllPages<T>(fetchPage: (cursor?: string) => Promise<AxiosResponse<PaginatedApiResponse<T>>>, options?: CursorPaginationOptions): Promise<PaginatedResponse<T>>;
+/**
+ * Simple pagination for APIs that might not have explicit pagination
+ * but could benefit from batching large requests
+ */
+export interface BatchOptions {
+    batchSize?: number;
+    maxBatches?: number;
+    delayMs?: number;
+}
+export declare function fetchInBatches<T, TParams>(fetchBatch: (params: TParams, offset: number, limit: number) => Promise<T[]>, params: TParams, options?: BatchOptions): Promise<T[]>;
+/**
+ * Check if a response indicates more pages are available
+ */
+export declare function hasMorePages<T>(response: PaginatedApiResponse<T>): boolean;
+/**
+ * Get pagination info from response
+ */
+export declare function getPaginationInfo<T>(response: PaginatedApiResponse<T>): PaginationMeta | null;
+//# sourceMappingURL=pagination.d.ts.map

package/dist/utils/pagination.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pagination.d.ts","sourceRoot":"","sources":["../../src/utils/pagination.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,OAAO,CAAC;AAItC,MAAM,WAAW,iBAAiB,CAAC,CAAC;IAClC,KAAK,EAAE,CAAC,EAAE,CAAC;IACX,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,OAAO,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,cAAc;IAC7B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB;AAED,MAAM,WAAW,oBAAoB,CAAC,CAAC;IACrC,IAAI,CAAC,EAAE,cAAc,CAAC;IACtB,KAAK,CAAC,EAAE,CAAC,EAAE,CAAC;IACZ,KAAK,CAAC,EAAE,CAAC,EAAE,CAAC;IACZ,QAAQ,CAAC,EAAE,CAAC,EAAE,CAAC;IACf,KAAK,CAAC,EAAE,CAAC,EAAE,CAAC;IACZ,QAAQ,CAAC,EAAE,CAAC,EAAE,CAAC;IACf,YAAY,CAAC,EAAE,CAAC,EAAE,CAAC;IACnB,cAAc,CAAC,EAAE,CAAC,EAAE,CAAC;IACrB,SAAS,CAAC,EAAE,CAAC,EAAE,CAAC;IAChB,QAAQ,CAAC,EAAE,CAAC,EAAE,CAAC;CAChB;AAED;;;GAGG;AACH,wBAAsB,aAAa,CAAC,CAAC,EACnC,SAAS,EAAE,CAAC,MAAM,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC,aAAa,CAAC,oBAAoB,CAAC,CAAC,CAAC,CAAC,CAAC,EAC/E,OAAO,GAAE,uBAA4B,GACpC,OAAO,CAAC,iBAAiB,CAAC,CAAC,CAAC,CAAC,CAqF/B;AAyBD;;;GAGG;AACH,MAAM,WAAW,YAAY;IAC3B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,wBAAsB,cAAc,CAAC,CAAC,EAAE,OAAO,EAC7C,UAAU,EAAE,CAAC,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,EAAE,CAAC,EAC5E,MAAM,EAAE,OAAO,EACf,OAAO,GAAE,YAAiB,GACzB,OAAO,CAAC,CAAC,EAAE,CAAC,CAuCd;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAAE,QAAQ,EAAE,oBAAoB,CAAC,CAAC,CAAC,GAAG,OAAO,CAE1E;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,QAAQ,EAAE,oBAAoB,CAAC,CAAC,CAAC,GAAG,cAAc,GAAG,IAAI,CAE7F"}

package/dist/utils/pagination.js

@@ -0,0 +1,168 @@
+"use strict";
+/**
+ * Pagination Utilities - Shared pagination logic for Motion API calls
+ *
+ * Provides utilities to handle cursor-based and offset-based pagination
+ * consistently across all API endpoints.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.fetchAllPages = fetchAllPages;
+exports.fetchInBatches = fetchInBatches;
+exports.hasMorePages = hasMorePages;
+exports.getPaginationInfo = getPaginationInfo;
+const logger_1 = require("./logger");
+const constants_1 = require("./constants");
+/**
+ * Generic cursor-based pagination handler
+ * Automatically fetches all pages or up to maxPages limit
+ */
+async function fetchAllPages(fetchPage, options = {}) {
+    const { maxPages = 10, logProgress = true } = options;
+    let allItems = [];
+    let cursor;
+    let pageCount = 0;
+    let hasMore = true;
+    // Infinite loop protection - ensure we never fetch more than absolute max pages
+    const absoluteMaxPages = Math.min(maxPages, 50); // Hard limit to prevent infinite loops
+    while (hasMore && pageCount < absoluteMaxPages) {
+        try {
+            if (logProgress && pageCount > 0) {
+                (0, logger_1.mcpLog)(constants_1.LOG_LEVELS.DEBUG, `Fetching page ${pageCount + 1}`, { cursor });
+            }
+            const response = await fetchPage(cursor);
+            const data = response.data;
+            // Extract items from various possible response structures
+            const pageItems = extractItemsFromResponse(data);
+            // Enforce page size limit to prevent memory exhaustion
+            if (pageItems.length > constants_1.LIMITS.MAX_PAGE_SIZE) {
+                (0, logger_1.mcpLog)(constants_1.LOG_LEVELS.WARN, `Page size ${pageItems.length} exceeds maximum allowed ${constants_1.LIMITS.MAX_PAGE_SIZE}, truncating`, {
+                    pageNumber: pageCount + 1,
+                    originalSize: pageItems.length,
+                    truncatedSize: constants_1.LIMITS.MAX_PAGE_SIZE
+                });
+                pageItems.splice(constants_1.LIMITS.MAX_PAGE_SIZE); // Truncate to limit
+            }
+            allItems = allItems.concat(pageItems);
+            // Update pagination state
+            const newCursor = data.meta?.nextCursor;
+            // Infinite loop protection: If cursor doesn't change, break
+            if (cursor && newCursor === cursor) {
+                (0, logger_1.mcpLog)(constants_1.LOG_LEVELS.WARN, 'Pagination cursor not advancing - breaking to prevent infinite loop', {
+                    cursor,
+                    pageCount,
+                    itemsCount: pageItems.length
+                });
+                break;
+            }
+            cursor = newCursor;
+            hasMore = !!cursor && pageItems.length > 0;
+            pageCount++;
+            if (logProgress) {
+                (0, logger_1.mcpLog)(constants_1.LOG_LEVELS.DEBUG, `Page ${pageCount} fetched`, {
+                    pageItems: pageItems.length,
+                    totalItems: allItems.length,
+                    hasMore,
+                    nextCursor: cursor
+                });
+            }
+        }
+        catch (error) {
+            (0, logger_1.mcpLog)(constants_1.LOG_LEVELS.ERROR, `Pagination failed on page ${pageCount + 1}`, {
+                error: error instanceof Error ? error.message : String(error),
+                cursor
+            });
+            // Return what we have so far
+            break;
+        }
+    }
+    if (pageCount >= absoluteMaxPages && hasMore) {
+        (0, logger_1.mcpLog)(constants_1.LOG_LEVELS.WARN, `Reached maximum page limit (${absoluteMaxPages})`, {
+            totalFetched: allItems.length,
+            finalCursor: cursor
+        });
+    }
+    return {
+        items: allItems,
+        nextCursor: cursor,
+        hasMore,
+        totalFetched: allItems.length
+    };
+}
+/**
+ * Extract items from various API response structures
+ * Handles the different ways Motion API can structure responses
+ */
+function extractItemsFromResponse(data) {
+    // Try different possible array locations
+    if (data.tasks && Array.isArray(data.tasks))
+        return data.tasks;
+    if (data.projects && Array.isArray(data.projects))
+        return data.projects;
+    if (data.users && Array.isArray(data.users))
+        return data.users;
+    if (data.comments && Array.isArray(data.comments))
+        return data.comments;
+    if (data.customFields && Array.isArray(data.customFields))
+        return data.customFields;
+    if (data.recurringTasks && Array.isArray(data.recurringTasks))
+        return data.recurringTasks;
+    if (data.schedules && Array.isArray(data.schedules))
+        return data.schedules;
+    if (data.statuses && Array.isArray(data.statuses))
+        return data.statuses;
+    if (data.items && Array.isArray(data.items))
+        return data.items;
+    // Fallback: if data itself is an array
+    if (Array.isArray(data))
+        return data;
+    // No items found
+    return [];
+}
+async function fetchInBatches(fetchBatch, params, options = {}) {
+    const { batchSize = 100, maxBatches = 10, delayMs = 100 } = options;
+    let allItems = [];
+    let offset = 0;
+    let batchCount = 0;
+    let hasMore = true;
+    while (hasMore && batchCount < maxBatches) {
+        try {
+            const batchItems = await fetchBatch(params, offset, batchSize);
+            if (batchItems.length === 0) {
+                hasMore = false;
+            }
+            else {
+                allItems = allItems.concat(batchItems);
+                offset += batchSize;
+                batchCount++;
+                // Small delay to be API-friendly
+                if (delayMs > 0 && hasMore) {
+                    await new Promise(resolve => setTimeout(resolve, delayMs));
+                }
+                // If we got fewer items than batch size, we've reached the end
+                if (batchItems.length < batchSize) {
+                    hasMore = false;
+                }
+            }
+        }
+        catch (error) {
+            (0, logger_1.mcpLog)(constants_1.LOG_LEVELS.ERROR, `Batch fetch failed at offset ${offset}`, {
+                error: error instanceof Error ? error.message : String(error)
+            });
+            break;
+        }
+    }
+    return allItems;
+}
+/**
+ * Check if a response indicates more pages are available
+ */
+function hasMorePages(response) {
+    return !!(response.meta?.nextCursor || response.meta?.hasMore);
+}
+/**
+ * Get pagination info from response
+ */
+function getPaginationInfo(response) {
+    return response.meta || null;
+}
+//# sourceMappingURL=pagination.js.map

package/dist/utils/pagination.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pagination.js","sourceRoot":"","sources":["../../src/utils/pagination.ts"],"names":[],"mappings":"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"}

package/dist/utils/paginationNew.d.ts

@@ -41,4 +41,18 @@ export declare function fetchSinglePage<T>(fetchPage: (cursor?: string) => Promi
  */
 export declare function endpointSupportsPagination(apiEndpoint: string): boolean;
 export { UnwrappedResponse } from './responseWrapper';
+/**
+ * Calculate adaptive fetch limit for search operations with overfetching.
+ *
+ * Used when fetching items that will be filtered client-side. The overfetch
+ * multiplier (typically 3x) compensates for filtered results, reducing the
+ * number of API calls needed while avoiding excessive memory usage.
+ *
+ * @param currentCount - Number of items already collected
+ * @param targetLimit - Maximum items the caller wants
+ * @param overfetchMultiplier - How much to overfetch (default 3x based on typical filter ratios)
+ * @param maxFetchLimit - Absolute maximum for a single fetch (prevents resource exhaustion)
+ * @returns Number of items to request, or 0 if target already reached
+ */
+export declare function calculateAdaptiveFetchLimit(currentCount: number, targetLimit: number, overfetchMultiplier?: number, maxFetchLimit?: number): number;
 //# sourceMappingURL=paginationNew.d.ts.map

package/dist/utils/paginationNew.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"paginationNew.d.ts","sourceRoot":"","sources":["../../src/utils/paginationNew.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,OAAO,CAAC;AAGtC,OAAO,EAAyC,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAG7F,MAAM,WAAW,iBAAiB,CAAC,CAAC;IAClC,KAAK,EAAE,CAAC,EAAE,CAAC;IACX,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,OAAO,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;GAOG;AACH,wBAAsB,aAAa,CAAC,CAAC,EACnC,SAAS,EAAE,CAAC,MAAM,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC,aAAa,CAAC,GAAG,CAAC,CAAC,EAC3D,WAAW,EAAE,MAAM,EACnB,OAAO,GAAE,uBAA4B,GACpC,OAAO,CAAC,iBAAiB,CAAC,CAAC,CAAC,CAAC,CAuH/B;AAED;;;;;;;GAOG;AACH,wBAAsB,eAAe,CAAC,CAAC,EACrC,SAAS,EAAE,CAAC,MAAM,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC,aAAa,CAAC,GAAG,CAAC,CAAC,EAC3D,WAAW,EAAE,MAAM,EACnB,MAAM,CAAC,EAAE,MAAM,GACd,OAAO,CAAC,iBAAiB,CAAC,CAAC,CAAC,CAAC,CAG/B;AAED;;GAEG;AACH,wBAAgB,0BAA0B,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAEvE;AAGD,OAAO,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC"}
+{"version":3,"file":"paginationNew.d.ts","sourceRoot":"","sources":["../../src/utils/paginationNew.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,OAAO,CAAC;AAGtC,OAAO,EAAyC,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAG7F,MAAM,WAAW,iBAAiB,CAAC,CAAC;IAClC,KAAK,EAAE,CAAC,EAAE,CAAC;IACX,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,OAAO,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;GAOG;AACH,wBAAsB,aAAa,CAAC,CAAC,EACnC,SAAS,EAAE,CAAC,MAAM,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC,aAAa,CAAC,GAAG,CAAC,CAAC,EAC3D,WAAW,EAAE,MAAM,EACnB,OAAO,GAAE,uBAA4B,GACpC,OAAO,CAAC,iBAAiB,CAAC,CAAC,CAAC,CAAC,CA6H/B;AAED;;;;;;;GAOG;AACH,wBAAsB,eAAe,CAAC,CAAC,EACrC,SAAS,EAAE,CAAC,MAAM,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC,aAAa,CAAC,GAAG,CAAC,CAAC,EAC3D,WAAW,EAAE,MAAM,EACnB,MAAM,CAAC,EAAE,MAAM,GACd,OAAO,CAAC,iBAAiB,CAAC,CAAC,CAAC,CAAC,CAG/B;AAED;;GAEG;AACH,wBAAgB,0BAA0B,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAEvE;AAGD,OAAO,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAEtD;;;;;;;;;;;;GAYG;AACH,wBAAgB,2BAA2B,CACzC,YAAY,EAAE,MAAM,EACpB,WAAW,EAAE,MAAM,EACnB,mBAAmB,GAAE,MAAU,EAC/B,aAAa,GAAE,MAAkC,GAChD,MAAM,CAKR"}