@doist/todoist-sdk 15.1.0 → 15.3.0

package/dist/esm/utils/index.js

@@ -3,6 +3,8 @@ export * from './sanitization.js';
 export { getTaskUrl, getProjectUrl, getSectionUrl, getLabelUrl, getFilterUrl, getWorkspaceFilterUrl, getWorkspaceUrl, getTaskCommentsUrl, getProjectCommentsUrl, getTaskCommentUrl, getProjectCommentUrl, parseTodoistUrl, TODOIST_LINK_TYPES, } from './url-helpers.js';
 export { createCommand } from './sync-helpers.js';
 export * from './project-helpers.js';
+export { isDateDrivenQuery } from './filter-queries.js';
+export { FILTER_QUERY_LANGUAGES } from './filter-query-definitions.js';
 export * from './task-sorting.js';
 export * from './view-options.js';
 export { parseWebhookPayload, verifyWebhookSignature } from './webhook-parser.js';

package/dist/esm/utils/sanitization.js

@@ -110,3 +110,22 @@ export function getSanitizedContent(input) {
 export function getSanitizedTasks(tasks) {
     return tasks.map((task) => (Object.assign(Object.assign({}, task), { sanitizedContent: getSanitizedContent(task.content) })));
 }
+/**
+ * Escapes text for use as a token in a Todoist filter query.
+ *
+ * Prefixes parentheses, pipes, ampersands, exclamation marks, commas, and
+ * backslashes with a backslash. Quotes and asterisks are left unchanged.
+ * Whitespace validation and trimming are the caller's responsibility.
+ * Pass unescaped text to this function once, before inserting it into a query.
+ *
+ * @example
+ * const tasks = await api.getTasksByFilter({
+ *     query: `search: ${escapeFilterToken(searchText)}`,
+ * })
+ *
+ * @param text - The text to escape, not a complete filter query
+ * @returns The escaped text, with whitespace preserved
+ */
+export function escapeFilterToken(text) {
+    return text.replace(/[()|&!,\\]/g, '\\$&');
+}

package/dist/esm/utils/task-sorting.js

@@ -249,6 +249,8 @@ function defaultSortOrder(sortedBy) {
  *
  * This function sorts only the tasks supplied to it. Fetch every page first
  * when globally correct ordering is required for a paginated query.
+ *
+ * @see isDateDrivenQuery
  */
 export function sortTasks(tasks, options, context = {}) {
     var _a, _b, _c;

package/dist/types/utils/filter-queries.d.ts

@@ -0,0 +1,42 @@
+export type IsDateDrivenQueryOptions = {
+    /**
+     * Language the query is written in, as the account's `lang`. Unknown codes
+     * and regional variants fall back to their base language, then to English.
+     */
+    lang?: string | null;
+};
+/**
+ * Returns whether a filter query leads with dates rather than with priority.
+ *
+ * Todoist gives every filter one of two default hierarchies, and a query that
+ * mentions dates gets the date-first one. Pass the answer to {@link sortTasks}
+ * as its `defaultOrder`:
+ *
+ * ```ts
+ * sortTasks(tasks, {
+ *     sortedBy: savedOptions?.sortedBy,
+ *     sortOrder: savedOptions?.sortOrder,
+ *     defaultOrder: isDateDrivenQuery(query, { lang }) ? 'DATE_FIRST' : 'PRIORITY_FIRST',
+ * })
+ * ```
+ *
+ * The query is read in `lang`, the account language `getUser` returns, the way
+ * the API reads it. English keywords parse under every language, so `lang` only
+ * matters for a query written in the account's own: `sin fecha` is a keyword
+ * under `es` and an unreadable phrase under `en`.
+ *
+ * Commas divide a filter into subqueries and Todoist draws each one as its own
+ * list, with its own hierarchy. Classify them one at a time for exact results;
+ * a whole query answers true only when every subquery is date-driven.
+ *
+ * Two kinds of unreadable query part company here. One that breaks the grammar,
+ * such as `(today`, returns false. One that only breaks the vocabulary, such as
+ * `sin fecha` under `en`, returns true, because a word this package doesn't
+ * recognize is treated as a bare date. Pass the account's own `lang` and the
+ * question doesn't arise; get it wrong and a keyword can read as a date.
+ *
+ * The function performs no I/O.
+ *
+ * @see sortTasks
+ */
+export declare function isDateDrivenQuery(query: string, options?: IsDateDrivenQueryOptions): boolean;

package/dist/types/utils/filter-query-definitions.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Languages the Todoist filter parser reads queries in.
+ *
+ * English keywords parse under every one of them, so only a query written in
+ * the account's own language needs the matching code.
+ */
+export declare const FILTER_QUERY_LANGUAGES: readonly ["cs", "da", "de", "en", "es", "fi", "fr", "it", "ja", "ko", "nb", "nl", "pl", "pt", "ru", "sv", "tr", "zh_cn", "zh_tw"];
+/** A language the Todoist filter parser reads queries in. */
+export type FilterQueryLanguage = (typeof FILTER_QUERY_LANGUAGES)[number];
+/** Token kinds the Todoist filter lexer recognizes, in the order it tries them. */
+export declare const FILTER_QUERY_TOKENS: readonly ["LEFT", "RIGHT", "NOT", "AND", "OR", "PRIORITY", "NO_PRIORITY", "PROJECT", "SECTION", "PROJECT_SINGLE", "LABEL", "NO_LABELS", "DUE", "DUE_BEFORE", "DUE_AFTER", "DEADLINE", "DEADLINE_BEFORE", "DEADLINE_AFTER", "DATE", "DATE_BEFORE", "DATE_AFTER", "DUE_RECURRING", "OVERDUE", "WITHIN_DAYS", "NO_DUE_DATE", "NO_DEADLINE", "NO_DATE", "NO_TIME", "CREATED", "CREATED_BEFORE", "CREATED_AFTER", "ADDED_BY", "SHARED", "ASSIGNED", "TO_ME", "TO_OTHERS", "ASSIGNED_TO", "ASSIGNED_BY", "SUBTASK", "VIEW_ALL", "ALL", "SEARCH", "WORKSPACE_SINGLE", "UNCOMPLETABLE"];
+/** A token kind the Todoist filter lexer recognizes. */
+export type FilterQueryToken = (typeof FILTER_QUERY_TOKENS)[number];
+/**
+ * Tokens that make a subquery date-driven, from FilteristKt's `Grouper`.
+ *
+ * `recurring`, `no date` and `created:` are absent there too. Each says
+ * something about dates without giving the list one to lead with.
+ */
+export declare const FILTER_QUERY_DATE_TOKENS: readonly ["DUE", "DUE_BEFORE", "DUE_AFTER", "DEADLINE", "DEADLINE_BEFORE", "DEADLINE_AFTER", "DATE", "DATE_BEFORE", "DATE_AFTER", "OVERDUE", "WITHIN_DAYS"];
+/** Tokens that join or negate operands rather than standing as one. */
+export declare const FILTER_QUERY_OPERATOR_TOKENS: readonly ["LEFT", "RIGHT", "NOT", "AND", "OR"];
+/**
+ * Localized patterns per token, each one the body of `^\s*<pattern>\s*` and
+ * matched case-insensitively at the cursor.
+ */
+export declare const FILTER_QUERY_PATTERNS: Record<FilterQueryLanguage, Record<FilterQueryToken, readonly string[]>>;

package/dist/types/utils/index.d.ts

@@ -4,6 +4,10 @@ export { getTaskUrl, getProjectUrl, getSectionUrl, getLabelUrl, getFilterUrl, ge
 export type { TodoistLinkType, TodoistUrlInfo } from './url-helpers.js';
 export { createCommand } from './sync-helpers.js';
 export * from './project-helpers.js';
+export { isDateDrivenQuery } from './filter-queries.js';
+export type { IsDateDrivenQueryOptions } from './filter-queries.js';
+export { FILTER_QUERY_LANGUAGES } from './filter-query-definitions.js';
+export type { FilterQueryLanguage } from './filter-query-definitions.js';
 export * from './task-sorting.js';
 export * from './view-options.js';
 export { parseWebhookPayload, verifyWebhookSignature } from './webhook-parser.js';

package/dist/types/utils/sanitization.d.ts

@@ -33,3 +33,20 @@ export declare function getSanitizedContent(input: string): string;
  * @returns Array of tasks with added sanitizedContent property
  */
 export declare function getSanitizedTasks(tasks: Task[]): TaskWithSanitizedContent[];
+/**
+ * Escapes text for use as a token in a Todoist filter query.
+ *
+ * Prefixes parentheses, pipes, ampersands, exclamation marks, commas, and
+ * backslashes with a backslash. Quotes and asterisks are left unchanged.
+ * Whitespace validation and trimming are the caller's responsibility.
+ * Pass unescaped text to this function once, before inserting it into a query.
+ *
+ * @example
+ * const tasks = await api.getTasksByFilter({
+ *     query: `search: ${escapeFilterToken(searchText)}`,
+ * })
+ *
+ * @param text - The text to escape, not a complete filter query
+ * @returns The escaped text, with whitespace preserved
+ */
+export declare function escapeFilterToken(text: string): string;

package/dist/types/utils/task-sorting.d.ts

@@ -9,7 +9,10 @@ export type TaskSortOptions = {
     sortedBy?: SortedBy | null;
     /** Saved or requested direction. Defaults by field when absent. */
     sortOrder?: SortOrder | null;
-    /** Default hierarchy for this view or filter query. */
+    /**
+     * Default hierarchy for this view or filter query. Today and Upcoming are
+     * date-first; for a filter, {@link isDateDrivenQuery} reads it off the query.
+     */
     defaultOrder: DefaultTaskOrder;
 };
 export type TaskSortContext = {
@@ -34,5 +37,7 @@ export type TaskSortContext = {
  *
  * This function sorts only the tasks supplied to it. Fetch every page first
  * when globally correct ordering is required for a paginated query.
+ *
+ * @see isDateDrivenQuery
  */
 export declare function sortTasks(tasks: readonly Task[], options: TaskSortOptions, context?: TaskSortContext): Task[];

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@doist/todoist-sdk",
-    "version": "15.1.0",
+    "version": "15.3.0",
     "description": "The official TypeScript SDK for the Todoist REST API.",
     "author": "Doist developers",
     "repository": "https://github.com/Doist/todoist-sdk-typescript",
@@ -72,7 +72,7 @@
         "ts-node": "10.9.2",
         "type-fest": "^5.0.0",
         "typescript": "5.9.3",
-        "vitest": "4.1.0"
+        "vitest": "4.1.11"
     },
     "peerDependencies": {
         "type-fest": "^4.12.0 || ^5.5.0"