applicaster-stars

Applicaster Stars js wrapper

This is an Applicaster utility package which provides simple access to Stars API and UQ client SDK features.

How to use it

simply run

$ npm i -S applicaster-stars

Inside your js application, you now have access to a Stars Object which provides three methods (more detailed documentation below) :

• starsInit(params) : returns an object which connects to the stars API and exposes a method to fetch events from a timeline
• UQInit() : returns an object which provides access to methods to deal with UQ client SDK features.

Here's how you access and use those methods in JS code :

import { starsInit, UQInit } from "applicaster-stars";
 
const stars = starsInit(params);
stars.fetchEvents(optionalSinceParam)
     .then( events => console.log(events));
 
const polling$ = stars.createPollingObservable(params);
 
const subscriptionHandler = x => console.log(x);
const errorHandler = error => console.error(error);
const completionHandler = () => console.log('done');
 
polling$.subscribe(subscriptionHandler, errorHandler, completionHandler);
 
const uq = UQInit(params);
uq.getQuestionData(optionnalQuestionUrl)
  .then(question => question.log(question));
 
 

APIs

starsInit(params) : stars Object

params = {
    accountId: '' // <String>, required - Applicaster account Id
    timelineId: '' // <String>, optional - Id of the main timeline you will be working on.
    timezone: 7200 //  <Number>, optional - Timezone of the episode. in seconds from GMT (GMT + 1 => 3600, GMT + 2 => 7200). If not provided, will use the first timezone it finds
    env: '' // <String>, optionnal - Environment desired. leave it null for Production, set to qa, demo, or server if required. use test only for unit tests
}

this function returns an object which connects to the stars API and exposes a method to fetch events from a timeline. The stars object is designed to run the lowest possible number of requests. It will store feeds and zone Id in private variables to be reused when necessary, or initialized otherwise

stars.fetchTimelines() : (Array)

returns a promise which resolves to an array containing all timelines enabled for the given account Id

stars.fetchTimeline(timelineId) : Promise()

returns a promise which resolves to the specified timeline object

stars.fetchFeeds(timelineId) : Promise(Array)

returns a promise which resolves to an array containing the feeds (event sources) for the given timeline Id

stars.fetchEpisodes(timelineId): Promise(Array)

returns a promise which resolves to an array of episodes : up to 5 upcoming episodes, if any.

stars.fetchEvents(params) : Promise(Array)

returns a promise which resolves to an array containing all the timeline events from the provided timestamps, for all feed ids provided.

params = {
    since: 1465576780 // <Number>, optional - Epoch Timestamp (in seconds) from which fecthing of the timeline events should start. if omitted, will return all past events
    timelineId: '' // <String>, optional - id of the timeline you want to fetch events from. can be omitted if stars is initialized with a timeline
    feedIds: [] // Array<String>, optional : array of feeds (event source) Ids you want to get events from. If not provided, will fetch from all feed 
}

stars.fetchTimelineCustomizations(timelineId) : Promise()

returns a promise which resolves to an object containing the timeline customization data.

stars.createPollingObservable(params) :

params = {
    startTime: 1465576780 // <Number>, optional - Epoch Timestamp (in seconds) from which fecthing of the timeline events should start.
    timelineId: '' // <String>, optional - id of the timeline you want to fetch events from. can be omitted if stars is initialized with a timeline
    pollRate: 2000 // Number, optional - interval to use for polling. if not specified, uses the interval value provided in the starsInit constructor. If not provided either, defaults to 5000
    pollFunction: function(timestamp) { // ... } // Function, optional. can be used to override the polling behaviour
}

this method returns an observable which fetches events every pollRate ms and delivers new events from the timeline. The Observable only emits the latest event fetched from the timeline, if it is different from the previously emitted event. If you need to get all events, use the above method instead.

the default polling function is the following :

function pollEvents(_timestamp, _timelineId) {
        return stars.fetchEvents({ since: this.timestamp || _timestamp, timelineId: _timelineId })
            .then(events => {
                if (events.length) {
                    const event = events[0];
                    this.timestamp = event.timestamp;
                }
                return events;
            });
    }

It does so to make sure each request to the stars api events.json endpoint is made with the timestamp of the last retrieved event. You can override this function to whatever you want. When the polling function is ran in the observable, it is bound to the stars object, therefore accessing all stars methods & properties.

stars object properties :

stars.timestamp : Number

Epoch timestamp used when calling stars api events.json endpoint. This property is used as default for stars.fetchEvents, if no timestamp is provided in the constructor

stars.feeds : Object

This property stores the full event sources object for quick reference if needed.

UQInit() : UQ Object

this method returns a singleton which provides access to methods to deal with UQ client SDK features.

getQuestionData(questionUrl) :

This method returns a promise which resolves to the question object from a UQ Url (the URL from starlight, with the appli-payload param);

answerQuestion(questionUrl, answerId, userToken, env)

This method submits an answer to a question. The userToken param is optional. If not provided, a uuid() token will be generated. If you want to make sure users answer only once, you should create your own userToken the env param is optionnal. if not provided, will resolve to production. other possible value is 'staging'

How to develop

• clone this repo
• install dependencies

$ npm install

• kick off test server (mocked stars API - will run on port 3000 so you need this port to be available)

$ npm run testServer

• enable test watch

$ npm test -- --watch -v