fileboy 0.1.1 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8733a37ff97e6459ba45a32878b7daad2dae4c24036aa2c259fe2f0c794b937c
-  data.tar.gz: 2afd08a3e2d9e9690fdead7989696bf4ece30922fa0e7ffd8df77416f4126262
+  metadata.gz: f032a5828ce3db69a2ac9a2952774a2d5797906ee46c144af088f5bba1188a1e
+  data.tar.gz: b625e71b7d308b922f4fd5ed9bd9821058d4a992732baab9cd64b2cfc8d5e245
 SHA512:
-  metadata.gz: 291cbb77ae1c0a7cff35c6e839df34a6575f857877634828fb9e377a8bd8d17eaee2d26d4ab0ae09ecfd0fee04b04d207bc1c960e609d9563bf458e8aecddd69
-  data.tar.gz: f7f30b41249df4b3d3dbf9d24d8b0ab0f70fcf6996524b3840606b55c0dfc40f9301ffb888659985d94f8eb49d66b2739ae6d49ac089c6686816854c797458f8
+  metadata.gz: 35732881e4adc1331d672f708e30618fc112e5f306093eec6cf27f0edc779a29617ee7124da5d2c7ff4f7abd431673757a85b585c0a1f4662de1e5f148af0ed9
+  data.tar.gz: fb4739be49a85cd9645a20d6bed26e674b02e50c6e8e53c71594ec4bdbd102799e1c106d98e53d9d327ccf36efe91e2087038cb5c761f1583893b7b01cba2870

data/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 0.2.0
+
+- New: manage your app from Ruby. List, change and delete files, videos and labels, and read your usage. These calls need the private key and raise `Fileboy::ConfigurationError` before any request if the client has none.
+- `list_files` and `list_videos` return a `Fileboy::Page` with `items` and `next_cursor`. `each_file` and `each_video` follow every page for you and can be used lazily.
+- `update_file` changes a file's name, type, metadata (merged by default, `replace_metadata: true` to replace) and labels. `delete_files` removes up to 100 files at once.
+- `Fileboy::FileData` has a new `labels` list, filled by the management calls.
+- Errors from these calls use the existing classes (`NotFoundError`, `AuthenticationError`, `PermissionError`, `BadRequestError`, `ServerError`) and keep the API's `code`, message and HTTP `status`.
+
 ## 0.1.1
 
 - Fix: the gem failed to load on Ruby 3.4 because it required the `base64` gem, which is no longer a default gem. It now uses only the standard library.

data/README.md

@@ -78,6 +78,54 @@ created in the dashboard.
 
 You can also pass a hash of `name => value`, such as `{ resize: "300x_", format: "webp", quality: 75 }`, or a ready-made string.
 
