mailerlite-ruby 2.0.0 → 2.1.0

data/lib/mailerlite/emails/emails.rb

@@ -0,0 +1,306 @@
+# frozen_string_literal: true
+
+module MailerLite
+  # This is a class for the emails built with the simple editor.
+  #
+  # To create such an email, create a campaign with `editor: MailerLite::Campaigns::EDITOR_SIMPLE` in the email.
+  # The ID of the email is in `data.emails[0].id` of the response.
+  #
+  # IDs are Strings of the digits 0-9. You can also give them as Integers. An empty ID raises
+  # `MailerLite::EmptyIdError`, and an ID with other characters raises `MailerLite::InvalidIdError`.
+  #
+  # Each method returns the `HTTP::Response` with the `MailerLite::ApiResponse` methods. The methods do not raise
+  # for a 4xx or 5xx status: use `response.api_error`. The SDK checks only the IDs in the URL path, and the settings
+  # Hash of `update_settings`. It sends all other values as you give them, and the API checks them.
+  #
+  # Each write needs the etag from the last response for the email, and returns a new etag. The etag covers the
+  # whole email, so send the writes to one email one after another. If the email changed after you read it, the
+  # API returns 409 and `response.api_error.code` is `VERSION_CONFLICT`. Then `response.api_error.etag` is the
+  # current etag.
+  #
+  # Idempotency keys: if a write fails with a network error, you do not know if the API did the write. Give an
+  # `idempotency_key` to the write, and send it again with the same key and the same arguments. If the first request
+  # was a success, the API returns the stored response and does not do the write two times. Then
+  # `response.idempotent_replay?` is true. Use a new key for each write. The API keeps a key for 24 hours.
+  # The key must be 1 to 255 printable ASCII characters. For a key that is not valid, the API returns 400.
+  class Emails
+    # The error code of a write with an etag that is not the current etag of the email.
+    VERSION_CONFLICT = 'version_conflict'
+
+    # Block types. The API can also return types that are not in this list.
+    module BlockType
+      BLOCKQUOTE = 'blockquote'
+      BULLETED_LIST = 'bulleted_list'
+      BUTTON = 'button'
+      CODE = 'code'
+      DIVIDER = 'divider'
+      HEADING = 'heading'
+      IMAGE = 'image'
+      NUMBERED_LIST = 'numbered_list'
+      PARAGRAPH = 'paragraph'
+      SOCIAL_ICON = 'social_icon'
+      # Only reads return this type. You cannot insert a block of this type.
+      TITLE = 'title'
+      VIDEO = 'video'
+    end
+
+    # Positions of a block, for `placement`. `BEFORE` and `AFTER` also need a `block_id`.
+    module BlockPosition
+      AT_START = 'start'
+      AT_END = 'end'
+      BEFORE = 'before'
+      AFTER = 'after'
+    end
+
+    # Where the palette of an email comes from, in `settings[:brand][:mode]`.
+    module BrandMode
+      ACCOUNT = 'account'
+      TEMPLATE = 'template'
+      CUSTOM = 'custom'
+    end
+
+    attr_reader :client
+
+    # Inits the `Emails` class with the specified `client`.
+    #
+    # @param client [MailerLite::Client] the `Client` instance to use
+    def initialize(client: MailerLite::Client.new)
+      @client = client
+    end
+
+    # Returns the email with its settings and blocks, and the etag of the email.
+    #
+    # @param email_id [String, Integer] the ID of the email
+    # @return [HTTP::Response] the response from the API
+    # @raise [MailerLite::EmptyIdError, MailerLite::InvalidIdError, TypeError] if the ID is not valid
+    def get(email_id)
+      email_id = Params.path_id(email_id, 'email_id')
+      Request.call(client, :get, "/emails/#{email_id}")
+    end
+
+    # Returns the HTML that the email sends, and the etag of the email.
+    # The API can return a temporary 503 error. Then try again later.
+    #
+    # @param email_id [String, Integer] the ID of the email
+    # @return [HTTP::Response] the response from the API
+    # @raise [MailerLite::EmptyIdError, MailerLite::InvalidIdError, TypeError] if the ID is not valid
+    def get_html(email_id)
+      email_id = Params.path_id(email_id, 'email_id')
+      Request.call(client, :get, "/emails/#{email_id}/html")
+    end
+
+    # Returns the block and its place in the email, and the etag of the email.
+    # `placement` has the IDs of the blocks `after` and `before` it, or nil.
+    #
+    # @param email_id [String, Integer] the ID of the email
+    # @param block_id [String, Integer] the ID of the block
+    # @return [HTTP::Response] the response from the API
+    # @raise [MailerLite::EmptyIdError, MailerLite::InvalidIdError, TypeError] if an ID is not valid
+    def get_block(email_id:, block_id:)
+      email_id = Params.path_id(email_id, 'email_id')
+      block_id = Params.path_id(block_id, 'block_id')
+      Request.call(client, :get, "/emails/#{email_id}/blocks/#{block_id}")
+    end
+
+    # Inserts a block in the email. Returns the new block and the new etag of the email.
+    #
+    # The API drops the attributes and the `mobile` keys that the block type does not declare, and the write still
+    # succeeds. Then the response has `rejected` with a `message` and the `keys` that the API dropped, for example
+    # `editor_content.attrs.onclick`. When the API drops nothing, the response has no `rejected`.
+    #
+    # @param email_id [String, Integer] the ID of the email
+    # @param etag [String] the etag from the last response for the email
+    # @param type [String] the block type, see `BlockType`. You cannot insert `title`.
+    # @param editor_content [Hash] the content of the block. It can be empty. Its keys are camelCase, for example `textAlign`.
+    # @param placement [Hash, nil] `position` (see `BlockPosition`) and, for `before` and `after`, `block_id`.
+    #   Without it, the API puts the block at the end of the email.
+    # @param idempotency_key [String, nil] a key to send the write again safely, see "Idempotency keys" in the class
+    #   documentation
+    # @return [HTTP::Response] the response from the API
+    # @raise [MailerLite::EmptyIdError, MailerLite::InvalidIdError, TypeError] if an ID is not valid
+    def create_block(email_id:, etag:, type:, editor_content:, placement: nil, idempotency_key: nil)
+      email_id = Params.path_id(email_id, 'email_id')
+      body = block_body(type, editor_content, placement).merge('etag' => etag)
+      Request.call(client, :post, "/emails/#{email_id}/blocks", json: body, idempotency_key: idempotency_key)
+    end
+
+    # Updates a block of the email. The new content replaces the whole content of the block: the API removes the
+    # keys that you do not send. Returns the block and the new etag of the email.
+    #
+    # The API drops the attributes and the `mobile` keys that the block type does not declare, and the write still
+    # succeeds. Then the response has `rejected` with a `message` and the `keys` that the API dropped, for example
+    # `editor_content.mobile.onclick`. When the API drops nothing, the response has no `rejected`.
+    #
+    # @param email_id [String, Integer] the ID of the email
+    # @param block_id [String, Integer] the ID of the block
+    # @param etag [String] the etag from the last response for the email
+    # @param editor_content [Hash] the new content of the block. Its keys are camelCase, for example `textAlign`.
+    # @param idempotency_key [String, nil] a key to send the write again safely, see "Idempotency keys" in the class
+    #   documentation
+    # @return [HTTP::Response] the response from the API
+    # @raise [MailerLite::EmptyIdError, MailerLite::InvalidIdError, TypeError] if an ID is not valid
+    def update_block(email_id:, block_id:, etag:, editor_content:, idempotency_key: nil)
+      email_id = Params.path_id(email_id, 'email_id')
+      block_id = Params.path_id(block_id, 'block_id')
+      body = { 'editor_content' => editor_content, 'etag' => etag }
+      Request.call(client, :patch, "/emails/#{email_id}/blocks/#{block_id}", json: body, idempotency_key: idempotency_key)
+    end
+
+    # Deletes a block of the email, and the blocks in it. The response has only the new etag of the email,
+    # so the method returns the response and not true.
+    #
+    # @param email_id [String, Integer] the ID of the email
+    # @param block_id [String, Integer] the ID of the block
+    # @param etag [String] the etag from the last response for the email
+    # @param idempotency_key [String, nil] a key to send the write again safely, see "Idempotency keys" in the class
+    #   documentation
+    # @return [HTTP::Response] the response from the API
+    # @raise [MailerLite::EmptyIdError, MailerLite::InvalidIdError, TypeError] if an ID is not valid
+    def delete_block(email_id:, block_id:, etag:, idempotency_key: nil)
+      email_id = Params.path_id(email_id, 'email_id')
+      block_id = Params.path_id(block_id, 'block_id')
+      Request.call(client, :delete, "/emails/#{email_id}/blocks/#{block_id}", json: { 'etag' => etag }, idempotency_key: idempotency_key)
+    end
+
+    # Moves a block of the email. Returns the block, its new place in the email, and the new etag of the email.
+    #
+    # @param email_id [String, Integer] the ID of the email
+    # @param block_id [String, Integer] the ID of the block to move
+    # @param etag [String] the etag from the last response for the email
+    # @param placement [Hash] `position` (see `BlockPosition`) and, for `before` and `after`, `block_id`
+    # @param idempotency_key [String, nil] a key to send the write again safely, see "Idempotency keys" in the class
+    #   documentation
+    # @return [HTTP::Response] the response from the API
+    # @raise [MailerLite::EmptyIdError, MailerLite::InvalidIdError, TypeError] if an ID is not valid
+    def move_block(email_id:, block_id:, etag:, placement:, idempotency_key: nil)
+      email_id = Params.path_id(email_id, 'email_id')
+      block_id = Params.path_id(block_id, 'block_id')
+      body = { 'placement' => placement, 'etag' => etag }
+      Request.call(client, :post, "/emails/#{email_id}/blocks/#{block_id}/move", json: body, idempotency_key: idempotency_key)
+    end
+
+    # Validates a block before you insert it. It needs no email and no etag. An invalid block is not an error:
+    # the response has `valid` set to false and the `errors` for each field.
+    #
+    # If a valid block has attributes or `mobile` keys that the block type does not declare, the response has
+    # `rejected` with a `message` and these `keys`. `create_block` and `update_block` drop these keys.
+    # When `valid` is false, the response has no `rejected`.
+    #
+    # @param type [String] the block type, see `BlockType`
+    # @param editor_content [Hash] the content of the block. Its keys are camelCase, for example `textAlign`.
+    # @param placement [Hash, nil] `position` (see `BlockPosition`) and, for `before` and `after`, `block_id`
+    # @return [HTTP::Response] the response from the API, with `valid`, `errors`, `schema` and, in some cases, `rejected`
+    def validate_block(type:, editor_content:, placement: nil)
+      Request.call(client, :post, '/emails/blocks/validate', json: block_body(type, editor_content, placement))
+    end
+
+    # Updates the design settings of the email. Returns the settings and the new etag of the email.
+    #
+    # Send only the keys to change, in the shape of `settings` in the response of `get`. The groups are `brand`,
+    # `layout`, `typography`, `button` and `footer`. The SDK sends exactly the keys of the Hash:
+    # - a key that is not in the Hash does not change;
+    # - an empty String unsets a brand colour, and the email then uses the account value;
+    # - an empty editor document, `{ editor_content: {} }` or `{ editor_content: { content: [] } }`, unsets a footer text;
+    # - other colours, sizes, `button.border_radius` and `brand.style` cannot be empty: an empty String gives a `422` error;
+    # - any other value is the new value. Send style values as Strings, for example '16'.
+    #
+    # The API stores each value that you send, also a value that the email inherits from the account.
+    # `footer.social_links` replaces the whole list: keep the `link_id` of each link to keep its click history.
+    # To apply a preset palette, send its `identifier` from `BrandStyles#get` in `brand.style`.
+    # The response can have `rejected` when the API removed unsafe values.
+    #
+    # @param email_id [String, Integer] the ID of the email
+    # @param etag [String] the etag from the last response for the email
+    # @param settings [Hash] the settings to change, without `etag`
+    # @param idempotency_key [String, nil] a key to send the write again safely, see "Idempotency keys" in the class
+    #   documentation
+    # @return [HTTP::Response] the response from the API
+    # @raise [MailerLite::EmptyIdError, MailerLite::InvalidIdError, TypeError] if the ID is not valid
+    # @raise [ArgumentError] if the settings contain an `etag` key
+    # @raise [TypeError] if the settings are not a Hash
+    def update_settings(email_id:, etag:, settings:, idempotency_key: nil)
+      email_id = Params.path_id(email_id, 'email_id')
+      body = Params.settings(settings).merge('etag' => etag)
+      Request.call(client, :patch, "/emails/#{email_id}/settings", json: body, idempotency_key: idempotency_key)
+    end
+
+    # Validates a change to the design settings of the email with the rules of `update_settings`, and saves nothing.
+    # It needs no etag. Invalid settings are not an error: the response has `valid` set to false and the `errors`
+    # for each field. The response can also have `rejected`.
+    #
+    # @param email_id [String, Integer] the ID of the email
+    # @param settings [Hash] the settings that you want to send to `update_settings`, without `etag`
+    # @return [HTTP::Response] the response from the API, with `valid`, `errors` and `schema`
+    # @raise [MailerLite::EmptyIdError, MailerLite::InvalidIdError, TypeError] if the ID is not valid
+    def validate_settings(email_id:, settings:)
+      email_id = Params.path_id(email_id, 'email_id')
+      Request.call(client, :post, "/emails/#{email_id}/settings/validate", json: settings)
+    end
+
+    # Saves the email as a new template with the name. The API cannot delete templates.
+    #
+    # @param email_id [String, Integer] the ID of the email
+    # @param name [String] the name of the template
+    # @param idempotency_key [String, nil] a key to send the write again safely, see "Idempotency keys" in the class
+    #   documentation
+    # @return [HTTP::Response] the response from the API
+    # @raise [MailerLite::EmptyIdError, MailerLite::InvalidIdError, TypeError] if the ID is not valid
+    def create_template(email_id:, name:, idempotency_key: nil)
+      email_id = Params.path_id(email_id, 'email_id')
+      Request.call(client, :post, "/emails/#{email_id}/templates", json: { 'name' => name }, idempotency_key: idempotency_key)
+    end
+
+    # Returns the saved versions of the email, newest first. `current` marks the version that the email has now.
+    #
+    # @param email_id [String, Integer] the ID of the email
+    # @param page [Integer] the page number of the results to return
+    # @param limit [Integer] the maximum number of versions to return, from 1 to 100
+    # @return [HTTP::Response] the response from the API
+    # @raise [MailerLite::EmptyIdError, MailerLite::InvalidIdError, TypeError] if the ID is not valid
+    def list_versions(email_id, page: nil, limit: nil)
+      email_id = Params.path_id(email_id, 'email_id')
+      Request.call(client, :get, "/emails/#{email_id}/versions", query: Params.query(page: page, limit: limit))
+    end
+
+    # Saves the content and the settings of the email as a new version. If nothing changed after the last version,
+    # the API saves no new version and returns the last version. The status code (`response.code`) is 201 for a new
+    # version and 200 for the last version. Both are a success.
+    #
+    # @param email_id [String, Integer] the ID of the email
+    # @param idempotency_key [String, nil] a key to send the write again safely, see "Idempotency keys" in the class
+    #   documentation
+    # @return [HTTP::Response] the response from the API
+    # @raise [MailerLite::EmptyIdError, MailerLite::InvalidIdError, TypeError] if the ID is not valid
+    def create_version(email_id, idempotency_key: nil)
+      email_id = Params.path_id(email_id, 'email_id')
+      Request.call(client, :post, "/emails/#{email_id}/versions", idempotency_key: idempotency_key)
+    end
+
+    # Restores the email to a version. Returns the email in the shape of `get`, with the new etag. Before the
+    # restore, the API saves the current state as a version, so you can undo the restore.
+    #
+    # @param email_id [String, Integer] the ID of the email
+    # @param version_id [String, Integer] the ID of the version
+    # @param etag [String] the etag from the last response for the email
+    # @param idempotency_key [String, nil] a key to send the write again safely, see "Idempotency keys" in the class
+    #   documentation
+    # @return [HTTP::Response] the response from the API
+    # @raise [MailerLite::EmptyIdError, MailerLite::InvalidIdError, TypeError] if an ID is not valid
+    def restore_version(email_id:, version_id:, etag:, idempotency_key: nil)
+      email_id = Params.path_id(email_id, 'email_id')
+      version_id = Params.path_id(version_id, 'version_id')
+      Request.call(client, :post, "/emails/#{email_id}/versions/#{version_id}/restore", json: { 'etag' => etag }, idempotency_key: idempotency_key)
+    end
+
+    private
+
+    def block_body(type, editor_content, placement)
+      body = {
+        'type' => type,
+        'editor_content' => editor_content
+      }
+      body['placement'] = placement unless placement.nil?
+      body
+    end
+  end
+end

