npm package: @mobisysgmbh/msb-custom-auth-api
Description: API definition for custom authentication scripts in MSB App
Author: mobisys GmbH
Latest version: 2.3.1

# Custom Authentication API for MSB App

This package contains Custom Authentication API Contract files needed to develop Custom Authentication Scripts for Mobisys MSB App.

# Custom Auth Api

```ts
export interface CustomAuthApi {
  http: CustomAuthHttpClient;
  logger: CustomAuthLogger;
  appLauncher: CustomAuthAppLauncher;
  cookieStorage: CustomAuthCookieStorage;
  appInfo: CustomAuthAppInfo;
  deviceInfo: CustomAuthDeviceInfo;
  versionInfo: CustomAuthVersionInfo;
  nfc: CustomAuthNfc;
  // MSB App >= 3.14
  urlProcessor: CustomAuthUrlProcessor;
  // MSB App >= 3.15
  scanning: CustomAuthScanning;
  // MSB App >= 3.16
  foregroundHttp: CustomAuthForegroundHttp;
}
```

Contains available native modules

```ts
export interface CustomAuthentication {
  login(profile: CustomAuthProfile): Promise<AuthConfig>;
  logout(profile: CustomAuthProfile): Promise<void>;
}
```

Interface that has to be implemented as a authentication script

```ts
export interface AuthConfig {
  headers: Record<Header, Value>;
  authOptions?: AuthOptions;
}

export interface AuthOptions {
  msbAuthentication: 'basic' | 'secureSession' | 'clientCert';
  useCustomHeaders: boolean;
}
```

AuthConfig consists of two parts. Headers and AuthOptions. The headers contain the headers that are to be used for further MSB communication.
AuthOptions configures whether further MSB authentication should be carried out afterwards. To do this, select the desired authentication ‘basic’ | ‘secureSession’ | ‘clientCert’ and whether the MSB header or the header of the custom authentication should be used

```ts
interface CustomAuthProfile
```

exposes MSB App settings. Those are readonly and can not be changed.

```ts
interface ScriptSettingsDescriptor
```

Interface that describes the data structure the MSB App expects for script settings.

It consists of two parts. A mandatory hide credentials script item and an optional array of script items.

```ts
export interface HideCredentialInputsScriptItem {
  key: 'hideCredentialInputs';
  description: 'Hide credential inputs';
  readonly dataType: 'Boolean';
  readonly uiType: 'Checkbox';
  readonly defaultValue: boolean;
}
```

```ts
export type ScriptItem =
  | BooleanScriptItem
  | EnumScriptItem
  | NumberScriptItem
  | StringScriptItem;
```

The hide credential inputs script item controls the visibility of credential inputs in the MSB App Login Screen.
The array of script items represents script settings that should be used in addition to MSB App settings.
A separate UI is generated in the MSB App for these settings.

# Native modules

## App Info

`getAppName(): Promise<string>`

Returns the name of the app. Most likely "MSB App" unless Mobisys changes the name.

`getPackageName(): Promise<string>`

Returns the package name of the app - the reversed domain name app identifier like com.example.appname

`getVersionCode(): Promise<string>`

Returns the build identifier of the app

`getVersionNumber(): Promise<string>`

Returns the version number of the app

## App Launcher

`launchByUri(uri: string): Promise<void>`

Launches a App by URI. 'https://google.com' would start the browser and open googles website. 'slack://open?team={1234}' would open slack app and go to team chat with team id 1234

## Cookie Storage

`setCookie(url: string, cookie: string): Promise<void>`

Sets a cookie for a specific url. Cookies are cleared after each log out off an MSB application.

## Device Info

`isAndroid(): Promise<boolean>`

`isIOs(): Promise<boolean>`

`isIPad(): Promise<boolean>`

`isElectron(): Promise<boolean>`

`isWindows(): Promise<boolean>`

Those can be used to check the platform.

`getUserAgent(): Promise<string>`

Returns current user agent string of current WebView depending on platform.

`getDeviceName(): Promise<string>`

Returns user-friendly name of the device.

`getOem(): Promise<string>`

Returns the manufacturer

`getOs(): Promise<string>`

Returns OS name and version

`getPlatformName(): Promise<PlatformName>`

Returns the device's operating system name.

`getDeviceDescription(): Promise<string>`

On mobile platforms returns model name. On Desktop returns current user name.

`getSerial(): Promise<string>`

Tries to retrieve the serial number on mobile platforms. On Desktop returns the uid.

`getUsername(): Promise<string>`

Not supported on mobile platforms. Throws error. On Desktop retruns the user name.

`getUuid(): Promise<string>`

Get the device's Universally Unique Identifier. The details of how a UUID is generated are determined by the device manufacturer and are specific to the device's platform or model.
The UUIDs aof a device are not guaranteed to be the same over the lifetime of a device. Sometimes new IDs are generated on factory resets or depending

`isScopedStorageEnabled(): Promise<boolean>`