+## Managing files
+
+List, change and delete what is stored in your app. These calls are signed, so build the client with
+your private key. With only a public key they raise `Fileboy::ConfigurationError` before any request.
+
+```ruby
+fileboy = Fileboy::Client.new(public_key: "PUBLIC", private_key: "PRIVATE")
+
+# One page, with filters
+page = fileboy.list_files(mime: "image/", metadata: { orderId: "42" }, limit: 100)
+page.items.each { |file| puts "#{file.name} #{file.labels}" }
+page.next_cursor # nil on the last page
+
+# Every page, lazily
+fileboy.each_file(mime: "image/").each { |file| puts file.name }
+fileboy.each_file(label: "logo").first(5)
+
+# Change a file. Metadata is merged and nil removes a key, replace_metadata: true replaces it.
+fileboy.update_file(file.id, name: "new.png", metadata: { owner: "7", old: nil },
+                    labels: { add: ["hero"], remove: ["draft"] })
+fileboy.update_file("hero", name: "x") # a label name works too
+
+fileboy.delete_file(file.id)                    # raises Fileboy::NotFoundError if it is gone
+result = fileboy.delete_files([id1, id2])       # up to 100; result.deleted, .not_found, .failed
+
+fileboy.list_videos(status: :ready).items
+fileboy.update_video(video_id, name: "Launch.mp4")
+fileboy.delete_video(video_id)
+
+fileboy.list_labels                             # [Fileboy::Label]
+fileboy.create_label("hero", file_id: file.id)  # BadRequestError with code "label_taken" if it exists
+fileboy.delete_label("hero")                    # the file is kept
+
+usage = fileboy.fetch_usage
+usage.files; usage.storage_bytes; usage.limits.storage_bytes # a nil limit means none is set
+```
+
+Failures carry the API's `code`, message and HTTP `status`:
+
+```ruby
+begin
+  fileboy.delete_file(id)
+rescue Fileboy::NotFoundError => e
+  e.code   # "file_not_found"
+  e.status # 404
+end
+```
+
 ## Errors
 
 Every error is a `Fileboy::Error` with `status`, `code` (the API's error code) and `body`.
@@ -97,7 +145,7 @@ Every error is a `Fileboy::Error` with `status`, `code` (the API's error code) a
 
 * File, image and video reads need no authorization, so URL builders never sign anything.
 * The shared `demo` key only accepts small images and cannot upload video.
-* There is no endpoint yet to update, delete or list files, so the client has no such methods.
+* Managing files, videos and labels needs the private key. See below.
 
 ## Development
 

data/lib/fileboy/client.rb

@@ -16,8 +16,12 @@ module Fileboy
   #
   # Reading a file (GET /files/get, /images/get, video data) needs no authorization, so URL
   # builders never sign anything. Uploads send your public key, or a signed token when you also
-  # pass a private key.
+  # pass a private key. Listing, changing and deleting files, videos and labels needs the private key.
   class Client
+    HTTP_METHODS = {
+      get: Net::HTTP::Get, post: Net::HTTP::Post, patch: Net::HTTP::Patch, delete: Net::HTTP::Delete
+    }.freeze
+
     attr_reader :public_key, :api_url
 
     # @param public_key [String] your app's public key
@@ -184,6 +188,165 @@ module Fileboy
       request(:get, "/videos/#{video_id}/poster", raw: true)
     end
 
+    # --- Management (needs the private key) ----------------------------------------------------
+    #
+    # These list, change and delete what is stored in your app. They are signed with the private
+    # key, so build the client with `private_key:`. Without one they raise
+    # {Fileboy::ConfigurationError} before any request is made. Failures raise {Fileboy::NotFoundError},
+    # {Fileboy::AuthenticationError}, {Fileboy::PermissionError}, {Fileboy::BadRequestError} (invalid
+    # input, a label name that is taken) or {Fileboy::ServerError}, each with `status`, `code` and
+    # the API's message.
+
+    # One page of your files.
+    #
+    #   page = fileboy.list_files(mime: "image/", limit: 100)
+    #   page.items.each { |file| puts file.name }
+    #   fileboy.list_files(cursor: page.next_cursor) if page.next_cursor
+    #
+    # @param limit [Integer, nil] page size, 1 to 100 (the API default is 50)
+    # @param cursor [String, nil] the `next_cursor` of the previous page
+    # @param sort [Symbol, String, nil] :created_at (default), :name or :file_size
+    # @param order [Symbol, String, nil] :asc or :desc
+    # @param label [String, nil] only the file this label points at
+    # @param mime [String, nil] only types starting with this, like "image/"
+    # @param name [String, nil] only names containing this text
+    # @param hash [String, nil] only files with this SHA1 content hash
+    # @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]
+    # @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)
+      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
+      )
+      Page.from_api(manage(:get, "/files", query: query), FileData)
+    end
+
+    # Every file matching the filters, following every page. Without a block it returns an
+    # Enumerator, so it can be lazy: `fileboy.each_file(mime: "image/").first(10)`.
+    #
+    # Takes the same filters as {#list_files}.
+    def each_file(**filters, &block)
+      return enum_for(:each_file, **filters) unless block
+
+      each_in_pages(:list_files, filters, &block)
+    end
+
+    # Change a file. Only the fields you pass change. `metadata` is merged into the existing
+    # metadata and a nil value removes that key; pass `replace_metadata: true` to replace it all.
+    #
+    #   fileboy.update_file(id, name: "new.png", metadata: { owner: "7", old: nil },
+    #                       labels: { add: ["hero"], remove: ["draft"] })
+    #
+    # @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.
+    # @return [Fileboy::FileData]
+    def update_file(id_or_label, name: nil, mime: nil, metadata: nil, replace_metadata: nil, labels: nil)
+      body = {}
+      body[:name] = name unless name.nil?
+      body[:mime] = mime unless mime.nil?
+      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?
+      unless labels.nil?
+        body[:labels] = {}
+        add = labels[:add] || labels["add"]
+        remove = labels[:remove] || labels["remove"]
+        body[:labels][:add] = Array(add).map(&:to_s) if add
+        body[:labels][:remove] = Array(remove).map(&:to_s) if remove
+      end
+      FileData.from_api(manage(:patch, "/files/#{file_ref(id_or_label)}", json: body).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)
+      manage(:delete, "/files/#{file_ref(id_or_label)}")
+      true
+    end
+
+    # Delete up to 100 files at once. Unknown ids come back in `not_found` instead of raising, so
+    # it is safe to repeat. Ids in `failed` are still there because storage was unreachable, send
+    # them again.
+    #
+    # @param ids [Array<String>]
+    # @return [Fileboy::BulkDeleteResult]
+    def delete_files(ids)
+      ids = Array(ids).map(&:to_s)
+      raise InvalidArgumentError, "No ids given" if ids.empty?
+
+      BulkDeleteResult.from_api(manage(:post, "/files/delete", json: { ids: ids }).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}.
+    #
+    # @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)
+      query = list_query(
+        limit: limit, cursor: cursor, sort: camelize(sort), order: order, name: name, status: status,
+        createdBefore: created_before, createdAfter: created_after
+      )
+      Page.from_api(manage(:get, "/videos", query: query), ManagedVideo)
+    end
+
+    # Every video matching the filters, following every page. See {#each_file}.
+    def each_video(**filters, &block)
+      return enum_for(:each_video, **filters) unless block
+
+      each_in_pages(:list_videos, filters, &block)
+    end
+
+    # Rename a video.
+    #
+    # @return [Fileboy::ManagedVideo]
+    def update_video(video_id, name:)
+      ManagedVideo.from_api(manage(:patch, "/videos/#{path_id(video_id)}", json: { name: name }).fetch("data"))
+    end
+
+    # Delete a video with its original, renditions, posters and transcripts. Returns true.
+    def delete_video(video_id)
+      manage(:delete, "/videos/#{path_id(video_id)}")
+      true
+    end
+
+    # All labels of your app.
+    #
+    # @return [Array<Fileboy::Label>]
+    def list_labels
+      manage(:get, "/labels").fetch("data").map { |data| Label.from_api(data) }
+    end
+
+    # Create a label, optionally pointing at a file. Raises {Fileboy::BadRequestError} with code
+    # "label_taken" when the name exists.
+    #
+    # @return [Fileboy::Label]
+    def create_label(name, file_id: nil)
+      raise InvalidArgumentError, "No name given" if name.to_s.empty?
+
+      body = { name: name }
+      body[:fileId] = file_id if file_id
+      Label.from_api(manage(:post, "/labels", json: body).fetch("data"))
+    end
+
+    # Delete a label. The file it points at is kept. Returns true.
+    def delete_label(name)
+      manage(:delete, "/labels/#{path_id(name, "name")}")
+      true
+    end
+
+    # How many files and videos the app has and how much they store, with the plan limits.
+    #
+    # @return [Fileboy::Usage]
+    def fetch_usage
+      Usage.from_api(manage(:get, "/usage").fetch("data"))
+    end
+
     # --- Tokens --------------------------------------------------------------------------------
 
     # A short-lived signed token for handing a browser limited access. Needs a private key.
@@ -207,6 +370,63 @@ module Fileboy
       "#{@public_key}+#{ERB::Util.url_encode(value)}"
     end
 
+    # Management calls are signed, so they need the private key.
+    def manage(method, path, query: nil, json: nil)
+      unless @private_key
+        raise ConfigurationError, "This needs the app's private key. Create the client with private_key:"
+      end
+
+      path += "?#{query}" if query && !query.empty?
+      request(method, path, json: json)
+    end
+
+    # Query string from a hash. Skips nils, formats times as ISO 8601, expands metadata.
+    def list_query(options)
+      params = []
+      options.each do |key, value|
+        next if value.nil?
+
+        if key == :metadata
+          value.each { |k, v| params << ["metadata[#{k}]", v.to_s] }
+        elsif value.respond_to?(:utc)
+          params << [key.to_s, value.utc.iso8601]
+        else
+          params << [key.to_s, value.to_s]
+        end
+      end
+      params.map { |k, v| "#{ERB::Util.url_encode(k)}=#{ERB::Util.url_encode(v)}" }.join("&")
+    end
+
+    def camelize(value)
+      value&.to_s&.gsub(/_([a-z])/) { Regexp.last_match(1).upcase }
+    end
+
+    def each_in_pages(method, filters)
+      cursor = filters.delete(:cursor)
+      loop do
+        page = public_send(method, **filters, cursor: cursor)
+        page.items.each { |item| yield item }
+        cursor = page.next_cursor
+        break if cursor.nil? || cursor.empty?
+      end
+    end
+
+    # A file id or label for a management path. Labels become PUBLIC_KEY%2BLABEL.
+    def file_ref(id_or_label)
+      value = id_or_label.to_s
+      raise InvalidArgumentError, "No id given" if value.empty?
+
+      # Build the raw reference first so it is percent-encoded exactly once
+      value = "#{@public_key}+#{value}" unless value.match?(UUID) || value.include?("+")
+      ERB::Util.url_encode(value)
+    end
+
+    def path_id(value, what = "id")
+      raise InvalidArgumentError, "No #{what} given" if value.to_s.empty?
+
+      ERB::Util.url_encode(value.to_s)
+    end
+
     def stringify(metadata)
       metadata.to_h.each_with_object({}) { |(k, v), memo| memo[k.to_s] = v.to_s }
     end
@@ -243,7 +463,7 @@ module Fileboy
 
     def request(method, path, json: nil, form: nil, raw: false, range: nil)
       uri = URI.parse("#{@api_url}#{path}")
-      req = (method == :post ? Net::HTTP::Post : Net::HTTP::Get).new(uri)
+      req = HTTP_METHODS.fetch(method).new(uri)
       req["Authorization"] = auth_header
       req["Accept"] = "application/json" unless raw
       req["User-Agent"] = "fileboy-ruby/#{VERSION}"
@@ -262,6 +482,7 @@ module Fileboy
 
       raise_for_status(response) unless response.is_a?(Net::HTTPSuccess)
       return response.body if raw
+      return nil if response.code.to_i == 204 || response.body.to_s.empty?
 
       begin
         JSON.parse(response.body)

data/lib/fileboy/file_data.rb

@@ -1,10 +1,11 @@
 require "time"
 
 module Fileboy
-  # The details of one stored file, as returned by an upload or `fetch_file_data`.
+  # The details of one stored file, as returned by an upload, `fetch_file_data` or the management calls.
+  # `labels` lists the labels pointing at the file and is only filled by the management calls.
   FileData = Struct.new(
     :id, :name, :original_filename, :mime, :metadata, :file_size, :content_hash, :signed,
-    :dies_at, :created_at,
+    :dies_at, :created_at, :labels,
     keyword_init: true
   ) do
     # Build from the `data` object of an API response.
@@ -19,7 +20,8 @@ module Fileboy
         content_hash: data["hash"],
         signed: data["signed"],
         dies_at: parse_time(data["diesAt"]),
-        created_at: parse_time(data["createdAt"])
+        created_at: parse_time(data["createdAt"]),
+        labels: data["labels"] || []
       )
     end
 