data/lib/mailerlite/errors.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module MailerLite
+  # The base class of the errors of the SDK.
+  class Error < StandardError; end
+
+  # An error response (4xx or 5xx) from the API.
+  #
+  # The SDK does not raise it. Get it with `response.api_error` and raise it if you want to.
+  # It is not an `HTTP::Error`, so code that retries on network errors does not also retry an API error.
+  # It keeps only plain values, so `Marshal.dump` works.
+  #
+  # Note: `HTTP::Response#code` is the numeric status. `ApiError#code` is the String code of the API,
+  # for example `"version_conflict"`. The numeric status is in `ApiError#status`.
+  class ApiError < Error
+    # @return [Integer] the HTTP status code, for example 409
+    attr_reader :status
+    # @return [String, nil] the error code of the API, for example "version_conflict"
+    attr_reader :code
+    # @return [String, nil] the current etag of the email, for a 409 version conflict
+    attr_reader :etag
+    # @return [Hash, nil] the error messages for each field, for some 422 responses
+    attr_reader :errors
+    # @return [String, nil] the message of the API
+    attr_reader :api_message
+    # @return [String] the response body as it is
+    attr_reader :body
+    # @return [Hash] the response headers
+    attr_reader :headers
+
+    # Makes an error from a response. It works for the responses of all methods of the SDK.
+    # A body that is not a JSON object gives nil fields.
+    #
+    # @param response [HTTP::Response] the response
+    # @return [MailerLite::ApiError] the error
+    def self.from_response(response)
+      body = response.body.to_s
+      data = parse(body)
+      new(status: response.code, reason: response.reason, body: body, headers: response.headers.to_h,
+          code: data['code'], etag: data['etag'], errors: data['errors'], api_message: data['message'])
+    end
+
+    def self.parse(body)
+      data = JSON.parse(body)
+      data.is_a?(Hash) ? data : {}
+    rescue JSON::ParserError, EncodingError
+      {}
+    end
+    private_class_method :parse
+
+    # @param status [Integer] the HTTP status code
+    # @param reason [String, nil] the reason phrase of the status
+    # @param code [String, nil] the error code of the API
+    # @param etag [String, nil] the current etag of the email
+    # @param errors [Hash, nil] the error messages for each field
+    # @param api_message [String, nil] the message of the API
+    # @param body [String] the response body
+    # @param headers [Hash] the response headers
+    def initialize(status:, reason: nil, code: nil, etag: nil, errors: nil, api_message: nil, body: '', headers: {})
+      @status = status
+      @code = code
+      @etag = etag
+      @errors = errors
+      @api_message = api_message
+      @body = body
+      @headers = headers
+      super(build_message(reason))
+    end
+
+    private
+
+    # For example "409 Conflict (version_conflict): The email was changed."
+    def build_message(reason)
+      text = [status, reason].compact.join(' ')
+      text += " (#{code})" if code
+      text += ": #{api_message}" if api_message
+      text
+    end
+  end
+
+  # An ID for the URL path is empty. The SDK sends no request.
+  class EmptyIdError < ArgumentError; end
+
+  # An ID for the URL path does not contain only the digits 0-9. The SDK sends no request.
+  class InvalidIdError < ArgumentError; end
+end

