@intellegens/cornerstone-client 0.0.9999-alpha-9 → 0.0.9999-alpha-10

package/src/data/api/interface/IConcurrencySafe.ts

@@ -0,0 +1,9 @@
+/**
+ * Interface for entities that have row versioning
+ */
+export interface IConcurrencySafe {
+  /**
+   * Row version
+   */
+  rowVersion: string;
+};

package/src/data/api/interface/IIdentifiable.ts

@@ -0,0 +1,12 @@
+import { IConcurrencySafe } from './IConcurrencySafe';
+
+/**
+ * Interface for entities that have a Id property.
+ * Will be used as a primary key in the database.
+ */
+export interface IIdentifiable<TKey> extends IConcurrencySafe {
+  /**
+   * Gets or sets the Id of the entity.
+   */
+  id: TKey;
+}

package/src/data/api/interface/IIdentifiableSecondary.ts

@@ -0,0 +1,9 @@
+/**
+ * Interface for entities that have a secondary Id property.
+ */
+export interface IIdentifiableSecondary<TKey> {
+  /**
+   * Gets or sets the secondary Id of the entity.
+   */
+  idSecondary: TKey;
+}

package/src/data/api/interface/index.ts

@@ -0,0 +1,3 @@
+export * from './IIdentifiable';
+export * from './IIdentifiableSecondary';
+export * from './IConcurrencySafe';

package/src/data/auth/dto/ClaimDto.ts

@@ -0,0 +1,4 @@
+export type ClaimDto = {
+  type: string;
+  value: string;
+};

package/src/data/auth/dto/RegisterRequestDto.ts

@@ -0,0 +1,4 @@
+export type RegisterRequestDto = {
+  username: string;
+  password: string;
+};

package/src/data/auth/dto/RoleDto.ts

@@ -0,0 +1,6 @@
+import { ClaimDto } from '@data';
+
+export type RoleDto = {
+  name: string;
+  claims: ClaimDto[];
+};

package/src/data/auth/dto/SignInRequestDto.ts

@@ -0,0 +1,4 @@
+export type SignInRequestDto = {
+  username: string;
+  password: string;
+};

package/src/data/auth/dto/TokensDto.ts

@@ -0,0 +1,4 @@
+export type TokensDto = {
+  accessToken?: string;
+  refreshToken?: string;
+};

package/src/data/auth/dto/UserDto.ts

@@ -0,0 +1,18 @@
+import { ClaimDto } from '@data';
+import { IIdentifiable } from '@data';
+
+/**
+ * Represents a user with an identifier and email address.
+ *
+ * @template TKey The type of the user identifier.
+ *
+ * @param {TKey} id The unique identifier for the user.
+ * @param {string} email The email address associated with the user.
+ * @param {string[]} roles The roles associated with the user.
+ * @param {ClaimDto[]} claims The claims associated with the user.
+ */
+export type UserDto<TKey> = IIdentifiable<TKey> & {
+  email: string;
+  roles: string[];
+  claims: ClaimDto[];
+};

package/src/data/auth/dto/UserInfoDto.ts

@@ -0,0 +1,15 @@
+import { UserDto } from '@data';
+
+/**
+ * Represents user information along with access token expiry.
+ *
+ * @template TKey The type of the user identifier.
+ * @template TUser The type of the user object, defaulting to `UserDto<TKey>`.
+ *
+ * @param {TUser} user The user object containing user details.
+ * @param {Date} accessTokenExpiry The date and time when the access token will expire.
+ */
+export type UserInfoDto<TKey, TUser = UserDto<TKey>> = {
+  user: TUser;
+  accessTokenExpiry: Date;
+};

package/src/data/auth/dto/index.ts

@@ -0,0 +1,4 @@
+export * from './ClaimDto';
+export * from './UserDto';
+export * from './UserInfoDto';
+export * from './RoleDto';

package/src/data/auth/index.ts

@@ -0,0 +1,2 @@
+export * from './dto';
+export * from './policy';

package/src/data/auth/policy.ts

