ospry

Node.js bindings for the Ospry image hosting API. Learn more about Ospry at ospry.io.

About

ospry allows developers to upload, download, delete, and change permissions on images stored with Ospry's image hosting services. The most popular use for ospry is to verify client-side image uploads in a process we call image claiming.

The vast majority of users will want to use their secret API key when using ospry. This allows you to claim, delete, and change privacy permissions on individual images. A public key may be used in certain cases where only public upload and download functionality is required (e.g. a CLI tool).

Requirements

To use ospry, you must have an active Ospry account. Sign up for one free at ospry.io.

Each account comes with a "sandbox" pair of public/secret keys for development, and a set of production keys when you're ready to roll.

Installation

Install ospry in your project directory using npm:

npm install ospry

Image Uploading

ospry.up(opts)

Uploads an image to Ospry with a given filename and privacy setting. Uploaded images are public by default.

Returns:

A writeable stream.

Example:

var fstream = fs.createReadStream('foo.jpg');
var uploader = ospry.up({
  filename: 'bar.jpg',
  isPrivate: true,
  imageReady: function(err, imgMetadata) {
    console.log(imgMetadata);
  },  
});

fstream.pipe(uploader);

Arguments:

• filename (required): the filename to be used when the image is uploaded
• isPrivate: the privacy setting for the uploaded image. Defaults to false (public)
• imageReady: a callback for when the upload attempt is complete. Callback is in the form fn(err, imgMetadata), where err is non-null if the upload failed.

Image Downloading

ospry.get(opts)

Downloads an image with the desired formatting and resizing options.

Returns:

A readable stream.

Example:

var downloader = ospry.get({
  url: 'https://abc.ospry.io/foo/bar.jpg',
  format: 'png',
  maxWidth: 200,
});

// Pipe to a file stream
var file = fs.createWriteStream('download.jpg')
downloader.pipe(file);

// Pipe to an http.ServerResponse
downloader.pipe(res);

Arguments:

• url (required): the URL for an Ospry image
• format: desired image format of the downloaded image. Defaults to image's current format.
• maxWidth: desired image width, in pixels
• maxHeight: desired image height, in pixels
• imageReady: a callback for when the download attempt has finished. Callback is in the form fn(err), where err is non-null if the download failed.

ospry.getMetadata(id, fn)

Downloads the metadata for an Ospry image with the provided id.

Example:

var id = 'image-id';
ospry.getMetadata(id, function(err, metadata) {
  if (err !== null) { ... handle error }
  else {
    console.log(metadata);
  }  
});

Arguments:

• id: (required) Ospry id of the requested image
• fn: (required) a callback in the form of fn(err, metadata), where err is non-null if the request failed.

ospry.formatURL(imgURL, opts)

Generates a valid Ospry download URL, including any desired formatting and resizing options.

For private images, the expireSeconds or expireDate options may be specified to provide temporary download access.

The returned URL can be used to download Ospry images directly (e.g. via an HTML <img>'s src attribute).

Returns:

A valid Ospry download URL (synchronously). If expireSeconds or expireDate is specified in the options, the URL will be signed with your secret API key, and can be used to allow temporary download access to the image.

Example:

var url = 'https://foo.ospry.io/bar/baz.jpg';
var formattedURL = ospry.formatURL(url, {
  maxHeight: 120,
  expireSeconds: 60 * 5,
});
...
// Then use formattedURL in your HTML, for instance

Arguments:

• imgURL (required): The image's raw Ospry URL
• opts: {
• format: desired image format, defaults to current image format
• maxWidth: desired image width, in pixels
• maxHeight: desired image height, in pixels
• expireSeconds: the number of seconds (from now) during which a private image can be downloaded with the format URL.
• expireDate: a Date object specifying the last time a private image may be downloaded with the format URL.
• }

Image Management

ospry.makePrivate(id, fn)

Sets an image's privacy setting to private.

A private image can only be downloaded using the secret API key, or with a URL that has been signed with the secret API key using ospry.formatURL.

**Example: **

var id = 'currently-public';
ospry.makePrivate(id, function(err, metadata) {
  if (err !== null) { ...handle error }
  else {
    console.log('Image is now private ', metadata.isPrivate);
  }  
});

Arguments:

• id (required): Ospry id of the image to make private
• fn (required): Callback called when the privacy update has finished. Callback has the form fn(err, metadata), where err is non-null if the update failed.

ospry.makePublic(id, fn)

Sets an image's privacy setting to public.

By default, images uploaded to Ospry are public.

**Example: **

var id = 'currently-private';
ospry.makePublic(id, function(err, metadata) {
  if (err !== null) { ...handle error }
  else {
    console.log('Image is now public: ', !metadata.isPrivate);
  }  
});

Arguments:

• id (required): Ospry id of the image to make public
• fn (required): Callback called when the privacy update has finished. Callback has the form fn(err, metadata), where err is non-null if the update failed.

ospry.del(id, fn)

Deletes an image with the given id. If delete fails, an error will be provided in teh callback. A null error means the delete was successful.

Images can only be deleted using the secret API key.

**Example: **

var id = 'id-to-delete';
ospry.del(id, function(err) {
  if (err !== null) { ...handle error }
  else {
    console.log('Image was deleted!');
  }  
});

Arguments:

• id (required): Ospry id of the image to delete
• fn (required): Callback called when the delete attempt has finished. Callback has the form fn(err), where err is non-null if the delete failed.

ospry.claim(id, fn)

Verifies an image uploaded client-side with ospry.js.

If claiming is enabled as an optional security mechanism on your account, each upload must be verified with your secret API key, or it will be treated as a rogue upload, and deleted from Ospry.

By default, claiming is disabled on your account. You can learn more about the claiming process in Ospry's docs.

**Example: **

var id = 'new-client-upload';
// If claiming is enabled on your account, verify the new upload
ospry.claim(id, function(err, metadata) {
  if (err !== null) { ...handle error }
  else {
    console.log('Image is now claimed!', metadata);
  }  
});

Arguments:

• id (required): Ospry id of the image to claim
• fn (required): Callback called when the claim attempt has finished. Callback has the form fn(err, metadata), where err is non-null if the claim failed.

Reference

Image Metadata

Calls that receive a metadata object in the callback can expect the following format:

{
  id:          // {string}  Ospry image ID
  url:         // {string}  Ospry download URL
  httpsURL:    // {string}  Download URL if your site is served over HTTPS
  timeCreated: // {Date}    Image upload time
  isClaimed:   // {boolean} Whether the image upload has been verified
  isPrivate:   // {boolean} Whether the image is private
  filename:    // {string}  Image filename
  format:      // {string}  Image format (e.g. "jpeg")
  size:        // {number}  Image file size in bytes
  height:      // {number}  Image height in pixels
  width:       // {number}  Image width in pixels
}

Error Handling

Calls that receive an error back in ospry can expect the error to implement the Node Error contract: name, message, stack, plus statusCode when applicable.

For example, a 404 error looks like:

{
  name: `not-found',
  statusCode: 404,
  message: 'Not found.',
  stack: ...
}