@doist/todoist-sdk 9.0.0 → 9.1.0

package/dist/types/types/ui-extensions/requests.d.ts

@@ -0,0 +1,108 @@
+import type { ComposerExtensionContext, ContextMenuExtensionContext, UiExtensionType } from './types.js';
+import { UiExtensionTypeEnum } from './types.js';
+/**
+ * Fields common to every UI extension variant — shared across all add/update
+ * request shapes.
+ */
+type BaseUiExtensionFields = {
+    /** HTTPS URL the extension loads. */
+    url: string;
+    /** Extension display name. */
+    name: string;
+    /** Extension description. */
+    description: string;
+    /** Rendered width in pixels. */
+    width?: number | null;
+    /** Rendered height in pixels. */
+    height?: number | null;
+    /** Optional HTTPS URL for the extension icon. */
+    icon?: string | null;
+    /** Extension definition version. Defaults to the backend default. */
+    defVersion?: number;
+    /** Minimum Cardist renderer version required, as a decimal version string (e.g. `'0.60'`). */
+    minimumCardistVersion?: string;
+    /** Optional client-specified extension ID (server generates one if omitted). */
+    extensionId?: string | null;
+};
+/** Arguments for adding a context-menu UI extension. */
+export type AddContextMenuExtensionArgs = BaseUiExtensionFields & {
+    /** The developer application (integration) ID the extension belongs to. */
+    integrationId: string;
+    extensionType: typeof UiExtensionTypeEnum.ContextMenu;
+    /** Where the extension appears. */
+    contextType: ContextMenuExtensionContext;
+};
+/** Arguments for adding a composer UI extension. */
+export type AddComposerExtensionArgs = BaseUiExtensionFields & {
+    /** The developer application (integration) ID the extension belongs to. */
+    integrationId: string;
+    extensionType: typeof UiExtensionTypeEnum.Composer;
+    /** Which composer the extension appears in. */
+    composerType: ComposerExtensionContext;
+};
+/** Arguments for adding a settings UI extension. */
+export type AddSettingsExtensionArgs = BaseUiExtensionFields & {
+    /** The developer application (integration) ID the extension belongs to. */
+    integrationId: string;
+    extensionType: typeof UiExtensionTypeEnum.Settings;
+};
+/**
+ * Arguments for adding a new UI extension to a developer application.
+ * Discriminated on `extensionType` so impossible combinations
+ * (e.g. `settings` + `contextType`) fail at compile time.
+ */
+export type AddUiExtensionArgs = AddContextMenuExtensionArgs | AddComposerExtensionArgs | AddSettingsExtensionArgs;
+/**
+ * Fields that are optional on every update variant.
+ */
+type UpdateUiExtensionFields = {
+    url?: string;
+    name?: string;
+    description?: string;
+    width?: number | null;
+    height?: number | null;
+    icon?: string | null;
+    defVersion?: number;
+    minimumCardistVersion?: string;
+    extensionId?: string | null;
+};
+/**
+ * Arguments for updating a context-menu UI extension.
+ * `extensionType` is required to discriminate the variant — callers
+ * already have it from the fetched `UiExtension`.
+ */
+export type UpdateContextMenuExtensionArgs = UpdateUiExtensionFields & {
+    extensionType: typeof UiExtensionTypeEnum.ContextMenu;
+    contextType?: ContextMenuExtensionContext;
+};
+/**
+ * Arguments for updating a composer UI extension.
+ */
+export type UpdateComposerExtensionArgs = UpdateUiExtensionFields & {
+    extensionType: typeof UiExtensionTypeEnum.Composer;
+    composerType?: ComposerExtensionContext;
+};
+/**
+ * Arguments for updating a settings UI extension.
+ */
+export type UpdateSettingsExtensionArgs = UpdateUiExtensionFields & {
+    extensionType: typeof UiExtensionTypeEnum.Settings;
+};
+/**
+ * Arguments for updating a UI extension — all value fields are optional
+ * but `extensionType` is required so TypeScript can discriminate which
+ * variant-specific fields (`contextType`, `composerType`) apply.
+ */
+export type UpdateUiExtensionArgs = UpdateContextMenuExtensionArgs | UpdateComposerExtensionArgs | UpdateSettingsExtensionArgs;
+export type { UiExtensionType };
+/**
+ * Arguments for uploading a UI extension icon.
+ */
+export type UploadUiExtensionIconArgs = {
+    /** The UI extension ID. */
+    uiExtensionId: 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;
+};

