@c8y/tutorial 1019.0.3

package/src/__mocks/README.md

@@ -0,0 +1,73 @@
+# Creating and Registering Interceptors
+## Introduction
+
+Interceptors are a feature used in HTTP communication to intercept and possibly alter HTTP requests or responses. They are powerful tools in managing communication with backend services and can be used to manipulate requests or simulate server responses.
+
+## Why Use Interceptors
+
+In our context, we aim to mock backend requests, particularly for unauthenticated users. This allows developers to simulate a variety of server responses without needing to communicate with the actual backend service, facilitating development and testing.
+
+## Precaution
+
+All files and logic within the __mocks folder are intended solely to enable Codex operation for unauthenticated users. This code should not be copied and should not be used as the basis for your own implementations.
+
+## Adding an Interceptor
+
+In this section, you will learn how to add your own interceptor in the tutorial application. The first decision you have to make is whether you want to create a global interceptor, which will act on all paths, or a scoped interceptor, which will act only on a selected path. They differ by the path parameter: global interceptors do not have a path specified.
+
+Here's an example of how to register interceptors in the module's providers section:
+
+```typescript
+{
+  provide: API_MOCK_CONFIG,
+  useValue: {
+    path: 'path-on-which-this-interceptor-is-tiggered',
+    // The interceptors are sorted by their ID, so the scoped interceptors should be before the global ones.
+    id: 'your-scoped-interceptor-name',
+    mockService: ScopedInterceptor
+  } as ApiMockConfig,
+  multi: true
+},
+{
+  provide: API_MOCK_CONFIG,
+  useValue: {
+    // The interceptors are sorted by their ID, so the scoped interceptors should be before the global ones.
+    id: 'z-your-global-interceptor-name',
+    mockService: GlobalInterceptor
+  } as ApiMockConfig,
+  multi: true
+},
+
+```
+
+## Implementing the Interceptor
+
+After deciding the type of interceptor, you should add it to the corresponding folder: scoped-mocks for scoped interceptors and global-mocks for global ones.
+
+Here's a template for an interceptor that intercepts all requests sent to "inventory/managedObjects":
+
+```typescript
+export class BoilerplateInterceptor implements HttpInterceptor {
+  intercept(req: ApiCall, next: HttpHandler): Observable<IFetchResponse> {
+    return handleRequest(req, next, 'inventory/managedObjects', {
+      POST: this.mockPOST.bind(this),
+      PUT: this.mockPUT.bind(this),
+      GET: this.mockGET.bind(this)
+    });
+  }
+
+  mockPOST(_requestDescriptor: string) {
+    return null;
+  }
+
+  mockPUT(_requestDescriptor: string) {
+    return null;
+  }
+
+  mockGET(_requestDescriptor: string) {
+    return null;
+  }
+}
+```
+
+This interceptor will capture all POST, PUT and GET requests to "inventory/managedObjects". In this template, all mock functions simply return null — you should replace them with your own logic.

package/src/__mocks/global-mocks/inventory.interceptor.ts