data/lib/mailerlite/files/files.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module MailerLite
+  # This is a class for the files of the media library from MailerLite API.
+  class Files
+    # File types for `filter: { type: ... }`. The API can also return types that are not in this list.
+    module FileType
+      IMAGE = 'image'
+      PDF = 'pdf'
+      EPUB = 'epub'
+    end
+
+    # Sort values. The values that start with `-` sort in descending order.
+    module FileSort
+      CREATED_AT = 'created_at'
+      CREATED_AT_DESC = '-created_at'
+      NAME = 'name'
+      NAME_DESC = '-name'
+      SIZE = 'size'
+      SIZE_DESC = '-size'
+    end
+
+    attr_reader :client
+
+    # Inits the `Files` class with the specified `client`.
+    #
+    # @param client [MailerLite::Client] the `Client` instance to use
+    def initialize(client: MailerLite::Client.new)
+      @client = client
+    end
+
+    # Returns the files of the media library. Use their `url` in image blocks.
+    # `width` and `height` are nil for files that are not images. The SDK does not send nil values.
+    #
+    # @param filter [Hash, nil] `name` (a part of the file name) and `type` (see `FileType`)
+    # @param sort [String, nil] see `FileSort`. The default is `-created_at`.
+    # @param page [Integer, nil] the page number of the results to return
+    # @param limit [Integer, nil] the maximum number of files to return, from 1 to 100
+    # @return [HTTP::Response] the response from the API, with the `MailerLite::ApiResponse` methods
+    # @raise [TypeError] if the filter is not a Hash
+    def list(filter: nil, sort: nil, page: nil, limit: nil)
+      Request.call(client, :get, '/files', query: Params.query(filter: filter, sort: sort, page: page, limit: limit))
+    end
+  end
+end

