@mainwp/mcp 1.0.0-beta.1

package/dist/naming.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Name Conversion Utilities
+ *
+ * Shared functions for converting between MainWP ability names and MCP tool names.
+ * Extracted to avoid circular imports between abilities.ts and tools.ts.
+ */
+/**
+ * Convert ability name to MCP tool name
+ * Strips namespace prefix since MCP server name provides context.
+ * e.g., "mainwp/list-sites-v1" -> "list_sites_v1"
+ */
+export declare function abilityNameToToolName(abilityName: string): string;
+/**
+ * Map MCP tool name back to ability name.
+ * Prepends the namespace since tool names don't include it.
+ *
+ * Note: This server only uses the 'mainwp' namespace. The namespace parameter
+ * is kept for test flexibility but is always called with 'mainwp' in production.
+ *
+ * @example toolNameToAbilityName("list_sites_v1", "mainwp") -> "mainwp/list-sites-v1"
+ */
+export declare function toolNameToAbilityName(toolName: string, namespace: string): string;
+//# sourceMappingURL=naming.d.ts.map

package/dist/naming.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"naming.d.ts","sourceRoot":"","sources":["../src/naming.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CASjE;AAED;;;;;;;;GAQG;AACH,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAKjF"}

package/dist/naming.js

@@ -0,0 +1,37 @@
+/**
+ * Name Conversion Utilities
+ *
+ * Shared functions for converting between MainWP ability names and MCP tool names.
+ * Extracted to avoid circular imports between abilities.ts and tools.ts.
+ */
+/**
+ * Convert ability name to MCP tool name
+ * Strips namespace prefix since MCP server name provides context.
+ * e.g., "mainwp/list-sites-v1" -> "list_sites_v1"
+ */
+export function abilityNameToToolName(abilityName) {
+    // Strip namespace prefix: "mainwp/list-sites-v1" → "list-sites-v1"
+    const slashIndex = abilityName.indexOf('/');
+    if (slashIndex === -1) {
+        throw new Error(`Invalid ability name format (missing namespace): ${abilityName}`);
+    }
+    const withoutNamespace = abilityName.slice(slashIndex + 1);
+    // Convert hyphens to underscores: "list-sites-v1" → "list_sites_v1"
+    return withoutNamespace.replace(/-/g, '_');
+}
+/**
+ * Map MCP tool name back to ability name.
+ * Prepends the namespace since tool names don't include it.
+ *
+ * Note: This server only uses the 'mainwp' namespace. The namespace parameter
+ * is kept for test flexibility but is always called with 'mainwp' in production.
+ *
+ * @example toolNameToAbilityName("list_sites_v1", "mainwp") -> "mainwp/list-sites-v1"
+ */
+export function toolNameToAbilityName(toolName, namespace) {
+    // Convert underscores back to hyphens: "list_sites_v1" → "list-sites-v1"
+    const withHyphens = toolName.replace(/_/g, '-');
+    // Prepend namespace: "mainwp/list-sites-v1"
+    return `${namespace}/${withHyphens}`;
+}
+//# sourceMappingURL=naming.js.map

package/dist/naming.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"naming.js","sourceRoot":"","sources":["../src/naming.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;;;GAIG;AACH,MAAM,UAAU,qBAAqB,CAAC,WAAmB;IACvD,mEAAmE;IACnE,MAAM,UAAU,GAAG,WAAW,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;IAC5C,IAAI,UAAU,KAAK,CAAC,CAAC,EAAE,CAAC;QACtB,MAAM,IAAI,KAAK,CAAC,oDAAoD,WAAW,EAAE,CAAC,CAAC;IACrF,CAAC;IACD,MAAM,gBAAgB,GAAG,WAAW,CAAC,KAAK,CAAC,UAAU,GAAG,CAAC,CAAC,CAAC;IAC3D,oEAAoE;IACpE,OAAO,gBAAgB,CAAC,OAAO,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;AAC7C,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,qBAAqB,CAAC,QAAgB,EAAE,SAAiB;IACvE,yEAAyE;IACzE,MAAM,WAAW,GAAG,QAAQ,CAAC,OAAO,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;IAChD,4CAA4C;IAC5C,OAAO,GAAG,SAAS,IAAI,WAAW,EAAE,CAAC;AACvC,CAAC"}

package/dist/prompts.d.ts

