phaxio-official

It is suggested that you ONLY use this library with Node.js 8 or higher.

Installation

# Stable Version:
npm install --save phaxio-official

# Development Version:
npm install --save https://github.com/phaxio/phaxio-node

Example Usage

Every method in phaxio returns a Promise. You should also be able to use async/await syntax with these methods.

See the test directory for more examples.

// Assuming you have a .env file in your project that contains your
// API credentials and you have installed the `dotenv` package from
// NPM so that you can attach those variables to the Node environment.

const { config } = require('dotenv');
config();
if (process.env.PHAXIOKEY === undefined || process.env.PHAXIOSECRET === undefined) {
  console.log('No `PHAXIOKEY` or `PHAXIOSECRET` found in file `.env`. Exiting.');
  process.exit();
}

const Phaxio = require('phaxio-official');
const phaxio = new Phaxio(process.env.PHAXIOKEY, process.env.PHAXIOSECRET);

// Send a single fax containing two documents: one a URL, one from the filesystem.
phaxio.faxes.create({
  to: '+1234567890', // Replace this with a number that can receive faxes.
  content_url: 'https://google.com',
  file: `${__dirname}/sample1.pdf`,
})
  .then((fax) => {
    // The `create` method returns a fax object with methods attached to it for doing things
    // like cancelling, resending, getting info, etc.

    // Wait 5 seconds to let the fax send, then get the status of the fax by getting its info from the API.
    return setTimeout(() => {
      fax.getInfo()
    }, 5000)
  })
  .then(status => console.log('Fax status response:\n', JSON.stringify(status, null, 2)))
  .catch((err) => { throw err; });