@@ -34,4 +36,83 @@ module Fileboy
       new(id: data["id"], name: data["name"], raw_file_id: data["rawFileId"])
     end
   end
+
+  # One page of a list. Enumerable over its items; `next_cursor` is nil on the last page.
+  class Page
+    include Enumerable
+
+    attr_reader :items, :next_cursor
+
+    def self.from_api(body, type)
+      new(items: body.fetch("data").map { |data| type.from_api(data) }, next_cursor: body["nextCursor"])
+    end
+
+    def initialize(items:, next_cursor: nil)
+      @items = items
+      @next_cursor = next_cursor
+    end
+
+    def each(&block)
+      return items.each unless block
+
+      items.each(&block)
+      self
+    end
+
+    def last_page?
+      next_cursor.nil?
+    end
+  end
+
+  # A video as the management API returns it. `status` is "pending", "processing", "ready" or
+  # "failed". `urls` is nil until ready, else a hash with :manifest, :hls, :dash and :poster.
+  ManagedVideo = Struct.new(
+    :id, :name, :created_at, :status, :status_message, :duration, :width, :height, :play_count,
+    :last_played_at, :urls,
+    keyword_init: true
+  ) do
+    def self.from_api(data)
+      urls = data["urls"]
+      new(
+        id: data["id"], name: data["name"], created_at: FileData.parse_time(data["createdAt"]),
+        status: data["status"], status_message: data["statusMessage"], duration: data["duration"],
+        width: data["width"], height: data["height"], play_count: data["playCount"],
+        last_played_at: FileData.parse_time(data["lastPlayedAt"]),
+        urls: urls && urls.each_with_object({}) { |(k, v), memo| memo[k.to_sym] = v }
+      )
+    end
+  end
+
+  # A label. `file_id` is the file it points at, or nil.
+  Label = Struct.new(:id, :name, :created_at, :file_id, keyword_init: true) do
+    def self.from_api(data)
+      new(id: data["id"], name: data["name"], created_at: FileData.parse_time(data["createdAt"]),
+          file_id: data["fileId"])
+    end
+  end
+
+  # The result of `delete_files`. `failed` is a list of {FailedDelete}.
+  BulkDeleteResult = Struct.new(:deleted, :not_found, :failed, keyword_init: true) do
+    def self.from_api(data)
+      new(
+        deleted: data["deleted"] || [], not_found: data["notFound"] || [],
+        failed: (data["failed"] || []).map { |f| FailedDelete.new(id: f["id"], message: f["message"]) }
+      )
+    end
+  end
+  FailedDelete = Struct.new(:id, :message, keyword_init: true)
+
+  # Plan limits. A nil limit means none is set.
+  UsageLimits = Struct.new(:files, :videos, :storage_bytes, keyword_init: true)
+
+  # What the app stores. `storage_bytes` counts files, image copies, video renditions and posters.
+  Usage = Struct.new(:files, :videos, :storage_bytes, :limits, keyword_init: true) do
+    def self.from_api(data)
+      limits = data["limits"] || {}
+      new(
+        files: data["files"], videos: data["videos"], storage_bytes: data["storageBytes"],
+        limits: UsageLimits.new(files: limits["files"], videos: limits["videos"], storage_bytes: limits["storageBytes"])
+      )
+    end
+  end
 end

data/lib/fileboy/version.rb

@@ -1,3 +1,3 @@
 module Fileboy
-  VERSION = "0.1.1"
+  VERSION = "0.2.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: fileboy
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.2.0
 platform: ruby
 authors:
 - CD2 Solutions