@intellegens/cornerstone-client 0.0.9999-alpha-41 → 0.0.9999-alpha-43

package/dist/data/auth/dto/role-with-claims-dto.d.ts

@@ -0,0 +1,5 @@
+import { ClaimDto } from '../..';
+export type RoleWithClaimsDto = {
+    name: string;
+    claims: ClaimDto[];
+};

package/dist/data/auth/dto/role-with-claims-dto.js

@@ -0,0 +1 @@
+export {};

package/dist/data/auth/dto/sign-in-request-dto.d.ts

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

package/dist/data/auth/dto/sign-in-request-dto.js

@@ -0,0 +1 @@
+export {};

package/dist/data/auth/dto/tokens-dto.d.ts

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

package/dist/data/auth/dto/tokens-dto.js

@@ -0,0 +1 @@
+export {};

package/dist/data/auth/dto/user-dto.d.ts

@@ -0,0 +1,16 @@
+import { ClaimDto, IIdentifiable, RoleWithClaimsDto } from '../..';
+/**
+ * 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 {RoleWithClaimsDto[]} roles The roles (with their claims) associated with the user.
+ * @param {ClaimDto[]} userClaims The claims associated with the user.
+ */
+export type UserDto<TKey> = IIdentifiable<TKey> & {
+    email: string;
+    roles: RoleWithClaimsDto[];
+    userClaims: ClaimDto[];
+};

package/dist/data/auth/dto/user-dto.js

@@ -0,0 +1 @@
+export {};

package/dist/data/auth/dto/user-info-dto.d.ts

@@ -0,0 +1,14 @@
+import { UserDto } from '../..';
+/**
+ * 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/dist/data/auth/dto/user-info-dto.js

@@ -0,0 +1 @@
+export {};

package/dist/services/api/api-crud-controller-client.d.ts

@@ -0,0 +1,62 @@
+import { ApiReadControllerClient, IApiReadControllerClient, IHttpService } from '../../services';
+import { ApiResponseDto, EmptyMetadataDto, IIdentifiable } from '../../data';
+/**
+ * Client for creating a new entity in a CRUD controller.
+ */
+export interface ICreateClient<TKey, TResultDto extends IIdentifiable<TKey>, TInsertRequestDto> {
+    create(dto: TInsertRequestDto, signal?: AbortSignal): Promise<ApiResponseDto<TResultDto, EmptyMetadataDto>>;
+}
+/**
+ * Client for updating an existing entity in a CRUD controller.
+ */
+export interface IUpdateClient<TKey, TResultDto extends IIdentifiable<TKey>, TUpdateRequestDto> {
+    update(id: TKey, dto: TUpdateRequestDto, signal?: AbortSignal): Promise<ApiResponseDto<TResultDto, EmptyMetadataDto>>;
+}
+/**
+ * Client for deleting an entity in a CRUD controller.
+ */
+export interface IDeleteClient<TKey> {
+    delete(id: TKey, signal?: AbortSignal): Promise<ApiResponseDto<undefined, EmptyMetadataDto>>;
+}
+/**
+ * Client for managing CRUD operations on a controller.
+ */
+export interface IApiCrudControllerClient<TKey, TResultDto extends IIdentifiable<TKey>, TSingleResultDto extends IIdentifiable<TKey>, TInsertRequestDto, TUpdateRequestDto> extends IApiReadControllerClient<TKey, TResultDto, TSingleResultDto>, ICreateClient<TKey, TSingleResultDto, TInsertRequestDto>, IUpdateClient<TKey, TSingleResultDto, TUpdateRequestDto>, IDeleteClient<TKey> {
+}
+/**
+ * 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 declare class ApiCrudControllerClient<TKey, TResultDto extends IIdentifiable<TKey>, TSingleResultDto extends IIdentifiable<TKey>, TInsertRequestDto, TUpdateRequestDto> extends ApiReadControllerClient<TKey, TResultDto, TSingleResultDto> implements IApiCrudControllerClient<TKey, TResultDto, TSingleResultDto, TInsertRequestDto, TUpdateRequestDto> {
+    /**
+     * Constructor
+     * @param baseControllerPath Base path to API controller
+     * @param httpService HTTP service implementation to use for requests
+     */
+    constructor(baseControllerPath: string, httpService?: IHttpService);
+    /**
+     * Creates a new entity.
+     * @param dto - Insert request DTO
+     * @param {AbortSignal} [signal] - Optional cancellation signal
+     * @returns The created entity DTO
+     */
+    create(dto: TInsertRequestDto, signal?: AbortSignal): Promise<ApiResponseDto<TSingleResultDto, 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
+     */
+    update(id: TKey, dto: TUpdateRequestDto, signal?: AbortSignal): Promise<ApiResponseDto<TSingleResultDto, EmptyMetadataDto>>;
+    /**
+     * Deletes an entity by ID.
+     * @param id - The ID of the entity to delete
+     * @param {AbortSignal} [signal] - Optional cancellation signal
+     */
+    delete(id: TKey, signal?: AbortSignal): Promise<ApiResponseDto<undefined, EmptyMetadataDto>>;
+}