@@ -0,0 +1,22 @@
+/**
+ * MCP Prompt Templates
+ *
+ * Pre-defined workflow prompts for common MainWP operations.
+ * These help AI assistants guide users through complex tasks.
+ */
+import type { Prompt, GetPromptResult } from '@modelcontextprotocol/sdk/types.js';
+/**
+ * Get the list of available prompts for MCP ListPrompts request
+ */
+export declare function getPromptList(): Prompt[];
+/**
+ * Get a specific prompt with its messages for MCP GetPrompt request
+ */
+export declare function getPrompt(name: string, args?: Record<string, string>): GetPromptResult;
+/**
+ * Get prompt argument values for completions
+ * @param _promptName - Reserved for future prompt-specific completions
+ * @param argumentName - The argument to get completions for
+ */
+export declare function getPromptArgumentCompletions(_promptName: string, argumentName: string): string[];
+//# sourceMappingURL=prompts.d.ts.map

package/dist/prompts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompts.d.ts","sourceRoot":"","sources":["../src/prompts.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,eAAe,EAAiB,MAAM,oCAAoC,CAAC;AAuVjG;;GAEG;AACH,wBAAgB,aAAa,IAAI,MAAM,EAAE,CAMxC;AAwDD;;GAEG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,eAAe,CAatF;AAED;;;;GAIG;AACH,wBAAgB,4BAA4B,CAAC,WAAW,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,MAAM,EAAE,CAWhG"}

package/dist/prompts.js

