fileboy 0.2.0 → 0.3.0

data/lib/fileboy/client.rb

@@ -6,6 +6,7 @@ require "pathname"
 
 module Fileboy
   DEFAULT_API_URL = "https://api.fileboy.io".freeze
+  DEFAULT_WEBSITE_URL = "https://fileboy.io".freeze
   UUID = /\A[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\z/i
 
   # A client for one Fileboy app.
@@ -21,19 +22,25 @@ module Fileboy
     HTTP_METHODS = {
       get: Net::HTTP::Get, post: Net::HTTP::Post, patch: Net::HTTP::Patch, delete: Net::HTTP::Delete
     }.freeze
+    # Marks an option that was not passed, where nil has a meaning of its own (the root folder)
+    NOT_GIVEN = Object.new.freeze
+    private_constant :NOT_GIVEN
 
-    attr_reader :public_key, :api_url
+    attr_reader :public_key, :api_url, :website_url
 
     # @param public_key [String] your app's public key
     # @param private_key [String, nil] your app's private key, for signed requests
     # @param api_url [String] override to point at another Fileboy server, for example a CDN host
     # @param timeout [Numeric] seconds to wait for a response (uploads included)
-    def initialize(public_key:, private_key: nil, api_url: DEFAULT_API_URL, timeout: 60, open_timeout: 10)
+    # @param website_url [String] where share pages are built, https://fileboy.io unless you develop Fileboy itself
+    def initialize(public_key:, private_key: nil, api_url: DEFAULT_API_URL, timeout: 60, open_timeout: 10,
+                   website_url: DEFAULT_WEBSITE_URL)
       raise ConfigurationError, "public_key is required" if public_key.to_s.empty?
 
       @public_key = public_key
       @private_key = private_key
       @api_url = api_url.to_s.chomp("/")
+      @website_url = website_url.to_s.chomp("/")
       @timeout = timeout
       @open_timeout = open_timeout
     end
@@ -63,7 +70,7 @@ module Fileboy
       url += "/#{ERB::Util.url_encode(filename)}" if filename
       params = []
       transform = Transforms.build(transforms)
-      params << "transform=#{transform}" unless transform.empty?
+      params << "transform=#{Transforms.encode_query(transform)}" unless transform.empty?
       params << "download" if download
       url += "?#{params.join('&')}" unless params.empty?
       url
@@ -81,6 +88,15 @@ module Fileboy
       "#{@api_url}/videos/#{video_id}/poster"
     end
 
+    # Seek-preview thumbnails of a video: `format: :vtt` (the WebVTT most players read) or :json
+    # (the same as a storyboard). For an app that requires signed reads, add `sign_video`'s query.
+    def build_video_thumbnails_url(video_id, format: :vtt)
+      format = format.to_s
+      raise InvalidArgumentError, "format must be vtt or json" unless %w[vtt json].include?(format)
+
+      "#{@api_url}/videos/#{video_id}/thumbnails.#{format}"
+    end
+
     # --- Files ---------------------------------------------------------------------------------
 
     # Upload a file from a path (String or Pathname) or an IO (File, StringIO, Tempfile).
@@ -88,11 +104,16 @@ module Fileboy
     # @param name [String, nil] name to store the file under. Defaults to the file name.
     # @param mime [String, nil] content type. Guessed from the name when omitted.
     # @param metadata [Hash{String=>String}, nil] custom string key/value pairs stored with the file
+    # @param folder_id [String, nil] put the file in this folder. Without a folder it goes at the root.
+    # @param folder_path [String, nil] put the file in the folder with this path, like "/Products/Shoes".
+    #   With the private key missing folders are created; with only the public key it must exist.
     # @return [Fileboy::FileData]
-    def upload_file(file, name: nil, mime: nil, metadata: nil)
+    def upload_file(file, name: nil, mime: nil, metadata: nil, folder_id: nil, folder_path: nil)
+      add = folder_fields(folder_id, folder_path)
       io, filename, opened = open_upload(file, name)
       data = { name: name || filename, mime: mime || Mime.for_filename(filename) }
       data[:metadata] = stringify(metadata) if metadata
+      data.merge!(add)
       form = [["file", io, { filename: filename, content_type: data[:mime] }], ["data", JSON.generate(data)]]
       FileData.from_api(request(:post, "/files/upload", form: form).fetch("data"))
     ensure
@@ -106,11 +127,13 @@ module Fileboy
     # Ask Fileboy to fetch a public http(s) URL and store the result.
     #
     # @param expect [String, Array<String>, nil] accepted types, like "image/*" or ".png"
-    def upload_file_from_url(url, name: nil, metadata: nil, expect: nil)
+    # @param folder_id, folder_path the folder to put it in, as in {#upload_file}
+    def upload_file_from_url(url, name: nil, metadata: nil, expect: nil, folder_id: nil, folder_path: nil)
       payload = { url: url }
       payload[:name] = name if name
       payload[:metadata] = stringify(metadata) if metadata
       payload[:expect] = expect if expect
+      payload.merge!(folder_fields(folder_id, folder_path))
       FileData.from_api(request(:post, "/files/upload", json: payload).fetch("data"))
     end
 
@@ -135,10 +158,21 @@ module Fileboy
     # Upload a video. Videos are processed in the background: poll {#fetch_video_data} and wait
     # for `extractionStatus` to finish. Not available with the shared demo key.
     #
+    # `description` is plain text shown on the watch page (up to 5000 characters). `tags` (up to
+    # 50, no commas) and `metadata` (your own string key-value data) are private.
+    #
+    #   fileboy.upload_video("intro.mp4", description: "Welcome", tags: ["onboarding"],
+    #                        metadata: { course_id: "c-1" })
+    #
     # @return [Fileboy::Video]
-    def upload_video(file, name: nil, mime: nil)
+    def upload_video(file, name: nil, mime: nil, description: nil, tags: nil, metadata: nil)
       io, filename, opened = open_upload(file, name)
       data = { name: name || filename }
+      data[:description] = description unless description.nil?
+      data[:tags] = Array(tags).map(&:to_s) unless tags.nil?
+      unless metadata.nil?
+        data[:metadata] = metadata.to_h.each_with_object({}) { |(k, v), memo| memo[k.to_s] = v.to_s }
+      end
       form = [["file", io, { filename: filename, content_type: mime || Mime.for_filename(filename) }],
               ["data", JSON.generate(data)]]
       Video.from_api(request(:post, "/videos/upload", form: form))
@@ -214,12 +248,17 @@ module Fileboy
     # @param metadata [Hash, nil] only files whose metadata has all of these pairs
     # @param created_before [Time, String, nil]
     # @param created_after [Time, String, nil]
+    # @param folder_id [String, nil] only the files directly in this folder. "root" for the files in no folder.
+    # @param folder_path [String, nil] only the files directly in the folder with this path. "/" is the root.
+    # @param recursive [Boolean, nil] with folder_id or folder_path, include the files in every subfolder
     # @return [Fileboy::Page] of {Fileboy::FileData}
     def list_files(limit: nil, cursor: nil, sort: nil, order: nil, label: nil, mime: nil, name: nil, hash: nil,
-                   metadata: nil, created_before: nil, created_after: nil)
+                   metadata: nil, created_before: nil, created_after: nil, folder_id: nil, folder_path: nil,
+                   recursive: nil)
       query = list_query(
         limit: limit, cursor: cursor, sort: camelize(sort), order: order, label: label, mime: mime, name: name,
-        hash: hash, metadata: metadata, createdBefore: created_before, createdAfter: created_after
+        hash: hash, metadata: metadata, createdBefore: created_before, createdAfter: created_after,
+        folderId: folder_id, folderPath: folder_path, recursive: recursive
       )
       Page.from_api(manage(:get, "/files", query: query), FileData)
     end
