brick_ftp 0.8.4 → 1.0.0.beta

data/lib/brick_ftp/restful_api/list_folder_behaviors.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require 'erb'
+
+module BrickFTP
+  module RESTfulAPI
+    # List behaviors for a folder
+    #
+    # @see https://developers.brickftp.com/#list-behaviors-for-a-folder List behaviors for a folder
+    #
+    # ### Params
+    #
+    # PARAMETER | TYPE     | DESCRIPTION
+    # --------- | -------- | -----------
+    # recursive | integer  | Optionally set to 1 to have response include behaviors inherited from parent folders.
+    #
+    class ListFolderBehaviors
+      include Command
+
+      # Returns the behaviors that apply to the given path.
+      #
+      # By default, only behaviors applied directly on the the given path will be returned.
+      # If you would also like behaviors that are inherited from parent folders to be returned,
+      # the recursive query parameter can be passed in on the URL with the value of 1.
+      #
+      # @param [String] path
+      # @param [Boolean] recursive
+      # @return [Array<BrickFTP::Types::Behavior>] Behaviors
+      #
+      def call(path, recursive: false)
+        endpoint = "/api/rest/v1/behaviors/folders/#{ERB::Util.url_encode(path)}"
+        endpoint = "#{endpoint}?recursive=1" if recursive
+        res = client.get(endpoint)
+
+        res.map { |i| BrickFTP::Types::Behavior.new(i.symbolize_keys) }
+      end
+    end
+  end
+end

data/lib/brick_ftp/restful_api/list_folders.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+require 'erb'
+
+module BrickFTP
+  module RESTfulAPI
+    # List folder contents
+    #
+    # @see https://developers.brickftp.com/#list-folder-contents List folder contents
+    #
+    # ### Params
+    #
+    # PARAMETER                     | TYPE     | DESCRIPTION
+    # ----------------------------- | -------- | -----------
+    # page                          | integer  | Page number of items to return in this request.
+    # per_page                      | integer  | Requested number of items returned per request. Maximum: `5000`, leave blank for default (strongly recommended).
+    # search                        | string   | Only return items matching the given search text.
+    # sort_by[path]                 | enum     | Sort by file name, and value is either `asc` or `desc` to indicate normal or reverse sort. (Note that `sort_by[path] = asc` is the default.)
+    # sort_by[size]                 | enum     | Sort by file size, and value is either `asc` or `desc` to indicate smaller files first or larger files first, respectively.
+    # sort_by[modified_at_datetime] | enum     | Sort by modification time, and value is either `asc` or `desc` to indicate older files first or newer files first, respectively.
+    #
+    class ListFolders
+      include Command
+      using BrickFTP::CoreExt::Struct
+      using BrickFTP::CoreExt::Hash
+
+      Params = Struct.new(
+        'ListFoldersParams',
+        :page,
+        :per_page,
+        :search,
+        :'sort_by[path]',
+        :'sort_by[size]',
+        :'sort_by[modified_at_datetime]',
+        keyword_init: true
+      )
+
+      # Lists the contents of the folder provided in the URL.
+      #
+      # Remember that a blank URL refers to the root folder. So for example, you can list the contents of the root folder
+      # using the REST API by sending a GET request to /folders. Another folder can be listed by inserting its complete
+      # path in that URL after /folders, for example: /folders/employee/engineering.
+      #
+      # There is a maximum number of entries in the folder that will be listed with a single request
+      # (default 1000 or whatever value you provide as the per_page parameter).
+      # So if exactly that many entries are returned you will need to increment the value of the page parameter in
+      # subsequent queries to continue listing the folder.
+      #
+      # @param [String] path Full path of the file or folder. Maximum of 550 characters.
+      # @param [BrickFTP::RESTfulAPI::ListFolders::Params, nil] params parameters
+      # @return [Array<BrickFTP::Types::File>] Files
+      #
+      def call(path, params = nil)
+        validate_params!(params)
+
+        query = build_query(params)
+        endpoint = "/api/rest/v1/folders/#{ERB::Util.url_encode(path)}"
+        endpoint = "#{endpoint}?#{query}" unless query.empty?
+
+        res = client.get(endpoint)
+
+        res.map { |i| BrickFTP::Types::File.new(i.symbolize_keys) }
+      end
+
+      private
+
+      def build_query(params)
+        return '' if params.nil?
+
+        params.to_h.compact.map { |k, v| "#{k}=#{ERB::Util.url_encode(v.to_s)}" }.join('&')
+      end
+
+      def validate_params!(params)
+        return if params.nil?
+
+        validate_page!(params[:page])
+        validate_per_page!(params[:per_page])
+        validate_sort_by!(params[:'sort_by[path]'])
+        validate_sort_by!(params[:'sort_by[size]'])
+        validate_sort_by!(params[:'sort_by[modified_at_datetime]'])
+      end
+
+      def validate_page!(page)
+        return if page.nil?
+        return if page.is_a?(Integer) && page.positive?
+
+        raise ArgumentError, 'page must be greater than 0.'
+      end
+
+      MAX_PER_PAGE = 5_000
+
+      def validate_per_page!(per_page)
+        return if per_page.nil?
+        return if per_page.is_a?(Integer) && per_page.positive? && per_page <= MAX_PER_PAGE
+
+        raise ArgumentError, "per_page must be greater than 0 and less than equal #{MAX_PER_PAGE}."
+      end
+
+      VALID_SORT = %w[asc desc].freeze
+
+      def validate_sort_by!(value)
+        return if value.nil? || VALID_SORT.include?(value)
+
+        raise ArgumentError, 'sort_by[*] must be `asc` or `desc`.'
+      end
+    end
+  end
+end