data/lib/mailerlite/groups/groups.rb

@@ -52,15 +52,23 @@ module MailerLite
     # @param group_id [Integer] The id of existing group belonging to the account
     # @param filter[:status] [String] Must be one of the possible statuses: active, unsubscribed, unconfirmed, bounced or junk. Defaults to active.
     # @param limit [Integer] the maximum number of subscribers to return
-    # @param page [Integer] the page number of the results to return
+    # @param cursor [String] the cursor for the page of results to return
+    # @param include [String] the relations to embed, only groups is supported
     # @return [HTTP::Response] the response from the API
-    def get_subscribers(group_id:, filter: {}, limit: nil, cursor: nil, sort: nil)
-      params = {}
-      params['filter[status]'] = filter[:status] if filter.key?(:status)
-      params['limit'] = limit if limit
-      params['sort'] = sort if sort
-      params['cursor'] = cursor if cursor
-      client.http.get("#{MAILERLITE_API_URL}/groups/#{group_id}/subscribers", json: params.compact)
+    def get_subscribers(group_id:, filter: {}, limit: nil, cursor: nil, sort: nil, include: nil)
+      params = QueryParams.filter(filter, %i[status]).merge('limit' => limit, 'sort' => sort, 'cursor' => cursor, 'include' => include)
+      client.http.get(QueryParams.uri("#{MAILERLITE_API_URL}/groups/#{group_id}/subscribers", params))
+    end
+
+    # Imports subscribers into the specified group.
+    # @param group_id [Integer] The id of existing group belonging to the account
+    # @param subscribers [Array] the subscribers to import, each a hash with email, and optional name and fields
+    # @param resubscribe [Boolean] reactivate unsubscribed subscribers, bounced and junk subscribers are not reactivated
+    # @param trigger_automations [Boolean] start the automations the import qualifies for
+    # @return [HTTP::Response] the response from the API
+    def import_subscribers(group_id:, subscribers:, resubscribe: nil, trigger_automations: nil)
+      params = { 'subscribers' => subscribers, 'resubscribe' => resubscribe, 'trigger_automations' => trigger_automations }
+      client.http.post("#{MAILERLITE_API_URL}/groups/#{group_id}/import-subscribers", json: params.compact)
     end
 
     # Assign Subscriber to the specified group.

