npm package: @tablelist/tablelist-js-sdk
Description: Tablelist Javascript SDK
Author: Tablelist, Inc.
Latest version: 2.39.0

[![Coverage Status](https://coveralls.io/repos/github/tablelist/js-sdk/badge.svg?branch=master&t=h6JcPW)](https://coveralls.io/github/tablelist/js-sdk?branch=master)

#Javascript SDK

##Table of Contents

1. [Getting Started](#user-content-getting-started)
2. [Usage](#user-content-usage)
3. [Contributing](#user-content-contributing)
  *[Code Style Guidelines](#user-content-code-style-guidelines)
  *[Tests](#user-content-tests)
  *[Publishing](#user-content-publishing)
  *[Code Quality](#user-content-code-quanlity)
  *[Versioning](#user-content-versioning)
  *[JsDoc](#user-content-jsdoc)
  *[Gulp](#user-content-gulp)
  *[Demo App](#user-content-demo-app)
  *[Admin Only Functionality](#user-content-admin-only-functionality)

<hr>

###Getting Started

1. Clone the repo
2. Run `npm install`

###Usage

1. Add the NPM dependency `tablelist-js-sdk` to your `package.json`
2. Add the Js SDK script to your html file, and add Js SDK dependencies to your html file:

  ``` html
  <script src="../node_modules/angular/angular.min.js"></script>
  <script src="../node_modules/angular-resource/angular-resource.min.js"></script>
  <script src="../node_modules/angular-cookies/angular-cookies.min.js"></script>
  ```

#Contributing
###Code Style Guidelines

1. Always add JSDoc attributes
2. Use ES6 wherever possible
2. Use single quotes instead of double quotes
3. Always use camel-case for file names and directories. Ex. `jsSdk.js` not `js-sdk.js`
4. Always namespace services, factories, etc... with `jsdSdk`. Ex. `jsSdk.venueService` or `jsSdk.config`
5. When using Angular's `ng-resource` always return the promise object Ex.

  ``` js
    login(email, password) {
      return auth.login().$promise;
    }
  ```

###Tests

- Run `npm test`

###Building

``
$ gulp release
``

###Publishing

To publish a new version of SDK to NPM follow these steps:

1. Make your changes the SDK
2. Bump the version number in ```package.json```
2. Write Unit Tests to verify your new code is working properly.

> You can also run the Demo App (```gulp run-demo```) and
add new pages to the demo app if you'd like to test any code within an actual browser. Usually testing with Unit Tests will be sufficient, but sometimes it's nice to verify things are working in a real browser/app setting.

3. That's it! The build system will build and test your code. If the build passes your code will be deployed and published to NPM automagically. The JsDocs will also be regenerated and published to [http://tablelist-js-sdk.herokuapp.com/](http://tablelist-js-sdk.herokuapp.com/)

###Testing

``` sh
$ gulp test
```

To run a subset of the tests, use ``fdescribe``. This will skip all other tests.

> Just put an `f` before the group of tests/test you want to run, such that the test block begins with ``fdescribe(...)``

Files must have ``-test`` in the name. For example: ``create-test.js``.

Alternatively, you can replace the function ``describe(....`` with ``describe.only(....``.

###Code Quality

- Run `gulp jsquality` - this will run jshint and jscs. The build will fail if this task fails.

###Naming Conventions

If an endpoint requires an ID/input of an object that isn't of the current service. Please specify that in the name. For example, to list all venues in a given city:

```js
eventService.listByCityId(cityId)
```

However, we do not need to specify in the ``.read`` function, since it requires the ID of an event.

```js
eventService.read(eventId)
```

###Versioning
 - Use [Semantic Versioning](http://semver.org/)

 
### Documentation

Use the [JSDocs](http://usejsdoc.org/) format for adding documentation

JsDocs can be generated to view all the classes and methods available in the project
- Run `gulp jsdoc` to generate the docs
- Run `gulp open-jsdoc` to open the results in your browser

**Documenting Modules**

> Example: 

```js
/**
 * Booking Service
 *
 * @module booking
 * @submodule booking-service
 */
```

**Documenting Methods**

JSDocs format for methods:

> Example: 

```js
/**
 * Read a booking object
 *
 * @param {String} id - Booking ID to read
 * @param {Object} options
 * @return {Promise}
 */
```

More info on JSDocs format for methods.

 > Example: Note the addition of **optional** fields and

```js
/*
 * Create an organization member
 *
 * @param {Object} options
 * @param {String} options.organizationId - ID of organization to add member in
 * @param {String} options.email - email of member to add
 * @param {String} [options.name] - first name of member to add (optional)
 * @param {String[]} options.venueIds - array of venue IDs member has access to
 * @return {Promise<OrganizationMember>} newly created organization member
 */
```

You can define return types like ``Promise<Object>`` or in this example - a kind of a fake type ``Promise<OrganizationMember>``

###Gulp

- Run `gulp ?` to list all Gulp tasks

###Demo App

- Run `gulp run-demo` to start a demo app. This can be helpful for debugging issues with the SDK and is a good starting point for applications using the SDK.

###Admin Only Functionality
Multiple builds of the SDK are generated. 1 for non-admin, and 1 for admins. The build generated for admins includes functionality that is
only available to Tablelist admins. The way this is controlled is by decorating functions with special comments to tell the build process
to exclude/include depending on the build type.

Example:

```
//removeIf(NON_ADMIN_BUILD)

/** @method */
/**
 * @param {Object} options
 * @return {Promise}
 */
create(options) {
  if (!options) throw new Error('jsSdk.commonService - create() - options is required');

  return this._resource.create({}, options).$promise;
}

//endRemoveIf(NON_ADMIN_BUILD)
```

This function will only be included in the ```tablelist-js-sdk.admin.js``` build.

###Adding New Resources
When adding new resources follow this pattern:

```
angular
  .module('jsSdk').service('jsSdk.venue.resource', [
    'jsSdk.resourceFactory', (resourceFactory) => {

      const ENDPOINT = '/venue/:id';
      const PARAM_DEFAULTS = {
        id: '@id'
      };

      let Venue = resourceFactory(ENDPOINT, PARAM_DEFAULTS, {});

      return Venue;
    }
  ]);
```

The endpoint for your resource should always include the ```id``` param,
and be sure to specify the ```id``` param in ```PARAM_DEFAULTS```.


###Caching

**js-sdk** includes support for caching API calls at the Angular.js Resource level. Use the ``cacheConfigProvider``, and call ``.cacheResourceEndpoints`` to specify which endpoints to cache. Example:


 ```
 angular.module('angularApp').config([
  'jsSdk.cacheConfigProvider',
  (cacheConfigProvider) => {
    cacheConfigProvider
      .cacheResourceEndpoints('jsSdk.venue.resource', [
        'list'
      ]);
  }
]);
```