@intellegens/cornerstone-client 0.0.0-experimental-upgrade-20260302-1

package/src/services/api/ApiInitializationService/index.ts

@@ -0,0 +1,254 @@
+// websettings.json configuration file contents type
+import { fail, ok } from '@utils';
+
+type WebSettings = {
+  api: string | undefined;
+};
+
+/**
+ * Generic shared settings interface - can represent any user-configured settings structure
+ * The actual properties depend on what users configure in their appsettings.json or environment variables
+ */
+type ISharedSettings = {
+  [key: string]: unknown;
+};
+
+/**
+ * Initialization info DTO that matches the server-side structure
+ */
+type IInitializationInfoDto<TSharedSettings = ISharedSettings> = {
+  appSettings: TSharedSettings;
+};
+
+import { ApiErrorResponseDto, ApiSuccessResponseDto, EmptyMetadataDto } from '@/data';
+import { defaultHttpService, IHttpService } from '../HttpService';
+
+/**
+ * Central API configuration service, fetches and exposes Cornerstone API configuration
+ *
+ * @export
+ * @class ApiInitializationService
+ */
+export class ApiInitializationService {
+  /**
+   * If API base URL detection was completed
+   * IMPORTANT: This property is not meant to be used in normal cases - when ever possible use the .getApiUrl(relativeEndpointPath: string) method instead.
+   */
+  public _apiBaseUrlDetected = false;
+
+  // #region HTTP service
+  /**
+   * If API base URL detection was completed, this property will hold the method by which detection was performed
+   * IMPORTANT: This property is not meant to be used in normal cases - when ever possible use the .getApiUrl(relativeEndpointPath: string) method instead.
+   */
+  public _apiBaseUrlDetectionMethod: string | undefined = undefined;
+  /**
+   * If API base URL detection was completed, this property will hold the detected API base URL
+   * IMPORTANT: This property is not meant to be used in normal cases - when ever possible use the .getApiUrl(relativeEndpointPath: string) method instead.
+   */
+  public _apiBaseUrl: string | undefined = undefined;
+
+  // #endregion
+
+  // #region API Base URL detection
+  /**
+   * If API base URL detection has failed, this property will hold the error with which it has failed
+   * IMPORTANT: This property is not meant to be used in normal cases - when ever possible use the .getApiUrl(relativeEndpointPath: string) method instead.
+   */
+  public _apiBaseError: Error | undefined = undefined;
+  // #region config App
+  public appConfig?: ISharedSettings | undefined;
+  private _httpService: IHttpService = defaultHttpService;
+  private _apiBaseUrlPromise: Promise<string | undefined> | undefined = undefined;
+
+  /**
+   * Initializes the API configuration
+   *
+   * This method calls all methods that need to be called during the API configuration phase:
+   * - Starts detection of API base URL.
+   * - Fetches shared settings from the server.
+   *
+   * @async
+   * @param httpService - HTTP service implementation to use for requests
+   * @param {AbortSignal} [signal] - Optional cancellation signal
+   * @return {Promise<void>} Resolves when initialization is complete.
+   */
+  public async initialize({
+    httpService,
+    signal,
+  }: {
+    httpService?: IHttpService;
+    signal?: AbortSignal;
+  } = {}): Promise<void> {
+    // Store configuration
+    if (httpService !== undefined) this._httpService = httpService;
+    // (Pre)detect API base URL
+    await this._getApiBaseUrl(signal);
+    // Initialize app config
+    await this._getAppConfig();
+  }
+
+  /**
+   * Gets configured HTTP service
+   * @returns
+   */
+  public _getHttpService(): IHttpService {
+    return this._httpService;
+  }
+
+  /**
+   * Tries detecting API base URL by multiple methods
+   *
+   * - Checks the response headers of the current URL for the `CORNERSTONE-API-BASEURL` header.
+   * - Attempts to load the `websettings.json` file and looks for an `api` field.
+   * - Defaults to `undefined`.
+   *
+   * IMPORTANT: This method is not meant to be used in normal cases - when ever possible use the .getApiUrl(relativeEndpointPath: string) method instead.
+   *
+   * @async
+   * @param {AbortSignal} [signal] - Optional cancellation signal
+   * @return {Promise<string | undefined>} Returns detected API base URL
+   * @throws {Error} Throws error if either of the detection methods fails
+   */
+  public async _getApiBaseUrl(signal?: AbortSignal): Promise<string | undefined> {
+    // Check if API already detected; don't reattempt detection
+    if (this._apiBaseUrlDetected) return this._apiBaseUrl;
+
+    // Check if detection already in progress; don't allow multiple detections in parallel
+    if (this._apiBaseUrlPromise) return this._apiBaseUrlPromise;
+
+    // Detect API base URL
+    return (this._apiBaseUrlPromise = new Promise<string | undefined>((resolve, reject) =>
+      (async () => {
+        // Reset
+        this._apiBaseUrlDetected = false;
+        this._apiBaseUrlDetectionMethod = undefined;
+        this._apiBaseUrl = undefined;
+        this._apiBaseError = undefined;
+
+        // Check CORNERSTONE-API-BASEURL header for API base URL
+        try {
+          const currentUrlResponse = await this._httpService.request(window.location.href, {
+            method: 'GET',
+            signal,
+          });
+          const apiHeader: string | null =
+            currentUrlResponse.headers['CORNERSTONE-API-BASEURL'] || currentUrlResponse.headers['cornerstone-api-baseurl'] || null;
+          if (apiHeader) {
+            this._apiBaseUrlDetected = true;
+            this._apiBaseUrlDetectionMethod = 'GET / Header:CORNERSTONE-API-BASEURL';
+            this._apiBaseUrl = apiHeader;
+            this._apiBaseError = undefined;
+            this._apiBaseUrlPromise = undefined;
+            return resolve(this._apiBaseUrl);
+          }
+        } catch (err) {
+          this._apiBaseError = err instanceof Error ? err : new Error('Failed loading API base URL from response header!');
+        }
+
+        // Check ./websettings.json header for API base URL
+        try {
+          const webSettingsResponse = await this._httpService.request('./websettings.json', {
+            method: 'GET',
+            signal,
+          });
+          if (webSettingsResponse.status === 404) return (this._apiBaseUrl = undefined);
+          const webSettings: WebSettings = await webSettingsResponse.json();
+          if (webSettings?.api) {
+            this._apiBaseUrlDetected = true;
+            this._apiBaseUrlDetectionMethod = 'GET websettings.json';
+            this._apiBaseUrl = webSettings.api;
+            this._apiBaseError = undefined;
+            this._apiBaseUrlPromise = undefined;
+            return resolve(this._apiBaseUrl);
+          }
+        } catch (err) {
+          this._apiBaseError = err instanceof Error ? err : new Error('Failed loading API base URL from settings file!');
+        }
+
+        // Check if error caught during any of the detection methods
+        if (this._apiBaseError !== undefined) {
+          this._apiBaseUrlDetected = false;
+          this._apiBaseUrlDetectionMethod = undefined;
+          this._apiBaseUrl = undefined;
+          this._apiBaseUrlPromise = undefined;
+          return reject(this._apiBaseError);
+        }
+
+        // Default to no API found
+        this._apiBaseUrlDetected = true;
+        this._apiBaseUrlDetectionMethod = undefined;
+        this._apiBaseUrl = undefined;
+        this._apiBaseError = undefined;
+        this._apiBaseUrlPromise = undefined;
+        return resolve(this._apiBaseUrl);
+      })(),
+    ));
+  }
+
+  /**
+   * Composes a full API URL for a provided endpoint path.
+   *
+   * @async
+   * @param relativeEndpointPathSections Relative endpoint path sections
+   * @return {Promise<string | undefined>} Returns the API endpoint's URL
+   * @throws {Error} Throws error if API base URL detection fails
+   */
+  public async getApiUrl(...relativeEndpointPathSections: string[]): Promise<string> {
+    const apiBaseUrl = await this._getApiBaseUrl();
+    const domain = !apiBaseUrl ? '/' : `${this.removeEndsWithSlashChar(apiBaseUrl)}/`;
+    const path = relativeEndpointPathSections.map(section => this.removeStartsWithSlashChar(this.removeEndsWithSlashChar(section))).join('/');
+    return `${domain}${path}`;
+  }
+
+  /**
+   * Removes starting '/' character
+   * @param str String to remove the starting '/' character from
+   * @returns String with starting '/' character  removed
+   */
+  private removeStartsWithSlashChar(str: string): string {
+    return !str.startsWith('/') ? str : str.substring(1);
+  }
+
+  // #endregion
+
+  /**
+   * Removes ending '/' character
+   * @param str String to remove the ending '/' character from
+   * @returns String with ending '/' character  removed
+   */
+  private removeEndsWithSlashChar(str: string): string {
+    return !str.endsWith('/') ? str : str.substring(0, str.length - 1);
+  }
+
+  /**
+   * Fetches initialization info (shared settings) from the server
+   * @returns Promise that resolves to shared settings or undefined if the request fails
+   */
+  private async _getAppConfig(): Promise<void> {
+    try {
+      const response = await fetch(`${this._apiBaseUrl}/system/init`, { credentials: 'include' });
+      if (!response.ok) {
+        throw fail(await response.json()) as ApiErrorResponseDto;
+      }
+      const apiResponse = ok<ApiSuccessResponseDto<IInitializationInfoDto, EmptyMetadataDto>, ApiErrorResponseDto>(await response.json());
+
+      if (!apiResponse.ok) {
+        throw apiResponse.error;
+      }
+
+      // Return the settings from the nested structure
+      this.appConfig = apiResponse.result.appSettings;
+    } catch (error) {
+      console.error('Failed to get app config', error);
+      this.appConfig = undefined;
+    }
+  }
+
+  // #endregion
+}
+
+/**
+ * Singleton instance of ApiInitializationService
+ */
+export const apiInitializationService = new ApiInitializationService();

