npm package: @mytomorrows/javascript-sdk
Description: The jQuery Javascript client used to communicate with the myTomorrows backend API.
Author: Travis Dunn
Latest version: 0.17.4

# myTomorrows Javascript SDK

This package contains the Javascript client used to communicate with the myTomorrows backend API. The SDK depends on jQuery for networking and utility functions. The package can be loaded as either a frontend plugin or sever-side library via npm, bower, etc.

https://mytomorrows.com/

Current version is: **0.17.4**

### Overview

The myTomorrows API is provided as a public web service and research tool; no registration is required to use the API, though requests may be rate-limited to prevent abuse.

The API enables users to explore worldwide clinical trial registry databases (such as from clinicaltrials.gov and EudraCT) along with associated medical conditions and inventions, published as schema.org medical objects. Users can additionally manage their myTomorrows platform accounts and track platform content updates.

Please contact the myTomorrows tech team with any questions:

tech@mytomorrows.com

### Installation

There are two ways to setup the API client library.

First, by including it as a script source in a page with access to the global jQuery `$` function alias, e.g.

    <script type='text/javascript' src='js/mytomorrows-javascript-sdk.js'></script>

Second, using the CommonJS style, e.g.

    require ('@mytomorrows/javascript-sdk');

In some cases it may be preferable to configure the library as an NPM package, e.g.

    "dependencies": {
      "mytomorrows-javascript-sdk": "git+https://github.com/myTomorrows/mytomorrows-javascript-sdk.git"
    }

NOTE: this package is under development and not yet published to the NPM Registry; to manually install via NPM you can run:

    npm install -g @mytomorrows/javascript-sdk

### Configuration

The SDK is configured through the `setOptions()` method which returns `this` as a convenience, e.g.

    var MT = $.MyTomorrows.setOptions({
      baseUrl: "https://api.mytomorrows.com/api/v1",
      debug: false,
      authToken: null,
      format: "json",
      clientPlatform: "js",
      statusCodeCallbacks: {
        404: function(){ console.log(404) },
        500: function(){ console.log(500) }
      }
    });

+ **baseUrl:** Sets the API server's URI; can be used for switching MyTomorrows environments or API versions
+ **debug:** If true, API request and response output is logged to the console. 
+ **authToken:** A user account's API authentication token. If provided, requesets to the API will be authenticated for that user.
+ **format:** Sets the response serialization format to either `json` or `xml`.
+ **clientPlatform:** Sets a custom `X-Client-Platform` HTTP header that identifies the API platform.
+ **statusCodeCallbacks:** Sets a global callback that is executed when the given status code is returned from an API call. Note, only `404` and `500` codes are supported; other errors should be handled with the ajax promise.

### Authorization

MyTomorrows user accounts can be authorized using the SDK's `signIn()` method. 

The SDK does not store credentials for reuse across sessions, however the signin response returns a `data.token` string that can be used to initialize the SDK for an authenticated user with a token the consumer app has stored, e.g.

    $.MyTomorrows.setOptions({token: "1234567890"})

or 

    require('mytomorrows-javascript-sdk').setOptions({token: "1234567890"})


### API Documentation

Internally the SDK uses the jQuery $.ajax request, and all API methods return a deferred `jqXHR` object to which completion methods can be bound, e.g.

    $.MyTomorrows.API.searchDiseases("cancer")
      .done(function(body, textStatus, jqXHR) {
      })
      .fail(function(jqXHR, textStatus, errorThrown ) {
      })
      .always(function(dataOrjqXHR, textStatus, jqXHROrerrorThrown) {
      });  

The API response body contains a JSON envelope standardized in the following object structure, e.g. 

    {
      status: "success",
      code: 200,
      message: null,
      data: {
        results: [ ... ],
        totalCount: 100
      }
    }

+ **data:** Required. A JSON object containing the serialized results of the request.
+ **status:** Required. Can be one of either `success`, `failure`, or `error`. 
+ **code:** Required. The HTTP status code of the response, e.g. 200, 204, 401, 500, etc.
+ **message:** Optional. If the status is `failure` or `error`, the message contains a string description of what went wrong.

Note, the API may use the full range of HTTP status codes.

#### API Methods

**$.MyTomorrows.API.getMedicalCondition(id)**
**$.MyTomorrows.API.getMedicalConditions(page)**
**$.MyTomorrows.API.searchMedicalConditions(query)**

**$.MyTomorrows.API.getMedicalTreatment(id)**
**$.MyTomorrows.API.getMedicalTreatments(diseaseIdOrName, treatmentQuery, interventionName, page, country, gender, phase, internal)**
**$.MyTomorrows.API.getMedicalTreatmentDisclosure(country)**

**$.MyTomorrows.API.getMedicalTrial(id)**
**$.MyTomorrows.API.getMedicalTrials(diseaseIdOrName, trialQuery, interventionName, page, country, gender, phase)**

**$.MyTomorrows.API.signUp(userType, email, password, country, gender, birthDate)**
**$.MyTomorrows.API.signIn(email, password)**
**$.MyTomorrows.API.signOut()**
**$.MyTomorrows.API.requestPassword(email)**
**$.MyTomorrows.API.resetPassword(token, new_password)**
**$.MyTomorrows.API.confirmAccount(token)**

**$.MyTomorrows.API.getAccount()**
**$.MyTomorrows.API.updateAccount(email, password, newPassword, country, locale, firstName, lastName, gender, birthDate, newsletter)**
**$.MyTomorrows.API.updateProfessionalDetails(specialisms)**
**$.MyTomorrows.API.getUserDisclosure()**

**$.MyTomorrows.API.subscribe(conditionId)**
**$.MyTomorrows.API.unsubscribe(conditionId)**

**$.MyTomorrows.API.getStatistics()**

**$.MyTomorrows.API.submitContactForm(comment, country, email, firstName, lastName, subject, treatmentQuestion, imA, regarding, phone, timeSlot, language)**

#### Utility Methods

**$.MyTomorrows.API.version()**

Returns the `[MAJOR].[MINOR].[PATCH]` version string of the SDK.

**$.MyTomorrows.API.isAuthenticated()**

Returns a boolean indicating authentication status. This only indicates whether the SDK is configured with a token, not whether the token is accepted as valid by the backend API.

**$.MyTomorrows.API.setOptions()**

Sets various configuration options for the SDK (see the preceeding README section on Configuration) and returns the SDK itself as a convenience.

### About

DISCOVER EXPANDED ACCESS PROGRAMS  

myTomorrows provides physicians and patients that are excluded from clinical trials access to drugs in development. We focus on disease areas with unmet needs; oncology, neurology, psychiatry and rare diseases.  

Expanded Access Programs include treatments for Severe Depression, Primary Liver Cancer (HCC), Chronic Fatigue Syndrome (CFS), Chest Wall Breast Cancer and Peripheral T-cell Lymphoma (Blood Cancer). 

https://mytomorrows.com/

## Development

To perform unit tests, install qunit via NPM, and then run:

    node_modules/.bin/qunit-cli test/tests.js 

To publish a new version of the api after making updates: 

    npm login <username,email,password>
    npm version <patch|minor|major>
    git add .
    git commit -m 'some changes'
    git push origin master
    npm publish .