# humanity-js-sdk

> Humanity JavaScript SDK

Latest version **1.2.3** (published 2016-06-21) · MIT license · 0 weekly downloads

## Install

```sh
npm install humanity-js-sdk
pnpm add humanity-js-sdk
yarn add humanity-js-sdk
bun add humanity-js-sdk
```

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.2.3 |
| Published | 2016-06-21 |
| First published | 2015-06-05 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 1 |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Maintainers | dvsoftware |

## Links

- npm: https://www.npmjs.com/package/humanity-js-sdk
- Repository: https://github.com/shiftplanning/humanity-js-sdk
- Issues: https://github.com/shiftplanning/humanity-js-sdk/issues
- npm.io page: https://npm.io/package/humanity-js-sdk

## Dependencies (1)

- [qs](https://npm.io/package/qs.md) ^6.2.0

## Recent versions

- 1.2.3 (latest) — 2016-06-21
- 1.2.2 — 2015-12-23
- 1.2.1 — 2015-12-23
- 1.2.0 — 2015-12-16
- 1.1.10 — 2015-09-25
- 1.1.9 — 2015-09-15
- 1.1.8 — 2015-09-15
- 1.1.7 — 2015-08-31
- 1.1.6 — 2015-08-24
- 1.1.5 — 2015-08-21
- 1.1.4 — 2015-08-10
- 1.1.3 — 2015-07-31
- 1.0.0 — 2015-06-05

## README

#Humanity JavaScript SDK

This package provides easy access to the [Humanity](https://www.humanity.com) API and IFrame SDK.

Before using, you will need to create your application and get the Application ID at the [Humanity Developers Portal](https://developers.humanity.com/).

Refer to the [Humanity API Docs](https://developers.humanity.com/docs/) for the available resources.


## Installation
For NodeJS

```
npm install humanity-js-sdk
```

For browsers

```
bower install humanity-js-sdk
```

## Usage

### NodeJS

```javascript
var Humanity = require('humanity-js-sdk');

// Instantiate auth class
var auth = new Humanity.Auth('your_client_id', 'your_redirect_uri', null, ['company.view'], 'your_secret');

// Generate SignIn URI
var signInUri = auth.generateSigninUri(); // https://accounts.humanity.com/oauth2/authorize?client_id=your_client_id&redirect_uri=your_redirect_uri%2F&company_id=&scope=company.view&response_type=code

// Redirect to the signInUri, and then depending on the http framework, set up a route for your redirect_uri
// The following example is for the express framework
app.get('/auth', function (req, res) {
	var authorizationCode = req.query.code;

	// Get the token
	Humanity.getToken(authorizationCode, function (token) {
		// Make a request using the token
		Humanity.get('companies', {}, token.access_token, function (response) {
			console.log(response);
		});
	});
});
```

### Browser
#### Using the API

```javascript
// Import the library using your desired module loader (AMD/CommonJS/ES6)
// Using CommonJS as an example
var Humanity = require('humanity-js-sdk');

// Instantiate auth class
var auth = new Humanity.Auth('your_client_id', 'your_redirect_uri', null, ['company.view']);

// Obtain auth data from hash if it's set
var authData = Humanity.deparam(window.location.hash.substr(1));

if (authData.access_token) {
	Humanity.get('companies', {}, authData.access_token, function (response) {
		console.log(response);
	});
} else {
	// Redirect to the OAuth2 service
	window.location.href = auth.generateSigninUri('token');
}

```

#### Using the Application framework
We developed a way for your app to communicate with the Humanity app in an unique way, allowing it to modify parts of the Humanity app and utilize core modules functionality.

```javascript
// Using CommonJS as an example
var Humanity = require('humanity-js-sdk');

/*
* Get Company Id
*
* Obtain company_id so the application doesn't need to ask the user for the company
*/
Humanity.IFrame.getCompanyId(function (companyId) {
	// Use the companyId here
});


/*
* Populating the 3 dots Menu
*
* This menu is used for navigating the application pages
*/

// First set a listener for the event, so we are able to act when menu item is clicked
Humanity.IFrame.listen('eventName', function () {
	alert('Menu Item is clicked');
});

Humanity.IFrame.setMenuItems([
	{
		title: 'Menu Item',
		page: 'eventName',
		icon: 'list'
	}
]);


/*
* Close subpage
*
* Closes the subpage. Note this only works when called from the subpage.
*/

Humanity.IFrame.closeSubPage();


/*
* Post to main
*
* Use this to post messages to the main frame. Useful when you want to notify
* the main application about some changes from the subpage.
*/

// First set a listener for the event on the main frame.
Humanity.IFrame.listen('eventName', function (data) {
	alert(data); // Alerts 'Message from the subpage'
});

// Then call it from the subpage
Humanity.IFrame.postToMain({
	method: 'eventName',
	data: 'Message from the subpage'
});


/*
* Open Subpage
*
* Open a subpage from your app in the native Humanity subpage
*/

// Path is relative to the application root
Humanity.IFrame.openSubpage('/some/path');


/*
* Notification
*
* Displays native Humanity notification
*/

Humanity.IFrame.notification(
	'Notification Text',	// Text
	5,						// Timeout (Seconds)
	'undoEvent',			// Event to call when undo is clicked. Undo will not
							// be shown if this is null
	'ok',					// Type, can be 'ok', 'error', 'info'
	true,					// Suppress other notifications
	'ENTITY_ID'				// Id of the deleted entity, in case undo is used,
							// it's going to be recieved as the undoEvent data
);


/*
* Set Controls
*
* Set the Humanity header controls
*/

Humanity.IFrame.setControls([
	{
		type: 'Title',					// Title Type
		style: {
			className: 'fl mr10 px5'	// Classes, feel free to inspect the
										// Humanity app to find the ones to use
		},
		text: "Title Text"				// Text
	},
	{
		type: 'Actions',				// Action button, turns to a dropdown if
										// there are multiple actions
		actions: [
			{
				handler: 'actionEvent',	// Action event, set up a listener for it
				label: "Button Label",  // Button label
				icon: 'addSmall'		// Icon
			}
		];
	},
	{
		type: 'Back',					// Back button
		text: 'Back',					// Button text
		handler: 'backEvent'			// Back button event
	},
]);


/*
* Set Subpage Controls
*
* Set the subpage header and footer
*/

Humanity.IFrame.setSubPageControls({
	header: { 										// Header controls
		title: 'SubPage Title',						// SubPage title
		visible: true,								// Header is visible
		controls: [
			{
				type: 'Actions',					// Action button
				actions: [
					{
						handler: 'closeSubPage',	// Close handler (built in),
													// you can use custom handler too
						label: null,				// No label
						icon: 'closeSmall'			// Icon

					}
				],
				style: {
					className: 'fr',
					group: {
						className: ''
					},
					primary: {
						className: 'btn btn-clean btn-drop fr'
					}
				}
			},
		]
	},
	footer: {											// Footer controls
		visible: true,									// Footer is visible
		controls: [
			{
				type: 'Actions',
				actions: [
					{
						handler: 'greenButtonEvent',
						label: 'Green Button'

					}
				],
				style: {
					className: 'fr',
					group: {
						className: ''
					},
					primary: {
						className: 'btn btn-green fr'
					}
				}
			},
			{
				type: 'Actions',
				actions: [
					{
						handler: 'closeSubPage',
						label: 'Cancel'

					}
				],
				style: {
					className: 'fr',
					group: {
						className: ''
					},
					primary: {
						className: 'btn btn-link fr'
					}
				}
			}
		]
	}
});




```

## Building

```
npm install
bower install
grunt build
```

---
_Source: https://npm.io/package/humanity-js-sdk · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._