package/src/services/api/ApiReadControllerClient/index.integration.test.ts

@@ -0,0 +1,71 @@
+import { beforeEach, describe, expect, it } from 'vitest';
+import { ApiReadControllerClient } from '.';
+import { FetchHttpService } from '../HttpService';
+import { ReadSelectedComparisonOperator, ReadSelectedDefinitionDto, ReadSelectedLogicalOperator, ReadSelectedPropertyType } from '@/data';
+
+type VehicleSlimDto = { Id: number; Brand: string; Model: string; Year: number; RowVersion: string };
+
+describe('ApiReadControllerClient', () => {
+  let client: ApiReadControllerClient<number, any, any>;
+  let fetchService: FetchHttpService;
+
+  beforeEach(() => {
+    fetchService = new FetchHttpService();
+    client = new ApiReadControllerClient('/VehiclesSlim', fetchService);
+  });
+
+  it('should use injected HTTP service for readAll', async () => {
+    const result = (await client.readAll()) as { ok: boolean; result: any };
+
+    expect(result.ok).toBe(true);
+    expect(result.result).toBeDefined();
+  });
+
+  it('should use injected HTTP service for readSingle', async () => {
+    const testId = 1;
+    const result = (await client.readSingle(testId)) as { ok: boolean; result: any };
+
+    expect(result.ok).toBe(true);
+    expect(result.result).toBeDefined();
+    expect(typeof result.result).toBe('object');
+    expect(result.result.id).toBe(testId);
+  });
+
+  it('should use injected HTTP service for readSelected', async () => {
+    const definition: ReadSelectedDefinitionDto<VehicleSlimDto> = {
+      searchDefinition: {
+        searches: [
+          {
+            propertyCriteria: [
+              {
+                propertyName: 'Brand',
+                comparisonOperator: ReadSelectedComparisonOperator.Equal,
+                valueType: ReadSelectedPropertyType.String,
+                value: 'Audi',
+              },
+              {
+                propertyName: 'Brand',
+                comparisonOperator: ReadSelectedComparisonOperator.Equal,
+                valueType: ReadSelectedPropertyType.String,
+                value: 'BMW',
+              },
+            ],
+            logicalOperator: ReadSelectedLogicalOperator.Or,
+          },
+        ],
+        logicalOperator: ReadSelectedLogicalOperator.And,
+      },
+    };
+
+    const result = (await client.readSelected(definition)) as { ok: boolean; result: any };
+
+    expect(result.ok).toBe(true);
+    expect(result.result).toBeDefined();
+  });
+
+  it('should handle HTTP errors properly', async () => {
+    const invalidClient = new ApiReadControllerClient('/InvalidPath', fetchService);
+    const result = await invalidClient.readAll();
+    expect(result.ok).toBe(false);
+  });
+});

