@doist/todoist-api-typescript 4.0.0-alpha.1 → 4.0.0-alpha.3

package/dist/TodoistApi.d.ts

@@ -1,75 +1,291 @@
-import { Task, Project, Label, User, Section, Comment } from './types/entities';
-import { AddCommentArgs, AddLabelArgs, AddProjectArgs, AddSectionArgs, AddTaskArgs, GetProjectCommentsArgs, GetTaskCommentsArgs, GetTasksArgs, UpdateCommentArgs, UpdateLabelArgs, UpdateProjectArgs, UpdateSectionArgs, UpdateTaskArgs, QuickAddTaskArgs, GetSharedLabelsArgs, RenameSharedLabelArgs, RemoveSharedLabelArgs, GetProjectsArgs, GetProjectCollaboratorsArgs, GetSections, GetLabelsArgs } from './types/requests';
+import { Project, Label, Section, Comment } from './types/entities';
+import type { Task } from './types/entities';
+import { AddCommentArgs, AddLabelArgs, AddProjectArgs, AddSectionArgs, AddTaskArgs, GetProjectCommentsArgs, GetTaskCommentsArgs, GetTasksArgs, UpdateCommentArgs, UpdateLabelArgs, UpdateProjectArgs, UpdateSectionArgs, UpdateTaskArgs, QuickAddTaskArgs, GetSharedLabelsArgs, RenameSharedLabelArgs, RemoveSharedLabelArgs, GetProjectsArgs, GetProjectCollaboratorsArgs, GetLabelsArgs, GetLabelsResponse, GetTasksResponse, GetProjectsResponse, GetProjectCollaboratorsResponse, GetSectionsArgs, GetSectionsResponse, GetSharedLabelsResponse, GetCommentsResponse, type MoveTaskArgs } from './types/requests';
+/**
+ * A client for interacting with the Todoist Sync API.
+ * This class provides methods to manage tasks, projects, sections, labels, and comments in Todoist.
+ *
+ * @example
+ * ```typescript
+ * const api = new TodoistApi('your-api-token');
+ *
+ * // Get all tasks
+ * const tasks = await api.getTasks();
+ *
+ * // Create a new task
+ * const newTask = await api.addTask({
+ *   content: 'My new task',
+ *   projectId: '12345'
+ * });
+ * ```
+ *
+ */
 export declare class TodoistApi {
-    authToken: string;
-    constructor(authToken: string, baseUrl?: string);
+    private authToken;
     private syncApiBase;
+    constructor(
+    /**
+     * Your Todoist API token.
+     */
+    authToken: string, 
+    /**
+     * Optional custom API base URL. If not provided, defaults to Todoist's standard API endpoint
+     */
+    baseUrl?: string);
+    /**
+     * Retrieves a single active (non-completed) task by its ID.
+     *
+     * @param id - The unique identifier of the task.
+     * @returns A promise that resolves to the requested task.
+     */
     getTask(id: string): Promise<Task>;
-    getTasks(args?: GetTasksArgs): Promise<{
-        results: Task[];
-        nextCursor: string | null;
-    }>;
+    /**
+     * Retrieves a list of active tasks filtered by specific parameters.
+     *
+     * @param args - Filter parameters such as project ID, label ID, or due date.
+     * @returns A promise that resolves to an array of tasks.
+     */
+    getTasks(args?: GetTasksArgs): Promise<GetTasksResponse>;
+    /**
+     * Creates a new task with the provided parameters.
+     *
+     * @param args - Task creation parameters such as content, due date, or priority.
+     * @param requestId - Optional unique identifier for idempotency.
+     * @returns A promise that resolves to the created task.
+     */
     addTask(args: AddTaskArgs, requestId?: string): Promise<Task>;
+    /**
+     * Quickly adds a task using natural language processing for due dates.
+     *
+     * @param args - Quick add task parameters, including content and due date.
+     * @returns A promise that resolves to the created task.
+     */
     quickAddTask(args: QuickAddTaskArgs): Promise<Task>;
+    /**
+     * Updates an existing task by its ID with the provided parameters.
+     *
+     * @param id - The unique identifier of the task to update.
+     * @param args - Update parameters such as content, priority, or due date.
+     * @param requestId - Optional unique identifier for idempotency.
+     * @returns A promise that resolves to the updated task.
+     */
     updateTask(id: string, args: UpdateTaskArgs, requestId?: string): Promise<Task>;
+    /**
+     * Moves existing tasks by their ID to either a different parent/section/project.
+     *
+     * @param ids - The unique identifier of the tasks to be moved.
+     * @param args - The paramets that should contain only one of projectId, sectionId, or parentId
+     * @param requestId - Optional unique identifier for idempotency.
+     * @returns - A promise that resolves to an array of the updated tasks.
+     */
+    moveTasks(ids: string[], args: MoveTaskArgs, requestId?: string): Promise<Task[]>;
+    /**
+     * Closes (completes) a task by its ID.
+     *
+     * @param id - The unique identifier of the task to close.
+     * @param requestId - Optional unique identifier for idempotency.
+     * @returns A promise that resolves to `true` if successful.
+     */
     closeTask(id: string, requestId?: string): Promise<boolean>;
+    /**
+     * Reopens a previously closed (completed) task by its ID.
+     *
+     * @param id - The unique identifier of the task to reopen.
+     * @param requestId - Optional unique identifier for idempotency.
+     * @returns A promise that resolves to `true` if successful.
+     */
     reopenTask(id: string, requestId?: string): Promise<boolean>;
+    /**
+     * Deletes a task by its ID.
+     *
+     * @param id - The unique identifier of the task to delete.
+     * @param requestId - Optional unique identifier for idempotency.
+     * @returns A promise that resolves to `true` if successful.
+     */
     deleteTask(id: string, requestId?: string): Promise<boolean>;
+    /**
+     * Retrieves a project by its ID.
+     *
+     * @param id - The unique identifier of the project.
+     * @returns A promise that resolves to the requested project.
+     */
     getProject(id: string): Promise<Project>;
-    getProjects(args?: GetProjectsArgs): Promise<{
-        results: Project[];
-        nextCursor: string | null;
-    }>;
+    /**
+     * Retrieves all projects with optional filters.
+     *
+     * @param args - Optional filters for retrieving projects.
+     * @returns A promise that resolves to an array of projects.
+     */
+    getProjects(args?: GetProjectsArgs): Promise<GetProjectsResponse>;
+    /**
+     * Creates a new project with the provided parameters.
+     *
+     * @param args - Project creation parameters such as name or color.
+     * @param requestId - Optional unique identifier for idempotency.
+     * @returns A promise that resolves to the created project.
+     */
     addProject(args: AddProjectArgs, requestId?: string): Promise<Project>;
+    /**
+     * Updates an existing project by its ID with the provided parameters.
+     *
+     * @param id - The unique identifier of the project to update.
+     * @param args - Update parameters such as name or color.
+     * @param requestId - Optional unique identifier for idempotency.
+     * @returns A promise that resolves to the updated project.
+     */
     updateProject(id: string, args: UpdateProjectArgs, requestId?: string): Promise<Project>;
+    /**
+     * Deletes a project by its ID.
+     *
+     * @param id - The unique identifier of the project to delete.
+     * @param requestId - Optional unique identifier for idempotency.
+     * @returns A promise that resolves to `true` if successful.
+     */
     deleteProject(id: string, requestId?: string): Promise<boolean>;
-    getProjectCollaborators(projectId: string, args?: GetProjectCollaboratorsArgs): Promise<{
-        results: User[];
-        nextCursor: string | null;
-    }>;
-    getSections(args: GetSections): Promise<{
-        results: Section[];
-        nextCursor: string | null;
-    }>;
+    /**
+     * Retrieves a list of collaborators for a specific project.
+     *
+     * @param projectId - The unique identifier of the project.
+     * @param args - Optional parameters to filter collaborators.
+     * @returns A promise that resolves to an array of collaborators for the project.
+     */
+    getProjectCollaborators(projectId: string, args?: GetProjectCollaboratorsArgs): Promise<GetProjectCollaboratorsResponse>;
+    /**
+     * Retrieves all sections within a specific project or matching criteria.
+     *
+     * @param args - Filter parameters such as project ID.
+     * @returns A promise that resolves to an array of sections.
+     */
+    getSections(args: GetSectionsArgs): Promise<GetSectionsResponse>;
+    /**
+     * Retrieves a single section by its ID.
+     *
+     * @param id - The unique identifier of the section.
+     * @returns A promise that resolves to the requested section.
+     */
     getSection(id: string): Promise<Section>;
+    /**
+     * Creates a new section within a project.
+     *
+     * @param args - Section creation parameters such as name or project ID.
+     * @param requestId - Optional unique identifier for idempotency.
+     * @returns A promise that resolves to the created section.
+     */
     addSection(args: AddSectionArgs, requestId?: string): Promise<Section>;
+    /**
+     * Updates a section by its ID with the provided parameters.
+     *
+     * @param id - The unique identifier of the section to update.
+     * @param args - Update parameters such as name or project ID.
+     * @param requestId - Optional unique identifier for idempotency.
+     * @returns A promise that resolves to the updated section.
+     */
     updateSection(id: string, args: UpdateSectionArgs, requestId?: string): Promise<Section>;
+    /**
+     * Deletes a section by its ID.
+     *
+     * @param id - The unique identifier of the section to delete.
+     * @param requestId - Optional unique identifier for idempotency.
+     * @returns A promise that resolves to `true` if successful.
+     */
     deleteSection(id: string, requestId?: string): Promise<boolean>;
     /**
-     * Fetches a personal label
+     * Retrieves a label by its ID.
+     *
+     * @param id - The unique identifier of the label.
+     * @returns A promise that resolves to the requested label.
      */
     getLabel(id: string): Promise<Label>;
     /**
-     * Fetches the personal labels
+     * Retrieves all labels.
+     *
+     * @param args - Optional filter parameters.
+     * @returns A promise that resolves to an array of labels.
      */
-    getLabels(args?: GetLabelsArgs): Promise<{
-        results: Label[];
-        nextCursor: string | null;
-    }>;
+    getLabels(args?: GetLabelsArgs): Promise<GetLabelsResponse>;
     /**
-     * Adds a personal label
+     * Adds a new label.
+     *
+     * @param args - Label creation parameters such as name.
+     * @param requestId - Optional unique identifier for idempotency.
+     * @returns A promise that resolves to the created label.
      */
     addLabel(args: AddLabelArgs, requestId?: string): Promise<Label>;
     /**
-     * Updates a personal label
+     * Updates an existing label by its ID.
+     *
+     * @param id - The unique identifier of the label to update.
+     * @param args - Update parameters such as name or color.
+     * @param requestId - Optional unique identifier for idempotency.
+     * @returns A promise that resolves to the updated label.
      */
     updateLabel(id: string, args: UpdateLabelArgs, requestId?: string): Promise<Label>;
     /**
-     * Deletes a personal label
+     * Deletes a label by its ID.
+     *
+     * @param id - The unique identifier of the label to delete.
+     * @param requestId - Optional unique identifier for idempotency.
+     * @returns A promise that resolves to `true` if successful.
      */
     deleteLabel(id: string, requestId?: string): Promise<boolean>;
-    getSharedLabels(args?: GetSharedLabelsArgs): Promise<{
-        results: string[];
-        nextCursor: string | null;
-    }>;
+    /**
+     * Retrieves a list of shared labels.
+     *
+     * @param args - Optional parameters to filter shared labels.
+     * @returns A promise that resolves to an array of shared labels.
+     */
+    getSharedLabels(args?: GetSharedLabelsArgs): Promise<GetSharedLabelsResponse>;
+    /**
+     * Renames an existing shared label.
+     *
+     * @param args - Parameters for renaming the shared label, including the current and new name.
+     * @returns A promise that resolves to `true` if successful.
+     */
     renameSharedLabel(args: RenameSharedLabelArgs): Promise<boolean>;
+    /**
+     * Removes a shared label.
+     *
+     * @param args - Parameters for removing the shared label.
+     * @returns A promise that resolves to `true` if successful.
+     */
     removeSharedLabel(args: RemoveSharedLabelArgs): Promise<boolean>;
-    getComments(args: GetTaskCommentsArgs | GetProjectCommentsArgs): Promise<{
-        results: Comment[];
-        nextCursor: string | null;
-    }>;
+    /**
+     * Retrieves all comments associated with a task or project.
+     *
+     * @param args - Parameters for retrieving comments, such as task ID or project ID.
+     * @returns A promise that resolves to an array of comments.
+     */
+    getComments(args: GetTaskCommentsArgs | GetProjectCommentsArgs): Promise<GetCommentsResponse>;
+    /**
+     * Retrieves a specific comment by its ID.
+     *
+     * @param id - The unique identifier of the comment to retrieve.
+     * @returns A promise that resolves to the requested comment.
+     */
     getComment(id: string): Promise<Comment>;
+    /**
+     * Adds a comment to a task or project.
+     *
+     * @param args - Parameters for creating the comment, such as content and the target task or project ID.
+     * @param requestId - Optional unique identifier for idempotency.
+     * @returns A promise that resolves to the created comment.
+     */
     addComment(args: AddCommentArgs, requestId?: string): Promise<Comment>;
+    /**
+     * Updates an existing comment by its ID.
+     *
+     * @param id - The unique identifier of the comment to update.
+     * @param args - Update parameters such as new content.
+     * @param requestId - Optional unique identifier for idempotency.
+     * @returns A promise that resolves to the updated comment.
+     */
     updateComment(id: string, args: UpdateCommentArgs, requestId?: string): Promise<Comment>;
+    /**
+     * Deletes a comment by its ID.
+     *
+     * @param id - The unique identifier of the comment to delete.
+     * @param requestId - Optional unique identifier for idempotency.
+     * @returns A promise that resolves to `true` if successful.
+     */
     deleteComment(id: string, requestId?: string): Promise<boolean>;
 }