data/lib/brick_ftp/restful_api/list_groups.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module BrickFTP
+  module RESTfulAPI
+    # List all groups
+    #
+    # @see https://developers.brickftp.com/#list-all-groups List all groups
+    #
+    class ListGroups
+      include Command
+
+      # Returns a list of all groups on the current site.
+      #
+      # @return [Array<BrickFTP::Types::Group>] Groups
+      #
+      def call
+        res = client.get('/api/rest/v1/groups.json')
+
+        res.map { |i| BrickFTP::Types::Group.new(i.symbolize_keys) }
+      end
+    end
+  end
+end

data/lib/brick_ftp/restful_api/list_notifications.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module BrickFTP
+  module RESTfulAPI
+    # List all notifications
+    #
+    # @see https://developers.brickftp.com/#list-all-notifications List all notifications
+    #
+    class ListNotifications
+      include Command
+
+      # Returns a list of all notifications on the current site.
+      #
+      # @return [Array<BrickFTP::Types::Notification>] Notifications
+      #
+      def call
+        res = client.get('/api/rest/v1/notifications.json')
+
+        res.map { |i| BrickFTP::Types::Notification.new(i.symbolize_keys) }
+      end
+    end
+  end
+end

data/lib/brick_ftp/restful_api/list_permissions.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require 'erb'
+
+module BrickFTP
+  module RESTfulAPI
+    # List permissions
+    #
+    # @see https://developers.brickftp.com/#list-permissions List permissions
+    #
+    # ### Params
+    #
+    # PARAMETER | TYPE   | DESCRIPTION
+    # --------- | ------ | -----------
+    # path      | string | Optional path to focus the result set on.
+    #
+    class ListPermissions
+      include Command
+
+      # Returns a list of permissions on the current site.
+      #
+      # - By default all permissions for the entire site are returned.
+      # - When given a path parameter, then only permissions immediately relevant to the given path are returned.
+      # - When using a path parameter, the result will include permissions on the current path and recursive
+      #   permissions that are inherited from parent paths, except that lesser permissions will be excluded
+      #   if a greater permission applies on the given path for a particular user or group.
+      #
+      # @param [String] path Folder path for the permission to apply to. This must be slash-delimited,
+      #   but it must neither start nor end with a slash. Maximum of 5000 characters.
+      # @return [Array<BrickFTP::Types::Permission>] Permissions
+      #
+      def call(path: nil)
+        endpoint = '/api/rest/v1/permissions.json'
+        endpoint = "#{endpoint}?path=#{ERB::Util.url_encode(path)}" unless path.nil?
+        res = client.get(endpoint)
+
+        res.map { |i| BrickFTP::Types::Permission.new(i.symbolize_keys) }
+      end
+    end
+  end
+end

