fileboy 0.1.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 8733a37ff97e6459ba45a32878b7daad2dae4c24036aa2c259fe2f0c794b937c
+  data.tar.gz: 2afd08a3e2d9e9690fdead7989696bf4ece30922fa0e7ffd8df77416f4126262
+SHA512:
+  metadata.gz: 291cbb77ae1c0a7cff35c6e839df34a6575f857877634828fb9e377a8bd8d17eaee2d26d4ab0ae09ecfd0fee04b04d207bc1c960e609d9563bf458e8aecddd69
+  data.tar.gz: f7f30b41249df4b3d3dbf9d24d8b0ab0f70fcf6996524b3840606b55c0dfc40f9301ffb888659985d94f8eb49d66b2739ae6d49ac089c6686816854c797458f8

data/CHANGELOG.md

@@ -0,0 +1,17 @@
+# Changelog
+
+## 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.
+
+## 0.1.0
+
+First release.
+
+- Upload files from a path, an IO or a remote URL.
+- Build file URLs and image transform URLs.
+- Download files and images.
+- Videos: upload, data, info, manifest and poster URLs, posters, transcripts.
+- Webhook verification with `Fileboy::Webhook.verify`.
+- Signed access tokens for apps that use a private key.
+- Typed errors and a Rails-friendly `Fileboy.configure` block.

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) CD2 Solutions Ltd
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,150 @@
+# Fileboy for Ruby
+
+The official Ruby client for [Fileboy](https://fileboy.io): upload files and videos, build image
+URLs that resize on the fly, and read video data. It uses only the Ruby standard library.
+
+## Install
+
+```ruby
+# Gemfile
+gem "fileboy"
+```
+
+## Quick start
+
+```ruby
+require "fileboy"
+
+fileboy = Fileboy::Client.new(public_key: ENV["FILEBOY_PUBLIC_KEY"])
+
+file = fileboy.upload_file("report.pdf")   # a path, or any IO
+puts file.id                               # store this
+
+fileboy.build_file_url(file.id, download: true)
+fileboy.build_image_url(file.id, transforms: [{ type: :resize, width: 300 }, { type: :format, format: :webp }])
+# => https://api.fileboy.io/images/get/<id>?transform=resize:300x_;format:webp
+```
+
+## Rails
+
+Configure once, then call `Fileboy.client` anywhere:
+
+```ruby
+# config/initializers/fileboy.rb
+Fileboy.configure do |config|
+  config.public_key = Rails.application.credentials.dig(:fileboy, :public_key)
+  # config.private_key = ...   only if your app uses signed requests
+  # config.api_url = "https://api.fileboy.io"
+end
+```
+
+`FILEBOY_PUBLIC_KEY`, `FILEBOY_PRIVATE_KEY` and `FILEBOY_API_URL` are read from the environment when you do not set them.
+
+## What you can do
+
+| Task | Method |
+| --- | --- |
+| Upload a path or IO | `upload_file(file, name:, mime:, metadata:)` |
+| Upload from a URL | `upload_file_from_url(url, name:, metadata:, expect:)` |
+| File details | `fetch_file_data(id_or_label)` |
+| File URL | `build_file_url(id_or_label, filename:, download:)` |
+| Image URL with transforms | `build_image_url(id_or_label, transforms:, filename:, download:)` |
+| Download bytes | `download_file`, `download_image` |
+| Upload a video | `upload_video(file, name:)` |
+| Video details | `fetch_video_data(id)`, `fetch_video_info(id)` |
+| Manifest and poster URLs | `build_video_manifest_url(id, type: :hls)`, `build_video_poster_url(id)` |
+| Custom poster | `upload_video_poster(video_id, image)` |
+| Transcripts | `upload_video_transcript(id, file, language: "English")`, `fetch_video_transcript(id, transcript_id)` |
+| Signed access token | `create_access_token(read:, write:, upload:, expires_in:)` |
+
+An id that is a UUID is used as is. Anything else is treated as a label in your app. Labels are
+created in the dashboard.
+
+### Image transforms
+
+`transforms:` takes an array of hashes applied in order. The image service supports `resize`,
+`format`, `quality`, `background` and `invert`:
+
+```ruby
+[
+  { type: :resize, width: 200, height: 200, fit: :cover },   # fit: contain cover fill inside outside
+  { type: :resize, width: 400, fit: :contain, position: "top-left", background: "#ffffff" },
+  { type: :format, format: :webp },                          # jpeg png webp tiff bmp
+  { type: :quality, value: 75 },
+  { type: :background, color: "#fff" },
+  { type: :invert }
+]
+```
+
+You can also pass a hash of `name => value`, such as `{ resize: "300x_", format: "webp", quality: 75 }`, or a ready-made string.
+
+## Errors
+
+Every error is a `Fileboy::Error` with `status`, `code` (the API's error code) and `body`.
+
+| Class | When |
+| --- | --- |
+| `Fileboy::AuthenticationError` | 401 |
+| `Fileboy::PermissionError` | 403, including plan limits |
+| `Fileboy::NotFoundError` | 404 |
+| `Fileboy::RateLimitError` | 429 |
+| `Fileboy::BadRequestError` | other 4xx, such as a file that is too large |
+| `Fileboy::ServerError` | 5xx |
+| `Fileboy::ConnectionError` | timeouts and network failures |
+| `Fileboy::InvalidArgumentError`, `Fileboy::ConfigurationError` | bad arguments, before any request |
+
+## Notes
+
+* 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.
+
+## Development
+
+```bash
+bundle install
+bundle exec rspec
+```
+
+The specs run against a local fake server. The transform builder is also checked against
+`packages/sdk-fixtures/transforms.json`, the same cases the Go image parser is tested with.
+
+MIT licensed.
+
+## Webhooks
+
+Verify the requests Fileboy sends to your endpoints. Use the raw body, exactly as received:
+
+```ruby
+# app/controllers/fileboy_webhooks_controller.rb
+class FileboyWebhooksController < ApplicationController
+  skip_forgery_protection
+
+  def create
+    event = Fileboy::Webhook.verify(request.raw_post, request.headers, ENV.fetch("FILEBOY_WEBHOOK_SECRET"))
+    if event["type"] == "video.ready"
+      # event["resource"]["urls"]["hls"], event["resource"]["duration"], ...
+    end
+    head :ok
+  rescue Fileboy::WebhookVerificationError => e
+    head :bad_request # e.code is "invalid_signature", "timestamp_out_of_tolerance", ...
+  end
+end
+```
+
+`verify` returns the parsed event (a Hash with string keys) or raises `Fileboy::WebhookVerificationError`.
+The timestamp must be within 5 minutes (`tolerance_seconds:` changes that). Events carry a unique `id`
+that is the same on every retry, so use it to ignore duplicates. `Fileboy::Webhook.sign(body, timestamp, secret)`
+builds a signature for your own tests.
+
+## Publishing (maintainers)
+
+You need a [RubyGems](https://rubygems.org) account that owns `fileboy` (the first push claims the name). The gemspec requires MFA.
+
+1. Bump `lib/fileboy/version.rb` and add a section to `CHANGELOG.md`.
+2. `bundle exec rspec` must pass.
+3. Build and check the contents: `gem build fileboy.gemspec && tar -tf fileboy-X.Y.Z.gem` (or `gem spec fileboy-X.Y.Z.gem files`).
+4. `gem signin`, then `gem push fileboy-X.Y.Z.gem` and enter the MFA code.
+5. Tag the commit: `git tag ruby-vX.Y.Z && git push origin ruby-vX.Y.Z`.
+
+A pushed version cannot be replaced, only yanked (`gem yank fileboy -v X.Y.Z`), so check step 3 first.

data/fileboy.gemspec

@@ -0,0 +1,29 @@
+require_relative "lib/fileboy/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "fileboy"
+  spec.version = Fileboy::VERSION
+  spec.authors = ["CD2 Solutions"]
+  spec.email = ["hello@fileboy.io"]
+
+  spec.summary = "Official Ruby client for the Fileboy file, image and video API."
+  spec.description = "Upload files and videos to Fileboy, build file URLs and image transform URLs, " \
+                     "and read video data and transcripts. Uses only the Ruby standard library."
+  spec.homepage = "https://fileboy.io/docs/libraries/ruby"
+  spec.license = "MIT"
+  spec.required_ruby_version = ">= 2.7"
+
+  spec.metadata = {
+    "homepage_uri" => spec.homepage,
+    "documentation_uri" => "https://fileboy.io/docs/libraries/ruby",
+    "changelog_uri" => "https://github.com/CD2/Fileboy/blob/master/packages/ruby/CHANGELOG.md",
+    "rubygems_mfa_required" => "true"
+  }
+
+  spec.files = Dir["lib/**/*.rb"] + %w[README.md CHANGELOG.md LICENSE fileboy.gemspec]
+  spec.require_paths = ["lib"]
+
+  spec.add_development_dependency "rake", "~> 13.0"
+  spec.add_development_dependency "rspec", "~> 3.12"
+  spec.add_development_dependency "webrick", "~> 1.8"
+end

data/lib/fileboy/client.rb

@@ -0,0 +1,297 @@
+require "net/http"
+require "uri"
+require "json"
+require "erb"
+require "pathname"
+
+module Fileboy
+  DEFAULT_API_URL = "https://api.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.
+  #
+  #   fileboy = Fileboy::Client.new(public_key: "YOUR_PUBLIC_KEY")
+  #   file = fileboy.upload_file("report.pdf")
+  #   fileboy.build_file_url(file.id)
+  #
+  # 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.
+  class Client
+    attr_reader :public_key, :api_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)
+      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("/")
+      @timeout = timeout
+      @open_timeout = open_timeout
+    end
+
+    # --- URLs ----------------------------------------------------------------------------------
+
+    # URL that serves the original file.
+    #
+    # @param id_or_label [String] a file id, or a label name
+    # @param filename [String, nil] sets the downloaded file name
+    # @param download [Boolean] true to ask the browser to download instead of showing inline
+    def build_file_url(id_or_label, filename: nil, download: false)
+      url = "#{@api_url}/files/get/#{resolve(id_or_label)}"
+      url += "/#{ERB::Util.url_encode(filename)}" if filename
+      url += "?download" if download
+      url
+    end
+
+    # URL that serves an image, optionally transformed.
+    #
+    #   fileboy.build_image_url(id, transforms: [{ type: :resize, width: 300 }, { type: :format, format: :webp }])
+    #   fileboy.build_image_url(id, transforms: { resize: "300x_", format: "webp", quality: 75 })
+    #
+    # See {Fileboy::Transforms.build} for the accepted forms.
+    def build_image_url(id_or_label, transforms: nil, filename: nil, download: false)
+      url = "#{@api_url}/images/get/#{resolve(id_or_label)}"
+      url += "/#{ERB::Util.url_encode(filename)}" if filename
+      params = []
+      transform = Transforms.build(transforms)
+      params << "transform=#{transform}" unless transform.empty?
+      params << "download" if download
+      url += "?#{params.join('&')}" unless params.empty?
+      url
+    end
+
+    # Manifest URL for adaptive playback. `type` is :auto, :hls or :dash.
+    def build_video_manifest_url(video_id, type: :auto)
+      type = type.to_s
+      raise InvalidArgumentError, "type must be auto, hls or dash" unless %w[auto hls dash].include?(type)
+
+      "#{@api_url}/videos/#{video_id}/manifest?type=#{type}"
+    end
+
+    def build_video_poster_url(video_id)
+      "#{@api_url}/videos/#{video_id}/poster"
+    end
+
+    # --- Files ---------------------------------------------------------------------------------
+
+    # Upload a file from a path (String or Pathname) or an IO (File, StringIO, Tempfile).
+    #
+    # @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
+    # @return [Fileboy::FileData]
+    def upload_file(file, name: nil, mime: nil, metadata: nil)
+      io, filename, opened = open_upload(file, name)
+      data = { name: name || filename, mime: mime || Mime.for_filename(filename) }
+      data[:metadata] = stringify(metadata) if metadata
+      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
+      io.close if opened && io
+    end
+
+    def upload_file_from_path(path, **options)
+      upload_file(path.to_s, **options)
+    end
+
+    # 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)
+      payload = { url: url }
+      payload[:name] = name if name
+      payload[:metadata] = stringify(metadata) if metadata
+      payload[:expect] = expect if expect
+      FileData.from_api(request(:post, "/files/upload", json: payload).fetch("data"))
+    end
+
+    # The details of a stored file.
+    def fetch_file_data(id_or_label)
+      FileData.from_api(request(:get, "/files/data/#{resolve(id_or_label)}").fetch("data"))
+    end
+
+    # The bytes of a file. `range` is [first_byte, last_byte].
+    def download_file(id_or_label, range: nil)
+      request(:get, "/files/get/#{resolve(id_or_label)}", raw: true, range: range)
+    end
+
+    # The bytes of an image, optionally transformed.
+    def download_image(id_or_label, transforms: nil, range: nil)
+      path = build_image_url(id_or_label, transforms: transforms).delete_prefix(@api_url)
+      request(:get, path, raw: true, range: range)
+    end
+
+    # --- Videos --------------------------------------------------------------------------------
+
+    # 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.
+    #
+    # @return [Fileboy::Video]
+    def upload_video(file, name: nil, mime: nil)
+      io, filename, opened = open_upload(file, name)
+      data = { name: name || filename }
+      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))
+    ensure
+      io.close if opened && io
+    end
+
+    # Processing state, renditions, poster ids and transcripts for a video. Returns the `data`
+    # object of the response with string keys.
+    def fetch_video_data(video_id)
+      request(:get, "/videos/#{video_id}/data").fetch("data")
+    end
+
+    # Lighter details for a video: id, name, rawVideoUrl, duration, createdAt.
+    def fetch_video_info(video_id)
+      request(:get, "/videos/#{video_id}/info")
+    end
+
+    # Set a custom poster image. Returns the id of the stored image file.
+    def upload_video_poster(video_id, image, name: nil, mime: nil)
+      io, filename, opened = open_upload(image, name)
+      form = [["file", io, { filename: filename, content_type: mime || Mime.for_filename(filename) }]]
+      request(:post, "/videos/#{video_id}/poster/upload", form: form).fetch("data").fetch("id")
+    ensure
+      io.close if opened && io
+    end
+
+    # Attach a text transcript (WebVTT or plain text) in a language. Returns the transcript id.
+    def upload_video_transcript(video_id, file, language:, name: nil, mime: nil)
+      raise InvalidArgumentError, "language is required" if language.to_s.empty?
+
+      io, filename, opened = open_upload(file, name)
+      form = [["file", io, { filename: filename, content_type: mime || text_mime(filename) }],
+              ["data", JSON.generate({ language: language })]]
+      request(:post, "/videos/#{video_id}/transcripts/upload", form: form).fetch("data").fetch("id")
+    ensure
+      io.close if opened && io
+    end
+
+    # The text of a transcript.
+    def fetch_video_transcript(video_id, transcript_id)
+      request(:get, "/videos/#{video_id}/transcripts/#{transcript_id}", raw: true)
+    end
+
+    # The poster image bytes.
+    def download_video_poster(video_id)
+      request(:get, "/videos/#{video_id}/poster", raw: true)
+    end
+
+    # --- Tokens --------------------------------------------------------------------------------
+
+    # A short-lived signed token for handing a browser limited access. Needs a private key.
+    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
+
+      Token.build(
+        public_key: @public_key, private_key: @private_key, expires_in: expires_in,
+        payload: { access: { read: read, write: write, upload: upload } }
+      )
+    end
+
+    private
+
+    # "abcd-..." UUIDs are ids; anything else is a label of this app.
+    def resolve(id_or_label)
+      value = id_or_label.to_s
+      raise InvalidArgumentError, "No id given" if value.empty?
+      return value if value.match?(UUID) || value.include?("+")
+
+      "#{@public_key}+#{ERB::Util.url_encode(value)}"
+    end
+
+    def stringify(metadata)
+      metadata.to_h.each_with_object({}) { |(k, v), memo| memo[k.to_s] = v.to_s }
+    end
+
+    def text_mime(filename)
+      mime = Mime.for_filename(filename)
+      mime.start_with?("text/") ? mime : "text/plain"
+    end
+
+    # Returns [io, filename, opened_by_us]
+    def open_upload(file, name)
+      case file
+      when String, Pathname
+        path = file.to_s
+        raise InvalidArgumentError, "No such file: #{path}" unless File.file?(path)
+
+        [File.open(path, "rb"), File.basename(path), true]
+      else
+        raise InvalidArgumentError, "Pass a path or an IO to upload" unless file.respond_to?(:read)
+
+        filename = name || (file.respond_to?(:path) && file.path ? File.basename(file.path.to_s) : "upload")
+        file.rewind if file.respond_to?(:rewind)
+        [file, filename, false]
+      end
+    end
+
+    def auth_header
+      if @private_key
+        "token #{Token.build(public_key: @public_key, private_key: @private_key, expires_in: 10)}"
+      else
+        "public #{@public_key}"
+      end
+    end
+
+    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["Authorization"] = auth_header
+      req["Accept"] = "application/json" unless raw
+      req["User-Agent"] = "fileboy-ruby/#{VERSION}"
+      req["Range"] = "bytes=#{range[0]}-#{range[1]}" if range
+      if json
+        req["Content-Type"] = "application/json"
+        req.body = JSON.generate(json)
+      elsif form
+        req.set_form(form, "multipart/form-data")
+      end
+
+      response = Net::HTTP.start(
+        uri.hostname, uri.port,
+        use_ssl: uri.scheme == "https", read_timeout: @timeout, write_timeout: @timeout, open_timeout: @open_timeout
+      ) { |http| http.request(req) }
+
+      raise_for_status(response) unless response.is_a?(Net::HTTPSuccess)
+      return response.body if raw
+
+      begin
+        JSON.parse(response.body)
+      rescue JSON::ParserError
+        raise Error.new("Fileboy sent a response that is not JSON", status: response.code.to_i, body: response.body)
+      end
+    rescue Timeout::Error, SocketError, SystemCallError, OpenSSL::SSL::SSLError, IOError, EOFError => e
+      raise ConnectionError, "Could not reach Fileboy at #{@api_url}: #{e.message}"
+    end
+
+    def raise_for_status(response)
+      status = response.code.to_i
+      body = response.body.to_s
+      parsed = begin
+        JSON.parse(body)
+      rescue JSON::ParserError
+        nil
+      end
+      code = parsed.is_a?(Hash) ? parsed["error"].to_s : nil
+      detail = parsed.is_a?(Hash) ? parsed["message"].to_s : body.strip
+      message = "Fileboy responded #{status}#{code.to_s.empty? ? '' : " (#{code})"}#{detail.empty? ? '' : ": #{detail}"}"
+      klass = case status
+              when 401 then AuthenticationError
+              when 403 then PermissionError
+              when 404 then NotFoundError
+              when 429 then RateLimitError
+              when 400..499 then BadRequestError
+              else ServerError
+              end
+      raise klass.new(message, status: status, code: code, body: parsed || body)
+    end
+  end
+end

data/lib/fileboy/errors.rb

@@ -0,0 +1,32 @@
+module Fileboy
+  # Base class for everything this gem raises on purpose.
+  class Error < StandardError
+    # HTTP status of the response, if there was one.
+    attr_reader :status
+    # The `error` code the API sent back, for example "unauthorized" or "file_too_large".
+    attr_reader :code
+    # Parsed JSON body or the raw text of the response.
+    attr_reader :body
+
+    def initialize(message = nil, status: nil, code: nil, body: nil)
+      super(message)
+      @status = status
+      @code = code
+      @body = body
+    end
+  end
+
+  # The client was set up wrongly or called with bad arguments. Raised before any request is made.
+  class ConfigurationError < Error; end
+  class InvalidArgumentError < Error; end
+
+  # The network failed, timed out or the server could not be reached.
+  class ConnectionError < Error; end
+
+  class BadRequestError < Error; end # 400, 413, 415, 422
+  class AuthenticationError < Error; end # 401
+  class PermissionError < Error; end # 403 (includes plan limits)
+  class NotFoundError < Error; end # 404
+  class RateLimitError < Error; end # 429
+  class ServerError < Error; end # 5xx
+end

data/lib/fileboy/file_data.rb

@@ -0,0 +1,37 @@
+require "time"
+
+module Fileboy
+  # The details of one stored file, as returned by an upload or `fetch_file_data`.
+  FileData = Struct.new(
+    :id, :name, :original_filename, :mime, :metadata, :file_size, :content_hash, :signed,
+    :dies_at, :created_at,
+    keyword_init: true
+  ) do
+    # Build from the `data` object of an API response.
+    def self.from_api(data)
+      new(
+        id: data["id"],
+        name: data["name"],
+        original_filename: data["originalFilename"],
+        mime: data["mime"],
+        metadata: data["metadata"] || {},
+        file_size: data["fileSize"],
+        content_hash: data["hash"],
+        signed: data["signed"],
+        dies_at: parse_time(data["diesAt"]),
+        created_at: parse_time(data["createdAt"])
+      )
+    end
+
+    def self.parse_time(value)
+      value.nil? || value == "" ? nil : Time.parse(value)
+    end
+  end
+
+  # The details of one video, as returned by `upload_video`.
+  Video = Struct.new(:id, :name, :raw_file_id, keyword_init: true) do
+    def self.from_api(data)
+      new(id: data["id"], name: data["name"], raw_file_id: data["rawFileId"])
+    end
+  end
+end

data/lib/fileboy/mime.rb

@@ -0,0 +1,27 @@
+module Fileboy
+  # A small extension to MIME type table so uploads from a path get a sensible content type
+  # without another dependency. Pass `mime:` to upload_file for anything not listed here.
+  module Mime
+    TYPES = {
+      ".jpg" => "image/jpeg", ".jpeg" => "image/jpeg", ".png" => "image/png", ".gif" => "image/gif",
+      ".webp" => "image/webp", ".avif" => "image/avif", ".heic" => "image/heic",
+      ".svg" => "image/svg+xml", ".bmp" => "image/bmp", ".tif" => "image/tiff", ".tiff" => "image/tiff",
+      ".mp4" => "video/mp4", ".m4v" => "video/mp4", ".mov" => "video/quicktime",
+      ".webm" => "video/webm", ".mkv" => "video/x-matroska", ".avi" => "video/x-msvideo",
+      ".mp3" => "audio/mpeg", ".wav" => "audio/wav", ".m4a" => "audio/mp4", ".ogg" => "audio/ogg",
+      ".pdf" => "application/pdf", ".zip" => "application/zip", ".json" => "application/json",
+      ".txt" => "text/plain", ".csv" => "text/csv", ".html" => "text/html", ".vtt" => "text/vtt",
+      ".srt" => "text/plain", ".md" => "text/markdown",
+      ".xlsx" => "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+      ".docx" => "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+      ".pptx" => "application/vnd.openxmlformats-officedocument.presentationml.presentation",
+      ".xls" => "application/vnd.ms-excel", ".doc" => "application/msword"
+    }.freeze
+
+    module_function
+
+    def for_filename(name)
+      TYPES.fetch(File.extname(name.to_s).downcase, "application/octet-stream")
+    end
+  end
+end

data/lib/fileboy/token.rb

@@ -0,0 +1,35 @@
+require "openssl"
+require "securerandom"
+require "json"
+
+module Fileboy
+  # Signed tokens for apps that use a private key. The format is `PUBLIC_KEY$NONCE$JWT`, where the
+  # JWT is HS256-signed with the private key. This is what the Fileboy API verifies, and what the
+  # Node client's createAccessToken produces.
+  module Token
+    module_function
+
+    def build(public_key:, private_key:, expires_in: 60, payload: nil, now: Time.now)
+      if public_key.include?("$") || private_key.include?("$")
+        raise InvalidArgumentError, "Keys must not contain a $ symbol"
+      end
+
+      nonce = SecureRandom.alphanumeric(32)
+      iat = now.to_i
+      claims = { "v" => 3, "token" => nonce, "iat" => iat, "exp" => iat + expires_in.to_i }
+      claims["payload"] = payload if payload
+      [public_key, nonce, jwt(claims, private_key)].join("$")
+    end
+
+    def jwt(claims, secret)
+      header = b64(JSON.generate({ "alg" => "HS256", "typ" => "JWT" }))
+      body = b64(JSON.generate(claims))
+      signature = OpenSSL::HMAC.digest("SHA256", secret, "#{header}.#{body}")
+      "#{header}.#{body}.#{b64(signature)}"
+    end
+
+    def b64(data)
+      [data].pack("m0").tr("+/", "-_").delete("=") # base64url without the base64 gem (not a default gem since Ruby 3.4)
+    end
+  end
+end

data/lib/fileboy/transforms.rb

@@ -0,0 +1,118 @@
+module Fileboy
+  # Builds the value of the `transform` query parameter on image URLs, for example
+  # `resize:300x_~fit:cover;format:webp;quality:75`. It only emits what the Fileboy image service
+  # understands: resize, format, quality, background and invert.
+  module Transforms
+    FITS = %w[contain cover fill inside outside].freeze
+    POSITIONS = %w[top-left top top-right left center right bottom-left bottom bottom-right].freeze
+    FORMATS = %w[jpeg jpg png bmp tiff tif webp].freeze
+    TYPES = %w[resize format quality background invert].freeze
+
+    module_function
+
+    # @param transforms [Array<Hash>, Hash, String, nil]
+    #   * an Array of hashes like `{ type: :resize, width: 300, fit: :cover }`, applied in order
+    #   * a Hash of `name => value`, like `{ resize: "300x_", format: "webp", quality: 75 }`
+    #   * a String, passed through untouched
+    # @return [String] the query value, or "" when there is nothing to apply
+    def build(transforms)
+      case transforms
+      when nil then ""
+      when String then transforms
+      when Hash then transforms.map { |name, value| shorthand(name, value) }.compact.join(";")
+      when Array then transforms.map { |t| build_one(t) }.join(";")
+      else
+        raise InvalidArgumentError, "transforms must be an Array, Hash or String"
+      end
+    end
+
+    def shorthand(name, value)
+      return nil if value.nil? || value.to_s.empty?
+      return name.to_s if value == true
+
+      "#{name}:#{value}"
+    end
+
+    def build_one(transform)
+      t = symbolize(transform)
+      type = t[:type].to_s
+      raise InvalidArgumentError, "Unknown transform #{type.inspect}. Use one of: #{TYPES.join(', ')}" unless TYPES.include?(type)
+
+      send("build_#{type}", t)
+    end
+
+    def build_invert(_t)
+      "invert"
+    end
+
+    def build_format(t)
+      "format:#{format_name(t[:format])}"
+    end
+
+    def build_quality(t)
+      value = t[:value]
+      unless value.is_a?(Integer) && value.between?(1, 100)
+        raise InvalidArgumentError, "quality must be a whole number from 1 to 100"
+      end
+
+      "quality:#{value}"
+    end
+
+    def build_background(t)
+      "background:#{color(t[:color])}"
+    end
+
+    def build_resize(t)
+      width = t[:width]
+      height = t[:height]
+      raise InvalidArgumentError, "resize needs a width, a height or both" if width.nil? && height.nil?
+
+      [width, height].compact.each do |n|
+        raise InvalidArgumentError, "resize width and height must be positive whole numbers" unless n.is_a?(Integer) && n.positive?
+      end
+
+      out = "resize:#{width || '_'}x#{height || '_'}"
+      out += "~position:#{position(t[:position])}" if t[:position]
+      out += "~fit:#{choice(t[:fit], FITS, 'fit')}" if t[:fit]
+      out += "~background:#{color(t[:background])}" if t[:background]
+      out += "~format:#{format_name(t[:format])}" if t[:format]
+      out
+    end
+
+    # "right top", "top right" and "top-right" all mean the same corner, which the image service
+    # spells top-right (vertical word first).
+    def position(value)
+      parts = value.to_s.downcase.strip.split(/[\s-]+/)
+      parts = parts.sort_by { |p| %w[top bottom left right].index(p) || 9 } if parts.size == 2
+      choice(parts.join("-"), POSITIONS, "position")
+    end
+
+    def format_name(value)
+      choice(value, FORMATS, "format")
+    end
+
+    def choice(value, allowed, label)
+      v = value.to_s.downcase
+      raise InvalidArgumentError, "Unsupported #{label} #{value.inspect}. Use one of: #{allowed.join(', ')}" unless allowed.include?(v)
+
+      v
+    end
+
+    # "#fff", "#ffffff" and "#ffffff80" become hex(...). Anything already in hex(...) form is kept.
+    def color(value)
+      s = value.to_s
+      return s if s.match?(/\Ahex\(([0-9a-f]{3}|[0-9a-f]{6}|[0-9a-f]{8})\)\z/i)
+
+      hex = s.delete_prefix("#")
+      raise InvalidArgumentError, "Colours must be hex, like #ff8800 (got #{value.inspect})" unless hex.match?(/\A([0-9a-f]{3}|[0-9a-f]{6}|[0-9a-f]{8})\z/i)
+
+      "hex(#{hex})"
+    end
+
+    def symbolize(hash)
+      raise InvalidArgumentError, "Each transform must be a Hash with a :type" unless hash.respond_to?(:to_h)
+
+      hash.to_h.each_with_object({}) { |(k, v), memo| memo[k.to_sym] = v }
+    end
+  end
+end

data/lib/fileboy/version.rb

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

data/lib/fileboy/webhook.rb

@@ -0,0 +1,98 @@
+require "openssl"
+require "json"
+
+module Fileboy
+  # Raised by {Webhook.verify}. `code` is one of "missing_header", "invalid_timestamp",
+  # "timestamp_out_of_tolerance", "invalid_signature" or "invalid_body".
+  class WebhookVerificationError < Error; end
+
+  # Check that a webhook really came from Fileboy and is recent.
+  #
+  # Every delivery is a POST with a JSON body and two headers:
+  #
+  # * `Fileboy-Timestamp`: unix time in seconds when it was sent
+  # * `Fileboy-Signature`: `v1=` and the hex HMAC-SHA256, keyed with your endpoint's signing
+  #   secret, of the string `"<timestamp>.<raw body>"`
+  #
+  # Use the exact bytes received. Parsing and re-serialising the JSON changes them and breaks the
+  # signature.
+  #
+  #   # Rails controller
+  #   event = Fileboy::Webhook.verify(request.raw_post, request.headers, ENV.fetch("FILEBOY_WEBHOOK_SECRET"))
+  #   event["type"] # => "video.ready"
+  module Webhook
+    SIGNATURE_HEADER = "Fileboy-Signature".freeze
+    TIMESTAMP_HEADER = "Fileboy-Timestamp".freeze
+    DEFAULT_TOLERANCE_SECONDS = 300
+
+    module_function
+
+    # The signature Fileboy sends for this secret, timestamp and body. Mostly useful in tests.
+    def sign(raw_body, timestamp, secret)
+      "v1=" + OpenSSL::HMAC.hexdigest("SHA256", secret, "#{timestamp.to_i}.#{raw_body}")
+    end
+
+    # @param raw_body [String] the request body exactly as received
+    # @param headers [#[], Hash] request headers: a Hash in any case, Rails/Rack headers, or any
+    #   object that answers `[]`
+    # @param secret [String] the endpoint's signing secret from the dashboard
+    # @param tolerance_seconds [Integer] how far from now the timestamp may be
+    # @param now [Time] replaces the current time, for tests
+    # @return [Hash] the parsed event, with string keys
+    # @raise [WebhookVerificationError]
+    def verify(raw_body, headers, secret, tolerance_seconds: DEFAULT_TOLERANCE_SECONDS, now: Time.now)
+      unless raw_body.is_a?(String)
+        raise WebhookVerificationError.new("The body must be the raw String received, not parsed JSON", code: "invalid_body")
+      end
+
+      timestamp_header = read_header(headers, TIMESTAMP_HEADER)
+      signature_header = read_header(headers, SIGNATURE_HEADER)
+      if timestamp_header.to_s.empty? || signature_header.to_s.empty?
+        raise WebhookVerificationError.new("Missing #{TIMESTAMP_HEADER} or #{SIGNATURE_HEADER} header", code: "missing_header")
+      end
+      unless timestamp_header.to_s.match?(/\A\d+\z/)
+        raise WebhookVerificationError.new("Timestamp is not a number", code: "invalid_timestamp")
+      end
+
+      timestamp = timestamp_header.to_i
+      if (now.to_i - timestamp).abs > tolerance_seconds
+        raise WebhookVerificationError.new("Timestamp is outside of the allowed time window", code: "timestamp_out_of_tolerance")
+      end
+
+      expected = sign(raw_body, timestamp, secret)
+      # More than one signature may be sent in future, for example while rotating secrets
+      candidates = signature_header.to_s.split(/[\s,]+/).reject(&:empty?)
+      unless candidates.any? { |candidate| secure_compare(candidate, expected) }
+        raise WebhookVerificationError.new("Signature does not match", code: "invalid_signature")
+      end
+
+      begin
+        JSON.parse(raw_body)
+      rescue JSON::ParserError
+        raise WebhookVerificationError.new("Body is not valid JSON", code: "invalid_body")
+      end
+    end
+
+    # Finds a header however the framework spells it: "Fileboy-Signature", "fileboy-signature"
+    # or the Rack env key "HTTP_FILEBOY_SIGNATURE".
+    def read_header(headers, name)
+      variants = [name, name.downcase, "HTTP_#{name.upcase.tr('-', '_')}"]
+      variants.each do |key|
+        value = headers[key] if headers.respond_to?(:[])
+        return value unless value.nil?
+      end
+      if headers.respond_to?(:each_pair)
+        headers.each_pair { |key, value| return value if key.to_s.casecmp?(name) }
+      end
+      nil
+    end
+
+    def secure_compare(a, b)
+      return false unless a.bytesize == b.bytesize
+
+      result = 0
+      a.bytes.zip(b.bytes) { |x, y| result |= x ^ y }
+      result.zero?
+    end
+  end
+end

data/lib/fileboy.rb

@@ -0,0 +1,54 @@
+require "fileboy/version"
+require "fileboy/errors"
+require "fileboy/mime"
+require "fileboy/file_data"
+require "fileboy/transforms"
+require "fileboy/token"
+require "fileboy/webhook"
+require "fileboy/client"
+
+# Official Ruby client for Fileboy (https://fileboy.io).
+#
+#   Fileboy.configure do |config|
+#     config.public_key = ENV["FILEBOY_PUBLIC_KEY"]
+#   end
+#
+#   Fileboy.client.upload_file("report.pdf")
+module Fileboy
+  # Settings for the shared client. Set these once in a Rails initializer.
+  class Configuration
+    attr_accessor :public_key, :private_key, :api_url, :timeout
+
+    def initialize
+      @public_key = ENV["FILEBOY_PUBLIC_KEY"]
+      @private_key = ENV["FILEBOY_PRIVATE_KEY"]
+      @api_url = ENV["FILEBOY_API_URL"] || DEFAULT_API_URL
+      @timeout = 60
+    end
+  end
+
+  class << self
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def configure
+      yield configuration
+      @client = nil
+      configuration
+    end
+
+    # A client built from {configuration}. Memoized, and rebuilt after #configure.
+    def client
+      @client ||= Client.new(
+        public_key: configuration.public_key, private_key: configuration.private_key,
+        api_url: configuration.api_url, timeout: configuration.timeout
+      )
+    end
+
+    def reset!
+      @configuration = nil
+      @client = nil
+    end
+  end
+end

metadata

@@ -0,0 +1,100 @@
+--- !ruby/object:Gem::Specification
+name: fileboy
+version: !ruby/object:Gem::Version
+  version: 0.1.1
+platform: ruby
+authors:
+- CD2 Solutions
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.12'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.12'
+- !ruby/object:Gem::Dependency
+  name: webrick
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.8'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.8'
+description: Upload files and videos to Fileboy, build file URLs and image transform
+  URLs, and read video data and transcripts. Uses only the Ruby standard library.
+email:
+- hello@fileboy.io
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- fileboy.gemspec
+- lib/fileboy.rb
+- lib/fileboy/client.rb
+- lib/fileboy/errors.rb
+- lib/fileboy/file_data.rb
+- lib/fileboy/mime.rb
+- lib/fileboy/token.rb
+- lib/fileboy/transforms.rb
+- lib/fileboy/version.rb
+- lib/fileboy/webhook.rb
+homepage: https://fileboy.io/docs/libraries/ruby
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://fileboy.io/docs/libraries/ruby
+  documentation_uri: https://fileboy.io/docs/libraries/ruby
+  changelog_uri: https://github.com/CD2/Fileboy/blob/master/packages/ruby/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '2.7'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.24
+specification_version: 4
+summary: Official Ruby client for the Fileboy file, image and video API.
+test_files: []