interfax
v0.8.4
Published
A wrapper around the InterFAX REST API for sending and receiving faxes.
Downloads
12,485
Readme
InterFAX Node Library
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.
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
- Fork the repo on GitHub
- Clone the project to your own machine
- Commit changes to your own branch
- Push your work back up to your fork
- Submit a Pull request so that we can review your changes
License
This library is released under the MIT License.