@airspacelink/portal-apps-sdk

Package name: Portal Apps SDK

Package author: Airspace Link

Installation:

npm install @airspacelink/portal-apps-sdk

Summary

The Portal Apps SDK enables developers to create Marketplace Apps for use within Portal Core. Portal Core handles user authentication and data access and passes requested information to the Marketplace Apps via invocation of SDK functions.

Technically, Marketplace Apps run inside an iframe context and the SDK uses Window.postMessage() and MessageEvents to send data back and forth between the Marketplace App and Portal Core.

The Portal Apps SDK uses a request-response model. Communication is initiated by the Marketplace App via SDK methods (request). All methods return a Promise which contains data sent from Portal Core when resolved (response).

SDK Methods

• getUserInfo()
• getSession()
• getAccessToken()
• getAppContext()

getUserInfo()

• Parameters: none
• Returns: Promise<UserInfo>
• Description: Used to request the profile information for the logged in user. Promise will resolve with a value of type UserInfo.

EXAMPLE

import { AppsSDK } from '@airspacelink/portal-apps-sdk';

const portal = new AppsSDK();
portal.getUserInfo().then(userInfo => {
  console.log(JSON.stringify(userInfo));
});

/* logs:
{
  "email": "[email protected]",
  "firstName": "Bob",
  "lastName": "Jones",
  "phone": "+1 (555)-867-5309",
  "certificateNumber": "KLJLKJ0980980✈️",
  "certificateIssueDate": "2021-09-28"
}
*/

getSession()

• Parameters: none
• Returns: Promise<Session>
• Description: Used to request the session context for the logged in user. Promise will resolve with a value of type Session.

EXAMPLE

import { AppsSDK } from '@airspacelink/portal-apps-sdk';

const portal = new AppsSDK();
portal.getSession().then(session => {
  console.log(JSON.stringify(session));
});

/* logs:
{
  "jurisdictions": [
    {
      "geoId": "01",
      "name": "AL"
    },
    {
      "geoId": "51",
      "name": "VA"
    }
  ],
  "org": {
    "id": "org_Wf44hhs3BLxqMS",
    "name": "Senatus Populusque Romanus"
  }
}
*/

getAccessToken()

• Parameters: none
• Returns: Promise<string>
• Description: Used to request the access token assigned to the user upon authentication. Promise will resolve with a value of type string.

EXAMPLE

import { AppsSDK } from '@airspacelink/portal-apps-sdk';

const portal = new AppsSDK();
portal.getAccessToken().then(accessToken => {
  console.log(accessToken);
});

/* logs:
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c
*/

getAppContext()

• Parameters: none
• Returns: Promise<AppContext>
• Description: Used to request the app execution context. Promise will resolve with a value of type AppContext.

EXAMPLE

import { AppsSDK } from '@airspacelink/portal-apps-sdk';

const portal = new AppsSDK();
portal.getAppContext().then(appContext => {
  console.log(appContext.slot);
});

/* logs:
{
  "kind": "default"
}
*/

Error Handling

Portal Apps SDK includes some classes that can be used to handle error conditions. If an underlying network request was cancelled, the SDK method will throw CmdCanceledError. If there was another type of failure, the SDK method will throw CmdFailedError which contains a message property that can be used to determine the underlying cause.

import { AppsSDK, CmdCanceledError, CmdFailedError } from '@airspacelink/portal-apps-sdk';

const portal = new AppsSDK();

portal.getUserInfo().catch(err => {
  if (err instanceof CmdCanceledError) {
    // Cmd cancelled
  }

  if (err instanceof CmdFailedError) {
    // Failed for some reason. Use the `message` property to determine cause.
    console.error(err.message);
  }
});

Copyright (c) 2023 Airspace Link