@@ -0,0 +1,414 @@
+/**
+ * MCP Prompt Templates
+ *
+ * Pre-defined workflow prompts for common MainWP operations.
+ * These help AI assistants guide users through complex tasks.
+ */
+/**
+ * All available prompt definitions
+ */
+const promptDefinitions = [
+    // === Site Troubleshooting ===
+    {
+        name: 'troubleshoot-site',
+        description: 'Diagnose issues with a MainWP child site',
+        arguments: [
+            { name: 'site_id', description: 'ID of the site to troubleshoot', required: true },
+            {
+                name: 'issue_type',
+                description: 'Focus area: connectivity, performance, security, updates (optional)',
+                required: false,
+            },
+        ],
+        getMessages: args => [
+            {
+                role: 'user',
+                content: {
+                    type: 'text',
+                    text: `Please diagnose issues with site ID ${args?.site_id || '[site_id]'}.${args?.issue_type ? ` Focus on: ${args.issue_type}.` : ''}
+
+Steps to follow:
+1. Use get_site_v1 to get site details and check connectivity status
+2. Check the last sync time - if stale, there may be connectivity issues
+3. Use list_updates_v1 to check for pending updates
+4. Review any error messages or warnings
+
+Provide a summary of:
+- Current site status
+- Any issues found
+- Recommended actions to resolve problems`,
+                },
+            },
+        ],
+    },
+    // === Maintenance Check ===
+    {
+        name: 'maintenance-check',
+        description: 'Run a comprehensive maintenance check across all managed sites',
+        arguments: [],
+        getMessages: () => [
+            {
+                role: 'user',
+                content: {
+                    type: 'text',
+                    text: `Run a comprehensive maintenance check across all managed sites.
+
+Steps to follow:
+1. Use list_sites_v1 to get all sites
+2. Use list_updates_v1 to check for pending updates
+3. Identify sites that haven't synced recently (check last_sync timestamps)
+
+Generate a maintenance summary including:
+- Total sites managed
+- Sites with pending plugin updates (list them)
+- Sites with pending theme updates (list them)
+- Sites with pending WordPress core updates (list them)
+- Sites with connectivity issues or stale sync times
+- Recommended priority order for maintenance tasks`,
+                },
+            },
+        ],
+    },
+    // === Update Workflow ===
+    {
+        name: 'update-workflow',
+        description: 'Guide through safely updating WordPress sites',
+        arguments: [
+            {
+                name: 'update_type',
+                description: 'Type of updates: plugins, themes, core, or all',
+                required: false,
+            },
+            {
+                name: 'site_ids',
+                description: 'Comma-separated site IDs, or "all" for all sites',
+                required: false,
+            },
+        ],
+        getMessages: args => [
+            {
+                role: 'user',
+                content: {
+                    type: 'text',
+                    text: `Help me safely update ${args?.update_type || 'all'} on ${args?.site_ids || 'all sites'}.
+
+Guide me through this update workflow:
+
+1. **Pre-update Assessment**
+   - List all pending ${args?.update_type || ''} updates using list_updates_v1
+   - Identify any updates that might have compatibility issues
+   - Check which sites are affected
+
+2. **Update Strategy**
+   - Recommend which updates to apply first (security patches > bug fixes > features)
+   - Suggest testing on staging/less critical sites first
+   - Identify any plugins/themes that should be researched before updating
+
+3. **Safety Recommendations**
+   - Remind about backup status
+   - Suggest update order (core before plugins/themes)
+   - Note any updates that require manual intervention
+
+Please start by checking the current update status.`,
+                },
+            },
+        ],
+    },
+    // === Site Report ===
+    {
+        name: 'site-report',
+        description: 'Generate a detailed report for a specific site',
+        arguments: [{ name: 'site_id', description: 'ID of the site to report on', required: true }],
+        getMessages: args => [
+            {
+                role: 'user',
+                content: {
+                    type: 'text',
+                    text: `Generate a detailed report for site ID ${args?.site_id || '[site_id]'}.
+
+Gather information using available tools and create a report covering:
+
+1. **Site Overview**
+   - Site name and URL
+   - WordPress version
+   - Last sync status and time
+
+2. **Update Status**
+   - Pending plugin updates (count and list)
+   - Pending theme updates (count and list)
+   - Core update status
+
+3. **Health Indicators**
+   - Connectivity status
+   - Any recent errors or warnings
+   - Sync reliability
+
+4. **Recommendations**
+   - Prioritized action items
+   - Any immediate concerns
+
+Format the report in a clear, scannable format.`,
+                },
+            },
+        ],
+    },
+    // === Network Summary ===
+    {
+        name: 'network-summary',
+        description: 'Generate a summary report of all managed sites',
+        arguments: [],
+        getMessages: () => [
+            {
+                role: 'user',
+                content: {
+                    type: 'text',
+                    text: `Generate a network-wide summary of all managed WordPress sites.
+
+Steps to follow:
+1. Use list_sites_v1 to get all sites
+2. Aggregate statistics across the network
+
+Create a summary report including:
+
+**Network Overview**
+- Total number of sites
+- Sites by status (connected, disconnected, issues)
+
+**Update Summary**
+- Total pending plugin updates
+- Total pending theme updates
+- Total pending core updates
+- Sites fully up-to-date vs needing updates
+
+**Health Overview**
+- Sites synced in last 24 hours
+- Sites with stale sync (>24 hours)
+- Any sites with errors
+
+**Action Items**
+- Most urgent maintenance tasks
+- Sites requiring immediate attention
+
+Present the data in a clear, executive-summary format.`,
+                },
+            },
+        ],
+    },
+    // === Security Audit ===
+    {
+        name: 'security-audit',
+        description: 'Perform a security-focused audit of managed sites',
+        arguments: [
+            {
+                name: 'site_ids',
+                description: 'Comma-separated site IDs to audit, or "all"',
+                required: false,
+            },
+        ],
+        getMessages: args => [
+            {
+                role: 'user',
+                content: {
+                    type: 'text',
+                    text: `Perform a security-focused audit of ${args?.site_ids || 'all managed sites'}.
+
+Security audit checklist:
+
+1. **WordPress Core**
+   - Check for outdated WordPress versions
+   - Identify any sites running unsupported versions
+
+2. **Plugin Security**
+   - List plugins with available security updates
+   - Identify any plugins that are abandoned/not updated in 2+ years
+   - Flag plugins known to have security issues
+
+3. **Theme Security**
+   - Check for outdated themes
+   - Identify unused themes that should be removed
+
+4. **General Recommendations**
+   - Sites most urgently needing security updates
+   - Best practices reminders
+   - Priority order for security updates
+
+Start by gathering the site and update information, then provide the security assessment.`,
+                },
+            },
+        ],
+    },
+    // === Backup Status ===
+    {
+        name: 'backup-status',
+        description: 'Check backup status across managed sites',
+        arguments: [
+            {
+                name: 'site_ids',
+                description: 'Comma-separated site IDs, or "all" (default)',
+                required: false,
+            },
+        ],
+        getMessages: args => [
+            {
+                role: 'user',
+                content: {
+                    type: 'text',
+                    text: `Check the backup status for ${args?.site_ids || 'all managed sites'}.
+
+Please help me understand the backup situation:
+
+1. **Backup Overview**
+   - Which sites have backup plugins installed?
+   - When was the last backup for each site?
+   - Are there any sites without backup solutions?
+
+2. **Backup Health**
+   - Sites with recent backups (< 24 hours)
+   - Sites with aging backups (> 7 days)
+   - Sites with no recent backup data
+
+3. **Recommendations**
+   - Sites that need immediate backup attention
+   - Suggestions for backup improvements
+   - Best practices for backup frequency
+
+Note: This analysis depends on the backup data available through MainWP. If backup information is limited, please indicate what additional data would be helpful.`,
+                },
+            },
+        ],
+    },
+    // === Performance Check ===
+    {
+        name: 'performance-check',
+        description: 'Analyze site performance indicators',
+        arguments: [
+            {
+                name: 'site_id',
+                description: 'Site ID to analyze, or "all" for overview',
+                required: false,
+            },
+        ],
+        getMessages: args => [
+            {
+                role: 'user',
+                content: {
+                    type: 'text',
+                    text: `Analyze performance indicators for ${args?.site_id ? `site ID ${args.site_id}` : 'all managed sites'}.
+
+Performance analysis:
+
+1. **Site Health**
+   - Sync response times (if available)
+   - Connection reliability
+   - Any timeout or connection errors
+
+2. **Resource Indicators**
+   - Number of active plugins (more plugins = potential slowdown)
+   - Theme complexity indicators
+   - Database or storage concerns (if data available)
+
+3. **Optimization Opportunities**
+   - Sites with excessive plugins
+   - Outdated components that may impact performance
+   - Caching and optimization plugin status
+
+4. **Recommendations**
+   - Sites most likely to benefit from optimization
+   - Quick wins for performance improvement
+   - Further investigation suggestions
+
+Gather available data and provide performance insights based on what can be determined from MainWP.`,
+                },
+            },
+        ],
+    },
+];
+/**
+ * Get the list of available prompts for MCP ListPrompts request
+ */
+export function getPromptList() {
+    return promptDefinitions.map(({ name, description, arguments: args }) => ({
+        name,
+        description,
+        arguments: args,
+    }));
+}
+/** Allowed values for the issue_type prompt argument */
+const VALID_ISSUE_TYPES = new Set(['connectivity', 'performance', 'security', 'updates']);
+/** Allowed values for the update_type prompt argument */
+const VALID_UPDATE_TYPES = new Set(['plugins', 'themes', 'core', 'all']);
+/**
+ * Validate and sanitize prompt arguments before interpolation.
+ * Prevents prompt injection via template arguments.
+ */
+function validatePromptArgs(args) {
+    if (!args)
+        return args;
+    const sanitized = {};
+    for (const [key, value] of Object.entries(args)) {
+        if (typeof value !== 'string')
+            continue;
+        // site_id: numeric or "all"; site_ids: "all" or comma-separated numeric
+        if (key === 'site_id') {
+            if (value !== 'all' && !/^\d+$/.test(value)) {
+                throw new Error(`Invalid site_id: must be a numeric value or "all"`);
+            }
+            sanitized[key] = value;
+        }
+        else if (key === 'site_ids') {
+            // "all" or comma-separated IDs
+            if (value !== 'all' && !/^(\d+)(,\s*\d+)*$/.test(value)) {
+                throw new Error(`Invalid site_ids: must be "all" or comma-separated numeric IDs`);
+            }
+            sanitized[key] = value;
+        }
+        else if (key === 'issue_type') {
+            if (!VALID_ISSUE_TYPES.has(value)) {
+                throw new Error(`Invalid issue_type: must be one of ${[...VALID_ISSUE_TYPES].join(', ')}`);
+            }
+            sanitized[key] = value;
+        }
+        else if (key === 'update_type') {
+            if (!VALID_UPDATE_TYPES.has(value)) {
+                throw new Error(`Invalid update_type: must be one of ${[...VALID_UPDATE_TYPES].join(', ')}`);
+            }
+            sanitized[key] = value;
+        }
+        else {
+            // Unknown argument: truncate to reasonable length and strip control characters
+            // eslint-disable-next-line no-control-regex
+            sanitized[key] = value.slice(0, 200).replace(/[\x00-\x1f]/g, '');
+        }
+    }
+    return sanitized;
+}
+/**
+ * Get a specific prompt with its messages for MCP GetPrompt request
+ */
+export function getPrompt(name, args) {
+    const prompt = promptDefinitions.find(p => p.name === name);
+    if (!prompt) {
+        throw new Error(`Unknown prompt: ${name}`);
+    }
+    // Validate and sanitize arguments before interpolation to prevent prompt injection
+    const validatedArgs = validatePromptArgs(args);
+    return {
+        messages: prompt.getMessages(validatedArgs),
+    };
+}
+/**
+ * Get prompt argument values for completions
+ * @param _promptName - Reserved for future prompt-specific completions
+ * @param argumentName - The argument to get completions for
+ */
+export function getPromptArgumentCompletions(_promptName, argumentName) {
+    if (argumentName === 'update_type') {
+        return ['plugins', 'themes', 'core', 'all'];
+    }
+    if (argumentName === 'issue_type') {
+        return ['connectivity', 'performance', 'security', 'updates'];
+    }
+    // site_id and site_ids require dynamic data - return empty for static completions
+    return [];
+}
+//# sourceMappingURL=prompts.js.map

