@enplug/sdk-dashboard - npm Package Compare versions

Comparing version 5.4.0 to 5.4.1

index.d.ts

@@ -0,0 +0,0 @@ import { EnplugDashboardSDK } from './types';

package.json

 {
   "name": "@enplug/sdk-dashboard",
-  "version": "5.4.0",
+  "version": "5.4.1",
   "description": "Enplug Dashboard SDK",
-  "types": "./index.d.ts",
+  "typings": "./index.d.ts",
   "scripts": {
     "clean": "rimraf dist/ && mkdirp dist",
-    "lint": "tslint -c tslint.json './src/**/*.ts' -e './**/*.d.ts'",
+    "lint": "eslint src/ --ext .ts --ignore-pattern *.d.ts --ignore-pattern *.spec.ts",
     "test": "karma start test/karma.conf.js",
@@ -15,5 +15,6 @@ "bundle": "npm run clean && webpack && npm run generateTypings",
     "release": "npm run bundle && enplug-release-sdk",
-    "release:prod": "npm run bundle:prod && enplug-release-sdk",
+    "release:prod": "npm run bundle:prod && enplug-release-sdk && npm run release:docs",
     "release:dev": "npm run bundle && enplug-release-sdk --dev",
-    "generateTypings": "tsc -d ./src/sdk.ts --declarationDir ./types --emitDeclarationOnly --allowJs"
+    "generateTypings": "tsc -d ./src/sdk.ts --declarationDir ./types --emitDeclarationOnly --allowJs",
+    "release:docs": "echo Building Enplug SDK docs... && cd ../enplug-docs && npm run release:prod"
   },
@@ -63,5 +64,13 @@ "repository": {
     "@types/node": "8.10.59",
+    "@typescript-eslint/eslint-plugin": "^4.28.4",
+    "@typescript-eslint/eslint-plugin-tslint": "^4.28.4",
+    "@typescript-eslint/parser": "^4.28.4",
     "command-line-args": "4.0.7",
     "dts-gen": "^0.6.0",
     "es6-shim": "0.35.5",
+    "eslint": "^7.31.0",
+    "eslint-plugin-import": "^2.23.4",
+    "eslint-plugin-jsdoc": "^35.5.0",
+    "eslint-plugin-prefer-arrow": "^1.2.3",
+    "eslint-plugin-tsdoc": "^0.2.14",
     "fs": "0.0.1-security",
@@ -71,9 +80,7 @@ "inquirer": "6.5.2",
     "jasmine-core": "2.99.1",
-    "karma": "4.4.1",
-    "karma-chrome-launcher": "2.2.0",
-    "karma-jasmine": "1.1.2",
-    "karma-phantomjs-launcher": "1.0.4",
-    "karma-phantomjs-shim": "1.5.0",
-    "karma-spec-reporter": "0.0.31",
-    "karma-typescript": "4.1.1",
+    "karma": "^6.3.4",
+    "karma-chrome-launcher": "^3.1.0",
+    "karma-jasmine": "^4.0.1",
+    "karma-mocha-reporter": "^2.2.5",
+    "karma-typescript": "^5.5.1",
     "mkdirp": "0.5.1",
@@ -86,3 +93,3 @@ "npm-run-all": "4.1.5",
     "ts-loader": "6.2.1",
-    "tslint": "5.20.1",
+    "tslint": "^6.1.3",
     "typescript": "~4.0.0",
@@ -89,0 +96,0 @@ "uglifyjs-webpack-plugin": "1.3.0",

types/account.d.ts

@@ -1,5 +0,29 @@
-import { Asset, DefaultAssetLevel, DeployDialogOptions, DisplayGroup, EnplugAccount, EnplugUser, FeedData, Layout, ThemeDefinition, ThemeAsset, FontDefinition, FontsApiItem, DefaultAsset, ZoningAppsResponse, ZoningConfig, AccountCustomPropertiesResponse } from './external-types';
+import { Asset, DefaultAssetLevel, DeployDialogOptions, EnplugAccount, EnplugUser, FeedData, Layout, ThemeDefinition, ThemeAsset, FontDefinition, FontsApiItem, DefaultAsset, ZoningAppsResponse, ZoningConfig, AccountCustomPropertiesResponse } from './external-types';
 import { BridgeBase } from './bridge/bridge-base';
+/**
+ * Account API is a part of the Dashboard SDK used for managing assets, and other app, user and account related data.
+ * Use global `enplug.account` object to access these methods.
+ *
+ * ```typescript title="Example usage of the Account API"
+ * const assets = await enplug.account.getAssets();
+ * ```
+ *
+ * Among others, this API allows you to fetch and manipulate the assets:
+ * - {@link getAssets|`enplug.account.getAssets()`} - fetch the asset list
+ * - {@link getAssetsByIds|`enplug.account.getAssetsByIds()`} - fetch provided assets
+ * - {@link saveAsset|`enplug.account.saveAsset()`} - creates/updates an asset, can display Deploy Dialog for editing
+ * - {@link deleteAsset|`enplug.account.deleteAsset()`} - removes an asset
+ * - {@link touchAsset|`enplug.account.touchAsset()`} - marks asset as recently viewed
+ *
+ * Other useful commands:
+ * - {@link getAccount|`enplug.account.getAccount()`} - fetch current account data
+ * - {@link getUser|`enplug.account.getUser()`} - fetch current user data
+ * - {@link getThemes|`enplug.account.getThemes()`} - fetches list of themes
+ * - {@link getTheme|`enplug.account.getTheme()`} - fetches theme
+ * - {@link editTheme|`enplug.account.editTheme()`} - edits the theme
+ * - {@link deleteTheme|`enplug.account.deleteTheme()`} - deletes the theme
+ */
 export declare class Account {
     private bridge;
+    /** @internal */
     constructor(bridge: BridgeBase);
@@ -9,4 +33,2 @@ /**
      * account type, token, account ID, venue ID, and environment.
-     *
-     * Data is passed as the first param to the success callback.
      */
@@ -18,6 +40,18 @@ getAccount(): Promise<EnplugAccount>;
     getUser(): Promise<EnplugUser>;
-    getDisplayGroups(): Promise<DisplayGroup[]>;
+    /**
+     * Loads information for the currently selected display group(s).
+     *
+     * @returns In the account context, it will return all Display Groups in the account;
+     * in the Display Group context, it will return only this group’s information.
+     */
+    getDisplayGroups(): Promise<any[]>;
     getSelectedDisplayId(): Promise<string>;
     /**
      * Loads an array of assets for the current app instance.
+     *
+     * The list is also limited to the {@link setDisplaySelectorCallback|Display Group selector} dropdown's choice.
+     *
+     * @param T - Model of asset's value
+     *
+     * @returns Array of assets added by current app filtered by the {@link setDisplaySelectorCallback|Display Group selection} if it is set.
      */
@@ -27,3 +61,7 @@ getAssets<T>(): Promise<Array<Asset<T>>>;
      * Loads an array of assets by Ids.
-     * @param {string[]} assetsIds An array of ids of the assets that are to be returned.
+     *
+     * @param T - Model of asset's value
+     * @param assetsIds - An array of ids of the assets that are to be returned.
+     *
+     * @returns Resolves to an array of requested assets.
      */
@@ -34,10 +72,15 @@ getAssetsByIds<T>(assetsIds: string[]): Promise<Array<Asset<T>>>;
      * Data is passed as the first param to the success callback.
-     * @param {string} appId An id of an app.
+     *
+     * @param T - Model of asset's value
+     * @param appId - An id of an app.
      */
     getAssetsForApp<T>(appId: string): Promise<Array<Asset<T>>>;
     /**
-     * Loads an content-approval asset revision.
-     * Data is passed as the first param to the success callback.
-     * @param {string} assetId An id of an asset.
-     * @param {string} version A version of an asset.
+     * Loads a content-approval asset revision.
+     *
+     * @param T - Model of asset's value
+     * @param assetId - ID of an asset
+     * @param version - Version of the asset
+     *
+     * @returns Resolves to the provided revision of the asset.
      */
@@ -47,5 +90,7 @@ getAssetRevision<T>(assetId: string, version: string): Promise<Asset<T>>;
      * Creates an asset under the current app instance.
-     * @param {Asset<T>[]} assets An array of asset object to create.
-     * @param {DeployDialogOptions?} dialogOptions An object with details about displaying a deploy dialog
+     * @param assets - An array of assets to create.
+     * @param dialogOptions - An object with details about displaying the deploy dialog
      * and its content after save.
+     *
+     * @returns Resolves to list of saved assets as they came from the server.
      */
@@ -55,32 +100,79 @@ bulkCreateAssets<T>(assets: Array<Asset<T>>, dialogOptions?: DeployDialogOptions): Promise<Array<Asset<T>>>;
      * Creates an asset under the current app instance.
-     * @param {Asset<T>[]} assets An array of assets to deploy.
-     * @param {DeployDialogOptions?} dialogOptions An object with details about displaying a deploy dialog
+     * @param assets - An array of assets to deploy.
+     * @param dialogOptions - An object with details about displaying the deploy dialog
      * and its content after save.
+     *
+     * @returns Resolves to list of saved assets as they came from the server.
      */
     bulkDeployAssets<T>(assets: Array<Asset<T>>, dialogOptions?: DeployDialogOptions): Promise<Array<Asset<T>>>;
     /**
-     * Saves an asset without showing the deployment dialog.
-     * @param {Asset<T>} asset An asset to save.
-     * @param {DeployDialogOptions?} dialogOptions An object with details about displaying a deploy dialog
-     * and its content after save.
+     * Creates or updates an asset. Can also be used to present the Deploy Dialog for changing asset's settings,
+     * such as assigning to Display Groups or changing the scheduling.
+     *
+     * When saving a new asset (`asset.Id` not defined) it will open the Deploy Dialog.
+     *
+     * ![Deploy Dialog](/img/dashboard-sdk/account/save-asset-deploy-dialog.png)<br />
+     * *Deploy Dialog*
+     *
+     * ```typescript title="Saving the asset"
+     * const dialogOptions: DeployDialogOptions = {
+     *   showSchedule: true,
+     *   scheduleOptions: {
+     *     showDuration: true
+     *   }
+     * };
+     *
+     * const savedAsset = await enplug.account.saveAsset(asset, dialogOptions);
+     * ```
+     *
+     * Saving an already existing asset will save it instantly without showing the Deploy Dialog.
+     *
+     * Another useful scenario is to allow the user to assign an existing asset to Display Groups or change the scheduling.
+     * To achieve this, you can force showing the Deploy Dialog for an already saved asset, by adjusting the `dialogOptions`.
+     * ```typescript title="Opening the Deploy Dialog to assign existing asset to Display Groups"
+     * const dialogOptions: DeployDialogOptions = {
+     *   showDeployDialog: true, // this forces the Deploy Dialog to appear for an already saved asset
+     *   showSchedule: true,
+     *   scheduleOptions: {
+     *     showDuration: true
+     *   }
+     * };
+     *
+     * const savedAsset = await enplug.account.saveAsset(asset, dialogOptions);
+     * ```
+     * *See more: {@link DeployDialogOptions}*
+     *
+     * @param T - Model of Asset's value
+     * @param asset - An asset to save.
+     * @param dialogOptions - Used to configure the Deploy Dialog, which can be shown to
+     * assign the asset to Display Groups or modify the scheduling options.
+     *
+     * @returns Promise resolving with the saved asset.
      */
     saveAsset<T>(asset: Asset<T>, dialogOptions?: DeployDialogOptions): Promise<Asset<T>>;
-    saveAssetForApp<T>(appId: string, asset: Asset<T>, dialogOptions?: DeployDialogOptions): Promise<any>;
+    saveAssetForApp<T>(appId: string, asset: Asset<T>, dialogOptions?: DeployDialogOptions): Promise<unknown>;
     /**
-     * This is for saving an order of assets if needed for the current app. An array of asset Ids
-     * is all that is needed, but the implementation also accepts an array of asset objects with "Id" string properties.
-     * @param {string[] | Asset<any>[]} assets An array of assetIds or assets in order which is to be saved.
+     * This is for saving an order of assets if needed for the current app. An array of asset IDs
+     * is all that is needed, but the implementation also accepts an array of asset objects with `Id` string properties.
+     *
+     * @param T - Model of asset's value
+     * @param assets - An array of assetIds or assets in order which is to be saved
+     *
+     * @returns Resolves if the order was successfully updated. Rejects otherwise.
      */
-    updateAssetOrder(assets: string[] | Array<Asset<any>>): Promise<void>;
+    updateAssetOrder<T>(assets: string[] | Array<Asset<T>>): Promise<void>;
     /**
-     * Deletes an asset for the current app instance.
-     * @param {string|string[]} id Id of an asset to delete.
+     * Deletes one or many assets under the current app instance.
+     *
+     * @param id - Id of an asset to delete. To delete multiple assets, an array of ids can be passed.
+     *
+     * @returns Resolves after successfully deleting the assets.
      */
     deleteAsset(id: string | string[]): Promise<void>;
     /**
-     * Marks asset as recently viewed
+     * Marks asset as recently viewed.
      */
     touchAsset(id: string): Promise<any>;
     /**
-     * Marks asset as recently viewed
+     * Marks asset as needing approval.
      */
@@ -90,30 +182,46 @@ getAssetNeedsApproval(id: string): Promise<any>;
      * Loads an array of default assets for the current instance's app definition.
-     * Data is passed as the first param to the success callback.
-     * @param {string} level 'Default', 'Network', 'Account'
-     * @param {string} levelId NetworkId or AccountId
+     *
+     * @param T - Model of asset's value
+     * @param level - 'Default', 'Network', 'Account'
+     * @param levelId - NetworkId or AccountId
+     *
+     * @returns Resolves to an array of default assets.
      */
     getDefaultAssets<T>(level?: DefaultAssetLevel, levelId?: string): Promise<Array<DefaultAsset<T>>>;
     /**
-     * Loads list of banner/ticker widget apps
+     * @internal
+     * Loads list of banner/ticker widget apps.
      */
     getZoningApps(): Promise<ZoningAppsResponse>;
     /**
-     * Loads widget assets used in a given zoning asset layout
+     * @internal
+     * Loads widget assets used in a given zoning asset layout.
      */
     getZoningLayoutAssets(assetId: string): Promise<Array<Asset<any>>>;
     /**
-     * Shows modal allowing to pick existing widget or create new
+     * @internal
+     * Shows modal allowing to pick existing widget or create new.
      */
     acquireZoningWidget(zoningAssetId: string, slotConfig: ZoningConfig, widgetAppId: string, usedAssetsIds: string[]): Promise<Asset<any>>;
     /**
-     * Fetches zoning data available after adding/editing a widget
+     * @internal
+     * Fetches zoning data available after adding/editing a widget.
      */
     editZoningWidget(zoningAssetId: string, slotConfig: ZoningConfig, widgetAppId: string, widgetAssetId: string): Promise<any>;
     /**
-     * Fetches zoning data available after adding/editing a widget
+     * @internal
+     * Fetches zoning data available after adding/editing a widget.
      */
     getZoningData(): Promise<any>;
     /**
-     * Loads available fonts for the current app or for specified appId.
-     * @param {string?} appId
+     * Loads the list of available fonts for the current app or for specified appId.
+     *
+     * ```typescript title="Loading the list of fonts"
+     * const { fonts } = await enplug.account.getFonts();
+     * console.log('List of available fonts', fonts);
+     * ```
+     *
+     * @param appId - ID of app for which the font list should be fetched. If not provided, the fonts for current app will be loaded.
+     *
+     * @returns Resolves to an object: `{ fonts: FontsApiItem[] }`. See: {@link FontsApiItem}.
      */
@@ -125,3 +233,2 @@ getFonts(appId?: string): Promise<{
      * Loads available themes for the current app or for specified appId.
-     * @param {string?} [appId]
      */
@@ -131,3 +238,3 @@ getThemes<T>(appId?: string): Promise<Array<ThemeAsset<T>>>;
      * Loads theme by id.
-     * @param {string} themeId An id of a theme
+     * @param themeId - An id of a theme
      */
@@ -138,10 +245,3 @@ getTheme<T>(id: string): Promise<ThemeAsset<T>>;
      * The new theme will be available only under the current user's account.
-     * @param {object} themeDefinition
-     * @param {object} theme
-     * @param {string} previewUrl
-     * @param {Array} previewAsset
-     * @param {object} layout
-     * @param {Array} fonts
-     * @param {object} feedData
-     * @returns {number} callId
+     * @returns callId
      */
@@ -152,3 +252,2 @@ editTheme<AssetValue, FeedType>(themeDefinition: ThemeDefinition, theme: ThemeAsset<any>, previewUrl: string, previewAsset?: Array<Asset<AssetValue>>, layout?: Layout | ZoningConfig, fonts?: FontDefinition[], feedData?: FeedData<FeedType>): Promise<ThemeAsset<AssetValue>>;
      * The new theme will be available to all users in the account.
-     * @param {object} theme
      */
@@ -159,13 +258,16 @@ saveTheme(theme: ThemeAsset<any>): Promise<any>;
      * the current app definition. Cannot remove default themes.
-     * @param {string} themeId
      */
     deleteTheme(themeId: string): Promise<any>;
     /**
-     * Returns flag status on account
+     * Returns flag status on account.
      */
     hasFeatureFlag(flagName: string): Promise<any>;
     /**
-     * Retrieve all custom display group properties on an account
+     * Retrieve all custom display group properties on an account.
      */
     getDisplayGroupCustomProperties(): Promise<AccountCustomPropertiesResponse[]>;
+    /**
+     * Returns account info such as network type and billing
+     */
+    loadAccount(accountId: string): Promise<any>;
 }

types/bridge/bridge-base.d.ts

@@ -7,8 +7,7 @@ import { InboundMessage, OutboundMessage } from '../internal-types';
     constructor(window: Window);
-    sendMessage(message: OutboundMessage, persistentCallback?: (...args: any[]) => void): Promise<any>;
-    abstract setWindowEventHandler(eventName: string, handler: (event: Event) => void): void;
+    sendMessage<T>(message: OutboundMessage, persistentCallback?: (...args: any[]) => void): Promise<T>;
     /**
      * Receives and parses a message from the dashboard.
-     * @param {MessageEvent} event An event coming from calling `postMessage` on the App's frame.
-     * @returns {boolean} Whether to allow the event to ne handled by another event handler.
+     * @param event - An event coming from calling `postMessage` on the App's frame.
+     * @returns Whether to allow the event to be handled by another event handler.
      */
@@ -18,6 +17,7 @@ protected receiveMessage(event: MessageEvent): boolean;
      * Decides what to do with an incoming message.
-     * @param {InboundMessage} response A dashboard's response to App's call.
-     * @returns {boolean} Whether to allow the event to ne handled by another event handler.
+     * @param response - A dashboard's response to App's call.
+     * @returns Whether to allow the event to ne handled by another event handler.
      */
     protected dispatchResponse(response: InboundMessage): boolean;
+    abstract setWindowEventHandler(eventName: string, handler: (event: Event) => void): void;
 }

types/dashboard.d.ts

 import { Asset, Button, DisplaySelectorCallback, FeedData, Layout, OpenConfirmOptions, ThemeAsset, EncodingStatusResult, UploaderOptions, UploadedFileResult, ApiDataConnectorOptions, DataConnectionConfig, AssetPreviewRequest, AssetPreviewData } from './external-types';
 import { BridgeBase } from './bridge/bridge-base';
+/**
+ * Dashboard API is a part of the Dashboard SDK. It can be used to present standardized User Interface elements.
+ * Use global `enplug.dashboard` object to access these methods.
+ *
+ * ```typescript title="Example usage of the Dashboard API"
+ * enplug.dashboard.pageLoading(false);
+ * ```
+ *
+ * **Useful commands**
+ *
+ * Header section:
+ * - {@link setHeaderTitle|`enplug.dashboard.setHeaderTitle()`} - sets header title
+ * - {@link setHeaderButtons|`enplug.dashboard.setHeaderButtons()`} - sets header buttons
+ * - {@link setDisplaySelectorCallback|`enplug.dashboard.setDisplaySelectorCallback()`} - sets Display Group selector callback
+ * - {@link setDisplaySelectorVisibility|`enplug.dashboard.setDisplaySelectorVisibility()`} - sets Display Group selector visibility
+ *
+ * Progress indicator:
+ * - {@link pageLoading|`enplug.dashboard.pageLoading()`} - sets the app's loader visibility
+ * - {@link loadingIndicator|`enplug.dashboard.loadingIndicator()`} - shows **Loading** indicator
+ * - {@link successIndicator|`enplug.dashboard.successIndicator()`} - shows **Success** indicator
+ * - {@link errorIndicator|`enplug.dashboard.errorIndicator()`} - shows **Error** indicator
+ *
+ * Dialogs:
+ * - {@link previewAsset|`enplug.dashboard.previewAsset()`} - shows asset preview
+ * - {@link upload|`enplug.dashboard.upload()`} - shows upload dialog
+ * - {@link openConfirm|`enplug.dashboard.openConfirm()`} - shows custom confirmation dialog
+ * - {@link confirmUnsavedChanges|`enplug.dashboard.confirmUnsavedChanges()`} - shows unsaved changes dialog
+ * - {@link setAppHasUnsavedChanges|`enplug.dashboard.setAppHasUnsavedChanges()`} - sets dashboard's navigation guard
+ */
 export declare class Dashboard {
@@ -8,3 +37,2 @@ private bridge;
      * Stored locally so that we can respond to click events
-     * @type {Button[]}
      */
@@ -14,10 +42,11 @@ private currentButtons;
      * Keeps track of whether the dashboard is loading mode so clients can check.
-     * @type {boolean}
      */
     private isLoadingCache;
+    /** @internal */
     constructor(bridge: BridgeBase);
     /**
-     * Notifies the parent dashboard of a click in the child iFrame. Used to close
-     * dropdown windows etc which were opened in parent window and are unable to
-     * respond to click events in child iFrame.
+     * @internal
+     * Notifies the parent dashboard of a click in the child iframe. Used to close
+     * dropdown windows, etc. which were opened in parent window and are unable to
+     * respond to click events in child iframe.
      *
@@ -29,4 +58,16 @@ * Event handler is automatically bound when the SDK is created.
      * Opens a confirm window asking the user to confirm their unsaved changes.
-     * If the user clicks the confirm button, the returned promise is resolved.
-     * Otherwise the error callback is called.
+     *
+     * ```typescript title="Presenting Unsaved Changes dialog"
+     * try {
+     *   await enplug.dashboard.confirmUnsavedChanges();
+     *   // user confirmed - take action
+     * } catch {
+     *   // user cancelled
+     * }
+     * ```
+     *
+     * ![Unsaved Changes dialog](/img/dashboard-sdk/dashboard/dialog-hasunsavedchanges.png)<br />
+     * *Unsaved Changes dialog*
+     *
+     * @returns Resolves if dialog was confirmed, rejects otherwise.
      */
@@ -36,4 +77,13 @@ confirmUnsavedChanges(): Promise<any>;
      * Shows the error indicator.
-     * Should only be used after a call has been made to .loadingIndicator().
-     * @param {string} message
+     *
+     * ```typescript title="Presenting the error indicator"
+     * enplug.dashboard.errorIndicator('Asset could not be removed');
+     * ```
+     *
+     * ![Error indicator](/img/dashboard-sdk/dashboard/progress-error.png)
+     * *Error indicator*
+     *
+     * @param message - A message to show in the error toast.
+     *
+     * @returns Resolves after the error indicator shows up on screen.
      */
@@ -45,2 +95,6 @@ errorIndicator(message: string): Promise<any>;
      * of successful SDK call from the dashboard.
+     *
+     * @see {@link pageLoading} to update the page loading state.
+     *
+     * @returns Current page loading state.
      */
@@ -50,24 +104,27 @@ isLoading(): boolean;
      * Turns on the progress indicator, typically used during asynchronous actions.
+     *
+     * :::note
      * Note that the progress indicator will continue until a call is made to the
-     * errorIndicator or successIndicator APIs.
+     * {@link errorIndicator} or {@link successIndicator} APIs.
+     * :::
+     *
+     * ```typescript title="Presenting the loading indicator"
+     * enplug.dashboard.loadingIndicator('Removing asset');
+     * ```
+     *
+     * ![Loading indicator](/img/dashboard-sdk/dashboard/progress-loading.png)
+     * *Loading indicator*
+     *
+     * @param message - A message to show in the loading toast.
+     *
+     * @returns Resolves after the loading indicator shows up on screen.
      */
-    loadingIndicator(message: string): Promise<any>;
+    loadingIndicator(message: string): Promise<void>;
     /**
-     * Navigates to url.
-     * @param {string} url Url to navigate to.
+     * Navigate to given relative dashboard URL.
      */
-    navigate(url: string): Promise<any>;
-    /**
-     * @deprecated use `navigateToZoning()`
-     * Navigate back from widget.
-     * @param {string} assetId Id of an asset to which to go back to.
-     */
-    navigateBack(assetId: string): Promise<any>;
-    /**
-     * Navigate to given relative dashboard url
-     */
     navigateToUrl(url: string): Promise<any>;
     /**
      * Navigate back to zoning from widget.
-     * assetId is optional, fallback parameter for v1->v2 transition phase
+     * @param assetId - optional, fallback parameter for v1-\>v2 transition phase
      */
@@ -77,5 +134,25 @@ navigateToZoning(assetId?: string): Promise<any>;
      * Opens a confirm window with Yes/No buttons and configurable messages.
-     * If the user clicks the Confirm button, the returned promise is resolved.
-     * Otherwise the promise is rejected.
-     * @param {OpenConfirmOpyions} options Confirm dialog options.
+     *
+     * ```typescript title="Presenting confirmation dialog"
+     * try {
+     *   await enplug.dashboard.openConfirm({
+     *     title: 'Delete asset?',
+     *     text: 'Are you sure you want to delete this asset? This action cannot be undone.',
+     *     cancelText: 'Cancel',
+     *     confirmText: 'Delete',
+     *     confirmClass: 'btn-danger'
+     *   });
+     *
+     *   // remove the asset
+     * } catch {
+     *   // user cancelled
+     * }
+     * ```
+     *
+     * ![Confirm dialog](/img/dashboard-sdk/dashboard/dialog-confirm.png)<br />
+     * *Confirm dialog*
+     *
+     * @param options - Confirm dialog options.
+     *
+     * @returns Resolves if Confirm button was clicked, rejects otherwise.
      */
@@ -85,62 +162,144 @@ openConfirm(options: OpenConfirmOptions): Promise<any>;
      * Puts the page into error state.
+     *
+     * ![Page error](/img/dashboard-sdk/dashboard/page-error.png)<br />
+     * *Page error*
+     *
+     * @returns Resolves after the Dashboard shows the page error.
      */
-    pageError(): Promise<any>;
+    pageError(): Promise<void>;
     /**
      * Controls the loading state for the entire page. Every application starts off in
-     * loading state, and must set pageLoading(false) to notify the dashboard that it
+     * loading state, and must set `pageLoading(false)` to notify the dashboard that it
      * has successfully loaded.
      *
-     * Use .isLoading() to synchronously check current loading state.
-     * @param {boolean} bool Page loading state
+     * ```typescript title="Turning off the loading spinner after app has started"
+     * enplug.dashboard.pageLoading(false);
+     * ```
+     *
+     * ![Page Loading spinner](/img/dashboard-sdk/dashboard/pageloading-spinner.png)<br />
+     * *Page Loading spinner*
+     *
+     * @param isLoading - Page loading state:<br />
+     * `false` - hides the loader and shows the app,<br />
+     * `true` - shows the loader and hides the app.
+     *
+     * @returns Resolves after the loading state has been updated by the Dashboard.
      */
-    pageLoading(bool: boolean): Promise<boolean>;
+    pageLoading(isLoading: boolean): Promise<boolean>;
     /**
-     * Puts the page into 404 state.
+     * Puts the page into not found (404) state.
+     *
+     * ![Page not available](/img/dashboard-sdk/dashboard/page-404.png)<br />
+     * *Page not available*
+     *
+     * @returns Resolves when after the Dashboard shows the page not found error.
      */
-    pageNotFound(): Promise<any>;
+    pageNotFound(): Promise<void>;
     /**
-     * @deprecated use `previewAsset()`
+     * @deprecated use {@link previewAsset}
+     *
      * Opens app preview modal.
-     * @param {string} url
-     * @param {Asset<AssetValue>} asset
-     * @param {object} theme
-     * @param {object} layout
-     * @param {object} feedData
      */
     preview<AssetValue, ThemeValue, FeedType>(url: string, asset: Asset<AssetValue>, theme: ThemeAsset<ThemeValue>, layout?: Layout, feedData?: FeedData<FeedType>): Promise<any>;
     /**
-     * Opens app asset preview modal.
+     * Opens asset preview modal.
+     *
+     * ![Asset preview modal](/img/dashboard-sdk/dashboard/previewAsset.png)<br />
+     * *Asset preview modal*
+     *
+     * ```typescript title="Previewing an asset"
+     * function showPreview(asset: Asset<AssetModel>) {
+     *   enplug.dashboard.previewAsset({ asset });
+     * }
+     * ```
+     *
+     * The above code opens the preview dialog with provided data.
+     * This method allows many preview customizations, see {@link AssetPreviewRequest}.
+     *
+     * :::note
+     * The app inside of the preview modal is presented in an iframe and the app is provided with basic SDK functionalities
+     * needed to display the asset only. The app's Player URL from app's definition will be used.
+     * The app is not run in a WebPlayer environment, so the behavior might be different.
+     * Most SDK calls will have no effect.
+     * :::
+     *
+     * @param TAssetValue - Model of asset's value
+     * @param TThemeValue - Model of theme's value (optional)
+     * @param TFeedType - Model of the feed (used for social apps)
+     *
+     * @returns Resolves after the preview modal gets closed.
      */
-    previewAsset<TAssetValue = any, TThemeValue = any, TFeedType = any>(request: AssetPreviewRequest<TAssetValue, TThemeValue, TFeedType>): Promise<any>;
+    previewAsset<TAssetValue = any, TThemeValue = any, TFeedType = any>(request: AssetPreviewRequest<TAssetValue, TThemeValue, TFeedType>): Promise<void>;
     /**
-     * Get preview params for an app asset for custom preview handling
-     * @param appId
-     * @param asset
-     * @param origin (default: true) - custom origin url, when omitted or falsy, `window.location.origin` will be attached
+     * @internal
+     * Get preview parameters for an app asset for custom preview handling.
+     * @param origin - (default: true) - custom origin url, when omitted or falsy, `window.location.origin` will be attached
      */
     getAssetPreviewData(appId: string, asset: Asset<any>, origin?: string | boolean): Promise<AssetPreviewData>;
     /**
-     * Sets the current callback for the title bar breadcrumb display selector dropdown.
-     * Attaching a callback enables the dropdown, it is disabled by default.
-     * The title is reset when the dashboard changes routes.
+     * Sets the current callback for the title bar breadcrumb Display Group selector dropdown.
+     * Attaching a callback enables the dropdown and resets the title.
      *
-     * the callback is fired when a display is selected, the callback will get the ID
-     * value when a single display is fired, or null when the 'All' selection is selected
-     * @param {DisplaySelectorCallback} callback A function to be called every time a user changes current display
-     * with display selector
+     * The callback is fired when a Display Group is selected from the dropdown, the callback will get the ID
+     * value when a single display is fired, or null when the whole 'Library' selection.
+     *
+     * ```typescript title="Setting up the Display Group selector"
+     * enplug.dashboard.setDisplaySelectorCallback(async () => {
+     *   // update your asset list using enplug.account.getAssets() which will return
+     *   // the assets assigned to the selected Display Group only
+     *   yourAssetList = await enplug.account.getAssets();
+     * });
+     * ```
+     *
+     * ![Display Group selector dropdown](/img/dashboard-sdk/dashboard/display-group-selector-dropdown.png)<br />
+     * *Display Group selector dropdown*
+     *
+     * @param callback - A function to be called every time a user changes current Display Group
+     * with the dropdown selector. The callback should reload the asset list to get the filtered version.
+     *
+     * @returns Promise which resolves after the command gets executed by the Dashboard.
      */
-    setDisplaySelectorCallback(callback: DisplaySelectorCallback): void;
+    setDisplaySelectorCallback(callback: DisplaySelectorCallback): Promise<void>;
     /**
-     * Hides or shows the display dropdown selector in the page title breadcrumb bar.
+     * Hides or shows the Display Group dropdown selector in the page title breadcrumb bar.
      * Send true to show the selector, false to hide it.
+     *
+     * The Display Group selector dropdown can be used to filter assets currently deployed to a specific Display Group.
+     * You can view all the saved assets by account for your app by selecting the 'Library' view from the dropdown on the upper left.
+     *
+     * ![Display Group selector dropdown](/img/dashboard-sdk/dashboard/display-group-selector-dropdown.png)
+     * *Display Group selector dropdown*
+     *
+     * @returns Promise which resolves after the command gets executed by the Dashboard.
      */
-    setDisplaySelectorVisibility(show: boolean): Promise<any>;
+    setDisplaySelectorVisibility(show: boolean): Promise<void>;
     /**
-     * Sets the primary action buttons for a page in the titlebar.
+     * Sets the action buttons for a page in the titlebar.
      *
      * Accepts either a single button object, or an array of buttons.
      * Each button must have a button.action callback.
-     * @param {Button[]|Button} buttons A button (single or array) to set on a header.
+     *
+     * ```typescript title="Updating the buttons"
+     * function updateButtons(hasUnsavedChanges: boolean) {
+     *   enplug.dashboard.setHeaderButtons([{
+     *     text: 'My Signs',
+     *     action: () => { \/* your code to navigate back to the Asset list *\/ },
+     *     class: 'btn-default'
+     *   }, {
+     *     text: 'Save',
+     *     action: () => { \/* your code saving the asset *\/ },
+     *     class: 'btn-primary',
+     *     disabled: !hasUnsavedChanges // this will disable the button if there are no unsaved changes
+     *   }]);
+     * }
+     * ```
+     *
+     * ![Header buttons](/img/dashboard-sdk/dashboard/header-buttons.png)<br />
+     * *Header buttons*
+     *
+     * @param buttons - A button (single or array) to set on a header.
+     *
+     * @returns Resolves after the buttons get updated.
      */
-    setHeaderButtons(buttons: Button[] | Button): void;
+    setHeaderButtons(buttons: Button[] | Button): Promise<void>;
     /**
@@ -152,31 +311,47 @@ * Sets the last part of the title bar breadcrumb.
      * The home/default page for an app should have no title set.
-     * @param {string} title A title to set.
+     *
+     * ```typescript title="Updating header's title"
+     * enplug.dashboard.setHeaderTitle('Setup');
+     * ```
+     *
+     * ![Header title](/img/dashboard-sdk/dashboard/header-title.png)
+     * *Header title section*
+     *
+     * @param title - A title to set.
+     *
+     * @returns Resolves after the title has been modified.
      */
-    setHeaderTitle(title: string): Promise<any>;
+    setHeaderTitle(title: string): Promise<void>;
     /**
      * Shows the success indicator.
-     * Should only be used after a call has been made to .loadingIndicator().
-     * @param {string} message A message to show in a success toast.
+     *
+     * ```typescript title="Presenting the success indicator"
+     * enplug.dashboard.successIndicator('Asset removed');
+     * ```
+     *
+     * ![Success indicator](/img/dashboard-sdk/dashboard/progress-success.png)
+     * *Success indicator*
+     *
+     * @param message - A message to show in the success toast.
+     *
+     * @returns Resolves after the success indicator shows up on screen.
      */
-    successIndicator(message: string): Promise<any>;
+    successIndicator(message: string): Promise<void>;
     /**
-     * Switches to account view aka "All" selection of instance selector or DisplayGroup view
+     * Switches to account view "Library"/All selection of instance selector or Display Group view.
      */
-    switchToView(displayGroupId: any, displayGroupName: any): Promise<any>;
+    switchToView(displayGroupId: string, displayGroupName: string): Promise<any>;
     /**
      * Uses upload interface and Enplug encoding service, returns uploaded object
-     * @param {UploaderOptions} options Filepicker options
+     * @param options - Filepicker options
      */
     upload(options: UploaderOptions): Promise<UploadedFileResult[]>;
     /**
-     * Uses connect data interface, returns connection configuration object
-     * @param {ApiDataConnectorOptions} options Api Data Connector configuration options
+     * Uses connect data interface, returns connection configuration object.
+     * @param options - API Data Connector configuration options.
      */
     connectData(options: ApiDataConnectorOptions): Promise<DataConnectionConfig>;
     /**
-     * Creates new assets and begins encoding process
-     */
-    processAssetResource<T>(accountId: string, appId: string, assets: Array<Asset<T>>): Promise<any>;
-    /**
-     * Returns current encoding status of an asset
+     * @internal
+     * Returns current encoding status of an asset.
      * @deprecated legacy FileStack upload flow
@@ -187,13 +362,14 @@ * @see resourcesEncodingStatus
     /**
-     * Returns current encoding statuses of resources or asset ids
-     * @param byAssetId if true, the provided ids are interpreted as asset ids, otherwise they are resource ids
+     * Returns current encoding statuses of resources or asset IDs.
+     * @param byAssetId - If `true`, the provided IDs are interpreted as asset IDs, otherwise they are resource IDs.
      */
     resourcesEncodingStatus(ids: string[], byAssetId?: boolean): Promise<EncodingStatusResult[]>;
     /**
-     * opens content interval settings dialog for ad-scheduler app
+     * Opens content interval settings dialog for Ad Scheduler app.
      */
     openContentIntervalSettingsDialog(appName: string, level: string, levelId: string): Promise<any>;
     /**
-     * Lets dashboard know that the state of user changes in the app changed
-     * @param {boolean} hasUnsavedChanges Whether the app has unsaved changes.
+     * Lets dashboard know that the state of user changes in the app changed.
+     *
+     * @param hasUnsavedChanges - Whether the app has unsaved changes.
      */
@@ -203,5 +379,4 @@ setAppHasUnsavedChanges(hasUnsavedChanges: boolean): Promise<any>;
      * The last callback registered with the dashboard title bar.
-     * @type {DisplaySelectorCallback}
      */
     private currentDisplayCallback;
 }

types/external-types.d.ts

@@ -32,4 +32,4 @@ /** These are meant to available to client apps */
     IsZoningWidget?: boolean;
-    /** Currently @ Value.Name - subject to change. Display name of the asset. used in lists. */
-    /** Currently @ Value.Zone - subject to change. Zoning widget asset slot type */
+    /** Currently \@ Value.Name - subject to change. Display name of the asset. used in lists. */
+    /** Currently \@ Value.Zone - subject to change. Zoning widget asset slot type */
     /** List of zoning assets on which the obj - a widget asset is placed */
@@ -72,2 +72,3 @@ ZoningAssetIds?: string[];
 export declare type DataItem = Date | DataImage | string;
+/** @internal */
 export declare class DataImage {
@@ -300,9 +301,2 @@ url: string;
 }
-export interface DisplayGroup {
-    /** e.g. English, Russian, French */
-    language: string;
-    /** Landscape or Portrait */
-    orientation: string;
-    timezone: string;
-}
 export interface DeployDialogOptions {
@@ -351,3 +345,3 @@ /** Whether to show the schedule tab in the dialog. */
     showTagsEditor?: boolean;
-    /** Graphics and Arts app only this one - list of assets to traverse with < > buttons */
+    /** Graphics and Arts app only this one - list of assets to traverse with &lt; &gt; buttons */
     assetsToNavigate?: Array<Asset<any>>;
@@ -423,3 +417,3 @@ /** Graphics and Arts app only use this one */
     bindingPairs: BindingPair[];
-    sampleData?: object;
+    sampleData?: any;
 }
@@ -444,3 +438,3 @@ export interface BindingPair {
 }
-interface ConnectionParams {
+export interface ConnectionParams {
     name: string;
@@ -486,10 +480,41 @@ value: string;
 }
+/**
+ * Type used to pass the asset, theme and other configuration details to the preview modal.
+ *
+ * For usage, see [`enplug.dashboard.previewAsset()`](/docs/sdk-dashboard/classes/Dashboard#previewasset).
+ *
+ * @param TAssetValue - Model of asset's value
+ * @param TThemeValue - Model of theme's value (optional)
+ * @param TFeedType - Model of the feed (used for social apps)
+ */
 export interface AssetPreviewRequest<TAssetValue, TThemeValue, TFeedType> {
+    /** Asset which is to be displayed in the preview modal */
     asset: Asset<TAssetValue>;
+    /**
+     * Theme applied to the asset.
+     *
+     * If your app uses themes, pass the theme here. It will be passed to the app,
+     * when it calls [`enplug.assets.getTheme()`](/docs/sdk-player/classes/Assets#gettheme).
+     */
     theme?: ThemeAsset<TThemeValue>;
+    /**
+     * Feed data - used for social apps.
+     */
     feedData?: FeedData<TFeedType>;
-    /** incompatible with `zoningConfig`. Pass `layout` for regular asset preview */
+    /**
+     * Customize the preview layout by, for example, providing the initial orientation of the preview.
+     */
     layout?: Layout;
-    /** incompatible with `layout`. Pass `zoningConfig` for zoning widget asset preview */
+    /**
+     * @internal
+     *
+     * Zoning preview options.
+     *
+     * This setting is incompatible with `layout`. Pass either `layout` for regular asset preview
+     * or `zoningConfig` for zoning widget asset preview
+     */
     zoningConfig?: ZoningConfig;
+    /**
+     * Limits the maximal pixel size of the preview.
+     */
     sizingConfig?: SizingConfig;
@@ -533,2 +558,1 @@ }
 }
-export {};

types/index.ts

 export * from './external-types';
 export * from './sdk';

types/internal-types.d.ts

@@ -111,4 +111,2 @@ /**
     LoadingIndicator = "dashboard.indicator.loading",
-    Navigate = "dashboard.navigate",
-    NavigateBack = "dashboard.navigateBack",
     NavigateToZoning = "dashboard.navigateToZoning",
@@ -132,3 +130,2 @@ NavigateToUrl = "dashboard.navigateToUrl",
     EditDataConnection = "dashboard.editDataConnection",
-    ProcessAssetResource = "dashboard.processAssetResource",
     EncodeStatus = "dashboard.encodeStatus",
@@ -162,3 +159,4 @@ ResourcesEncodingStatus = "dashboard.resourcesEncodingStatus",
     LoadBlacklist = "social.loadBlacklist",
-    UnbanUser = "social.unbanUser"
+    UnbanUser = "social.unbanUser",
+    LoadAccount = "app.loadAccount"
 }

types/sdk.d.ts

@@ -0,0 +0,0 @@ import { Account } from './account';

types/social.d.ts

 import { BridgeBase } from './bridge/bridge-base';
 import { PreapprovalDialogOptions, SocialItemsResponse, TwitterSubscriptionStatusResponse } from './external-types';
+/**
+ * Social API is a part of the Dashboard SDK used to access social media related data.
+ * Use global `enplug.social` object to access these methods.
+ */
 export declare class Social {
     private bridge;
+    /** @internal */
     constructor(bridge: BridgeBase);
@@ -13,3 +18,3 @@ clearQueryString(): Promise<any>;
      * Saves Teams Admin token to backend.
-     * @param tenantId A user id returned from MS Teams after authenticating.
+     * @param tenantId - A user id returned from MS Teams after authenticating.
      */
@@ -23,4 +28,4 @@ authenticateTeamsAdmin(tenantId: string): Promise<any>;
     /**
-     * Returns Channels available for a given user id
-     * @param tenantId An ID returned after authenticating the user with MS Teams
+     * Returns Channels available for a given user ID.
+     * @param tenantId - An ID returned after authenticating the user with MS Teams.
      */
@@ -27,0 +32,0 @@ getTeamsChannels(tenantId: string): Promise<any>;

types/utils.d.ts

@@ -0,0 +0,0 @@ export declare function validateArray(arg: any, message: string): void;

New alerts

No bug tracker

Maintenance

Package does not have a linked bug tracker in package.json.

Found 1 instance in 1 package

Fixed alerts

No README

Quality

Package does not have a README. This may indicate a failed publish or a low quality package.

Found 1 instance in 1 package

No bug tracker

Maintenance

Package does not have a linked bug tracker in package.json.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

243159

increased by15.91%

Number of package files

14

increased by7.69%

Lines of code

3306

increased by20.52%

Number of medium quality alerts

1

decreased by-50%

Number of lines in readme file

84

increased byInfinity%

Worsened metrics

Dev dependency count

35

increased by20.69%

No dependency changes