@vrtmrz/livesync-commonlib 0.1.0-rc.1 → 0.1.0-rc.10

package/dist/replication/trystero/addP2PEventHandlers.js

@@ -1,30 +1,29 @@
 import { EVENT_DATABASE_REBUILT, EVENT_PLATFORM_UNLOADED, EVENT_SETTING_SAVED } from "../../events/coreEvents.js";
 import { EVENT_ADVERTISEMENT_RECEIVED, EVENT_DEVICE_LEAVED, EVENT_REQUEST_STATUS } from "./TrysteroReplicatorP2PServer.js";
-function addP2PEventHandlers(instance, events) {
+function addP2PEventHandlers(source, events) {
+  const current = () => typeof source === "function" ? source() : source;
   events.onEvent(EVENT_ADVERTISEMENT_RECEIVED, (peer) => {
-    void instance.onNewPeer(peer);
+    void current().onNewPeer(peer);
   });
   events.onEvent(EVENT_DEVICE_LEAVED, (peerId) => {
-    instance.onPeerLeaved(peerId);
+    current().onPeerLeaved(peerId);
   });
   events.onEvent(EVENT_REQUEST_STATUS, () => {
-    instance.requestStatus();
+    current().requestStatus();
   });
   events.onEvent(EVENT_DATABASE_REBUILT, async () => {
-    await instance.open();
+    await current().open();
   });
   events.onEvent(EVENT_PLATFORM_UNLOADED, () => {
-    void instance.close();
+    void current().close();
   });
   events.onEvent(EVENT_SETTING_SAVED, async (settings) => {
-    const isOpen = instance.isServing ?? instance.server?.isServing ?? false;
+    const instance = current();
     if (settings.P2P_Enabled && settings.P2P_AutoStart) {
       await instance.open();
       return;
     }
-    if (isOpen) {
-      await instance.close();
-    }
+    await instance.close();
   });
 }
 async function openP2PReplicator(instance) {

package/dist/replication/trystero/types.d.ts

@@ -85,6 +85,8 @@ export interface ReplicatorHostEnv extends ReplicatorHost {
     db: PouchDB.Database<EntryDoc>;
     simpleStore: SimpleStore<unknown>;
     runFiniteReplicationActivity?: AsyncActivityRunner["run"];
+    /** Lightweight, repeatable host policy checked before ordinary P2P replication starts. */
+    canStartOrdinaryReplication?(showMessage?: boolean): Promise<boolean>;
     processReplicatedDocs(docs: Array<PouchDB.Core.ExistingDocument<EntryDoc>>): void | Promise<void>;
 }
 export type Advertisement = {

package/dist/replication/trystero/useP2PReplicatorCommands.d.ts

@@ -4,4 +4,4 @@ import type { UseP2PReplicatorResult } from "./UseP2PReplicatorResult.js";
  * ServiceFeature: Registers event handlers for P2P replication and manages the lifecycle of a LiveSyncTrysteroReplicator instance.
  * @param host
  */
-export declare function useP2PReplicatorCommands(host: NecessaryServices<"API" | "setting", never>, { replicator }: UseP2PReplicatorResult): void;
+export declare function useP2PReplicatorCommands(host: NecessaryServices<"API" | "setting", never>, result: UseP2PReplicatorResult): void;

package/dist/replication/trystero/useP2PReplicatorCommands.js

@@ -1,9 +1,10 @@
 import { Logger, LOG_LEVEL_NOTICE } from "octagonal-wheels/common/logger";
-function useP2PReplicatorCommands(host, { replicator }) {
+function useP2PReplicatorCommands(host, result) {
   host.services.API.addCommand({
     id: "p2p-establish-connection",
     name: "P2P Sync : Connect to the Signalling Server",
     checkCallback: (isChecking) => {
+      const replicator = result.replicator;
       if (!replicator) return false;
       if (isChecking) return !(replicator.server?.isServing ?? false);
       void replicator.open();
@@ -13,6 +14,7 @@ function useP2PReplicatorCommands(host, { replicator }) {
     id: "p2p-close-connection",
     name: "P2P Sync : Disconnect from the Signalling Server",
     checkCallback: (isChecking) => {
+      const replicator = result.replicator;
       if (!replicator) return false;
       if (isChecking) return replicator.server?.isServing ?? false;
       Logger("Closing P2P Connection", LOG_LEVEL_NOTICE);

package/dist/replication/trystero/useP2PReplicatorFeature.js

@@ -8,6 +8,7 @@ function useP2PReplicatorFeature(host, openReplicationUIFactory, openRebuildUIFa
   let replicator = new LiveSyncTrysteroReplicator({
     services: host.services
   });
+  let replacementPromise;
   if (openReplicationUIFactory) {
     replicator.env.openReplicationUI = openReplicationUIFactory(replicator);
   }
@@ -19,27 +20,36 @@ function useP2PReplicatorFeature(host, openReplicationUIFactory, openRebuildUIFa
       return replicator;
     }
   };
-  addP2PEventHandlers(activeReplicator.replicator, host.services.context.events);
+  addP2PEventHandlers(() => activeReplicator.replicator, host.services.context.events);
   host.services.replicator.getNewReplicator.addHandler(
     async (settingOverride = {}) => {
       const settings = { ...host.services.setting.currentSettings(), ...settingOverride };
       if (settings.remoteType == REMOTE_P2P) {
-        const existingReplicator = replicator;
+        if (replacementPromise) return await replacementPromise;
+        const operation = (async () => {
+          const existingReplicator = replicator;
+          try {
+            await existingReplicator?.close();
+          } catch (e) {
+            Logger(`Error closing existing p2p replicator`);
+            Logger(e, LOG_LEVEL_VERBOSE);
+          }
+          const newReplicator = new LiveSyncTrysteroReplicator({ services: host.services });
+          if (openReplicationUIFactory) {
+            newReplicator.env.openReplicationUI = openReplicationUIFactory(newReplicator);
+          }
+          if (openRebuildUIFactory) {
+            newReplicator.env.openRebuildUI = openRebuildUIFactory(newReplicator);
+          }
+          replicator = newReplicator;
+          return replicator;
+        })();
+        replacementPromise = operation;
         try {
-          await existingReplicator?.close();
-        } catch (e) {
-          Logger(`Error closing existing p2p replicator`);
-          Logger(e, LOG_LEVEL_VERBOSE);
+          return await operation;
+        } finally {
+          if (replacementPromise === operation) replacementPromise = void 0;
         }
-        const newReplicator = new LiveSyncTrysteroReplicator({ services: host.services });
-        if (openReplicationUIFactory) {
-          newReplicator.env.openReplicationUI = openReplicationUIFactory(newReplicator);
-        }
-        if (openRebuildUIFactory) {
-          newReplicator.env.openRebuildUI = openRebuildUIFactory(newReplicator);
-        }
-        replicator = newReplicator;
-        return replicator;
       }
       return void 0;
     }

package/dist/rpc/RpcRoom.d.ts

@@ -10,7 +10,7 @@ export declare class RpcRoom {
     private incomingChunkMap;
     private incomingChunkTimers;
     private peerVersion;
-    private disposer;
+    private disposers;
     constructor(options: RpcRoomOptions);
     close(): void;
     session(peerId: string): RpcSession;

package/dist/rpc/RpcRoom.js

@@ -23,34 +23,40 @@ class RpcRoom {
   incomingChunkMap = /* @__PURE__ */ new Map();
   incomingChunkTimers = /* @__PURE__ */ new Map();
   peerVersion = /* @__PURE__ */ new Map();
-  disposer;
+  disposers = [];
   constructor(options) {
     this.options = {
       maxWirePayloadBytes: options.maxWirePayloadBytes ?? 32 * 1024,
       chunkMissingRetryMs: options.chunkMissingRetryMs ?? 350,
       ...options
     };
-    this.disposer = this.options.transport.onMessage((msg, peerId) => {
-      void this.onWireMessage(msg, peerId);
-    });
+    this.disposers.push(
+      this.options.transport.onMessage((msg, peerId) => {
+        void this.onWireMessage(msg, peerId);
+      })
+    );
     if (this.options.transport.onPeerJoin) {
-      this.options.transport.onPeerJoin((peerId) => {
-        void this.sendEnvelope(peerId, {
-          kind: "handshake",
-          versionMajor: RPC_VERSION_MAJOR,
-          versionMinor: RPC_VERSION_MINOR
-        });
-      });
+      this.disposers.push(
+        this.options.transport.onPeerJoin((peerId) => {
+          void this.sendEnvelope(peerId, {
+            kind: "handshake",
+            versionMajor: RPC_VERSION_MAJOR,
+            versionMinor: RPC_VERSION_MINOR
+          });
+        })
+      );
     }
     if (this.options.transport.onPeerLeave) {
-      this.options.transport.onPeerLeave((peerId) => {
-        this.sessions.delete(peerId);
-        this.peerVersion.delete(peerId);
-      });
+      this.disposers.push(
+        this.options.transport.onPeerLeave((peerId) => {
+          this.sessions.delete(peerId);
+          this.peerVersion.delete(peerId);
+        })
+      );
     }
   }
   close() {
-    this.disposer?.();
+    this.disposers.splice(0).forEach((dispose) => dispose());
     this.pending.forEach((pending) => pending.reject(new RpcError("NOT_CONNECTED", "Room closed")));
     this.pending.clear();
     this.inboundCalls.clear();

package/dist/rpc/transports/TrysteroTransport.d.ts

@@ -96,6 +96,8 @@ export type TrysteroRoomHandle = {
     /**
      * Returns the current WebRTC peer connections keyed by peer ID.
      * Equivalent to the Trystero `room.getPeers()` call.
+     * Treat these as diagnostic handles. Their lifecycle belongs to Trystero;
+     * call {@link TrysteroRoomHandle.leave} instead of closing them directly.
      */
     getPeers: () => Record<string, RTCPeerConnection>;
     /**

package/dist/rpc/transports/TrysteroTransport.js

@@ -5,30 +5,37 @@ import { RpcPouchDBProxy } from "../pouchdb/RpcPouchDBProxy.js";
 import { ConnectionStringParser } from "../../common/ConnectionString.js";
 import { compatGlobal } from "../../common/coreEnvFunctions.js";
 import { generateJoinRoomOptions } from "./trysteroUtils.js";
+import { subscribeTrysteroPeerEvents } from "./trysteroRoomEvents.js";
 const RPC_ACTION_NAME = "rpc2";
 const AD_ACTION_NAME = "ad";
 function attachAdvertisement(room, localPeerId, name, platform = "unknown") {
   const peerMap = /* @__PURE__ */ new Map();
   const localAd = { peerId: localPeerId, name, platform };
-  const [sendAd, arrivedAd] = room.makeAction(AD_ACTION_NAME);
-  const sendAdvertisement = (toPeerId) => sendAd(localAd, toPeerId).then(() => void 0);
-  room.onPeerJoin((peerId) => {
-    void sendAdvertisement(peerId);
-  });
-  room.onPeerLeave((peerId) => {
-    peerMap.delete(peerId);
+  const advertisementAction = room.makeAction(AD_ACTION_NAME);
+  const sendAdvertisement = (toPeerId) => advertisementAction.send(localAd, toPeerId ? { target: toPeerId } : void 0);
+  const disposePeerEvents = subscribeTrysteroPeerEvents(room, {
+    // When a new peer joins, introduce ourselves to them specifically.
+    onJoin: (peerId) => {
+      void sendAdvertisement(peerId);
+    },
+    // Remove stale entries when a peer disconnects.
+    onLeave: (peerId) => {
+      peerMap.delete(peerId);
+    }
   });
-  arrivedAd((data, peerId) => {
+  advertisementAction.onMessage = (data, { peerId }) => {
     if (data.peerId === localPeerId) return;
     if (data.peerId !== peerId) return;
     peerMap.set(peerId, data);
-  });
+  };
   return {
     get peers() {
       return peerMap;
     },
     sendAdvertisement,
     stop() {
+      disposePeerEvents();
+      advertisementAction.onMessage = null;
       peerMap.clear();
     }
   };
@@ -40,22 +47,22 @@ const TRYSTERO_RPC_DEFAULTS = {
   chunkMissingRetryMs: 150
 };
 function wrapTrysteroRoom(room) {
-  const [sendRpc, arrivedRpc] = room.makeAction(RPC_ACTION_NAME);
+  const rpcAction = room.makeAction(RPC_ACTION_NAME);
   return {
     send(message, peerId) {
-      return sendRpc(message, peerId).then(() => void 0);
+      return rpcAction.send(message, { target: peerId });
     },
     onMessage(handler) {
-      arrivedRpc((data, peerId) => handler(data, peerId));
-      return () => void 0;
+      rpcAction.onMessage = (data, { peerId }) => handler(data, peerId);
+      return () => {
+        rpcAction.onMessage = null;
+      };
     },
     onPeerJoin(handler) {
-      room.onPeerJoin((peerId) => handler(peerId));
-      return () => void 0;
+      return subscribeTrysteroPeerEvents(room, { onJoin: handler });
     },
     onPeerLeave(handler) {
-      room.onPeerLeave((peerId) => handler(peerId));
-      return () => void 0;
+      return subscribeTrysteroPeerEvents(room, { onLeave: handler });
     }
   };
 }

package/dist/rpc/transports/trysteroRoomEvents.d.ts

@@ -0,0 +1,14 @@
+import type { Room } from "@trystero-p2p/nostr";
+type PeerHandler = (peerId: string) => void;
+/**
+ * Subscribe multiple consumers to Trystero's single peer-event callback slots.
+ *
+ * Trystero 0.25 exposes `onPeerJoin` and `onPeerLeave` as nullable callback
+ * properties. This adapter preserves the library's multi-subscriber transport
+ * contract and returns a disposer for each subscription.
+ */
+export declare function subscribeTrysteroPeerEvents(room: Room, handlers: {
+    onJoin?: PeerHandler;
+    onLeave?: PeerHandler;
+}): () => void;
+export {};

package/dist/rpc/transports/trysteroRoomEvents.js

@@ -0,0 +1,34 @@
+const subscribersByRoom = /* @__PURE__ */ new WeakMap();
+function getSubscribers(room) {
+  const existing = subscribersByRoom.get(room);
+  if (existing) return existing;
+  const subscribers = {
+    join: /* @__PURE__ */ new Set(),
+    leave: /* @__PURE__ */ new Set()
+  };
+  subscribersByRoom.set(room, subscribers);
+  room.onPeerJoin = (peerId) => {
+    for (const handler of [...subscribers.join]) handler(peerId);
+  };
+  room.onPeerLeave = (peerId) => {
+    for (const handler of [...subscribers.leave]) handler(peerId);
+  };
+  return subscribers;
+}
+function subscribeTrysteroPeerEvents(room, handlers) {
+  const subscribers = getSubscribers(room);
+  if (handlers.onJoin) subscribers.join.add(handlers.onJoin);
+  if (handlers.onLeave) subscribers.leave.add(handlers.onLeave);
+  return () => {
+    if (handlers.onJoin) subscribers.join.delete(handlers.onJoin);
+    if (handlers.onLeave) subscribers.leave.delete(handlers.onLeave);
+    if (subscribers.join.size === 0 && subscribers.leave.size === 0) {
+      room.onPeerJoin = null;
+      room.onPeerLeave = null;
+      subscribersByRoom.delete(room);
+    }
+  };
+}
+export {
+  subscribeTrysteroPeerEvents
+};

package/dist/serviceFeatures/checkRemoteSize.d.ts

@@ -1,10 +1,11 @@
 import { createInstanceLogFunction, type LogFunction } from "../services/lib/logUtils.js";
 import type { NecessaryServices } from "../interfaces/ServiceModule.js";
+type RemoteSizeReviewMode = "notice" | "dialogue";
 /**
  * Notify when checking remote storage size is not configured.
  * @returns true if the check is passed or user has configured the notification, false to block subsequent processes. (always true).
  */
-export declare function onNotifyRemoteSizeNotConfiguredFactory(host: NecessaryServices<"appLifecycle" | "API" | "setting", never>, log: ReturnType<typeof createInstanceLogFunction>): () => Promise<boolean>;
+export declare function onNotifyRemoteSizeNotConfiguredFactory(host: NecessaryServices<"appLifecycle" | "API" | "setting", never>, log: ReturnType<typeof createInstanceLogFunction>, mode?: RemoteSizeReviewMode): () => Promise<boolean>;
 /**
  * Notify when the remote storage size exceed the threshold.
  * @returns true if the check is passed or user has chosen to ignore the warning, false to block subsequent processes.
@@ -12,7 +13,7 @@ export declare function onNotifyRemoteSizeNotConfiguredFactory(host: NecessarySe
  * @param log
  * @returns
  */
-export declare function onNotifyRemoteSizeExceedFactory(host: NecessaryServices<"API" | "setting" | "replicator", "rebuilder">, log: ReturnType<typeof createInstanceLogFunction>): () => Promise<boolean>;
+export declare function onNotifyRemoteSizeExceedFactory(host: NecessaryServices<"API" | "setting" | "replicator", "rebuilder">, log: ReturnType<typeof createInstanceLogFunction>, mode?: RemoteSizeReviewMode): () => Promise<boolean>;
 /**
  * Scan the remote storage size and notify if it is not configured or exceed the threshold.
  * @param host The necessary services required for the operation.
@@ -20,9 +21,10 @@ export declare function onNotifyRemoteSizeExceedFactory(host: NecessaryServices<
  * @param resetThreshold Whether to reset the notification threshold before scanning. This is useful when you want to force the notification to show up again.
  * @returns A promise that resolves to true if all checks pass or user has configured the notification.
  */
-export declare function scanAllStat(host: NecessaryServices<"API" | "setting" | "replicator" | "appLifecycle", "rebuilder">, log: LogFunction, resetThreshold?: boolean): Promise<boolean>;
+export declare function scanAllStat(host: NecessaryServices<"API" | "setting" | "replicator" | "appLifecycle", "rebuilder">, log: LogFunction, resetThreshold?: boolean, mode?: RemoteSizeReviewMode): Promise<boolean>;
 /**
  * Associate the remote storage size check feature with the app lifecycle events.
  * @param host
  */
 export declare function useCheckRemoteSize(host: NecessaryServices<"API" | "setting" | "replicator" | "appLifecycle", "rebuilder">): void;
+export {};

package/dist/serviceFeatures/checkRemoteSize.js

@@ -2,7 +2,17 @@ import { sizeToHumanReadable } from "octagonal-wheels/number";
 import { LOG_LEVEL_INFO, LOG_LEVEL_NOTICE, LOG_LEVEL_VERBOSE } from "../common/types.js";
 import { createInstanceLogFunction } from "../services/lib/logUtils.js";
 import { EVENT_REQUEST_CHECK_REMOTE_SIZE } from "../events/coreEvents.js";
-function onNotifyRemoteSizeNotConfiguredFactory(host, log) {
+import { fireAndForget } from "../common/utils.js";
+const REMOTE_SIZE_NOTICE_DURATION_MS = 5 * 60 * 1e3;
+function configureReviewAnchor(anchor, label, review) {
+  anchor.href = "#";
+  anchor.textContent = label;
+  anchor.addEventListener("click", (event) => {
+    event.preventDefault();
+    fireAndForget(review);
+  });
+}
+function onNotifyRemoteSizeNotConfiguredFactory(host, log, mode = "notice") {
   return async () => {
     const translate = host.services.context.translate;
     log(translate("moduleCheckRemoteSize.logCheckingStorageSizes"), LOG_LEVEL_VERBOSE);
@@ -15,13 +25,25 @@ function onNotifyRemoteSizeNotConfiguredFactory(host, log) {
     const ANSWER_800 = translate("moduleCheckRemoteSize.option800MB");
     const ANSWER_2000 = translate("moduleCheckRemoteSize.option2GB");
     const ASK_ME_NEXT_TIME = translate("moduleCheckRemoteSize.optionAskMeLater");
+    if (mode === "notice") {
+      host.services.API.confirm.askInPopup(
+        "remote-size-not-configured",
+        translate("moduleCheckRemoteSize.noticeNotConfigured"),
+        (anchor) => configureReviewAnchor(
+          anchor,
+          translate("moduleCheckRemoteSize.optionReview"),
+          () => onNotifyRemoteSizeNotConfiguredFactory(host, log, "dialogue")()
+        ),
+        REMOTE_SIZE_NOTICE_DURATION_MS
+      );
+      return true;
+    }
     const ret = await host.services.API.confirm.askSelectStringDialogue(
       message,
       [ANSWER_0, ANSWER_800, ANSWER_2000, ASK_ME_NEXT_TIME],
       {
         defaultAction: ASK_ME_NEXT_TIME,
-        title: translate("moduleCheckRemoteSize.titleDatabaseSizeNotify"),
-        timeout: 40
+        title: translate("moduleCheckRemoteSize.titleDatabaseSizeNotify")
       }
     );
     if (ret == ANSWER_0) {
@@ -49,7 +71,7 @@ function onNotifyRemoteSizeNotConfiguredFactory(host, log) {
     return true;
   };
 }
-function onNotifyRemoteSizeExceedFactory(host, log) {
+function onNotifyRemoteSizeExceedFactory(host, log, mode = "notice") {
   return async () => {
     const translate = host.services.context.translate;
     const settings = host.services.setting.currentSettings();
@@ -89,13 +111,28 @@ function onNotifyRemoteSizeExceedFactory(host, log) {
       });
       const ANSWER_REBUILD = translate("moduleCheckRemoteSize.optionRebuildAll");
       const ANSWER_IGNORE = translate("moduleCheckRemoteSize.optionDismiss");
+      if (mode === "notice") {
+        host.services.API.confirm.askInPopup(
+          "remote-size-exceeded",
+          translate("moduleCheckRemoteSize.noticeExceeded", {
+            measuredSize: sizeToHumanReadable(estimatedSize),
+            notifySize: sizeToHumanReadable(maxSize)
+          }),
+          (anchor) => configureReviewAnchor(
+            anchor,
+            translate("moduleCheckRemoteSize.optionReview"),
+            () => onNotifyRemoteSizeExceedFactory(host, log, "dialogue")()
+          ),
+          REMOTE_SIZE_NOTICE_DURATION_MS
+        );
+        return true;
+      }
       const ret = await host.services.API.confirm.askSelectStringDialogue(
         message,
         [ANSWER_ENLARGE_LIMIT, ANSWER_REBUILD, ANSWER_IGNORE],
         {
           defaultAction: ANSWER_IGNORE,
-          title: translate("moduleCheckRemoteSize.titleDatabaseSizeLimitExceeded"),
-          timeout: 60
+          title: translate("moduleCheckRemoteSize.titleDatabaseSizeLimitExceeded")
         }
       );
       if (ret == ANSWER_REBUILD) {
@@ -142,7 +179,7 @@ function onNotifyRemoteSizeExceedFactory(host, log) {
     return true;
   };
 }
-async function scanAllStat(host, log, resetThreshold = false) {
+async function scanAllStat(host, log, resetThreshold = false, mode = "notice") {
   if (resetThreshold) {
     await host.services.setting.applyPartial(
       {
@@ -151,8 +188,8 @@ async function scanAllStat(host, log, resetThreshold = false) {
       true
     );
   }
-  const onNotifyNotConfigured = onNotifyRemoteSizeNotConfiguredFactory(host, log);
-  const onNotifyExceed = onNotifyRemoteSizeExceedFactory(host, log);
+  const onNotifyNotConfigured = onNotifyRemoteSizeNotConfiguredFactory(host, log, mode);
+  const onNotifyExceed = onNotifyRemoteSizeExceedFactory(host, log, mode);
   return await onNotifyNotConfigured() && await onNotifyExceed();
 }
 function useCheckRemoteSize(host) {
@@ -163,10 +200,13 @@ function useCheckRemoteSize(host) {
       id: "livesync-reset-remote-size-threshold-and-check",
       name: "Reset notification threshold and check the remote database usage",
       callback: async () => {
-        await scanAllStat(host, log, true);
+        await scanAllStat(host, log, true, "dialogue");
       }
     });
-    host.services.context.events.onEvent(EVENT_REQUEST_CHECK_REMOTE_SIZE, () => scanAllStat(host, log, true));
+    host.services.context.events.onEvent(
+      EVENT_REQUEST_CHECK_REMOTE_SIZE,
+      () => scanAllStat(host, log, true, "dialogue")
+    );
     return Promise.resolve(true);
   });
 }

package/dist/serviceFeatures/remoteConfig.d.ts

@@ -1,5 +1,6 @@
 import { type LOG_LEVEL } from "../common/logger.js";
-import type { ObsidianLiveSyncSettings } from "../common/models/setting.type.js";
+import { type RemoteConfigurationResult } from "../common/ConnectionString.js";
+import type { ObsidianLiveSyncSettings, RemoteConfiguration } from "../common/models/setting.type.js";
 import type { NecessaryServices } from "../interfaces/ServiceModule.js";
 export type RemoteConfigHost = NecessaryServices<"setting" | "UI" | "replication" | "control" | "appLifecycle" | "API", never>;
 export declare function migrateLegacyRemoteConfigurationsInPlace(settings: ObsidianLiveSyncSettings, log?: (message: string, level?: LOG_LEVEL) => void): boolean;
@@ -8,6 +9,41 @@ export declare function migrateLegacyRemoteConfigurationsInPlace(settings: Obsid
  * @returns A unique string identifier.
  */
 export declare function createRemoteConfigurationId(): string;
+export type SerializableRemoteConfigurationType = Exclude<RemoteConfigurationResult["type"], "webdav">;
+export interface UpsertRemoteConfigurationOptions {
+    /**
+     * Reuse this identifier to update a known profile. Omit it to allocate a new opaque identifier.
+     */
+    id?: string;
+    /**
+     * User-visible name. Omit it to derive a descriptive name from the connection settings.
+     */
+    name?: string;
+    /**
+     * Select this profile as the main remote and project it onto the compatibility fields.
+     */
+    activate?: boolean;
+    /**
+     * Select this profile for P2P features without changing the main remote selection.
+     */
+    activateForP2P?: boolean;
+}
+/**
+ * Suggest a concise display name from a serialisable remote configuration.
+ *
+ * The name is presentation only. Callers must continue to use the profile ID for identity and
+ * `activeConfigurationId` for the selected main remote.
+ */
+export declare function suggestRemoteConfigurationName(configuration: RemoteConfigurationResult): string;
+/**
+ * Create or update a multiple-remote profile from the corresponding compatibility fields.
+ *
+ * This mutates `settings`. Passing an existing `id` intentionally replaces that profile; omitting
+ * it always allocates a new opaque ID and preserves all existing profiles. Generated display names
+ * are made unique for readability, but names never act as identifiers. The stored connection URI is
+ * plaintext at this boundary; `SettingService` applies configured at-rest encryption when saving it.
+ */
+export declare function upsertRemoteConfigurationInPlace(settings: ObsidianLiveSyncSettings, type: SerializableRemoteConfigurationType, options?: UpsertRemoteConfigurationOptions): RemoteConfiguration;
 /**
  * Keep compatibility for users who were already using P2P as their main active remote.
  */

package/dist/serviceFeatures/remoteConfig.js

@@ -51,6 +51,94 @@ function migrateLegacyRemoteConfigurationsInPlace(settings, log) {
 function createRemoteConfigurationId() {
   return `remote-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`;
 }
+function toRemoteConfigurationResult(type, settings) {
+  if (type === "couchdb") {
+    return { type, settings };
+  }
+  if (type === "s3") {
+    return { type, settings };
+  }
+  return { type, settings };
+}
+function suggestRemoteConfigurationName(configuration) {
+  if (configuration.type === "couchdb") {
+    try {
+      const host = new URL(configuration.settings.couchDB_URI).host;
+      return host ? `CouchDB ${host}` : "CouchDB remote";
+    } catch {
+      return "CouchDB remote";
+    }
+  }
+  if (configuration.type === "s3") {
+    const bucket = configuration.settings.bucket.trim();
+    if (bucket) {
+      return `S3 ${bucket}`;
+    }
+    try {
+      const host = new URL(configuration.settings.endpoint).host;
+      return host ? `S3 ${host}` : "Object Storage remote";
+    } catch {
+      return "Object Storage remote";
+    }
+  }
+  if (configuration.type === "p2p") {
+    const room = configuration.settings.P2P_roomID.trim();
+    return room ? `P2P ${room}` : "P2P remote";
+  }
+  return "Remote configuration";
+}
+function allocateRemoteConfigurationId(configurations) {
+  let id = createRemoteConfigurationId();
+  while (configurations[id]) {
+    id = createRemoteConfigurationId();
+  }
+  return id;
+}
+function allocateRemoteConfigurationName(configurations, baseName, updatingId) {
+  const usedNames = new Set(
+    Object.values(configurations).filter((configuration) => configuration.id !== updatingId).map((configuration) => configuration.name)
+  );
+  if (!usedNames.has(baseName)) {
+    return baseName;
+  }
+  let suffix = 2;
+  while (usedNames.has(`${baseName} (${suffix})`)) {
+    suffix += 1;
+  }
+  return `${baseName} (${suffix})`;
+}
+function upsertRemoteConfigurationInPlace(settings, type, options = {}) {
+  if (options.activateForP2P && type !== "p2p") {
+    throw new Error("Only a P2P remote configuration can be selected for P2P features.");
+  }
+  const configurations = settings.remoteConfigurations ?? {};
+  const requestedId = options.id?.trim();
+  const id = requestedId || allocateRemoteConfigurationId(configurations);
+  const existing = configurations[id];
+  const serialisable = toRemoteConfigurationResult(type, settings);
+  const suggestedName = suggestRemoteConfigurationName(serialisable);
+  const requestedName = options.name?.trim();
+  const name = requestedName || existing?.name || allocateRemoteConfigurationName(configurations, suggestedName, existing?.id);
+  const configuration = {
+    id,
+    name,
+    uri: ConnectionStringParser.serialize(serialisable),
+    isEncrypted: false
+  };
+  settings.remoteConfigurations ??= configurations;
+  configurations[id] = configuration;
+  if (options.activate) {
+    if (!activateRemoteConfiguration(settings, id)) {
+      throw new Error(`Failed to activate remote configuration '${id}'.`);
+    }
+  }
+  if (options.activateForP2P) {
+    if (!activateP2PRemoteConfiguration(settings, id)) {
+      throw new Error(`Failed to activate P2P remote configuration '${id}'.`);
+    }
+  }
+  return configuration;
+}
 function migrateP2PActiveRemoteConfigurationIdInPlace(settings) {
   if ((settings.P2P_ActiveRemoteConfigurationId ?? "").trim() !== "") {
     return false;
@@ -242,6 +330,8 @@ export {
   migrateLegacyRemoteConfigurationsInPlace,
   migrateP2PActiveRemoteConfigurationIdInPlace,
   migrateToMultipleRemoteConfigurations,
+  suggestRemoteConfigurationName,
+  upsertRemoteConfigurationInPlace,
   useRemoteConfiguration,
   useRemoteConfigurationMigration
 };