package/dist/services/api/api-crud-controller-client.integration.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/services/api/api-crud-controller-client.integration.test.js

@@ -0,0 +1,34 @@
+import { beforeEach, describe, expect, it } from 'vitest';
+import { ApiCrudControllerClient } from '.';
+import { FetchHttpService } from '..';
+describe('ApiCrudControllerClient', () => {
+    let client;
+    let fetchService;
+    const testId = 100;
+    beforeEach(() => {
+        fetchService = new FetchHttpService();
+        client = new ApiCrudControllerClient('/VehiclesSlim', fetchService);
+    });
+    it('should use injected HTTP service for create', async () => {
+        const newVehicle = { id: testId, brand: 'New Brand', model: 'New Model' };
+        const result = (await client.create(newVehicle));
+        expect(result.ok).toBe(true);
+        expect(result.result).toBeDefined();
+        expect(result.result.id).toBe(newVehicle.id);
+        expect(result.result.brand).toBe(newVehicle.brand);
+        expect(result.result.model).toBe(newVehicle.model);
+    });
+    it('should use injected HTTP service for update', async () => {
+        const updateVehicle = { id: testId, brand: 'Updated Brand', model: 'Updated Model' };
+        const result = (await client.update(testId, updateVehicle));
+        expect(result.ok).toBe(true);
+        expect(result.result).toBeDefined();
+        expect(result.result.id).toBe(updateVehicle.id);
+        expect(result.result.brand).toBe(updateVehicle.brand);
+        expect(result.result.model).toBe(updateVehicle.model);
+    });
+    it('should use injected HTTP service for delete', async () => {
+        const result = await client.delete(testId);
+        expect(result.ok).toBe(true);
+    });
+});

package/dist/services/api/api-crud-controller-client.js

@@ -0,0 +1,133 @@
+import { apiInitializationService, ApiReadControllerClient } from '../../services';
+import { ErrorCode } from '../../data';
+import { fail, ok } from '../../utils/result';
+function isAbortError(err) {
+    return err instanceof DOMException && err.name === 'AbortError';
+}
+/**
+ * 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 extends ApiReadControllerClient {
+    /**
+     * Constructor
+     * @param baseControllerPath Base path to API controller
+     * @param httpService HTTP service implementation to use for requests
+     */
+    constructor(baseControllerPath, httpService) {
+        super(baseControllerPath, httpService);
+    }
+    /**
+     * Creates a new entity.
+     * @param dto - Insert request DTO
+     * @param {AbortSignal} [signal] - Optional cancellation signal
+     * @returns The created entity DTO
+     */
+    async create(dto, signal) {
+        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(await res.json());
+            }
+            return ok(await res.json());
+        }
+        catch (err) {
+            if (isAbortError(err)) {
+                return fail({
+                    error: { code: ErrorCode.Aborted, message: 'Request was aborted', metadata: {} },
+                });
+            }
+            console.error(err);
+            return fail({
+                error: {
+                    code: ErrorCode.UnknownError,
+                    message: 'Unknown error occurred while creating the record.',
+                    metadata: {},
+                },
+            });
+        }
+    }
+    /**
+     * 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
+     */
+    async update(id, dto, signal) {
+        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(await res.json());
+            }
+            return ok(await res.json());
+        }
+        catch (err) {
+            if (isAbortError(err)) {
+                return fail({
+                    error: { code: ErrorCode.Aborted, message: 'Request was aborted', metadata: {} },
+                });
+            }
+            console.error(err);
+            return fail({
+                error: {
+                    code: ErrorCode.UnknownError,
+                    message: `Unknown error occurred while updating the record with id ${id}`,
+                    metadata: {},
+                },
+            });
+        }
+    }
+    /**
+     * Deletes an entity by ID.
+     * @param id - The ID of the entity to delete
+     * @param {AbortSignal} [signal] - Optional cancellation signal
+     */
+    async delete(id, signal) {
+        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(await res.json());
+            }
+            return ok(await res.json());
+        }
+        catch (err) {
+            if (isAbortError(err)) {
+                return fail({
+                    error: { code: ErrorCode.Aborted, message: 'Request was aborted', metadata: {} },
+                });
+            }
+            console.error(err);
+            return fail({
+                error: {
+                    code: ErrorCode.UnknownError,
+                    message: `Unknown error occurred while deleting the record with id ${id}`,
+                    metadata: {},
+                },
+            });
+        }
+    }
+}