package/dist/prompts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompts.js","sourceRoot":"","sources":["../src/prompts.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAkBH;;GAEG;AACH,MAAM,iBAAiB,GAAuB;IAC5C,+BAA+B;IAC/B;QACE,IAAI,EAAE,mBAAmB;QACzB,WAAW,EAAE,0CAA0C;QACvD,SAAS,EAAE;YACT,EAAE,IAAI,EAAE,SAAS,EAAE,WAAW,EAAE,gCAAgC,EAAE,QAAQ,EAAE,IAAI,EAAE;YAClF;gBACE,IAAI,EAAE,YAAY;gBAClB,WAAW,EAAE,qEAAqE;gBAClF,QAAQ,EAAE,KAAK;aAChB;SACF;QACD,WAAW,EAAE,IAAI,CAAC,EAAE,CAAC;YACnB;gBACE,IAAI,EAAE,MAAM;gBACZ,OAAO,EAAE;oBACP,IAAI,EAAE,MAAM;oBACZ,IAAI,EAAE,uCAAuC,IAAI,EAAE,OAAO,IAAI,WAAW,IAAI,IAAI,EAAE,UAAU,CAAC,CAAC,CAAC,cAAc,IAAI,CAAC,UAAU,GAAG,CAAC,CAAC,CAAC,EAAE;;;;;;;;;;;0CAWrG;iBACjC;aACF;SACF;KACF;IAED,4BAA4B;IAC5B;QACE,IAAI,EAAE,mBAAmB;QACzB,WAAW,EAAE,gEAAgE;QAC7E,SAAS,EAAE,EAAE;QACb,WAAW,EAAE,GAAG,EAAE,CAAC;YACjB;gBACE,IAAI,EAAE,MAAM;gBACZ,OAAO,EAAE;oBACP,IAAI,EAAE,MAAM;oBACZ,IAAI,EAAE;;;;;;;;;;;;;mDAamC;iBAC1C;aACF;SACF;KACF;IAED,0BAA0B;IAC1B;QACE,IAAI,EAAE,iBAAiB;QACvB,WAAW,EAAE,+CAA+C;QAC5D,SAAS,EAAE;YACT;gBACE,IAAI,EAAE,aAAa;gBACnB,WAAW,EAAE,gDAAgD;gBAC7D,QAAQ,EAAE,KAAK;aAChB;YACD;gBACE,IAAI,EAAE,UAAU;gBAChB,WAAW,EAAE,kDAAkD;gBAC/D,QAAQ,EAAE,KAAK;aAChB;SACF;QACD,WAAW,EAAE,IAAI,CAAC,EAAE,CAAC;YACnB;gBACE,IAAI,EAAE,MAAM;gBACZ,OAAO,EAAE;oBACP,IAAI,EAAE,MAAM;oBACZ,IAAI,EAAE,yBAAyB,IAAI,EAAE,WAAW,IAAI,KAAK,OAAO,IAAI,EAAE,QAAQ,IAAI,WAAW;;;;;wBAK/E,IAAI,EAAE,WAAW,IAAI,EAAE;;;;;;;;;;;;;;oDAcK;iBAC3C;aACF;SACF;KACF;IAED,sBAAsB;IACtB;QACE,IAAI,EAAE,aAAa;QACnB,WAAW,EAAE,gDAAgD;QAC7D,SAAS,EAAE,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE,WAAW,EAAE,6BAA6B,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC;QAC5F,WAAW,EAAE,IAAI,CAAC,EAAE,CAAC;YACnB;gBACE,IAAI,EAAE,MAAM;gBACZ,OAAO,EAAE;oBACP,IAAI,EAAE,MAAM;oBACZ,IAAI,EAAE,0CAA0C,IAAI,EAAE,OAAO,IAAI,WAAW;;;;;;;;;;;;;;;;;;;;;;;gDAuBtC;iBACvC;aACF;SACF;KACF;IAED,0BAA0B;IAC1B;QACE,IAAI,EAAE,iBAAiB;QACvB,WAAW,EAAE,gDAAgD;QAC7D,SAAS,EAAE,EAAE;QACb,WAAW,EAAE,GAAG,EAAE,CAAC;YACjB;gBACE,IAAI,EAAE,MAAM;gBACZ,OAAO,EAAE;oBACP,IAAI,EAAE,MAAM;oBACZ,IAAI,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;uDA2BuC;iBAC9C;aACF;SACF;KACF;IAED,yBAAyB;IACzB;QACE,IAAI,EAAE,gBAAgB;QACtB,WAAW,EAAE,mDAAmD;QAChE,SAAS,EAAE;YACT;gBACE,IAAI,EAAE,UAAU;gBAChB,WAAW,EAAE,6CAA6C;gBAC1D,QAAQ,EAAE,KAAK;aAChB;SACF;QACD,WAAW,EAAE,IAAI,CAAC,EAAE,CAAC;YACnB;gBACE,IAAI,EAAE,MAAM;gBACZ,OAAO,EAAE;oBACP,IAAI,EAAE,MAAM;oBACZ,IAAI,EAAE,uCAAuC,IAAI,EAAE,QAAQ,IAAI,mBAAmB;;;;;;;;;;;;;;;;;;;;;;0FAsBF;iBACjF;aACF;SACF;KACF;IAED,wBAAwB;IACxB;QACE,IAAI,EAAE,eAAe;QACrB,WAAW,EAAE,0CAA0C;QACvD,SAAS,EAAE;YACT;gBACE,IAAI,EAAE,UAAU;gBAChB,WAAW,EAAE,8CAA8C;gBAC3D,QAAQ,EAAE,KAAK;aAChB;SACF;QACD,WAAW,EAAE,IAAI,CAAC,EAAE,CAAC;YACnB;gBACE,IAAI,EAAE,MAAM;gBACZ,OAAO,EAAE;oBACP,IAAI,EAAE,MAAM;oBACZ,IAAI,EAAE,+BAA+B,IAAI,EAAE,QAAQ,IAAI,mBAAmB;;;;;;;;;;;;;;;;;;;kKAmB8E;iBACzJ;aACF;SACF;KACF;IAED,4BAA4B;IAC5B;QACE,IAAI,EAAE,mBAAmB;QACzB,WAAW,EAAE,qCAAqC;QAClD,SAAS,EAAE;YACT;gBACE,IAAI,EAAE,SAAS;gBACf,WAAW,EAAE,2CAA2C;gBACxD,QAAQ,EAAE,KAAK;aAChB;SACF;QACD,WAAW,EAAE,IAAI,CAAC,EAAE,CAAC;YACnB;gBACE,IAAI,EAAE,MAAM;gBACZ,OAAO,EAAE;oBACP,IAAI,EAAE,MAAM;oBACZ,IAAI,EAAE,sCAAsC,IAAI,EAAE,OAAO,CAAC,CAAC,CAAC,WAAW,IAAI,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,mBAAmB;;;;;;;;;;;;;;;;;;;;;;;;oGAwBjB;iBAC3F;aACF;SACF;KACF;CACF,CAAC;AAEF;;GAEG;AACH,MAAM,UAAU,aAAa;IAC3B,OAAO,iBAAiB,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,WAAW,EAAE,SAAS,EAAE,IAAI,EAAE,EAAE,EAAE,CAAC,CAAC;QACxE,IAAI;QACJ,WAAW;QACX,SAAS,EAAE,IAAI;KAChB,CAAC,CAAC,CAAC;AACN,CAAC;AAED,wDAAwD;AACxD,MAAM,iBAAiB,GAAG,IAAI,GAAG,CAAC,CAAC,cAAc,EAAE,aAAa,EAAE,UAAU,EAAE,SAAS,CAAC,CAAC,CAAC;AAE1F,yDAAyD;AACzD,MAAM,kBAAkB,GAAG,IAAI,GAAG,CAAC,CAAC,SAAS,EAAE,QAAQ,EAAE,MAAM,EAAE,KAAK,CAAC,CAAC,CAAC;AAEzE;;;GAGG;AACH,SAAS,kBAAkB,CACzB,IAAwC;IAExC,IAAI,CAAC,IAAI;QAAE,OAAO,IAAI,CAAC;IAEvB,MAAM,SAAS,GAA2B,EAAE,CAAC;IAE7C,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;QAChD,IAAI,OAAO,KAAK,KAAK,QAAQ;YAAE,SAAS;QAExC,wEAAwE;QACxE,IAAI,GAAG,KAAK,SAAS,EAAE,CAAC;YACtB,IAAI,KAAK,KAAK,KAAK,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;gBAC5C,MAAM,IAAI,KAAK,CAAC,mDAAmD,CAAC,CAAC;YACvE,CAAC;YACD,SAAS,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;QACzB,CAAC;aAAM,IAAI,GAAG,KAAK,UAAU,EAAE,CAAC;YAC9B,+BAA+B;YAC/B,IAAI,KAAK,KAAK,KAAK,IAAI,CAAC,mBAAmB,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;gBACxD,MAAM,IAAI,KAAK,CAAC,gEAAgE,CAAC,CAAC;YACpF,CAAC;YACD,SAAS,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;QACzB,CAAC;aAAM,IAAI,GAAG,KAAK,YAAY,EAAE,CAAC;YAChC,IAAI,CAAC,iBAAiB,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC;gBAClC,MAAM,IAAI,KAAK,CAAC,sCAAsC,CAAC,GAAG,iBAAiB,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;YAC7F,CAAC;YACD,SAAS,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;QACzB,CAAC;aAAM,IAAI,GAAG,KAAK,aAAa,EAAE,CAAC;YACjC,IAAI,CAAC,kBAAkB,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC;gBACnC,MAAM,IAAI,KAAK,CACb,uCAAuC,CAAC,GAAG,kBAAkB,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAC5E,CAAC;YACJ,CAAC;YACD,SAAS,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;QACzB,CAAC;aAAM,CAAC;YACN,+EAA+E;YAC/E,4CAA4C;YAC5C,SAAS,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,OAAO,CAAC,cAAc,EAAE,EAAE,CAAC,CAAC;QACnE,CAAC;IACH,CAAC;IAED,OAAO,SAAS,CAAC;AACnB,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,SAAS,CAAC,IAAY,EAAE,IAA6B;IACnE,MAAM,MAAM,GAAG,iBAAiB,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,IAAI,CAAC,CAAC;IAE5D,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,MAAM,IAAI,KAAK,CAAC,mBAAmB,IAAI,EAAE,CAAC,CAAC;IAC7C,CAAC;IAED,mFAAmF;IACnF,MAAM,aAAa,GAAG,kBAAkB,CAAC,IAAI,CAAC,CAAC;IAE/C,OAAO;QACL,QAAQ,EAAE,MAAM,CAAC,WAAW,CAAC,aAAa,CAAC;KAC5C,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,4BAA4B,CAAC,WAAmB,EAAE,YAAoB;IACpF,IAAI,YAAY,KAAK,aAAa,EAAE,CAAC;QACnC,OAAO,CAAC,SAAS,EAAE,QAAQ,EAAE,MAAM,EAAE,KAAK,CAAC,CAAC;IAC9C,CAAC;IAED,IAAI,YAAY,KAAK,YAAY,EAAE,CAAC;QAClC,OAAO,CAAC,cAAc,EAAE,aAAa,EAAE,UAAU,EAAE,SAAS,CAAC,CAAC;IAChE,CAAC;IAED,kFAAkF;IAClF,OAAO,EAAE,CAAC;AACZ,CAAC"}