package/dist/types/types/ui-extensions/types.d.ts

@@ -0,0 +1,185 @@
+import { z } from 'zod';
+/**
+ * Discriminator values for the UI extension variants.
+ * Exposed as an enum-like object because the values are used in `z.literal()`
+ * across multiple variant schemas (see AGENTS.md "Discriminated unions" exception).
+ */
+export declare const UiExtensionTypeEnum: {
+    readonly ContextMenu: "context-menu";
+    readonly Composer: "composer";
+    readonly Settings: "settings";
+};
+/**
+ * All UI extension type values.
+ */
+export declare const UI_EXTENSION_TYPES: readonly ["context-menu", "composer", "settings"];
+/**
+ * Type of UI extension.
+ */
+export type UiExtensionType = (typeof UI_EXTENSION_TYPES)[number];
+/**
+ * Context locations where a context-menu extension can appear.
+ */
+export declare const CONTEXT_MENU_EXTENSION_CONTEXTS: readonly ["project", "task"];
+/**
+ * Context location of a context-menu UI extension.
+ */
+export type ContextMenuExtensionContext = (typeof CONTEXT_MENU_EXTENSION_CONTEXTS)[number];
+export declare const ContextMenuExtensionContextSchema: z.ZodEnum<{
+    task: "task";
+    project: "project";
+}>;
+/**
+ * Composer locations where a composer extension can appear.
+ */
+export declare const COMPOSER_EXTENSION_CONTEXTS: readonly ["task", "comment"];
+/**
+ * Composer location of a composer UI extension.
+ */
+export type ComposerExtensionContext = (typeof COMPOSER_EXTENSION_CONTEXTS)[number];
+export declare const ComposerExtensionContextSchema: z.ZodEnum<{
+    task: "task";
+    comment: "comment";
+}>;
+/**
+ * Shared fields across all UI extension variants.
+ */
+export declare const UiExtensionBaseSchema: z.ZodObject<{
+    id: z.ZodPipe<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>, z.ZodTransform<string, string | number>>;
+    integrationId: z.ZodPipe<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>, z.ZodTransform<string, string | number>>;
+    extensionId: z.ZodString;
+    url: z.ZodString;
+    icon: z.ZodNullable<z.ZodString>;
+    name: z.ZodString;
+    description: z.ZodString;
+    width: z.ZodNullable<z.ZodNumber>;
+    height: z.ZodNullable<z.ZodNumber>;
+    defVersion: z.ZodNumber;
+    minimumCardistVersion: z.ZodString;
+}, z.core.$strip>;
+/**
+ * Schema for a context-menu UI extension.
+ */
+export declare const ContextMenuExtensionSchema: z.ZodObject<{
+    id: z.ZodPipe<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>, z.ZodTransform<string, string | number>>;
+    integrationId: z.ZodPipe<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>, z.ZodTransform<string, string | number>>;
+    extensionId: z.ZodString;
+    url: z.ZodString;
+    icon: z.ZodNullable<z.ZodString>;
+    name: z.ZodString;
+    description: z.ZodString;
+    width: z.ZodNullable<z.ZodNumber>;
+    height: z.ZodNullable<z.ZodNumber>;
+    defVersion: z.ZodNumber;
+    minimumCardistVersion: z.ZodString;
+    extensionType: z.ZodLiteral<"context-menu">;
+    contextType: z.ZodEnum<{
+        task: "task";
+        project: "project";
+    }>;
+}, z.core.$strip>;
+/**
+ * A context-menu UI extension.
+ */
+export type ContextMenuExtension = z.infer<typeof ContextMenuExtensionSchema>;
+/**
+ * Schema for a composer UI extension.
+ */
+export declare const ComposerExtensionSchema: z.ZodObject<{
+    id: z.ZodPipe<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>, z.ZodTransform<string, string | number>>;
+    integrationId: z.ZodPipe<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>, z.ZodTransform<string, string | number>>;
+    extensionId: z.ZodString;
+    url: z.ZodString;
+    icon: z.ZodNullable<z.ZodString>;
+    name: z.ZodString;
+    description: z.ZodString;
+    width: z.ZodNullable<z.ZodNumber>;
+    height: z.ZodNullable<z.ZodNumber>;
+    defVersion: z.ZodNumber;
+    minimumCardistVersion: z.ZodString;
+    extensionType: z.ZodLiteral<"composer">;
+    composerType: z.ZodEnum<{
+        task: "task";
+        comment: "comment";
+    }>;
+}, z.core.$strip>;
+/**
+ * A composer UI extension.
+ */
+export type ComposerExtension = z.infer<typeof ComposerExtensionSchema>;
+/**
+ * Schema for a settings UI extension.
+ */
+export declare const SettingsExtensionSchema: z.ZodObject<{
+    id: z.ZodPipe<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>, z.ZodTransform<string, string | number>>;
+    integrationId: z.ZodPipe<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>, z.ZodTransform<string, string | number>>;
+    extensionId: z.ZodString;
+    url: z.ZodString;
+    icon: z.ZodNullable<z.ZodString>;
+    name: z.ZodString;
+    description: z.ZodString;
+    width: z.ZodNullable<z.ZodNumber>;
+    height: z.ZodNullable<z.ZodNumber>;
+    defVersion: z.ZodNumber;
+    minimumCardistVersion: z.ZodString;
+    extensionType: z.ZodLiteral<"settings">;
+}, z.core.$strip>;
+/**
+ * A settings UI extension.
+ */
+export type SettingsExtension = z.infer<typeof SettingsExtensionSchema>;
+/**
+ * Discriminated union of all UI extension variants.
+ */
+export declare const UiExtensionSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    id: z.ZodPipe<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>, z.ZodTransform<string, string | number>>;
+    integrationId: z.ZodPipe<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>, z.ZodTransform<string, string | number>>;
+    extensionId: z.ZodString;
+    url: z.ZodString;
+    icon: z.ZodNullable<z.ZodString>;
+    name: z.ZodString;
+    description: z.ZodString;
+    width: z.ZodNullable<z.ZodNumber>;
+    height: z.ZodNullable<z.ZodNumber>;
+    defVersion: z.ZodNumber;
+    minimumCardistVersion: z.ZodString;
+    extensionType: z.ZodLiteral<"context-menu">;
+    contextType: z.ZodEnum<{
+        task: "task";
+        project: "project";
+    }>;
+}, z.core.$strip>, z.ZodObject<{
+    id: z.ZodPipe<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>, z.ZodTransform<string, string | number>>;
+    integrationId: z.ZodPipe<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>, z.ZodTransform<string, string | number>>;
+    extensionId: z.ZodString;
+    url: z.ZodString;
+    icon: z.ZodNullable<z.ZodString>;
+    name: z.ZodString;
+    description: z.ZodString;
+    width: z.ZodNullable<z.ZodNumber>;
+    height: z.ZodNullable<z.ZodNumber>;
+    defVersion: z.ZodNumber;
+    minimumCardistVersion: z.ZodString;
+    extensionType: z.ZodLiteral<"composer">;
+    composerType: z.ZodEnum<{
+        task: "task";
+        comment: "comment";
+    }>;
+}, z.core.$strip>, z.ZodObject<{
+    id: z.ZodPipe<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>, z.ZodTransform<string, string | number>>;
+    integrationId: z.ZodPipe<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>, z.ZodTransform<string, string | number>>;
+    extensionId: z.ZodString;
+    url: z.ZodString;
+    icon: z.ZodNullable<z.ZodString>;
+    name: z.ZodString;
+    description: z.ZodString;
+    width: z.ZodNullable<z.ZodNumber>;
+    height: z.ZodNullable<z.ZodNumber>;
+    defVersion: z.ZodNumber;
+    minimumCardistVersion: z.ZodString;
+    extensionType: z.ZodLiteral<"settings">;
+}, z.core.$strip>], "extensionType">;
+/**
+ * A UI extension attached to a developer application.
+ */
+export type UiExtension = z.infer<typeof UiExtensionSchema>;

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

