JavaScript Client for api.phone.com.

Description

This package is supposed to simplify usage of Phone.com API in front-end applications.

Api documentation can be found here.

Installation

Using npm:

$ npm i phoenix-api-js-client

Note: add --save if you are using npm < 5.0.0

Usage

Initialization

// 1. Import the package:
const PhoenixClient = require('phoenix-api-js-client');

// 2. Define options
const options = {
    client_id: null,
    handle_rate_limit: true,
    handle_server_error: 3,
    scope: ["account-owner"],
    session_name: "phoenix-api-js-client-session",
    id_token_sign_out: false,
    decode_id_token: false,
    session_scope: 'tab',
};

// 3. Create client object
const phoenix_client = new PhoenixClient(options);

// 4. Load user
phoenix_client.init_user().then(authorized => {
  if (authorized) {
      // 5. Make a request
      phoenix_client.get_list('/messages')
        .then(console.log)
        .catch(console.error);
  } else {
    console.log('We can redirect user to the login form');
  }
}).catch(console.error);

Options

• client_id : string, required default null; your api account client id
• handle_rate_limit: boolean, default: true; If you send too much requests in certain period of time, it will throw 429 error. Enabling this option, this will wait for the response specified time and it will resend the same request. Logs the message in the console. Disabling this option, it immediately throws the 429 error.
• handle_server_error: false or unsigned integer, default: 3; Specifies the number of retries if the server responds with 500+ error (500, 501, 502 etc). Logs error in the console. Disabling this option, it immediately throws the error.
• scope: array, default: ["account-owner"]; scopes for users, possible values: account-owner, extension-user, call-logs, billing-api, oauth-management, openid.
• session_name: string, default: "phoenix-api-js-client-session"; session name for authenticated users.
• id_token_sign_out: boolean, default: false; if openid scope is used, this option confirms that you want to use id_token for signing out.
• decode_id_token: boolean, default: false; if openid scope is used, this option enabled will decode your id_token and validate its signature. As result it will return id_token's payload or null.
• session_scope: string, in: ['tab', 'browser'], default: 'tab'; defines how data is stored, 'tab' - uses sessionStorage (phoenix-api-js-client is available per tab), 'browser' - uses localStorage (phoenix-api-js-client data is shared across browser windows and tabs).
• phoenix_url: string, default: 'https://api.phone.com'; can be setup to use custom stage url
• accounts_url: string, default: 'https://accounts.phone.com'; can be setup to use custom url
• oauth_api_url: string, default: 'https://oauth-api.phone.com'; can be setup to use custom url

Listeners

Session offers some listeners you can use: | listener | args | description | |--|--|--| |logging-out|--|Triggered on the begining of sing out process| |logged-out|--|Triggered when user is logged out| |session-expired|--|Triggered when user is logged out after session expiration| |error|error object|Triggered when an error returned from the API|

Usage example:

    this.session.on('logged-out', listener_callback);

Client methods

Client object implements some methods you can use:

| method | args | description | |--|--|--| | oauth_url | property | generates sign-in uri. User now can sign in by filling the form, which response will return Bearer token needed for the OAuth 2.0. If you use token based authentication, please skip this step. | init_user | | sets up the user for the session. | _load_user | token: string, uses_token: boolean | sets up the user for the session. If uses_token is true, token will not be deleted from the account on sign out | sign_out | | sings out the user | create_item | uri: string, required; data: object, required | Sends POST request to create the item | get_item | uri: string, required | returns the item specified in the uri. | get_list | uri: string, required; limit: unsigned integer, max:500; offset: unsigned integer; global: boolean | Returns items limited by limit argument, with offset of offset argument | get_list_all | uri: string, required | returns all items (specified in the uri) from the account | patch_item | uri: string, required; data: object, required | Sends PATCH request to update the item specified in the uri | replace_item | uri: string, required; data: object, required | Sends PUT request to update the item specified in the uri | download_item | uri: string, required | Downloads the item specified in the uri. | delete_item | uri: string, required | Deletes the item specified in the uri.