feat: add custom HTTP client support for cross-platform compatibility (#383)

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.