feat(client): findFolder method, also ability to pass folder name in editFolder

packages/client/src/client.ts

@@ -43,6 +43,7 @@ import { unarchiveChats } from './methods/chats/unarchive-chats'
 import { createFolder } from './methods/dialogs/create-folder'
 import { deleteFolder } from './methods/dialogs/delete-folder'
 import { editFolder } from './methods/dialogs/edit-folder'
+import { findFolder } from './methods/dialogs/find-folder'
 import { getDialogs } from './methods/dialogs/get-dialogs'
 import { getFolders } from './methods/dialogs/get-folders'
 import { downloadAsBuffer } from './methods/files/download-buffer'
@@ -722,14 +723,32 @@ export interface TelegramClient extends BaseTelegramClient {
     /**
      * Edit a folder with given modification
      *
-     * @param folder  Folder or folder ID. Note that passing an ID will require re-fetching all folders
+     * @param folder
+     *     Folder, folder ID or name.
+     *     Note that passing an ID or name will require re-fetching all folders,
+     *     and passing name might affect not the right folder if you have multiple
+     *     with the same name.
      * @param modification  Modification that will be applied to this folder
      * @returns  Modified folder
      */
     editFolder(
-        folder: tl.RawDialogFilter | number,
+        folder: tl.RawDialogFilter | number | string,
         modification: Partial<Omit<tl.RawDialogFilter, 'id' | '_'>>
     ): Promise<tl.RawDialogFilter>
+    /**
+     * Find a folder by its parameter.
+     *
+     * > **Note**: Searching by title and/or emoji might not be
+     * > accurate since you can set the same title and/or emoji
+     * > to multiple folders.
+     *
+     * @param params  Search parameters. At least one must be set.
+     */
+    findFolder(params: {
+        title?: string
+        emoji?: string
+        id?: number
+    }): Promise<tl.RawDialogFilter | null>
     /**
      * Iterate over dialogs.
      *
@@ -1786,6 +1805,7 @@ export class TelegramClient extends BaseTelegramClient {
     createFolder = createFolder
     deleteFolder = deleteFolder
     editFolder = editFolder
+    findFolder = findFolder
     getDialogs = getDialogs
     getFolders = getFolders
     downloadAsBuffer = downloadAsBuffer

packages/client/src/methods/dialogs/edit-folder.ts

@@ -5,20 +5,24 @@ import { MtCuteArgumentError } from '../../types'
 /**
  * Edit a folder with given modification
  *
- * @param folder  Folder or folder ID. Note that passing an ID will require re-fetching all folders
+ * @param folder
+ *     Folder, folder ID or name.
+ *     Note that passing an ID or name will require re-fetching all folders,
+ *     and passing name might affect not the right folder if you have multiple
+ *     with the same name.
  * @param modification  Modification that will be applied to this folder
  * @returns  Modified folder
  * @internal
  */
 export async function editFolder(
     this: TelegramClient,
-    folder: tl.RawDialogFilter | number,
+    folder: tl.RawDialogFilter | number | string,
     modification: Partial<Omit<tl.RawDialogFilter, 'id' | '_'>>
 ): Promise<tl.RawDialogFilter> {
-    if (typeof folder === 'number') {
+    if (typeof folder === 'number' || typeof folder === 'string') {
         const old = await this.getFolders()
-        const found = old.find(it => it.id === folder)
+        const found = old.find(it => it.id === folder || it.title === folder)
-        if (!found) throw new MtCuteArgumentError(`Could not find a folder with ID ${folder}`)
+        if (!found) throw new MtCuteArgumentError(`Could not find a folder ${folder}`)
 
         folder = found
     }

packages/client/src/methods/dialogs/find-folder.ts

@@ -0,0 +1,35 @@
+import { TelegramClient } from '../../client'
+import { tl } from '@mtcute/tl'
+import { MtCuteArgumentError } from '../../types'
+
+/**
+ * Find a folder by its parameter.
+ *
+ * > **Note**: Searching by title and/or emoji might not be
+ * > accurate since you can set the same title and/or emoji
+ * > to multiple folders.
+ *
+ * @param params  Search parameters. At least one must be set.
+ * @internal
+ */
+export async function findFolder(
+    this: TelegramClient,
+    params: {
+        title?: string
+        emoji?: string
+        id?: number
+    }
+): Promise<tl.RawDialogFilter | null> {
+    if (!params.title && !params.emoji && !params.id)
+        throw new MtCuteArgumentError('One of search parameters must be passed')
+
+    const folders = await this.getFolders()
+
+    return folders.find((it) => {
+        if (params.id && it.id !== params.id) return false
+        if (params.title && it.title !== params.title) return false
+        if (params.emoji && it.emoticon !== params.emoji) return false
+
+        return true
+    }) ?? null
+}