package/src/services/api/ApiReadControllerClient/index.ts

@@ -0,0 +1,137 @@
+import { apiInitializationService } from '../ApiInitializationService';
+import {
+  ApiErrorResponseDto,
+  ApiResponseDto,
+  ApiSuccessResponseDto,
+  EmptyMetadataDto,
+  ReadMetadataDto,
+  ReadSelectedDefinitionDto,
+} from '../../../data/api/dto';
+import { IIdentifiable } from '../../../data/api/interface';
+import { IHttpService } from '../HttpService';
+import { fail, ok } from '@utils/result';
+import { ErrorCode } from '@data';
+
+/**
+ * Base client for read-only API controllers
+ */
+export class ApiReadControllerClient<TKey, TResultDto extends IIdentifiable<TKey>, TSingleResultDto extends IIdentifiable<TKey>> {
+  /**
+   * Constructor
+   * @param baseControllerPath Base path to API controller
+   * @param httpService HTTP service implementation to use for requests
+   */
+  constructor(
+    protected readonly baseControllerPath: string,
+    httpService?: IHttpService,
+  ) {
+    this._httpService = httpService;
+  }
+
+  // #region HTTP service
+  private readonly _httpService?: IHttpService = undefined;
+
+  /**
+   * Gets globally selected HTTP service
+   */
+  protected get httpService(): IHttpService {
+    return this._httpService || apiInitializationService._getHttpService();
+  }
+
+  // #endregion
+
+  // #region API
+  /**
+   * Fetches all entities from the read controller.
+   * @param {AbortSignal} [signal] - Optional cancellation signal
+   * @returns {Promise<ApiSuccessResponseDto<TDto>[], ReadMetadataDto>>} List of all entities with metadata
+   */
+  public async readAll(signal?: AbortSignal): Promise<ApiResponseDto<TResultDto[], ReadMetadataDto>> {
+    try {
+      const url = await apiInitializationService.getApiUrl(this.baseControllerPath, `/ReadAll`);
+      const res = await this.httpService.request(url, { method: 'GET', credentials: 'include', signal });
+
+      if (!res.ok) {
+        return fail<ApiSuccessResponseDto<TResultDto[], ReadMetadataDto>, ApiErrorResponseDto>(await res.json());
+      }
+
+      return ok<ApiSuccessResponseDto<TResultDto[], ReadMetadataDto>, ApiErrorResponseDto>(await res.json());
+    } catch (err) {
+      console.error(err);
+
+      return fail<ApiSuccessResponseDto<TResultDto[], ReadMetadataDto>, ApiErrorResponseDto>({
+        error: {
+          code: ErrorCode.UnknownError,
+          message: 'Unknown error fetching all records',
+          metadata: {} as EmptyMetadataDto,
+        },
+      });
+    }
+  }
+
+  /**
+   * Fetches selected entities based on a filter definition.
+   * @param {any} definition - The filter definition object
+   * @param {AbortSignal} [signal] - Optional cancellation signal
+   * @returns {Promise<ApiSuccessResponseDto<TDto>[], ReadMetadataDto>>} The result of the read operation with metadata
+   */
+  public async readSelected(definition: ReadSelectedDefinitionDto<TResultDto>, signal?: AbortSignal): Promise<ApiResponseDto<TResultDto[], ReadMetadataDto>> {
+    try {
+      const url = await apiInitializationService.getApiUrl(this.baseControllerPath, `/ReadSelected`);
+      const res = await this.httpService.request(url, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify(definition),
+        credentials: 'include',
+        signal,
+      });
+
+      if (!res.ok) {
+        return fail<ApiSuccessResponseDto<TResultDto[], ReadMetadataDto>, ApiErrorResponseDto>(await res.json());
+      }
+
+      return ok<ApiSuccessResponseDto<TResultDto[], ReadMetadataDto>, ApiErrorResponseDto>(await res.json());
+    } catch (err) {
+      console.error(err);
+
+      return fail<ApiSuccessResponseDto<TResultDto[], ReadMetadataDto>, ApiErrorResponseDto>({
+        error: {
+          code: ErrorCode.UnknownError,
+          message: 'Unknown error fetching selected records',
+          metadata: {} as EmptyMetadataDto,
+        },
+      });
+    }
+  }
+
+  /**
+   * Fetches a single entity by its ID.
+   * @param {TKey} id - The ID of the entity
+   * @param {AbortSignal} [signal] - Optional cancellation signal
+   * @returns {Promise<ApiSuccessResponseDto<TDto, EmptyMetadataDto>>} The requested entity
+   */
+  public async readSingle(id: TKey, signal?: AbortSignal): Promise<ApiResponseDto<TSingleResultDto, EmptyMetadataDto>> {
+    try {
+      const url = await apiInitializationService.getApiUrl(this.baseControllerPath, `/ReadSingle?id=${encodeURIComponent(String(id))}`);
+      const res = await this.httpService.request(url, { method: 'GET', credentials: 'include', signal });
+
+      if (!res.ok) {
+        return fail<ApiSuccessResponseDto<TSingleResultDto, EmptyMetadataDto>, ApiErrorResponseDto>(await res.json());
+      }
+
+      return ok<ApiSuccessResponseDto<TSingleResultDto, EmptyMetadataDto>, ApiErrorResponseDto>(await res.json());
+    } catch (err) {
+      console.error(err);
+
+      return fail<ApiSuccessResponseDto<TSingleResultDto, EmptyMetadataDto>, ApiErrorResponseDto>({
+        error: {
+          code: ErrorCode.UnknownError,
+          message: `Unknown error fetching record with id ${id}`,
+          metadata: {} as EmptyMetadataDto,
+        },
+      });
+    }
+  }
+
+  // #endregion
+}

