@todoist/sdk 0.0.1 → 19.0.0

package/dist/types/transport/fetch-with-retry.d.ts

@@ -0,0 +1,12 @@
+import type { CustomFetch, HttpResponse, RetryConfig } from '../types/http.js';
+/**
+ * Performs a fetch request with retry logic and timeout support
+ */
+export declare function fetchWithRetry<T = unknown>(args: {
+    url: string;
+    options?: RequestInit & {
+        timeout?: number;
+    };
+    retryConfig?: Partial<RetryConfig>;
+    customFetch?: CustomFetch;
+}): Promise<HttpResponse<T>>;

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

@@ -0,0 +1,25 @@
+import type { CustomFetch, CustomHeaders, HttpMethod, HttpResponse } from '../types/http.js';
+type RequestArgs = {
+    httpMethod: HttpMethod;
+    baseUri: string;
+    relativePath: string;
+    apiToken?: string;
+    payload?: Record<string, unknown>;
+    requestId?: string;
+    hasSyncCommands?: boolean;
+    customHeaders?: CustomHeaders;
+    customFetch?: CustomFetch;
+    /** Top-level response fields whose map keys are identifiers, left out of camel-casing. */
+    opaqueKeyMaps?: ReadonlySet<string>;
+};
+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/transport/http-dispatcher.d.ts

@@ -0,0 +1,65 @@
+import type { Dispatcher } from 'undici';
+type UndiciFetch = typeof import('undici').fetch;
+/**
+ * A dispatcher and the `fetch` that must be used with it. `fetch` is undici's
+ * own `fetch` on the full-undici Node path, or `undefined` (meaning: use the
+ * global `fetch`) on the Bun path. The two are cached together so callers can
+ * never observe a dispatcher paired with a mismatched `fetch` — see
+ * {@link getDefaultFetch} for why the pairing matters.
+ */
+export type DefaultTransport = {
+    dispatcher: Dispatcher;
+    fetch: UndiciFetch | undefined;
+};
+/**
+ * The default dispatcher and its paired `fetch`, as a single value so the two
+ * are always read consistently. Resolves to `undefined` outside Node (browser/
+ * edge), where callers use the global `fetch` with no dispatcher.
+ *
+ * Use this when supplying a `customFetch` that should still honour the proxy
+ * environment variables (`HTTP_PROXY`, `HTTPS_PROXY`, `NO_PROXY`) and decode
+ * compressed responses the way the SDK does by default.
+ *
+ * Both halves must be used together. `dispatcher` decompresses the response
+ * body itself, so a `fetch` from a different undici build will try to decode
+ * it a second time and the request fails mid-stream with `terminated`. A
+ * `fetch` of `undefined` means the runtime's global `fetch` is the correct
+ * partner for this dispatcher.
+ *
+ * @example
+ * ```ts
+ * const transport = await getDefaultTransport()
+ * const fetchImpl = transport?.fetch ?? fetch
+ * const response = await fetchImpl(url, { ...options, dispatcher: transport?.dispatcher })
+ * ```
+ */
+export declare function getDefaultTransport(): Promise<DefaultTransport | undefined>;
+/**
+ * The default dispatcher on its own.
+ *
+ * @deprecated Use {@link getDefaultTransport} instead, which returns this
+ * dispatcher together with the `fetch` it must be used with. Attaching this
+ * dispatcher to the runtime's global `fetch` decodes compressed responses
+ * twice on Node 26 and the request fails with `terminated`.
+ */
+export declare function getDefaultDispatcher(): Promise<Dispatcher | undefined>;
+/**
+ * The `fetch` implementation that must be used with the default dispatcher.
+ * Returns undici's own `fetch` on the full-undici Node path, or `undefined`
+ * (meaning: use the global `fetch`) in the browser/edge/Bun paths.
+ *
+ * Node's global `fetch` is backed by whatever undici version ships inside that
+ * Node release (6.x on Node 22 … 8.x on Node 26). Our dispatcher — and its
+ * `decompress` interceptor — comes from the npm `undici` package, which is a
+ * different version. Handing an npm-undici dispatcher to a mismatched built-in
+ * client makes gzip responses fail mid-stream with `terminated`. Sourcing
+ * `fetch` from the same npm `undici` keeps the whole request path on one
+ * version and removes the split.
+ *
+ * Only meaningful after {@link getDefaultTransport} has resolved, which is the
+ * one place that populates it.
+ */
+export declare function getDefaultFetch(): UndiciFetch | undefined;
+export declare function resetDefaultDispatcherForTests(): Promise<void>;
+export declare function suppressExperimentalWarningsSync<T>(fn: () => T): T;
+export {};

package/dist/types/transport/sync-request.d.ts

