Skip to content

Latest commit

 

History

History
558 lines (385 loc) · 14 KB

README.md

File metadata and controls

558 lines (385 loc) · 14 KB
Raw

InterFAX Node Library

Module Version Build Status

Installation | Getting Started | Contributing | License

Send and receive faxes in Node / Javascript with the InterFAX REST API.

Installation

This library requires Node 4+ and can be installed via NPM.

npm install interfax --save

This module is written in ES6 and is transpiled to ES5 for backwards compatibility. While all documentation below is written in ES6 this module works equally as well in ES5 projects.

Getting started

All our API calls support Promises to handle asynchronous callbacks. For example to send a fax from a PDF file:

var InterFAX = require('interfax');
// or: import InterFAX from 'interfax';
var interfax = new InterFAX();

interfax.deliver({
  faxNumber : '+11111111112',
  file : 'folder/fax.pdf'
}).then(fax => {
  return interfax.outbound.find(fax.id);
  //=> find the fax we just created
}).then(fax => {
  console.log(fax.status);
  //=> the status of the fax we just sent
})
.catch(error => {
  console.log(error);
  //=> an error object
});

Alternatively we also support callbacks instead of promises.

interfax.deliver({
  faxNumber : '+11111111112',
  file : 'folder/fax.pdf'
}, function(error, response) {
  if (error) {
    console.log(error);
    //=> an error object
  } else {
    console.log(response.id);
    //=> the ID of the Fax just created
  }
});

Usage

Client | Account | Outbound | Inbound | Documents | Files

Client

The client follows the 12-factor apps principle and can be either set directly or via environment variables.

var InterFAX = require('interfax');

// Initialize using parameters
var interfax = new InterFAX({
  username: '...',
  password: '...'
});

// Alternative: Initialize using
// environment variables
// * INTERFAX_USERNAME
// * INTERFAX_PASSWORD
var interfax = new InterFAX();

All connections are established over HTTPS. To debug the API calls, simply provide a second parameter to the initializer:

var InterFAX = require('interfax');
var interfax = new InterFAX({
  username: '...',
  password: '...'
}, true); // passing true enables debugging mode

Account

Balance

interfax.account.balance(callback);

Determine the remaining faxing credits in your account.

interfax.account.balance()
  .then(console.log); //=> 9.86

More: documentation

Outbound

Send | Get list | Get completed list | Get record | Get image | Cancel fax | Search

Send fax

.outbound.deliver(options, callback);

Submit a fax to a single destination number.

There are a few ways to send a fax. One way is to directly provide a file path or url.

// with a path
interfax.outbound.deliver({
  faxNumber: '+11111111112',
  file: 'folder/fax.txt'
}).then(fax => {
  console.log(fax) //=> fax object
});

// or with a URL
interfax.outbound.deliver({
  faxNumber: '+11111111112',
  file: 'https://s3.aws.com/example/fax.html'
}).then(...);

InterFAX supports over 20 file types including HTML, PDF, TXT, Word, and many more. For a full list see the Supported File Types documentation.

The returned object is a plain object with just an id. You can use this ID to load more information, get the image, or cancel the sending of the fax.

interfax.outbound.deliver({
  faxNumber: '+11111111112',
  file: 'folder/fax.txt'
}).then(fax => {
  return interfax.outbound.cancel(fax.id);
}).then(success => {
  //=> now the fax is cancelled
});;

Additionally you can create a File with binary data and pass this in as well.

var data = fs.readFileSync('fax.pdf');
interfax.files.create(data, {mimeType: 'application/pdf'})
  .then(function(file) {
    interfax.outbound.deliver({
      faxNumber: "+11111111112",
      file: file
    });
  });

To send multiple files just pass in an array of strings and File objects.

interfax.outbound.deliver({
  faxNumber: "+11111111112",
  files: ['file://fax.pdf', 'https://s3.aws.com/example/fax.html']
}).then(...);

Under the hood every path and string is turned into a File object. For more information see the documentation for this class.

Additionally this API will automatically detect large files and upload them in chunks using the Documents API.

Options: contact, postponeTime, retriesToPerform, csid, pageHeader, reference, pageSize, fitToPage, pageOrientation, resolution, rendering

Alias: interfax.deliver

Get outbound fax list

interfax.outbound.all(options, callback);

Get a list of recent outbound faxes (which does not include batch faxes).

interfax.outbound.all({
  limit: 5
}).then(faxes => {
  console.log(faxes); //=> an array of fax objects
});

Options: limit, lastId, sortOrder, userId

Get completed fax list

interfax.outbound.completed(array_of_ids, callback);

