@3e/sqa-common 6.0.6-1 → 6.0.6-12

package/index.d.ts

@@ -672,21 +672,48 @@ declare module '@3e/sqa-common' {
     body: Section[]
   }
 
+  export type Parameters = {
+    class: string
+    id: string
+  }
+
+  export type ViewData = SQView & {
+    artifact: {
+      type: string
+      version: string
+    }
+    body: {
+      body: Parameters[]
+      class: string
+      id: string
+    }[]
+    version: string
+  }
+
+  export type ParameterOption = {
+    options: {value: string; label: string}[]
+    id: string
+    label: string
+    ldType: string
+    container?: string
+    value: string
+  }
+
   export interface ApiConfig extends RequestInit {
     token?: string
     body?: any
   }
 
   export type ApiFn = (
-    endpoint: string,
-    config?: ApiConfig,
+      endpoint: string,
+      config?: ApiConfig,
   ) => Promise<
-    {status: ErrorStatus} | {body: Record<string, any>; status: OKStatus}
-  >
+      {status: ErrorStatus} | {body: Record<string, any>; status: OKStatus}
+      >
 
   export type TokenThunk = () => Promise<
-    {status: OKStatus; body: {token: string}} | {status: ErrorStatus}
-  >
+      {status: OKStatus; body: {token: string}} | {status: ErrorStatus}
+      >
 
   export interface InitialisationConfig {
     apiFn: ApiFn
@@ -695,75 +722,75 @@ declare module '@3e/sqa-common' {
   export type PeriodTimeMode = 'absolute' | 'local'
 
   export type ViewType =
-    | 'time-chart'
-    | 'object-chart'
-    | 'object-heatmap'
-    | 'scatter-chart'
-    | 'object-table'
-    | 'time-table'
-    | 'kpis'
+      | 'time-chart'
+      | 'object-chart'
+      | 'object-heatmap'
+      | 'scatter-chart'
+      | 'object-table'
+      | 'time-table'
+      | 'kpis'
 
   export type Granularity =
-    | '1 minute'
-    | '5 minutes'
-    | '10 minutes'
-    | '15 minutes'
-    | '30 minutes'
-    | '1 hour'
-    | '1 day'
-    | '1 week'
-    | '1 month'
-    | '3 months'
-    | '1 year'
+      | '1 minute'
+      | '5 minutes'
+      | '10 minutes'
+      | '15 minutes'
+      | '30 minutes'
+      | '1 hour'
+      | '1 day'
+      | '1 week'
+      | '1 month'
+      | '3 months'
+      | '1 year'
 
   export type Period =
-    | 'last-7-days'
-    | 'last-week'
-    | 'since-beginning'
-    | 'last-12-months'
-    | 'year-to-date'
-    | 'today'
-    | 'current-month'
-    | 'last-month'
-    | 'forecast-4-days'
-    | 'tomorrow'
-    | 'last-24-hours'
-    | 'last-30-days'
-    | 'last-7x24-hours'
-    | 'last-3x24-hours'
-    | 'last-15-minutes'
-    | 'last-3-days'
-    | 'last-year'
-    | 'yesterday'
-    | 'forecast-10-days'
-    | 'custom'
+      | 'last-7-days'
+      | 'last-week'
+      | 'since-beginning'
+      | 'last-12-months'
+      | 'year-to-date'
+      | 'today'
+      | 'current-month'
+      | 'last-month'
+      | 'forecast-4-days'
+      | 'tomorrow'
+      | 'last-24-hours'
+      | 'last-30-days'
+      | 'last-7x24-hours'
+      | 'last-3x24-hours'
+      | 'last-15-minutes'
+      | 'last-3-days'
+      | 'last-year'
+      | 'yesterday'
+      | 'forecast-10-days'
+      | 'custom'
 
   export type LevelValue =
-    | 'site-group'
-    | 'site'
-    | 'ac-node'
-    | 'ac-input'
-    | 'ac-phase'
-    | 'connection'
-    | 'dc-input'
-    | 'dc-node'
-    | 'inverter'
-    | 'inverter-device'
-    | 'logger'
-    | 'mppt'
-    | 'module-group'
-    | 'power-unit'
-    | 'sensor'
-    | 'strings'
-    | 'tracker'
+      | 'site-group'
+      | 'site'
+      | 'ac-node'
+      | 'ac-input'
+      | 'ac-phase'
+      | 'connection'
+      | 'dc-input'
+      | 'dc-node'
+      | 'inverter'
+      | 'inverter-device'
+      | 'logger'
+      | 'mppt'
+      | 'module-group'
+      | 'power-unit'
+      | 'sensor'
+      | 'strings'
+      | 'tracker'
 
   export type RepresentationValue =
-    | 'line'
-    | 'line-and-marker'
-    | 'marker'
-    | 'spline'
-    | 'column'
-    | 'area'
+      | 'line'
+      | 'line-and-marker'
+      | 'marker'
+      | 'spline'
+      | 'column'
+      | 'area'
 
   export type StackingOptionValue = 'no' | 'normal' | 'percent'
 
@@ -777,6 +804,7 @@ declare module '@3e/sqa-common' {
   export type Level = {
     value: LevelValue
     label: string
+    models?: {label: string; value: string}[]
   }
 
   /**
@@ -787,6 +815,8 @@ declare module '@3e/sqa-common' {
     label: string
   }
 
+  export type ContainerValue = string
+
   /**
    * Containers (Actually physical plants)
    */
@@ -825,6 +855,15 @@ declare module '@3e/sqa-common' {
 
   export type ColorSchemeValue = 'scheme_blrd' | 'scheme_ylrdbl'
 
+  export type ColorSettings =
+      | {
+    label: string
+    value: string
+    type: 'palette'
+    colors: string[]
+  }
+      | {label: string; value: string; type: 'fixed'; color: string}
+
   export type ColorScheme = {
     value: ColorSchemeValue
     label: string
@@ -882,13 +921,63 @@ declare module '@3e/sqa-common' {
     }
   }
 
+  export interface LdType {
+    sqid: string
+    ref: string
+    label: string
+  }
+
+  export interface LDRoot {
+    sqid: string
+    ref: string
+    label: string
+  }
+
+  export interface Model {
+    sqid: string
+    ref: string
+    label: string
+  }
+
+  export interface LogicalDevice {
+    sqid: string
+    ld_type: string
+    ref: string
+    root: LDRoot
+    label: string
+    full_name: string
+    act_to: Date
+    act_from: Date
+    model: Model
+  }
+
+  export interface Indicator {
+    default_graphical_representation: string
+    description: string
+    key: string
+    label: string
+    level: LevelValue
+    unit: string
+    unit_key: string
+  }
+
+  export interface LDIndicator {
+    indicator_key: string
+    object_ref: string
+    unit: string
+    unit_key: string
+  }
+
   /**
    * Options for representing the dataset
    */
   export interface DatasetOptions {
-    graphicalRepresentation: string
-    id: string
-    colorSetting: string
+    graphicalRepresentation?: string
+    id?: string
+    colorSetting?: string
+    stacking?: StackingOptionValue
+    showNullsAs?: string
+    label?: string
   }
 
   export interface DatasetTemplateSpec {
@@ -897,7 +986,99 @@ declare module '@3e/sqa-common' {
     selectedTemplate: string
   }
 
-  export type Dataset = any //TODO: Better types here
+  export interface Object {
+    name: string
+    level: LevelValue
+    ref: string
+    type: string
+    statistics?: {
+      median: number
+      mean: number
+      sum: number
+      min: number
+      max: number
+    }
+  }
+
+  export interface ObjectSet {
+    template: string
+    level: string
+    objects: Object[]
+  }
+
+  export interface UnitScale {
+    min?: any
+    max?: any
+  }
+
+  export type Scaling = Record<string, UnitScale>
+
+  export interface Dataset {
+    objects?: any
+    colorSetting?: ColorSettings
+    indicators: Indicator[]
+    objectSet: ObjectSet
+    stacking: StackingOptionValue
+    showNullsAs?: any
+    representation: string
+    label?: any
+    id: string
+    scaling: Scaling
+    stack?: any
+    error?: any
+    idx: number
+    objectSetLabel: string
+  }
+
+  // TODO: Better types for PacoViewParameters
+  type PacoViewParameters = any
+
+  type SaveDataJobStatus =
+      | {
+    status: 'terminated'
+    respResult: {downloadUrl: string}
+    completedTime: ISODateString
+    respStatus: number
+  }
+      | {status: 'running'}
+
+  type SaveDataJobResponse = SaveDataJobStatus & {
+    actorSqid: string
+    numRetries: number
+    sqid: string
+    maxRetries: number
+
+    /**
+     * The arguments derived from the visualization given as argument
+     * for the `createSaveDataJob` function
+     */
+    arguments: {
+      object: string[]
+      toDate: ISODateString
+      filename: string
+      replyTz: string
+      fromDate: string
+      indicator: string[]
+      granularity: Granularity[] // must be a single value
+    }
+    /**
+     * The place in the queue
+     */
+    priority: number
+
+    timeout: number
+
+    /**
+     * currently can be just save_data
+     */
+    typeSqid: number
+  }
+
+  type Parameter = {
+    id: string
+    class: 'Parameter'
+    parameter: {class: string; label: string; initial: unknown; value: unknown}
+  }
 
   /**
    * Type definitions for all the API
@@ -917,8 +1098,8 @@ declare module '@3e/sqa-common' {
      * @param getToken - function with no arguments that returns the JWT token
      */
     wrapRefresh(
-      apiFn: ApiFn,
-      getToken: TokenThunk,
+        apiFn: ApiFn,
+        getToken: TokenThunk,
     ): {apiFn: ApiFn; resetFn: () => void}
 
     /**
@@ -932,6 +1113,12 @@ declare module '@3e/sqa-common' {
      */
     newEmptyView(viewOptions: EmptyViewOptions): SQView
 
+    /**
+     * Returns the type for the given view
+     * @param view SQView
+     */
+    getViewType(view: SQView): ViewType
+
     /**
      * Get title of the view
      * @param view - the SQView
@@ -977,19 +1164,28 @@ declare module '@3e/sqa-common' {
      * @param options - creation options
      */
     getVisualization(
-      view: SQView,
-      options: VisualisationOptions,
+        view: SQView,
+        options: VisualisationOptions,
     ): Promise<Visualization>
 
     /**
      * Populates a visualization with data, using the default `append-data` to append each page.
      * @param visualisation - the visualization to be populated
-     * @param callback - A callback that will be called when the operation is complete
+     * @param callback - Callback function called with the populated viz when the operation is done
+     *
+     * @returns a function to cancel the operation
      */
     populateVisualisation(
-      visualisation: Visualization,
-      callback: (data: any) => void,
-    ): Promise<void>
+        visualisation: Visualization,
+        callback: (visualization: Visualization) => void,
+    ): () => void
+
+    /**
+     * @param visualisation - the visualization to be populated
+     *
+     * @returns A promise with the populated visualization
+     */
+    populateVisualisation(visualisation: Visualization): Promise<Visualization>
 
     /**
      * Returns the granularity for the view
@@ -999,9 +1195,10 @@ declare module '@3e/sqa-common' {
 
     /**
      * Returns the granularity for the view
-     * @param view
+     * @param view - the view to modify
+     * @param granularity - the new granularity
      */
-    setGranularityParameter(view: SQView): Granularity
+    setGranularityParameter(view: SQView, granularity: Granularity): SQView
 
     /**
      * Returns the object parameters for a view
@@ -1010,10 +1207,10 @@ declare module '@3e/sqa-common' {
     getObjectParameters(view: SQView): {
       id: string
       label: string
-      ldType: LDType
-      container: Container
+      ldType: string
+      container: string
       value: string
-    }
+    }[]
 
     /**
      * Sets the object parameter with the given id
@@ -1021,19 +1218,21 @@ declare module '@3e/sqa-common' {
      * @param id - The ID of the parameter //TODO: Get list of possible parameters
      * @param value - Value of the parameter
      */
-    setObjectParameters(view: SQView, id: string, value: string): SQView
+    setObjectParameter(view: SQView, id: string, value: string): SQView
 
     DataTimezoneModes: [
       {value: 'user'; label: 'Display data in my own timezone'},
       {value: 'plant'; label: 'Display data in the timezone of the plant'},
     ]
 
-    ShowNullAsOptions: [
+    ShowNullsAsOptions: [
       {value: 'no'; label: 'No'},
       {value: 'normal'; label: 'Normal'},
       {value: 'percent'; label: 'Percent'},
     ]
 
+    ViewTypes: {label: string; value: ViewType}[]
+
     /**
      * A collection of all timezones in the format {label, value}
      */
@@ -1056,12 +1255,33 @@ declare module '@3e/sqa-common' {
      */
     getColorSchemes(): ColorScheme[]
 
+    /**
+     * Returns the possible color settings for a certain view type
+     * @param viewType
+     */
+    getColorSettings(viewType: ViewType): ColorSettings[]
+
+    getColorSettingsCssStyle(colorSetting: ColorSettings):
+        | {
+      backgroundColor: string
+    }
+        | {
+      backgroundImage: string
+    }
+
+    /**
+     * Sets the colorscheme of a view
+     * @param view the view to be modified
+     * @param colorScheme - the new colorscheme
+     */
+    setViewColorScheme(view: SQView, colorScheme: string): SQView
+
     /**
      * Array with available levels
      *
      * !! Only usable after `init` has been called
      */
-    getLevels: Level[]
+    getLevels(): Level[]
 
     StackingOptions: StackingOption[]
 
@@ -1072,7 +1292,7 @@ declare module '@3e/sqa-common' {
      * Gets the container logical devices types to populate
      * @param level - level means container
      */
-    getContainerLdTypes(level: LevelValue): LDType[]
+    getContainersLdTypes(level: LevelValue): Promise<LDType[]>
 
     /**
      * Based on the selected level and the Selected Logical Device type, returns
@@ -1081,16 +1301,22 @@ declare module '@3e/sqa-common' {
      * @param selectedContainerLdType
      */
     getContainers(
-      selectedLevel: LevelValue,
-      selectedContainerLdType: LDType,
-    ): Container[]
+        selectedLevel: LevelValue,
+        selectedContainerLdType?: string,
+    ): Promise<Container[]>
 
     /**
      * Get all available templates for the current selection
-     * @param selectedLevel
-     * @param selectedContainer
+     * @param view
+     * @param specification
      */
-    getTemplates(selectedLevel: Level, selectedContainer: Container): Template[]
+    getTemplates(
+        view: SQView,
+        specification: {
+          selectedLevel: LevelValue
+          selectedContainer: ContainerValue
+        },
+    ): Promise<Template[]>
 
     /**
      * Sets the unit scaling for a view.
@@ -1100,9 +1326,9 @@ declare module '@3e/sqa-common' {
      * @param unitScaling
      */
     setUnitScaling(
-      view: SQView,
-      unitKey: string,
-      unitScaling: {min?: number; max?: number},
+        view: SQView,
+        unitKey: string,
+        unitScaling: {min?: number; max?: number},
     ): SQView
 
     /**
@@ -1111,8 +1337,8 @@ declare module '@3e/sqa-common' {
      * @param unitKey - the
      */
     getUnitScaling(
-      view: SQView,
-      unitKey: string,
+        view: SQView,
+        unitKey: string,
     ): {
       min: number
       max: number
@@ -1175,7 +1401,7 @@ declare module '@3e/sqa-common' {
       periodTimeMode: PeriodTimeMode
     }
 
-    getDatasets(view: SQView): Dataset[]
+    getDatasets(view: SQView): Promise<Dataset[]>
 
     /**
      * Adds a dataset to the view using a fixed set of objects.
@@ -1186,18 +1412,98 @@ declare module '@3e/sqa-common' {
      * @param options
      */
     addEnumDataset(
-      view: SQView,
-      objects: LDType,
-      indicators: [string],
-      options: DatasetOptions,
+        view: SQView,
+        objects: string[],
+        indicators: [string],
+        options: DatasetOptions,
     ): SQView
 
     addTemplateDataset(
-      view: SQView,
-      spec: DatasetTemplateSpec,
-      indicators: [string],
-      opts: DatasetOptions,
+        view: SQView,
+        spec: DatasetTemplateSpec,
+        indicators: [string],
+        opts: DatasetOptions,
     ): SQView
+
+    /**
+     * Remove a dataset from the view
+     * @param view the view to be modified
+     * @param id the id of the dataset
+     */
+    removeDataset(view: SQView, id: string): SQView
+
+    /**
+     * Set particular options on a dataset for a view
+     * @param view - the view to be updated
+     * @param id  - the id of the dataset in the view body
+     * @param options - the new options
+     *
+     * @returns The updated view
+     */
+    setDatasetOptions(view: SQView, id: string, options: DatasetOptions): SQView
+
+    /**
+     * Returns the type of picker needed for the granularity
+     * @param granularity
+     */
+    getClockOrCalendarMode(granularity: Granularity): 'clock' | 'calendar'
+
+    /**
+     * Returns the type of picker needed for the granularity
+     * @param granularity
+     */
+    getTimeMode(granularity: Granularity): 'clock' | 'calendar'
+
+    /**
+     * Adds the statistics alongside the objects in the dataset
+     * @param datasets - datasets to be updated
+     * @param visualization - Visualization to be added to datasets
+     */
+    withStatistics(datasets: Dataset[], visualization: Visualization): Dataset[]
+
+    levelToLdTypeAndModel(level: LevelValue): {ldType: string; model: string}
+
+    viewVariablesRefCategories(viewParameters: PacoViewParameters): any
+
+    /**
+     * Update a visualization
+     * @param visualization
+     */
+    updateVisualization(visualization: Visualization): Visualization
+
+    /**
+     * Create a SAVE_DATA job request for a visualization. After a job is
+     * successfully created, a *JobUrl* is returned to be polled for a status
+     * on the job
+     *
+     * @param visualization - The visualization to be saved in a .csv format
+     * @param filename - the name of the csv.zip file to be downloaded
+     *
+     * @throws An error in case the provided parameters were incorrect. Wrap the
+     * request inside a `try-catch` block
+     */
+    createSaveDataJob(
+        visualization: Visualization,
+        filename: string,
+    ): Promise<string>
+
+    /**
+     * Used for polling the SQA API for the job status.
+     *
+     * Use the jobUrl returned from `createSaveDataJob` and poll until `status` is `terminated`
+     * @param jobUrl
+     *
+     * @throws An error in case something goes wrong with the request or the job does not
+     * exist. Wrap the call inside a `try-catch` block
+     */
+    checkJobStatus(jobUrl: string): Promise<SaveDataJobResponse>
+
+    /**
+     * Returns the parameters of a view
+     * @param view
+     */
+    getViewParameters(view: SQView): Parameter[]
+
   }
 
   export const sqa: {
@@ -1206,4 +1512,3 @@ declare module '@3e/sqa-common' {
 
   export default sqa
 }
-