data/lib/mailerlite/params.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module MailerLite
+  # Checks and helpers for the request parameters of the resources.
+  # The SDK checks only the IDs in the URL path and the values that its code reads. The API checks all other values.
+  # Each check raises before the request, so the SDK sends no request when a value is not valid.
+  module Params
+    module_function
+
+    # Use \A and \z: `$` and \Z also match before a final new line.
+    # Use [0-9]: [[:digit:]] also matches digits that are not ASCII.
+    ID_PATTERN = /\A[0-9]+\z/
+
+    def path_id(value, name)
+      raise EmptyIdError, "`#{name}` must not be empty." if value.nil? || value == ''
+
+      raise TypeError, "`#{name}` type is not valid. Expected String or Integer, got #{value.class}." unless value.is_a?(String) || value.is_a?(Integer)
+
+      id = value.to_s
+      # match? raises for a String with invalid bytes, so check the encoding first.
+      raise InvalidIdError, "`#{name}` must contain only the digits 0-9, got #{id.inspect}." unless id.valid_encoding? && id.ascii_only? && id.match?(ID_PATTERN)
+
+      id
+    end
+
+    def require_hash(value, name)
+      raise TypeError, "`#{name}` type is not valid. Expected Hash, got #{value.class}." unless value.is_a?(Hash)
+
+      value
+    end
+
+    def settings(settings)
+      require_hash(settings, 'settings')
+      # The body has the settings and the etag at the same level. An etag key in the settings can hide the etag argument.
+      raise ArgumentError, '`settings` must not contain `etag`. Use the `etag` argument.' if settings.key?(:etag) || settings.key?('etag')
+
+      settings
+    end
+
+    # It drops nil values and keeps empty Strings.
+    def query(filter: nil, **params)
+      query = {}
+      unless filter.nil?
+        require_hash(filter, 'filter').each do |key, value|
+          query["filter[#{key}]"] = value unless value.nil?
+        end
+      end
+      params.each { |key, value| query[key.to_s] = value unless value.nil? }
+      query
+    end
+
+    def idempotency_headers(key)
+      return {} if key.nil?
+
+      { 'Idempotency-Key' => key }
+    end
+  end
+end

