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.

$3

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();
`

$3

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.

$3

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().then(foundBuckets => {
assert(foundBuckets instanceof BucketCollection);
}).catch(err => {
//Called if there was a problem contacting the API
});
`

$3

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

Example:
`
Bucket.findOneByName().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.

$3

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);
});
`

$3

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

$3

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).

$3

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()); //
`

#### .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\", ... }"
`

$3

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
});
`

$3

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