syntax = "proto3";

package com.wix.media.site_media.v1;

import "wix/api/validations.proto";
import "wix/api/permissions.proto";
import "wix/api/annotations.proto";
import "google/api/annotations.proto";
import "google/protobuf/field_mask.proto";
import "google/protobuf/wrappers.proto";
import "com/wix/media/site_media/v1/folder.proto";
import "com/wix/media/site_media/v1/root_folders.proto";
import "wix/api/entity.proto";
import "com/wix/media/site_media/upstream/wix/common/paging.proto";
import "wix/api/callback.proto";
// flynt-disable disallow-direct-common-imports
import "wix/common/sorting.proto";
import "wix/http/field_mask.proto";
import "wix/api/api_errors.proto";
import "wix/sdk/definitions.proto";
import "com/wix/media/site_media/v1/namespace.proto";




message CreateFolderRequest {
    // Folder name that appears in the Media Manager.
    string display_name = 1 [(.wix.api.maxLength) = 200];
    // ID of the folder's parent folder.
    google.protobuf.StringValue parent_folder_id = 2 [(.wix.api.maxLength) = 100];

    // The namespace this folder will be created under
    google.protobuf.StringValue raw_namespace = 3 [(.wix.api.field_exposure) = INTERNAL, (.wix.api.maxLength) = 100];

    // The namespace this folder will be created under
    // Note - Namespace value `Others` is not supported and will produce an error
    Namespace namespace = 4 [(.wix.api.field_exposure) = INTERNAL];
}

message CreateFolderResponse {
    // Information about the newly created folder.
    Folder folder = 1;
}


message GetFolderRequest {
    // Folder ID.
    string folder_id = 1 [(.wix.api.maxLength) = 100];
}

message GetFolderResponse {
    // Information about the folder.
    Folder folder = 1;
}

message GetFoldersRequest {
    // List of folder IDs.
    repeated string folder_ids = 1  [(.wix.api.maxSize) = 199, (.wix.api.maxLength) = 100];
}

message GetFoldersResponse {
    // Information about the requested folders.
    repeated Folder folders = 1  [(.wix.api.maxSize) = 200];
}

message ListFoldersRequest {
    /*
    ID of the folder's parent folder.
    
    Default: `media-root` folder.
    */
    google.protobuf.StringValue parent_folder_id = 1 [(.wix.api.maxLength) = 100];
    /*
    Field name and order to sort by. One of:
  
    * `displayName` 
    * `updatedDate`
  
    Default: `updatedDate` in `desc` order.
    */
    .wix.common.Sorting sort = 2;

    // Cursor and paging information.
    com.wix.media.site_media.upstream.wix.common.CursorPaging paging = 3;
    // List folders of the specified namespace.
    google.protobuf.StringValue raw_namespace = 4 [(.wix.api.field_exposure) = INTERNAL, (.wix.api.maxLength) = 100];

    // List folders of the specified namespace.
    // Note - Namespace value `Others` is not supported and will produce an error
    Namespace namespace = 5 [(.wix.api.field_exposure) = INTERNAL];
}

message ListFoldersResponse {
    // Information about the folders in the requested folder.
    repeated Folder folders = 1  [(.wix.api.maxSize) = 200];
    // The next cursor if it exists.
    com.wix.media.site_media.upstream.wix.common.PagingMetadataV2 next_cursor = 2;
}


message SearchFoldersRequest {
    /*
    The root folder in the Media Manager to search in.
    For more information, see Root Folders in Terminology ([SDK](https://dev.wix.com/docs/sdk/backend-modules/media/introduction#terminology) | [REST](https://dev.wix.com/docs/rest/assets/media/media-manager/introduction#terminology)).

    
    Default: `MEDIA_ROOT`.
    */
    RootFolder root_folder = 1;

    /*
    Field name and order to sort by. One of:
  
    * `displayName` 
    * `updatedDate`
  
    Default: `updatedDate` in `desc` order.
    */
    .wix.common.Sorting sort = 2;
    // Cursor and paging information.
    com.wix.media.site_media.upstream.wix.common.CursorPaging paging = 3;

    /*
    Free text to match in searchable fields.

    For example, search for specific values in a folder's `displayName`.
    */
    google.protobuf.StringValue search = 4 [(.wix.api.maxLength) = 200];

    // Search folders of the specified namespace.
    google.protobuf.StringValue raw_namespace = 5 [(.wix.api.field_exposure) = INTERNAL, (.wix.api.maxLength) = 100];

    // Search folders of the specified namespace.
    // Note - Namespace value `Others` is not supported and will produce an error
    Namespace namespace = 6 [(.wix.api.field_exposure) = INTERNAL];
}