package/dist/services/api/api-initialization-service.d.ts

@@ -0,0 +1,106 @@
+import { IHttpService } from '../../services';
+/**
+ * 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;
+};
+/**
+ * Central API configuration service, fetches and exposes Cornerstone API configuration
+ *
+ * @export
+ * @class ApiInitializationService
+ */
+export declare 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.
+     */
+    _apiBaseUrlDetected: boolean;
+    /**
+     * 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.
+     */
+    _apiBaseUrlDetectionMethod: string | 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.
+     */
+    _apiBaseUrl: string | undefined;
+    /**
+     * 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.
+     */
+    _apiBaseError: Error | undefined;
+    appConfig?: ISharedSettings | undefined;
+    private _httpService;
+    private _apiBaseUrlPromise;
+    /**
+     * 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.
+     */
+    initialize({ httpService, signal, }?: {
+        httpService?: IHttpService;
+        signal?: AbortSignal;
+    }): Promise<void>;
+    /**
+     * Gets configured HTTP service
+     * @returns
+     */
+    _getHttpService(): IHttpService;
+    /**
+     * 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
+     */
+    _getApiBaseUrl(signal?: AbortSignal): Promise<string | undefined>;
+    /**
+     * 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
+     */
+    getApiUrl(...relativeEndpointPathSections: string[]): Promise<string>;
+    /**
+     * Removes starting '/' character
+     * @param str String to remove the starting '/' character from
+     * @returns String with starting '/' character  removed
+     */
+    private removeStartsWithSlashChar;
+    /**
+     * Removes ending '/' character
+     * @param str String to remove the ending '/' character from
+     * @returns String with ending '/' character  removed
+     */
+    private removeEndsWithSlashChar;
+    /**
+     * Fetches initialization info (shared settings) from the server
+     * @returns Promise that resolves to shared settings or undefined if the request fails
+     */
+    private _getAppConfig;
+}
+/**
+ * Singleton instance of ApiInitializationService
+ */
+export declare const apiInitializationService: ApiInitializationService;
+export {};

package/dist/services/api/api-initialization-service.js

@@ -0,0 +1,207 @@
+import { fail, ok } from '../../utils';
+import { defaultHttpService } from '../../services';
+/**
+ * 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.
+     */
+    _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.
+     */
+    _apiBaseUrlDetectionMethod = 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.
+     */
+    _apiBaseUrl = 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.
+     */
+    _apiBaseError = undefined;
+    // #region config App
+    appConfig;
+    _httpService = defaultHttpService;
+    _apiBaseUrlPromise = 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.
+     */
+    async initialize({ httpService, signal, } = {}) {
+        // 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
+     */
+    _getHttpService() {
+        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
+     */
+    async _getApiBaseUrl(signal) {
+        // 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((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 = 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 = 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
+     */
+    async getApiUrl(...relativeEndpointPathSections) {
+        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
+     */
+    removeStartsWithSlashChar(str) {
+        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
+     */
+    removeEndsWithSlashChar(str) {
+        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
+     */
+    async _getAppConfig() {
+        try {
+            const response = await fetch(`${this._apiBaseUrl}/system/init`, { credentials: 'include' });
+            if (!response.ok) {
+                throw fail(await response.json());
+            }
+            const apiResponse = ok(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;
+        }
+    }
+}
+/**
+ * Singleton instance of ApiInitializationService
+ */
+export const apiInitializationService = new ApiInitializationService();