@@ -0,0 +1,7 @@
+/**
+ * Converts a native Fetch `Headers` object into a plain `Record<string, string>`.
+ * Used when wrapping a native `fetch` response into the SDK's `FileResponse`
+ * shape (which expects headers as a plain record for symmetry with
+ * `CustomFetchResponse`).
+ */
+export declare function headersToRecord(headers: Headers): Record<string, string>;

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

@@ -0,0 +1,13 @@
+/**
+ * Joins path segments using `/` separator.
+ * @param segments A list of **valid** path segments.
+ * @returns A joined path.
+ */
+export declare function generatePath(...segments: string[]): string;
+/**
+ * Returns `fn(value)` spread into an object if `value` is defined, otherwise an empty object.
+ *
+ * Used to conditionally include a property on a payload object without
+ * resorting to mutation or ternary-built object literals.
+ */
+export declare function spreadIfDefined<T, V extends Record<string, unknown>>(value: T | undefined, fn: (v: T) => V): V | Record<string, never>;

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

@@ -1520,3 +1520,226 @@ export declare const validateSuggestion: (input: unknown) => {
     isDeleted: boolean;
 })[];
 export declare function parseSyncResponse(raw: Record<string, unknown>): SyncResponse;
+export declare const validateApp: (input: unknown) => {
+    id: string;
+    status: "public";
+    displayName: string;
+    userId: string;
+    createdAt: Date;
+    serviceUrl: string | null;
+    oauthRedirectUri: string | null;
+    description: string | null;
+    iconSm: string | null;
+    iconMd: string | null;
+    iconLg: string | null;
+    appTokenScopes: string[] | null;
+}, validateAppArray: (input: unknown) => {
+    id: string;
+    status: "public";
+    displayName: string;
+    userId: string;
+    createdAt: Date;
+    serviceUrl: string | null;
+    oauthRedirectUri: string | null;
+    description: string | null;
+    iconSm: string | null;
+    iconMd: string | null;
+    iconLg: string | null;
+    appTokenScopes: string[] | null;
+}[];
+export declare const validateAppWithUserCount: (input: unknown) => {
+    id: string;
+    status: "public";
+    displayName: string;
+    userId: string;
+    createdAt: Date;
+    serviceUrl: string | null;
+    oauthRedirectUri: string | null;
+    description: string | null;
+    iconSm: string | null;
+    iconMd: string | null;
+    iconLg: string | null;
+    appTokenScopes: string[] | null;
+    userCount: number;
+};
+export declare const validateAppSecrets: (input: unknown) => {
+    clientId: string;
+    clientSecret: string;
+};
+export declare const validateAppVerificationToken: (input: unknown) => {
+    verificationToken: string;
+};
+export declare const validateAppTestToken: (input: unknown) => {
+    accessToken?: string | null | undefined;
+};
+export declare const validateAppDistributionToken: (input: unknown) => {
+    distributionToken: string;
+};
+export declare const validateAppByDistributionToken: (input: unknown) => {
+    id: string;
+    displayName: string;
+    description: string | null;
+    iconMd: string | null;
+    appTokenScopes: string[] | null;
+    uiExtensions: {
+        name: string;
+        description: string;
+        icon: string | null;
+        extensionType: "context-menu" | "composer" | "settings";
+    }[];
+};
+export declare const validateAppWebhook: (input: unknown) => {
+    status: "active" | "invalid";
+    callbackUrl: string;
+    version: "1";
+    events: ("project:added" | "project:updated" | "project:deleted" | "project:archived" | "project:unarchived" | "item:added" | "item:updated" | "item:completed" | "item:uncompleted" | "item:deleted" | "note:added" | "note:updated" | "note:deleted" | "section:added" | "section:updated" | "section:deleted" | "section:archived" | "section:unarchived" | "label:added" | "label:updated" | "label:deleted" | "filter:added" | "filter:updated" | "filter:deleted" | "reminder:fired")[];
+};
+export declare const validateAppInstallation: (input: unknown) => {
+    id: string;
+    creator: string;
+    createdTs: number;
+    installationType: "user";
+    appTokenScopesValidated: boolean;
+    integration: {
+        id: string;
+        status: "public";
+        displayName: string;
+        userId: string;
+        createdAt: Date;
+        serviceUrl: string | null;
+        oauthRedirectUri: string | null;
+        description: string | null;
+        iconSm: string | null;
+        iconMd: string | null;
+        iconLg: string | null;
+        appTokenScopes: string[] | null;
+    } | null;
+}, validateAppInstallationArray: (input: unknown) => {
+    id: string;
+    creator: string;
+    createdTs: number;
+    installationType: "user";
+    appTokenScopesValidated: boolean;
+    integration: {
+        id: string;
+        status: "public";
+        displayName: string;
+        userId: string;
+        createdAt: Date;
+        serviceUrl: string | null;
+        oauthRedirectUri: string | null;
+        description: string | null;
+        iconSm: string | null;
+        iconMd: string | null;
+        iconLg: string | null;
+        appTokenScopes: string[] | null;
+    } | null;
+}[];
+export declare const validateUserAuthorization: (input: unknown) => {
+    accessTokenId: string;
+    scope: string[];
+    scopeDescriptions: string[];
+    createdAt: Date;
+    app: {
+        id: string;
+        displayName: string;
+        description: string | null;
+        serviceUrl: string | null;
+        iconMd: string | null;
+    } | null;
+}, validateUserAuthorizationArray: (input: unknown) => {
+    accessTokenId: string;
+    scope: string[];
+    scopeDescriptions: string[];
+    createdAt: Date;
+    app: {
+        id: string;
+        displayName: string;
+        description: string | null;
+        serviceUrl: string | null;
+        iconMd: string | null;
+    } | null;
+}[];
+export declare const validateUiExtension: (input: unknown) => {
+    id: string;
+    integrationId: string;
+    extensionId: string;
+    url: string;
+    icon: string | null;
+    name: string;
+    description: string;
+    width: number | null;
+    height: number | null;
+    defVersion: number;
+    minimumCardistVersion: string;
+    extensionType: "context-menu";
+    contextType: "task" | "project";
+} | {
+    id: string;
+    integrationId: string;
+    extensionId: string;
+    url: string;
+    icon: string | null;
+    name: string;
+    description: string;
+    width: number | null;
+    height: number | null;
+    defVersion: number;
+    minimumCardistVersion: string;
+    extensionType: "composer";
+    composerType: "task" | "comment";
+} | {
+    id: string;
+    integrationId: string;
+    extensionId: string;
+    url: string;
+    icon: string | null;
+    name: string;
+    description: string;
+    width: number | null;
+    height: number | null;
+    defVersion: number;
+    minimumCardistVersion: string;
+    extensionType: "settings";
+}, validateUiExtensionArray: (input: unknown) => ({
+    id: string;
+    integrationId: string;
+    extensionId: string;
+    url: string;
+    icon: string | null;
+    name: string;
+    description: string;
+    width: number | null;
+    height: number | null;
+    defVersion: number;
+    minimumCardistVersion: string;
+    extensionType: "context-menu";
+    contextType: "task" | "project";
+} | {
+    id: string;
+    integrationId: string;
+    extensionId: string;
+    url: string;
+    icon: string | null;
+    name: string;
+    description: string;
+    width: number | null;
+    height: number | null;
+    defVersion: number;
+    minimumCardistVersion: string;
+    extensionType: "composer";
+    composerType: "task" | "comment";
+} | {
+    id: string;
+    integrationId: string;
+    extensionId: string;
+    url: string;
+    icon: string | null;
+    name: string;
+    description: string;
+    width: number | null;
+    height: number | null;
+    defVersion: number;
+    minimumCardistVersion: string;
+    extensionType: "settings";
+})[];

package/package.json

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