@epilot/sdk 2.1.0-rc.0 → 2.1.0

package/docs/dashboard.md

@@ -0,0 +1,640 @@
+# Dashboard API
+
+- **Base URL:** `https://dashboard.sls.epilot.io`
+- **Full API Docs:** [https://docs.epilot.io/api/dashboard](https://docs.epilot.io/api/dashboard)
+
+## Usage
+
+```ts
+import { epilot } from '@epilot/sdk'
+
+epilot.authorize(() => '<token>')
+const { data } = await epilot.dashboard.listDashboards(...)
+```
+
+### Tree-shakeable import
+
+```ts
+import { getClient, authorize } from '@epilot/sdk/dashboard'
+
+const dashboardClient = getClient()
+authorize(dashboardClient, () => '<token>')
+const { data } = await dashboardClient.listDashboards(...)
+```
+
+## Operations
+
+**Dashboards**
+- [`listDashboards`](#listdashboards)
+- [`createDashboard`](#createdashboard)
+- [`getDashboard`](#getdashboard)
+- [`putDashboard`](#putdashboard)
+- [`deleteDashboard`](#deletedashboard)
+
+**Visualisations**
+- [`listAvailableVisualisations`](#listavailablevisualisations)
+
+**Examples**
+- [`listAvailableExamples`](#listavailableexamples)
+
+**Schemas**
+- [`DashboardID`](#dashboardid)
+- [`Dashboard`](#dashboard)
+- [`DashboardTileID`](#dashboardtileid)
+- [`DashboardTile`](#dashboardtile)
+- [`VisualisationConfig`](#visualisationconfig)
+- [`timechartVisualisationConfig`](#timechartvisualisationconfig)
+- [`ExampleID`](#exampleid)
+- [`Example`](#example)
+- [`DatalakeQuery`](#datalakequery)
+- [`VisualisationId`](#visualisationid)
+- [`Visualisation`](#visualisation)
+
+### `listDashboards`
+
+List dashboards available to the user
+
+`GET /v1/dashboard/dashboards`
+
+```ts
+const { data } = await client.listDashboards()
+```
+
+<details>
+<summary>Response</summary>
+
+```json
+{
+  "results": [
+    {
+      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
+      "title": "Employee Dashboard",
+      "tiles": [
+        {
+          "id": "e4af1297-1fd6-440f-9846-f475f580d40f",
+          "coordinates": {},
+          "visualisation": "timechart",
+          "visualisation_config": {
+            "query": {
+              "dataset": "entity_operations",
+              "measure": "count_operations",
+              "filters": [
+                {
+                  "operation": ["createEntity"]
+                },
+                {
+                  "entity_schema": ["opportunity"]
+                }
+              ],
+              "dimensions": [
+                {
+                  "time_with_granularity": "month"
+                },
+                {
+                  "entity_attribute": "source.title"
+                }
+              ]
+            },
+            "options": {
+              "type": "line"
+            }
+          }
+        }
+      ]
+    }
+  ]
+}
+```
+
+</details>
+
+---
+
+### `createDashboard`
+
+Create new dashboard
+
+`POST /v1/dashboard/dashboards`
+
+```ts
+const { data } = await client.createDashboard(
+  null,
+  {
+    id: '3fa85f64-5717-4562-b3fc-2c963f66afa6',
+    title: 'Employee Dashboard',
+    tiles: [
+      {
+        id: 'e4af1297-1fd6-440f-9846-f475f580d40f',
+        coordinates: {},
+        visualisation: 'timechart',
+        visualisation_config: {
+          query: {
+            dataset: 'entity_operations',
+            measure: 'count_operations',
+            filters: [
+              {
+                operation: ['createEntity']
+              },
+              {
+                entity_schema: ['opportunity']
+              }
+            ],
+            dimensions: [
+              {
+                time_with_granularity: 'month'
+              },
+              {
+                entity_attribute: 'source.title'
+              }
+            ]
+          },
+          options: {
+            type: 'line'
+          }
+        }
+      }
+    ]
+  },
+)
+```
+
+<details>
+<summary>Response</summary>
+
+```json
+{
+  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
+  "title": "Employee Dashboard",
+  "tiles": [
+    {
+      "id": "e4af1297-1fd6-440f-9846-f475f580d40f",
+      "coordinates": {},
+      "visualisation": "timechart",
+      "visualisation_config": {
+        "query": {
+          "dataset": "entity_operations",
+          "measure": "count_operations",
+          "filters": [
+            {
+              "operation": ["createEntity"]
+            },
+            {
+              "entity_schema": ["opportunity"]
+            }
+          ],
+          "dimensions": [
+            {
+              "time_with_granularity": "month"
+            },
+            {
+              "entity_attribute": "source.title"
+            }
+          ]
+        },
+        "options": {
+          "type": "line"
+        }
+      }
+    }
+  ]
+}
+```
+
+</details>
+
+---
+
+### `getDashboard`
+
+Get dashboard by ID
+
+`GET /v1/dashboard/dashboards/{id}`
+
+```ts
+const { data } = await client.getDashboard({
+  id: '123e4567-e89b-12d3-a456-426614174000',
+})
+```
+
+<details>
+<summary>Response</summary>
+
+```json
+{
+  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
+  "title": "Employee Dashboard",
+  "tiles": [
+    {
+      "id": "e4af1297-1fd6-440f-9846-f475f580d40f",
+      "coordinates": {},
+      "visualisation": "timechart",
+      "visualisation_config": {
+        "query": {
+          "dataset": "entity_operations",
+          "measure": "count_operations",
+          "filters": [
+            {
+              "operation": ["createEntity"]
+            },
+            {
+              "entity_schema": ["opportunity"]
+            }
+          ],
+          "dimensions": [
+            {
+              "time_with_granularity": "month"
+            },
+            {
+              "entity_attribute": "source.title"
+            }
+          ]
+        },
+        "options": {
+          "type": "line"
+        }
+      }
+    }
+  ]
+}
+```
+
+</details>
+
+---
+
+### `putDashboard`
+
+Update a dashboard by ID
+
+`PUT /v1/dashboard/dashboards/{id}`
+
+```ts
+const { data } = await client.putDashboard(
+  {
+    id: '123e4567-e89b-12d3-a456-426614174000',
+  },
+  {
+    id: '3fa85f64-5717-4562-b3fc-2c963f66afa6',
+    title: 'Employee Dashboard',
+    tiles: [
+      {
+        id: 'e4af1297-1fd6-440f-9846-f475f580d40f',
+        coordinates: {},
+        visualisation: 'timechart',
+        visualisation_config: {
+          query: {
+            dataset: 'entity_operations',
+            measure: 'count_operations',
+            filters: [
+              {
+                operation: ['createEntity']
+              },
+              {
+                entity_schema: ['opportunity']
+              }
+            ],
+            dimensions: [
+              {
+                time_with_granularity: 'month'
+              },
+              {
+                entity_attribute: 'source.title'
+              }
+            ]
+          },
+          options: {
+            type: 'line'
+          }
+        }
+      }
+    ]
+  },
+)
+```
+
+<details>
+<summary>Response</summary>
+
+```json
+{
+  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
+  "title": "Employee Dashboard",
+  "tiles": [
+    {
+      "id": "e4af1297-1fd6-440f-9846-f475f580d40f",
+      "coordinates": {},
+      "visualisation": "timechart",
+      "visualisation_config": {
+        "query": {
+          "dataset": "entity_operations",
+          "measure": "count_operations",
+          "filters": [
+            {
+              "operation": ["createEntity"]
+            },
+            {
+              "entity_schema": ["opportunity"]
+            }
+          ],
+          "dimensions": [
+            {
+              "time_with_granularity": "month"
+            },
+            {
+              "entity_attribute": "source.title"
+            }
+          ]
+        },
+        "options": {
+          "type": "line"
+        }
+      }
+    }
+  ]
+}
+```
+
+</details>
+
+---
+
+### `deleteDashboard`
+
+Delete a dashboard by ID
+
+`DELETE /v1/dashboard/dashboards/{id}`
+
+```ts
+const { data } = await client.deleteDashboard({
+  id: '123e4567-e89b-12d3-a456-426614174000',
+})
+```
+
+<details>
+<summary>Response</summary>
+
+```json
+{
+  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
+  "title": "Employee Dashboard",
+  "tiles": [
+    {
+      "id": "e4af1297-1fd6-440f-9846-f475f580d40f",
+      "coordinates": {},
+      "visualisation": "timechart",
+      "visualisation_config": {
+        "query": {
+          "dataset": "entity_operations",
+          "measure": "count_operations",
+          "filters": [
+            {
+              "operation": ["createEntity"]
+            },
+            {
+              "entity_schema": ["opportunity"]
+            }
+          ],
+          "dimensions": [
+            {
+              "time_with_granularity": "month"
+            },
+            {
+              "entity_attribute": "source.title"
+            }
+          ]
+        },
+        "options": {
+          "type": "line"
+        }
+      }
+    }
+  ]
+}
+```
+
+</details>
+
+---
+
+### `listAvailableVisualisations`
+
+Returns list of available Visualisations to configure new dashboard tiles
+
+`GET /v1/dashboard/visualisations`
+
+```ts
+const { data } = await client.listAvailableVisualisations()
+```
+
+<details>
+<summary>Response</summary>
+
+```json
+{
+  "results": [
+    {
+      "visualisation": "timechart",
+      "title": "Time Series Visualisation",
+      "description": "Visualise your metrics with respect to time series",
+      "package_name": "@epilot360/highcharts"
+    },
+    {
+      "visualisation": "kpi",
+      "title": "KPI Visualisation",
+      "description": "Visualise your key performance indicators",
+      "package_name": "@epilot360/kpi"
+    }
+  ]
+}
+```
+
+</details>
+
+---
+
+### `listAvailableExamples`
+
+Returns list of available exampless for visualisations to configure new dashboard tiles
+
+`GET /v1/dashboard/examples`
+
+```ts
+const { data } = await client.listAvailableExamples()
+```
+
+<details>
+<summary>Response</summary>
+
+```json
+{
+  "results": [
+    {
+      "id": "e4af1297-1fd6-440f-9846-f475f580d40f",
+      "title": "Number of opportunities created by journeys every month",
+      "visualisation": "timechart",
+      "query": {
+        "dataset": "entity_operations",
+        "measure": "count_operations",
+        "dimensions": [
+          {
+            "time_with_granularity": "year-month"
+          }
+        ],
+        "filters": [
+          {
+            "entity_schema": "opportunity"
+          }
+        ]
+      }
+    }
+  ]
+}
+```
+
+</details>
+
+---
+
+## Schemas
+
+### `DashboardID`
+
+Unique identifier for dashboard
+
+```ts
+type DashboardID = string // uuid
+```
+
+### `Dashboard`
+
+Adashboard configuration with tiles
+
+```ts
+type Dashboard = {
+  id?: string // uuid
+  title: string
+  tiles: Array<{
+    id?: string // uuid
+    coordinates?: object
+    title?: string
+    visualisation_id?: "kpi" | "funnel" | "toplist" | "timechart" | "pie" | "bar" | "entity_list" | "markdown" | "news_feed" | "workflow"
+    visualisation_config?: {
+      query?: { ... }
+      options?: { ... }
+    }
+  }>
+}
+```
+
+### `DashboardTileID`
+
+Unique identifier for a tile in a dashboard
+
+```ts
+type DashboardTileID = string // uuid
+```
+
+### `DashboardTile`
+
+```ts
+type DashboardTile = {
+  id?: string // uuid
+  coordinates?: object
+  title?: string
+  visualisation_id?: "kpi" | "funnel" | "toplist" | "timechart" | "pie" | "bar" | "entity_list" | "markdown" | "news_feed" | "workflow"
+  visualisation_config?: {
+    query?: {
+      dataset?: { ... }
+      measure?: { ... }
+      dimensions?: { ... }
+      filters?: { ... }
+    }
+    options?: Record<string, unknown>
+  }
+}
+```
+
+### `VisualisationConfig`
+
+```ts
+type VisualisationConfig = {
+  query?: {
+    dataset?: string
+    measure?: string
+    dimensions?: Record<string, unknown>[]
+    filters?: Record<string, unknown>[]
+  }
+  options?: Record<string, unknown>
+}
+```
+
+### `timechartVisualisationConfig`
+
+```ts
+type timechartVisualisationConfig = {
+  query?: {
+    dataset?: string
+    measure?: string
+    dimensions?: Record<string, unknown>[]
+    filters?: Record<string, unknown>[]
+  }
+  options?: Record<string, unknown>
+}
+```
+
+### `ExampleID`
+
+Unique identifier for a visualisation examples for tiles in a dashboard
+
+```ts
+type ExampleID = string // uuid
+```
+
+### `Example`
+
+```ts
+type Example = {
+  id?: string // uuid
+  title?: string
+  visualisation?: "kpi" | "funnel" | "toplist" | "timechart" | "pie" | "bar" | "entity_list" | "markdown" | "news_feed" | "workflow"
+  query?: {
+    dataset?: string
+    measure?: string
+    dimensions?: Record<string, unknown>[]
+    filters?: Record<string, unknown>[]
+  }
+}
+```
+
+### `DatalakeQuery`
+
+```ts
+type DatalakeQuery = {
+  dataset?: string
+  measure?: string
+  dimensions?: Record<string, unknown>[]
+  filters?: Record<string, unknown>[]
+}
+```
+
+### `VisualisationId`
+
+Unique identifier for a Visualisation
+
+```ts
+type VisualisationId = "kpi" | "funnel" | "toplist" | "timechart" | "pie" | "bar" | "entity_list" | "markdown" | "news_feed" | "workflow"
+```
+
+### `Visualisation`
+
+A Visualisation that can be used to configure tiles in dashboards
+
+```ts
+type Visualisation = {
+  visualisation?: "kpi" | "funnel" | "toplist" | "timechart" | "pie" | "bar" | "entity_list" | "markdown" | "news_feed" | "workflow"
+  title?: string
+  description?: string
+  package_name?: string
+  import_url?: string // uri
+}
+```