Get details for a subset of completed faxes from a submitted list. (Submitted id's which have not completed are ignored).

interfax.outbound.completed([123, 234])
  .then(faxes => {
    console.log(faxes); //=> an array of fax objects
  });

More: documentation

Get outbound fax record

interfax.outbound.find(fax_id, callback);

Retrieves information regarding a previously-submitted fax, including its current status.

interfax.outbound.find(123456)
  .then(fax => {
    console.log(fax); //=> fax object
  });

More: documentation

Get outbound fax image

interfax.outbound.image(fax_id, callback);

Retrieve the fax image (TIFF or PDF file) of a submitted fax.

interfax.outbound.image(123456)
  .then(image => {
    console.log(image.dataBuffer); //=> TIFF/PDF image data
    image.save(`path/to/file.${image.extension}`); //=> saves image to file
  });

More: documentation

Cancel a fax

interfax.outbound.cancel(fax_id, callback);

Cancel a fax in progress.

interfax.outbound.cancel(123456)
  .then(fax => {
    console.log(fax); //=> fax object
  });

More: documentation

Search fax list

interfax.outbound.search(options, callback);

Search for outbound faxes.

interfax.outbound.search({
  faxNumber: '+1230002305555'
}).then(faxes => {
  console.log(faxes); //=> an array of fax objects
});

Options: ids, reference, dateFrom, dateTo, status, userId, faxNumber, limit, offset

Inbound

Get list | Get record | Get image | Get emails | Mark as read | Resend to email

Get inbound fax list

interfax.inbound.all(options, callback);

Retrieves a user's list of inbound faxes. (Sort order is always in descending ID).

interfax.inbound.all({
  limit: 5
}).then(faxes => {
  console.log(faxes); //=> an array of fax objects
});

Options: unreadOnly, limit, lastId, allUsers

Get inbound fax record

interfax.inbound.find(fax_id, callback);

Retrieves a single fax's metadata (receive time, sender number, etc.).

interfax.inbound.find(123456)
  .then(fax => {
    console.log(fax); //=> fax object
  });

More: documentation

Get inbound fax image

interfax.inbound.image(fax_id, callback);

Retrieves a single fax's image.

interfax.inbound.image(123456)
  .then(image => {
    console.log(image.dataBuffer); //=> TIFF or PDF image data
    image.save(`path/to/file.${image.extension}`); //=> saves image to file
  });

More: documentation

Get forwarding emails

interfax.inbound.emails(fax_id, callback);

Retrieve the list of email addresses to which a fax was forwarded.

interfax.inbound.emails(123456)
  .then(emails => {
    console.log(emails); //=> a list of email objects
  });

More: documentation

Mark as read/unread

interfax.inbound.mark(fax_id, is_read, callback);

Mark a transaction as read/unread.

// mark as read
interfax.inbound.mark(123456, true)
  .then((success) => {
    console.log(success); // boolean
  });

// mark as unread
interfax.inbound.mark(123456, false)
  .then((success) => {
    console.log(success); // boolean
  });

More: documentation

Resend inbound fax

interfax.inbound.resend(fax_id, to_email, callback);

Resend an inbound fax to a specific email address.

// resend to the email(s) to which the fax was previously forwarded
interfax.inbound.resend(123456)
  .then((success) => {
    console.log(success); // boolean
  });

// resend to a specific address
interfax.inbound.resend(123456, '[email protected]')
  .then((success) => {
    console.log(success); // boolean
  });
=> true

More: documentation

Documents

Create | Upload chunk | Get list | Status | Cancel

Documents allow for uploading of large files up to 20MB in 200kb chunks. In general you do no need to use this API yourself as the outbound.deliver method will automatically detect large files and upload them in chunks as documents.

If you do wish to do this yourself the following example shows how you could upload a file in 500 byte chunks:

var fs = require('fs');

var upload = function(cursor = 0, document, data) {
  if (cursor >= data.length) { return };
  var chunk = data.slice(cursor, cursor+500);
  var next_cursor = cursor+Buffer.byteLength(chunk);

  interfax.documents.upload(document.id, cursor, next_cursor-1, chunk)
    .then(() => { upload(next_cursor, document, data); });
}

fs.readFile('tests/test.pdf', function(err, data){
  interfax.documents.create('test.pdf', Buffer.byteLength(data))
    .then(document => { upload(0, document, data); });
});

Create Documents

interfax.documents.create(name, size, options, callback);

Create a document upload session, allowing you to upload large files in chunks.

interfax.documents.create('large_file.pdf', 231234)
  .then(document => {
    console.log(document.id); // the ID of the document created
  });

Options: disposition, sharing

Upload chunk

interfax.documents.upload(id, range_start, range_end, chunk, callback);

Upload a chunk to an existing document upload session.

interfax.documents.upload(123456, 0, 999, "....binary-data....")
  .then(document => {
    console.log(document);
  });

More: documentation

Get document list

interfax.documents.all(options, callback);

Get a list of previous document uploads which are currently available.

interfax.documents.all({
  offset: 10
}).then(documents => {
  console.log(documents); //=> a list of documents
});

Options: limit, offset

Get document status

interfax.documents.find(document_id, callback);

Get the current status of a specific document upload.

interfax.documents.find(123456)
  .then(document => {
    console.log(document); //=> a document object
  });

More: documentation

Cancel document

interfax.documents.cancel(document_id, callback);

Cancel a document upload and tear down the upload session, or delete a previous upload.

interfax.documents.cancel(123456)
  .then(success => {
    console.log(success); //=> boolean
  })

More: documentation

Files

This class is used by interfax.outbound.deliver to turn every URL, path and binary data into a uniform format, ready to be sent out to the InterFAX API. Under the hood it automatically uploads large files in chunks using the Documents API.

It is most useful for sending binary data to the .deliver method.

interfax.files.create('....binary data.....', { mimeType: 'application/pdf' })
  .then(file => {
    console.log(file.header); //=> 'Content-Type: application/pdf'
    console.log(file.body);   //=> ....binary data.....
    interfax.outbound.deliver(faxNumber: '+1111111111112', file: file);
  });

Additionally it can be used to turn a URL or path into a valid object as well, though the .deliver method does this conversion automatically.

// a file by path
interfax.files.create('foo/bar.pdf');

// a file by url
interfax.files.create('https://foo.com/bar.html');

Contributing

  1. Fork the repo on GitHub
  2. Clone the project to your own machine
  3. Commit changes to your own branch
  4. Push your work back up to your fork
  5. Submit a Pull request so that we can review your changes

License

This library is released under the MIT License.