@doist/todoist-sdk 15.3.1 → 15.4.0

package/dist/esm/consts/endpoints.js

@@ -1,3 +1,4 @@
+import { encodePathSegment } from '../utils/request-helpers.js';
 const BASE_URI = 'https://api.todoist.com';
 const TODOIST_URI = 'https://todoist.com';
 export const TODOIST_WEB_URI = 'https://app.todoist.com/app';
@@ -94,48 +95,48 @@ export const ENDPOINT_PRICES = 'prices';
 export const ENDPOINT_PRICING = 'pricing';
 // Workspace invitation actions (require invite_code parameter)
 export function getWorkspaceInvitationAcceptEndpoint(inviteCode) {
-    return `workspaces/invitations/${inviteCode}/accept`;
+    return `workspaces/invitations/${encodePathSegment(inviteCode)}/accept`;
 }
 export function getWorkspaceInvitationRejectEndpoint(inviteCode) {
-    return `workspaces/invitations/${inviteCode}/reject`;
+    return `workspaces/invitations/${encodePathSegment(inviteCode)}/reject`;
 }
 // Insights endpoints
 export function getProjectInsightsActivityStatsEndpoint(projectId) {
-    return `projects/${projectId}/insights/activity_stats`;
+    return `projects/${encodePathSegment(projectId)}/insights/activity_stats`;
 }
 export function getProjectInsightsHealthEndpoint(projectId) {
-    return `projects/${projectId}/insights/health`;
+    return `projects/${encodePathSegment(projectId)}/insights/health`;
 }
 export function getProjectInsightsHealthContextEndpoint(projectId) {
-    return `projects/${projectId}/insights/health/context`;
+    return `projects/${encodePathSegment(projectId)}/insights/health/context`;
 }
 export function getProjectInsightsProgressEndpoint(projectId) {
-    return `projects/${projectId}/insights/progress`;
+    return `projects/${encodePathSegment(projectId)}/insights/progress`;
 }
 export function getProjectInsightsHealthAnalyzeEndpoint(projectId) {
-    return `projects/${projectId}/insights/health/analyze`;
+    return `projects/${encodePathSegment(projectId)}/insights/health/analyze`;
 }
 export function getWorkspaceInsightsEndpoint(workspaceId) {
-    return `workspaces/${workspaceId}/insights`;
+    return `workspaces/${encodePathSegment(workspaceId)}/insights`;
 }
 // Workspace members
 export const ENDPOINT_WORKSPACE_MEMBERS = 'workspaces/members';
 // Workspace user management (require workspace_id and/or user_id parameters)
 export function getWorkspaceUserTasksEndpoint(workspaceId, userId) {
-    return `workspaces/${workspaceId}/users/${userId}/tasks`;
+    return `workspaces/${encodePathSegment(workspaceId)}/users/${encodePathSegment(userId)}/tasks`;
 }
 export function getWorkspaceInviteUsersEndpoint(workspaceId) {
-    return `workspaces/${workspaceId}/users/invite`;
+    return `workspaces/${encodePathSegment(workspaceId)}/users/invite`;
 }
 export function getWorkspaceUserEndpoint(workspaceId, userId) {
-    return `workspaces/${workspaceId}/users/${userId}`;
+    return `workspaces/${encodePathSegment(workspaceId)}/users/${encodePathSegment(userId)}`;
 }
 // Workspace projects (require workspace_id parameter)
 export function getWorkspaceActiveProjectsEndpoint(workspaceId) {
-    return `workspaces/${workspaceId}/projects/active`;
+    return `workspaces/${encodePathSegment(workspaceId)}/projects/active`;
 }
 export function getWorkspaceArchivedProjectsEndpoint(workspaceId) {
-    return `workspaces/${workspaceId}/projects/archived`;
+    return `workspaces/${encodePathSegment(workspaceId)}/projects/archived`;
 }
 // App management endpoints (dev:app_console scope)
 export const ENDPOINT_REST_APPS = 'apps';