package/dist/retry.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Retry Logic for Transient Errors
+ *
+ * Provides exponential backoff with jitter for handling transient network
+ * failures and server errors (HTTP 5xx, 429, network errors).
+ *
+ * Key features:
+ * - Only retries transient errors (5xx, 429, network errors)
+ * - Permanent errors (4xx except 429) fail immediately
+ * - Timeout budget ensures total time never exceeds requestTimeout
+ * - Exponential backoff with jitter prevents thundering herd
+ */
+import type { Logger } from './logging.js';
+/**
+ * Options for retry behavior
+ */
+export interface RetryOptions {
+    /** Maximum retry attempts including initial request */
+    maxRetries: number;
+    /** Base delay between retries in milliseconds */
+    baseDelay: number;
+    /** Maximum delay between retries in milliseconds */
+    maxDelay: number;
+    /** Total time budget in milliseconds for all attempts */
+    timeoutBudget: number;
+    /** Structured logger for retry attempts */
+    logger?: Logger;
+}
+/**
+ * Context passed to retryable operations for timeout budget awareness
+ */
+export interface RetryContext {
+    /** Remaining timeout budget in milliseconds for this attempt */
+    remainingBudget: number;
+    /** Current attempt number (0-indexed) */
+    attempt: number;
+}
+/**
+ * A function that returns a promise and can be retried.
+ * Optionally receives retry context with remaining timeout budget.
+ */
+export type RetryableOperation<T> = (context: RetryContext) => Promise<T>;
+/**
+ * Determine if an error is retryable (transient).
+ *
+ * Retryable errors:
+ * - HTTP 5xx (server errors)
+ * - HTTP 429 (rate limited)
+ * - Network errors: ECONNRESET, ECONNREFUSED, ETIMEDOUT, ENOTFOUND
+ *
+ * Non-retryable errors:
+ * - HTTP 4xx (except 429): client errors, auth failures, validation errors
+ * - AbortError: user cancellation
+ * - Any other errors (treat as permanent)
+ */
+export declare function isRetryableError(error: unknown): boolean;
+/**
+ * Calculate exponential backoff delay with jitter.
+ *
+ * Formula: min(maxDelay, baseDelay * 2^attempt + random(0, baseDelay))
+ *
+ * @param attempt - 0-indexed attempt number (0 for first retry, 1 for second, etc.)
+ * @param baseDelay - Base delay in milliseconds
+ * @param maxDelay - Maximum delay in milliseconds
+ * @returns Delay in milliseconds
+ */
+export declare function calculateBackoff(attempt: number, baseDelay: number, maxDelay: number): number;
+/**
+ * Execute an operation with retry logic.
+ *
+ * @param operation - The async operation to execute
+ * @param options - Retry configuration
+ * @returns The result of the operation
+ * @throws The last error if all retries are exhausted or a non-retryable error occurs
+ */
+export declare function withRetry<T>(operation: RetryableOperation<T>, options: RetryOptions): Promise<T>;
+//# sourceMappingURL=retry.d.ts.map

