@genesislcap/foundation-comms 14.372.0 → 14.373.0

package/dist/foundation-comms.api.json

@@ -26550,6 +26550,92 @@
           ],
           "extendsTokenRanges": []
         },
+        {
+          "kind": "Interface",
+          "canonicalReference": "@genesislcap/foundation-comms!HttpError:interface",
+          "docComment": "/**\n * An error thrown when an HTTP request fails with a non-2xx status code.\n *\n * @public\n */\n",
+          "excerptTokens": [
+            {
+              "kind": "Content",
+              "text": "export interface HttpError extends "
+            },
+            {
+              "kind": "Reference",
+              "text": "Error",
+              "canonicalReference": "!Error:interface"
+            },
+            {
+              "kind": "Content",
+              "text": " "
+            }
+          ],
+          "fileUrlPath": "src/connect/http.ts",
+          "releaseTag": "Public",
+          "name": "HttpError",
+          "preserveMemberOrder": false,
+          "members": [
+            {
+              "kind": "PropertySignature",
+              "canonicalReference": "@genesislcap/foundation-comms!HttpError#message:member",
+              "docComment": "",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "message: "
+                },
+                {
+                  "kind": "Content",
+                  "text": "string"
+                },
+                {
+                  "kind": "Content",
+                  "text": ";"
+                }
+              ],
+              "isReadonly": false,
+              "isOptional": false,
+              "releaseTag": "Public",
+              "name": "message",
+              "propertyTypeTokenRange": {
+                "startIndex": 1,
+                "endIndex": 2
+              }
+            },
+            {
+              "kind": "PropertySignature",
+              "canonicalReference": "@genesislcap/foundation-comms!HttpError#status:member",
+              "docComment": "",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "status: "
+                },
+                {
+                  "kind": "Content",
+                  "text": "number"
+                },
+                {
+                  "kind": "Content",
+                  "text": ";"
+                }
+              ],
+              "isReadonly": false,
+              "isOptional": false,
+              "releaseTag": "Public",
+              "name": "status",
+              "propertyTypeTokenRange": {
+                "startIndex": 1,
+                "endIndex": 2
+              }
+            }
+          ],
+          "extendsTokenRanges": [
+            {
+              "startIndex": 1,
+              "endIndex": 2
+            }
+          ]
+        },
         {
           "kind": "Interface",
           "canonicalReference": "@genesislcap/foundation-comms!HttpRequestInit:interface",
@@ -31739,6 +31825,51 @@
           ],
           "name": "normaliseCriteria"
         },
+        {
+          "kind": "Function",
+          "canonicalReference": "@genesislcap/foundation-comms!onOtherTabReauthComplete:function(1)",
+          "docComment": "/**\n * Subscribes to storage events to detect when another tab has finished reauthenticating.\n *\n * @param callback - Called when the other tab finishes reauthentication\n *\n * @returns A function to unsubscribe from the storage events\n *\n * @public\n */\n",
+          "excerptTokens": [
+            {
+              "kind": "Content",
+              "text": "export declare function onOtherTabReauthComplete(callback: "
+            },
+            {
+              "kind": "Content",
+              "text": "() => void"
+            },
+            {
+              "kind": "Content",
+              "text": "): "
+            },
+            {
+              "kind": "Content",
+              "text": "() => void"
+            },
+            {
+              "kind": "Content",
+              "text": ";"
+            }
+          ],
+          "fileUrlPath": "src/connect/sessionRefresh.ts",
+          "returnTypeTokenRange": {
+            "startIndex": 3,
+            "endIndex": 4
+          },
+          "releaseTag": "Public",
+          "overloadIndex": 1,
+          "parameters": [
+            {
+              "parameterName": "callback",
+              "parameterTypeTokenRange": {
+                "startIndex": 1,
+                "endIndex": 2
+              },
+              "isOptional": false
+            }
+          ],
+          "name": "onOtherTabReauthComplete"
+        },
         {
           "kind": "TypeAlias",
           "canonicalReference": "@genesislcap/foundation-comms!PingMessage:type",
@@ -33756,6 +33887,107 @@
           ],
           "extendsTokenRanges": []
         },