@@ -0,0 +1,145 @@
+import { IFetchResponse } from '@c8y/client';
+import { ApiCall, HttpHandler, HttpInterceptor } from '@c8y/ngx-components/api';
+import { Observable } from 'rxjs';
+import { generateResponse, handleRequest } from '../utils/common';
+import {
+  generateUserPreferences,
+  generateRealtimeDeviceMO,
+  generateRandomMo,
+  generateDevice,
+  generateSubGroup,
+  generateAsset,
+  generateGroup,
+  generateAssetType
+} from '../../__mocks/utils/generators/managedObjects';
+
+export class InventoryInterceptor implements HttpInterceptor {
+  intercept(req: ApiCall, next: HttpHandler): Observable<IFetchResponse> {
+    return handleRequest(req, next, 'inventory/managedObjects', {
+      POST: this.mockPOST.bind(this),
+      PUT: this.mockPUT.bind(this),
+      GET: this.mockGET.bind(this)
+    });
+  }
+
+  private mockPOST(_requestDescriptor: string) {
+    if (_requestDescriptor.includes('c8y_UserPreference')) {
+      return generateResponse(() => generateUserPreferences());
+    }
+    return null;
+  }
+
+  private mockPUT(_requestDescriptor: string) {
+    return null;
+  }
+
+  private async mockGET(_requestDescriptor: string) {
+    /**
+     * Workaround. Leaflet is lazy loaded. Adding mocked assets too fast leads to not loaded markers.
+     */
+    await new Promise(r => setTimeout(r, 300));
+
+    const responseGenerators = this.getResponseGenerators(_requestDescriptor);
+    for (const urlPart in responseGenerators) {
+      if (_requestDescriptor.includes(urlPart)) {
+        const generatorResult = responseGenerators[urlPart]();
+        if (generatorResult) {
+          return generateResponse(() => generatorResult);
+        }
+      }
+    }
+
+    /**
+     * Intercept request to /inventory/managedObjects/<moId>
+     */
+    if (/\/\d+/.test(_requestDescriptor)) {
+      return generateResponse(() => generateDevice());
+    }
+    return null;
+  }
+
+  private getResponseGenerators(_requestDescriptor: string) {
+    return {
+      c8y_DeviceGroup: () => ({
+        managedObjects: [...[...Array(10)].map(() => generateSubGroup())]
+      }),
+      c8y_DeviceSubgroup: () => ({
+        managedObjects: [generateSubGroup()]
+      }),
+      'has(c8y_IsDeviceGroup)': () => ({
+        managedObjects: [...[...Array(5)].map(() => generateGroup())]
+      }),
+      'has(c8y_Position)': () => ({
+        managedObjects: [generateRealtimeDeviceMO()]
+      }),
+      'has(c8y_IsDevice)': () => ({
+        managedObjects: [...[...Array(5)].map(() => generateDevice())]
+      }),
+      childAssets: () => ({
+        references: [
+          ...[...Array(3)].map(() => ({
+            managedObject: generateRandomMo()
+          }))
+        ]
+      }),
+      childDevices: () => ({
+        references: []
+      }),
+      childAdditions: () => ({
+        references: []
+      }),
+      c8y_Dashboard: () => ({
+        managedObjects: []
+      }),
+      c8y_IsAssetType: () => ({
+        managedObjects: [generateAssetType()]
+      }),
+      c8y_IsDeviceGroup: () => ({
+        managedObjects: [
+          ...[...Array(5)].map(() => (Math.random() < 0.5 ? generateSubGroup() : generateAsset()))
+        ]
+      }),
+      c8y_IsDevice: () =>
+        _requestDescriptor.includes('"onlyRoots":true') &&
+        !_requestDescriptor.includes('c8y_IsDeviceGroup')
+          ? {
+              managedObjects: [...[...Array(2)].map(() => generateDevice())]
+            }
+          : null,
+      supportedMeasurements: () => ({
+        c8y_SupportedMeasurements: ['c8y_Battery']
+      }),
+      supportedSeries: () => ({
+        c8y_SupportedSeries: ['c8y_Battery.Battery']
+      }),
+      c8y_Kpi: () => ({
+        managedObjects: []
+      }),
+      kpis: () => ({
+        managedObjects: []
+      }),
+      c8y_Battery: () => ({
+        id: '100000',
+        type: 'c8y_Battery',
+        source: {
+          id: '200000'
+        },
+        c8y_Battery: {
+          Battery: {
+            unit: '%',
+            value: 67
+          }
+        }
+      }),
+      c8y_Service: () => ({
+        managedObjects: [generateDevice()]
+      }),
+      gainsightBotEnabled: () => ({
+        managedObjects: []
+      }),
+      language: () => ({
+        managedObjects: [generateUserPreferences()]
+      })
+    };
+  }
+}

package/src/__mocks/global-mocks/measurements.interceptor.ts