data/lib/mailerlite/query_params.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require 'uri'
+
+module MailerLite
+  # Encodes values for the query string of the MailerLite API.
+  module QueryParams
+    module_function
+
+    def boolean(value)
+      return if value.nil?
+
+      value ? 1 : 0
+    end
+
+    def filter(filter, keys)
+      filter.each_with_object({}) do |(key, value), params|
+        params["filter[#{key}]"] = value.is_a?(Array) ? value.join(',') : value if keys.include?(key)
+      end
+    end
+
+    def report(start_date:, end_date:, shop_id:, excel:)
+      { 'start_date' => start_date, 'end_date' => end_date, 'shop_id' => shop_id, 'excel' => boolean(excel) }
+    end
+
+    def uri(url, params)
+      uri = URI(url)
+      query = URI.encode_www_form(params.compact)
+      uri.query = query unless query.empty?
+      uri
+    end
+  end
+end

data/lib/mailerlite/request.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require 'uri'
+
+module MailerLite
+  # Sends the requests of `Emails`, `BrandStyles` and `Files`.
+  module Request
+    module_function
+
+    # It does not raise for a 4xx or 5xx status.
+    def call(client, method, path, json: nil, query: nil, idempotency_key: nil)
+      headers = Params.idempotency_headers(idempotency_key)
+      # Read the constant here, not when the file loads.
+      uri = URI("#{MAILERLITE_API_URL}#{path}")
+      uri.query = URI.encode_www_form(query) if query && !query.empty?
+      options = {}
+      # `body: nil.to_json` sends "null", so add `json:` only when there is a body.
+      options[:json] = json unless json.nil?
+      http = client.http
+      http = http.headers(headers) unless headers.empty?
+      http.request(method, uri, options).extend(ApiResponse)
+    end
+  end
+end