package/dist/retry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"retry.d.ts","sourceRoot":"","sources":["../src/retry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAE3C;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,uDAAuD;IACvD,UAAU,EAAE,MAAM,CAAC;IACnB,iDAAiD;IACjD,SAAS,EAAE,MAAM,CAAC;IAClB,oDAAoD;IACpD,QAAQ,EAAE,MAAM,CAAC;IACjB,yDAAyD;IACzD,aAAa,EAAE,MAAM,CAAC;IACtB,2CAA2C;IAC3C,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,gEAAgE;IAChE,eAAe,EAAE,MAAM,CAAC;IACxB,yCAAyC;IACzC,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;GAGG;AACH,MAAM,MAAM,kBAAkB,CAAC,CAAC,IAAI,CAAC,OAAO,EAAE,YAAY,KAAK,OAAO,CAAC,CAAC,CAAC,CAAC;AA4E1E;;;;;;;;;;;;GAYG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAoCxD;AAED;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAY7F;AAED;;;;;;;GAOG;AACH,wBAAsB,SAAS,CAAC,CAAC,EAC/B,SAAS,EAAE,kBAAkB,CAAC,CAAC,CAAC,EAChC,OAAO,EAAE,YAAY,GACpB,OAAO,CAAC,CAAC,CAAC,CAwEZ"}