@@ -0,0 +1,31 @@
+import type { CustomFetch, CustomHeaders } from '../types/http.js';
+import { type SyncRequest, type SyncResponse } from '../types/sync/index.js';
+/**
+ * Shared context needed to issue Sync API requests.
+ *
+ * Constructed by {@link TodoistApi} and each {@link BaseClient} subclass so
+ * that sub-clients can delegate to {@link performSyncRequest} without
+ * rebuilding the HTTP identity on every call.
+ */
+export type SyncRequestContext = {
+    authToken: string;
+    syncApiBase: string;
+    customFetch?: CustomFetch;
+    customHeaders?: CustomHeaders;
+};
+/**
+ * Makes a request to the Sync API and handles error checking.
+ *
+ * @param ctx - HTTP identity (auth token, sync API base URI, optional custom fetch and headers).
+ * @param syncRequest - The sync request payload.
+ * @param options - Optional request identifier and commands flag.
+ * @returns The sync response data, with `syncStatus` keyed by command `uuid` and
+ * `tempIdMapping` keyed by command `tempId`.
+ * @throws TodoistSyncError if any command failed. Commands are applied
+ * independently, so its `syncStatus` and `tempIdMapping` report the ones that
+ * were applied regardless.
+ */
+export declare function performSyncRequest(ctx: SyncRequestContext, syncRequest: SyncRequest, options?: {
+    requestId?: string;
+    hasSyncCommands?: boolean;
+}): Promise<SyncResponse>;

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

@@ -0,0 +1,2 @@
+export * from './types.js';
+export * from './requests.js';

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

@@ -0,0 +1,85 @@
+import type { ActivityEvent, ActivityObjectEventType } from './types.js';
+/**
+ * Common arguments for retrieving activity logs (excluding filter-type params).
+ */
+type GetActivityLogsArgsCommon = {
+    /**
+     * Filter by the ID of a specific object.
+     */
+    objectId?: string;
+    /**
+     * Filter events by parent project ID.
+     */
+    parentProjectId?: string;
+    /**
+     * Filter events by parent task ID.
+     */
+    parentItemId?: string;
+    /**
+     * When true, includes the parent object data in the response.
+     */
+    includeParentObject?: boolean;
+    /**
+     * When true, includes child object data in the response.
+     */
+    includeChildObjects?: boolean;
+    /**
+     * Filter by the user ID who initiated the event.
+     */
+    initiatorId?: string;
+    /**
+     * When true, filters for events with no initiator (system-generated events).
+     * When false, filters for events with an initiator.
+     * When null or undefined, no filtering on initiator is applied.
+     */
+    initiatorIdNull?: boolean | null;
+    /**
+     * When true, ensures the last state of objects is included in the response.
+     */
+    ensureLastState?: boolean;
+    /**
+     * When true, includes comment annotations in the response.
+     */
+    annotateNotes?: boolean;
+    /**
+     * When true, includes parent object annotations in the response.
+     */
+    annotateParents?: boolean;
+    /**
+     * Pagination cursor for retrieving the next page of results.
+     */
+    cursor?: string | null;
+    /**
+     * Maximum number of results to return per page.
+     */
+    limit?: number;
+    /**
+     * Start date for filtering events (inclusive). Replaces deprecated `since`.
+     * Accepts a Date object or YYYY-MM-DD string.
+     */
+    dateFrom?: Date | string;
+    /**
+     * End date for filtering events (inclusive). Replaces deprecated `until`.
+     * Accepts a Date object or YYYY-MM-DD string.
+     */
+    dateTo?: Date | string;
+};
+export type GetActivityLogsArgs = GetActivityLogsArgsCommon & {
+    objectEventTypes?: ActivityObjectEventType | ActivityObjectEventType[];
+    /** @removed Use `objectEventTypes` instead. */
+    objectType?: never;
+    /** @removed Use `objectEventTypes` instead. */
+    eventType?: never;
+    /** @removed Use `dateFrom` instead. */
+    since?: never;
+    /** @removed Use `dateTo` instead. */
+    until?: never;
+};
+/**
+ * Response from retrieving activity logs.
+ */
+export type GetActivityLogsResponse = {
+    results: ActivityEvent[];
+    nextCursor: string | null;
+};
+export {};

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