@@ -243,8 +282,11 @@ module Fileboy
     # @param id_or_label [String] a file id, or a label name
     # @param labels [Hash, nil] `{ add: [...], remove: [...] }`. A label points at one file, so
     #   adding one that is on another file moves it here.
+    # @param folder_id [String, nil] move the file to this folder. `folder_id: nil` moves it to the root.
+    # @param folder_path [String, nil] move the file to the folder with this path, creating missing folders
     # @return [Fileboy::FileData]
-    def update_file(id_or_label, name: nil, mime: nil, metadata: nil, replace_metadata: nil, labels: nil)
+    def update_file(id_or_label, name: nil, mime: nil, metadata: nil, replace_metadata: nil, labels: nil,
+                    folder_id: NOT_GIVEN, folder_path: nil, share_page: nil)
       body = {}
       body[:name] = name unless name.nil?
       body[:mime] = mime unless mime.nil?
@@ -259,9 +301,22 @@ module Fileboy
         body[:labels][:add] = Array(add).map(&:to_s) if add
         body[:labels][:remove] = Array(remove).map(&:to_s) if remove
       end
+      body[:folderId] = folder_id unless folder_id.equal?(NOT_GIVEN)
+      body[:folderPath] = folder_path unless folder_path.nil?
+      body[:sharePage] = share_page ? true : false unless share_page.nil?
       FileData.from_api(manage(:patch, "/files/#{file_ref(id_or_label)}", json: body).fetch("data"))
     end
 
