@cyclomedia/streetsmart-api 23.14.4 → 23.14.6

package/README.md

@@ -1,6 +1,7 @@
 # Street Smart API
 
-This Street Smart api package provides programmatic access to most of the UI components of the Street Smart Web application [here](https://streetsmart.cyclomedia.com).
+This Street Smart api package provides programmatic access to most of the UI components of the Street Smart Web
+application [here](https://streetsmart.cyclomedia.com).
 
 ---
 
@@ -12,85 +13,139 @@ First install the package using npm or yarn.
 npm i @cyclomedia/streetsmart-api
 ```
 
-Then import the package like
+Then import the package
 
 ```ts
-import StreetSmartApi from "@cyclomedia/streetsmart-api";
+import { StreetSmartApi } from "@cyclomedia/streetsmart-api";
 ````
 
-Please note that the package only exposes one default export and no named exports.
+The package exposes also named exports of Typescript types and constants.
 
-❌ This will not work
 ```ts
-import { init } from "@cyclomedia/streetsmart-api"
-```
-
-✅ Named imports of TypeScript types is okay
-```ts
-import { ApiOptions } from "@cyclomedia/streetsmart-api"
+import { ApiOptions, ViewerType, AuthOptions } from "@cyclomedia/streetsmart-api"
 ```
 
 ## API
-#### Init
 
-Please see the [official docs](https://streetsmart.cyclomedia.com/api/v23.14/documentation/#init) or the `ApiOptions` type for more information about the options.
+Note the item below will just list some examples of the most frequently used methods.
+> [!TIP]
+> For all the available methods on the `StreetSmartApi` object and the individual viewer objects, please refer to the docs.
+### Init
+
+Please see the [official docs](https://streetsmart.cyclomedia.com/api/v23.14/documentation/#init) or the `ApiOptions`
+type for more information about the options.
 
 ```ts
-import StreetSmartApi from "@cyclomedia/streetsmart-api";
-
-StreetSmartApi.init({
-    targetElement: HTMLElement,
-    srs: string,
-    locale: string,
-    apiKey: string,
-    loginOauth: boolean,
-    loginRedirectUri: string,
-    logoutRedirectUri: string,
-    clientId: string,
-    ...
+import { StreetSmartApi } from "@cyclomedia/streetsmart-api";
+
+await StreetSmartApi.init({
+    targetElement: document.getElementById('panorama-window'),
+    srs: "EPSG:28992",
+    locale: 'en-GB',
+    apiKey: 'some-secret-xxx',
+    addressSettings: {
+        locale: 'nl',
+        database: 'CMDatabase'
+    },
+    loginOauth: true,
+    clientId: 'CLIENT_ID-XX-YY-ZZ',
+    loginRedirectUri: 'localhost:3000/login',
+    logoutRedirectUri: 'localhost:3000/logoutt'
 })
 ```
 
-#### Open Panorama viewer
+### Open viewer
 
+After the call to `init` has successfully resolved, one or more viewers can be opened using the `open` function.
 Please check out the [official docs](https://streetsmart.cyclomedia.com/api/v23.14/documentation/#open).
 
 ```ts
-import StreetSmartApi, {OpenViewerQuery} from "@cyclomedia/streetsmart-api";
+import { StreetSmartApi, ViewerType } from "@cyclomedia/streetsmart-api";
 
-StreetSmartApi.open("1681 broadway, New York NY", {
-    viewerType: "PANORAMA" | "OBLIQUE" | "...",
-    srs: string,
+const viewerInstance = await StreetSmartApi.open("5D4KX5SM", {
+    viewerType: [ViewerType.PANORAMA, ViewerType.OBLIQUE],
+    srs: "EPSG:28992",
     panoramaViewer: {
-        closable: boolean,
-        maximizable: boolean,
-        timeTravelVisible: boolean,
-        recordingsVisible: boolean,
-        navbarVisible: boolean,
-        ...
+        closable: true,
+        maximizable: false,
+        timeTravelVisible: true,
+        recordingsVisible: true,
+        navbarVisible: true,
+        replace: true,
     },
-    ...
+    obliqueViewer: {
+        closable: true,
+        maximizable: false,
+    }
 })
 ```
 
-#### Destroy
+### Events
+
+You can listen for events both on the global `StreetSmartApi` object and on a specific viewer object, returned by
+the `open` function.
+
+Please check the documentation or the typescript declarations for all available events. 
+#### Example: global events
+
+```ts
+import { GlobalViewerEvents, MeasurementEvents, StreetSmartApi } from "@cyclomedia/streetsmart-api";
+
+StreetSmartApi
+    .on(MeasurementEvents.MEASUREMENT_SAVED, (evt) => {
+        const { activeMeasurement } = evt.detail
+        console.log(activeMeasurement.geometry)
+    })
+    .on(GlobalViewerEvents.VIEWER_ADDED, (evt) => {
+        const viewerId = evt.detail.viewer.getId()
+        console.log("Viewer added: ", viewerId)
+    })
+```
 
-For options and behavior please refer to the [official docs](https://streetsmart.cyclomedia.com/api/v23.14/documentation/#destroy)
+#### Example: viewer specific event
 
 ```ts
-StreetSmartApi.destroy({
-    targetElement: HTMLElement,
-    loginOauth: boolean
+import { PanoramaViewer, PanoramaViewerEvents, StreetSmartApi, ViewerType } from "@cyclomedia/streetsmart-api";
+
+try {
+    const viewers = await StreetSmartApi.open({
+        coordinate: [121692.34, 487812.37, 5.60],
+        dateRange: { from: '2022-01-01', to: '2024-01-01' }
+    }, {
+        viewerType: ViewerType.PANORAMA,
+        srs: 'EPSG:28992',
+    })
+
+    const panoramaViewer = viewers[0] as PanoramaViewer
+    panoramaViewer.on(PanoramaViewerEvents.RECORDING_CLICK, (evt) => {
+        const recording = evt.detail.recording
+        console.log("Clicked recording ", recording.id)
+    })
+} catch (e) {
+    // handle error e
+}
+
+```
+
+### Destroy
+
+For more information please refer to
+the [official docs](https://streetsmart.cyclomedia.com/api/v23.14/documentation/#destroy)
+
+```ts
+import {StreetSmartApi} from "@cyclomedia/streetsmart-api";
+
+await StreetSmartApi.destroy({
+    targetElement: document.getElementById('panorama-window'),
+    loginOauth: true,
 })
 ```
 
 ## FAQ
+
 - [What API functions are available?](#what-api-functions-are-available)
-- [The Point Cloud Viewer or 3DNL viewer don't load](#the-pointcloud-viewer-or-3dnl-viewer-don't-load)
 
 #### What API functions are available?
-Please see the [docs](https://streetsmart.cyclomedia.com/api/v23.14/documentation/) for all available functionality.
 
-#### The PointCloud Viewer or 3DNL viewer don't load
-Only the panorama and oblique viewer are working in this package.
-We are actively working on integrating the point cloud viewer and the mesh (3DNL) viewer.
+Please see the [docs](https://streetsmart.cyclomedia.com/api/v23.14/documentation/) for all available functions.
+