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

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.

Key features:
- CustomFetch and CustomFetchResponse types for HTTP client abstraction
- Backward-compatible TodoistApi constructor with options object pattern
- OAuth functions (getAuthToken, revokeAuthToken, revokeToken) support custom fetch
- Complete HTTP layer integration with retry logic and error handling preserved
- File upload support with custom fetch implementations
- All existing transforms (snake_case ↔ camelCase) work automatically
- Comprehensive documentation and usage examples

Resolves #381

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[email protected]>

Author: scottlovegrove

README.md

@@ -38,6 +38,78 @@ Key changes in v1 include:
 -   Object renames (e.g., items → tasks, notes → comments)
 -   URL renames and endpoint signature changes
 
+## Custom HTTP Clients
+
+The Todoist API client supports custom HTTP implementations to enable usage in environments with specific networking requirements, such as:
+
+-   **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, or certificate handling
+
+### Basic Usage
+
+```typescript
+import { TodoistApi } from '@doist/todoist-api-typescript'
+
+// Using the new options-based constructor
+const api = new TodoistApi('YOURTOKEN', {
+    baseUrl: 'https://custom-api.example.com', // optional
+    customFetch: myCustomFetch, // your custom fetch implementation
+})
+
+// Legacy constructor (deprecated but supported)
+const apiLegacy = new TodoistApi('YOURTOKEN', 'https://custom-api.example.com')
+```
+
+### Custom Fetch Interface
+
+Your custom fetch function must implement this interface:
+
+```typescript
+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>
+}
+```
+
+### OAuth with Custom Fetch
+
+OAuth authentication functions (`getAuthToken`, `revokeAuthToken`, `revokeToken`) support custom fetch through an options object:
+
+```typescript
+// 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)
+```
+
+### Important Notes
+
+-   All existing transforms (snake_case ↔ camelCase) work automatically with custom fetch
+-   Retry logic and error handling are preserved
+-   File uploads work with custom fetch implementations
+-   The custom fetch function should handle FormData for multipart uploads
+-   Timeout parameter is optional and up to your custom implementation
+
 ## Development and Testing
 
 Instead of having an example app in the repository to assist development and testing, we have included [ts-node](https://github.com/TypeStrong/ts-node) as a dev dependency. This allows us to have a scratch file locally that can import and utilize the API while developing or reviewing pull requests without having to manage a separate app project.

src/authentication.ts

@@ -1,6 +1,7 @@
 import { request, isSuccess } from './rest-client'
 import { v4 as uuid } from 'uuid'
 import { TodoistRequestError } from './types'
+import { CustomFetch } from './types/http'
 import {
     getAuthBaseUri,
     getSyncBaseUri,
@@ -10,6 +11,14 @@ import {
     ENDPOINT_REVOKE,
 } from './consts/endpoints'
 
+/**
+ * Options for authentication functions
+ */
+export type AuthOptions = {
+    baseUrl?: string
+    customFetch?: CustomFetch
+}
+
 /**
  * Permission scopes that can be requested during OAuth2 authorization.
  * @see {@link https://todoist.com/api/v1/docs#tag/Authorization}
@@ -140,17 +149,43 @@ export function getAuthorizationUrl({
  * @returns The access token response
  * @throws {@link TodoistRequestError} If the token exchange fails
  */
+// Function overloads for backward compatibility
+/**
+ * @deprecated Use options object instead: getAuthToken(args, { baseUrl, customFetch })
+ */
 export async function getAuthToken(
     args: AuthTokenRequestArgs,
     baseUrl?: string,
+): Promise<AuthTokenResponse>
+export async function getAuthToken(
+    args: AuthTokenRequestArgs,
+    options?: AuthOptions,
+): Promise<AuthTokenResponse>
+export async function getAuthToken(
+    args: AuthTokenRequestArgs,
+    baseUrlOrOptions?: string | AuthOptions,
 ): Promise<AuthTokenResponse> {
+    let baseUrl: string | undefined
+    let customFetch: CustomFetch | undefined
+
+    if (typeof baseUrlOrOptions === 'string') {
+        // Legacy signature: (args, baseUrl)
+        baseUrl = baseUrlOrOptions
+        customFetch = undefined
+    } else if (baseUrlOrOptions) {
+        // New signature: (args, options)
+        baseUrl = baseUrlOrOptions.baseUrl
+        customFetch = baseUrlOrOptions.customFetch
+    }
+
     try {
         const response = await request<AuthTokenResponse>({
             httpMethod: 'POST',
             baseUri: getAuthBaseUri(baseUrl),
             relativePath: ENDPOINT_GET_TOKEN,
             apiToken: undefined,
             payload: args,
+            customFetch,
         })
 
         if (response.status !== 200 || !response.data?.accessToken) {
@@ -189,16 +224,41 @@ export async function getAuthToken(
  * @returns True if revocation was successful
  * @see https://todoist.com/api/v1/docs#tag/Authorization/operation/revoke_access_token_api_api_v1_access_tokens_delete
  */
+// Function overloads for backward compatibility
+/**
+ * @deprecated Use options object instead: revokeAuthToken(args, { baseUrl, customFetch })
+ */
 export async function revokeAuthToken(
     args: RevokeAuthTokenRequestArgs,
     baseUrl?: string,
+): Promise<boolean>
+export async function revokeAuthToken(
+    args: RevokeAuthTokenRequestArgs,
+    options?: AuthOptions,
+): Promise<boolean>
+export async function revokeAuthToken(
+    args: RevokeAuthTokenRequestArgs,
+    baseUrlOrOptions?: string | AuthOptions,
 ): Promise<boolean> {
+    let baseUrl: string | undefined
+    let customFetch: CustomFetch | undefined
+
+    if (typeof baseUrlOrOptions === 'string') {
+        // Legacy signature: (args, baseUrl)
+        baseUrl = baseUrlOrOptions
+        customFetch = undefined
+    } else if (baseUrlOrOptions) {
+        // New signature: (args, options)
+        baseUrl = baseUrlOrOptions.baseUrl
+        customFetch = baseUrlOrOptions.customFetch
+    }
     const response = await request({
         httpMethod: 'POST',
         baseUri: getSyncBaseUri(baseUrl),
         relativePath: ENDPOINT_REVOKE_TOKEN,
         apiToken: undefined,
         payload: args,
+        customFetch,
     })
 
     return isSuccess(response)
@@ -223,10 +283,31 @@ export async function revokeAuthToken(
  * @see https://datatracker.ietf.org/doc/html/rfc7009
  * @see https://todoist.com/api/v1/docs#tag/Authorization
  */
+// Function overloads for backward compatibility
+/**
+ * @deprecated Use options object instead: revokeToken(args, { baseUrl, customFetch })
+ */
+export async function revokeToken(args: RevokeTokenRequestArgs, baseUrl?: string): Promise<boolean>
 export async function revokeToken(
     args: RevokeTokenRequestArgs,
-    baseUrl?: string,
+    options?: AuthOptions,
+): Promise<boolean>
+export async function revokeToken(
+    args: RevokeTokenRequestArgs,
+    baseUrlOrOptions?: string | AuthOptions,
 ): Promise<boolean> {
+    let baseUrl: string | undefined
+    let customFetch: CustomFetch | undefined
+
+    if (typeof baseUrlOrOptions === 'string') {
+        // Legacy signature: (args, baseUrl)
+        baseUrl = baseUrlOrOptions
+        customFetch = undefined
+    } else if (baseUrlOrOptions) {
+        // New signature: (args, options)
+        baseUrl = baseUrlOrOptions.baseUrl
+        customFetch = baseUrlOrOptions.customFetch
+    }
     const { clientId, clientSecret, token } = args
 
     // Create Basic Auth header as per RFC 7009
@@ -250,6 +331,7 @@ export async function revokeToken(
         requestId: undefined,
         hasSyncCommands: false,
         customHeaders: customHeaders,
+        customFetch,
     })
 
     return isSuccess(response)

src/custom-fetch-simple.test.ts

@@ -0,0 +1,87 @@
+import { TodoistApi } from './todoist-api'
+import { CustomFetch, CustomFetchResponse } from './types/http'
+
+// Mock fetch globally
+const mockFetch = jest.fn()
+global.fetch = mockFetch as unknown as typeof fetch
+
+const DEFAULT_AUTH_TOKEN = 'test-auth-token'
+
+describe('Custom Fetch Core Functionality', () => {
+    beforeEach(() => {
+        jest.clearAllMocks()
+    })
+
+    describe('Constructor Options', () => {
+        it('should accept customFetch in options', () => {
+            const mockCustomFetch: CustomFetch = jest.fn()
+            const api = new TodoistApi(DEFAULT_AUTH_TOKEN, {
+                customFetch: mockCustomFetch,
+            })
+            expect(api).toBeInstanceOf(TodoistApi)
+        })
+
+        it('should show deprecation warning for old constructor', () => {
+            const consoleSpy = jest.spyOn(console, 'warn').mockImplementation()
+            const api = new TodoistApi(DEFAULT_AUTH_TOKEN, 'https://custom.api.com')
+
+            expect(consoleSpy).toHaveBeenCalledWith(expect.stringContaining('deprecated'))
+            expect(api).toBeInstanceOf(TodoistApi)
+            consoleSpy.mockRestore()
+        })
+    })
+
+    describe('Custom Fetch Usage', () => {
+        it('should call custom fetch when provided', async () => {
+            const mockCustomFetch = jest.fn().mockResolvedValue({
+                ok: true,
+                status: 200,
+                statusText: 'OK',
+                headers: { 'content-type': 'application/json' },
+                text: () => Promise.resolve('{"id":"123"}'),
+                json: () => Promise.resolve({ id: '123' }),
+            } as CustomFetchResponse)
+
+            const api = new TodoistApi(DEFAULT_AUTH_TOKEN, {
+                customFetch: mockCustomFetch,
+            })
+
+            try {
+                await api.getUser()
+            } catch (error) {
+                // Expected to fail validation, but custom fetch should be called
+            }
+
+            expect(mockCustomFetch).toHaveBeenCalledWith(
+                'https://api.todoist.com/api/v1/user',
+                expect.objectContaining({
+                    method: 'GET',
+                    headers: expect.objectContaining({
+                        Authorization: `Bearer ${DEFAULT_AUTH_TOKEN}`,
+                    }),
+                }),
+            )
+        })
+
+        it('should use native fetch when no custom fetch provided', async () => {
+            mockFetch.mockResolvedValue({
+                ok: true,
+                status: 200,
+                statusText: 'OK',
+                headers: new Map([['content-type', 'application/json']]),
+                text: jest.fn().mockResolvedValue('{"id":"123"}'),
+                json: jest.fn().mockResolvedValue({ id: '123' }),
+            })
+
+            const api = new TodoistApi(DEFAULT_AUTH_TOKEN)
+
+            try {
+                await api.getUser()
+            } catch (error) {
+                // Expected to fail validation, but native fetch should be called
+            }
+
+            expect(mockFetch).toHaveBeenCalled()
+        })
+    })
+})

src/rest-client.ts

@@ -1,5 +1,5 @@
 import { TodoistRequestError } from './types/errors'
-import { HttpMethod, HttpResponse, isNetworkError, isHttpError } from './types/http'
+import { HttpMethod, HttpResponse, isNetworkError, isHttpError, CustomFetch } from './types/http'
 import { v4 as uuidv4 } from 'uuid'
 import { API_BASE_URI } from './consts/endpoints'
 import { camelCaseKeys, snakeCaseKeys } from './utils/case-conversion'
@@ -33,6 +33,7 @@ type RequestArgs = {
     requestId?: string
     hasSyncCommands?: boolean
     customHeaders?: Record<string, string>
+    customFetch?: CustomFetch
 }
 
 export function paramsSerializer(params: Record<string, unknown>) {
@@ -116,6 +117,7 @@ export async function request<T>(args: RequestArgs): Promise<HttpResponse<T>> {
         requestId: initialRequestId,
         hasSyncCommands,
         customHeaders,
+        customFetch,
     } = args
 
     // Capture original stack for better error reporting
@@ -174,6 +176,7 @@ export async function request<T>(args: RequestArgs): Promise<HttpResponse<T>> {
             url: finalUrl,
             options: fetchOptions,
             retryConfig: config.retry,
+            customFetch,
         })
 
         // Convert snake_case response to camelCase