@@ -0,0 +1,58 @@
+import { IFetchResponse } from '@c8y/client';
+import { ApiCall, HttpHandler, HttpInterceptor } from '@c8y/ngx-components/api';
+import { Observable } from 'rxjs';
+import { generateResponse, handleRequest } from '../utils/common';
+
+export class MeasurementsInterceptor implements HttpInterceptor {
+  intercept(req: ApiCall, next: HttpHandler): Observable<IFetchResponse> {
+    return handleRequest(req, next, 'measurement/measurements', {
+      POST: this.mockPOST.bind(this),
+      PUT: this.mockPUT.bind(this),
+      GET: this.mockGET.bind(this)
+    });
+  }
+
+  private mockPOST(_requestDescriptor) {
+    return null;
+  }
+
+  private mockPUT(_requestDescriptor) {
+    return null;
+  }
+
+  private mockGET(_requestDescriptor: string) {
+    const responseGenerators = this.getResponseGenerators();
+
+    for (const urlPart in responseGenerators) {
+      if (_requestDescriptor.includes(urlPart)) {
+        const generatorResult = responseGenerators[urlPart]();
+        if (generatorResult) {
+          return generateResponse(() => generatorResult);
+        }
+      }
+    }
+    return null;
+  }
+
+  private getResponseGenerators() {
+    return {
+      c8y_Battery: () => ({
+        measurements: [
+          {
+            id: '10000',
+            type: 'c8y_Battery',
+            source: {
+              id: '20000'
+            },
+            c8y_Battery: {
+              Battery: {
+                unit: '%',
+                value: 67
+              }
+            }
+          }
+        ]
+      })
+    };
+  }
+}

package/src/__mocks/index.ts

@@ -0,0 +1,5 @@
+export * from './mock.module';
+export * from './mock.service';
+export * from './mock.model';
+export * from './mock.realtime';
+export * from './mock.realtime-subject';

package/src/__mocks/mock.model.ts

@@ -0,0 +1,76 @@
+import { InjectionToken } from '@angular/core';
+import {
+  IAlarm,
+  IEvent,
+  IManagedObject,
+  IMeasurement,
+  IOperation,
+  IOperationBulk
+} from '@c8y/client';
+import { HttpInterceptor } from '@c8y/ngx-components/api';
+
+/**
+ * A string literal type that represents the HTTP methods that can be used for making requests.
+ */
+export type HttpMethods = 'GET' | 'POST' | 'PUT' | 'DELETE' | 'OPTIONS' | 'PATCH';
+/**
+ * A type that extends the built-in Response object to include a json method, which returns a Promise of a generic type T.
+ */
+export type ResponseWithType<T = unknown> = Response & {
+  json: () => T;
+};
+/**
+ * A union type representing any of the possible data types.
+ */
+export type IAnyData =
+  | IAlarm
+  | IEvent
+  | IManagedObject
+  | IMeasurement
+  | IOperation
+  | IOperationBulk;
+
+/**
+ * Enumeration of the possible channel paths.
+ */
+export enum Channels {
+  ManagedObjects = '/managedobjects/*',
+  Operations = '/operations/*',
+  BulkOperations = '/bulkOperations/*',
+  Measurements = '/measurements/*',
+  Alarms = '/alarms/*',
+  Events = '/events/*',
+  MangedObjectsMap = '/managedobjects/1'
+}
+/**
+ * path and mockService
+ */
+export const API_MOCK_CONFIG = new InjectionToken<ApiMockConfig>('ApiMockConfig');
+/**
+ * Interface for configuring API mocking.
+ */
+export interface ApiMockConfig {
+  /**
+   * Route path under which all interceptors are registered.
+   * By default all routes are affected.
+   */
+  path?: string;
+  /**
+   * Mock service that should implement the HttpInterceptor interface.
+   * This service will be used to intercept http requests and return mock responses.
+   */
+  mockService: new (...args: unknown[]) => HttpInterceptor;
+  /**
+   * Unique identifier for the interceptor.
+   */
+  id: string;
+  debug?: boolean;
+}
+/**
+ * An object representing default values for pagination statistics.
+ */
+export const DEFAULT_STATISTICS = {
+  totalPages: 1,
+  pageSize: 2000,
+  currentPage: 1
+};

package/src/__mocks/mock.module.ts

