[PB-6608] feat/add favorites support for files and folders

package.json

@@ -1,7 +1,7 @@
 {
   "name": "@internxt/sdk",
   "author": "Internxt <hello@internxt.com>",
-  "version": "1.17.22",
+  "version": "1.17.23",
   "description": "An sdk for interacting with Internxt's services",
   "repository": {
     "type": "git",

src/drive/storage/index.ts

@@ -16,6 +16,10 @@ import {
   CreateThumbnailEntryPayload,
   DeleteFilePayload,
   DriveFileData,
+  FavoriteFileDto,
+  FavoriteFolderDto,
+  FavoriteItemType,
+  FavoriteStatusResponse,
   FetchFolderContentResponse,
   FetchLimitResponse,
   FetchPaginatedFilesContent,
@@ -31,6 +35,7 @@ import {
   FolderStatsResponse,
   FolderTreeResponse,
   FileLimitsResponse,
+  GetFavoritesPayload,
   MoveFilePayload,
   MoveFileResponse,
   MoveFileUuidPayload,
@@ -911,4 +916,57 @@ export class Storage {
   public getFileVersionLimits(): Promise<FileLimitsResponse> {
     return this.client.get<FileLimitsResponse>('/files/limits', this.headers());
   }
+
+  /**
+   * Marks a file or folder as favorite. The operation is idempotent: marking an
+   * already favorited item succeeds without creating duplicates.
+   *
+   * @param {FavoriteItemType} itemType - The type of the item ('file' | 'folder').
+   * @param {string} uuid - The UUID of the item.
+   * @returns {Promise<FavoriteStatusResponse>} A promise that resolves with the favorite status.
+   */
+  public markItemAsFavorite(itemType: FavoriteItemType, uuid: string): Promise<FavoriteStatusResponse> {
+    return this.client.put(`/favorites/${itemType}/${uuid}`, {}, this.headers());
+  }
+
+  /**
+   * Unmarks a file or folder as favorite. The operation is idempotent: unmarking
+   * an item that is not favorited succeeds as a no-op.
+   *
+   * @param {FavoriteItemType} itemType - The type of the item ('file' | 'folder').
+   * @param {string} uuid - The UUID of the item.
+   * @returns {Promise<FavoriteStatusResponse>} A promise that resolves with the favorite status.
+   */
+  public unmarkItemAsFavorite(itemType: FavoriteItemType, uuid: string): Promise<FavoriteStatusResponse> {
+    return this.client.delete(`/favorites/${itemType}/${uuid}`, this.headers());
+  }
+
+  /**
+   * Gets the list of files or folders marked as favorite by the user.
+   *
+   * @param {FavoriteItemType} type - The type of favorite items to list ('file' | 'folder').
+   * @param {GetFavoritesPayload} payload - Pagination (limit/offset required) plus optional sort and order.
+   * @returns {[Promise<FavoriteFileDto[] | FavoriteFolderDto[]>, RequestCanceler]} An array containing a promise to get the API response and a function to cancel the request.
+   */
+  public getFavorites(type: 'file', payload: GetFavoritesPayload): [Promise<FavoriteFileDto[]>, RequestCanceler];
+  public getFavorites(type: 'folder', payload: GetFavoritesPayload): [Promise<FavoriteFolderDto[]>, RequestCanceler];
+  public getFavorites(
+    type: FavoriteItemType,
+    payload: GetFavoritesPayload,
+  ): [Promise<FavoriteFileDto[] | FavoriteFolderDto[]>, RequestCanceler] {
+    const { limit, offset, sort, order } = payload;
+    const query = new URLSearchParams();
+    query.set('type', type);
+    query.set('limit', String(limit));
+    query.set('offset', String(offset));
+    if (sort !== undefined) query.set('sort', sort);
+    if (order !== undefined) query.set('order', order);
+
+    const { promise, requestCanceler } = this.client.getCancellable<FavoriteFileDto[] | FavoriteFolderDto[]>(
+      `/favorites?${query}`,
+      this.headers(),
+    );
+
+    return [promise, requestCanceler];
+  }
 }

src/drive/storage/types.ts

@@ -1,4 +1,4 @@
-import { paths } from '../../schema';
+import { components, paths } from '../../schema';
 import { UserResumeData } from '../users/types';
 
 export interface DriveFolderData {
@@ -22,6 +22,7 @@ export interface DriveFolderData {
   user_id: number;
   uuid: string;
   user?: UserResumeData;
+  isFavorite?: boolean;
 }
 
 export interface DriveFileData {
@@ -51,6 +52,7 @@ export interface DriveFileData {
   user?: UserResumeData;
   creationTime?: string;
   modificationTime?: string;
+  isFavorite?: boolean;
 }
 
 export interface Thumbnail {
@@ -84,6 +86,7 @@ export interface FolderChild {
   user_id: number;
   uuid: string;
   plainName?: string;
+  isFavorite?: boolean;
 }
 
 export interface FetchFolderContentResponse {
@@ -469,6 +472,25 @@ export interface CheckDuplicatedFoldersResponse {
   existentFolders: DriveFolderData[];
 }
 
+// Favorites
+
+export type FavoriteItemType = 'file' | 'folder';
+
+export type FavoriteFileDto = components['schemas']['FileDto'];
+
+export type FavoriteFolderDto = components['schemas']['FolderDto'];
+
+export interface FavoriteStatusResponse {
+  favorited: boolean;
+}
+
+export interface GetFavoritesPayload {
+  limit: number;
+  offset: number;
+  sort?: 'uuid' | 'plainName' | 'updatedAt';
+  order?: 'ASC' | 'DESC';
+}
+
 export type FileVersion = paths['/files/{uuid}/versions']['get']['responses']['200']['content']['application/json'][0];
 
 export type RestoreFileVersionResponse =