@@ -0,0 +1,63 @@
+/**
+ * Interface for policies that can be checked.
+ *
+ * @interface IPolicy<TParams extends unknown[]>
+ * @template TParams - The type of the parameters that will be passed to the policy check function.
+ */
+export interface IPolicy<TParams extends unknown[]> {
+  /**
+   * Checks if the policy is valid for the given parameters.
+   *
+   * @param params - Parameters to pass to the policy check function.
+   * @return A promise that resolves if the policy is valid, rejects otherwise.
+   */
+  check(...params: TParams): Promise<boolean>;
+}
+
+/**
+ * Base class for policies. It implements the IPolicy interface.
+ *
+ * @class PolicyBase
+ * @template TParams - The type of the parameters that will be passed to the policy check function.
+ */
+export class PolicyBase<TParams extends unknown[]> implements IPolicy<TParams> {
+  /**
+   * Checks if the policy is valid for the given parameters.
+   *
+   * @return A promise that resolves if the policy is valid, rejects otherwise.
+   * @throws {Error} Error if not implemented.
+   */
+  public async check(): Promise<boolean> {
+    throw new Error('Not implemented');
+  }
+}
+
+/**
+ * Class for policies that can be checked.
+ *
+ * @class Policy
+ * @template TParams - The type of the parameters that will be passed to the policy check function.
+ */
+export class Policy<TParams extends unknown[]> extends PolicyBase<TParams> {
+  private readonly _verificationFn: (...params: TParams) => Promise<boolean>;
+
+  /**
+   * Creates a new policy.
+   *
+   * @param verificationFn - The function that will be used to verify the policy.
+   */
+  constructor(verificationFn: (...params: TParams) => Promise<boolean>) {
+    super();
+    this._verificationFn = verificationFn;
+  }
+
+  /**
+   * Checks if the policy is valid for the given parameters.
+   *
+   * @param params - Parameters to pass to the policy check function.
+   * @return A promise that resolves if the policy is valid, rejects otherwise.
+   */
+  public async check(...params: TParams): Promise<boolean> {
+    return this._verificationFn(...params);
+  }
+}

package/src/data/index.ts

@@ -0,0 +1,2 @@
+export * from './auth';
+export * from './api';

package/src/index.ts

@@ -0,0 +1,4 @@
+export * from './services';
+export * from './data';
+export * from './adapters';
+export * from './utils';

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