@@ -147,44 +148,45 @@ export const ENDPOINT_REST_USER_AUTHORIZATIONS_DELETE = 'user/authorizations/del
 /** Available app icon sizes (small 60x60, medium 300x300, large 600x600). */
 export const APP_ICON_SIZES = ['small', 'medium', 'large'];
 export function getAppEndpoint(appId) {
-    return `apps/${appId}`;
+    return `apps/${encodePathSegment(appId)}`;
 }
 export function getAppSecretsEndpoint(appId) {
-    return `apps/${appId}/secrets`;
+    return `apps/${encodePathSegment(appId)}/secrets`;
 }
 export function getAppClientSecretEndpoint(appId) {
-    return `apps/${appId}/client_secret`;
+    return `apps/${encodePathSegment(appId)}/client_secret`;
 }
 export function getAppTokensEndpoint(appId) {
-    return `apps/${appId}/tokens`;
+    return `apps/${encodePathSegment(appId)}/tokens`;
 }
 export function getAppTestTokenEndpoint(appId) {
-    return `apps/${appId}/test_token`;
+    return `apps/${encodePathSegment(appId)}/test_token`;
 }
 export function getAppDistributionTokenEndpoint(appId) {
-    return `apps/${appId}/distribution_token`;
+    return `apps/${encodePathSegment(appId)}/distribution_token`;
 }
 export function getAppVerificationTokenEndpoint(appId) {
-    return `apps/${appId}/verification_token`;
+    return `apps/${encodePathSegment(appId)}/verification_token`;
 }
 export function getAppWebhookEndpoint(appId) {
-    return `apps/${appId}/webhook`;
+    return `apps/${encodePathSegment(appId)}/webhook`;
 }
 export function getAppIconEndpoint(appId, size) {
-    return size === 'medium' ? `apps/${appId}/icon` : `apps/${appId}/icon/${size}`;
+    const base = `apps/${encodePathSegment(appId)}/icon`;
+    return size === 'medium' ? base : `${base}/${size}`;
 }
 export function getAppInstallationEndpoint(installationId) {
-    return `apps/installations/${installationId}`;
+    return `apps/installations/${encodePathSegment(installationId)}`;
 }
 export function getAppByDistributionTokenEndpoint(distributionToken) {
-    return `apps/by_distribution_token/${distributionToken}`;
+    return `apps/by_distribution_token/${encodePathSegment(distributionToken)}`;
 }
 export function getUiExtensionEndpoint(uiExtensionId) {
-    return `apps/ui_extensions/${uiExtensionId}`;
+    return `apps/ui_extensions/${encodePathSegment(uiExtensionId)}`;
 }
 export function getUiExtensionIconEndpoint(uiExtensionId) {
-    return `apps/ui_extensions/${uiExtensionId}/icon`;
+    return `apps/ui_extensions/${encodePathSegment(uiExtensionId)}/icon`;
 }
 export function getUiExtensionsByIntegrationEndpoint(integrationId) {
-    return `apps/ui_extensions/integration/${integrationId}`;
+    return `apps/ui_extensions/integration/${encodePathSegment(integrationId)}`;
 }

package/dist/esm/transport/http-client.js

@@ -43,6 +43,18 @@ function getTodoistRequestError(args) {
     }
     return requestError;
 }
+/**
+ * Normalises anything thrown while making an API request into the error a
+ * caller should see: a `TodoistRequestError` (carrying the HTTP status and
+ * response body when there is one) reported against `originalStack`, or a
+ * generic `Error` when the thrown value isn't an `Error` at all.
+ */
+export function toTodoistRequestError(error, originalStack) {
+    if (!(error instanceof Error)) {
+        return new Error('An unknown error occurred during the request');
+    }
+    return getTodoistRequestError({ error, originalStack });
+}
 function getRequestConfiguration(args) {
     const { baseURL, apiToken, requestId, customHeaders } = args;
     const authHeader = apiToken ? { Authorization: getAuthHeader(apiToken) } : undefined;
@@ -121,9 +133,6 @@ export async function request(args) {
         return Object.assign(Object.assign({}, response), { data: convertedData });
     }
     catch (error) {
-        if (!(error instanceof Error)) {
-            throw new Error('An unknown error occurred during the request');
-        }
-        throw getTodoistRequestError({ error, originalStack });
+        throw toTodoistRequestError(error, originalStack);
     }
 }

package/dist/esm/types/activity/types.js

@@ -1,4 +1,24 @@
 import { z } from 'zod';