+        {
+          "kind": "Enum",
+          "canonicalReference": "@genesislcap/foundation-comms!SessionRefreshResult:enum",
+          "docComment": "/**\n * Result of a session refresh attempt.\n *\n * @public\n */\n",
+          "excerptTokens": [
+            {
+              "kind": "Content",
+              "text": "export declare enum SessionRefreshResult "
+            }
+          ],
+          "fileUrlPath": "src/connect/sessionRefresh.ts",
+          "releaseTag": "Public",
+          "name": "SessionRefreshResult",
+          "preserveMemberOrder": false,
+          "members": [
+            {
+              "kind": "EnumMember",
+              "canonicalReference": "@genesislcap/foundation-comms!SessionRefreshResult.ALREADY_VALID:member",
+              "docComment": "/**\n * Session was already valid\n */\n",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "ALREADY_VALID = "
+                },
+                {
+                  "kind": "Content",
+                  "text": "\"ALREADY_VALID\""
+                }
+              ],
+              "initializerTokenRange": {
+                "startIndex": 1,
+                "endIndex": 2
+              },
+              "releaseTag": "Public",
+              "name": "ALREADY_VALID"
+            },
+            {
+              "kind": "EnumMember",
+              "canonicalReference": "@genesislcap/foundation-comms!SessionRefreshResult.FAILED:member",
+              "docComment": "/**\n * Refresh failed - page will reload\n */\n",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "FAILED = "
+                },
+                {
+                  "kind": "Content",
+                  "text": "\"FAILED\""
+                }
+              ],
+              "initializerTokenRange": {
+                "startIndex": 1,
+                "endIndex": 2
+              },
+              "releaseTag": "Public",
+              "name": "FAILED"
+            },
+            {
+              "kind": "EnumMember",
+              "canonicalReference": "@genesislcap/foundation-comms!SessionRefreshResult.HANDLED_BY_OTHER_TAB:member",
+              "docComment": "/**\n * Another tab is handling the refresh\n */\n",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "HANDLED_BY_OTHER_TAB = "
+                },
+                {
+                  "kind": "Content",
+                  "text": "\"HANDLED_BY_OTHER_TAB\""
+                }
+              ],
+              "initializerTokenRange": {
+                "startIndex": 1,
+                "endIndex": 2
+              },
+              "releaseTag": "Public",
+              "name": "HANDLED_BY_OTHER_TAB"
+            },
+            {
+              "kind": "EnumMember",
+              "canonicalReference": "@genesislcap/foundation-comms!SessionRefreshResult.SUCCESS:member",
+              "docComment": "/**\n * Session was successfully refreshed\n */\n",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "SUCCESS = "
+                },
+                {
+                  "kind": "Content",
+                  "text": "\"SUCCESS\""
+                }
+              ],
+              "initializerTokenRange": {
+                "startIndex": 1,
+                "endIndex": 2
+              },
+              "releaseTag": "Public",
+              "name": "SUCCESS"
+            }
+          ]
+        },
         {
           "kind": "Interface",
           "canonicalReference": "@genesislcap/foundation-comms!Socket:interface",
@@ -35713,6 +35945,65 @@
           ],
           "name": "toFieldMetadata"
         },