+    # A photo's camera, lens, exposure, date taken, GPS position and other EXIF, IPTC and XMP
+    # metadata. It includes personal data (GPS, serial numbers), so it needs the private key;
+    # `personal: false` leaves that out, for example before showing it to your own users.
+    #
+    # @return [Fileboy::FileExif]
+    def fetch_file_exif(id_or_label, personal: true)
+      query = personal == false ? "personal=false" : nil
+      FileExif.from_api(manage(:get, "/files/#{file_ref(id_or_label)}/exif", query: query).fetch("data"))
+    end
+
     # Delete a file and its stored data. Raises {Fileboy::NotFoundError} when there is no such
     # file, which includes one that is already deleted. Returns true.
     def delete_file(id_or_label)
@@ -282,15 +337,37 @@ module Fileboy
       BulkDeleteResult.from_api(manage(:post, "/files/delete", json: { ids: ids }).fetch("data"))
     end
 
+    # Move up to 100 files into a folder. `folder_id: nil` (the default) moves them to the root;
+    # `folder_path:` moves them to the folder with that path, creating missing folders. Unknown ids
+    # come back in `not_found`.
+    #
+    #   fileboy.move_files([id1, id2], folder_path: "/Products/Shoes")
+    #
+    # @return [Fileboy::MoveFilesResult]
+    def move_files(ids, folder_id: nil, folder_path: nil)
+      ids = Array(ids).map(&:to_s)
+      raise InvalidArgumentError, "No ids given" if ids.empty?
+
+      body = { ids: ids }
+      if folder_path.nil?
+        body[:folderId] = folder_id
+      else
+        body[:folderPath] = folder_path
+      end
+      MoveFilesResult.from_api(manage(:post, "/files/move", json: body).fetch("data"))
+    end
+
     # One page of your videos. `status` is :pending, :processing, :ready or :failed, `sort` is
-    # :created_at or :name. Other options are as in {#list_files}.
+    # :created_at or :name. `tags` keeps videos that have every one of the tags (case-sensitive)
+    # and `metadata` those whose metadata has all of the pairs. Other options are as in
+    # {#list_files}.
     #
     # @return [Fileboy::Page] of {Fileboy::ManagedVideo}
-    def list_videos(limit: nil, cursor: nil, sort: nil, order: nil, name: nil, status: nil, created_before: nil,
-                    created_after: nil)
+    def list_videos(limit: nil, cursor: nil, sort: nil, order: nil, name: nil, status: nil, tags: nil,
+                    metadata: nil, created_before: nil, created_after: nil)
       query = list_query(
         limit: limit, cursor: cursor, sort: camelize(sort), order: order, name: name, status: status,
-        createdBefore: created_before, createdAfter: created_after
+        tags: tags, metadata: metadata, createdBefore: created_before, createdAfter: created_after
       )
       Page.from_api(manage(:get, "/videos", query: query), ManagedVideo)
     end