data/lib/brick_ftp/restful_api/list_public_keys.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module BrickFTP
+  module RESTfulAPI
+    # List public keys
+    #
+    # @see https://developers.brickftp.com/#list-public-keys List public keys
+    #
+    class ListPublicKeys
+      include Command
+
+      # Returns a list of all public keys for a user on the current site.
+      #
+      # @param [Integer] id Globally unique identifier of each user.
+      #   Each user is given an ID automatically upon creation.
+      # @return [Array<BrickFTP::Types::UserPublicKey>] User's Public keys
+      #
+      def call(id)
+        res = client.get("/api/rest/v1/users/#{id}/public_keys.json")
+
+        res.map { |i| BrickFTP::Types::UserPublicKey.new(i.symbolize_keys) }
+      end
+    end
+  end
+end

data/lib/brick_ftp/restful_api/list_users.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module BrickFTP
+  module RESTfulAPI
+    # List users
+    #
+    # @see https://developers.brickftp.com/#list-users List users
+    #
+    # ### Params
+    #
+    # PARAMETER | TYPE    | DESCRIPTION
+    # --------- | ------- | -----------
+    # page      | integer | Optional page number of items to return in this request. Default: 1.
+    # per_page  | integer | Optional requested number of items returned per request. Default: 1000. Leave blank for default (strongly recommended).
+    #
+    class ListUsers
+      include Command
+
+      # Returns a list of users on the current site.
+      #
+      # @param [Integer] page Optional page number of items to return in this request.
+      #   Default: 1.
+      # @param [Integer] per_page Optional requested number of items returned per request.
+      #   Default: 1000. Leave blank for default (strongly recommended).
+      # @return [Array<BrickFTP::Types::User>] Users
+      #
+      def call(page: nil, per_page: nil)
+        validate_page!(page)
+        validate_per_page!(per_page)
+
+        params = {}
+        params[:page] = page if page
+        params[:per_page] = per_page if per_page
+        query = params.map { |k, v| "#{k}=#{v}" }.join('&')
+
+        endpoint = '/api/rest/v1/users.json'
+        endpoint = "#{endpoint}?#{query}" unless query.empty?
+        res = client.get(endpoint)
+
+        res.map { |i| BrickFTP::Types::User.new(i.symbolize_keys) }
+      end
+
+      private
+
+      def validate_page!(page)
+        return if page.nil?
+        return if page.is_a?(Integer) && page.positive?
+
+        raise ArgumentError, 'page must be greater than 0.'
+      end
+
+      def validate_per_page!(per_page)
+        return if per_page.nil?
+        return if per_page.is_a?(Integer) && per_page.positive?
+
+        raise ArgumentError, 'per_page must be greater than 0.'
+      end
+    end
+  end
+end

data/lib/brick_ftp/restful_api/move_folder.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require 'erb'
+
+module BrickFTP
+  module RESTfulAPI
+    # Move or rename a file or folder
+    #
+    # @see https://developers.brickftp.com/#move-or-rename-a-file-or-folder Move or rename a file or folder
+    #
+    # ### Params
+    #
+    # PARAMETER        | TYPE   | DESCRIPTION
+    # ---------------- | ------ | -----------
+    # move-destination | string | Full path of the file or folder. Maximum of 550 characters.
+    #
+    class MoveFolder
+      include Command
+      using BrickFTP::CoreExt::Struct
+      using BrickFTP::CoreExt::Hash
+
+      Params = Struct.new(
+        'MoveFolderParams',
+        :'move-destination',
+        keyword_init: true
+      )
+
+      # Moves or renames a file or folder to the destination provided in
+      # the `move-destination` parameter in the request body.
+      # Note that a move/rename will fail if the destination already exists.
+      #
+      # @param [String] path Full path of the file or folder. Maximum of 550 characters.
+      # @param [BrickFTP::RESTfulAPI::MoveFolder::Params] params parameters
+      #
+      def call(path, params)
+        client.post("/api/rest/v1/files/#{ERB::Util.url_encode(path)}", params.to_h.compact)
+        true
+      end
+    end
+  end
+end

