npm package: @natec/mef-dev-platform-connector
Description: Mef.dev platform connector library
Latest version: 17.0.7


# Mef-Dev-Platform-Connector

The library is designed to write Angular plugins (as Trusted application on the architecture below) and simplify the interaction within the MEF.DEV serverless platform [mef.dev](https://mef.dev/).

![Architecture platform](https://natec.tech/wp-content/uploads/2021/11/%D0%93%D1%80%D0%B0%D1%84%D0%B8%D0%BA-1_ok-1-1.svg  "Architecture platform")

## Get the right version

| Angular / CLI | @natec/mef-dev-platform-connector | 
|-|-|
| 13 / 13 | 1.0.0 | 
| 14 / 14 | 14.0.0 | 
| 15 / 15 | 15.0.0 | 
| 16 / 16 | 16.0.0 | 

## General types and classes

### static class PlatformHelper

The main class in which the methods of working with the MEF.DEV platform 

### class MefDevAuthInterceptor

Ensures security headers are added to requests. It is used as an ordinary interceptor. An example is [here](https://github.com/mef-dev/tutorial-ui-plugin/blob/28db6999e9c3865a5330f5ebe64fa3411ef28649/src/app/app.module.ts#L51)

### class PlatformSseHelper

A service class that takes over part of the logic for working with SSE. Can be used for cases where only work with SSE is required.


## General methods

The library's features are located by the static class **PlatformHelper**. Its main methods are given in the table below:

|Name|Return type|Description|
|-|-|-|
| `PluginDataSync` | *UiProfileViewModel* | Return plugin data synchronous if data will previously downloaded (PlatformHelper.loadPlatformOptions() or PlatformHelper.setOptions(...)) |
| `getPluginData()` | *Observable \<UiProfileViewModel\>* | Return plugin data asynchronous. After successfully loading, data stored(session mode). Initiates loading of plugin data if no previusly loaded. |
| `setOptions(options: GetInfoSpecificOptions)` | *Observable \<UiProfileViewModel\>* | This method used for setup data for running plugin on local machine(debug mode).  Initiates loading of plugin data. Example and best practice [on this demo](https://github.com/mef-dev/tutorial-ui-plugin/blob/master/src/app/resolvers/platform-connection.resolver.ts#L28located) |
| `loadPlatformOptions()` | *Observable\<UiProfileViewModel\>* | Load and return plugin data asynchronous if plugin in production mode(work under platform). After successfully loading, store plugin data. For development mode use `PlatformHelper.setOptions(...)` |
| `getAssetUrl ()` | *string* | Return the asset path. In debug mode(on local machine) is 'assets'. But after uploading plugin in platform this path change |
| `updatePluginsRoutes(routes: Routes)` | *Routes* | Update plugin components routes. After upload on platform path is changed. Its method help platform resolve plugin routes. `Required to usage`, [code example](https://github.com/mef-dev/tutorial-ui-plugin/blob/master/src/app/app-routing.module.ts) |
| `getSseStream()` | *Observable\<any\>* | Emit object from plugin SSE stream. |
| `sendSseStream(data: any)` | *Observable\<any\>* | Send any object to plugin SSE stream.  |

Specific methods(Use for creating own secure interceptor or other stuff)

|Name|Return type|Description|
|-|-|-|
| setAuthHeaders(request: HttpRequest<any> \| any, bearerToken: string \| undefined = undefined) | *HttpRequest\<any\>* | Used for manual adding security headers for request. |
| refreshPlatformAccessToken() | *Observable\<string\>* | Used for manual initiates refresh platform token. Token expire in few minutes. 455 request status signaled about token expiration. |

Depricated methods list:

|Name|Return type|Description|
|-|-|-|
| `getPluginLocalData()` | *PluginLocalData \| undefined* | Return plugin data (old interface). Works only in production mode |
| `_getPlatformIHttpService()` | *IHttpService \| undefined* | Return platform instance of IHttpService (old interface). Works only in production mode |

# Scripts

There are two main scripts available: `mef-dev-publish` and `generate-version-file`. To run them, use the following command: `npm explore @natec/mef-dev-platform-connector -- npm run {script} [argsName=argValue]`

## generate-version-file

This script creates a `version.js` file containing a unique identifier for any plugin version. It is required for publishing on the mef.dev platform.

> Example: `npm explore @natec/mef-dev-platform-connector -- npm run generate-version-file`

## mef-dev-publish

This script builds, generates the `version.js` file, and publishes the plugin to the mef.dev platform from the CLI, without any manipulations on the site interface.

> Example: `npm explore @natec/mef-dev-platform-connector -- npm run mef-dev-publish debug=true

### Argument List

| Argument | Description | 
|-|-|
| pluginBuildCommand | npm script what start build plugin process, default: ```build:plugin``` | 
| apiUrl | platform API web address, default: ```https://sandbox.mef.dev``` | 
| bauth | Basic credentials for publish, format ```NAME:PASS``` | 
| alias | Alias of plugin (optional) | 
| updateTenantVersion | Update tenant plugin version after upload, default: `true`| 
| updateConfiguration | Update plugin configuration after upload, default: `false` | 
| debug | Log expanded information, default: `false` | 

### Environment file

You can declare any arguments in `environment.ts`. Note that CLI arguments take priority.
``` typescript
// /src/environments/environment.ts
import { PLUGIN_VERSION } from './version';

export const environment = {
  production: false,
  version: PLUGIN_VERSION.version,
  alias: 'test',
  bauth: 'NAME:PASS',
  apiUrl: 'https://api.mef.dev'
};
```
### metadata.json file
At the root of the project (near the angular.json file), you need to create a metadata.json file. This file will be automatically applied for publication and stores the data required for publication

```
// /metadata.json
{
  "name": "basic-request-demo",
  "serviceType": "APIUI",
  "description": "basic-request-demo",
  "dependencies": [],
  "config":{
    "routesUI":[
      {
          "lang":"en",
          "routerLink":"plugin-information",
          "label":"plugin-information"
      }
    ]
  },
  "externalUrl": null,
  "configuration": "{ \"someProp\": \"some value\" }"
}
```