Office Bot Image Service Client

Helper library for interacting with the Office Bot Image Service (images.api.office-bot.com).

Getting Started

This library exposes two basic objects for manipulating the image service: Bucket and Image. The below documentation outlines the interaction between these two objects, and some sample code for interacting with them.

Installing

Node

  npm install --save officebot-images-client

Bucket

A bucket is uniquely identified by its name. Buckets cannot be directly manipulated, but provide an easy way of interacting with the objects that have been stored in them.

Instance Methods

These methods can be called from an instantiated bucket. Instantiated buckets are returned from calls like .find or .findOneByName. Buckets can be instantiated manually; however, bucket objects lack the ability to post any data back to the server, so creating a new bucket this way will have no impact on what is stored in the API.

Contents

Returns the array of Image objects stored in this bucket.

Example:

  let images = myBucket.contents();

Name

Returns the name of this bucket

Example:

  let name = myBucket.name();

Static Methods

These methods can be called directly from the Bucket object - the do not require an instance. These are the methods you are likely to use when interacting with buckets.

.find(query={})

This will return a listing of all of the buckets for the current user. Optionally, a query can be passed in to limit the returned results. The object returned from this call is not an array, but a BucketCollection object. See the below documentation on BucketCollection to see how to interact with BucketCollection objects.

Example:

  Bucket.find(<optional query object>).then(foundBuckets => {
    assert(foundBuckets instanceof BucketCollection);
  }).catch(err => {
    //Called if there was a problem contacting the API
  });

.findOneByName(name)