@@ -0,0 +1,121 @@
+import { CommonModule } from '@angular/common';
+import { Inject, NgModule } from '@angular/core';
+import { IUser } from '@c8y/client';
+import {
+  AppStateService,
+  CoreModule,
+  OptionsService,
+  RealtimeSubjectService
+} from '@c8y/ngx-components';
+import { InventoryInterceptor } from './global-mocks/inventory.interceptor';
+import { MeasurementsInterceptor } from './global-mocks/measurements.interceptor';
+import { API_MOCK_CONFIG, ApiMockConfig } from './mock.model';
+import { MockService } from './mock.service';
+import { NamedContextDashboardInterceptor } from './scoped-mocks/named-context-dashboard';
+import { ContextDashboardInterceptor } from './scoped-mocks/context-dashboard';
+import { ServerSideDataGridInterceptor } from './scoped-mocks/server-side-data-grid';
+import { DeviceDataGridInterceptor } from './scoped-mocks/device-data-grid';
+import { ServiceDashboardInterceptor } from './scoped-mocks/service-dashboard';
+import { RealtimeSubjectServiceWithMocking } from './mock.realtime';
+// import { BoilerplateInterceptor } from './scoped-mocks/boilerplate';
+@NgModule({
+  imports: [CoreModule, CommonModule],
+  providers: [
+    // TODO: ask Jan about mocking clusters maps/cluster
+    // {
+    //   provide: API_MOCK_CONFIG,
+    //   useValue: {
+    //     id: 'a-cluster-map-interceptor',
+    //     path: 'maps/cluster',
+    //     mockService: BoilerplateInterceptor,
+    //     debug: true
+    //   } as ApiMockConfig,
+    //   multi: true
+    // },
+    {
+      provide: API_MOCK_CONFIG,
+      useValue: {
+        id: 'a-service-dashboard-interceptor',
+        path: 'service-dashboard',
+        mockService: ServiceDashboardInterceptor,
+        debug: true
+      } as ApiMockConfig,
+      multi: true
+    },
+    {
+      provide: API_MOCK_CONFIG,
+      useValue: {
+        id: 'server-side-data-grid-interceptor',
+        path: 'server-grid-example',
+        mockService: ServerSideDataGridInterceptor
+      } as ApiMockConfig,
+      multi: true
+    },
+    {
+      provide: API_MOCK_CONFIG,
+      useValue: {
+        id: 'device-data-grid-interceptor',
+        path: 'device-grid-example',
+        mockService: DeviceDataGridInterceptor
+      } as ApiMockConfig,
+      multi: true
+    },
+    {
+      provide: API_MOCK_CONFIG,
+      useValue: {
+        id: 'scoped-dashboard-context-interceptor',
+        path: 'dashboards/context',
+        mockService: ContextDashboardInterceptor
+      } as ApiMockConfig,
+      multi: true
+    },
+    {
+      provide: API_MOCK_CONFIG,
+      useValue: {
+        path: 'named-context',
+        // The interceptors are sorted by their ID, so the scoped interceptors should be before the global ones.
+        id: 'named-context-interceptor-example',
+        mockService: NamedContextDashboardInterceptor
+      } as ApiMockConfig,
+      multi: true
+    },
+    {
+      provide: API_MOCK_CONFIG,
+      useValue: {
+        // The interceptors are sorted by their ID, so the scoped interceptors should be before the global ones.
+        id: 'z-global-inventory-interceptor',
+        mockService: InventoryInterceptor
+      } as ApiMockConfig,
+      multi: true
+    },
+    {
+      provide: API_MOCK_CONFIG,
+      useValue: {
+        // The interceptors are sorted by their ID, so the scoped interceptors should be before the global ones.
+        id: 'z-global-measurementsInterceptor-interceptor',
+        mockService: MeasurementsInterceptor
+      } as ApiMockConfig,
+      multi: true
+    },
+    {
+      provide: RealtimeSubjectService,
+      useExisting: RealtimeSubjectServiceWithMocking
+    }
+  ]
+})
+export class MockModule {
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  constructor(
+    @Inject(MockService) service,
+    appStateService: AppStateService,
+    private options: OptionsService
+  ) {
+    if (this.options.get<boolean>('noLogin', false)) {
+      appStateService.currentUser.next({
+        id: 'NO_LOGIN',
+        userName: 'noLogin',
+        displayName: 'noLogin'
+      } as IUser);
+    }
+  }
+}

package/src/__mocks/mock.realtime-subject.ts