data/lib/brick_ftp/restful_api/remove_group_member.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module BrickFTP
+  module RESTfulAPI
+    # Remove a member
+    #
+    # @see https://developers.brickftp.com/#remove-a-member Remove a member
+    #
+    class RemoveGroupMember
+      include Command
+
+      # Removes a user from a group. No action will be taken if the user is not already in the group.
+      #
+      # @param [Integer] group_id ID of the group the membership is associated with.
+      # @param [Integer] user_id ID of the user the membership is associated with.
+      #
+      def call(group_id, user_id)
+        client.delete("/api/rest/v1/groups/#{group_id}/memberships/#{user_id}.json")
+        true
+      end
+    end
+  end
+end

data/lib/brick_ftp/restful_api/retrieve_file_history.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require 'erb'
+
+module BrickFTP
+  module RESTfulAPI
+    # Retrieve file history
+    #
+    # @see https://developers.brickftp.com/#retrieve-file-history Retrieve file history
+    #
+    # ### Params
+    #
+    # PARAMETER | TYPE     | DESCRIPTION
+    # --------- | -------- | -----------
+    # page      | integer  | Optional page number of items to return in this request.
+    # per_page  | integer  | Optional requested number of items returned per request. Default: 1000, maximum: 10000. Leave blank for default (strongly recommended).
+    # start_at  | datetime | Optional date and time in the history to start from.
+    #
+    class RetrieveFileHistory
+      include Command
+      include RetrieveHistory
+
+      # Returns all history for a specific file.
+      #
+      # - The history starts with the most recent entries and proceeds back in time.
+      # - There is a maximum number of records that will be returned with a single request
+      #   (default 1000 or whatever value you provide as the per_page parameter, up to a maximum of 10,000).
+      #
+      # @param [String] path Path of the file or folder associated with the history entry.
+      # @param [Integer] page Optional page number of items to return in this request.
+      # @param [Integer] per_page Optional requested number of items returned per request.
+      #   Default: 1000, maximum: 10000. Leave blank for default (strongly recommended).
+      # @param [Time] start_at Optional date and time in the history to start from.
+      # @return [Array<BrickFTP::Types::History>] History
+      #
+      def call(path, page: nil, per_page: nil, start_at: nil)
+        retrieve("/api/rest/v1/history/files/#{ERB::Util.url_encode(path)}", page, per_page, start_at)
+      end
+    end
+  end
+end

data/lib/brick_ftp/restful_api/retrieve_folder_history.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require 'erb'
+
+module BrickFTP
+  module RESTfulAPI
+    # Retrieve folder history
+    #
+    # @see https://developers.brickftp.com/#retrieve-folder-history Retrieve folder history
+    #
+    # ### Params
+    #
+    # PARAMETER | TYPE     | DESCRIPTION
+    # --------- | -------- | -----------
+    # page      | integer  | Optional page number of items to return in this request.
+    # per_page  | integer  | Optional requested number of items returned per request. Default: 1000, maximum: 10000. Leave blank for default (strongly recommended).
+    # start_at  | datetime | Optional date and time in the history to start from.
+    #
+    class RetrieveFolderHistory
+      include Command
+      include RetrieveHistory
+
+      # Returns all history for a specific folder.
+      #
+      # - The history starts with the most recent entries and proceeds back in time.
+      # - There is a maximum number of records that will be returned with a single request
+      #   (default 1000 or whatever value you provide as the per_page parameter, up to a maximum of 10,000).
+      #
+      # @param [String] path Path of the file or folder associated with the history entry.
+      # @param [Integer] page Optional page number of items to return in this request.
+      # @param [Integer] per_page Optional requested number of items returned per request.
+      #   Default: 1000, maximum: 10000. Leave blank for default (strongly recommended).
+      # @param [Time] start_at Optional date and time in the history to start from.
+      # @return [Array<BrickFTP::Types::History>] History
+      #
+      def call(path, page: nil, per_page: nil, start_at: nil)
+        retrieve("/api/rest/v1/history/folders/#{ERB::Util.url_encode(path)}", page, per_page, start_at)
+      end
+    end
+  end
+end