Developing Add-ons

Add-on states

Installed Add-ons have 3 states/stages:

disabled

• Storeganise will not call the Add-on events/webhooks.
• The external system cannot access the Storeganise account.

paused

• Storeganise will not call the Add-on events/webhooks.
• The external system can access the Storeganise account.
• This is the default state when an Add-on has just been installed.

enabled

• Storeganise will call the Add-on events/webhooks.
• The external system cannot access the Storeganise account.

Outline on how to use an Add-on

Get data from the request

// Get the event data from the request body
const {
  type, // The event type, e.g. `user.created`, `job.unit_moveIn.completed`
  data = {}, // An object of event data; contains IDs depending on the event type, e.g. userId    , jobId    
  apiUrl, // The base URL of Storeganise API
  addonId, // The ID of the addon which called this webhook; the addon contains the business-specific customFields/settings
} = req.body;

Fetch Storeganise API

function StoreganiseApi({ apiUrl, addonId }) {
  return function fetchSg(path, {
    method = 'GET',
    body,
  } = {}) {
    return fetch(`${apiUrl}${path}`, {
      method,
      headers: {
        'Content-Type': 'application/json',
        Authorization: `Addon ${addonId}|${config.sgApiKey}`,
      },
      body: body && JSON.stringify(body),
    })
      .then(async response => {
        const data = await response.json().catch(() => ({}));
        if (!response.ok) {
          console.error(`Error calling ${method} ${apiUrl}${path}: ${response.status} ${response.statusText}`); 
          const err = Object.assign(new Error(), data.error);
          err.status = response.status;
          throw err;
        }
        return data;
      });
  }
}

Fetch addon details

const fetchSg = storeganiseApi(req.body);
const addon = await fetchSg(`/v1/admin/addons/${addonId}`);

Handle request data

Example of a move-in event:

const { unitRentalId } = data;
const rental = await fetchSg(`/v1/admin/unit-rentals/${unitRentalId}?include=unit,owner,customFields`);
// now call remote API using addon.customFields for the credentials, and rental data to sync

Conventions for access controls Add-ons

• If unit.customFields.{prefix}_id is set, it'll override unit.name for the unit name to sync on the remote API
• If unit.customFields.{prefix}_id is set to NONE, it skips synchronisation for this unit
• Useunit.customFields.{prefix}_overlocked (Booleans custom field) for the overlocking status of the unit
• Useunit.customFields.{prefix}_accessCode or unit.customFields.{prefix}_pinCode or other relevant names for the access codes (String custom field) and generate this value randomly with enough digits (at least 6)
• Useunit.customFields.{prefix}_resync (Boolean custom field) to action a resync for this unit

note: prefix is the name of the addon, for example it could be pti , bearbox , noke