We offer a powerful and customizable javascript library which allows you to integrate Fileboy into your applications in minutes.
The
@cd2/fileboy-nodeSetting up the node library is simple and should only take about 15 minutes to get up and running. The first step is to create a Fileboy account. Once created you need to obtain your API keys by either creating a new application or retrieving them for an existing app.
Firstly, you need to include the
@cd2/fileboy-nodenpm install @cd2/fileboy-node --saveyarn add @cd2/fileboy-node1 2 3 4 5npm install @cd2/fileboy-node --save or yarn add @cd2/fileboy-node
After installing the library you can now create an instance of the Fileboy client, this will give you the ability to control your application such as uploading files. To create the client you will need to supply your API keys.
1 2 3 4 5 6import { Fileboy } from "@cd2/fileboy-node" const fileboy = Fileboy({ publicKey: "YOUR PUBLIC KEY", privateKey: "YOUR PRIVATE KEY", })
Now you have a client created you can use it to interact with your application. To upload a file you can simply call
fileboy.uploadFileThe example shows using the fs package to read a file, then uploading it.
1 2 3 4 5const myFile = fs.readFile("./bobs_face.png") const file = await fileboy.uploadFile( myFile )
Retrieving a file is just as simple by using the
saveFileOptions can be passed as an optional third argument to apply transformations to the file. Read more about them here.
1await fileboy.downloadFile(file.id, "./downloadedFile.png")
The node client has many other functions to help you write clean and understandable code, all of which are documented below.
Construct a URL to retrieve a given file. You can also provide a single argument of an options object containing an additional property of id or label.
id string
The id or label of the file
options (optional) object
options.filename (optional) string
The name of the file to use when using this url to download the file
options.download (optional) boolean
If true then navigating to the produced url will download the file instead of attempting to render it
A URL for the file
Construct a URL to retrieve a given image, optionally supplying a transform to perform. You can also provide a single argument of an options object containing an additional property of id or label.
id string
The id or label of the image
options (optional) object
options.filename (optional) string
The name of the file to use when using this url to download the file
options.download (optional) boolean
If true then navigating to the produced url will download the file instead of attempting to render it
transformations (optional) array of transform objects
Transformations to apply to the image. For a list of transformation options see the transformation section of the docs.
A URL for the image
Given a file id, download the file at return a Buffer containing the file data
id string
The id of the file to download
options (optional) object
options.range (optional) [number, number?]
If given, a range header will be added to the request allowing you to request just a part of the file
The file data
Given an image id, download the image at return a Buffer containing the file data
id string
The id of the image to download
options (optional) object
Options for transforming the image, as described in buildImageUrl.
options.filename (optional) string
The name of the file to use when using this url to download the file
The image data
Given a file id, download the file and store it at the given path
id string
The id of the file to download
filePath string
The path at which to save the file
options (optional) object
options.range (optional) [number, number?]
If given, a range header will be added to the request allowing you to request just a part of the file
Given an image id, download the file and store it at the given path
id string
The id of the image to download
filePath string
The path at which to save the file
options (optional) object
Options for transforming the image, as described in buildImageUrl.
options.filename (optional) string
The name of the file to use when using this url to download the file
Retrieve all of the data for a given file id
id string
The id of the image to download
The file data. Read more about it here
Retrieve all of the data for a given file id
file File | Buffer | Stream | Blob
The file object to generate a hash from
The hash of the file object. Read more about the hash here
This function will return true if the id of the file has the same hash as the given data. This function can be useful when wanting to check if a file has been updated without needing to spend time upload a file.
fileId string
file File | Buffer | Stream | Blob
The file object to generate a hash from
Whether the given file matches that of the one stored against the given fileId.
Finds your files by hash or metadata, following every page. Needs the private key. For paging, sorting and the other filters use listFiles.
filter object
an object specifying how to reduce the number of returned results. Must contain either filter.hash or filter.metadata
filter.hash (optional) string
only return files with a matching hash.
filter.metadata (optional) metadata
{ usage: "logo" }{ usage: "logo", region: "footer" }{ usage: "logo", name: "header-image" }{ usage: "something else" }The a list of all file data which matches the query.
Upload a file.
file File | Buffer | Stream | Blob
The file object to generate a hash from
options (optional) object
additional options to alter the upload
options.name (optional) string
the name of the file being uploaded
options.mime (optional) string
specify a customer mime
options.metadata (optional) metadata
metadata to add to the file
The file data of the uploaded file.
Upload a file from the filesystem.
filePath string
A path to a file to upload
options (optional) object
additional options to alter the upload
options.name (optional) string
the name of the file being uploaded
options.mime (optional) string
specify a customer mime
options.metadata (optional) metadata
metadata to add to the file
The file data of the uploaded file.
Upload a file from a url.
url string
A URL leading to a file
options (optional) object
additional options to alter the upload
options.name (optional) string
the name of the file being uploaded
options.mime (optional) string
specify a customer mime
options.metadata (optional) metadata
metadata to add to the file
options.expect (optional) string or string[]
Expected mime type to be returned from the URL. The upload will fail if the response does not match it.
The file data of the uploaded file.
Lists your files one page at a time, newest first. Needs the private key. Images Fileboy generates when resizing are not listed.
options (optional) object
limit (1 to 100), cursor, sort (createdAt, name or fileSize), order (asc or desc), label, mime (a type prefix such as image/), name (contains), hash, metadata (exact key and value pairs), createdBefore and createdAfter (Date or ISO string).
One page of files, each with labels. Pass nextCursor as cursor for the next page.
Updates a file. Only the fields you pass change. Needs the private key.
fileId string
The id of an uploaded file
data object
Data to update the file with.
data.name (optional) string
A new name for the file.
data.metadata (optional) metadata
Pairs to set, merged into the existing metadata. A null value removes a key.
data.replaceMetadata (optional) boolean
Replace all the metadata with data.metadata instead of merging.
data.mime (optional) string
A new type for the file.
data.labels (optional) { add?: string[], remove?: string[] }
Labels to point at the file or take off it.
data.sharePage (optional) boolean
Turn the file's share page on or off. buildSharePageUrl(id) gives its link, and signSharePageUrl(id, { expiresIn }) a signed link for a file that needs a signed URL.
The updated file, with labels.
Permanently deletes a file, its stored data and cached resized copies, and sends a file.deleted webhook. Throws a notFound error if there is no such file. Needs the private key.
fileId string
The id of an uploaded file
Deletes up to 100 files at once. Unknown ids are reported in notFound instead of throwing, so it is safe to repeat. Needs the private key.
ids string[]
File ids.
Files in failed are still there because storage could not be reached: send them again.
Lists your videos one page at a time. Options: limit, cursor, sort (createdAt or name), order, name, status (pending, processing, ready or failed), tags (videos with every one of them), metadata (pairs that must all match), createdBefore and createdAfter. Each video has its description, tags and metadata.
options (optional) object
Filters and paging.
Changes a video's name, description, tags or metadata. Only what you pass changes. The description shows on the watch page, tags and metadata are private.
videoId string
The video's id.
data.name (optional) string
The new name.
data.description (optional) string | null
Plain text up to 5000 characters. "" or null removes it.
data.tags (optional) string[] | null | { add?, remove? }
A list replaces the tags, null removes them all, { add, remove } changes some. Up to 50 of up to 64 characters, no commas.
data.metadata (optional) Record<string, string | null>
Merged into the existing metadata, null removes a key. replaceMetadata: true replaces it all.
Deletes a video with its original, renditions, posters and transcripts, and sends video.deleted.
videoId string
The video's id.
List, create and delete labels. Deleting a label keeps the file it points at.
name string
The label.
How many files and videos the app has, the bytes it stores and the plan's limits.
What the app stores by kind (images, other files, video originals, renditions, posters, captions, cached image copies), its biggest files and videos, and one total a day. storageBytes matches getUsage().
days (optional) number
How many days of daily totals, 1 to 365. Defaults to 30.
top (optional) number
How many of the biggest files and videos to list, 1 to 50. Defaults to 10.
Checks that a webhook came from Fileboy and is recent, then returns the typed event. It is exported from the package rather than the client, so it does not need your keys. Throws a WebhookVerificationError if the signature does not match or the timestamp is outside the allowed window.
rawBody string | Buffer
The request body exactly as received, not parsed JSON
headers object | Headers
The request headers, for example req.headers in Express
secret string
The endpoint's signing secret from the dashboard
options.toleranceSeconds (optional) number
How far the timestamp may be from now, in seconds. Defaults to 300.
Creates a signed access token that can be used to grant specific permissions.
options object
Options describing the permissions granted by the token.
options.read (optional) boolean | string[]
The files (ids or labels) that this token grants read access to. Providing true is interpreted as 'all files' and providing false is interpreted as 'no files'. Defaults to false.
options.write (optional) boolean | string[]
The files (ids or labels) that this token grants write access to. Providing true is interpreted as 'all files' and providing false is interpreted as 'no files'. Write access includes both updating and deleting. Defaults to false.
options.upload (optional) boolean
Whether or not this token grants permission to upload new files. Defaults to false.
options.expiresInSeconds (optional) number
The number of seconds until the token expires. Defaults to 60.