data/lib/mailerlite/segments/segments.rb

@@ -16,22 +16,20 @@ module MailerLite
     #
     # @param limit [Integer] the maximum number of Segments to return
     # @param page [Integer] the page number of the results to return
+    # @param sort [String] the field to sort by, prefix with - for descending order
     # @return [HTTP::Response] the response from the API
-    def list(limit: nil, page: nil)
-      params = {}
-      params['limit'] = limit if limit
-      params['page'] = page if page
-
-      client.http.get("#{MAILERLITE_API_URL}/segments", json: params.compact)
+    def list(limit: nil, page: nil, sort: nil)
+      client.http.get(QueryParams.uri("#{MAILERLITE_API_URL}/segments", { 'limit' => limit, 'page' => page, 'sort' => sort }))
     end
 
     # Update the specified Segment
     #
     # @param segment_id [String] the ID of the Segments to update
     # @param name [String] the name to update
+    # @param filter [Array] the segment rules
     # @return [HTTP::Response] the response from the API
-    def update(segment_id:, name:)
-      params = { 'name' => name }
+    def update(segment_id:, name:, filter: nil)
+      params = { 'name' => name, 'filter' => filter }
       client.http.put("#{MAILERLITE_API_URL}/segments/#{segment_id}", json: params.compact)
     end
 
@@ -39,12 +37,14 @@ module MailerLite
     # @param segment_id [Integer] The id of existing Segment belonging to the account
     # @param filter[status] [String] Must be one of the possible statuses: active, unsubscribed, unconfirmed, bounced or junk. Defaults to active.
     # @param limit [Integer] the maximum number of subscribers to return
-    # @param after [Integer] The last subscriber id, available in meta.last
+    # @param cursor [String] the cursor for the page of results to return, available in meta.next_cursor
+    # @param after [Integer] deprecated, the API ignores it, use cursor
     # @return [HTTP::Response] the response from the API
-    def get_subscribers(segment_id:, filter: {}, limit: nil, after: nil)
+    def get_subscribers(segment_id:, filter: {}, limit: nil, after: nil, cursor: nil)
       params = {}
       params['filter[status]'] = filter[:status] if filter.key?(:status)
       params['limit'] = limit if limit
+      params['cursor'] = cursor if cursor
       params['after'] = after if after
       uri = URI("#{MAILERLITE_API_URL}/segments/#{segment_id}/subscribers")
       uri.query = URI.encode_www_form(params.compact)