package/src/services/api/HttpService/FetchHttpService.integration.test.ts

@@ -0,0 +1,65 @@
+import { beforeEach, describe, expect, it } from 'vitest';
+import { FetchHttpService } from './FetchHttpService';
+
+const baseUrl = 'http://localhost:5000/api';
+const credentials = {
+  username: 'admin@test.com',
+  password: 'Password1234!',
+};
+
+describe('FetchHttpService', () => {
+  let fetchService: FetchHttpService;
+
+  beforeEach(() => {
+    fetchService = new FetchHttpService();
+  });
+
+  it('should make a GET request successfully', async () => {
+    const result = await fetchService.request(`${baseUrl}/AnythingManuallyMappedRead/ReadAll`);
+
+    expect(result.ok).toBe(true);
+    expect(result.status).toBe(200);
+    expect(result.statusText).toBe('OK');
+
+    const jsonData = await result.json();
+    expect(jsonData.result).toBeDefined();
+    expect(jsonData.error).toBeNull();
+  });
+
+  it('should make a POST request with body', async () => {
+    const result = await fetchService.request(`${baseUrl}/auth/signin`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(credentials),
+    });
+
+    expect(result.ok).toBe(true);
+    expect(result.status).toBe(204);
+  });
+
+  it('should handle non-ok responses', async () => {
+    const result = await fetchService.request(`${baseUrl}/auth/signin`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ username: credentials.username, password: `${credentials.password}wrong` }),
+    });
+
+    expect(result.ok).toBe(false);
+    expect(result.status).toBe(400);
+    expect(result.statusText).toBe('Bad Request');
+
+    const jsonData = await result.json();
+    expect(jsonData.result).toBeNull();
+    expect(jsonData.error).toBeDefined();
+    expect(jsonData.error.code).toBe(400);
+    expect(jsonData.error.message).toBe('Invalid email or password');
+  });
+
+  it('should handle fetch errors from backend', async () => {
+    const result = await fetchService.request('http://localhost:5000/api/error');
+
+    expect(result.ok).toBe(false);
+    expect(result.status).toBe(404);
+    expect(result.statusText).toBe('Not Found');
+  });
+});

