brick_ftp 0.8.4 → 1.0.0.beta

data/lib/brick_ftp/restful_api/retrieve_history.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require 'erb'
+
+module BrickFTP
+  module RESTfulAPI
+    module RetrieveHistory
+      def retrieve(path, page, per_page, start_at)
+        validate_page!(page)
+        validate_per_page!(per_page)
+        validate_start_at!(start_at)
+
+        query = build_query(page, per_page, start_at)
+        endpoint = path
+        endpoint = "#{path}?#{query}" unless query.empty?
+        res = client.get(endpoint)
+
+        res.map { |i| BrickFTP::Types::History.new(i.symbolize_keys) }
+      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 = 10_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
+
+      def validate_start_at!(start_at)
+        return if start_at.nil?
+        return if start_at.is_a?(Time)
+
+        raise ArgumentError, 'start_at must be a Time.'
+      end
+
+      def build_query(page, per_page, start_at)
+        params = {}
+        params[:page] = page if page
+        params[:per_page] = per_page if per_page
+        params[:start_at] = start_at.utc.iso8601 if start_at
+
+        params.map { |k, v| "#{k}=#{ERB::Util.url_encode(v.to_s)}" }.join('&')
+      end
+    end
+  end
+end

data/lib/brick_ftp/restful_api/retrieve_login_history.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module BrickFTP
+  module RESTfulAPI
+    # Retrieve login history
+    #
+    # @see https://developers.brickftp.com/#retrieve-login-history Retrieve login 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 RetrieveLoginHistory
+      include Command
+      include RetrieveHistory
+
+      # Returns login history only.
+      #
+      # - 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 [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(page: nil, per_page: nil, start_at: nil)
+        retrieve('/api/rest/v1/history/login.json', page, per_page, start_at)
+      end
+    end
+  end
+end

data/lib/brick_ftp/restful_api/retrieve_site_history.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module BrickFTP
+  module RESTfulAPI
+    # Retrieve site history
+    #
+    # @see https://developers.brickftp.com/#retrieve-site-history Retrieve site 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 RetrieveSiteHistory
+      include Command
+      include RetrieveHistory
+
+      # Returns the entire history for the current site.
+      #
+      # - 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 [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(page: nil, per_page: nil, start_at: nil)
+        retrieve('/api/rest/v1/history.json', page, per_page, start_at)
+      end
+    end
+  end
+end

data/lib/brick_ftp/restful_api/retrieve_user_history.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module BrickFTP
+  module RESTfulAPI
+    # Retrieve user history
+    #
+    # @see https://developers.brickftp.com/#retrieve-user-history Retrieve user 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 RetrieveUserHistory
+      include Command
+      include RetrieveHistory
+
+      # Returns user history only.
+      #
+      # - 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 [Integer] id Globally unique identifier of each user.
+      #   Each user is given an ID automatically upon creation.
+      # @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(id, page: nil, per_page: nil, start_at: nil)
+        retrieve("/api/rest/v1/history/users/#{id}.json", page, per_page, start_at)
+      end
+    end
+  end
+end

data/lib/brick_ftp/restful_api/search_user.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require 'erb'
+
+module BrickFTP
+  module RESTfulAPI
+    # Search users
+    #
+    # @see https://developers.brickftp.com/#search-users Search users
+    #
+    class SearchUser
+      include Command
+
+      # Returns a single user.
+      #
+      # @param [String] username Username for the user. This is how the user will be displayed on the site.
+      #   Maximum of 50 characters.
+      # @return [BrickFTP::Types::User, nil] found User or nil
+      #
+      def call(username)
+        res = client.get("/api/rest/v1/users.json?q[username]=#{ERB::Util.url_encode(username)}")
+        return nil if !res || res.empty?
+
+        BrickFTP::Types::User.new(res.first.symbolize_keys)
+      end
+    end
+  end
+end

data/lib/brick_ftp/restful_api/start_upload.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require 'erb'
+
+module BrickFTP
+  module RESTfulAPI
+    # Starting a new upload
+    #
+    # @see https://developers.brickftp.com/#starting-a-new-upload Starting a new upload
+    #
+    class StartUpload
+      include Command
+
+      # The first request to upload a new file is a POST request to /files/PATH_AND_FILENAME.EXT
+      # with an action parameter with the value of put.
+      #
+      # @param [String] path Full path of the file or folder. Maximum of 550 characters.
+      # @return [BrickFTP::Types::Upload] Upload object
+      #
+      def call(path)
+        res = client.post("/api/rest/v1/files/#{ERB::Util.url_encode(path)}", action: 'put')
+
+        BrickFTP::Types::Upload.new(res.symbolize_keys)
+      end
+    end
+  end
+end

data/lib/brick_ftp/restful_api/unlock_user.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module BrickFTP
+  module RESTfulAPI
+    # Unlock a user
+    #
+    # @see https://developers.brickftp.com/#unlock-a-user Unlock a user
+    #
+    class UnlockUser
+      include Command
+
+      # Unlocks a user that has been locked out by Brute Force Login Protection.
+      #
+      # @param [Integer] id Globally unique identifier of each user.
+      #   Each user is given an ID automatically upon creation.
+      # @return [BrickFTP::Types::User, nil] unlocked User or nil
+      #
+      def call(id)
+        res = client.post("/api/rest/v1/users/#{id}/unlock.json")
+
+        BrickFTP::Types::User.new(res.symbolize_keys)
+      end
+    end
+  end
+end

