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

package/README.md

@@ -0,0 +1,256 @@
+# Cornerstone TypeScript WebClient Services
+
+This project includes services for easy communication from a Cornerstone client application to the Cornerstone API.
+
+## Getting started
+
+1. Install dependencies:
+
+```bash
+pnpm install
+```
+
+2. Build the project:
+
+```bash
+pnpm run build
+```
+
+3. Run Client demo HTTP server:
+
+```bash
+pnpm run demo
+```
+
+4. Open
+
+http://localhost:3000
+
+## API reference
+
+### API Initialization service
+
+This service provides a centralized way to initialize API configuration for a Cornerstone client application, including automatic API base URL detection and shared settings fetching:
+
+```ts
+import { ApiInitializationService } from '@intellegens/cornerstone-client';
+const apiInitializationService = new ApiInitializationService();
+await apiInitializationService.initializeAsync();
+```
+
+or use the existing singleton instance
+
+```ts
+import { apiInitializationService } from '@intellegens/cornerstone-client';
+await apiInitializationService.initializeAsync();
+```
+
+#### Key Features
+
+- **API Base URL Detection**: Automatically detects the API base URL through multiple methods
+- **Shared Settings Management**: Fetches and caches server-side configuration that's safe to share with clients
+- **HTTP Service Configuration**: Allows customization of the global HTTP service
+- **Automatic Initialization**: Handles both API detection and configuration fetching in a single call
+
+It also provides a way of customizing global defaults for Cornerstone client application:
+
+- `httpService` Configures a default HTTP Service to be used across the application, unless specified otherwise (See [HTTP Service Abstraction](#http-service-abstraction))
+
+```ts
+import { apiInitializationService, FetchHttpService } from '@intellegens/cornerstone-client';
+await apiInitializationService.initializeAsync({
+  httpService: new FetchHttpService(),
+});
+```
+
+#### API base URL detection
+
+Base API URL is detected by checking the `CORNERSTONE-API-BASEURL` response header and the `./websettings.json` file.
+
+- First, Cornerstone client checks the response headers of the current URL for the `CORNERSTONE-API-BASEURL` header.
+- If the header is not found, Cornerstone client attempts to load the `websettings.json` file and looks for an `api` field.
+- If no API base URL is found, Cornerstone client defaults to `undefined`.
+
+Before, or after the base API URL has been detected, you can get any API endpoint URL by calling:
+
+```ts
+const fetchUrl = `${await apiInitializationService.getApiUrlAsync('/my/endpoint')}`;
+```
+
+#### Shared Settings Access
+
+After initialization, you can access server-side configuration that's been shared with the client:
+
+```ts
+// Get cached app settings
+const settings = apiInitializationService.appConfig;
+```
+
+The app shared settings contain only client-safe configuration properties as defined by the server-side `AppSettingsShared` class, plus any additional runtime settings. Sensitive server-only settings are never exposed to clients.
+
+### ~~System Service~~ (Deprecated)
+
+> **Note**: The SystemService has been deprecated and its functionality has been integrated into the ApiInitializationService. Use `apiInitializationService.appConfig` instead of the SystemService methods.
+
+The System Service functionality is now handled directly by the ApiInitializationService during initialization. The service automatically fetches and caches shared configuration settings from the server's `/api/system/init` endpoint.
+
+#### Migration Guide
+
+**Old approach:**
+
+```ts
+import { systemService } from '@intellegens/cornerstone-client';
+
+// Initialize and fetch shared settings
+await systemService.initializeAsync();
+
+// Get cached settings
+const settings = systemService.getInitializationInfo();
+```
+
+**New approach:**
+
+```ts
+import { apiInitializationService } from '@intellegens/cornerstone-client';
+
+// Initialize (automatically fetches shared settings)
+await apiInitializationService.initializeAsync();
+
+// Get cached settings
+const settings = apiInitializationService.appConfig;
+```
+
+#### Key Features
+
+- **Automatic Integration**: Settings are fetched during API initialization
+- **Type Safety**: Supports generic typed settings interfaces
+- **Error Handling**: Gracefully handles network errors and returns undefined for failed requests
+- **Server Integration**: Works seamlessly with Cornerstone server-side configuration system
+
+### HTTP Service Abstraction
+
+The Cornerstone client provides a flexible HTTP service abstraction that allows you to use different HTTP libraries (Fetch API, Angular HttpClient) with the same API clients. This abstraction provides consistent behavior across different HTTP implementations while maintaining framework independence.
+
+#### Key Features
+
+- **Pluggable HTTP implementations** - Switch between Fetch and Angular HttpClient
+- **Consistent interface** - All HTTP services implement the same `IHttpService` interface
+- **Framework agnostic** - Use the same API clients in React, Angular, Vue, or any other framework
+- **Easy testing** - Mock HTTP requests easily for unit testing
+- **Runtime switching** - Change HTTP service implementations at runtime
+
+#### Quick Example
+
+```ts
+import { ApiReadControllerClient, FetchHttpService } from '@intellegens/cornerstone-client';
+
+// Using default Fetch implementation
+const client = new ApiReadControllerClient('/api/users');
+```
+
+For detailed documentation, examples, and advanced usage, see: [HTTP Service Documentation](./src/services/api/HttpService/README.md)
+
+### Auth Service
+
+This service provides authentication methods for managing user sessions in a Cornerstone client application.
+
+```ts
+import { AuthService } from './index.js';
+const authService = new AuthService();
+await authService.initialize();
+const user = authService.user;
+```
+
+#### Methods
+
+##### Who Am I
+
+```ts
+authService.whoAmI(): Promise<UserDto | undefined>
+```
+
+This method checks the current session and returns the UserDto object for the logged-in user. If no user is logged in, it returns undefined.
+
+##### Sign in
+
+```ts
+authService.signin(username: string, password: string): Promise<UserDto | undefined>
+```
+
+This method logs the user in by sending the provided username and password to the API. If the login is successful, it returns the authenticated UserDto object.
+
+##### Sign out
+
+```ts
+authService.logout(): Promise<UserDto | undefined>
+```
+
+This method logs the user out by sending a request to the API to end the session. It returns undefined if the logout is successful
+
+### CollectionViewAdapter
+
+TS class for handling sorting, filtering and paginating collections
+
+Note that the collection is fetched on a page by page basis. Page size determines the number of items returned for display.
+
+```typescript
+ ngOnInit() {
+    this._adapter = new CollectionViewAdapter<number, ExampleDto>(
+      'Example', // controller name
+      (isLoading, data) => {
+        // data: ExampleDto[]
+        // handle as needed
+      },
+      this._options, // pass along initial options CollectionViewAdapterOptions<TDto>
+    );
+  }
+```
+
+### utils
+
+Helper functions for constructing `ReadSelectedSearchDefinitionDto`.
+
+Example usage:
+
+```typescript
+const search = condition(
+  ReadSelectedLogicalOperator.Or,
+  { path: 'clients', operator: ReadSelectedComparisonOperator.Contains, value: 'search-term', valueType: ReadSelectedPropertyType.String },
+  { path: 'suppliers', operator: ReadSelectedComparisonOperator.Contains, value: 'search-term', valueType: ReadSelectedPropertyType.String },
+  { path: 'facilities', operator: ReadSelectedComparisonOperator.Contains, value: 'search-term', valueType: ReadSelectedPropertyType.String },
+);
+
+const dateRange = condition(
+  ReadSelectedLogicalOperator.And,
+  {
+    path: 'createdDate',
+    operator: ReadSelectedComparisonOperator.GreaterOrEqual,
+    value: new Date('2024-01-01'),
+    valueType: ReadSelectedPropertyType.DateTime,
+  },
+  {
+    path: 'createdDate',
+    operator: ReadSelectedComparisonOperator.LessOrEqual,
+    value: new Date('2024-12-31'),
+    valueType: ReadSelectedPropertyType.DateTime,
+  },
+);
+
+const definition = and(search, dateRange);
+```
+
+Functions `searchTerm` and `dateInterval` have been prepared to simplify usage for these common needs:
+
+```typescript
+const definition = and(
+  searchTerm('search-term', textSearchablePaths, numericSearchablePaths),
+  dateInterval(
+    from,
+    to,
+    ReadSelectedComparisonOperator.GreaterOrEqual,
+    ReadSelectedComparisonOperator.LessOrEqual,
+    ReadSelectedPropertyType.DateTimeOffset,
+    'exampleColumnName',
+  ),
+);
+```

package/demo/index.ts

@@ -0,0 +1,29 @@
+import express from 'express';
+import { createProxyMiddleware } from 'http-proxy-middleware';
+
+const HTTP_PORT = 3000;
+const API_PORT = 5235;
+
+const app = express();
+
+// config proxy for api calls
+app.use(
+  createProxyMiddleware({
+    pathFilter: '/api',
+    target: `http://localhost:${API_PORT}`,
+    changeOrigin: true,
+    logger: console,
+  }),
+);
+app.use(
+  express.static('./demo/public_html', {
+    setHeaders: function (res) {
+      if (Math.random() > 0.5) res.set('CORNERSTONE-API-BASEURL', `/api`);
+    },
+  }),
+);
+app.listen(HTTP_PORT, () => {
+  console.log();
+  console.log(`Demo App listening on: http://localhost:${HTTP_PORT}`);
+  console.log(`... API requests proxied to: http://localhost:${API_PORT}/api`);
+});

package/demo/public_html/index.html

@@ -0,0 +1,106 @@
+<!doctype html>
+<html lang="en">
+  <!-- HEAD -->
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Cornerstone Test Client</title>
+
+    <!-- General styling -->
+    <style>
+      html {
+        font-family: monospace;
+      }
+      .comment {
+        color: gray;
+      }
+    </style>
+  </head>
+
+  <!-- BODY --> 
+  <body>
+    <!-- API base URL detection demo template-->
+    <div>
+      <h2>API Detection Demo</h2>
+      <pre class="comment">
+        This demo will randomly initialize client configuration from one of:
+        - Response CORNERSTONE-API-BASEURL header
+        - A settings file: websettings.json
+      </pre>
+      
+      <span>Detected API base URL as: <strong id="api-base-url"></strong> via method <strong id="api-base-url-method"></strong></span>
+      </pre>
+    </div>
+    <!-- API base URL detection demo JS -->
+    <script type="module">
+      import { apiService } from './index.js';
+      document.getElementById('api-base-url').innerText = await apiService._getApiBaseUrl();
+      document.getElementById('api-base-url-method').innerText = apiService._apiBaseUrlDetectionMethod;
+    </script>
+
+    <!-- Auth demo template -->
+    <hr />
+    <div>
+      <h2>Auth Demo</h2>
+      <pre class="comment">
+        This demo will allow you to interact with the authentication API by:
+        - Checking the authentication status
+        - Authenticating with a username and password
+        - Deauthenticating
+      </pre>
+      <div>
+        <div>
+          Check your current authentication status:
+          <button id="whoAmI">Who am I?</button>
+        </div>
+        <div>
+          Authenticate using your credentials: 
+          <input type="text" name="username" id="username" placeholder="Username" value="admin@test.com" />
+          <input type="password" name="password" id="password" placeholder="Password" value="Test1234!" />
+          <button id="signin">Sign in</button>
+        </div>
+        <div>
+          Deauthenticate:
+          <button id="signout">Sign out</button>
+        </div>
+      </div>
+      <div id="authentication-info" style="margin-top: 10px"></div>
+    </div>
+    <!-- API base URL detection demo JS -->
+    <script type="module">
+      import { authService } from './index.js';
+      // whoAmI demo functionality
+      document.getElementById('whoAmI').addEventListener('click', async () => {
+        const authInfoEl = document.getElementById('authentication-info');
+        try {
+          const user = await authService.whoAmI();
+          authInfoEl.innerText = `You are authenticated as: ${JSON.stringify(user)}`;
+        } catch (err) {
+          authInfoEl.innerText = 'You are not authenticated!';
+        }
+      });
+      // login demo functionality
+      document.getElementById('signin').addEventListener('click', async () => {
+        const authInfoEl = document.getElementById('authentication-info');
+        const username = document.getElementById('username').value;
+        const password = document.getElementById('password').value;
+        try {
+          const user = await authService.signin(username, password);
+          authInfoEl.innerText = `Signed in in successfully as: ${JSON.stringify(user)}`;
+        } catch (err) {
+          authInfoEl.innerText = `Failed signing in: ${err.message}`;
+        }
+      });
+      // logout demo functionality
+      document.getElementById('signout').addEventListener('click', async () => {
+        const authInfoEl = document.getElementById('authentication-info');
+        try {
+          await authService.signout();
+          authInfoEl.innerText = `Successfully signed out`;
+        } catch (err) {
+          authInfoEl.innerText = `Failed signing out: ${err.message}`;
+        }
+      });
+    </script>
+  </body>
+</html>

package/demo/public_html/websettings.json

@@ -0,0 +1,3 @@
+{
+  "api": "/api"
+}

package/dist/adapters/CollectionViewAdapter/index.d.ts

@@ -0,0 +1,198 @@
+import { IIdentifiable, PropertyPathDto, ReadSelectedOrderingDirection, ReadSelectedSearchDefinitionDto } from '../../data';
+/**
+ * Used with CollectionViewAdapter, a simplified configuration object for handling reading/writing from/to ReadSelectedDefinitionDto.
+ *
+ * @template TDto The type of the collection being sorted/filtered/paginated.
+ *
+ * @property {object} pagination - Pagination configuration
+ * @property {boolean} pagination.useTotalItemCount - Used for last page related logic of the paginator.
+ * Set to true if the total count for the collection is available; false assumes the last page is not known
+ * and adapts the pagination display accordingly.
+ * @property {number} [pagination.pageSize] - Number of items/rows to be fetched for the current page.
+ * @property {number} [pagination.pageNumber] - Current page index (skips fetching `(n-1) * pageSize` items/rows).
+ *
+ * @property {object} ordering - Ordering configuration
+ * @property {string[]} [ordering.orderByPath] - Array of column/property names that are sortable.
+ * @property {ReadSelectedOrderingDirection} [ordering.orderDirection] - Enum for ascending/descending sort order.
+ *
+ * @property {object} search - Search configuration
+ * @property {(keyof TDto)[]} [search.textSearchableProperties] - Array of column/property names that are searchable where the value type is string.
+ * @property {(keyof TDto)[]} [search.numericSearchableProperties] - Array of column/property names that are searchable where the value type is number.
+ * @property {ReadSelectedSearchDefinitionDto<TDto>} [search.searchDefinition] - The search definition by which the collection will be filtered.
+ */
+export type CollectionViewAdapterOptions<TDto> = {
+    pagination: {
+        useTotalItemCount: boolean;
+        pageSize?: number;
+        pageNumber?: number;
+    };
+    ordering: {
+        maxActiveOrderingColumns: number;
+        orderByPaths: {
+            orderByPath: PropertyPathDto;
+            orderDirection: ReadSelectedOrderingDirection;
+        }[];
+    };
+    search: {
+        textSearchableProperties?: (keyof TDto)[];
+        numericSearchableProperties?: (keyof TDto)[];
+        searchDefinition?: ReadSelectedSearchDefinitionDto<TDto>;
+    };
+};
+/**
+ * TS class for handling ordering, filtering and paginating collections
+ *
+ * @param controllerName - specify the target endpoint controller name.
+ * @param dataChangedCallback - Function invoked whenever the data changes.
+ * Receives a loading state flag and the updated data collection.
+ * @param options - Optional settings of type CollectionViewAdapter to customize the behavior of the adapter.
+ */
+export declare class CollectionViewAdapter<TKey, TDto extends IIdentifiable<TKey>, TDetailsDto extends IIdentifiable<TKey>> {
+    private _readClient;
+    private _isLoading;
+    private _pageData;
+    private _selectedItems;
+    private _defaultOptions;
+    private _initialOptions;
+    private _currentOptions;
+    constructor(controllerName: string, dataChangedCallback: (isLoading: boolean, data: TDto[] | undefined, error: string | undefined) => void, options?: CollectionViewAdapterOptions<TDto>);
+    /**
+     * Allows for adding any filtering criteria. Label is required to distinguish custom search categories (e.g. searchTerm, dateRange, anyCustom ...)
+     */
+    setSearchDefinition(searchDefinition: ReadSelectedSearchDefinitionDto<TDto>): Promise<TDto[]>;
+    /**
+     * Compares two PropertyPathDto arrays for equality
+     */
+    private _arePropertyPathsEqual;
+    /**
+     * Public method for ordering the collection by property path / column name.
+     *
+     * @param propertyPath - must match camel-cased property/column name being sorted
+     * @param orderDirection - use `ReadSelectedOrderingDirection` enum choices
+     */
+    setOrdering(propertyPath: PropertyPathDto, orderDirection: ReadSelectedOrderingDirection): Promise<TDto[]>;
+    /**
+     * Returns the property name of the current columns/properties on which ordering is applied, along with the `ReadSelectedOrderingDirection` direction
+     */
+    getCurrentOrdering(): {
+        orderByPath: PropertyPathDto;
+        orderDirection: ReadSelectedOrderingDirection;
+    }[];
+    /**
+     * Returns the current page's page number
+     */
+    get currentPage(): number | undefined;
+    /**
+     * Sets the current page to `pageNumber` and triggers data re-fetch
+     *
+     * @param pageNumber
+     */
+    jumpToPage(pageNumber: number): Promise<TDto[]>;
+    /**
+     * Returns the currently set page size value
+     */
+    get pageSize(): number | undefined;
+    /**
+     * Page size dictates the number of items or rows being fetched in a single API call
+     *
+     * @param pageSize
+     */
+    setPageSize(pageSize: number): Promise<TDto[]>;
+    /**
+     * Refreshes the data by re-fetching the current page
+     */
+    refreshData(): Promise<TDto[]>;
+    private _totalItemCount;
+    /**
+     * Returns the total count value of the collection.
+     *
+     * If `CollectionViewAdapterOptions` has set `pagination.useTotalItemCount` to `true`, the API will return this value along with the collection and it will be set automatically.
+     * Else this adapter will attempt to dynamically calculate this value via `_calculateTotal()`.
+     */
+    get totalItemCount(): number;
+    /**
+     * Callback function invoked whenever data changes.
+     * Receives a loading state flag and the updated data collection.
+     */
+    private readonly _dataChangedCallback;
+    /**
+     * Timeout reference used to debounce calls to `_fetchCurrentPageData`.
+     */
+    private _fetchCurrentPageDataTimeout?;
+    /**
+     * Queue of pending promises waiting for `_fetchCurrentPageData` to resolve or reject.
+     */
+    private _fetchCurrentPageDataPromises;
+    /**
+     * Tracks the current in-flight request controller to allow cancellation when a new fetch starts.
+     */
+    private _currentAbortController?;
+    /**
+     * Fetches the current page of data with debouncing support.
+     * Consolidates multiple concurrent calls into a single execution,
+     * resolving all queued promises with the same result.
+     *
+     * @returns A promise resolving to the fetched page of data.
+     */
+    private _fetchCurrentPageData;
+    /**
+     * Executes the actual data fetch operation after debounce delay.
+     * Updates the loading state, triggers data change callbacks,
+     * and handles total item count calculation if pagination is enabled.
+     *
+     * @returns A promise resolving to the fetched page of data.
+     */
+    private _fetchCurrentPageDataDebounced;
+    /**
+     * Takes current `CollectionViewAdapterOptions` and parses to `ReadSelectedDefinitionDto` which the cornerstone API expects.
+     *
+     * @returns - `ReadSelectedDefinitionDto` object
+     */
+    private _parseOptionsToDefinition;
+    /**
+     * Calculates the total item count given pagination inputs.
+     *
+     * For example, with 10 items per page, on page 2 with 3 items, total = 13.
+     * If the total cannot be inferred (e.g., a full page is returned), the previous total is returned unchanged.
+     *
+     * @param pageSize - Number of items per page
+     * @param currentPageNumber - Current page number (1-based)
+     * @param itemsOnCurrentPageCount - Number of items in the fetched page
+     * @param previousTotal - Previous known total to preserve when indeterminate
+     * @returns The computed total item count
+     */
+    private _calculateTotal;
+    /**
+     * Selects or deselects an item based on its ID.
+     * @param item - The item to select or deselect.
+     */
+    toggleItemSelected(item: TDto): void;
+    clearSelectedItems(): void;
+    selectItems(item: TDto): void;
+    deselectItem(item: TDto): void;
+    /**
+     * Returns the currently selected items
+     */
+    get selectedItems(): TDto[];
+    /**
+     * Checks if an item is currently selected
+     * @param item - The item to check
+     */
+    isItemSelected(item: TDto): boolean;
+    /**
+     * Selects all items on the current page
+     */
+    selectAllItemsOnCurrentPage(): void;
+    /**
+     * Deselects all items on the current page
+     */
+    deselectAllItemsOnCurrentPage(): void;
+    /**
+     * Checks if all items on the current page are selected
+     */
+    areAllItemsOnCurrentPageSelected(): boolean;
+    /**
+     * Checks if some (but not all) items on the current page are selected
+     */
+    areSomeItemsOnCurrentPageSelected(): boolean;
+}

package/dist/adapters/CollectionViewAdapter/index.integration.test.d.ts

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