@@ -0,0 +1,68 @@
+import { Injectable } from '@angular/core';
+import { RealtimeMessage } from '@c8y/ngx-components';
+import { Observable, Subject, Subscription, interval } from 'rxjs';
+import { map, take, takeUntil } from 'rxjs/operators';
+import { CleanRealtime } from './utils/clean.realtime';
+import { Channels } from './mock.model';
+import { getFakeData } from './utils/realtime';
+import { IManagedObject } from '@c8y/client';
+
+/**
+ * Mock service for creating a stream of realtime data for a given channel.
+ */
+@Injectable({ providedIn: 'root' })
+export class MockRealtimeSubject {
+  /**
+   * The channel for which the realtime data will be mocked.
+   */
+  private readonly REALTIME_CHANNEL = Channels.ManagedObjects;
+  /**
+   * The subscription for the interval generating the mocked data.
+   */
+  private intervalSubscription: Subscription;
+  /**
+   * The subject emitting the mocked realtime data.
+   */
+  private realtimeMockedData$: Subject<RealtimeMessage<IManagedObject>>;
+
+  constructor(cleanRealtime: CleanRealtime) {
+    cleanRealtime.stop$.pipe(takeUntil(cleanRealtime.onDestroy$)).subscribe(() => this.cleanUp());
+    cleanRealtime.onDestroy$.pipe(take(1)).subscribe(() => this.cleanUp());
+  }
+  /**
+   * Returns an observable emitting realtime data for the given channel.
+   *
+   * @returns The observable of the mocked realtime data.
+   */
+  getObservableForChannel(): Observable<RealtimeMessage<IManagedObject>> {
+    this.realtimeMockedData$ = new Subject<RealtimeMessage<IManagedObject>>();
+    this.setInterval(this.realtimeMockedData$);
+    return this.realtimeMockedData$;
+  }
+  /**
+   * Sets up an interval for generating and emitting the mocked data.
+   *
+   * @param realtimeMessageSubject$ - The subject to emit the mocked data.
+   */
+  private setInterval(realtimeMessageSubject$: Subject<RealtimeMessage<IManagedObject>>) {
+    this.intervalSubscription = interval(5000)
+      .pipe(map(() => getFakeData<IManagedObject>(this.REALTIME_CHANNEL)))
+      .subscribe(data => {
+        if (!realtimeMessageSubject$.isStopped) {
+          realtimeMessageSubject$.next(data);
+        }
+      });
+  }
+  /**
+   * Cleans up by completing and unsubscribing the subject and the interval subscription.
+   */
+  private cleanUp() {
+    if (this.realtimeMockedData$) {
+      this.realtimeMockedData$.complete();
+      this.realtimeMockedData$.unsubscribe();
+    }
+    if (this.intervalSubscription) {
+      this.intervalSubscription.unsubscribe();
+    }
+  }
+}

package/src/__mocks/mock.realtime.ts

@@ -0,0 +1,31 @@
+import { Injectable } from '@angular/core';
+import { OptionsService, RealtimeMessage, RealtimeSubjectService } from '@c8y/ngx-components';
+import { Observable, interval } from 'rxjs';
+import { map } from 'rxjs/operators';
+import { getFakeData } from './utils/realtime';
+import { Realtime } from '@c8y/client';
+
+/**
+ * A mocked implementation of `RealtimeSubjectService` provides observables with emitting fake data every 5 seconds in case the noLogin option is set.
+ * In case it is not set, we will use the default functionality of `RealtimeSubjectService`.
+ */
+@Injectable({ providedIn: 'root' })
+export class RealtimeSubjectServiceWithMocking extends RealtimeSubjectService {
+  mockingEnabled = false;
+  constructor(options: OptionsService, realtime: Realtime) {
+    super(realtime);
+    this.mockingEnabled = options.get<boolean>('noLogin', false);
+  }
+
+  getObservableForChannel<T>(channel: string): Observable<RealtimeMessage<T>> {
+    if (!this.mockingEnabled) {
+      return super.getObservableForChannel(channel);
+    }
+
+    return this.getMockedData$<T>(channel);
+  }
+
+  private getMockedData$<T>(channel: string): Observable<RealtimeMessage<T>> {
+    return interval(5000).pipe(map(() => getFakeData<T>(channel)));
+  }
+}

package/src/__mocks/mock.service.ts