+        {
+          "kind": "Function",
+          "canonicalReference": "@genesislcap/foundation-comms!tryRefreshSession:function(1)",
+          "docComment": "/**\n * Attempts to refresh the session when authentication has expired. Uses a localStorage-based lock mechanism to prevent multiple tabs from trying to reauthenticate simultaneously.\n *\n * @param options - Optional configuration\n *\n * @param  - options.reloadOnFailure - Whether to reload the page if refresh fails (default: true)\n *\n * @returns The result of the refresh attempt\n *\n * @public\n */\n",
+          "excerptTokens": [
+            {
+              "kind": "Content",
+              "text": "export declare function tryRefreshSession(options?: "
+            },
+            {
+              "kind": "Content",
+              "text": "{\n    reloadOnFailure?: boolean;\n}"
+            },
+            {
+              "kind": "Content",
+              "text": "): "
+            },
+            {
+              "kind": "Reference",
+              "text": "Promise",
+              "canonicalReference": "!Promise:interface"
+            },
+            {
+              "kind": "Content",
+              "text": "<"
+            },
+            {
+              "kind": "Reference",
+              "text": "SessionRefreshResult",
+              "canonicalReference": "@genesislcap/foundation-comms!SessionRefreshResult:enum"
+            },
+            {
+              "kind": "Content",
+              "text": ">"
+            },
+            {
+              "kind": "Content",
+              "text": ";"
+            }
+          ],
+          "fileUrlPath": "src/connect/sessionRefresh.ts",
+          "returnTypeTokenRange": {
+            "startIndex": 3,
+            "endIndex": 7
+          },
+          "releaseTag": "Public",
+          "overloadIndex": 1,
+          "parameters": [
+            {
+              "parameterName": "options",
+              "parameterTypeTokenRange": {
+                "startIndex": 1,
+                "endIndex": 2
+              },
+              "isOptional": true
+            }
+          ],
+          "name": "tryRefreshSession"
+        },
         {
           "kind": "Variable",
           "canonicalReference": "@genesislcap/foundation-comms!TYPES_MAP:var",

package/dist/foundation-comms.d.ts

@@ -11,8 +11,8 @@ import { Listener } from '@genesislcap/foundation-utils';
 import { Logger } from '@genesislcap/foundation-logger';
 import type { LogLevel } from '@genesislcap/foundation-utils';
 import { Observable } from 'rxjs';
-import { Observer } from '@genesislcap/foundation-utils';
-import { Observer as Observer_2 } from 'rxjs';
+import { Observer } from 'rxjs';
+import { Observer as Observer_2 } from '@genesislcap/foundation-utils';
 import { SetUserProperties } from '@genesislcap/foundation-user';
 import { Subscription as SocketSubscription } from 'rxjs';
 import { Subject } from 'rxjs';
@@ -1868,11 +1868,11 @@ export declare const defaultConnectConfig: ConnectConfig;
  */
 export declare class DefaultConnectEvents implements ConnectEventsEmitter {
     /** @internal */
-    protected streamListeners: Observer<StreamEvent>;
+    protected streamListeners: Observer_2<StreamEvent>;
     /** @internal */
-    protected streamCompleteListeners: Observer<StreamCompleteEvent>;
+    protected streamCompleteListeners: Observer_2<StreamCompleteEvent>;
     /** @internal */
-    protected streamErrorListeners: Observer<StreamErrorEvent>;
+    protected streamErrorListeners: Observer_2<StreamErrorEvent>;
     /** {@inheritDoc ConnectEvents.addStreamListener} */
     addStreamListener(listener: Listener<StreamEvent>, complete: Listener<StreamCompleteEvent>, error: Listener<StreamErrorEvent>): () => void;
     /** {@inheritDoc ConnectEventsEmitter.onStreamEvent} */
@@ -1882,19 +1882,19 @@ export declare class DefaultConnectEvents implements ConnectEventsEmitter {
     /** {@inheritDoc ConnectEventsEmitter.onStreamCompleteEvent} */
     onStreamCompleteEvent(resourceName: string, stream: SocketObservable<any>): void;
     /** @internal */
-    protected commitListeners: Observer<CommitEvent>;
+    protected commitListeners: Observer_2<CommitEvent>;
     /** {@inheritDoc ConnectEvents.addCommitListener} */
     addCommitListener(listener: Listener<CommitEvent>): () => void;
     /** {@inheritDoc ConnectEventsEmitter.onStreamEvent} */
     onCommitEvent(eventName: string, message: Message): void;
     /** @internal */
-    protected metadataListeners: Observer<MetadataEvent>;
+    protected metadataListeners: Observer_2<MetadataEvent>;
     /** {@inheritDoc ConnectEvents.addMetadataListener} */
     addMetadataListener(listener: Listener<MetadataEvent>): () => void;
     /** {@inheritDoc ConnectEventsEmitter.onMetadataEvent} */
     onMetadataEvent(resourceName: string, message: Message<MessageDetails.MetaRequest>, error?: any): void;
     /** @internal */
-    protected commitResponseListeners: Observer<CommitResponseEvent>;
+    protected commitResponseListeners: Observer_2<CommitResponseEvent>;
     /** {@inheritDoc ConnectEvents.addCommitResponseListener} */
     addCommitResponseListener(listener: Listener<CommitResponseEvent>): () => void;
     /** {@inheritDoc ConnectEventsEmitter.onCommitResponseEvent} */
@@ -2153,13 +2153,39 @@ export declare class DefaultHttpConnect implements Connect {
     get isConnected(): boolean;
     set isConnected(value: boolean);
     private ongoingTurbo?;
+    /**
+     * Amount of time (in milliseconds) to wait when another tab is handling session reauthentication.
+     */
+    private static readonly REAUTH_WAIT_MS;
+    /**
+     * Amount of time (in milliseconds) to wait before retrying a failed request.
+     */
+    private static readonly RETRY_DELAY_MS;
+    /**
+     * Maximum number of retry attempts for failed requests.
+     */
+    private static readonly MAX_RETRIES;
     /**
      * A map of active messages in "polling" mode.
      * @remarks Equivalent to messaged being streamed in a WebSocket connection.
      * @internal
      */
     private streams;
+    /**
+     * Promise that tracks an ongoing session refresh to prevent concurrent refreshes from the same instance.
+     * @internal
+     */
+    private ongoingRefresh;
     constructor(http: Http, messageBuilder: MessageBuilder, session: Session, metaCache: MetaCache, serializer: JSONSerializer, config: HttpConnectConfig);
+    /**
+     * Attempts to refresh the session when a 401 Unauthorized error is received.
+     * Uses a lock mechanism to prevent multiple tabs from trying to reauthenticate simultaneously.
+     * Also prevents concurrent refresh attempts from the same instance by reusing an ongoing refresh.
+     * If another tab is handling the refresh, waits and retries once to verify the result.
+     * @internal
+     * @returns A Promise that resolves to `true` if session was refreshed successfully, `false` otherwise.
+     */
+    private handleSessionRefresh;
     /**
      * Checks if the host is available by sending a heartbeat ping message and waiting for the response.
      * @internal
@@ -2552,9 +2578,7 @@ export declare class DefaultSocket implements Socket {
      * more info here https://docs.genesis.global/docs/develop/server-capabilities/access-control/authentication/#sessiontimeoutmins
      */
     private handleExpiredSession;
-    private static REAUTH_ACTION_LOCK_KEY;
     private handleCookieBasedReauth;
-    private onStorageEvent;
     private updateSessionAndSubscriptions;
     private prepareHeartbeat;
     private reconnect;
@@ -3189,6 +3213,15 @@ declare interface HttpConnectConfig {
  */
 declare const HttpConnectConfig: InterfaceSymbol<HttpConnectConfig>;
 
+/**
+ * An error thrown when an HTTP request fails with a non-2xx status code.
+ * @public
+ */
+export declare interface HttpError extends Error {
+    status: number;
+    message: string;
+}
+
 /**
  * Configuration options for http connection.
  * @public
@@ -4119,6 +4152,14 @@ export declare const NetworkMonitorConfig: InterfaceSymbol<NetworkMonitorConfig>
  */
 export declare function normaliseCriteria(criteria: string, delimiter?: string): string;
 
+/**
+ * Subscribes to storage events to detect when another tab has finished reauthenticating.
+ * @public
+ * @param callback - Called when the other tab finishes reauthentication
+ * @returns A function to unsubscribe from the storage events
+ */
+export declare function onOtherTabReauthComplete(callback: () => void): () => void;
+
 /**
  * @public
  */
@@ -4515,6 +4556,21 @@ export declare class SessionMock implements Session {
     removeSessionStorageItem(key: string): void;
 }
 
+/**
+ * Result of a session refresh attempt.
+ * @public
+ */
+export declare enum SessionRefreshResult {
+    /** Session was successfully refreshed */
+    SUCCESS = "SUCCESS",
+    /** Refresh failed - page will reload */
+    FAILED = "FAILED",
+    /** Another tab is handling the refresh */
+    HANDLED_BY_OTHER_TAB = "HANDLED_BY_OTHER_TAB",
+    /** Session was already valid */
+    ALREADY_VALID = "ALREADY_VALID"
+}
+
 /**
  * Represents a WebSocket used to establish a communication channel between client and a Genesis server.
  * Provides methods for socket connection, sending and receiving WS messages.
@@ -4563,7 +4619,7 @@ export declare type SocketConnectOptions = {
     /**
      * An observer to receive notifications of incoming messages from the server.
      */
-    connectObserver?: Observer_2<Message>;
+    connectObserver?: Observer<Message>;
     /**
      * Enable sending heartbeat messages to the server to prevent the connection from timing out.
      */
@@ -4698,7 +4754,7 @@ export declare type SocketReconnectOptions = {
      * Observer to notify when reconnection occurs
      * @public
      */
-    reconnectObserver?: Observer_2<any>;
+    reconnectObserver?: Observer<any>;
     /**
      * Reconnect stream subscriptions on reconnection
      * @public
@@ -4962,6 +5018,20 @@ export declare type SystemHealthStatus = {
  */
 export declare const toFieldMetadata: (fieldDef: MetadataDetail[]) => FieldMetadata[];
 
+/**
+ * Attempts to refresh the session when authentication has expired.
+ * Uses a localStorage-based lock mechanism to prevent multiple tabs from
+ * trying to reauthenticate simultaneously.
+ *
+ * @public
+ * @param options - Optional configuration
+ * @param options.reloadOnFailure - Whether to reload the page if refresh fails (default: true)
+ * @returns The result of the refresh attempt
+ */
+export declare function tryRefreshSession(options?: {
+    reloadOnFailure?: boolean;
+}): Promise<SessionRefreshResult>;
+
 /**
  * Types map for FieldTypeEnum.
  * @public

package/docs/api/foundation-comms.httperror.md

@@ -0,0 +1,74 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@genesislcap/foundation-comms](./foundation-comms.md) &gt; [HttpError](./foundation-comms.httperror.md)
+
+## HttpError interface
+
+An error thrown when an HTTP request fails with a non-2xx status code.
+
+**Signature:**
+
+```typescript
+export interface HttpError extends Error 
+```
+**Extends:** Error
+
+## Properties
+
+<table><thead><tr><th>
+
+Property
+
+
+</th><th>
+
+Modifiers
+
+
+</th><th>
+
+Type
+
+
+</th><th>
+
+Description
+
+
+</th></tr></thead>
+<tbody><tr><td>
+
+[message](./foundation-comms.httperror.message.md)
+
+
+</td><td>
+
+
+</td><td>
+
+string
+
+
+</td><td>
+
+
+</td></tr>
+<tr><td>
+
+[status](./foundation-comms.httperror.status.md)
+
+
+</td><td>
+
+
+</td><td>
+
+number
+
+
+</td><td>
+
+
+</td></tr>
+</tbody></table>
+

package/docs/api/foundation-comms.httperror.message.md

@@ -0,0 +1,11 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@genesislcap/foundation-comms](./foundation-comms.md) &gt; [HttpError](./foundation-comms.httperror.md) &gt; [message](./foundation-comms.httperror.message.md)
+
+## HttpError.message property
+
+**Signature:**
+
+```typescript
+message: string;
+```

package/docs/api/foundation-comms.httperror.status.md

@@ -0,0 +1,11 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@genesislcap/foundation-comms](./foundation-comms.md) &gt; [HttpError](./foundation-comms.httperror.md) &gt; [status](./foundation-comms.httperror.status.md)
+
+## HttpError.status property
+
+**Signature:**
+
+```typescript
+status: number;
+```

package/docs/api/foundation-comms.md

@@ -393,6 +393,17 @@ General Message types
 Types of Genesis resources.
 
 
+</td></tr>
+<tr><td>
+
+[SessionRefreshResult](./foundation-comms.sessionrefreshresult.md)
+
+
+</td><td>
+
+Result of a session refresh attempt.
+
+
 </td></tr>
 <tr><td>
 
@@ -584,6 +595,17 @@ Check if the provided message contains an error and throw an Error if it does
 Normalise criteria.
 
 
+</td></tr>
+<tr><td>
+
+[onOtherTabReauthComplete(callback)](./foundation-comms.onothertabreauthcomplete.md)
+
+
+</td><td>
+
+Subscribes to storage events to detect when another tab has finished reauthenticating.
+
+
 </td></tr>
 <tr><td>
 
@@ -606,6 +628,17 @@ Generate reconnect interval based on scheduler
 Converts the field definitions to field metadata.
 
 
+</td></tr>
+<tr><td>
+
+[tryRefreshSession(options)](./foundation-comms.tryrefreshsession.md)
+
+
+</td><td>
+
+Attempts to refresh the session when authentication has expired. Uses a localStorage-based lock mechanism to prevent multiple tabs from trying to reauthenticate simultaneously.
+
+
 </td></tr>
 <tr><td>
 
@@ -863,6 +896,17 @@ GenesisResourcesConfig DI interface.
 An interface representing an HTTP client that can make GET and POST requests and return a promise with the response data.
 
 
+</td></tr>
+<tr><td>
+
+[HttpError](./foundation-comms.httperror.md)
+
+
+</td><td>
+
+An error thrown when an HTTP request fails with a non-2xx status code.
+
+
 </td></tr>
 <tr><td>