@@ -302,11 +379,35 @@ module Fileboy
       each_in_pages(:list_videos, filters, &block)
     end
 
-    # Rename a video.
+    # Change a video's name, description, tags or metadata. Only the fields you pass change.
+    #
+    #   fileboy.update_video(id, description: "Launch day", tags: { add: ["launch"], remove: ["draft"] },
+    #                        metadata: { order_id: "42", old: nil })
     #
+    # @param description [String, nil] plain text shown on the watch page, "" removes it
+    # @param tags [Array, Hash, nil] an Array replaces the tags ([] removes them all),
+    #   `{ add: [...], remove: [...] }` changes some
+    # @param metadata [Hash, nil] merged into the existing metadata, a nil value removes that key.
+    #   Pass `replace_metadata: true` to replace it all.
     # @return [Fileboy::ManagedVideo]
-    def update_video(video_id, name:)
-      ManagedVideo.from_api(manage(:patch, "/videos/#{path_id(video_id)}", json: { name: name }).fetch("data"))
+    def update_video(video_id, name: nil, description: nil, tags: nil, metadata: nil, replace_metadata: nil)
+      body = {}
+      body[:name] = name unless name.nil?
+      body[:description] = description unless description.nil?
+      if tags.is_a?(Hash)
+        add = tags[:add] || tags["add"]
+        remove = tags[:remove] || tags["remove"]
+        body[:tags] = {}
+        body[:tags][:add] = Array(add).map(&:to_s) if add
+        body[:tags][:remove] = Array(remove).map(&:to_s) if remove
+      elsif !tags.nil?
+        body[:tags] = Array(tags).map(&:to_s)
+      end
+      unless metadata.nil?
+        body[:metadata] = metadata.to_h.each_with_object({}) { |(k, v), memo| memo[k.to_s] = v.nil? ? nil : v.to_s }
+      end
+      body[:replaceMetadata] = replace_metadata unless replace_metadata.nil?
+      ManagedVideo.from_api(manage(:patch, "/videos/#{path_id(video_id)}", json: body).fetch("data"))
     end
 
     # Delete a video with its original, renditions, posters and transcripts. Returns true.
@@ -340,16 +441,229 @@ module Fileboy
       true
     end
 
-    # How many files and videos the app has and how much they store, with the plan limits.
+    # How many files and videos the app has and how much they store, with the limits set on the app.
     #
     # @return [Fileboy::Usage]
     def fetch_usage
       Usage.from_api(manage(:get, "/usage").fetch("data"))
     end
 