@@ -0,0 +1,113 @@
+import { Inject, Injectable } from '@angular/core';
+import { NavigationEnd, Router } from '@angular/router';
+import { OptionsService } from '@c8y/ngx-components';
+import { ApiService } from '@c8y/ngx-components/api';
+import { filter } from 'rxjs/operators';
+import { API_MOCK_CONFIG, ApiMockConfig } from './mock.model';
+interface DebugData {
+  text: string;
+  content?: any;
+}
+@Injectable({ providedIn: 'root' })
+export class MockService {
+  constructor(
+    @Inject(API_MOCK_CONFIG) private apiMocks,
+    private apiService: ApiService,
+    private router: Router,
+    private options: OptionsService
+  ) {
+    if (this.options.get<boolean>('noLogin', false)) {
+      this.setupMocks();
+    }
+  }
+  /**
+   * Method responsible for setting up API mock behaviors.
+   * It adds global interceptors and handles scoped interceptors for the current router URL.
+   * If 'noLogin' option is true, it sets up scoped interceptors based on router navigation events and returns.
+   * If 'noLogin' option is false, it sets up reactions for changes in the Mock API enabled state and
+   * sets up scoped interceptors with filter based on router navigation events.
+   */
+  private setupMocks() {
+    this.addGlobalInterceptors();
+    this.handleScopedInterceptors(this.router.url);
+
+    this.setupScopedInterceptorsOnNavigationEnd();
+  }
+  /**
+   * Method responsible for handling scoped interceptors based on router navigation events.
+   * It listens for NavigationEnd events, and calls handleScopedInterceptors method with current URL.
+   */
+  private setupScopedInterceptorsOnNavigationEnd() {
+    this.router.events
+      .pipe(filter(event => event instanceof NavigationEnd))
+      .subscribe((event: NavigationEnd) => {
+        this.handleScopedInterceptors(event.url);
+      });
+  }
+  /**
+   * Registers global interceptors from the apiMocks configuration.
+   *
+   * This method filters apiMocks for entries with undefined path, considering them as global.
+   * For each such entry, it creates an instance of the corresponding mock service and adds it as an interceptor.
+   *
+   * Note: The method is private and is likely to be used within the class internally.
+   */
+  private addGlobalInterceptors() {
+    const mocksToRegister = this.apiMocks.filter((mock: ApiMockConfig) => mock.path === undefined);
+    mocksToRegister.forEach((mock: ApiMockConfig) => {
+      if (this.apiService.hasInterceptor(mock.id)) {
+        return;
+      }
+      this.apiService.addInterceptor(new mock.mockService() as any, mock.id);
+      this.logDebugInfo({ text: `Added global interceptor with id: ${mock.id}` }, mock.debug);
+    });
+  }
+  /**
+   * Handles registration and unregistration of scoped interceptors based on the provided URL.
+   *
+   * This method filters the apiMocks configuration for entries where the path is defined and included in the URL.
+   * It registers these as scoped interceptors. It then filters for entries where the path is defined but not included in the URL,
+   * and unregisters these interceptors.
+   *
+   * @param url The URL used to determine which interceptors to register and unregister.
+   */
+  private handleScopedInterceptors(url: string) {
+    const mocksToRegister = [];
+    const mocksToUnregister = [];
+
+    this.apiMocks.forEach((mock: ApiMockConfig) => {
+      if (!mock.path) {
+        return;
+      }
+
+      if (url.includes(mock.path)) {
+        mocksToRegister.push(mock);
+      } else {
+        mocksToUnregister.push(mock);
+      }
+    });
+
+    this.applyMockConfig(mocksToRegister, mock => {
+      this.logDebugInfo({ text: `Added scoped interceptor with id: ${mock.id}` }, mock.debug);
+      this.apiService.addInterceptor(new mock.mockService() as any, mock.id);
+    });
+
+    this.applyMockConfig(mocksToUnregister, mock => {
+      if (this.apiService.hasInterceptor(mock.id)) {
+        this.logDebugInfo({ text: `Removed scoped interceptor with id: ${mock.id}` }, mock.debug);
+        this.apiService.removeInterceptor(mock.id);
+      }
+    });
+  }
+
+  private applyMockConfig(mockConfigs: ApiMockConfig[], action: (mock: ApiMockConfig) => void) {
+    mockConfigs.forEach(mock => action(mock));
+  }
+
+  private logDebugInfo(data: DebugData, show: boolean) {
+    if (show) {
+      // eslint-disable-next-line no-console
+      data.content ? console.info(data.text, data.content) : console.info(data.text);
+    }
+  }
+}