@@ -0,0 +1,129 @@
+import { apiInitializationService } from '../ApiInitializationService';
+import { ApiErrorResponseDto, ApiResponseDto, ApiSuccessResponseDto, EmptyMetadataDto } from '../../../data/api/dto';
+import { IIdentifiable } from '../../../data/api/interface';
+import { IHttpService } from '../HttpService';
+import { ApiReadControllerClient } from '../ApiReadControllerClient';
+import { ErrorCode } from '@data';
+import { fail, ok } from '@utils/result';
+
+/**
+ * Generic API client for consuming any Cornerstone CrudController
+ *
+ * @export
+ * @class ApiCrudControllerClient
+ * @template TKey - Type of the entity key (e.g., number, string, GUID, etc.)
+ * @template TDto - Data Transfer Object representing the entity
+ */
+
+export class ApiCrudControllerClient<TKey, TDto extends IIdentifiable<TKey>> extends ApiReadControllerClient<TKey, TDto> {
+  /**
+   * Constructor
+   * @param baseControllerPath Base path to API controller
+   * @param httpService HTTP service implementation to use for requests
+   */
+  constructor(baseControllerPath: string, httpService?: IHttpService) {
+    super(baseControllerPath, httpService);
+  }
+
+  /**
+   * Creates a new entity.
+   * @param dto - Insert request DTO
+   * @param {AbortSignal} [signal] - Optional cancellation signal
+   * @returns The created entity DTO
+   */
+  public async create(dto: TDto, signal?: AbortSignal): Promise<ApiResponseDto<TDto, EmptyMetadataDto>> {
+    try {
+      const url = await apiInitializationService.getApiUrl(this.baseControllerPath, `/Create`);
+      const res = await this.httpService.request(url, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify(dto),
+        credentials: 'include',
+        signal,
+      });
+      if (!res.ok) {
+        return fail<ApiSuccessResponseDto<TDto, EmptyMetadataDto>, ApiErrorResponseDto>(await res.json());
+      }
+
+      return ok<ApiSuccessResponseDto<TDto, EmptyMetadataDto>, ApiErrorResponseDto>(await res.json());
+    } catch (err) {
+      console.error(err);
+
+      return fail<ApiSuccessResponseDto<TDto, EmptyMetadataDto>, ApiErrorResponseDto>({
+        error: {
+          code: ErrorCode.UnknownError,
+          message: 'Unknown error occurred while creating the record.',
+          metadata: {} as EmptyMetadataDto,
+        },
+      });
+    }
+  }
+
+  /**
+   * Updates an existing entity.
+   * @param id - The ID of the entity to update
+   * @param dto - Update request DTO
+   * @param {AbortSignal} [signal] - Optional cancellation signal
+   * @returns The updated entity DTO
+   */
+  public async update(id: TKey, dto: TDto, signal?: AbortSignal): Promise<ApiResponseDto<TDto, EmptyMetadataDto>> {
+    try {
+      const url = await apiInitializationService.getApiUrl(this.baseControllerPath, `/Update?id=${encodeURIComponent(String(id))}`);
+      const res = await this.httpService.request(url, {
+        method: 'PUT',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify(dto),
+        credentials: 'include',
+        signal,
+      });
+
+      if (!res.ok) {
+        return fail<ApiSuccessResponseDto<TDto, EmptyMetadataDto>, ApiErrorResponseDto>(await res.json());
+      }
+
+      return ok<ApiSuccessResponseDto<TDto, EmptyMetadataDto>, ApiErrorResponseDto>(await res.json());
+    } catch (err) {
+      console.error(err);
+
+      return fail<ApiSuccessResponseDto<TDto, EmptyMetadataDto>, ApiErrorResponseDto>({
+        error: {
+          code: ErrorCode.UnknownError,
+          message: `Unknown error occurred while updating the record with id ${id}`,
+          metadata: {} as EmptyMetadataDto,
+        },
+      });
+    }
+  }
+
+  /**
+   * Deletes an entity by ID.
+   * @param id - The ID of the entity to delete
+   * @param {AbortSignal} [signal] - Optional cancellation signal
+   */
+  public async delete(id: TKey, signal?: AbortSignal): Promise<ApiResponseDto<undefined, EmptyMetadataDto>> {
+    try {
+      const url = await apiInitializationService.getApiUrl(this.baseControllerPath, `/Delete?id=${encodeURIComponent(String(id))}`);
+      const res = await this.httpService.request(url, {
+        method: 'DELETE',
+        credentials: 'include',
+        signal,
+      });
+
+      if (!res.ok) {
+        return fail<ApiSuccessResponseDto<undefined, EmptyMetadataDto>, ApiErrorResponseDto>(await res.json());
+      }
+
+      return ok<ApiSuccessResponseDto<undefined, EmptyMetadataDto>, ApiErrorResponseDto>(await res.json());
+    } catch (err) {
+      console.error(err);
+
+      return fail<ApiSuccessResponseDto<undefined, EmptyMetadataDto>, ApiErrorResponseDto>({
+        error: {
+          code: ErrorCode.UnknownError,
+          message: `Unknown error occurred while deleting the record with id ${id}`,
+          metadata: {} as EmptyMetadataDto,
+        },
+      });
+    }
+  }
+}

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> = {
+  settings: 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.settings;
+    } catch (error) {
+      console.error('Failed to get app config', error);
+      this.appConfig = undefined;
+    }
+  }
+
+  // #endregion
+}
+
+/**
+ * Singleton instance of ApiInitializationService
+ */
+export const apiInitializationService = new ApiInitializationService();