@persistica/flux-agent 0.0.12 → 0.0.14

package/index.js

@@ -1,3 +1,12 @@
+// libs/flux/shared/types/src/lib/errors/network-authority-not-found.error.ts
+var NetworkAuthorityNotFoundError = class _NetworkAuthorityNotFoundError extends Error {
+  static message = "Network authority not found for networkId";
+  constructor(networkId) {
+    super(`${_NetworkAuthorityNotFoundError.message}: '${networkId}'`);
+    this.name = "NetworkAuthorityNotFoundError";
+  }
+};
+
 // libs/flux/shared/types/src/lib/channel.type.ts
 var validateChannelNameOrThrow = (channelName) => {
   if (channelName.includes(":")) {
@@ -73,16 +82,20 @@ var validateNetworkIdOrThrow = (networkId) => {
   return true;
 };
 
+// libs/flux/shared/types/src/lib/client-id.type.ts
+var NANOID_LENGTH = 21;
+var NANOID_ALPHABET = "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ_abcdefghijklmnopqrstuvwxyz-";
+var isNanoId = (id) => {
+  if (typeof id !== "string") return false;
+  const regex = new RegExp(`^[${NANOID_ALPHABET}]{${NANOID_LENGTH}}$`);
+  return regex.test(id);
+};
+
 // libs/flux/shared/ws/src/lib/rpc/rpc-server.class.ts
 var RPCServer = class {
   methods = /* @__PURE__ */ new Map();
   /**
    * Registers a method to be called by the client.
-   * 
-   * @param { TMethodName }   methodName
-   * @param { TCallback }     fn
-   * 
-   * @returns { void }
    */
   registerMethod(methodName, fn) {
     const existingMethod = this.methods.get(methodName);
@@ -93,11 +106,6 @@ var RPCServer = class {
   }
   /**
    * Handles the request from the client.
-   * 
-   * @param { RPCRequest }    request
-   * @param { Function }      sendToRPCClient
-   * 
-   * @returns { void } 
    */
   async handleMessage(request, sendToRPCClient) {
     const response = {
@@ -144,8 +152,7 @@ var WebSocketClient = class extends RPCServer {
     };
   }
   /**
-   * 
-   * @returns { Promise<void> }
+   * Opens the WebSocket connection.
    */
   connect() {
     return new Promise((resolve, reject) => {
@@ -192,19 +199,23 @@ var WebSocketClient = class extends RPCServer {
       };
     });
   }
+  /**
+   * Emits a WebSocket event to all registered listeners.
+   */
   emit(event, data) {
     for (const listener of this.eventListeners[event]) {
       listener(data);
     }
   }
+  /**
+   * Registers an event listener.
+   */
   on(event, listener) {
     this.eventListeners[event].push(listener);
     return this;
   }
   /**
    * Clears all subscribers.
-   * 
-   * @returns { void }
    */
   clearEventSubscribers() {
     this.eventListeners.open = [];
@@ -213,6 +224,9 @@ var WebSocketClient = class extends RPCServer {
     this.eventListeners.connecting = [];
     this.eventListeners.error = [];
   }
+  /**
+   * Sends a message over the WebSocket connection.
+   */
   send(message) {
     if (this.ws?.readyState === WebSocket.OPEN) {
       this.ws.send(message);
@@ -220,6 +234,9 @@ var WebSocketClient = class extends RPCServer {
       console.warn("WebSocket not open.");
     }
   }
+  /**
+   * Closes the WebSocket connection and prevents auto-reconnect.
+   */
   close() {
     this.options.autoReconnect = false;
     this.ws?.close();
@@ -234,8 +251,16 @@ var FluxRemoteClient = class {
   constructor(iceConnection) {
     this.iceConnection = iceConnection;
   }
+  /**
+   * Calls a remote procedure on the connected client.
+   */
   callProcedure() {
   }
+  /**
+   * Sends a message to the connected client.
+   * 
+   * @param { string } message - The message to send to the connected client
+   */
   send(message) {
     this.iceConnection.sendMessage(message);
   }
@@ -288,6 +313,8 @@ var ICEConnection = class {
   offerSDP;
   /**
    * This offer must be sent to the other peer.
+   * 
+   * @returns { Promise<RTCSessionDescriptionInit> } The WebRTC offer
    */
   async createOffer() {
     console.log("creating offer and data channel");
@@ -299,8 +326,11 @@ var ICEConnection = class {
     return offer;
   }
   /**
+   * Accepts a WebRTC offer from the peer and generates an answer.
+   * 
+   * @param { RTCSessionDescriptionInit } offer - The offer from the remote peer
    * 
-   * @param { RTCSessionDescriptionInit } offer 
+   * @returns { Promise<RTCSessionDescriptionInit> } The answer to send back
    */
   async acceptOffer(offer) {
     this._stateChange("setting-remote-offer");
@@ -311,6 +341,13 @@ var ICEConnection = class {
     console.log("Send this Answer to the peer");
     return answer;
   }
+  /**
+   * Accepts a WebRTC answer from the peer.
+   * 
+   * @param { any } answer - The answer from the initiating peer
+   * 
+   * @returns { Promise<boolean> } True if the answer was accepted
+   */
   async acceptAnswer(answer) {
     this._stateChange("setting-remote-answer");
     await this.peerConnection.setRemoteDescription(new RTCSessionDescription(answer));
@@ -321,12 +358,16 @@ var ICEConnection = class {
   /**
    * If remote (not initiator) the answer was accepted.
    * 
-   * @param answer 
-   * @returns 
+   * @param { boolean } answerAccepted - Whether the answer was accepted
    */
   answerAcceptedByInitiator(answerAccepted) {
     this._stateChange(answerAccepted ? "connected" : "failed");
   }
+  /**
+   * Sends a message to the connected peer via the WebRTC data channel.
+   * 
+   * @param { string } message - The message to send
+   */
   sendMessage(message) {
     console.log("Sending message over webRTC");
     if (this.dataChannel && this.dataChannel.readyState === "open") {
@@ -357,8 +398,6 @@ var FluxAgentNetworkConnection = class {
   connectedChannelSet = /* @__PURE__ */ new Set();
   /**
    * Joins a channel on the network.
-   * 
-   * @param { string } channelName 
    */
   async joinChannel(channelName) {
     console.log(`Joining channel "${channelName}"`);
@@ -372,11 +411,7 @@ var FluxAgentNetworkConnection = class {
     return fluxNetworkChannel;
   }
   /**
-   * Listen to messages on this channel.
-   * 
-   * @param { string } channelName
-   * 
-   * @returns { Promise<void> }
+   * Leaves a channel on the network.
    */
   async leaveChannel(channelName) {
     console.log(`Leaving channel "${channelName}"`);
@@ -389,16 +424,15 @@ var FluxAgentNetworkConnection = class {
     this.connectedChannelSet.delete(channelName);
   }
   /**
-   * Connects to a client.
-   * 
-   * @param clientId
-   * 
-   * @returns 
+   * Connects to a remote agent.
    */
   connectToAgent(clientId) {
     this._fluxWebSocketConnection.connectToAgent(clientId);
     return new FluxRemoteClient(this.iceConnection);
   }
+  /**
+   * Returns a list of channels the agent is currently subscribed to.
+   */
   readConnectedChannels() {
     return [...this.connectedChannelSet];
   }
@@ -412,10 +446,6 @@ var FluxNetworkChannel = class {
   }
   /**
    * Broadcasts a message to the channel.
-   * 
-   * @param { string } channelName
-   * 
-   * @returns { void }
    */
   publish(message) {
     this._fluxWebSocketConnection.publish(
@@ -425,10 +455,6 @@ var FluxNetworkChannel = class {
   }
   /**
    * Listen to messages on this channel.
-   * 
-   * @param { TMessageCallback } fn
-   * 
-   * @returns { void }
    */
   onPublish(fn) {
     this._fluxWebSocketConnection.onPublish(
@@ -439,15 +465,6 @@ var FluxNetworkChannel = class {
   }
 };
 
-// libs/flux/shared/types/src/lib/client-id.type.ts
-var NANOID_LENGTH = 21;
-var NANOID_ALPHABET = "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ_abcdefghijklmnopqrstuvwxyz-";
-var isNanoId = (id) => {
-  if (typeof id !== "string") return false;
-  const regex = new RegExp(`^[${NANOID_ALPHABET}]{${NANOID_LENGTH}}$`);
-  return regex.test(id);
-};
-
 // libs/utils/logger/src/lib/utils-logger.ts
 var hasOverlap = (a, b) => a && b ? [...a].some((item) => (Array.isArray(b) ? b : [b]).includes(item)) : false;
 var PicoLogger = /* @__PURE__ */ (() => {
@@ -488,7 +505,11 @@ var createWSConnection = (id, ticket, stateManager, onReconnectCallback, options
     onReconnectCallback,
     stateManager,
     ticket,
-    options
+    {
+      secretKey: options?.secretKey,
+      retries: options?.retries,
+      port: options?.domain ? new URL(options.domain).port ? Number.parseInt(new URL(options.domain).port) : void 0 : void 0
+    }
   );
 };
 var FluxWebSocketConnection = class {
@@ -499,11 +520,9 @@ var FluxWebSocketConnection = class {
     this.token = token;
     this.options = options;
     this.options = {
-      // Defaults
-      retries: 1e4,
-      port: 5100,
-      // Override with provided options
-      ...this.options
+      secretKey: this.options?.secretKey,
+      retries: this.options?.retries ?? 1e4,
+      port: this.options?.port ?? 5100
     };
     this.socket = new FluxWebSocketClientConnection(
       {
@@ -523,11 +542,6 @@ var FluxWebSocketConnection = class {
   first = true;
   /**
    * Intercepts messages of a given package type.
-   * 
-   * @param { string }            packageType 
-   * @param { TMessageCallback }  fn
-   * 
-   * @returns { void } 
    */
   interceptPackageTypeMessages(packageType, fn) {
     const existingInterceptors = this.packageTypeInterceptorCallbacks.get(packageType);
@@ -539,11 +553,6 @@ var FluxWebSocketConnection = class {
   }
   /**
    * Removes a package type interceptor.
-   * 
-   * @param { string }            packageType 
-   * @param { TMessageCallback }  fn
-   * 
-   * @returns { void } 
    */
   removePackageTypeInterceptor(packageType, fn) {
     const existingInterceptors = this.packageTypeInterceptorCallbacks.get(packageType);
@@ -558,8 +567,6 @@ var FluxWebSocketConnection = class {
   }
   /**
    * Connect to the Flux platform.
-   * 
-   * @returns { Promise<FluxWebSocketClientConnection> }
    */
   async connect() {
     if (this.webSocketClient) {
@@ -598,6 +605,9 @@ var FluxWebSocketConnection = class {
       this.socket.connect();
     });
   }
+  /**
+   * Disconnects from the Flux platform.
+   */
   disconnect() {
     this.socket.close();
     this.webSocketClient = void 0;
@@ -605,11 +615,6 @@ var FluxWebSocketConnection = class {
   }
   /**
    * Registers an authority to the network.
-   * 
-   * @param { TAuthorizeCallback }        cb
-   * @param { TChannnelAuthCallback<M> }  authorizeNetworkChannel
-   * 
-   * @returns { Promise<void> }
    */
   async registerAuthority(cb, authorizeNetworkChannel) {
     const webSocketClient = await this.connect();
@@ -623,8 +628,6 @@ var FluxWebSocketConnection = class {
   }
   /**
    * Connects to a network.
-   * 
-   * @returns { Promise<FluxAgentNetworkConnection> }
    */
   async connectToNetwork() {
     const webSocketClient = await this.connect();
@@ -636,10 +639,6 @@ var FluxWebSocketConnection = class {
   }
   /**
    * Join a channel.
-   * 
-   * @param { TChannelName } channelName
-   * 
-   * @returns { Promise<FluxNetworkChannel> } 
    */
   async joinChannel(channelName) {
     if (this.webSocketClient) {
@@ -663,10 +662,7 @@ var FluxWebSocketConnection = class {
     return Promise.reject(new Error("Not connected"));
   }
   /**
-   * 
-   * @param { TChannelName } channelName
-   * 
-   * @returns { Promise<void> } 
+   * Leaves a channel.
    */
   async leaveChannel(channelName) {
     if (this.webSocketClient) {
@@ -676,11 +672,7 @@ var FluxWebSocketConnection = class {
     return Promise.reject(new Error("Not connected"));
   }
   /**
-   * 
-   * @param { TChannelName } channelName
-   * @param { string } message
-   * 
-   * @returns { void } 
+   * Publishes a message to a channel.
    */
   publish(channelName, message) {
     if (this.webSocketClient) {
@@ -690,11 +682,6 @@ var FluxWebSocketConnection = class {
   }
   /**
    * Adds a callback to the list of callbacks for a given channel topic.
-   * 
-   * @param { TChannelName } channelName
-   * @param { string } message
-   * 
-   * @returns { void } 
    */
   onPublish(channelName, fn) {
     const existingSubscriber = this.channelCallbacks.get(channelName);
@@ -707,10 +694,7 @@ var FluxWebSocketConnection = class {
     }
   }
   /**
-   * 
-   * @param { string } channelName
-   * 
-   * @returns { Promise<FluxNetworkChannel> } 
+   * Sends a connection request to another agent.
    */
   async connectToAgent(destinationClientId) {
     if (this.webSocketClient) {
@@ -719,10 +703,7 @@ var FluxWebSocketConnection = class {
     return Promise.resolve();
   }
   /**
-   * 
-   * @param { TMessageCallback } cb
-   * 
-   * @returns { void } 
+   * Registers a callback to be called when a message is received.
    */
   onMessage(cb) {
     this.callbacks.add(cb);
@@ -732,8 +713,6 @@ var FluxWebSocketConnection = class {
   // ****************************************************************************
   /**
    * Subscribes to the channel changes.
-   * 
-   * @returns { void }
    */
   subscribeToChannelChanges() {
     if (this.webSocketClient) {
@@ -744,10 +723,6 @@ var FluxWebSocketConnection = class {
   }
   /**
    * Disconnects an agent from the network.
-   * 
-   * @param { string } id
-   * 
-   * @returns { void }
    */
   disconnectAgent(id) {
     if (!isNanoId(id)) {
@@ -762,6 +737,9 @@ var FluxWebSocketConnection = class {
   // ****************************************************************************
   // *** Internal Helpers
   // ****************************************************************************
+  /**
+   * Handles incoming WebSocket messages.
+   */
   handleMessage(message_) {
     for (const cb of this.callbacks) {
       cb(message_);
@@ -779,11 +757,12 @@ var FluxWebSocketConnection = class {
       case ON_NETWORK_CHANNEL_PUBLISH: {
         const firstColon = message_.indexOf(":");
         const secondColon = message_.indexOf(":", firstColon + 1);
-        const channelName = message_.slice(firstColon + 1, secondColon);
+        const thirdColon = message_.indexOf(":", secondColon + 1);
+        const channelName = message_.slice(secondColon + 1, thirdColon);
         if (validateChannelNameOrThrow(channelName)) {
           const topicCallbacks = this.channelCallbacks.get(channelName);
           if (topicCallbacks) {
-            let data = message_.slice(secondColon + 1);
+            let data = message_.slice(thirdColon + 1);
             if (data.startsWith("o:")) {
               try {
                 data = JSON.parse(data.substring(2));
@@ -813,7 +792,6 @@ var FluxWebSocketConnection = class {
       }
       default:
         if (message_.startsWith(`${ERROR}:`)) {
-          throw new Error(message_.substring(message_.indexOf(":") + 1) ?? "Unknown error");
         }
         PicoLogger.log(`\u{1F50C} Unhandled type: "${message_}"`, "ws-client");
         break;
@@ -877,23 +855,41 @@ async function encrypt(data, password) {
 var StateManager = class {
   networkStateListeners = /* @__PURE__ */ new Set();
   webRTCStateListeners = /* @__PURE__ */ new Set();
+  /**
+   * Attaches a listener for network connection state changes.
+   */
   attachNetworkStateListener(fn) {
     this.networkStateListeners.add(fn);
   }
+  /**
+   * Detaches a previously registered network connection state listener.
+   */
   detachNetworkStateListener(fn) {
     this.networkStateListeners.delete(fn);
   }
+  /**
+   * Attaches a listener for WebRTC connection state changes.
+   */
   attachWebRTCStateListener(fn) {
     this.webRTCStateListeners.add(fn);
   }
+  /**
+   * Detaches a previously registered WebRTC connection state listener.
+   */
   detachWebRTCStateListener(fn) {
     this.webRTCStateListeners.delete(fn);
   }
+  /**
+   * Emits a network connection state change to all registered listeners.
+   */
   emitNetworkState(networkState) {
     for (const fn of this.networkStateListeners) {
       fn(networkState);
     }
   }
+  /**
+   * Emits a WebRTC connection state change to all registered listeners.
+   */
   emitWebRTCState(rtcState) {
     for (const fn of this.webRTCStateListeners) {
       fn(rtcState);
@@ -933,6 +929,34 @@ var StateManager = class {
    */
 };
 
+// libs/flux/shared/utils/src/lib/promises.utils.ts
+var retryOrThrow = async (fn, shouldRetry, options) => {
+  let attempt = 0;
+  let overrideDelay;
+  while (true) {
+    try {
+      if (attempt > 0) {
+        if (options.onRetry) {
+          overrideDelay = options.onRetry(attempt, options.retries) ?? void 0;
+        }
+      }
+      return await fn();
+    } catch (err) {
+      attempt++;
+      if (attempt > options.retries || !shouldRetry(err)) {
+        throw err;
+      }
+      if (options.delayMs > 0 || overrideDelay && overrideDelay > 0) {
+        let delay = overrideDelay ?? options.delayMs;
+        await new Promise((res) => setTimeout(
+          res,
+          delay
+        ));
+      }
+    }
+  }
+};
+
 // libs/flux/shared/utils/src/lib/machine-id.util.ts
 var validateMachineUID = (machineUID) => {
   if (typeof machineUID !== "string") {
@@ -1001,6 +1025,12 @@ var authenticateAgentOrThrow = async (networkId, domain, unknownIdentificationPa
     body: customPayload
   });
   if (!response.ok) {
+    if (response.status === 401) {
+      const textResponse = await response.text();
+      if (textResponse.startsWith(NetworkAuthorityNotFoundError.message)) {
+        throw new NetworkAuthorityNotFoundError(networkId);
+      }
+    }
     throw new Error(`Auth failed: ${response.status}`);
   }
   const result = await response.text();
@@ -1042,62 +1072,82 @@ var FluxAgent = class {
   /**
    * Connect to the network using provided identification.
    * 
-   * @param { unknown }   identification
-   * @param { string }    [clientUId]
-   *
-   * @returns { Promise<FluxAgentNetworkConnection> }
+   * @param { unknown } identification - The identification payload to authenticate with
+   * @param { string } [clientUId] - Optional client UID to use
+   * 
+   * @returns { Promise<FluxAgentNetworkConnection> } The network connection
    */
   async connect(identification, clientUId) {
     this.stateManager.emitNetworkState("authorizing");
     if (clientUId && !validateAgentUIDOrThrow(clientUId)) {
       throw new Error("Will never be thrown");
     }
-    const ticket = await authenticateAgentOrThrow(
-      this.networkId,
-      this.options?.domain ?? "http://localhost:5100",
-      identification,
-      {
-        clientUId,
-        machineUID: await getMachineUID() ?? void 0
-      }
-    );
-    this.fluxWebSocketConnection = createWSConnection(
-      this.id,
-      ticket,
-      this.stateManager,
-      async () => {
-        await this.connect(
-          identification,
-          clientUId
-        );
-      },
-      this.options
-    );
-    this.fluxClientData.updateWsConnection(this.fluxWebSocketConnection);
-    const fluxNetworkConnection = await this.fluxWebSocketConnection.connectToNetwork();
-    return fluxNetworkConnection;
+    try {
+      const ticket = await retryOrThrow(
+        async () => {
+          return authenticateAgentOrThrow(
+            this.networkId,
+            this.options?.domain ?? "http://localhost:5100",
+            identification,
+            {
+              clientUId,
+              machineUID: await getMachineUID() ?? void 0
+            }
+          );
+        },
+        // Retry if no authority was found yet
+        (error) => error instanceof NetworkAuthorityNotFoundError,
+        {
+          retries: 100,
+          delayMs: 500,
+          // Backoff until 3 seconds
+          onRetry: (attempt) => Math.min(3e3, 500 + attempt * 200)
+        }
+      );
+      this.fluxWebSocketConnection = createWSConnection(
+        this.id,
+        ticket,
+        this.stateManager,
+        async () => {
+          await this.connect(
+            identification,
+            clientUId
+          );
+        },
+        this.options
+      );
+      this.fluxClientData.updateWsConnection(this.fluxWebSocketConnection);
+      const fluxNetworkConnection = await this.fluxWebSocketConnection.connectToNetwork();
+      return fluxNetworkConnection;
+    } catch (error) {
+      return Promise.reject(error);
+    }
   }
+  /**
+   * Disconnects from the network.
+   */
   disconnect() {
     this.fluxWebSocketConnection?.disconnect();
   }
   /**
-   *
-   * @param fn
-   *
-   * @returns { void }
+   * Attaches a listener for WebRTC connection state changes.
    */
   onWebRTConnectionState = this.stateManager.attachWebRTCStateListener.bind(this.stateManager);
   /**
-   *
-   * @param fn
-   *
-   * @returns { void }
+   * Attaches a listener for network connection state changes.
    */
   onNetworkState = this.stateManager.attachNetworkStateListener.bind(this.stateManager);
+  /**
+   * Registers a callback to be called when a message is received.
+   * 
+   * @param { TMessageCallback } cb - Callback to invoke when a message is received
+   */
   onMessage(cb) {
     this.fluxClientData.onMessage(cb);
   }
 };
 export {
-  FluxAgent
+  FluxAgent,
+  FluxNetworkChannel,
+  FluxRemoteClient
 };

package/package.json

@@ -1,23 +1,29 @@
 {
     "name": "@persistica/flux-agent",
-    "version": "0.0.12",
+    "version": "0.0.14",
     "description": "Persistica Flux Agent",
     "type": "module",
     "keywords": [],
     "publishConfig": {
         "access": "public"
     },
-    "exports": "./index.js",
+    "exports": {
+        ".": {
+            "types": "./src/index.d.ts",
+            "import": "./index.js",
+            "default": "./index.js"
+        }
+    },
     "main": "./index.js",
     "types": "./src/index.d.ts",
     "repository": {
         "type": "git",
-        "url": "git+https://github.com/rujorgensen/persistica.git"
+        "url": "git+https://github.com/rujorgensen/flux.git"
     },
     "author": "pixl.prophet",
     "license": "ISC",
     "bugs": {
-        "url": "https://github.com/rujorgensen/persistica/issues"
+        "url": "https://github.com/rujorgensen/flux/issues"
     },
-    "homepage": "https://github.com/rujorgensen/persistica#readme"
+    "homepage": "https://github.com/rujorgensen/flux#readme"
 }

package/src/index.d.ts

@@ -1,2 +1,4 @@
 export type { FluxAgentNetworkConnection } from '@flux/shared/connection';
 export { FluxAgent, } from './lib/flux-agent.class';
+export { FluxNetworkChannel, } from '@flux/shared/connection';
+export { FluxRemoteClient, } from './lib/flux-remote-client.class';

package/src/lib/channel/channel.type.d.ts

@@ -2,9 +2,9 @@ import type { TChannelName } from '@flux/shared/types';
 /**
  * Callback function to authorize a channel connection.
  *
- * @param { TChannelName }     channelTopic - the topic to subscribe to
- * @param { unknown }           identification - whatever identification the authority requires
+ * @param { TChannelName } channelTopic - The channel topic to subscribe to
+ * @param { T } identification - Whatever identification the authority requires
  *
- * @returns { Promise<boolean> } - true if the channel connection is authorized, false otherwise
+ * @returns { Promise<boolean> } True if the channel connection is authorized, false otherwise
  */
 export type TChannnelAuthCallback<T> = (channelTopic: TChannelName, identification: T) => Promise<boolean>;

package/src/lib/connector/auth/register-client.auth.d.ts

@@ -5,12 +5,13 @@ import { type TFluxClientUID } from '@flux/shared/utils';
  *
  * This client -> flux server -> authority client -> flux server -> this client.
  *
- * @param { string }        domain The domain of the authority server.
- * @param { unknown }       unknownIdentificationPayload The payload to send to the authority server.
- * @param { string }        [password]
- * @param { TAgentOwnUId }  [agentOwnUId]
+ * @param { TNetworkId_S } networkId - The network ID to connect to
+ * @param { string } domain - The domain of the authority server
+ * @param { unknown } unknownIdentificationPayload - The payload to send to the authority server
+ * @param { object } clientInfo - Optional client identification info
+ * @param { string } [password] - Optional password for encrypting the payload
  *
- * @returns { Promise<TAuthenticationTicket> }
+ * @returns { Promise<TAuthenticationTicket> } The authentication ticket for connecting the websocket
  */
 export declare const authenticateAgentOrThrow: (networkId: TNetworkId_S, domain: string, unknownIdentificationPayload: unknown, clientInfo: {
     clientUId?: TAgentOwnUId;

package/src/lib/connector/low-level-com/web-rtc/ice-connection.d.ts

@@ -15,20 +15,36 @@ export declare class ICEConnection {
     constructor(_fluxWebSocketClientConnection: FluxWebSocketClientConnection, _stateChange: (state: TRTCState) => void);
     /**
      * This offer must be sent to the other peer.
+     *
+     * @returns { Promise<RTCSessionDescriptionInit> } The WebRTC offer
      */
     private createOffer;
     /**
+     * Accepts a WebRTC offer from the peer and generates an answer.
+     *
+     * @param { RTCSessionDescriptionInit } offer - The offer from the remote peer
      *
-     * @param { RTCSessionDescriptionInit } offer
+     * @returns { Promise<RTCSessionDescriptionInit> } The answer to send back
      */
     private acceptOffer;
+    /**
+     * Accepts a WebRTC answer from the peer.
+     *
+     * @param { any } answer - The answer from the initiating peer
+     *
+     * @returns { Promise<boolean> } True if the answer was accepted
+     */
     private acceptAnswer;
     /**
      * If remote (not initiator) the answer was accepted.
      *
-     * @param answer
-     * @returns
+     * @param { boolean } answerAccepted - Whether the answer was accepted
      */
     private answerAcceptedByInitiator;
+    /**
+     * Sends a message to the connected peer via the WebRTC data channel.
+     *
+     * @param { string } message - The message to send
+     */
     sendMessage(message: string): void;
 }

package/src/lib/flux-agent.class.d.ts

@@ -18,26 +18,28 @@ export declare class FluxAgent {
     /**
      * Connect to the network using provided identification.
      *
-     * @param { unknown }   identification
-     * @param { string }    [clientUId]
+     * @param { unknown } identification - The identification payload to authenticate with
+     * @param { string } [clientUId] - Optional client UID to use
      *
-     * @returns { Promise<FluxAgentNetworkConnection> }
+     * @returns { Promise<FluxAgentNetworkConnection> } The network connection
      */
     connect(identification: unknown, clientUId?: string): Promise<FluxAgentNetworkConnection>;
+    /**
+     * Disconnects from the network.
+     */
     disconnect(): void;
     /**
-     *
-     * @param fn
-     *
-     * @returns { void }
+     * Attaches a listener for WebRTC connection state changes.
      */
     onWebRTConnectionState: (fn: (rtcState: import("@flux/shared/utils").TRTCState) => void) => void;
     /**
-     *
-     * @param fn
-     *
-     * @returns { void }
+     * Attaches a listener for network connection state changes.
      */
     onNetworkState: (fn: (networkState: import("@flux/shared/utils").TNetworkConnectionState) => void) => void;
+    /**
+     * Registers a callback to be called when a message is received.
+     *
+     * @param { TMessageCallback } cb - Callback to invoke when a message is received
+     */
     onMessage(cb: TMessageCallback): void;
 }

package/src/lib/flux-remote-client.class.d.ts

@@ -5,6 +5,14 @@ import { ICEConnection } from './connector/low-level-com/web-rtc/ice-connection'
 export declare class FluxRemoteClient {
     private readonly iceConnection;
     constructor(iceConnection: ICEConnection);
+    /**
+     * Calls a remote procedure on the connected client.
+     */
     callProcedure(): void;
+    /**
+     * Sends a message to the connected client.
+     *
+     * @param { string } message - The message to send to the connected client
+     */
     send(message: string): void;
 }

package/src/lib/utils/obscuring/decrypt.utils.d.ts

@@ -4,10 +4,12 @@ interface IEncryptedData {
     salt: string;
 }
 /**
- * Decrypts an AES-256-GCM encrypted JSON object using a password
- * @param {IEncryptedData} encryptedData - The encrypted data object
- * @param {string} password - The password
- * @returns {Promise<Object>} - Decrypted JSON object
+ * Decrypts an AES-256-GCM encrypted JSON object using a password.
+ *
+ * @param { IEncryptedData } encryptedData - The encrypted data object containing iv, salt, and ciphertext
+ * @param { string } password - The password to derive the decryption key from
+ *
+ * @returns { Promise<Object> } The decrypted JSON object
  */
 export declare function decrypt(encryptedData: IEncryptedData, password: string): Promise<any>;
 export {};

package/src/lib/utils/obscuring/encyprt.utils.d.ts

@@ -1,9 +1,10 @@
 /**
- * Encrypts a JSON object using AES-256-GCM with password-derived key
+ * Encrypts a JSON object using AES-256-GCM with a password-derived key.
  *
- * @param {Object} data - The data to encrypt
- * @param {string} password - The password
- * @returns {Promise<Object>} - Encrypted data (Base64 format)
+ * @param { string } data - The data string to encrypt
+ * @param { string } password - The password to derive the encryption key from
+ *
+ * @returns { Promise<Object> } The encrypted data in Base64 format with iv and salt
  */
 export declare function encrypt(data: string, password: string): Promise<{
     encrypted: string;

package/src/lib/utils/obscuring/shared.utils.d.ts

@@ -1,9 +1,9 @@
 /**
- * Derive a cryptographic key from a password using PBKDF2
+ * Derives a cryptographic key from a password using PBKDF2.
  *
- * @param { string } password - User-provided password
- * @param { Uint8Array } salt - Salt for key derivation
+ * @param { string } password - The password to derive the key from
+ * @param { any } salt - The salt for key derivation
  *
- * @returns { Promise<CryptoKey> } - AES-256-GCM key
+ * @returns { Promise<CryptoKey> } The derived cryptographic key
  */
 export declare function deriveKey(password: string, salt: any): Promise<CryptoKey>;