Add env option for forcing IPv4.

[saul-jb]

This PR adds the config option N8N_API_FORCE_IPV4 which forces the api calls to run over IPv4.

For some ISPs/network configurations, IPv6 doesn't work reliably and node throws an error as soon as the IPv6 request fails without waiting to check if the IPv4 would succeed, so this just gives the user the option of removing IPv6 altogether if necessary.

[codecov]

Codecov Report

❌ Patch coverage is 63.63636% with 4 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
src/services/n8n-api-client.ts	55.55%	4 Missing ⚠️

📢 Thoughts on this report? Let us know!

[czlonkowski]

🔧 Changes Requested

Thanks for this useful addition! The IPv4 forcing option will help users with IPv6 connectivity issues. However, there are a few required changes before this can be merged:

🔴 Required Fix - Test Failure

The tests are failing because the new ipv4 property is missing from test configurations:

tests/unit/services/n8n-api-client.test.ts (line 32-37) needs updating:

const defaultConfig: N8nApiClientConfig = {
  baseUrl: 'https://n8n.example.com',
  apiKey: 'test-api-key',
  ipv4: false,  // ← Add this line
  timeout: 30000,
  maxRetries: 3,
};

Please check for any other test files that might need similar updates.

💡 Additional Improvements

1. Optimize agent creation - Only create agents when needed:

const httpsAgent = ipv4 ? new HttpsAgent({ family: 4 }) : undefined;
const httpAgent = ipv4 ? new HttpAgent({ family: 4 }) : undefined;

2. Add documentation - Update .env.example:

# Force IPv4 for n8n API connections (useful for IPv6 issues)
# N8N_API_FORCE_IPV4=false

3. Minor comment fix - Line 64: Change "http/s agents" to "HTTP/HTTPS agents"

4. Consider debug logging:

if (ipv4) {
  logger.debug('Forcing IPv4 for n8n API connections');
  config.httpAgent = httpAgent;
  config.httpsAgent = httpsAgent;
}

✅ What Works Well

• Clean implementation using Node.js built-in agents
• Proper Zod validation with sensible defaults
• Backward compatible
• Solves a real connectivity issue

Once the test file is updated (which will fix the CI failure), this will be ready to merge. The other suggestions are minor optimizations that would improve the feature but aren't blocking.