Checks wether scoped storage is enabled on Android. This is always the case from SDK Level 30. Retruns false on other platforms.

`cordovaVersion(): Promise<string>`

Returns the version of Cordova running on the device.

## Http

Allows sending HTTP Get and Post requests.

`get({ url, headers }: GetParams): Promise<HttpResponse<string>>`

Sends a HTTP GET request to provided url containing provided headers. ResponseType is set to text.

`getArrayBuffer({ url, headers }: GetArrayBufferParams): Promise<HttpResponse<ArrayBuffer>>`

Same as `get` but ResponseType is ArrayBuffer.

`getBlob({ url, headers }: GetBlobParams): Promise<HttpResponse<Blob>>`

Same as `get` but ResponseType is Blob.

`post({ url, headers, body }: PostParams): Promise<HttpResponse<string>>`

Sends a HTTP POST request to provided url containing provided headers and body. Body has to be a string.

`postArrayBuffer({ url, headers, data }: PostArrayBufferParams): Promise<HttpResponse<string>>`

Same as `post` but data has to be an ArrayBuffer.

## Logger

`log(...message: unknown[]): Promise<void>`

`error(...message: unknown[]): Promise<void>`

`warn(...message: unknown[]): Promise<void>`

`info(...message: unknown[]): Promise<void>`

`debug(...message: unknown[]): Promise<void>`

Use these to write logs to log files of MSB App. The log levels are set in MSB App settings.

## Version Info

Provides build time meta data.

`getVersionString(): Promise<string>`

Returns MSB App version.

`getBuildNumber(): Promise<number>`

Returns MSB App build number.

`getFullVersionString(): Promise<string>`

Returns both version and build number in one string.

`getDateString(): Promise<string>`

Returns the date on which app was built. In ISO 8601 format.

`getYearNumber(): Promise<number>`

Returns the year in whcih app was built.

`getSapVersion(): Promise<string>`

Returns current MSB App version in SAP readable format. String length max 4.

`isLocalBuild(): Promise<boolean>`

Returns if the MSB App was build localy on a dev machine.

`getOssLicenseURL(): Promise<string>`

Returns the URL to Open Source Software Licenses.

## NFC

Provides data from NFC tag scans.

`startNfcCapture(captureDataHandler: (data: string) => void): Promise<void>`

Provides scanned data to a handler. Handler is called on each new scan.

`stopNfcCapture(): Promise<void>;`

Stops data capturing.

## Url Processor

`setHandler(handler: CustomAuthAppUrlHandler<T>): void`

Sets a handler that is called on deeplink calls of _msbapp://v1/authentication/customauth/v1_ or _http://msbapp.mobisys.com/v1/authentication/customauth/v1_. The data returned by the handler depends on the query parameters of the called url, but is always a **Record<string, string>**.

_msbapp://v1/authentication/customauth/v1?param1=paramOne&param2=paramTwo...&paramN=paramN_ would result in following object beeing returned:

```ts
{
 param1: 'paramOne'
 param2: 'paramTwo'
 ...
 paramN: 'paramN'
}
```

`clearHandler(): void`

Removes all handlers

## Scanning

`enableScanning(params: ScanningParams): Promise<void>`

Enables the scanning method that is currently selected in the app settings.

```ts
export interface ScanningParams {
  scanDataHandler: ScanDataHandler;
  scanButtonPosition?: ScanButtonPositionParams;
  config?: ScanConfig;
}
```

_scanDataHandler_ - handler which receives the data scanned and the barcode type

```ts
type ScanDataHandler = (data: string, type: string) => void;
```

_config_ - configuration for hardware scanner integration such as Zebra and Honeywell etc.. This is documented in user documentation of the EDT component on mobisys portal

**Camera Scanning**

_scanButtonPosition_ - contains configuration for scan button placement

- _targetElement_ - defines the target HTML element where the scan button should appear

- _scanButtonDimensionsFactor_ - determines the size of scan button

- _mode_ - sets positioning strategy.

```ts
export type ScanButtonPositioningMode =
  | 'Above'
  | 'Below'
  | 'Dynamic'
  | 'Fixed'
  | 'Hidden';
```

_Above_ and _Below_ positions scan button above or below the target element. _Dynamic_ switches between these two dependent on available space around the target element. _Fixed_ positions the button in the upper right corner of the screen and is much bigger than the other options.

_Fixed_ is the default setting if no scanButtonPosition is provided.

`disableScanning(): Promise<void>`

Disables scanning

## Foreground HTTP

`foregroundHttp: CustomAuthForegroundHttp`

Provides methods for polling HTTP endpoints in the foreground. Available in MSB App >= 3.16.

### Methods

- `pollWithHttpGet(pollingInterval: number): void`

  Starts polling with HTTP GET requests at the specified interval (in milliseconds).

- `stopPollingWithHttpGet(): Promise<void>`

  Stops the polling process.

Use this module to perform periodic HTTP GET requests while the app is in the foreground, for example to check authentication or session status.