Ruby integration

The official Ruby package for Fileboy. Upload files and video, build image transform URLs and read video data from Rails or plain Ruby.

Installation

Install

fileboy

from RubyGems. You need your public key from your app's keys page.

1
bundle add fileboy

Quick start

1
2
3
4
5
6
7
8
require "fileboy"

fileboy = Fileboy::Client.new(public_key: ENV["FILEBOY_PUBLIC_KEY"])

file = fileboy.upload_file("report.pdf")
puts file.id # store this

fileboy.build_image_url(file.id, transforms: [{ type: :resize, width: 300 }])

Upload a file

Pass a path or an open file. The method returns the stored file's details. Save its id.

1
2
3
4
5
6
file = fileboy.upload_file(
  "./exports/report.pdf",
  metadata: { customerId: "cus_123", kind: "monthly-report" }
)

puts file.id # save this

Upload from a URL

Fileboy fetches the file itself, so it never passes through your server.

1
2
3
4
5
photo = fileboy.upload_file_from_url(
  "https://example.com/photo.jpg",
  name: "photo.jpg",
  expect: "image/jpeg"
)

Build file and image URLs

URLs are built locally, with no request.

1
2
3
4
5
6
# the details of one file: name, mime, size, hash, metadata
data = fileboy.fetch_file_data(file.id)

# a URL for a file or an image
link = fileboy.build_file_url(file.id, download: true)
thumb = fileboy.build_image_url(photo.id, transforms: [{ type: :resize, width: 300 }])

Resize images with a URL

Transforms run in the order you list them. The image service supports resize, format, quality, background and invert.

1
2
3
4
5
url = fileboy.build_image_url(photo_id, transforms: [
  { type: :resize, width: 800 },
  { type: :format, format: :webp },
  { type: :quality, value: 80 }
])

Videos

Videos are encoded in the background. Upload, then poll the video's data until it is ready.

1
2
3
4
5
6
7
8
video = fileboy.upload_video("./clips/launch.mp4", name: "Launch day")

# encoding runs in the background: poll until it is ready
data = fileboy.fetch_video_data(video.id)
data["extractionStatus"]

fileboy.build_video_manifest_url(video.id, type: :hls)
fileboy.build_video_poster_url(video.id)

Using it in Rails

1
2
3
4
5
6
7
8
# 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
end

# anywhere in your app
Fileboy.client.upload_file(params[:avatar].tempfile, name: params[:avatar].original_filename)

Webhooks

Check that a webhook really came from Fileboy. Pass the raw request body, exactly as received. The webhooks reference lists every event.

1
2
3
4
5
6
event = Fileboy::Webhook.verify(
  request.raw_post, request.headers, ENV.fetch("FILEBOY_WEBHOOK_SECRET")
)

puts event["resource"]["urls"]["hls"] if event["type"] == "video.ready"
# raises Fileboy::WebhookVerificationError when the signature or timestamp is wrong

The package README lists every method, the error classes and the transform options. Every endpoint is also in the API reference and the OpenAPI spec.