@doist/todoist-api-typescript 6.0.1 → 6.1.5

package/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.
@@ -65,15 +137,43 @@ api.getProjects()
 
 ## Releases
 
-A new version is published to the NPM Registry whenever a new release on GitHub is created.
+This project uses [Release Please](https://github.com/googleapis/release-please) to automate releases. Releases are created automatically based on [Conventional Commits](https://www.conventionalcommits.org/).
+
+### For Contributors
+
+When making changes, use conventional commit messages:
+
+-   `feat:` - New features (triggers a minor version bump)
+-   `fix:` - Bug fixes (triggers a patch version bump)
+-   `feat!:` or `BREAKING CHANGE:` - Breaking changes (triggers a major version bump)
+-   `chore:`, `docs:`, `refactor:`, `perf:` - Other changes (included in changelog)
+
+Example:
+
+```
+feat: add support for recurring tasks
+fix: resolve issue with date parsing
+feat!: remove deprecated getTask method
+```
+
+### For Maintainers
+
+The release process is fully automated:
+
+1. **Automatic PR Creation**: When commits are merged to `main`, Release Please automatically creates or updates a release PR with:
 
-The version in both package.json and package-lock.json is updated with:
+    - Updated version in `package.json`
+    - Updated `CHANGELOG.md`
+    - Aggregated changes since the last release
 
-`npm version <major|minor|patch> --no-git-tag-version`
+2. **Review and Merge**: Review the release PR to ensure the version bump and changelog are correct, then merge it.
 
-Once these changes have been pushed and merged, a release should be created, and a GitHub Action will automatically perform all the necessary steps and will release the version number that's specified inside the `package.json` file's version field.
+3. **Automatic Release**: Upon merging the release PR:
+    - A GitHub release is automatically created with the new version tag
+    - The `publish.yml` workflow is triggered by the tag
+    - The package is automatically published to NPM
 
-Users of the API client can then update to this version in their `package.json`.
+Users of the API client can then update to the new version in their `package.json`.
 
 ### Feedback
 

package/dist/cjs/authentication.js

@@ -58,81 +58,76 @@ function getAuthorizationUrl({ clientId, permissions, state, baseUrl, }) {
     const scope = permissions.join(',');
     return `${(0, endpoints_1.getAuthBaseUri)(baseUrl)}${endpoints_1.ENDPOINT_AUTHORIZATION}?client_id=${clientId}&scope=${scope}&state=${state}`;
 }
-/**
- * Exchanges an authorization code for an access token.
- *
- * @example
- * ```typescript
- * const { accessToken } = await getAuthToken({
- *   clientId: 'your-client-id',
- *   clientSecret: 'your-client-secret',
- *   code: authCode
- * })
- * ```
- *
- * @returns The access token response
- * @throws {@link TodoistRequestError} If the token exchange fails
- */
-async function getAuthToken(args, baseUrl) {
+async function getAuthToken(args, baseUrlOrOptions) {
     var _a;
-    const response = await (0, rest_client_1.request)({
-        httpMethod: 'POST',
-        baseUri: (0, endpoints_1.getAuthBaseUri)(baseUrl),
-        relativePath: endpoints_1.ENDPOINT_GET_TOKEN,
-        apiToken: undefined,
-        payload: args,
-    });
-    if (response.status !== 200 || !((_a = response.data) === null || _a === void 0 ? void 0 : _a.accessToken)) {
-        throw new types_1.TodoistRequestError('Authentication token exchange failed.', response.status, response.data);
+    let baseUrl;
+    let customFetch;
+    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 (0, rest_client_1.request)({
+            httpMethod: 'POST',
+            baseUri: (0, endpoints_1.getAuthBaseUri)(baseUrl),
+            relativePath: endpoints_1.ENDPOINT_GET_TOKEN,
+            apiToken: undefined,
+            payload: args,
+            customFetch,
+        });
+        if (response.status !== 200 || !((_a = response.data) === null || _a === void 0 ? void 0 : _a.accessToken)) {
+            throw new types_1.TodoistRequestError('Authentication token exchange failed.', response.status, response.data);
+        }
+        return response.data;
+    }
+    catch (error) {
+        // Re-throw with custom message for authentication failures
+        const err = error;
+        throw new types_1.TodoistRequestError('Authentication token exchange failed.', err.httpStatusCode, err.responseData);
     }
-    return response.data;
 }
-/**
- * Revokes an access token, making it invalid for future use.
- *
- * @example
- * ```typescript
- * await revokeAuthToken({
- *   clientId: 'your-client-id',
- *   clientSecret: 'your-client-secret',
- *   accessToken: token
- * })
- * ```
- *
- * @deprecated Use {@link revokeToken} instead. This function uses a legacy endpoint that will be removed in a future version. The new function uses the RFC 7009 compliant endpoint.
- * @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
- */
-async function revokeAuthToken(args, baseUrl) {
+async function revokeAuthToken(args, baseUrlOrOptions) {
+    let baseUrl;
+    let customFetch;
+    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 (0, rest_client_1.request)({
         httpMethod: 'POST',
         baseUri: (0, endpoints_1.getSyncBaseUri)(baseUrl),
         relativePath: endpoints_1.ENDPOINT_REVOKE_TOKEN,
         apiToken: undefined,
         payload: args,
+        customFetch,
     });
     return (0, rest_client_1.isSuccess)(response);
 }
-/**
- * Revokes a token using the RFC 7009 OAuth 2.0 Token Revocation standard.
- *
- * This function uses HTTP Basic Authentication with client credentials and follows
- * the RFC 7009 specification for token revocation.
- *
- * @example
- * ```typescript
- * await revokeToken({
- *   clientId: 'your-client-id',
- *   clientSecret: 'your-client-secret',
- *   token: 'access-token-to-revoke'
- * })
- * ```
- *
- * @returns True if revocation was successful
- * @see https://datatracker.ietf.org/doc/html/rfc7009
- * @see https://todoist.com/api/v1/docs#tag/Authorization
- */
-async function revokeToken(args, baseUrl) {
+async function revokeToken(args, baseUrlOrOptions) {
+    let baseUrl;
+    let customFetch;
+    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
     const basicAuth = createBasicAuthHeader(clientId, clientSecret);
@@ -153,6 +148,7 @@ async function revokeToken(args, baseUrl) {
         requestId: undefined,
         hasSyncCommands: false,
         customHeaders: customHeaders,
+        customFetch,
     });
     return (0, rest_client_1.isSuccess)(response);
 }

package/dist/cjs/rest-client.js

@@ -17,9 +17,14 @@ function paramsSerializer(params) {
             if (Array.isArray(value)) {
                 qs.append(key, value.join(','));
             }
-            else {
+            else if (typeof value === 'string' ||
+                typeof value === 'number' ||
+                typeof value === 'boolean') {
                 qs.append(key, String(value));
             }
+            else {
+                qs.append(key, JSON.stringify(value));
+            }
         }
     });
     return qs.toString();
@@ -63,7 +68,7 @@ function isSuccess(response) {
     return response.status >= 200 && response.status < 300;
 }
 async function request(args) {
-    const { httpMethod, baseUri, relativePath, apiToken, payload, requestId: initialRequestId, hasSyncCommands, customHeaders, } = args;
+    const { httpMethod, baseUri, relativePath, apiToken, payload, requestId: initialRequestId, hasSyncCommands, customHeaders, customFetch, } = args;
     // Capture original stack for better error reporting
     const originalStack = new Error();
     try {
@@ -94,24 +99,26 @@ async function request(args) {
                 }
                 break;
             case 'POST':
-            case 'PUT': {
+            case 'PUT':
+            case 'DELETE': {
                 // Convert payload from camelCase to snake_case
-                const convertedPayload = payload ? (0, case_conversion_1.snakeCaseKeys)(payload) : payload;
-                const body = hasSyncCommands
-                    ? JSON.stringify(convertedPayload)
-                    : JSON.stringify(convertedPayload);
-                fetchOptions.body = body;
+                // Note: While DELETE with body is uncommon, the Todoist API uses it for some endpoints
+                if (payload) {
+                    const convertedPayload = (0, case_conversion_1.snakeCaseKeys)(payload);
+                    const body = hasSyncCommands
+                        ? JSON.stringify(convertedPayload)
+                        : JSON.stringify(convertedPayload);
+                    fetchOptions.body = body;
+                }
                 break;
             }
-            case 'DELETE':
-                // DELETE requests don't have a body
-                break;
         }
         // Make the request
         const response = await (0, fetch_with_retry_1.fetchWithRetry)({
             url: finalUrl,
             options: fetchOptions,
             retryConfig: config.retry,
+            customFetch,
         });
         // Convert snake_case response to camelCase
         const convertedData = (0, case_conversion_1.camelCaseKeys)(response.data);

package/dist/cjs/test-utils/mocks.js

@@ -1,46 +1,3 @@
 "use strict";
-var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    var desc = Object.getOwnPropertyDescriptor(m, k);
-    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
-      desc = { enumerable: true, get: function() { return m[k]; } };
-    }
-    Object.defineProperty(o, k2, desc);
-}) : (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    o[k2] = m[k];
-}));
-var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
-    Object.defineProperty(o, "default", { enumerable: true, value: v });
-}) : function(o, v) {
-    o["default"] = v;
-});
-var __importStar = (this && this.__importStar) || (function () {
-    var ownKeys = function(o) {
-        ownKeys = Object.getOwnPropertyNames || function (o) {
-            var ar = [];
-            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
-            return ar;
-        };
-        return ownKeys(o);
-    };
-    return function (mod) {
-        if (mod && mod.__esModule) return mod;
-        var result = {};
-        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
-        __setModuleDefault(result, mod);
-        return result;
-    };
-})();
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.setupRestClientMock = setupRestClientMock;
-const restClient = __importStar(require("../rest-client"));
-function setupRestClientMock(responseData, status = 200) {
-    const response = {
-        status,
-        statusText: status === 200 ? 'OK' : 'Error',
-        headers: {},
-        data: responseData,
-    };
-    return jest.spyOn(restClient, 'request').mockResolvedValue(response);
-}
+// This file is reserved for future test utilities
+// All network mocking is now handled by MSW in msw-setup.ts

