Snowplanner API service

Javascript service that abstracts and leverages interaction with Snowplanner REST API

Install

npm i @snowplanner/api-service-js

Usage

The service is preconfigured to work with Snowplanner API v1. Read the API documentation to know more.

import snowplanner from '@snowplanner/api-service-js';

const loadData = async () => {
  const { data: calendar } = await snowplanner.getCalendar();
  const { data: zones } = await snowplanner.getZones();
};

API resources are available via service methods and return a promise that can be used with async/await.

• login({ email, password } | { code } [, target])

• invite({ email, role [, message [, language]] })

• requestPasswordReset(email [, language])

• resetPassword(password, resetToken)

• changeTeam(teamId)

• signup({ name, surname, password [, avatar] }, signupToken)

• join(joinToken)

• getUsers({ role })

• deleteUser(id)

• getProfile()

• updateProfile({ name, surname, avatar, , preferences, password, oldPassword })

• getZones()

• getObstacles()

• getCalendar()

• getVehicles()

• getVehicle(id)

• getVehicleTrajectory(vehicleId, { day })

• getVehicleStats({ vehicleId, day })

• startVehicleSession(userId)

• updateVehicleSession(sessionId, session{})

• finishVehicleSession(sessionId)

• getSnowDepth({ day })

• getSnowStats(type, { options })

Authentication

Snowplanner API resources are protected with JWT authentication. The service must be authenticated before making any request.

import snowplanner, { TokenManager } from '@snowplanner/api-service-js';

const tokenManager = TokenManager();

// Authenticate the service before requesting protected resources
const authenticate = async (email, password) => {
  const { data: user } = await snowplanner.login({ email, password });
  const { accessToken, refreshToken } = user;
  tokenManager.setTokens({ accessToken, refreshToken });
};

// 
const deauthenticate = () => tokenManager.clearTokens();

Access token will automatically be embedded in future requests. Refresh token is kept in localStorage to allow token refresh.

Token Refresh

The service provides a mechanism to refresh access token automatically after a 401 error is returned from the API.

The request that triggered the unauthenticated response is kept in a queue and redone after the access token has been refreshed.

Access token can also be refreshed programatically using the tokenManager.

import { TokenManager } from '@snowplanner/api-service-js';

const tokenManager = TokenManager();

const task = async () => {
  try {
    // Some login here...
  } catch (error) {
    const token = await tokenManager.refreshAccessToken(error);
  }
}

The tokenManager exposes event callbacks that allow to run some logic after a token refresh has been successful or has failed. It may be useful to use the accessToken in some logic, to display an error message or to logout user.

tokenManager.onRefreshTokenError(error => {
  console.log(error.message);
  tokenManager.clearTokens();
  store.dispatch('logout');
});

tokenManager.onRefreshTokenSuccess(token => store.commit('SET_ACCESS_TOKEN', token));