+/**
+ * Known activity object types, using modern names (`task`, `comment`) rather
+ * than legacy API names (`item`, `note`).
+ */
+export const ACTIVITY_OBJECT_TYPES = ['task', 'comment', 'project'];
+/**
+ * Known activity event types.
+ */
+export const ACTIVITY_EVENT_TYPES = [
+    'added',
+    'updated',
+    'deleted',
+    'completed',
+    'uncompleted',
+    'archived',
+    'unarchived',
+    'shared',
+    'left',
+    'moved',
+];
 /**
  * Flexible object containing event-specific data.
  * Uses z.record to accept any properties for forward compatibility.

package/dist/esm/utils/multipart-upload.js

@@ -20,6 +20,7 @@ var __asyncGenerator = (this && this.__asyncGenerator) || function (thisArg, _ar
 };
 import { v4 as uuidv4 } from 'uuid';
 import { fetchWithRetry } from '../transport/fetch-with-retry.js';
+import { toTodoistRequestError } from '../transport/http-client.js';
 import { camelCaseKeys } from './case-conversion.js';
 /**
  * Helper function to determine content-type from filename extension.
@@ -170,6 +171,8 @@ function buildMultipartBody(args) {
  * @param additionalFields - Additional form fields to include (e.g., project_id, workspace_id)
  * @param requestId - Optional request ID for idempotency
  * @returns The response data from the server
+ * @throws TodoistRequestError if the upload fails, carrying the HTTP status and
+ * the server's error body like any other API request.
  *
  * @example
  * ```typescript
@@ -197,6 +200,8 @@ function buildMultipartBody(args) {
  */
 export async function uploadMultipartFile(args) {
     const { baseUrl, authToken, endpoint, file, fileName, additionalFields, requestId, customFetch, } = args;
+    // Capture original stack for better error reporting
+    const originalStack = new Error();
     // Build the full URL
     const url = `${baseUrl}${endpoint}`;
     let body;
@@ -251,7 +256,15 @@ export async function uploadMultipartFile(args) {
     headers['Content-Type'] = multipart.contentType;
     body = multipart.body;
     // Make the request using fetch
-    const response = await fetchWithRetry(Object.assign(Object.assign({ url, options: Object.assign({ method: 'POST', body,
-            headers, timeout: 30000 }, (multipart.isStreamed ? { duplex: 'half' } : {})) }, (multipart.isStreamed ? { retryConfig: { retries: 0 } } : {})), { customFetch }));
+    let response;
+    try {
+        response = await fetchWithRetry(Object.assign(Object.assign({ url, options: Object.assign({ method: 'POST', body,
+                headers, timeout: 30000 }, (multipart.isStreamed ? { duplex: 'half' } : {})) }, (multipart.isStreamed ? { retryConfig: { retries: 0 } } : {})), { customFetch }));
+    }
+    catch (error) {
+        // `fetchWithRetry` throws a plain `Error` for non-2xx responses; convert
+        // it so callers get the same error type as every other API request.
+        throw toTodoistRequestError(error, originalStack);
+    }
     return camelCaseKeys(response.data);
 }

package/dist/esm/utils/request-helpers.js

@@ -1,10 +1,36 @@
+import { TodoistArgumentError } from '../types/errors.js';
 /**
- * Joins path segments using `/` separator.
- * @param segments A list of **valid** path segments.
+ * Encodes a caller-supplied value (an ID, a name) for use as one URL path segment.
+ *
+ * Without this, a value such as `../projects/123` would be joined into the path
+ * as-is and the URL would resolve to a different endpoint. `encodeURIComponent`
+ * escapes `/`, `?`, `#` and `%`, but leaves `.` alone, so the dot segments `.`
+ * and `..` (and the empty segment) are rejected outright. `,` is kept literal,
+ * as it is a valid path character and joins lists of IDs.
+ *
+ * @param segment The value to encode.
+ * @returns The encoded segment.
+ * @throws {TodoistArgumentError} When the value is empty, `.` or `..`.
+ */
+export function encodePathSegment(segment) {
+    if (segment === '' || segment === '.' || segment === '..') {
+        throw new TodoistArgumentError(`Invalid path segment: "${segment}"`);
+    }
+    return encodeURIComponent(segment).replace(/%2C/gi, ',');
+}
+/**
+ * Joins an endpoint with path segments using `/` separator.
+ *
+ * The endpoint is used as-is (it may contain `/`); every following segment is
+ * encoded with {@link encodePathSegment}, so an ID can never address another
+ * resource.
+ *
+ * @param endpoint The base endpoint, e.g. `tasks`.
+ * @param segments Path segments to append, e.g. an ID and an action.
  * @returns A joined path.
  */
-export function generatePath(...segments) {
-    return segments.join('/');
+export function generatePath(endpoint, ...segments) {
+    return [endpoint, ...segments.map(encodePathSegment)].join('/');
 }
 /**
  * Returns `fn(value)` spread into an object if `value` is defined, otherwise an empty object.

package/dist/types/transport/http-client.d.ts

@@ -11,6 +11,13 @@ type RequestArgs = {
     customFetch?: CustomFetch;
 };
 export declare function paramsSerializer(params: Record<string, unknown>): string;
+/**
+ * Normalises anything thrown while making an API request into the error a
+ * caller should see: a `TodoistRequestError` (carrying the HTTP status and
+ * response body when there is one) reported against `originalStack`, or a
+ * generic `Error` when the thrown value isn't an `Error` at all.
+ */
+export declare function toTodoistRequestError(error: unknown, originalStack?: Error): Error;
 export declare function isSuccess(response: HttpResponse): boolean;
 export declare function request<T>(args: RequestArgs): Promise<HttpResponse<T>>;
 export {};

package/dist/types/types/activity/types.d.ts

@@ -1,13 +1,21 @@
 import { z } from 'zod';
+/**
+ * Known activity object types, using modern names (`task`, `comment`) rather
+ * than legacy API names (`item`, `note`).
+ */
+export declare const ACTIVITY_OBJECT_TYPES: readonly ["task", "comment", "project"];
+/**
+ * Known activity event types.
+ */
+export declare const ACTIVITY_EVENT_TYPES: readonly ["added", "updated", "deleted", "completed", "uncompleted", "archived", "unarchived", "shared", "left", "moved"];
 /**
  * Type hints for known object types. Accepts any string for forward compatibility.
  */
-export type ActivityObjectType = 'task' | 'comment' | 'project' | (string & Record<string, never>);
+export type ActivityObjectType = (typeof ACTIVITY_OBJECT_TYPES)[number] | (string & Record<string, never>);
 /**
  * Type hints for known event types. Accepts any string for forward compatibility.
  */
-export type ActivityEventType = 'added' | 'updated' | 'deleted' | 'completed' | 'uncompleted' | 'archived' | 'unarchived' | 'shared' | 'left' | (string & Record<string, never>);
-type ModernActivityObjectType = 'task' | 'comment' | 'project' | (string & Record<string, never>);
+export type ActivityEventType = (typeof ACTIVITY_EVENT_TYPES)[number] | (string & Record<string, never>);
 /**
  * Combined object:event filter string for the `objectEventTypes` parameter of `getActivityLogs`.
  *
@@ -21,7 +29,7 @@ type ModernActivityObjectType = 'task' | 'comment' | 'project' | (string & Recor
  * to be passed for forward compatibility, while still providing autocomplete for
  * the known combinations above.
  */
-export type ActivityObjectEventType = `${ModernActivityObjectType}:${ActivityEventType}` | `${ModernActivityObjectType}:` | `:${ActivityEventType}` | (string & Record<string, never>);
+export type ActivityObjectEventType = `${ActivityObjectType}:${ActivityEventType}` | `${ActivityObjectType}:` | `:${ActivityEventType}` | (string & Record<string, never>);
 /**
  * Flexible object containing event-specific data.
  * Uses z.record to accept any properties for forward compatibility.
@@ -46,4 +54,3 @@ export declare const ActivityEventSchema: z.ZodObject<{
  * Represents an activity log event in Todoist.
  */
 export type ActivityEvent = z.infer<typeof ActivityEventSchema>;
-export {};

package/dist/types/utils/multipart-upload.d.ts

@@ -25,6 +25,8 @@ type UploadMultipartFileArgs = {
  * @param additionalFields - Additional form fields to include (e.g., project_id, workspace_id)
  * @param requestId - Optional request ID for idempotency
  * @returns The response data from the server
+ * @throws TodoistRequestError if the upload fails, carrying the HTTP status and
+ * the server's error body like any other API request.
  *
  * @example
  * ```typescript

package/dist/types/utils/request-helpers.d.ts

@@ -1,9 +1,29 @@
 /**
- * Joins path segments using `/` separator.
- * @param segments A list of **valid** path segments.
+ * Encodes a caller-supplied value (an ID, a name) for use as one URL path segment.
+ *
+ * Without this, a value such as `../projects/123` would be joined into the path
+ * as-is and the URL would resolve to a different endpoint. `encodeURIComponent`
+ * escapes `/`, `?`, `#` and `%`, but leaves `.` alone, so the dot segments `.`
+ * and `..` (and the empty segment) are rejected outright. `,` is kept literal,
+ * as it is a valid path character and joins lists of IDs.
+ *
+ * @param segment The value to encode.
+ * @returns The encoded segment.
+ * @throws {TodoistArgumentError} When the value is empty, `.` or `..`.
+ */
+export declare function encodePathSegment(segment: string): string;
+/**
+ * Joins an endpoint with path segments using `/` separator.
+ *
+ * The endpoint is used as-is (it may contain `/`); every following segment is
+ * encoded with {@link encodePathSegment}, so an ID can never address another
+ * resource.
+ *
+ * @param endpoint The base endpoint, e.g. `tasks`.
+ * @param segments Path segments to append, e.g. an ID and an action.
  * @returns A joined path.
  */
-export declare function generatePath(...segments: string[]): string;
+export declare function generatePath(endpoint: string, ...segments: string[]): string;
 /**
  * Returns `fn(value)` spread into an object if `value` is defined, otherwise an empty object.
  *

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@doist/todoist-sdk",
-    "version": "15.3.1",
+    "version": "15.4.0",
     "description": "The official TypeScript SDK for the Todoist REST API.",
     "author": "Doist developers",
     "repository": "https://github.com/Doist/todoist-sdk-typescript",