@sassoftware/vi-api 1.40.4 → 1.44.0

package/README.md

@@ -1,9 +1,40 @@
-# SAS Visual Investigator API
+# Visual Investigator API
 
-## Overview
-
-A package containing TypeScript type definitions to be used with the Visual Investigator Client API.
+The [SAS Visual Investigator](https://www.sas.com/en_us/software/intelligence-analytics-visual-investigator.html) API provides a set of components and service methods that enable developers to create customized solutions within the application.
 
 ## Getting Started
 
-For documentation and examples please see our [Solution Extension GitHub](https://github.com/sassoftware/vi-solution-extensions)
+For documentation and examples please see our [Solution Extension GitHub](https://github.com/sassoftware/vi-solution-extensions).
+
+### Installation
+To use the API, install the NPM package [@sassoftware/vi-api](https://www.npmjs.com/package/@sassoftware/vi-api):
+```bash
+npm install @sassoftware/vi-api
+```
+
+### API
+
+The SVI API is available through the JavaScript window object: 
+```javascript
+window.sas.vi.metadata.getEntity("person");
+```
+### Typings
+
+To complement the API, solution developers can download the API typings package.
+Run the following command in your project:
+```
+npm install @sassoftware/vi-api
+```
+The types can be used to help with autocompletion of API spaces, methods, and expected return types.
+```typescript
+import { SviWindow } from "@sassoftware/vi-api";
+import { StoredObjectDTO } from "@sassoftware/vi-api/svi-datahub";
+
+const sviWindow = window as SviWindow;
+sviWindow.sas.vi.metadata.getEntity("person").then((entity: StoredObjectDTO | undefined) => {
+    if (entity) {
+        console.log("Retrieved entity:", entity.label);
+    }
+});
+```
+

package/alert-reps/index.d.ts

@@ -1,6 +1,6 @@
 /* tslint:disable */
 /* eslint-disable */
-// Generated using typescript-generator version 2.15.527 on 2024-05-10 11:17:19.
+// Generated using typescript-generator version 2.15.527 on 2024-10-31 19:39:54.
 
 export interface ActionRequestRep {
     version?: number;
@@ -17,6 +17,15 @@ export interface ActionResponseRep {
     alertChanged?: boolean;
 }
 
+export interface AlertConstants {
+}
+
+export interface Length {
+}
+
+export interface LengthConstants {
+}
+
 export interface AlertDispositionRep extends BaseRep {
     alertDispositionDescription?: string;
     alertDispositionId?: string;
@@ -130,8 +139,8 @@ export interface AlertVersionSummaryRep {
     versionDispositionResolutionCode?: string;
     versionScore?: number;
     versionLastUpdateTimeStamp?: string;
-    versionCreationTimestamp?: string;
     versionLastUpdateTimestamp?: string;
+    versionCreationTimestamp?: string;
 }
 
 export interface AlertWorkflowRep {
@@ -228,6 +237,7 @@ export interface DispositionNotificationRep extends TypedPayload {
 
 export interface DispositionQueueRep extends BaseRep {
     displayCode?: string;
+    dispositionAutoApplied?: boolean;
     dispositionId?: string;
     dispositionName?: string;
     groupId?: string;
@@ -617,7 +627,7 @@ export interface MapType {
     entry?: MapEntryType[];
 }
 
-export interface Link extends Serializable {
+export interface Link extends Serializable, Comparable<Link> {
     method?: string;
     rel?: string;
     href?: string;
@@ -659,6 +669,9 @@ export interface ETagAndLastModifiedProvider extends ETaggable, LastModifiedProv
 export interface XmlAdapter<ValueType, BoundType> {
 }
 
+export interface Comparable<T> {
+}
+
 export interface Preconditionable {
 }
 

package/alert-reps/package.json

@@ -1,5 +1,5 @@
 {
   "name": "@types/alert-reps",
-  "version": "18.0.4",
+  "version": "19.5.5",
   "types": "index.d.ts"
 }

package/component/index.d.ts

@@ -16,7 +16,11 @@ export interface ComponentCreationResult<T> {
 }
 /**
  * Functionality related to dynamically creating SAS Visual Investigator user interface components.
- * Accessed from the window at window.sas.vi.component.
+ *
+ * Accessed from the window at `window.sas.vi.component`.
+ *
+ * @example window.sas.vi.component.create(SviComponent.Page, targetElement, bindings);
+ * @category API
  */
 export interface ComponentApi {
     create(component: SviComponent.ControlCollection, target: HTMLElement, bindings?: ControlCollectionBindings): Promise<ComponentCreationResult<ControlCollectionBindings>>;

package/component/package.json

@@ -4,6 +4,6 @@
         "**/*.d.ts",
         "**/*.js"
     ],
-    "main": "public-api.js",
-    "types": "public-api.d.ts"
+    "main": "index.js",
+    "types": "index.d.ts"
 }

package/config/config-api.d.ts

@@ -5,6 +5,15 @@ export declare enum ControlType {
     Angular = "angular",
     WebComponent = "webcomponent"
 }
+export declare enum ControlCategory {
+    Renderer = "Renderers",
+    Control = "Fields",
+    Toolbar = "ToolbarItems",
+    Home = "Home",
+    Chart = "Charts",
+    Panels = "Panels",
+    Container = "Container"
+}
 export interface Solution {
     label: string;
     version?: string;
@@ -20,6 +29,13 @@ export interface SolutionExtension extends ControlMetadata {
     clientApplication?: string;
     name: string;
 }
+export interface HomepageSolutionExtension extends SolutionExtension {
+    /** When set to true, the solution extension is reused when the homepage is reloaded instead. If unset, or set to
+     * false, then the control will be destroyed and recreated when the homepage is revisited.
+     */
+    reuse?: boolean;
+    category: ControlCategory.Home;
+}
 export interface SolutionExtensionConfigTypeAttributes {
     metadata?: SolutionExtensionMetadata;
     attributes?: Record<string, SolutionExtensionAttribute>;
@@ -109,7 +125,11 @@ export interface VersionSummary {
 }
 /**
  * Configuration-related functionality.
- * Accessed from the window at window.sas.vi.config.
+ *
+ * Accessed from the window at `window.sas.vi.config`.
+ *
+ * @example window.sas.vi.config.getSolutions();
+ * @category API
  */
 export interface ConfigApi {
     /**
@@ -145,14 +165,14 @@ export interface ConfigApi {
      * @param name {string} Name of the solution extension.
      * @returns A Promise that resolves to the solution extension if the name is found.
      */
-    getSolutionExtension(name: string): Promise<SolutionExtension | undefined>;
+    getSolutionExtension(name: string): Promise<SolutionExtension | HomepageSolutionExtension | undefined>;
     /**
      * @method
      * @description Registers a solution extension with the application.
      * @param config {SolutionExtension} Solution extension configuration.
      * @returns A Promise that resolves when the solution has been sent to the cache.
      */
-    registerSolutionExtension(config: SolutionExtension): Promise<void>;
+    registerSolutionExtension(config: SolutionExtension | HomepageSolutionExtension): Promise<void>;
     /**
      * @method
      * @description Registers a document manager with the application.

package/config/config-api.js

@@ -4,3 +4,13 @@ export var ControlType;
     ControlType["Angular"] = "angular";
     ControlType["WebComponent"] = "webcomponent";
 })(ControlType || (ControlType = {}));
+export var ControlCategory;
+(function (ControlCategory) {
+    ControlCategory["Renderer"] = "Renderers";
+    ControlCategory["Control"] = "Fields";
+    ControlCategory["Toolbar"] = "ToolbarItems";
+    ControlCategory["Home"] = "Home";
+    ControlCategory["Chart"] = "Charts";
+    ControlCategory["Panels"] = "Panels";
+    ControlCategory["Container"] = "Container";
+})(ControlCategory || (ControlCategory = {}));

package/config/package.json

@@ -4,6 +4,6 @@
         "**/*.d.ts",
         "**/*.js"
     ],
-    "main": "public-api.js",
-    "types": "public-api.d.ts"
+    "main": "index.js",
+    "types": "index.d.ts"
 }

package/control/control-api.d.ts

@@ -5,6 +5,7 @@ import { PageDataChange, PageModeChange, StateChange } from "./events";
 import { Control, RefreshablePageControlOptions, SlidingPanelContent, SlidingPanelProperties, TypeAttributes } from "./page";
 import { FieldTypeToRestrictions, FileRestrictions } from "./restrictions";
 import { AttachmentFormData } from "./file";
+import { MaskingControlApi, MaskingPageApi } from "./masking-api";
 /**
  * The minimum API that should be supported on control members across solutions.
  */
@@ -21,6 +22,7 @@ export interface ControlMemberApiBase<ControlTypeAttributes extends TypeAttribut
 /**
  * {@link ControlMemberApiBase} extension that provides more functionality.
  * @extends ControlMemberApiBase
+ * @category API
  */
 export interface ControlMemberApi<ControlTypeAttributes extends TypeAttributes = TypeAttributes, ControlFieldType extends FieldType = any> extends ControlMemberApiBase<ControlTypeAttributes, ControlFieldType> {
     /**
@@ -46,9 +48,14 @@ export interface ControlApiBase<ControlTypeAttributes extends TypeAttributes = T
     readonly state: ControlStateApi;
     /** Control type. */
     readonly type: string;
-    /** Control Mask */
+    /**
+     * Control Mask
+     * @deprecated use `api.control.masking.isConfiguredForMasking` instead.
+     **/
     isMaskedControl(): boolean;
-    /** Control Mask Authorization */
+    /** Control Mask Authorization
+     * @deprecated use `api.control.masking.isAuthorizedToUnmask`
+     **/
     isAuthorizedToUnmask(): boolean;
     /**
      * Sets the value of the control's field.
@@ -84,9 +91,15 @@ export interface ControlApiBase<ControlTypeAttributes extends TypeAttributes = T
      * @returns Object representing the calling control.
      */
     getControl(): Control<ControlTypeAttributes>;
+    /**
+     * Access the Control Data Masking API
+     */
+    masking: MaskingControlApi;
 }
 /**
  * This API pertains to administration functionality for controls, for example registering resources.
+ *
+ * @category API
  */
 export interface ControlAdminApi {
     /**
@@ -100,6 +113,7 @@ export interface ControlAdminApi {
 /**
  * Extension of {@link ControlApiBase} supplied by SAS Visual Investigator to provide more functionality.
  * @extends ControlApiBase
+ * @category API
  */
 export interface ControlApi<ControlTypeAttributes extends TypeAttributes = TypeAttributes, ControlFieldType extends FieldType = never> extends ControlApiBase<ControlTypeAttributes, ControlFieldType> {
     /**
@@ -138,6 +152,8 @@ export interface ControlApi<ControlTypeAttributes extends TypeAttributes = TypeA
 }
 /**
  * Methods and properties related to the state of the control.
+ *
+ * @category API
  */
 export interface ControlStateApi {
     /**
@@ -170,16 +186,17 @@ export interface ControlStateApi {
      * True if the control is hidden, otherwise false.
      */
     readonly hidden: boolean;
-    /**
-     * Returns the masked state of the calling control.
-     * True if the control is masked, otherwise false.
-     */
-    readonly maskActive: boolean;
     /**
      * Returns the disabled state of the calling control.
      * True if the control is disabled, otherwise false.
      */
     readonly disabled: boolean;
+    /**
+     * Returns the masked state of the calling control.
+     * True if the control is masked, otherwise false.
+     * @deprecated use `api.control.masking.isMasked`
+     */
+    readonly maskActive: boolean;
     /**
      * Registers a function to be invoked whenever a state change event occurs.
      * This function receives an object that contains information about the change event.
@@ -197,6 +214,8 @@ export interface ControlStateApi {
 }
 /**
  * API methods related to object fields associated with a page.
+ *
+ * @category API
  */
 export interface ControlPageFieldApi {
     /**
@@ -277,6 +296,7 @@ export interface ControlPageApiBase {
 /**
  * {@link ControlPageApiBase} extension that provides more functionality.
  * @extends ControlPageApiBase
+ * @category API
  */
 export interface ControlPageApi extends ControlPageApiBase {
     /**
@@ -309,7 +329,8 @@ export interface ControlPageApi extends ControlPageApiBase {
     isToolbarDisabled(): boolean;
     /**
      * Sets the toolbar control to be disabled.
-     * @param control {Control} The control to be disabled.
+     * @param {string} actionName the toolbar action name.
+     * @param {boolean} setDisabled disable the toolbar item.
      * @method
      */
     setToolbarItemDisabled(actionName: string, setDisabled: boolean): void;
@@ -413,6 +434,11 @@ export interface ControlPageApi extends ControlPageApiBase {
      * @returns A Promise which resolves when the page has been saved.
      */
     save(stopEditing: boolean, closeObject: boolean): Promise<void>;
+    /**
+     * Access the Page Data Masking API
+     */
+    masking: MaskingPageApi;
+    onNavigationStart(callback: () => void): void;
 }
 /**
  * Methods related to files.
@@ -429,6 +455,7 @@ export interface ControlFileApiBase {
 /**
  * {@link ControlFileApiBase} extension that provides more functionality.
  * @extends ControlFileApiBase
+ * @category API
  */
 export interface ControlFileApi extends ControlFileApiBase {
     /**
@@ -495,3 +522,8 @@ export interface ControlFileApi extends ControlFileApiBase {
  */
 export interface ControlPageEventsApi extends PageEventsApiBase {
 }
+export interface FieldNotOnPageError {
+    name: "FieldNotOnPageError";
+    message: string;
+    fields: string[];
+}

package/control/events.d.ts

@@ -72,5 +72,5 @@ export interface StateChange {
     allowInput?: boolean;
     couldBeReadOnly?: boolean;
     couldBeRequired?: boolean;
-    maskActive?: boolean;
+    masked?: boolean;
 }

package/control/masking-api.d.ts

@@ -0,0 +1,187 @@
+import { FieldValue } from "./data-types";
+export interface UnmaskEventData {
+    data: {
+        [fieldName: string]: FieldValue;
+    };
+    fieldNames: string[];
+    documentId: string;
+    documentType: string;
+    scopeId: string;
+    nodeId?: string;
+}
+export interface MaskEventData {
+    fieldNames: string[];
+    documentId: string;
+    documentType: string;
+    scopeId: string;
+    nodeId?: string;
+}
+export interface MaskResetEventData {
+    scopeId: string;
+    documentId: string;
+    fieldNames: string[];
+}
+export declare const MASKED_FIELD_CHAR = "\u2022";
+export declare const MASKED_FIELD_PLACEHOLDER: string;
+export declare const MASKED_FIELD_ISO_CODE_PLACEHOLDER: string;
+export interface MaskingPageApi {
+    /**
+     * Determines whether a field is masked.
+     * @throws {FieldNotOnPageError}
+     * @param fieldName The field name.
+     * @returns A boolean.
+     */
+    isMasked(fieldName: string): boolean;
+    /**
+     * Masks a field.
+     * @throws {NotConfiguredForMaskingError}
+     * @throws {FieldNotOnPageError}
+     * @param fieldName The field name.
+     */
+    mask(fieldName: string): void;
+    /**
+     * Masks the fields.
+     * If no fields array is passed in then all fields that are configured for masking on the page will be masked.
+     * @throws {NotConfiguredForMaskingError} If one or more of the fields are not configured for masking.
+     * @throws {FieldNotOnPageError} If one or more of the fields are not available on the page.
+     * @param fieldNames The field names.
+     */
+    maskAll(fieldNames?: string[]): void;
+    /**
+     * Unmasks the field via a fetch.
+     * Subsequent get field value calls return the unmasked value.
+     * If the field is unmasked or has been unmasked in the current page mode, no fetch is made.
+     * If the field is not on the page the promise will reject with a {@link FieldNotOnPageError}.
+     * If the field is not configured for masking the promise will reject with a {@link NotConfiguredForMaskingError}.
+     * If the user is not authorized to reveal the field, the returned promise will reject with an {@link UnmaskAuthError}.
+     * @param fieldName The field name.
+     * @returns A promise that resolves when the unmask is successful.
+     */
+    unmask(fieldName: string): Promise<void>;
+    /**
+     * Unmasks the fields via a fetch.
+     * Subsequent get field value calls return the unmasked value.
+     * If no fields array is passed in then all fields on the page configured for masking will be unmasked.
+     * For each field, if the field is unmasked or has been unmasked in the current page mode, no fetch for it is made.
+     * If one or more of the fields are not on the page the promise will reject with a {@link FieldNotOnPageError}.
+     * If one or more of the fields are not configured for masking the promise will reject with a {@link NotConfiguredForMaskingError}.
+     * If the user is not authorized to reveal one or more of the fields, the returned promise will reject with an {@link UnmaskAuthError}.
+     * @param fieldNames The field names.
+     * @returns A promise that resolves when the unmasks are successful.
+     */
+    unmaskAll(fieldNames?: string[]): Promise<void>;
+    /**
+     * Invokes the callback whenever any field value is masked.
+     * When an individual field is masked via a mask call, the callback will be invoked once.
+     * When multiple fields are masked via a single mask/mask all call, the callback will be invoked once.
+     * @param callback The callback function.
+     * @returns A function that removes the callback.
+     */
+    onEveryMask(callback: (mask: {
+        fieldNames: string[];
+    }) => void): () => void;
+    /**
+     * Invokes the callback whenever the specified field is masked.
+     * @throws {FieldNotOnPageError}
+     * @param fieldName The field name.
+     * @param callback The callback function.
+     * @returns A function that removes the callback.
+     */
+    onMask(fieldName: string, callback: () => void): () => void;
+    /**
+     * Invokes the callback whenever any field value is unmasked.
+     * When an individual field is unmasked via an unmask call, the callback will be invoked once.
+     * When multiple fields are unmasked via a single unmask/unmask all call, the callback will be invoked once.
+     * @param callback The callback function.
+     * @returns A function that removes the callback.
+     */
+    onEveryUnmask(callback: (unmask: {
+        fieldNames: string[];
+    }) => void): () => void;
+    /**
+     * Invokes the callback whenever the specified field is unmasked.
+     * @throws {FieldNotOnPageError}
+     * @param fieldName The field name.
+     * @param callback The callback function.
+     * @returns A function that removes the callback.
+     */
+    onUnmask(fieldName: string, callback: () => void): () => void;
+    /**
+     * Determines whether the field is configured for masking via the field's restrictions.
+     * @throws {FieldNotOnPageError}
+     * @param fieldName The field name.
+     * @returns Whether the field is configured for masking.
+     */
+    isConfiguredForMasking(fieldName: string): boolean;
+    /**
+     * Determines whether the current user can unmask the field.
+     * @throws {FieldNotOnPageError}
+     * @throws {NotConfiguredForMaskingError}
+     * @param fieldName The field name.
+     * @returns Whether the current can unmask the field.
+     */
+    isAuthorizedToUnmask(fieldName: string): boolean;
+}
+export interface MaskingControlApi {
+    /**
+     * In the case of a single field control, determines whether the control's field is masked.
+     * In the case of a multiple field control, determines whether one or more of the control's fields are masked.
+     * @returns A boolean.
+     */
+    isMasked(): boolean;
+    /**
+     * Masks the control's field(s) that are configured for masking.
+     * @throws {NotConfiguredForMaskingError} If a single field control's field is not configured for masking or if
+     * all of a multiple field control's fields are not configured for masking.
+     */
+    mask(): void;
+    /**
+     * Unmasks the controls field(s) via a fetch.
+     * Subsequent get field value calls return the unmasked value.
+     * For each field, if the field is unmasked or has been unmasked in the current page mode, no fetch for it is made.
+     * If a single field control's field is not configured for masking or if all of a multiple field control's fields are not configured for masking the returned
+     * promise will reject with a {@link NotConfiguredForMaskingError}.
+     * If the user is not authorized to reveal one or more of the control's fields, the returned promise will reject with an {@link UnmaskAuthError}.
+     * @returns A promise that resolves when the unmask is successful.
+     */
+    unmask(): Promise<void>;
+    /**
+     * Invokes the callback whenever the control's field is (or, in the case of a multiple field control, fields are) masked.
+     * @param callback The callback function.
+     * @returns A function that removes the callback.
+     */
+    onMask(callback: (mask: {
+        fieldNames: string[];
+    }) => void): () => void;
+    /**
+     * Invokes the callback whenever the control's field is (or, in the case of a multiple field control, fields are) unmasked.
+     * @param callback The callback function.
+     * @returns A function that removes the callback.
+     */
+    onUnmask(callback: (unmask: {
+        fieldNames: string[];
+    }) => void): () => void;
+    /**
+     * In the case of a single field control, determines (via the field restrictions) whether the control's field is configured for masking.
+     * In the case of a multiple field control, determines (via the field restrictions) whether one or more of the control's fields are configured for masking.
+     * @returns Whether the control is configured for masking.
+     */
+    isConfiguredForMasking(): boolean;
+    /**
+     * In the case of a single field control, determines whether the current user is able to unmask the control's field.
+     * In the case of a multiple field control, determines whether the current user is able to unmask all of the control's fields.
+     * @throws {NotConfiguredForMaskingError}
+     * @returns Whether the current user is able to unmask the control.
+     */
+    isAuthorizedToUnmask(): boolean;
+}
+export interface UnmaskAuthError {
+    name: "UnmaskAuthError";
+    message: string;
+    fields: string[];
+}
+export interface NotConfiguredForMaskingError {
+    name: "NotConfiguredForMaskingError";
+    message: string;
+    fields: string[];
+}

package/control/masking-api.js

@@ -0,0 +1,3 @@
+export const MASKED_FIELD_CHAR = "\u2022";
+export const MASKED_FIELD_PLACEHOLDER = MASKED_FIELD_CHAR.repeat(9);
+export const MASKED_FIELD_ISO_CODE_PLACEHOLDER = MASKED_FIELD_CHAR.repeat(3);

package/control/package.json

@@ -4,6 +4,6 @@
         "**/*.d.ts",
         "**/*.js"
     ],
-    "main": "public-api.js",
-    "types": "public-api.d.ts"
+    "main": "index.js",
+    "types": "index.d.ts"
 }

package/control/restrictions.d.ts

@@ -1,5 +1,11 @@
 import { FieldType, NumberDataType } from "./data-types";
-export interface RequirableRestriction {
+export interface MaskedFieldRestriction {
+    masked?: {
+        currentUserIsAuthorizedToReveal: boolean;
+        revealUrl?: string;
+    };
+}
+export interface RequirableRestriction extends MaskedFieldRestriction {
     required: boolean;
 }
 export interface FieldRestrictions extends RequirableRestriction {

package/current-user/currentUser-api.d.ts

@@ -28,7 +28,11 @@ export interface SessionDetails {
 }
 /**
  * This API is used to get the details and functionality associated with the current user.
- * Accessed from the window at window.sas.vi.currentUser.
+ *
+ * Accessed from the window at `window.sas.vi.currentUser`.
+ *
+ * @example window.sas.vi.currentUser.getSessionDetails();
+ * @category API
  */
 export interface CurrentUserApi {
     /**
@@ -46,9 +50,10 @@ export interface CurrentUserApi {
     /**
      * @method
      * @description Gets the list of groups to which the current user belongs.
+     * @param limit Maximum number of groups to be returned. Default: 1000.
      * @returns A list of group details.
      */
-    getUserMemberships(): Promise<IdentitySummary[]>;
+    getUserMemberships(limit?: number): Promise<IdentitySummary[]>;
     /**
      * @method
      * @description Verifies if the current user has administration features.

package/current-user/package.json

@@ -4,6 +4,6 @@
         "**/*.d.ts",
         "**/*.js"
     ],
-    "main": "public-api.js",
-    "types": "public-api.d.ts"
+    "main": "index.js",
+    "types": "index.d.ts"
 }

package/elements/bindings.d.ts

@@ -0,0 +1,25 @@
+import { PageModel } from "../page-model";
+import { Control } from "../control";
+/**
+ * @category Properties
+ */
+export interface SASInputBindings<T = any> {
+    id?: string;
+    readOnly?: boolean;
+    placeholder?: string;
+    autocomplete?: string;
+    isDisabled?: boolean;
+    model?: T;
+    inputFocus?: (event: FocusEvent) => void;
+    inputBlur?: (event: FocusEvent) => void;
+    modelChanged?: (modelValue: T) => void;
+}
+/**
+ * Page Controls require a valid {@link Control | childNode} and {@link PageModel | pageModel}.</strong>
+ *
+ * @category Properties
+ **/
+export interface PageControlBindings {
+    childNode: Control;
+    pageModel: PageModel;
+}