data/lib/brick_ftp/restful_api/update_behavior.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module BrickFTP
+  module RESTfulAPI
+    # Update a behavior
+    #
+    # @see https://developers.brickftp.com/#update-a-behavior Update a behavior
+    #
+    # ### Params
+    #
+    # PARAMETER | TYPE   | DESCRIPTION
+    # --------- | ------ | -----------
+    # value     | array | Array of values associated with the behavior.
+    #
+    class UpdateBehavior
+      include Command
+      using BrickFTP::CoreExt::Struct
+      using BrickFTP::CoreExt::Hash
+
+      Params = Struct.new(
+        'UpdateBehaviorParams',
+        :value,
+        keyword_init: true
+      )
+
+      # Updates an existing behavior.
+      #
+      # @param [Integer] id Globally unique identifier of each behavior.
+      # @param [BrickFTP::RESTfulAPI::UpdateBehavior::Params] params parameters
+      # @return [BrickFTP::Types::Behavior] Behavior
+      #
+      def call(id, params)
+        res = client.patch("/api/rest/v1/behaviors/#{id}.json", params.to_h.compact)
+
+        BrickFTP::Types::Behavior.new(res.symbolize_keys)
+      end
+    end
+  end
+end

data/lib/brick_ftp/restful_api/update_group.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module BrickFTP
+  module RESTfulAPI
+    # Update a group
+    #
+    # @see https://developers.brickftp.com/#update-a-group Update a group
+    #
+    # ### Params
+    #
+    # PARAMETER | TYPE                     | DESCRIPTION
+    # --------- | ------------------------ | -----------
+    # name      | string                   | Name of the group. This is how the group will be displayed on the site. Maximum of 50 characters.
+    # notes     | text                     | You may use this property to store any additional information you require. There are no restrictions on its formatting.
+    # user_ids  | comma-separated integers | IDs of the users that are in this group.
+    #
+    class UpdateGroup
+      include Command
+      using BrickFTP::CoreExt::Struct
+      using BrickFTP::CoreExt::Hash
+
+      Params = Struct.new(
+        'UpdateGroupParams',
+        :name,
+        :notes,
+        :user_ids,
+        keyword_init: true
+      )
+
+      # Updates the specified group.
+      #
+      # @param [Integer] id Globally unique identifier of each group.
+      #   Each group is given an ID automatically upon creation.
+      # @param [BrickFTP::RESTfulAPI::UpdateGroup::Params] params parameters for updating a Group
+      # @return [BrickFTP::Types::Group] updated Group
+      #
+      def call(id, params)
+        res = client.put("/api/rest/v1/groups/#{id}.json", params.to_h.compact)
+
+        BrickFTP::Types::Group.new(res.symbolize_keys)
+      end
+    end
+  end
+end

data/lib/brick_ftp/restful_api/update_group_member.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module BrickFTP
+  module RESTfulAPI
+    # Update a member
+    #
+    # @see https://developers.brickftp.com/#update-a-member Update a member
+    #
+    # ### Params
+    #
+    # PARAMETER | TYPE    | DESCRIPTION
+    # --------- | ------- | -----------
+    # admin     | boolean | Indicates whether the user is an administrator of the group.
+    #
+    class UpdateGroupMember
+      include Command
+      using BrickFTP::CoreExt::Struct
+      using BrickFTP::CoreExt::Hash
+
+      Params = Struct.new(
+        'UpdateGroupMemberParams',
+        :admin,
+        keyword_init: true
+      )
+
+      # Updates a user's group membership. 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.
+      # @param [BrickFTP::RESTfulAPI::UpdateGroupMember::Params] params parameters
+      # @return [BrickFTP::Types::GroupMembership] group membership
+      #
+      def call(group_id, user_id, params)
+        res = client.patch("/api/rest/v1/groups/#{group_id}/memberships/#{user_id}.json", membership: params.to_h.compact)
+
+        BrickFTP::Types::GroupMembership.new(res.symbolize_keys)
+      end
+    end
+  end
+end

