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

package/dist/authentication.d.ts

@@ -1,19 +1,93 @@
+/**
+ * Permission scopes that can be requested during OAuth2 authorization.
+ * @see {@link https://developer.todoist.com/guides/#step-1-authorization-request}
+ */
 export type Permission = 'task:add' | 'data:read' | 'data:read_write' | 'data:delete' | 'project:delete';
-export type AuthTokenResponse = {
-    accessToken: string;
-    tokenType: string;
-};
+/**
+ * Parameters required to exchange an authorization code for an access token.
+ * @see https://developer.todoist.com/guides/#step-3-token-exchange
+ */
 export type AuthTokenRequestArgs = {
     clientId: string;
     clientSecret: string;
     code: string;
 };
+/**
+ * Response from a successful OAuth2 token exchange.
+ * @see https://developer.todoist.com/guides/#step-3-token-exchange
+ */
+export type AuthTokenResponse = {
+    accessToken: string;
+    tokenType: string;
+};
+/**
+ * Parameters required to revoke an access token.
+ * @see https://developer.todoist.com/rest/v2/#authorization
+ */
 export type RevokeAuthTokenRequestArgs = {
     clientId: string;
     clientSecret: string;
     accessToken: string;
 };
+/**
+ * Generates a random state parameter for OAuth2 authorization.
+ * The state parameter helps prevent CSRF attacks.
+ *
+ * @example
+ * ```typescript
+ * const state = getAuthStateParameter()
+ * // Store state in session
+ * const authUrl = getAuthorizationUrl(clientId, ['data:read'], state)
+ * ```
+ *
+ * @returns A random UUID v4 string
+ */
 export declare function getAuthStateParameter(): string;
+/**
+ * Generates the authorization URL for the OAuth2 flow.
+ *
+ * @example
+ * ```typescript
+ * const url = getAuthorizationUrl(
+ *   'your-client-id',
+ *   ['data:read', 'task:add'],
+ *   state
+ * )
+ * // Redirect user to url
+ * ```
+ *
+ * @returns The full authorization URL to redirect users to
+ * @see https://developer.todoist.com/guides/#step-1-authorization-request
+ */
 export declare function getAuthorizationUrl(clientId: string, permissions: Permission[], state: string, baseUrl?: string): string;
+/**
+ * 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
+ */
 export declare function getAuthToken(args: AuthTokenRequestArgs, baseUrl?: string): Promise<AuthTokenResponse>;
+/**
+ * Revokes an access token, making it invalid for future use.
+ *
+ * @example
+ * ```typescript
+ * await revokeAuthToken({
+ *   clientId: 'your-client-id',
+ *   clientSecret: 'your-client-secret',
+ *   accessToken: token
+ * })
+ * ```
+ *
+ * @returns True if revocation was successful
+ */
 export declare function revokeAuthToken(args: RevokeAuthTokenRequestArgs, baseUrl?: string): Promise<boolean>;

package/dist/authentication.js

@@ -41,10 +41,39 @@ var restClient_1 = require("./restClient");
 var uuid_1 = require("uuid");
 var types_1 = require("./types");
 var endpoints_1 = require("./consts/endpoints");
+/**
+ * Generates a random state parameter for OAuth2 authorization.
+ * The state parameter helps prevent CSRF attacks.
+ *
+ * @example
+ * ```typescript
+ * const state = getAuthStateParameter()
+ * // Store state in session
+ * const authUrl = getAuthorizationUrl(clientId, ['data:read'], state)
+ * ```
+ *
+ * @returns A random UUID v4 string
+ */
 function getAuthStateParameter() {
     return (0, uuid_1.v4)();
 }
 exports.getAuthStateParameter = getAuthStateParameter;
