ec.sdk

This is the SDK for all ec.APIs by entrecode. By entrecode.

Documentation can be found here. If you like to see some code look here.

Getting Started

In order to use this SDK you should be familiar with ec.APIs and the concepts behind those. Please refer to the official documentation to get a basic understanding. The documentation you are reading now will first introduce the basic concept when using the SDK. Secondly it is the complete API documentation for ec.sdk.

For every ec.API you will find an API connector. Use one of those to connect to a certain ec.API. Login and logout for ec.users are special cases and are done in Session API connector. All API connectors of a certain environment share some information. The most important one is any access token either received with Session#login or by calling Core#setToken. This means you can specifiy the token on any API connector and it will be automatically used by all other API connectors. Also it will be saved in a cookie with the name <environment>Token. If any API connector receives a token related Error (Problem) it will be automatically removed from all API connectors and a logout event is triggered. A special case is PublicAPI since this will store the token in a cookie containing the environment and Data Manager shortID of the PublicAPI (for example: stagebeefbeefToken).

Since version 0.13.0 you can create a stand-alone API Connector. By calling the constructor with new Session({ noCookie: true }); the API Connector won't share its token with other API Connectors.

Every action you take in the ec.sdk will be validated before it will be sent as a request to ec.APIs. This means that the provided json schemas are used.

Installation

npm i --save ec.sdk

ES6 / Webpack

Add the following in your webpack.config.js.

const config = {
  // …
  node: {
    fs: 'empty',
    Buffer: false,
    net: 'empty',
    tls: 'empty',
  },
};

Then you can start coding:

import { Session, Accounts, DataManager } from 'ec.sdk';
import AccountResource from 'ec.sdk/src/resources/accounts/AccountResource';
import DataManagerResource from 'ec.sdk/src/resources/datamanager/DataManagerResource';

class MyExample {
  session: Session;
  accounts: Accounts;
  dataManager: DataManager;

  me: AccountResource;
  dm: DataManagerResource;

  constructor() {
    session = new Session();
    accounts = new Accounts();

    session.setClientID('rest');
    // this will also receive events from Accounts and DataManager
    session.on('error', console.error);
  }

  login(email, password) {
    session.login(email, password)
    .then((token) => {
      // if you use stand-alone API Connectors (`noCookie` set to true)
      accounts.setToken(token);

      // or anywhere in the code
      dataManager.setToken(session.getToken());
    });
  }

  setAccountLanguage(lang) {
    Promise.resolve()
    .then(() => {
      if (this.me){
        return this.me;
      }
      return this.accounts.me();
    })
    .then((me) => {
      me.language = lang;
      return me.save();
    })
    .then((meSaved: AccountResource) => this.me = meSaved);
  }

  loadDataManager(id) {
    if (!this.dataManager){
      this.dataManager = new DataManager();
    }

    this.dataManager.dataManager(id)
    .then((dm) =>{
      this.dm = dm;
    });
  }
}

Node

Require statements are different on node. Also, you probably don't want to share tokens in a node.js environment. You'll need to use noCookie or namespacing via cookieModifier.

const ec = require('ec.sdk');
const dataManager = new ec.DataManager({ environment: 'live', cookieModifier: 'myScriptName' });
dataManager.setToken(accessToken);

dataManager.dataManagerList()
.then(list => doSomthingWith(list))
.catch(console.log);

Browsers

This is not officially supported. Mainly exists for usage in jsfiddles or similar.

<script src="https://unpkg.com/ec.sdk/dist/ec.sdk.min.js"></script>
<script>
    console.log('My development stack is old and I should feel old');

    var dataManager = new ec.DataManager('live');
    dataManager.setToken(accessToken);
    dataManager.list()
    .then(list => doSomthingWith(list))
    .catch(console.log);
</script>

Development

Here are two notes on developing ec.sdk:

Please use Conventional Commits
When releasing a new version use npm run release <semver-version> – This will build docs and changelog etc, npm publish is handled by travis.