+    # An image's colour palette: its dominant colour, up to `colors` main colours (0 to 16, default
+    # 6) with their share of the image, the named swatches (vibrant, muted...) and a readable text
+    # colour for each. Worked out at upload, or on the first request for older images. Files that are
+    # not JPEG, PNG, WebP, BMP or TIFF images raise {Fileboy::BadRequestError} with code
+    # "unsupported_image". In a browser, use the palette transform on an image URL instead.
+    #
+    # @return [Hash] the palette as the API returns it, with string keys ("dominant", "colors",
+    #   "swatches", "transparentShare")
+    def fetch_file_palette(id_or_label, colors: nil)
+      query = colors.nil? ? nil : "colors=#{Integer(colors)}"
+      manage(:get, "/files/#{file_ref(id_or_label)}/palette", query: query).fetch("data")
+    end
+
+    # What the app stores by kind (images, other files, video originals, renditions, posters,
+    # captions and cached copies), its biggest files and videos, and a daily total. `days` (1 to
+    # 365, default 30) is how far back the totals go, `top` (1 to 50, default 10) how many files
+    # and videos are listed. `storage_bytes` is the same total {#fetch_usage} reports.
+    #
+    # @return [Fileboy::StorageUsage]
+    def fetch_storage_usage(days: nil, top: nil)
+      StorageUsage.from_api(manage(:get, "/usage/storage", query: list_query(days: days, top: top)).fetch("data"))
+    end
+
+    # --- Folders (needs the private key) -------------------------------------------------------
+
+    # One page of your folders, sorted by name. With no options it lists every folder.
+    #
+    # @param parent_id [String, nil] only the folders directly in this one. "root" for the top level.
+    # @param name [String, nil] only folders whose name contains this text
+    # @param sort [Symbol, String, nil] :name (default) or :created_at
+    # @param path [String, nil] the folder with exactly this path, like "/Products/Shoes". The page
+    #   holds it or nothing.
+    # @return [Fileboy::Page] of {Fileboy::Folder}
+    def list_folders(parent_id: nil, name: nil, sort: nil, order: nil, limit: nil, cursor: nil, path: nil)
+      query = list_query(
+        parentId: parent_id, name: name, sort: camelize(sort), order: order, limit: limit, cursor: cursor, path: path
+      )
+      Page.from_api(manage(:get, "/folders", query: query), Folder)
+    end
+
+    # Every folder matching the filters, following every page. See {#each_file}.
+    def each_folder(**filters, &block)
+      return enum_for(:each_folder, **filters) unless block
+
+      each_in_pages(:list_folders, filters, &block)
+    end
+
+    # One folder, with its `ancestors`.
+    #
+    # @return [Fileboy::Folder]
+    def fetch_folder(folder_id)
+      Folder.from_api(manage(:get, "/folders/#{path_id(folder_id, "folder id")}").fetch("data"))
+    end
+
+    # Create a folder, at the root or in `parent_id`. Raises {Fileboy::BadRequestError} with code
+    # "folder_exists" when that folder already has one of the same name. Pass `path:` instead to
+    # create every folder on the path that is missing and reuse those that exist.
+    #
+    #   shoes = fileboy.create_folder(path: "/Products/Shoes")
+    #   fileboy.create_folder("Sale", parent_id: shoes.id)
+    #
+    # @return [Fileboy::Folder]
+    def create_folder(name = nil, parent_id: nil, path: nil)
+      if path
+        raise InvalidArgumentError, "Pass a name (and parent_id) or a path, not both" if name || parent_id
+
+        body = { path: path }
+      else
+        raise InvalidArgumentError, "No name given" if name.to_s.empty?
+
+        body = { name: name }
+        body[:parentId] = parent_id if parent_id
+      end
+      Folder.from_api(manage(:post, "/folders", json: body).fetch("data"))
+    end
+
+    # Rename a folder or move it into `parent_id`. `parent_id: nil` moves it to the root. Its files
+    # go with it, and no file URL changes.
+    #
+    # @return [Fileboy::Folder]
+    def update_folder(folder_id, name: nil, parent_id: NOT_GIVEN)
+      body = {}
+      body[:name] = name unless name.nil?
+      body[:parentId] = parent_id unless parent_id.equal?(NOT_GIVEN)
+      Folder.from_api(manage(:patch, "/folders/#{path_id(folder_id, "folder id")}", json: body).fetch("data"))
+    end
+
+    # Delete a folder. By default only an empty folder can be deleted, otherwise it raises
+    # {Fileboy::BadRequestError} with code "folder_not_empty". `contents: :move_to_parent` moves its
+    # files and subfolders up a level first; `contents: :delete` deletes them, files included (at
+    # most 1000 files).
+    #
+    # @return [Fileboy::FolderDeleteResult]
+    def delete_folder(folder_id, contents: nil)
+      path = "/folders/#{path_id(folder_id, "folder id")}"
+      FolderDeleteResult.from_api(manage(:delete, path, query: list_query(contents: camelize(contents))).fetch("data"))
+    end
+
+    # --- Expiring links (needs the private key) ------------------------------------------------
+
+    # Make an expiring link to a file that you can revoke later. The link works until it expires
+    # or is revoked, even if the file is "Signed URLs only" or the app requires signed reads. For a
+    # fresh link on every page view, {#sign_url} is the better tool.
+    #
+    #   link = fileboy.create_file_link(id, expires_in: 7 * 24 * 3600, note: "for the auditors")
+    #   link.url
+    #
+    # @param id_or_label [String] a file id, or a label name
+    # @param expires_in [Integer, nil] whole seconds from now, one minute to 365 days. Give this or `expires_at`.
+    # @param expires_at [Time, DateTime, String, nil] when the link stops working; a String must be ISO 8601 with a zone
+    # @param transform [String, Hash, Array, nil] an image transform, like "resize:400x_;format:webp",
+    #   or any form {Fileboy::Transforms.build} takes
+    # @param download [Boolean] true to ask the browser to download instead of showing inline
+    # @param filename [String, nil] the name the file is served under
+    # @param note [String, nil] a note for yourself, shown in the dashboard
+    # @return [Fileboy::FileLink]
+    def create_file_link(id_or_label, expires_in: nil, expires_at: nil, transform: nil, download: false, filename: nil,
+                         note: nil)
+      raise InvalidArgumentError, "Give exactly one of expires_in or expires_at" if expires_in.nil? == expires_at.nil?
+
+      body = {}
+      body[:expiresIn] = expires_in unless expires_in.nil?
+      body[:expiresAt] = iso_time(expires_at) unless expires_at.nil?
+      transform = Transforms.build(transform)
+      body[:transform] = transform unless transform.empty?
+      body[:download] = true if download
+      body[:filename] = filename.to_s unless filename.to_s.empty?
+      body[:note] = note.to_s unless note.to_s.empty?
+      FileLink.from_api(manage(:post, "/files/#{file_ref(id_or_label)}/links", json: body).fetch("data"))
+    end
+
+    # One page of a file's links, newest first.
+    #
+    # @param status [Symbol, String, nil] :active for only the links that still work, or :all (the default)
+    # @param limit [Integer, nil] page size, 1 to 100
+    # @param cursor [String, nil] the `next_cursor` of the previous page
+    # @return [Fileboy::Page] of {Fileboy::FileLink}
+    def list_file_links(id_or_label, status: nil, limit: nil, cursor: nil)
+      query = list_query(status: status, limit: limit, cursor: cursor)
+      Page.from_api(manage(:get, "/files/#{file_ref(id_or_label)}/links", query: query), FileLink)
+    end
+
+    # Every link of a file, following every page. Without a block it returns an Enumerator.
+    # Takes the same filters as {#list_file_links}.
+    def each_file_link(id_or_label, **filters, &block)
+      return enum_for(:each_file_link, id_or_label, **filters) unless block
+
+      each_in_pages(:list_file_links, filters, id_or_label, &block)
+    end
+
+    # Turn a link off for good. Safe to repeat.
+    #
+    # @return [Fileboy::FileLink] with status "revoked"
+    def revoke_file_link(id_or_label, link_id)
+      path = "/files/#{file_ref(id_or_label)}/links/#{path_id(link_id, 'link id')}"
+      FileLink.from_api(manage(:delete, path).fetch("data"))
+    end
+
     # --- Tokens --------------------------------------------------------------------------------
 
     # A short-lived signed token for handing a browser limited access. Needs a private key.