@@ -0,0 +1,56 @@
+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 = (typeof ACTIVITY_OBJECT_TYPES)[number] | (string & Record<string, never>);
+/**
+ * Type hints for known event types. Accepts any string for forward compatibility.
+ */
+export type ActivityEventType = (typeof ACTIVITY_EVENT_TYPES)[number] | (string & Record<string, never>);
+/**
+ * Combined object:event filter string for the `objectEventTypes` parameter of `getActivityLogs`.
+ *
+ * Uses modern object type names (`task`, `comment`) rather than legacy API names (`item`, `note`).
+ * Either part may be omitted:
+ * - `'task:added'` — task additions only
+ * - `'task:'` — all events for tasks
+ * - `':deleted'` — all deleted events across all object types
+ *
+ * The final `string & Record<string, never>` member allows any arbitrary string
+ * to be passed for forward compatibility, while still providing autocomplete for
+ * the known combinations above.
+ */
+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.
+ */
+export declare const ActivityEventExtraDataSchema: z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodAny>>;
+export type ActivityEventExtraData = z.infer<typeof ActivityEventExtraDataSchema>;
+/**
+ * Activity log event schema. Accepts unknown fields for forward compatibility.
+ */
+export declare const ActivityEventSchema: z.ZodObject<{
+    objectType: z.ZodString;
+    objectId: z.ZodString;
+    eventType: z.ZodString;
+    eventDate: z.ZodCoercedDate<unknown>;
+    id: z.ZodNullable<z.ZodPipe<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>, z.ZodTransform<string, string | number>>>;
+    parentProjectId: z.ZodNullable<z.ZodString>;
+    parentItemId: z.ZodNullable<z.ZodString>;
+    initiatorId: z.ZodNullable<z.ZodString>;
+    extraData: z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodAny>>;
+}, z.core.$catchall<z.ZodAny>>;
+/**
+ * Represents an activity log event in Todoist.
+ */
+export type ActivityEvent = z.infer<typeof ActivityEventSchema>;

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

@@ -0,0 +1,2 @@
+export * from './types.js';
+export * from './requests.js';

package/dist/types/types/apps/requests.d.ts

@@ -0,0 +1,99 @@
+import type { Permission } from '../../authentication.js';
+import type { AppIconSize } from '../../consts/endpoints.js';
+import type { AppClientType, InstallationType, WebhookEvent, WebhookVersion } from './types.js';
+/**
+ * Arguments for creating a new developer application.
+ */
+export type AddAppArgs = {
+    /** Display name of the application. */
+    displayName: string;
+    /** The application's service URL. */
+    serviceUrl: string;
+};
+/**
+ * Arguments for updating a developer application.
+ * All fields are optional — only provided fields are updated.
+ *
+ * Pass `appTokenScopes` as an array (e.g. `['data:read', 'task:add']`);
+ * the SDK serializes it to the comma-separated string the backend expects.
+ */
+export type UpdateAppArgs = {
+    /** Updated display name. */
+    displayName?: string;
+    /** Updated OAuth redirect URI. Pass `null` to clear. */
+    oauthRedirectUri?: string | null;
+    /** Updated service URL. */
+    serviceUrl?: string;
+    /** Updated app description. */
+    description?: string;
+    /**
+     * Updated list of scopes the app may request. Pass `null` to clear.
+     *
+     * Typed as `Permission | (string & {})` so known scopes get autocomplete
+     * while still permitting plain strings — needed so a fetched
+     * `App['appTokenScopes']` (typed `string[] | null`) can be passed back
+     * to `updateApp()` without casts.
+     */
+    appTokenScopes?: readonly (Permission | (string & {}))[] | null;
+    /**
+     * Updated OAuth client type. Set to `'public'` for apps that cannot keep a
+     * secret (native apps, browser extensions, CLIs), so they exchange
+     * authorization codes with PKCE alone. The client secret is kept, so
+     * switching back to `'confidential'` needs no new one.
+     *
+     * Dynamically registered clients cannot change it: the API rejects the
+     * update with `BAD_REQUEST`.
+     */
+    clientType?: AppClientType;
+};
+/**
+ * Arguments for uploading an app icon.
+ */
+export type UploadAppIconArgs = {
+    /** The application ID. */
+    appId: string;
+    /** The icon file to upload (Buffer, Stream, or file path). */
+    file: Buffer | NodeJS.ReadableStream | string | Blob;
+    /** The file name (required for Buffer/Stream uploads). */
+    fileName?: string;
+    /** Icon size variant. Defaults to `'medium'`. */
+    size?: AppIconSize;
+};
+/**
+ * Arguments for configuring (creating or updating) an app webhook.
+ */
+export type UpdateAppWebhookArgs = {
+    /** The application ID. */
+    appId: string;
+    /** The URL the webhook will POST events to. */
+    callbackUrl: string;
+    /** Events the webhook should receive. Must be unique. */
+    events: readonly WebhookEvent[];
+    /** Webhook payload version. Defaults to the backend's latest supported version. */
+    version?: WebhookVersion;
+};
+/**
+ * Arguments for installing a developer application via its distribution token.
+ */
+export type InstallAppArgs = {
+    /** The distribution token for the app being installed. */
+    distributionToken: string;
+    /** Type of installation to create. */
+    installationType: InstallationType;
+    /** Whether the requesting client has validated the app's requested scopes with the user. */
+    appTokenScopesValidated?: boolean;
+};
+/**
+ * Arguments for updating an app installation.
+ */
+export type UpdateAppInstallationArgs = {
+    /** Updated validated-scopes flag. */
+    appTokenScopesValidated?: boolean;
+};
+/**
+ * Arguments for revoking a user's authorization of a third-party app.
+ */
+export type RevokeUserAuthorizationArgs = {
+    /** The ID of the access token to revoke. */
+    accessTokenId: string;
+};