phonegap-build

PhoneGap Build Node Module

Node module to create and build PhoneGap projects with PhoneGap Build.

Getting Started

Install

package.json:

{
    "dependencies": {
        "phonegap-build": "*"
    }
}

Require

var phonegapbuild = require('phonegap-build');

API

Login

Authenticates with PhoneGap Build, saves the token, and return an API object. When the save token exists, the authentication step is skipped.

Options:

• options {Object} contains the login credentials.
• [options.username] {String} is the username.
• [options.password] {String} is the password.
• [options.protocol] {String} optional server protocol. e.g. 'https:'.
• [options.host] {String} optional server host. e.g. 'build.phonegap.com:'.
• [options.port] {String} optional server port. e.g. '443'.
• [options.path] {String} optional server path prefix. e.g. '/api/v1'.
• [options.proxy] {String} specifies an optional proxy server. e.g. 'http://myproxy.com:8181'.
• [callback] {Function} is called after the login.
  • e {Error} is null on a successful login attempt.
  • api {Object} the API object defined by phonegap-build-rest

Events:

• login is triggered when login credentials are required.
• error is triggered on an error.
  • e {Error} details the error.
• log is triggered with log messages.
• warn is triggered with warning messages.

Examples:

//
// given the login credentials
//

var options = { username: '[e-mail]', password: 'abc123' };

phonegapbuild.login(data, function(e, api) {
    // now logged in
});

//
// get login credentials on demand
//

phonegapbuild.on('login', function(options, callback) {
    options.username = options.username || '[e-mail]';
    options.password = options.password || 'abc123';
    callback(null, options);
});

phonegapbuild.login(function(e, api) {
    // now logged in
});

Login Event

This event is called whenever a task must authenticate with PhoneGap/Build and the credentials are unknown. If only the username or only the password is known, the it is passed into the event as the options object.

The developer should listen on this event and correctly retrieve the login credentials: looking them up from storage or prompting the user. Once the credentials are found, the callback can be fired with the correct credentials.

Options:

• options {Object} contains the known login credentials.
• [options.username] {String} is null or the username.
• [options.password] {String} is null or the password.
• callback {Function} is called with the correct credentials.
  • e {Error} is null or the error that occured.
  • options {Object} is the correct username and password.

Examples:

phonegapbuild.on('login', function(options, callback) {
    options.username = options.username || '[e-mail]';
    options.password = options.password || 'abc123';
    callback(null, options);
});

Logout

Logout the user by deleting the token key from the config file.

Options:

• args {Object} is unused and should be {}.
• [callback] {Function} is a callback function.
  • e {Error} is null unless there is an error.

Events:

• error is trigger on an error.
  • e {Error} details the error.

Examples:

phonegapbuild.logout({}, function(e) {
    // now logged out unless e is defined
});

Create an App

Creates an application on the local filesystem. The remote application is created on-demand during the first build.

Options:

• options {Object} is data required to create an app
  • path {String} is a directory path for the app.
• [callback] {Function} is triggered after creating the app.
  • e {Error} is null unless there is an error.

Events:

• error is triggered on an error.
  • e {Error} details the error.

Examples:

var options = { path: '~/development/my-app' };

phonegapbuild.create(options, function(e) {
    if (e) {
        console.error('failed to create the project:', e.message);
    }
    else {
        console.log('created the project:', path);
    }
});

Build an App

Builds the application using PhoneGap/Build. If the application does not exist, then it is first created. Currently, the build task only supports file transfers (zip) but will be extended to git repositories in the future.

Options:

• options {Object} is data required for building a platform.
• options.platforms {Array} is a collection of platform names {String} that
• [options.protocol] {String} optional server protocol. e.g. 'https:'.
• [options.host] {String} optional server host. e.g. 'build.phonegap.com:'.
• [options.port] {String} optional server port. e.g. '443'.
• [options.path] {String} optional server path prefix. e.g. '/api/v1'.
• [options.proxy] {String} specifies an optional proxy server. e.g. 'http://myproxy.com:8181'. specify the platforms to build.
• [callback] {Function} is triggered after the build is complete.
  • e {Error} is null unless there is an error.
  • data {Object} describes the built app.

Events:

• error is trigger on an error.
  • e {Error} details the error.

Examples:

var options = { platforms: ['android'] };

phonegapbuild.build(options, function(e, data) {
    if (e) {
        console.error('failed to build the app:', e);
    }
    else {
        console.log('successfully built the app:', data);
    }
});