message SearchFoldersResponse {
    /*
    Retrieved folders that match the search criteria specified in the request.
  
    Each folder includes all standard folder information.
    */
    repeated Folder folders = 1  [(.wix.api.maxSize) = 200];
    // The next cursor if it exists.
    com.wix.media.site_media.upstream.wix.common.PagingMetadataV2 next_cursor = 2;
}

message UpdateFolderRequest {
    // ID of the folder to update.
//    string folder_id = 1 [(.wix.api.field_deprecated) = {
//        replaced_by: "folder"
//        target_removal_date: "2023-02-25"
//    }];
    reserved 1;

    // Folder name that appears in the Media Manager.
//    google.protobuf.StringValue display_name = 2 [(.wix.api.field_deprecated) = {
//        replaced_by: "folder"
//        target_removal_date: "2023-02-25"
//    }];
    reserved 2;
    // ID of the folder's parent folder.
//    google.protobuf.StringValue parent_folder_id = 3 [(.wix.api.field_deprecated) = {
//        replaced_by: "folder"
//        target_removal_date: "2023-02-25"
//    }];
    reserved 3;
    // Folder to update.
    Folder folder = 4;
    // Set of fields to update. Fields that aren't included in `fieldMask.paths` are ignored.
    google.protobuf.FieldMask field_mask = 5 [(.wix.api.field_exposure) = INTERNAL];
}

message UpdateFolderResponse {
    // Information about the updated folder.
    Folder folder = 1;
}

message GenerateFolderDownloadUrlRequest {
    // Folder ID.
    string folder_id = 1 [(.wix.api.maxLength) = 100];
}

message GenerateFolderDownloadUrlResponse {
    // URL for downloading a specific folder in the Media Manager.
    string download_url = 1 [(.wix.api.format) = WEB_URL];
}

message BulkDeleteFoldersRequest {
    // IDs of the folders to move to the Media Manager's trash bin.
    repeated string folder_ids = 1 [(.wix.api.maxSize) = 100, (.wix.api.maxLength) = 100];

    // Whether the specified folders are permanently deleted. <br />
    // Default: `false`
    bool permanent = 2;
}

message BulkDeleteFoldersResponse {
}

message BulkRestoreFoldersFromTrashBinRequest {
    // IDs of the folders to restore from the Media Manager's trash bin.
    repeated string folder_ids = 1 [(.wix.api.maxSize) = 100, (.wix.api.maxLength) = 100];
}

message BulkRestoreFoldersFromTrashBinResponse {
}

message ListDeletedFoldersRequest {
    // ID of the folder's parent folder.
    google.protobuf.StringValue parent_folder_id = 1 [(.wix.api.maxLength) = 100];
    // Field name and order to sort by. One of:
    // * `displayName`
    // * `updatedDate`
    // Default: `updatedDate` in `desc` order.
    .wix.common.Sorting sort = 2;

    // Cursor and paging information.
    com.wix.media.site_media.upstream.wix.common.CursorPaging paging = 3;
    // List folders of the specified namespace.
    google.protobuf.StringValue raw_namespace = 4 [(.wix.api.field_exposure) = INTERNAL, (.wix.api.maxLength) = 100];

    // List folders of the specified namespace.
    // Note - Namespace value `Others` is not supported and will produce an error
    Namespace namespace = 5 [(.wix.api.field_exposure) = INTERNAL];
}

message ListDeletedFoldersResponse {
    // List of folders in the Media Manager's trash bin.
    repeated Folder folders = 1 [(.wix.api.maxSize) = 200];
    // The next cursor if it exists.
    .com.wix.media.site_media.upstream.wix.common.PagingMetadataV2 next_cursor = 2;
}

