PhoneGap Build API Node Module
Node.js REST Client for the PhoneGap Build API
Overview
This library simplifies authentication and requests to the PhoneGap Build REST API for node.js clients.
In many ways, this library is little more than a convenience wrapper
for mikeal's request library. You can expect
that all of request's functionality to be available to the
API
object returned by client.auth();
.
If something is inaccurate or missing, please send a pull request!
Usage
Authenticate with Username and Password
var client = require('phonegap-build-api');
client.auth({ username: 'zelda', password: 'tr1f0rce' }, function(e, api) {
// time to make requests
});
Authenticate with Token
var client = require('phonegap-build-api');
client.auth({ token: 'abc123' }, function(e, api) {
// time to make requests
});
GET /api/v1/me
api.get('/me', function(e, data) {
console.log('error:', e);
console.log('data:', data);
});
GET /api/v1/apps
api.get('/apps', function(e, data) {
console.log('error:', e);
console.log('data:', data);
});
GET /api/v1/apps/:id
api.get('/apps/199692', function(e, data) {
console.log('error:', e);
console.log('data:', data);
});
GET /api/v1/apps/:id/icon
api.get('/apps/199692/icon').pipe(fs.createWriteStream('icon.png'));
GET /api/v1/apps/:id/:platform
api.get('/apps/199692/android').pipe(fs.createWriteStream('app.apk'));
GET /api/v1/keys
api.get('/keys', function(e, data) {
console.log('error:', e);
console.log('data:', data);
});
GET /api/v1/keys/:platform
api.get('/keys/ios', function(e, data) {
console.log('error:', e);
console.log('data:', data);
});
GET /api/v1/keys/:platform/:id
api.get('/keys/ios/917', function(e, data) {
console.log('error:', e);
console.log('data:', data);
});
POST /api/v1/apps
var options = {
form: {
data: {
title: 'My App',
create_method: 'file'
},
file: '/path/to/app.zip'
}
};
api.post('/apps', options, function(e, data) {
console.log('error:', e);
console.log('data:', data);
});
PUT /api/v1/apps/:id
var options = {
form: {
data: {
debug: false
},
file: '/path/to/app.zip'
}
};
api.put('/apps/197196', options, function(e, data) {
console.log('error:', e);
console.log('data:', data);
});
POST /api/v1/apps/:id/icon
var options = {
form: {
icon: 'my-icon.png'
}
};
api.post('/apps/232741/icon', options, function(e, data) {
console.log('error:', e);
console.log('data:', data);
});
POST /api/v1/apps/:id/build
Build all platforms:
api.post('/apps/232741/build', function(e, data) {
console.log('error:', e);
console.log('data:', data);
});
Build specific platforms:
var options = {
form: {
data: {
platforms: [ 'android', 'blackberry', 'ios', 'winphone', 'webos' ]
}
}
};
api.post('/apps/232741/build', options, function(e, data) {
console.log('error:', e);
console.log('data:', data);
});
POST /api/v1/apps/:id/build/:platform
api.post('/apps/232741/build/android', function(e, data) {
console.log('error:', e);
console.log('data:', data);
});
POST /api/v1/apps/:id/collaborators
var options = {
form: {
data: {
email: 'michael@michaelbrooks.ca',
role: 'dev'
}
}
};
api.post('/apps/232741/collaborators', options, function(e, data) {
console.log('error:', e);
console.log('data:', data);
});
PUT /api/v1/apps/:id/collaborators/:id
var options = {
form: {
data: {
role: 'tester'
}
}
};
api.put('/apps/232741/collaborators/263955', options, function(e, data) {
console.log('error:', e);
console.log('data:', data);
});
POST /api/v1/keys/:platform
var options = {
form: {
data: {
title: 'My BlackBerry Signing Key',
password: 'my-password'
},
db: '/path/to/sigtool.db',
csk: '/path/to/sigtool.csk'
}
};
api.post('/keys/blackberry', options, function(e, data) {
console.log('error:', e);
console.log('data:', data);
});
PUT /api/v1/keys/:platform/:id
var options = {
form: {
data: {
password: 'my-updated-password'
}
}
};
api.put('/keys/blackberry/1505', options, function(e, data) {
console.log('error:', e);
console.log('data:', data);
});
DELETE /api/v1/apps/:id
api.del('/apps/14450', function(e, data) {
console.log('error:', e);
console.log('data:', data);
});
DELETE /api/v1/apps/:id/collaborators/:id
api.del('/apps/232741/collaborators/263955', function(e, data) {
console.log('error:', e);
console.log('data:', data);
});
DELETE /api/v1/keys/:platform/:id
api.del('/keys/ios/2729', function(e, data) {
console.log('error:', e);
console.log('data:', data);
});
API
client.auth(options, callback)
PhoneGap Build Authentication.
Authentications with PhoneGap Build and returns an instance of API
.
The authentication credentials can be a username and password or user-token.
Options:
options
{Object}
is the authentication settings.options.username
{String}
is the phonegap build username.options.password
{String}
is the phonegap build password.options.token
{String}
can be used instead of username and 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 trigger after the authentication.e
{Error}
is null unless there is an error.api
{Object}
is theAPI
instance to interact with phonegap build.
Example:
var client = require('phonegap-build-api');
client.auth({ username: 'zelda', password: 'tr1force' }, function(e, api) {
if (e) {
console.log('error:', e);
return;
}
// make some api requests
});
api(path, [options], [callback])
API Request.
Create a RESTful request to the PhoneGap Build API. The api
function is a
wrapper to request's interface.
The path
parameter is a relative path to a PhoneGap Build API response.
For example, to the resource https://build.phonegap.com/api/v1/me
is specified
as the path /me
.
The options
parameter maps directly to request's options.
The default request method is GET
. You can specify a specific but you can be changed
in the options
parameters (e.g. { method: 'POST' }
).
To send form data, you can use the options.form
parameter. The key data
is
assumed to be JSON and all other keys are assumed to be file paths.
Options:
path
{String}
is a relative resource path (e.g."/apps"
).[options]
{Object}
is a request options object.[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'.[callback]
{Function}
is trigger after the requeste
{Error}
is null unless there is an errordata
{Object}
is the JSON response.
Example: GET Request
api('/me', function(e, data) {
console.log('error:', e);
console.log('data:', data);
});
Example: POST Request
var options = {
form: {
data: {
title: 'My App',
create_method: 'file'
},
file: '/path/to/app.zip'
},
method: 'POST'
};
api('/apps', options, function(e, data) {
console.log('error:', e);
console.log('data:', data);
});
api.get(path, [options], [callback])
GET API Request.
A convenience function for api(path, [options], [callback])
, where options
uses { method: 'GET' }
.
Options:
path
{String}
is a relative resource path (e.g."/apps"
).[options]
{Object}
is a request options object.[callback]
{Function}
is trigger after the requeste
{Error}
is null unless there is an errordata
{Object}
is the JSON response.
Example:
api.get('/me', function(e, data) {
console.log('error:', e);
console.log('data:', data);
});
api.post(path, [options], [callback])
POST API Request.
A convenience function for api(path, [options], [callback])
, where options
uses { method: 'POST' }
.
Options:
path
{String}
is a relative resource path (e.g."/apps"
).[options]
{Object}
is a request options object.[callback]
{Function}
is trigger after the requeste
{Error}
is null unless there is an errordata
{Object}
is the JSON response.
Example:
var options = {
form: {
data: {
title: 'My App',
create_method: 'file'
},
file: '/path/to/app.zip'
}
};
api.post('/apps', options, function(e, data) {
console.log('error:', e);
console.log('data:', data);
});
api.put(path, [options], [callback])
PUT API Request.
A convenience function for api(path, [options], [callback])
, where options
uses { method: 'PUT' }
.
Options:
path
{String}
is a relative resource path (e.g."/apps"
).[options]
{Object}
is a request options object.[callback]
{Function}
is trigger after the requeste
{Error}
is null unless there is an errordata
{Object}
is the JSON response.
Example:
var options = {
form: {
data: {
debug: false
},
file: '/path/to/app.zip'
}
};
api.put('/apps/197196', options, function(e, data) {
console.log('error:', e);
console.log('data:', data);
});
api.del(path, [options], [callback])
DELETE API Request.
A convenience function for api(path, [options], [callback])
, where options
uses { method: 'DELETE' }
.
Options:
path
{String}
is a relative resource path (e.g."/apps"
).[options]
{Object}
is a request options object.[callback]
{Function}
is trigger after the requeste
{Error}
is null unless there is an errordata
{Object}
is the JSON response.
Example:
api.del('/apps/14450', function(e, data) {
console.log('error:', e);
console.log('data:', data);
});
api.defaults(options)
This maps directly to request's default
method.
This method returns a wrapper around the normal request API that defaults to whatever options you pass in to it.