feat: add custom HTTP client support for cross-platform compatibility

[scottlovegrove]

Summary

Adds support for custom fetch implementations to enable usage in restrictive environments like Obsidian plugins, browser extensions, Electron apps, React Native, and enterprise environments with specific networking requirements.

This PR addresses issue #381 by providing a complete custom HTTP client abstraction while maintaining 100% backward compatibility.

Key Features

• CustomFetch and CustomFetchResponse types for HTTP client abstraction
• Backward-compatible TodoistApi constructor with new options object pattern
• OAuth functions support custom fetch with consistent API design
• Complete HTTP layer integration with retry logic and error handling preserved
• File upload support with custom fetch implementations
• All existing transforms preserved (snake_case ↔ camelCase work automatically)
• Comprehensive test coverage and documentation
• Obsidian integration tests demonstrating custom fetch working with Obsidian's requestUrl API

Usage Examples

TodoistApi with Custom Fetch

// New options-based constructor
const api = new TodoistApi('TOKEN', {
    baseUrl: 'https://custom-api.example.com', // optional
    customFetch: myCustomFetch, // your custom implementation
})

// Legacy constructor (deprecated but supported)
const apiLegacy = new TodoistApi('TOKEN', 'https://custom-api.example.com')

OAuth with Custom Fetch

// New options-based usage
const { accessToken } = await getAuthToken(args, {
    baseUrl: 'https://custom-auth.example.com',
    customFetch: myCustomFetch
})

await revokeToken(args, {
    customFetch: myCustomFetch
})

// Legacy usage (deprecated)
const { accessToken } = await getAuthToken(args, baseUrl)

Custom Fetch Interface

type CustomFetch = (
    url: string,
    options?: RequestInit & { timeout?: number },
) => Promise<CustomFetchResponse>

type CustomFetchResponse = {
    ok: boolean
    status: number
    statusText: string
    headers: Record<string, string>
    text(): Promise<string>
    json(): Promise<unknown>
}

Test Coverage

• ✅ All existing tests pass (268 tests)
• ✅ New custom fetch functionality tests added
• ✅ Obsidian requestUrl integration tests - 7 test cases demonstrating custom fetch working with Obsidian's API (GET, POST, DELETE requests with various parameter types)
• ✅ TypeScript compilation (CommonJS + ESM)
• ✅ ESLint and Prettier checks
• ✅ Build process verification

Backward Compatibility

• All existing APIs continue to work without changes
• Deprecation warnings guide users to new options-based patterns
• No breaking changes to existing functionality

Cross-Platform Benefits

This enables the Todoist API client to work in:

• Obsidian plugins - Desktop app with strict CORS policies
• Browser extensions - Custom HTTP APIs with different security models
• Electron apps - Requests routed through IPC layer
• React Native - Different networking stack
• Enterprise environments - Proxy configuration, custom headers, certificate handling

Resolves #381

🤖 Generated with Claude Code