+/**
+ * Generates the authorization URL for the OAuth2 flow.
+ *
+ * @example
+ * ```typescript
+ * const url = getAuthorizationUrl(
+ *   'your-client-id',
+ *   ['data:read', 'task:add'],
+ *   state
+ * )
+ * // Redirect user to url
+ * ```
+ *
+ * @returns The full authorization URL to redirect users to
+ * @see https://developer.todoist.com/guides/#step-1-authorization-request
+ */
 function getAuthorizationUrl(clientId, permissions, state, baseUrl) {
     if (!(permissions === null || permissions === void 0 ? void 0 : permissions.length)) {
         throw new Error('At least one scope value should be passed for permissions.');
@@ -53,6 +82,21 @@ function getAuthorizationUrl(clientId, permissions, state, baseUrl) {
     return "".concat((0, endpoints_1.getAuthBaseUri)(baseUrl)).concat(endpoints_1.ENDPOINT_AUTHORIZATION, "?client_id=").concat(clientId, "&scope=").concat(scope, "&state=").concat(state);
 }
 exports.getAuthorizationUrl = getAuthorizationUrl;
+/**
+ * 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
+ */
 function getAuthToken(args, baseUrl) {
     var _a;
     return __awaiter(this, void 0, void 0, function () {
@@ -71,6 +115,20 @@ function getAuthToken(args, baseUrl) {
     });
 }
 exports.getAuthToken = getAuthToken;
+/**
+ * Revokes an access token, making it invalid for future use.
+ *
+ * @example
+ * ```typescript
+ * await revokeAuthToken({
+ *   clientId: 'your-client-id',
+ *   clientSecret: 'your-client-secret',
+ *   accessToken: token
+ * })
+ * ```
+ *
+ * @returns True if revocation was successful
+ */
 function revokeAuthToken(args, baseUrl) {
     return __awaiter(this, void 0, void 0, function () {
         var response;

package/dist/consts/endpoints.d.ts

@@ -1,5 +1,5 @@
 export declare const API_VERSION = "v9.208";
-export declare const API_BASE_URI: string;
+export declare const API_BASE_URI = "/api/v9.208/";
 export declare function getSyncBaseUri(domainBase?: string): string;
 export declare function getAuthBaseUri(domainBase?: string): string;
 export declare const ENDPOINT_REST_TASKS = "tasks";
@@ -14,6 +14,7 @@ export declare const ENDPOINT_REST_TASK_CLOSE = "close";
 export declare const ENDPOINT_REST_TASK_REOPEN = "reopen";
 export declare const ENDPOINT_REST_PROJECT_COLLABORATORS = "collaborators";
 export declare const ENDPOINT_SYNC_QUICK_ADD = "quick";
+export declare const ENDPOINT_SYNC = "sync";
 export declare const ENDPOINT_AUTHORIZATION = "authorize";
 export declare const ENDPOINT_GET_TOKEN = "access_token";
 export declare const ENDPOINT_REVOKE_TOKEN = "access_tokens/revoke";

package/dist/consts/endpoints.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ENDPOINT_REVOKE_TOKEN = exports.ENDPOINT_GET_TOKEN = exports.ENDPOINT_AUTHORIZATION = exports.ENDPOINT_SYNC_QUICK_ADD = exports.ENDPOINT_REST_PROJECT_COLLABORATORS = exports.ENDPOINT_REST_TASK_REOPEN = exports.ENDPOINT_REST_TASK_CLOSE = exports.ENDPOINT_REST_COMMENTS = exports.ENDPOINT_REST_LABELS_SHARED_REMOVE = exports.ENDPOINT_REST_LABELS_SHARED_RENAME = exports.ENDPOINT_REST_LABELS_SHARED = exports.ENDPOINT_REST_LABELS = exports.ENDPOINT_REST_SECTIONS = exports.ENDPOINT_REST_PROJECTS = exports.ENDPOINT_REST_TASKS = exports.getAuthBaseUri = exports.getSyncBaseUri = exports.API_BASE_URI = exports.API_VERSION = void 0;
+exports.ENDPOINT_REVOKE_TOKEN = exports.ENDPOINT_GET_TOKEN = exports.ENDPOINT_AUTHORIZATION = exports.ENDPOINT_SYNC = exports.ENDPOINT_SYNC_QUICK_ADD = exports.ENDPOINT_REST_PROJECT_COLLABORATORS = exports.ENDPOINT_REST_TASK_REOPEN = exports.ENDPOINT_REST_TASK_CLOSE = exports.ENDPOINT_REST_COMMENTS = exports.ENDPOINT_REST_LABELS_SHARED_REMOVE = exports.ENDPOINT_REST_LABELS_SHARED_RENAME = exports.ENDPOINT_REST_LABELS_SHARED = exports.ENDPOINT_REST_LABELS = exports.ENDPOINT_REST_SECTIONS = exports.ENDPOINT_REST_PROJECTS = exports.ENDPOINT_REST_TASKS = exports.getAuthBaseUri = exports.getSyncBaseUri = exports.API_BASE_URI = exports.API_VERSION = void 0;
 var BASE_URI = 'https://api.todoist.com';
 var TODOIST_URI = 'https://todoist.com';
 // The API version is not configurable, to ensure
@@ -30,6 +30,7 @@ exports.ENDPOINT_REST_TASK_CLOSE = 'close';
 exports.ENDPOINT_REST_TASK_REOPEN = 'reopen';
 exports.ENDPOINT_REST_PROJECT_COLLABORATORS = 'collaborators';
 exports.ENDPOINT_SYNC_QUICK_ADD = 'quick';
+exports.ENDPOINT_SYNC = 'sync';
 exports.ENDPOINT_AUTHORIZATION = 'authorize';
 exports.ENDPOINT_GET_TOKEN = 'access_token';
 exports.ENDPOINT_REVOKE_TOKEN = 'access_tokens/revoke';

package/dist/index.d.ts

@@ -1,5 +1,4 @@
 export * from './TodoistApi';
-export * from './restClient';
 export * from './authentication';
 export * from './types';
 export * from './utils';

package/dist/index.js

@@ -15,7 +15,6 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./TodoistApi"), exports);
-__exportStar(require("./restClient"), exports);
 __exportStar(require("./authentication"), exports);
 __exportStar(require("./types"), exports);
 __exportStar(require("./utils"), exports);

package/dist/restClient.d.ts

@@ -2,4 +2,4 @@ import { AxiosResponse } from 'axios';
 import { HttpMethod } from './types/http';
 export declare function paramsSerializer(params: Record<string, unknown>): string;
 export declare function isSuccess(response: AxiosResponse): boolean;
-export declare function request<T>(httpMethod: HttpMethod, baseUri: string, relativePath: string, apiToken?: string, payload?: Record<string, unknown>, requestId?: string): Promise<AxiosResponse<T>>;
+export declare function request<T>(httpMethod: HttpMethod, baseUri: string, relativePath: string, apiToken?: string, payload?: Record<string, unknown>, requestId?: string, hasSyncCommands?: boolean): Promise<AxiosResponse<T>>;

package/dist/restClient.js

@@ -116,7 +116,7 @@ function isSuccess(response) {
     return response.status >= 200 && response.status < 300;
 }
 exports.isSuccess = isSuccess;
-function request(httpMethod, baseUri, relativePath, apiToken, payload, requestId) {
+function request(httpMethod, baseUri, relativePath, apiToken, payload, requestId, hasSyncCommands) {
     return __awaiter(this, void 0, void 0, function () {
         var originalStack, axiosClient, _a, error_1;
         return __generator(this, function (_b) {
@@ -145,7 +145,7 @@ function request(httpMethod, baseUri, relativePath, apiToken, payload, requestId
                         },
                     })];
                 case 3: return [2 /*return*/, _b.sent()];
-                case 4: return [4 /*yield*/, axiosClient.post(relativePath, payload)];
+                case 4: return [4 /*yield*/, axiosClient.post(relativePath, hasSyncCommands ? JSON.stringify(payload) : payload)];
                 case 5: return [2 /*return*/, _b.sent()];
                 case 6: return [4 /*yield*/, axiosClient.delete(relativePath)];
                 case 7: return [2 /*return*/, _b.sent()];

package/dist/testUtils/asserts.d.ts

@@ -1,2 +1 @@
 export declare function assertInstance<T extends new (...args: any) => any>(value: unknown, type: T): asserts value is InstanceType<T>;
-export declare function assertInputValidationError(apiCall: () => Promise<unknown>): Promise<void>;

package/dist/testUtils/asserts.js

@@ -1,44 +1,6 @@
 "use strict";
-var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
-    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
-    return new (P || (P = Promise))(function (resolve, reject) {
-        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
-        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
-        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
-        step((generator = generator.apply(thisArg, _arguments || [])).next());
-    });
-};
-var __generator = (this && this.__generator) || function (thisArg, body) {
-    var _ = { label: 0, sent: function() { if (t[0] & 1) throw t[1]; return t[1]; }, trys: [], ops: [] }, f, y, t, g;
-    return g = { next: verb(0), "throw": verb(1), "return": verb(2) }, typeof Symbol === "function" && (g[Symbol.iterator] = function() { return this; }), g;
-    function verb(n) { return function (v) { return step([n, v]); }; }
-    function step(op) {
-        if (f) throw new TypeError("Generator is already executing.");
-        while (g && (g = 0, op[0] && (_ = 0)), _) try {
-            if (f = 1, y && (t = op[0] & 2 ? y["return"] : op[0] ? y["throw"] || ((t = y["return"]) && t.call(y), 0) : y.next) && !(t = t.call(y, op[1])).done) return t;
-            if (y = 0, t) op = [op[0] & 2, t.value];
-            switch (op[0]) {
-                case 0: case 1: t = op; break;
-                case 4: _.label++; return { value: op[1], done: false };
-                case 5: _.label++; y = op[1]; op = [0]; continue;
-                case 7: op = _.ops.pop(); _.trys.pop(); continue;
-                default:
-                    if (!(t = _.trys, t = t.length > 0 && t[t.length - 1]) && (op[0] === 6 || op[0] === 2)) { _ = 0; continue; }
-                    if (op[0] === 3 && (!t || (op[1] > t[0] && op[1] < t[3]))) { _.label = op[1]; break; }
-                    if (op[0] === 6 && _.label < t[1]) { _.label = t[1]; t = op; break; }
-                    if (t && _.label < t[2]) { _.label = t[2]; _.ops.push(op); break; }
-                    if (t[2]) _.ops.pop();
-                    _.trys.pop(); continue;
-            }
-            op = body.call(thisArg, _);
-        } catch (e) { op = [6, e]; y = 0; } finally { f = t = 0; }
-        if (op[0] & 5) throw op[1]; return { value: op[0] ? op[1] : void 0, done: true };
-    }
-};
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.assertInputValidationError = exports.assertInstance = void 0;
-var mocks_1 = require("./mocks");
-var runtypes_1 = require("runtypes");
+exports.assertInstance = void 0;
 // Has to use 'any' to express constructor type
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 function assertInstance(value, type) {
@@ -48,29 +10,3 @@ function assertInstance(value, type) {
     throw new TypeError("Unexpected type ".concat(typeof value));
 }
 exports.assertInstance = assertInstance;
-function assertInputValidationError(apiCall) {
-    return __awaiter(this, void 0, void 0, function () {
-        var requestMock, e_1;
-        return __generator(this, function (_a) {
-            switch (_a.label) {
-                case 0:
-                    requestMock = (0, mocks_1.setupRestClientMock)(undefined);
-                    expect.assertions(1);
-                    _a.label = 1;
-                case 1:
-                    _a.trys.push([1, 3, , 4]);
-                    return [4 /*yield*/, apiCall()];
-                case 2:
-                    _a.sent();
-                    return [3 /*break*/, 4];
-                case 3:
-                    e_1 = _a.sent();
-                    assertInstance(e_1, runtypes_1.ValidationError);
-                    expect(requestMock).not.toBeCalled();
-                    return [3 /*break*/, 4];
-                case 4: return [2 /*return*/];
-            }
-        });
-    });
-}
-exports.assertInputValidationError = assertInputValidationError;

package/dist/testUtils/testDefaults.d.ts

@@ -82,6 +82,7 @@ export declare const DEFAULT_ATTACHMENT: Attachment;
 export declare const INVALID_ATTACHMENT: {
     uploadState: string;
     resourceType: string;
+    url?: string | null | undefined;
     fileName?: string | null | undefined;
     fileSize?: number | null | undefined;
     fileType?: string | null | undefined;
@@ -90,7 +91,6 @@ export declare const INVALID_ATTACHMENT: {
     image?: string | null | undefined;
     imageWidth?: number | null | undefined;
     imageHeight?: number | null | undefined;
-    url?: string | null | undefined;
     title?: string | null | undefined;
 };
 export declare const DEFAULT_COMMENT: Comment;
@@ -98,6 +98,7 @@ export declare const INVALID_COMMENT: {
     attachment: {
         uploadState: string;
         resourceType: string;
+        url?: string | null | undefined;
         fileName?: string | null | undefined;
         fileSize?: number | null | undefined;
         fileType?: string | null | undefined;
@@ -106,7 +107,6 @@ export declare const INVALID_COMMENT: {
         image?: string | null | undefined;
         imageWidth?: number | null | undefined;
         imageHeight?: number | null | undefined;
-        url?: string | null | undefined;
         title?: string | null | undefined;
     };
     id: string;