package/src/services/api/HttpService/FetchHttpService.ts

@@ -0,0 +1,34 @@
+// Ignore eslint any error in this file
+/* eslint-disable @typescript-eslint/no-explicit-any */
+
+import { HttpRequestConfig, HttpResponse, IHttpService } from '@/services';
+
+/**
+ * Default HTTP service implementation using the Fetch API
+ */
+export class FetchHttpService implements IHttpService {
+  public async request<T = any>(url: string, config?: HttpRequestConfig): Promise<HttpResponse<T>> {
+    const response = await fetch(url, {
+      method: config?.method || 'GET',
+      headers: config?.headers,
+      body: config?.body,
+      credentials: config?.credentials || 'include',
+      signal: config?.signal,
+    });
+
+    // Convert Headers to a plain object
+    const headers: Record<string, string> = {};
+    response.headers.forEach((value, key) => {
+      headers[key] = value;
+    });
+
+    return {
+      ok: response.ok,
+      status: response.status,
+      statusText: response.statusText,
+      headers,
+      json: () => response.json(),
+      text: () => response.text(),
+    };
+  }
+}

package/src/services/api/HttpService/HttpRequestConfig.ts

@@ -0,0 +1,10 @@
+/**
+ * HTTP request configuration interface
+ */
+export interface HttpRequestConfig {
+  method?: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH';
+  headers?: Record<string, string>;
+  body?: string;
+  credentials?: RequestCredentials;
+  signal?: AbortSignal;
+}

package/src/services/api/HttpService/HttpResponse.ts

@@ -0,0 +1,14 @@
+// Ignore eslint any error in this file
+/* eslint-disable @typescript-eslint/no-explicit-any */
+
+/**
+ * HTTP response interface
+ */
+export interface HttpResponse<T = any> {
+  ok: boolean;
+  status: number;
+  statusText: string;
+  headers: Record<string, string>;
+  json(): Promise<T>;
+  text(): Promise<string>;
+}

package/src/services/api/HttpService/IHttpService.ts

@@ -0,0 +1,17 @@
+// Ignore eslint any error in this file
+/* eslint-disable @typescript-eslint/no-explicit-any */
+
+import { HttpRequestConfig, HttpResponse } from '@/services';
+
+/**
+ * Abstract HTTP service interface that can be implemented by different HTTP clients
+ */
+export interface IHttpService {
+  /**
+   * Performs an HTTP request
+   * @param url - The URL to make the request to
+   * @param config - Request configuration
+   * @returns Promise that resolves to the HTTP response
+   */
+  request<T = any>(url: string, config?: HttpRequestConfig): Promise<HttpResponse<T>>;
+}