// Get a list of all the faxes you have sent in the past and re-send the most recent one.
phaxio.faxes.listFaxes({ direction: 'sent' })
  .then((faxes) => {
    const mostRecent = faxes.data.reduce((acc, cv) => {
      const accCreated = new Date(acc.created_at);
      const cvCreated = new Date(cv.created_at);
      const output = accCreated > cvCreated ? acc : cv;
      return output;
    }, { created_at: '1970-01-01T00:00:00.000Z' });

    return phaxio.faxes.resend({ id: mostRecent.id });
  })
  .then(response => console.log('Response from resending most recent fax:\n', JSON.stringify(response, null, 2));
  .catch((err) => { throw err; });

Documentation

Phaxio methods are categorized according to the Phaxio API route that they target. See the Phaxio Docs for more information about the raw API.

Initialization

Initializing the Phaxio class takes two required arguments, the Key and Secret you retreived from Phaxio, and allows for one optional argument, the minimum TLS version to use. By default, the minimum TLS version is set to TLSv1.2. See the TLS documentation for other possible options to minVersion if you require something other than TLSv1.2. Modifying the minimum TLS version is not recommended.

Arguments:

| Key | Value Type | Required? | Description | | --- | ---------- | --------- | ----------- | | phaxio api key | String | True | Your Phaxio API Key | | phaxio api secret | String | True | Your Phaxio API Secret | | minimum TLS Version | String | False | Default: TLSv1.2, other possible options are the same as minVersion in the TLS documentation. |

const Phaxio = require('phaxio-official');

const phaxio = new Phaxio(<phaxio api key>, <phaxio api secret>, [optional: <minimum TLS version>]);

All Phaxio methods take one argument: either a single argument such as an ID, or an Object containing key: value parameters. See the documentation below for specifics.

Public

phaxio.public.getAreaCodes()

Displays a list of area codes available for purchasing Phaxio numbers. This operation requires no authentication and can be used without passing an API key.

See docs for more information.

Arguments (Object):

| Key | Value Type | Required? | Description | | --- | ---------- | --------- | ----------- | | toll_free | Boolean | False | If set to true, only toll free area codes will be returned. If specified and set to false, only non-toll free area codes will be returned. | | country_code | Integer | False | A country code (E.164) you'd like to filter by. | | country | String | False | A two character country abbreviation (ISO 3166; e.g. US or CA) you'd like to filter by. | | state | String | False | A two character state or province abbreviation (ISO 3166; e.g. IL or YT) you'd like to filter by. When using this parameter, country_code or country must also be provided. | | per_page | Integer | False | Maximum number of results returned per call or "page". | | page | Integer | False | The current page number. 1-based. |

phaxio.public.getAreaCodes()
  .then(response => console.log(JSON.stringify(response, null, 2)))
  .catch((err) => { throw err; });

phaxio.public.getCountries()

Returns a list of supported countries for sending and receiving faxes on Phaxio. This operation requires no authentication and can be used without passing an API key.

See docs for more information.

Arguments (Object):

| Key | Value Type | Required? | Description | | --- | ---------- | --------- | ----------- | | per_page | Integer | False | Maximum number of results returned per call or "page". | | page | Integer | False | The current page number. 1-based. |

phaxio.public.getCountries()
  .then(response => console.log(JSON.stringify(response, null, 2)))
  .catch((err) => { throw err; });

Faxes

phaxio.faxes.create()

Create and send a fax.

Returns a Fax Object with methods attached. More detail on Fax Objects after the example.

See docs for more information.

Arguments (Object):

| Key | Value Type | Required? | Description | | --- | ---------- | --------- | ----------- | | to | String or Array | True | A phone number in E.164 format (+[country code][number]). Pass an Array to send to multiple numbers. | | file | String or Array | Only when sending files from filesystem | The file you wish to fax. A least one file or content_url parameter is required. Pass an Array to send to multiple files. | | content_url | String or Array | Only when sending public URL's | URL to be rendered and sent as the fax content. At least one file or content_url parameter is required. Pass an Array to send to multiple URL's. | | header_text | String | False | Text that will be displayed at the top of each page of the fax. 50 characters maximum. Default header text is "-". Note that the header is not applied until the fax is transmitted, so it will not appear on fax PDFs or thumbnails. | | batch_delay | Integer | False | Specifies the amount of time in seconds before the batch is fired. Maximum is 3600 (1 hour). | | batch_collision_avoidance | Boolean | False | When batch_delay is set to 'true', fax will be blocked until the receiving machine is no longer busy. See docs for more info. Default is 'false'. | | callback_url | String | False | You can specify a callback url that will override the one you have defined globally for your account. | | cancel_timeout | Integer | False | A number of minutes after which the fax will be canceled if it hasn't yet completed. Must be between 3 and 60. Additionally, for faxes with a batch_delay, the cancel_timeout must be at least 3 minutes after the batch_delay. If it is not, it will automatically be extended when batching. | | tags | Object | False | An object containing key: value metadata tags relevant to your application. You may specify up to 10 tags. { my_tag1: tag_val1, my_tag2: tag_val2, ..., my_tag10: tag_val10 } | | caller_id | String | False | A Phaxio phone number you would like to use for the caller id. | | test_fail | String | False | When using a test API key, this will simulate a sending failure at Phaxio. The contents of this parameter should be one of the Phaxio error types which will dictate how the fax will "fail". |

phaxio.faxes.create({ to: '+1234567890', content_url: 'https://google.com', file: 'sample.pdf' })
  .then(faxObject => console.log(JSON.stringify(faxObject, null, 2)))
  .catch((err) => { throw err; });

Fax Objects

Fax Objects are returned by phaxio.faxes.create(). They contain some metadata attributes as well as methods for doing extra things with a particular fax. The methods attached to a Fax Object take one or no arguments as they already have the required metadata to fire off against the raw API.

| Method | Arguments | Description | | ------ | --------- | ----------- | | faxObject.cancel() | None | Cancels the fax. | | faxObject.resend() | callback_url (optional) | Resends the fax. Default callback_url uses the fax's original callback_url. Passing a URL string will set the callback_url to the new value. | | faxObject.getInfo() | None | Gets the fax's metadata information. | | faxObject.getFile() | thumbnail (optional) | Gets the fax's document. The default thumbnail is null, which gets the full PDF file. Specify a string, 's' or 'l', to get a small or large JPG thumbnail (respectively) of the first page of the document. | | faxObject.deleteFile() | None | Deletes a document associated with a fax. | | faxObject.testDelete() | None | Deletes a fax created using Test API Credentials. |

// Cancelling a fax you just sent.
phaxio.faxes.create({ to: '+1234567890', content_url: 'https://google.com' })
  .then((faxObject) => {
    return faxObject.cancel();
  })
  .then(response => console.log('Fax cancelled:\n', JSON.stringify(response, null, 2)))
  .catch((err) => { throw err; });

// Suppose that earlier you created a `FaxDB` sequelize model you want to store Fax data into.
phaxio.faxes.create({ to: '+1234567890', content_url: 'https://google.com' })
  .then((faxObject) => {
    return faxObject.getInfo();
  })
  .then((faxInfo) => {
    const fi = FaxDB.build(faxInfo);
    return fi.save();
  })
  .then(() => console.log('Insert successful.'))
  .catch((err) => { throw err; });

// Write out the thumbnail of a created fax to a file.
phaxio.faxes.create({ to: '+1234567890', content_url: 'https://google.com' })
  .then((faxObject) => {
    return faxObject.getFile('s')
  })
  .then(fileString => fs.writeFileSync(`${__dirname}/thumbnail.jpg`, fileString))
  .catch((err) => { throw err; });

phaxio.faxes.cancel()

Cancel a fax.

See docs for more information.

Argument (Value):

| Key | Value Type | Required? | Description | | --- | ---------- | --------- | ----------- | | id | Integer | True | A Fax Identifier |

phaxio.faxes.cancel(987)
  .then(response => console.log(JSON.stringify(response, null, 2)))
  .catch((err) => { throw err; });

phaxio.faxes.resend()

Resend a fax.

See docs for more information.

Argument (Value):

| Key | Value Type | Required? | Description | | --- | ---------- | --------- | ----------- | | id | Integer | True | A Fax Identifier |

phaxio.faxes.resend(987)
  .then(response => console.log(JSON.stringify(response, null, 2)))
  .catch((err) => { throw err; });

phaxio.faxes.getInfo()

Get fax info.

See docs for more information.

Argument (Value):

| Key | Value Type | Required? | Description | | --- | ---------- | --------- | ----------- | | id | Integer | True | A Fax Identifier |

phaxio.faxes.getInfo(987)
  .then(response => console.log(JSON.stringify(response, null, 2)))
  .catch((err) => { throw err; });

phaxio.faxes.getFile()

Get fax content file or thumbnail.

See docs for more information.

Arguments (Object):

| Key | Value Type | Required? | Description | | --- | ---------- | --------- | ----------- | | id | Integer | True | A Fax Identifier | | thumbnail | String | False | The default thumbnail is null, which gets the full file. Specify a string, 's' or 'l', to get a small or large thumbnail (respectively) of the first page of the document. |

phaxio.faxes.getFile({ id: 987 })
  .then(fileString => fs.writeFileSync(`${__dirname}/full_file.pdf`, fileString))
  .catch((err) => { throw err; });

phaxio.faxes.listFaxes()

List sent faxes.

See docs for more information.

Arguments (Object):

| Key | Value Type | Required? | Description | | --- | ---------- | --------- | ----------- | | created_before | String | False | The end of the range. Must be in RFC 3339 format, except that the timezone may be omitted (e.g. '2016-05-31T23:59:59'). Defaults to now. | | created_after | String | False | The beginning of the range. Must be in RFC 3339 format, except that the timezone may be omitted (e.g. '2016-05-01T00:00:00'). Defaults to one week ago. | | direction | String | False | Either 'sent' or 'received'. Limits results to faxes with the specified direction. | | status | String | False | Limits results to faxes with the specified status. | | phone_number | String | False | A phone number in E.164 format that you want to use to filter results. The phone number must be an exact match, not a number fragment. | | tags | Object | False | An object containing key: value metadata tags relevant to your application. You may specify up to 10 tags. { my_tag1: tag_val1, my_tag2: tag_val2, ..., my_tag10: tag_val10 } | | per_page | Integer | False | Maximum number of results returned per call or "page". | | page | Integer | False | The current page number. 1-based. |

phaxio.faxes.listFaxes()
  .then(response => console.log(JSON.stringify(response, null, 2)))
  .catch((err) => { throw err; });

phaxio.faxes.deleteFile()

Delete fax document files.

See docs for more information.

Argument (Value):

| Key | Value Type | Required? | Description | | --- | ---------- | --------- | ----------- | | id | Integer | True | A Fax Identifier |

phaxio.faxes.deleteFile(987)
  .then(response => console.log(JSON.stringify(response, null, 2)))
  .catch((err) => { throw err; });

phaxio.faxes.testDelete()

Delete a sent fax. May only be used with test credentials.

See docs for more information.

Argument (Value):

| Key | Value Type | Required? | Description | | --- | ---------- | --------- | ----------- | | id | Integer | True | A Fax Identifier |

phaxio.faxes.testDelete(987)
  .then(response => console.log(JSON.stringify(response, null, 2)))
  .catch((err) => { throw err; });

phaxio.faxes.testReceive()

Test receiving a fax.

See docs for more information.

Arguments (Object):

| Key | Value Type | Required? | Description | | --- | ---------- | --------- | ----------- | | file | String | True | A PDF file to simulate receiving. | | from_number | String | False | The phone number of the simulated sender in E.164 format. Default is the public Phaxio fax number. | | to_number | String | False | The phone number, in E.164 format, that is receiving the fax. Specifically, a Phaxio phone number you have purchased in your account that is "receiving" the fax, or the public Phaxio fax number. Default is the public Phaxio fax number. |

phaxio.faxes.testReceive({ file: 'sample.pdf' })
  .then(response => console.log(JSON.stringify(response, null, 2)))
  .catch((err) => { throw err; });

Account

phaxio.account.status()

Information about the Phaxio account for the configured API key and secret.

See docs for more information.

Does not take arguments.

phaxio.account.status()
  .then(response => console.log(JSON.stringify(response, null, 2)))
  .catch((err) => { throw err; });

PhaxCode

phaxio.phaxCode.create()

Create a custom PhaxCode.

See docs for more information.

Arguments (Object):

| Key | Value Type | Required? | Description | | --- | ---------- | --------- | ----------- | | metadata | String | True | Custom metadata to be associated with this barcode. | | type | String | False | Defaults to .json. Other option is .png |

phaxio.phaxCode.create({ metadata: 'This is my metadata.' })
  .then(response => console.log(JSON.stringify(response, null, 2)))
  .catch((err) => { throw err; });

phaxio.phaxCode.get()

Retreive a PhaxCode.

See docs for more information.

Arguments (Object):

| Key | Value Type | Required? | Description | | --- | ---------- | --------- | ----------- | | id | String | False | PhaxCode Identifier to retrieve. If not specified, provides default PhaxCode for your account. | | type | String | False | Defaults to .json. Other option is .png |

phaxio.phaxCode.get()
  .then(response => console.log(JSON.stringify(response, null, 2)))
  .catch((err) => { throw err; });

Phone Number

phaxio.phoneNumber.provisionNumber()

Provision a phone number that you can use to receive faxes in your Phaxio account.

See docs for more information.

Arguments (Object):

| Key | Value Type | Required? | Description | | --- | ---------- | --------- | ----------- | | country_code | Integer | True | The country code (E.164) of the number you'd like to provision. | | area_code | Integer | True | The area code of the number you'd like to provision. | | callback_url | String | False | A callback URL that we'll post to when a fax is received by this number. This will override the global receive callback URL, if you have one specified. |

phaxio.phoneNumbers.provisionNumber({
  country_code: 1,
  area_code: 847,
})
  .then(response => console.log(JSON.stringify(response, null, 2)))
  .catch((err) => { throw err; });

phaxio.phoneNumber.releaseNumber()

Release a phone number that you no longer need. Once a phone number is released you will no longer be charged for it.

See docs for more information.

Arguments (Value):

| Key | Value Type | Required? | Description | | --- | ---------- | --------- | ----------- | | number | String | True | The phone number to be released in E.164 format. |

phaxio.phoneNumbers.releaseNumber('+1234567890')
  .then(response => console.log(JSON.stringify(response, null, 2)))
  .catch((err) => { throw err; });

phaxio.phoneNumber.getNumberInfo()

Get information about a phone number you own.

See docs for more information.

Arguments (Value):

| Key | Value Type | Required? | Description | | --- | ---------- | --------- | ----------- | | number | String | True | The phone number to be released in E.164 format. |

phaxio.phoneNumber.getNumberInfo()
  .then(response => console.log(JSON.stringify(response, null, 2)))
  .catch((err) => { throw err; });

phaxio.phoneNumber.listNumbers()

Get a detailed list of the phone numbers that you currently own on Phaxio.

See docs for more information.

Arguments (Object):

| Key | Value Type | Required? | Description | | --- | ---------- | --------- | ----------- | | country_code | Integer | False | The country code (E.164) of the numbers you'd like to list. | | area_code | Integer | False | The area code of the numbers you'd like to list. |

phaxio.phoneNumber.listNumbers()
  .then(response => console.log(JSON.stringify(response, null, 2)))
  .catch((err) => { throw err; });

Testing This Package

This package tests against the Phaxio API.

YOU ARE RESPONSIBLE FOR ANY CHARGES ACCRUED WHEN RUNNING THE TEST SUITE.

WARNING Running many of these tests will cause your Phaxio account to be billed, unless you use Test API credentials.

DOUBLE WARNING Running tests for provisioning Phone Numbers WILL ALWAYS bill your account, even if you use Test API credentials. These tests are not run by default. See test/phonenumber/index.test.js for comments on how to enable these tests.

You should create a .env file in the root of this directory containing three pieces of information:

TEST_APIKEY # Your Phaxio Test API Key.
TEST_APISECRET # Your Phaxio Test API Secret.
PHONE_NUMBER # Your Phone Number purchased from Phaxio.

To run the test suite:

npm run test

Note: this test suite uses setTimeout() to reduce the likelihood of receiving rate limiting errors.

LICENSE

MIT Copyright 2018 Phaxio

See LICENSE file for full detail.