package/dist/cjs/test-utils/msw-setup.js

@@ -1,7 +1,43 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.HttpResponse = exports.http = exports.server = exports.handlers = void 0;
+exports.captureRequest = captureRequest;
+exports.getLastRequest = getLastRequest;
+exports.getAllRequests = getAllRequests;
+exports.clearCapturedRequests = clearCapturedRequests;
+exports.mockApiResponse = mockApiResponse;
+exports.mockApiError = mockApiError;
 const node_1 = require("msw/node");
+const msw_1 = require("msw");
+Object.defineProperty(exports, "http", { enumerable: true, get: function () { return msw_1.http; } });
+Object.defineProperty(exports, "HttpResponse", { enumerable: true, get: function () { return msw_1.HttpResponse; } });
+// Request capture storage
+const capturedRequests = [];
+// Helper function to capture requests
+function captureRequest({ request, body }) {
+    const headers = {};
+    request.headers.forEach((value, key) => {
+        headers[key] = value;
+    });
+    capturedRequests.push({
+        url: request.url,
+        method: request.method,
+        headers,
+        body,
+    });
+}
+// Helper function to get the last captured request
+function getLastRequest() {
+    return capturedRequests[capturedRequests.length - 1];
+}
+// Helper function to get all captured requests
+function getAllRequests() {
+    return [...capturedRequests];
+}
+// Helper function to clear captured requests
+function clearCapturedRequests() {
+    capturedRequests.length = 0;
+}
 // Default handlers for common API responses
 exports.handlers = [
 // Default handlers can be added here for common endpoints
@@ -9,19 +45,52 @@ exports.handlers = [
 ];
 // Create MSW server instance
 exports.server = (0, node_1.setupServer)(...exports.handlers);
+// Helper to create a resolver function for MSW handlers
+function createResolver(data, status, headers) {
+    return async function resolver({ request }) {
+        let body = undefined;
+        if (request.method !== 'GET') {
+            try {
+                body = await request.json();
+            }
+            catch (_a) {
+                // Body might not be JSON
+                try {
+                    body = await request.text();
+                }
+                catch (_b) {
+                    // Body might be FormData or not parseable
+                }
+            }
+        }
+        captureRequest({ request, body });
+        return msw_1.HttpResponse.json(data, {
+            status,
+            headers,
+        });
+    };
+}
+// Helper to mock a successful API response
+function mockApiResponse({ endpoint, data, options = {}, }) {
+    const { status = 200, method = 'GET', headers = {} } = options;
+    const resolver = createResolver(data, status, headers);
+    const httpMethod = method.toLowerCase();
+    exports.server.use(msw_1.http[httpMethod](endpoint, resolver));
+}
+// Helper to mock an error response
+function mockApiError({ endpoint, data, status, options = {}, }) {
+    mockApiResponse({ endpoint, data, options: Object.assign(Object.assign({}, options), { status }) });
+}
 // Setup MSW for tests
 beforeAll(() => {
     exports.server.listen({
-        onUnhandledRequest: 'warn', // Log warnings for unhandled requests during development
+        onUnhandledRequest: 'error', // Throw errors for unhandled requests to catch unexpected fetch calls
     });
 });
 afterEach(() => {
     exports.server.resetHandlers(); // Reset handlers between tests
+    clearCapturedRequests(); // Clear captured requests between tests
 });
 afterAll(() => {
     exports.server.close(); // Clean up after all tests
 });
-// Export MSW utilities for use in tests
-var msw_1 = require("msw");
-Object.defineProperty(exports, "http", { enumerable: true, get: function () { return msw_1.http; } });
-Object.defineProperty(exports, "HttpResponse", { enumerable: true, get: function () { return msw_1.HttpResponse; } });

package/dist/cjs/test-utils/obsidian-fetch-adapter.js

@@ -0,0 +1,53 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createObsidianFetchAdapter = createObsidianFetchAdapter;
+/**
+ * Creates a CustomFetch adapter for Obsidian's requestUrl API.
+ *
+ * This adapter bridges the gap between Obsidian's requestUrl interface and the
+ * standard fetch-like interface expected by the Todoist API SDK.
+ *
+ * Key differences handled by this adapter:
+ * - Obsidian returns response data as properties (response.json, response.text)
+ *   while the SDK expects methods (response.json(), response.text())
+ * - Obsidian's requestUrl bypasses CORS restrictions that would block standard fetch
+ * - Obsidian throws on HTTP errors by default; we set throw: false to handle manually
+ * - Obsidian doesn't provide statusText; we default to empty string
+ *
+ * @example
+ * ```typescript
+ * import { requestUrl } from 'obsidian';
+ * import { createObsidianFetchAdapter } from './obsidian-fetch-adapter';
+ *
+ * const api = new TodoistApi('your-token', {
+ *   customFetch: createObsidianFetchAdapter(requestUrl)
+ * });
+ * ```
+ *
+ * @param requestUrl - The Obsidian requestUrl function
+ * @returns A CustomFetch function compatible with the Todoist API SDK
+ */
+function createObsidianFetchAdapter(requestUrl) {
+    return async (url, options) => {
+        // Build the request parameters in Obsidian's format
+        const requestParams = {
+            url,
+            method: (options === null || options === void 0 ? void 0 : options.method) || 'GET',
+            headers: options === null || options === void 0 ? void 0 : options.headers,
+            body: options === null || options === void 0 ? void 0 : options.body,
+            throw: false, // Don't throw on HTTP errors; let the SDK handle status codes
+        };
+        // Make the request using Obsidian's requestUrl
+        const response = await requestUrl(requestParams);
+        // Transform Obsidian's response format to match CustomFetchResponse interface
+        return {
+            ok: response.status >= 200 && response.status < 300,
+            status: response.status,
+            statusText: '', // Obsidian doesn't provide statusText
+            headers: response.headers,
+            // Wrap Obsidian's direct properties as methods returning promises
+            text: () => Promise.resolve(response.text),
+            json: () => Promise.resolve(response.json),
+        };
+    };
+}