data/lib/brick_ftp/restful_api/update_user.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+module BrickFTP
+  module RESTfulAPI
+    # Update a user
+    #
+    # @see https://developers.brickftp.com/#update-a-user Update a user
+    #
+    # ### Params
+    #
+    # PARAMETER               | TYPE                     | DESCRIPTION
+    # ----------------------- | ------------------------ | -----------
+    # username                | string                   | Username for the user. This is how the user will be displayed on the site. Maximum of 50 characters.
+    # authentication_method   | enum                     | Authentication method for this user. Can be one of the following: password, ldap, or oauth_google. Default is password.
+    # password                | string                   | Password for the user. This property is write-only. It cannot be retrieved via the API.
+    # password_confirmation   | string                   | Confirms the new password provided in the password field. This field is optional but will be validated if provided.
+    # authenticate_until      | datetime                 | If set, the user will be blocked from logging in after this date.
+    # name                    | string                   | Real name of the user. For your reference. Maximum of 50 characters.
+    # email                   | string                   | E-Mail address of the user. Maximum of 50 characters.
+    # notes                   | text                     | You may use this property to store any additional information you require. There are no restrictions on its formatting.
+    # group_ids               | comma-separated integers | IDs of the Groups that this user is in.
+    # ftp_permission          | boolean                  | Allow user access via FTP/FTPS (port 21 or 990) interface. Default is true.
+    # sftp_permission         | boolean                  | Allow user access via SFTP (port 22) interface. Default is true.
+    # dav_permission          | boolean                  | Allow user access via WebDAV (port 443) interface. Default is true.
+    # restapi_permission      | boolean                  | Allow user access the REST API, via HTTP/HTTPS (port 80 or 443), and the desktop application. Default is true.
+    # attachments_permission  | boolean                  | Allow user to use Sharing tab in web interface to share files with anonymous users via a unique URL. Default is false.
+    # self_managed            | boolean                  | Allow user to change their password and user information via the web interface. Default is true.
+    # require_password_change | boolean                  | Require user to change their password at their next login. Note: requires restapi_permission to be true, as password changes can only occur via the web interface. Default is false.
+    # allowed_ips             | text                     | List allowed IPs, one per line. You may specify a range in CIDR format, such as 192.168.1.0/27. Leave blank to allow all IPs. If you are also restricting IP addresses on the Site tab, users matching in either place will be allowed to log in.
+    # user_root               | string                   | Folder to show as the root when this user logs in via the FTP interface. Make sure this folder exists, as it will not be automatically created. Does not apply to the web interface! This should not contain a leading slash, but must contain a trailing slash. Example: Users/jenny/. Limit of 250 characters.
+    # time_zone               | string                   | File modification times will be displayed in this time zone. Default is Eastern Time (US & Canada).
+    # language                | string                   | The language that BrickFTP will be displayed in, if the translation is available. Leave as default (null) to auto-detect or use the site setting.
+    # grant_permission        | enum                     | Value must be set to full, read, write, preview, read+write, or preview+write. The user will be granted that permission on their FTP root folder as defined by the user_root. This property is write-only. It cannot be retrieved via the User resource of the REST API, though may be obtained with the Permissions resource of the REST API.
+    # ssl_required            | enum                     | Whether or not SSL encryption is required on all connections for this user. Can be one of the following: use_system_setting, always_require, or never_require. Default is use_system_setting.
+    # site_admin              | boolean                  | If set to true, this user will be treated as a site-wide administrator. Default is false.
+    # receive_admin_alerts    | boolean                  | Enable this user to receive alerts sent to site administrators. This property will only be accepted/returned if site_admin is true. Default is false.
+    # subscribe_to_newsletter | boolean                  | Add this user to the BrickFTP newsletter and our mailing list for notices about product updates. This property will only be accepted/returned if site_admin is true. Default is false.
+    # can_create_new_users    | boolean                  | If true, this user will be able to create other users within groups where they have administrator privileges. Default is false.
+    # admin_group_ids         | comma-separated integers | IDs of the Groups that this user is an administrator of.
+    #
+    class UpdateUser
+      include Command
+      using BrickFTP::CoreExt::Struct
+      using BrickFTP::CoreExt::Hash
+
+      Params = Struct.new(
+        'UpdateUserParams',
+        :username,
+        :authentication_method,
+        :password,
+        :password_confirmation,
+        :authenticate_until,
+        :name,
+        :email,
+        :notes,
+        :group_ids,
+        :ftp_permission,
+        :sftp_permission,
+        :dav_permission,
+        :restapi_permission,
+        :attachments_permission,
+        :self_managed,
+        :require_password_change,
+        :allowed_ips,
+        :user_root,
+        :time_zone,
+        :language,
+        :grant_permission,
+        :ssl_required,
+        :site_admin,
+        :receive_admin_alerts,
+        :subscribe_to_newsletter,
+        :can_create_new_users,
+        :admin_group_ids,
+        keyword_init: true
+      )
+
+      # Updates the specified user.
+      #
+      # For additional security, this method requires reauthentication when updating a password unless an API key is used.
+      #
+      # @note The `allowed_ips` may accept only blank value.
+      #
+      #   e.g. When set `"192.168.1.0/27"` to `allowed_ips`, receive following message with 500 error:
+      #
+      #     An unhandled lowlevel error occurred. The application logs may have details.
+      #
+      #
+      # @param [Integer] id Globally unique identifier of each user.
+      #   Each user is given an ID automatically upon creation.
+      # @param [BrickFTP::RESTfulAPI::CreateUser::Params] params parameters for create a user
+      # @return [BrickFTP::Types::User] updated User
+      #
+      def call(id, params)
+        res = client.put("/api/rest/v1/users/#{id}.json", params.to_h.compact)
+
+        BrickFTP::Types::User.new(res.symbolize_keys)
+      end
+    end
+  end
+end