service FoldersService {
    option (.wix.api.service_maturity) = GA;
    option (.wix.api.service_exposure) = PUBLIC;
    option (.wix.api.service_entity).message = "com.wix.media.site_media.v1.Folder";

    // Creates a new folder in the Media Manager. <br/>
    //
    // Use the `parentFolderId` parameter to specify in which existing folder you want the new folder to be created.
    // If no folder is specified, the new folder is created in the `media-root` folder.
    rpc CreateFolder (CreateFolderRequest) returns (CreateFolderResponse) {
        // Triggered when a folder is created.
        //
        // This event is also triggered when a folder is restored from the Media Manager's trash bin.
        option (.wix.api.callback) = {
            event_type: CREATED
        };
        option (google.api.http) = {post: "/v1/folders"};
        option (.wix.api.required) = "CreateFolderRequest.display_name";
        option (.wix.api.permission).name = "MEDIA.SITE_MEDIA_FOLDERS_CREATE";
    }

    // Gets information from a specific folder in the Media Manager.
    rpc GetFolder (GetFolderRequest) returns (GetFolderResponse) {
        option (.wix.api.required) = "GetFolderRequest.folder_id";
        option (google.api.http) = {get: "/v1/folders/{folder_id}"};
        option (.wix.api.permission).name = "MEDIA.SITE_MEDIA_FOLDERS_READ";
        option (.wix.api.crud) = {
            method: GET_ITEM
            get_options: {
                id_field: "folder_id"
                item_field: "folder"
            }
        };
    }

    // Retrieves a list of folders in the Media Manager. To retrieve a list of folders within a specific folder in the Media Manager, specify the specific folder's ID in the `parentFolderId` parameter. If no folder is specified, the method retrieves a list of folders within the root folder of the Media Manager.
    rpc ListFolders (ListFoldersRequest) returns (ListFoldersResponse) {
        option (google.api.http) = {get: "/v1/folders"};
        option (.wix.api.permission).name = "MEDIA.SITE_MEDIA_FOLDERS_LIST";
    }

    /*
    Retrieves a list of up to 200 folders with the specified filtering, sorting, and cursor paging.
  
    If no parameters are specified, the method returns all folders in the `MEDIA_ROOT` folder. 
  
    ## Defaults
  
    Search Folders has the following default setting, which you can override:
    + Sorted by `updatedDate` in descending order.
  
    ## Filters
  
    When using filters for dates, you must use
    [UTC time](https://en.wikipedia.org/wiki/Coordinated_Universal_Time).
    
    ## See also
  
    To learn about working with *Search* methods, see
    _API Query Language_
    ([SDK](https://dev.wix.com/docs/sdk/articles/work-with-the-sdk/api-query-language) | [REST](https://dev.wix.com/docs/rest/articles/get-started/api-query-language))
    and *Sorting and Paging*
    ([SDK](https://dev.wix.com/docs/sdk/articles/work-with-the-sdk/api-query-language#the-sort-array) | [REST](https://dev.wix.com/docs/rest/articles/get-started/sorting-and-paging)).
    */
    rpc SearchFolders (SearchFoldersRequest) returns (SearchFoldersResponse) {
        option (google.api.http) = {post: "/v1/folders/search"};
        option (.wix.api.permission).name = "MEDIA.SITE_MEDIA_FOLDERS_LIST";
    }

    // Updates a folder. <br />
    //
    // You can use the `parentFolderId` parameter to move a folder from its current parent folder to a different parent folder.
    rpc UpdateFolder (UpdateFolderRequest) returns (UpdateFolderResponse) {
        // Triggered when a folder is updated, including when a folder is moved to a different parent folder.
        option (.wix.api.callback) = {
            event_type: UPDATED
        };
        option (.wix.api.required) = "UpdateFolderRequest.folder.id";
        option (.wix.api.required) = "UpdateFolderRequest.folder";
        option (google.api.http) = {patch: "/v1/folders/{folder.id}"};
        option (.wix.sdk.signature) = {params: "folder"};
        option (.wix.api.permission).name = "MEDIA.SITE_MEDIA_FOLDERS_UPDATE";
        option (.wix.http.infer_fieldmask) = {
            from: "folder"
            fieldmask: "field_mask"
        };

        // Field mask field is empty or missing from the request
        option (.wix.api.custom_validation_error) = {
            rule_name: "FIELD_MASK_IS_EMPTY_OR_MISSING"
            data: "com.wix.media.site_media.v1.UnsupportedRequestValueError"
        };
        option (.wix.api.crud) = {
            method: UPDATE
            update_options: {
                item_field: "folder"
                fieldmask_field: "field_mask"
            }
        };
    }

    // Generates a URL for downloading a compressed file containing a specific folder in the Media Manager. <br/>
    //
    // The compressed file can contain sub-folders, and up to 1000 files.
    rpc GenerateFolderDownloadUrl (GenerateFolderDownloadUrlRequest) returns (GenerateFolderDownloadUrlResponse) {
        option (.wix.api.required) = "GenerateFolderDownloadUrlRequest.folder_id";
        option (google.api.http) = {post: "/v1/folders/{folder_id}/generate-download-url"};
        option (.wix.api.permission).name = "MEDIA.SITE_MEDIA_FOLDERS_DOWNLOAD";
    }

    // Temporarily deletes the specified folders from the Media Manager. <br/>
    //
    // The deleted folders are moved to the Media Manager's `trash-root` folder (trash bin) unless permanently deleted. To permanently delete folders, specify the `permanent` parameter with the value `true`. Permanently deleting folders isn't reversible, so make sure that the files in these folders aren't being used in a site or in any other way as the files will no longer be accessible.
    //
    // Note the following:
    // * When a folder is deleted, the files in that folder are deleted.
    // * The specified folders can be from different parent folders.
    // * Moving multiple folders at once is an asynchronous action, and may take time for the changes to appear in the Media Manager.
    // * Attempting to delete folders that are already in the trash bin doesn't result in an error.
    // * If a site contains files from a deleted media folder, the files still appear on the site as the deleted folder is still in the Media Manager (in the trash bin).
    // * You can also use the Bulk Restore Folders From Trash Bin ([SDK](https://dev.wix.com/docs/sdk/backend-modules/media/folders/bulk-restore-folders-from-trash-bin) | [REST](https://dev.wix.com/docs/rest/assets/media/media-manager/folders/bulk-restore-folders-from-trash-bin)) method to restore folders from the Media Manager's trash bin.
    rpc BulkDeleteFolders (BulkDeleteFoldersRequest) returns (BulkDeleteFoldersResponse) {
        option (.wix.api.required) = "BulkDeleteFoldersRequest.folder_ids";
        // Triggered when a folder is deleted.
        //
        // If the `movedToTrash` property in the event object is `true`, the folder was moved to the Media Manager's trash bin. If the `movedToTrash` property in the event object is `false`, the folder was permanently deleted.
        option (.wix.api.callback) = {
            event_type: DELETED
        };
        option (google.api.http) = {post: "/v1/bulk/folders/delete"};
        option (.wix.api.permission).name = "MEDIA.SITE_MEDIA_FOLDERS_MOVE_TO_TRASH";
        option (.wix.api.crud) = {
            method: BULK_DELETE
            bulk_delete_options: {
                ids_field: "folder_ids"
            }
        };
    }

    // Restores the specified folders from the Media Manager's trash bin, and moves them to their original locations in the Media Manager.
    rpc BulkRestoreFoldersFromTrashBin(BulkRestoreFoldersFromTrashBinRequest) returns (BulkRestoreFoldersFromTrashBinResponse) {
        option (.wix.api.required) = "BulkRestoreFoldersFromTrashBinRequest.folder_ids";
        option (google.api.http) = {
            post : "/v1/bulk/trash-bin/folders/restore"
        };
        option (.wix.api.permission).name = "MEDIA.SITE_MEDIA_FOLDERS_RESTORE_FROM_TRASH";
    }

    // Retrieves a list of folders in the Media Manager's trash bin.
    rpc ListDeletedFolders(ListDeletedFoldersRequest) returns (ListDeletedFoldersResponse) {
        option (google.api.http) = {
            get : "/v1/trash-bin/folders"
        };
        option (.wix.api.permission).name = "MEDIA.SITE_MEDIA_FOLDERS_LIST_DELETED";
    }

    option (.wix.api.event) = {
        event_type: CREATED
    };

    option (.wix.api.event) = {
        event_type: UPDATED
    };

    option (.wix.api.event) = {
        event_type: DELETED
    };
}