+    # Sign the URL of a file, image or video so it works when the app requires signed reads.
+    # Needs the private key, so do this on your server. Expires in an hour unless you say otherwise.
+    #
+    #   client.sign_url(client.build_image_url(id, transforms: { resize: [400, 400] }), expires_in: 600)
+    #
+    # @param url [String]
+    # @param expires_in [Integer] seconds from now
+    # @param expires_at [Time, Integer] an exact expiry
+    # @param ip [String, nil] only this address or CIDR range can use the URL
+    # @return [String]
+    def sign_url(url, expires_in: Signing::DEFAULT_EXPIRES_IN, expires_at: nil, ip: nil)
+      raise ConfigurationError, "Signing needs the app's private key. Create the client with private_key:" unless @private_key
+
+      Signing.sign_url(url, @private_key, expires_in: expires_in, expires_at: expires_at, ip: ip)
+    end
+
+    # The file's share page: a page anyone can open, with a preview and a download button. It only
+    # works once the page is turned on (`update_file(id, share_page: true)` or the dashboard). For a
+    # file that needs a signed URL, send {#sign_share_page_url} instead.
+    # @return [String]
+    def build_share_page_url(file_id)
+      raise InvalidArgumentError, "No file id given" if file_id.to_s.empty?
+
+      "#{@website_url}/f/#{ERB::Util.url_encode(file_id.to_s)}"
+    end
+
+    # A share page link for a file that needs a signed URL (Signed URLs only, or an app that requires
+    # signed reads). The page's preview and download stop working when the link expires. Needs the
+    # private key, so do this on your server.
+    # @return [String]
+    def sign_share_page_url(file_id, expires_in: Signing::DEFAULT_EXPIRES_IN, expires_at: nil, ip: nil)
+      sign_url(build_share_page_url(file_id), expires_in: expires_in, expires_at: expires_at, ip: ip)
+    end
+
+    # The query string that unlocks every URL of one video (manifests, segments, poster, captions
+    # and data). Pass it to the video player or add it to any /videos/{id}/... URL.
+    # @return [String]
+    def sign_video(video_id, expires_in: Signing::DEFAULT_EXPIRES_IN, expires_at: nil, ip: nil)
+      raise ConfigurationError, "Signing needs the app's private key. Create the client with private_key:" unless @private_key
+
+      Signing.sign_video_query(video_id, @private_key, expires_in: expires_in, expires_at: expires_at, ip: ip)
+    end
+
+    # Whether reads of this app need a signed URL.
+    # @return [Boolean]
+    def fetch_require_signed_reads
+      manage(:get, "/app/settings").dig("data", "requireSignedReads")
+    end
+
+    # Turn signed reads on or off. Turning them on stops every unsigned link working at once.
+    # @return [Boolean] the new value
+    def update_require_signed_reads(value)
+      manage(:patch, "/app/settings", json: { requireSignedReads: value }).dig("data", "requireSignedReads")
+    end
+
     def create_access_token(read: false, write: false, upload: false, expires_in: 60)
       raise ConfigurationError, "Cannot create access tokens without a private key" unless @private_key
 