This will return a single bucket instance (even if the bucket doesn't exist in the API).

Example:

  Bucket.findOneByName(<bucket name>).then(foundBucket => {
    assert(foundBucket instanceof Bucket);
  }).catch(err => {
    //Called if there was a problem contacting the API
  });

BucketCollection

For convenience, arrays of buckets (as in the case of calling Bucket.find) are stored in a BucketCollection, instead of a native JavaScript array. BucketCollections provide the following helper methods. The BucketCollection constructor is not exposed through this library.

.buckets()

Calling this method will return the array containing the unerlying buckets. Use this if you want to iterate over the buckets in this BucketCollection.

Example:

  myBucketCollection.buckets().forEach(bucket => {
    assert(bucket instanceof Bucket);
  });

.toString(replacerFn=false, spaces=0)

Returns a string representation of the buckets (and their contents) stores in this collection.

.toJSON()

Calls .toJSON on the underlying Bucket objects and returns an array of those results.

Image

Images contain binary data (the actual image content) and metadata (for searching).

Instance Methods

Most of these instance methods will act as setters when passed a value, and getters otherwise. When acting as a setter, the method will return the current instance (for chaining).

.description(newDescription)

Gets / sets the description for this image. Descriptions aren't searchable, but can provide helpful information to users.

Example:

  myImage.description('This is a sample image');
  console.log(myImage.description()); // "This is a sample image"

.public(setPublic)

Gets / sets the public flag for this image. Images that are public can be viewed by anyone with the link to this resource (users and non-users).

Example:

  myImage.public(true);
  console.log(myImage.public()); // true

.filename(newName)

Gets / sets the name of the file that is being upload. Files must have this attribute set before attempting to save them to the API.

Example:

  myImage.filename('sample-image.jpg');
  console.log(myImage.filename()); // "sample-image.jpg"

.contents(binaryContents)

Gets / set the binary contents for this file. This must be set before calling .save on this instance. This should be used just for setting, as there are much better ways of getting the contents of this image (see .small, .large, and .original).

Example:

  const fs = require('fs');
  myImage.contents(fs.readFileSync('./sample-image.jpg'));
  console.log(myImage.contents()); // <Buffer>

.bucket(newBucketName)

Gets / sets the bucket this image belongs to. The bucket does not need to exist prior to saving an image to it. Bucket names must be lower-case and only contain letters and dashes. Images saved without setting the bucket name will be saved to the "default" bucket for that user.

Example:

  myImage.bucket('sample-bucket');
  console.log(myImage.bucket()); // "sample-bucket"

.tags(newTagList)

Gets / sets an array of tags that can be used to find images. Tags will be converted to an array if a non-array value is passed in.

Example:

  myImage.tags('tag1, tag2, tag3');
  //is the same as
  myImage.tags(['tag1','tag2','tag3']);
  console.log(myImage.tags()); // ['tag1','tag2','tag3']

.contentType(type)

Gets / sets the mimetype for the image being uploaded. This should be set before trying to upload, as the API may reject if it can't figure out what is being uploaded. Common values are image/jpg, image/jpeg, and image/png.

Example:

  myImage.contentType('image/jpg`);
  console.log(myImage.contentType()); // "image/jpg"

.href()

Readonly. This will return the absolute url for this image. This will return undefined for images that have not yet been saved to the API.

  let myImage = new Image();
  console.log(myImage.href()); // undefined
  myImage.save().then(() => {
    console.log(myImage.href()); // "https://images.api.office-bot.com/v1.0/objects/8c912b80-556a-11e8-9c2d-fa7ae01bbebc"
  });

.save()

This will save images back to the API. New images will be POSTed to the server, images that have already been saved or brought down from the server will be PUT to the server using the image's href() value.

Example:

  let myNewImage = new Image();
  // Fill out the rest of the image metadata / contents
  myNewImage.save().then(imageId => {
    console.log(imageId); // "8c912b80-556a-11e8-9c2d-fa7ae01bbebc"
  });

.remove()

This will delete this image from the API. There is no way to undo this. This method will only work for images that have already exist on the server, and will reject with an error otherwise.

Example:

  let myNewImage = new Image();
  myNewImage.remove().then(() => {
    //never gets called
  }).catch(err => {
    console.error(err); // "Invalid href.";
  });

  imageThatAlreadyExists.remove().then(() => {
    //success!
  });

.small()

Helper method to return the small version of this image. This method will return binary data (no metadata). This will always return a jpeg.

Example:

  myImage.small().then(imageData => {
    fs.writeFileSync('./output.jpeg', imageData, 'binary');
  });

.large()

Helper method to return the large version of this image. This method will return binary data (no metadata). This will always return a jpeg.

Example:

  myImage.large().then(imageData => {
    fs.writeFileSync('./output.jpeg', imageData, 'binary');
  });

.original()

Helper method to return the original version of this image. This method will return binary data (no metadata).

Example:

  myImage.original().then(imageData => {
    fs.writeFileSync('./output.jpeg', imageData, 'binary');
  });

.toJSON()

Returns a copy of this image's configuration. This method may have a significant memory impact, and should be used sparingly.

Example:

  myImage.toJSON(); // { resourceId : "8c912b80-556a-11e8-9c2d-fa7ae01bbebc", public : true, ... }

.toString(replacerFn=false,'spaces=0)

Returns a string representation of this image's configuration.

Example:

  console.log(myImage.toString()); // "{ \"resourceId\" : \"8c912b80-556a-11e8-9c2d-fa7ae01bbebc\", \"public\" : \"true\", ... }"

Static Methods

Use these methods for directly interacting with the API before you have an instance of an image.

.find(query={})

Returns an array of Image objects using an optional query.

Example:

  Image.find({bucket : 'samples', public : true}).then(images => {
    //Images is an array
  });

.findById(id, query={})

Finds a single image in the API. The returned Image object will only contain metadata - getting the binary data from the server requires one additional step (see example).

Example:

  Image.findById('8c912b80-556a-11e8-9c2d-fa7ae01bbebc').then(image => {
    console.log(image.href()); // "https://images.api.office-bot.com/v1.0/objects/8c912b80-556a-11e8-9c2d-fa7ae01bbebc";
    image.original().then(binaryContents => {
      fs.writeFileSync(image.filename(), binaryContents, 'binary');
    });
  }).catch(err => {
    //Image not found
  });

.findByIdAndRemove(id, query={})

This will remove a single image from the server. There is likely no reason to ever pass in the optional query object.

Example:

  Image.findByIdAndRemove('8c912b80-556a-11e8-9c2d-fa7ae01bbebc').then(() => {
    //Success - with empty response
  }).catch(err => {
    //could not remove the image - likely an invalid id or insufficient privileges
  });

Model

You should never need to interact with the underlying model, but here it is for debug purposes.

  Image {
    resourceId  : String,
    filename    : String,
    contentType : String,
    public      : Boolean,
    bucket      : String,
    tags        : [String],
    href        : String
  }

Authors

Scott Peterson (Office Bot)

License

This project is licensed under the MIT License