barchart-portfolio-client v0.1.5

portfoltio-client-js

Javascript library for managing Barchart portfolios

The Barchart Portfolio system allows users to create and track paper portfolios. This library allows a user to manage those portfolios.

##Setup

This library is intended for use in the browser or headless JavaScript environments (i.e. Node.js). It has been released via the usual package managers.

###npm

To import the library as a dependency to your application using npm, use the following command:

npm install portfolio-management-client -S

###bower

To import the library as a dependency to your application using bower, use the following command:

bower install portfolio-management-client -S

###git

The git repository is publicly-accessible here:

https://github.com/barchart/portfolio-client-js

##Usage

The Barchart Portfolio system exposes both REST and socket.iohttp://socket.io endpoints. This library is a convenience-wrapper for interacting with the Barchart Portfolio system. So, instead of invoking these transports directly, and worrying about the details of the protocol, the consumers can make single-line method calls to perform asynchronous operations (e.g. list portfolios, create portfolio etc).

###Example

An example browser-based implementation can be found in the git repository at:

/example/browser/example.html

###Initialization (Using REST)

In the browser, an object has been added to the global namespace. Connect as follows:

var portfolioManager = new Barchart.Portfolio.RestPortfolioManager();

Alternately, the URL and port of the portfolio management system can be passed to the constructor:

var portfolioManager = new Barchart.Portfolios.RestPortfolioManager('portfolios-management-test.elasticbeanstalk.com', 80);

Then, call the connect method before using any operations:

portfolioManager.connect()
	.then(function() {
		// ready
	});

###Asynchronous Operations

All operations are asynchronous. The result of any method call will be an A+ style promise. Here is an example:

portfolioManager.getServerVersion()
	.then(function(version) {
		console.log(version.semver);
	})
	.catch(function(error) {
		console.log('A problem occurred.');
	});

##Data

The library uses a JSON-in, JSON-out architecture. All data exchanged is in JSON format. Requests must supply JSON data. Responses are composed of JSON data.

The following data structures are important:

###Portfolio

A "portfolio" is a container for positions

{
	"portfolio_id": "40b90191-d802-442b-a640-b985a4819f7c",
	"portfolio_type": "US Equities",
	"portfolio_system": "barchart.com",
	"user_id": "barchart-test-user",
	"name": "My Portfolio",
	"portfolio_view_for_display": "Portfolio",
	"portfolio_view_for_email": "Portfolio",
	"show_closed_positions": true,
	"send_end_of_day_email": true,
	"cash_position": {
		"track": true,
		"opening_balance": 10000
	}
}

###PortfolioType

A "portfolio type" categorizes a portfolio and describes the types of positions that a portfolio can hold.

{
	"description": "US Equities",
	"currency": "USD",
	"can_track_cash_positions": true
}

##PortfolioManager Operations

###getServerVersion

Returns the version of the server in a JSON object, as follows:

JSON-in:

{
}

JSON-out:

{
  "semver": "0.0.1"
}

###retrievePortfolios

Retrieves all the "Portfolio" objects for a user account:

JSON-in:

{
	"portfolio_system": "barchart.com"
    "user_id": "barchart-test-user"
}

JSON-out:

An array of "Portfolio" objects belonging to the specified user.

###createPortfolio

The following JSON object can be used to create an portfolio. The input is a simplified version of the "Portfolio" object.

JSON-in:

{
	"portfolio_type": "US Equities",
	"portfolio_system": "barchart.com",
	"user_id": "barchart-test-user",
	"name": "My Portfolio",
	"portfolio_view_for_display": "Portfolio",
	"portfolio_view_for_email": "Portfolio",
	"show_closed_positions": true,
	"send_end_of_day_email": true,
	"cash_position": {
		"track": true,
		"opening_balance": 10000
	}
}

JSON-out:

A "Portfolio" object.

###updatePortfolio

The following JSON object can be used to update an existing portfolio. The only field that is required is "portfolio_id" any field that is omitted will not be updated.

JSON-in:

{
	"portfolio_id": "3ff90d2b-4605-4490-85b4-58274922f9a0",
	"name": "My New Portfolio Name",
	"portfolio_view_for_display": "Portfolio",
	"portfolio_view_for_email": "Portfolio",
	"show_closed_positions": false,
	"send_end_of_day_email": false,
	"cash_position": {
		"track": false
	}
}

JSON-out:

A "Portfolio" object, after the update has been applied.

###deletePortfolio

Deletes a single "Portfolio" object, using its identifier:

JSON-in:

{
    "portfolio_id": "40b90191-d802-442b-a640-b985a4819f7c"
}

JSON-out:

The "Portfolio" object that was deleted.

##Unit Testing

Gulp and Jasmine are used. Execute unit tests, as follows:

gulp test