@@ -388,6 +702,10 @@ module Fileboy
 
         if key == :metadata
           value.each { |k, v| params << ["metadata[#{k}]", v.to_s] }
+        elsif key == :tags
+          # Tags can't contain commas, so one comma-separated parameter is unambiguous
+          tags = Array(value).map(&:to_s)
+          params << ["tags", tags.join(",")] unless tags.empty?
         elsif value.respond_to?(:utc)
           params << [key.to_s, value.utc.iso8601]
         else
@@ -401,10 +719,10 @@ module Fileboy
       value&.to_s&.gsub(/_([a-z])/) { Regexp.last_match(1).upcase }
     end
 
-    def each_in_pages(method, filters)
+    def each_in_pages(method, filters, *args)
       cursor = filters.delete(:cursor)
       loop do
-        page = public_send(method, **filters, cursor: cursor)
+        page = public_send(method, *args, **filters, cursor: cursor)
         page.items.each { |item| yield item }
         cursor = page.next_cursor
         break if cursor.nil? || cursor.empty?
@@ -427,6 +745,23 @@ module Fileboy
       ERB::Util.url_encode(value.to_s)
     end
 
+    def folder_fields(folder_id, folder_path)
+      raise InvalidArgumentError, "Pass folder_id or folder_path, not both" if folder_id && folder_path
+
+      fields = {}
+      fields[:folderId] = folder_id if folder_id
+      fields[:folderPath] = folder_path if folder_path
+      fields
+    end
+
+    # A Time, DateTime or Date as ISO 8601 in UTC with a trailing Z. Strings are sent as they are.
+    def iso_time(value)
+      return value if value.is_a?(String)
+
+      value = value.to_time if !value.is_a?(Time) && value.respond_to?(:to_time)
+      value.respond_to?(:getutc) ? value.getutc.iso8601 : value.to_s
+    end
+
     def stringify(metadata)
       metadata.to_h.each_with_object({}) { |(k, v), memo| memo[k.to_s] = v.to_s }
     end