Updated docs

docs/.vitepress/config.mts

@@ -52,7 +52,7 @@ export default defineConfig({
           { text: 'Usage with Node.js', link: '/nodejs' },
           { text: 'Usage in Cordova apps', link: '/cordova' },
           { text: 'Usage with TypeScript', link: '/typescript' },
-          { text: 'Dropbox and Google Drive', link: '/dropbox-and-google-drive' },
+          { text: 'Dropbox, Google Drive and Solid', link: '/dropbox-googledrive-solid' },
         ]
       },
       {

docs/dropbox-and-google-drive.md → docs/dropbox-googledrive-solid.md

@@ -1,9 +1,9 @@
-# Offering Dropbox and Google Drive storage options
+# Offering Dropbox, Google Drive, and Solid storage options
 
 ![Screenshot of the connect-widget choose-backend screen](./images/screenshot-widget-choose.png){width="50%"}
 
-rs.js has optional support for syncing data with Dropbox and Google
-Drive instead of a RemoteStorage server.
+rs.js has optional support for syncing data with Dropbox, Google
+Drive, and Solid instead of a RemoteStorage server.
 
 There are a few drawbacks, mostly sync performance and the lack of a
 permission model. So apps can usually access all of a user's storage
@@ -29,6 +29,23 @@ only the available storage options, based on the presence of the Dropbox and
 Google Drive API keys. RemoteStorage is always enabled.
 :::
 
+For the Solid backend you have to specify the available authentication URLs
+for the user to choose from on the connect widget's configurations. Once
+configured, it will also show Solid as an available storage option. Like so:
+
+```js
+const config = {
+    solidProviders: {
+        providers: [
+            Widget.SOLID_COMMUNITY,
+            Widget.INRUPT
+        ],
+        allowAnyProvider: true
+    }
+};
+const widget = new Widget(remoteStorage, config);
+```
+
 ## Dropbox
 
 An app key can be obtained by [registering your
@@ -75,3 +92,23 @@ Console](https://console.developers.google.com/flows/enableapi?apiid=drive).
 
 - Sharing public files is not supported yet (see issue 1051)
 - `getItemURL` is not implemented yet (see issue 1054)
+
+## Solid
+
+An authentication URL must always have been set on the Solid backend before
+calling `connect()`. You can do so by calling `setAuthURL()` first.
+
+The connect widget accepts a list of authentication URLs as configuration
+and automatically sets it on the Solid backend when selected.
+
+Each option consists of two keys: `authURL` which is the authentication URL
+to connect to. And a `name` to be displayed on the widget. The
+`allowAnyProvider` option if set to `true`, adds an input box to the widget
+to allow the user to type any authentication URL of their choosing.
+
+::: info
+The Solid backend exposes the connected session. It is the `Session` object
+from the [Inrupt](https://docs.inrupt.com/developer-tools/javascript/client-libraries/)
+Solid library. It can be accessed by calling `remoteStorage.solid.getSession()`
+only after the backend is connected.
+:::

docs/index.md

@@ -12,7 +12,7 @@ Welcome to the remoteStorage.js documentation!
 remoteStorage.js is a JavaScript/TypeScript library for storing user data
 locally in the browser, as well as connecting to [remoteStorage](/) servers and
 syncing data across devices and applications. It is also capable of connecting
-and syncing data with a person\'s Dropbox or Google Drive account (optional).
+and syncing data with a person\'s Dropbox, Google Drive, or Solid account (optional).
 
 > [!NOTE]
 > For brevity\'s sake, we will also use the short name **rs.js** across these docs.

docs/why.md

@@ -56,10 +56,10 @@ critical bug, there\'s a team of people who will help with fixing it.
 
 ## One JS API for multiple storage options
 
-rs.js optionally supports Dropbox and Google Drive as storage backends which
-users can connect. Conveniently, as an app developer you don\'t have to
+rs.js optionally supports Dropbox, Google Drive and Solid as storage backends
+which users can connect. Conveniently, as an app developer you don\'t have to
 implement anything special in order for these backends to work with your code.
-Just [configure OAuth app keys](./dropbox-and-google-drive), and
+Just [configure OAuth app keys](./dropbox-googledrive-solid), and
 your users can choose between 3 different backends to connect. If you're not
 using the [connect widget](./getting-started/connect-widget), you may need to
 create additional UI for these alternate backends.

release/remotestorage.js

@@ -56821,7 +56821,6 @@ function unHookGetItemURL(rs) {
  * @param {XMLHttpRequestBodyInit} body - Request body
  * @returns {Blob} Blob equivalent of the body
  *
- *
  * @private
  */
 function requestBodyToBlob(body) {
@@ -56853,36 +56852,31 @@ function requestBodyToBlob(body) {
 /**
  * @class Solid
  *
- * To use this backend, you need to specify the authURL like so:
+ * To use this backend, you need to specify the authURL before calling connect like so:
  *
  * @example
- * remoteStorage.setAuthURL('https://login.example.com');
+ * solid.setAuthURL('https://login.example.com');
+ * solid.connect();
  *
- * In order to set the Solid options for the widget you have to specify the valid options like so:
+ * If connect is successful a list of available pods for the Solid account is retrieved and
+ * a `pod-not-selected` event is fired. After receiving this event you have to call getPodURLs
+ * to get the list of available pods and set one of them to be used by calling setPodURL. After
+ * setting the pod URL the `connected` event is fired.
  *
- * @example
- * remoteStorage.setApiKeys({
- *   solid: {
- *     providers: [
- *       {
- *         name: "provider name",
- *         authURL: "auth URL"
- *       }
- *     ],
- *     allowAnyProvider: true|false
- *   }
- * });
+ * You can find a list of running solid servers on the solid project website here:
+ * https://solidproject.org/for-developers#hosted-pod-services
 **/
 class Solid extends remote_1.RemoteBase {
     constructor(remoteStorage) {
         super(remoteStorage);
-        this.podURLs = [];
+        this.podURLs = null;
         this.online = true;
-        this.storageApi = 'draft-dejong-remotestorage-19';
         this.addEvents(['connected', 'not-connected', 'pod-not-selected']);
+        // We use a custom ConfigStore to store the solid session in a rs friendly manner to
+        // make configuration and disconnect work.
         this.configStorage = new solidStorage_1.default(this);
         this.session = new solid_client_authn_browser_1.Session({
-            secureStorage: new solid_client_authn_browser_1.InMemoryStorage(),
+            secureStorage: new solid_client_authn_browser_1.InMemoryStorage(), // Inrupt prefers InMemoryStorage for tokens. We respect that.
             insecureStorage: this.configStorage
         }, 'any');
         hasLocalStorage = (0, util_1.localStorageAvailable)();
@@ -56893,6 +56887,15 @@ class Solid extends remote_1.RemoteBase {
             }
         }
     }
+    /**
+     * Solid Session storage state changed.
+     *
+     * This function is called by the ConfigStore that we provided to Session as an insecure storage.
+     *
+     * @param {string} config - The entire Session configuration object serialized into a string
+     *
+     * @private
+     */
     onConfigChanged(config) {
         if (config) {
             const sessionConfig = JSON.parse(config);
@@ -56911,6 +56914,7 @@ class Solid extends remote_1.RemoteBase {
                 return;
             }
         }
+        this.podURLs = null;
         localStorage.removeItem(SETTINGS_KEY);
     }
     /**
@@ -56969,6 +56973,7 @@ class Solid extends remote_1.RemoteBase {
         const handleError = function () {
             this.connected = false;
             this.sessionProperties = null;
+            this.podURLs = null;
             if (hasLocalStorage) {
                 localStorage.removeItem(SETTINGS_KEY);
             }
@@ -56984,18 +56989,40 @@ class Solid extends remote_1.RemoteBase {
     }
     /**
      * Set the auth URL
+     *
      * @param {string} authURL - Auth URL
+     *
+     * @public
      */
     setAuthURL(authURL) {
         this.authURL = authURL;
     }
     /**
+     * Get a list of pod URLs for this Solid account.
+     *
+     * If the Solid Session is not connected, this function returns null.
      *
      * @returns Get the list of pod URLs
+     *
+     * @public
      */
     getPodURLs() {
         return this.podURLs;
     }
+    /**
+     * Set the pod URL to use as the storage.
+     *
+     * Pod URL must be one of the URLs provided by the getPodURLs function. This function does
+     * not validate this constraint.
+     *
+     * If the Solid Session is connected and the pod URL is updated to be null, a
+     * `pod-not-selected` event will be fired. If Session is connected and the pod URL is set,
+     * a `connected` event will be fired.
+     *
+     * @param {string} podURL - URL of the pod to be used as storage
+     *
+     * @public
+     */
     setPodURL(podURL) {
         if (this.selectedPodURL === podURL) {
             return;
@@ -57023,11 +57050,20 @@ class Solid extends remote_1.RemoteBase {
             }
         }
     }
+    /**
+     * Get the pod URL that is being used as the storage.
+     *
+     * @returns {string} The in-use pod URL or null
+     *
+     * @public
+     */
     getPodURL() {
         return this.selectedPodURL;
     }
     /**
      * Initiate the authorization flow's OAuth dance.
+     *
+     * @public
      */
     connect() {
         this.rs.setBackend('solid');
@@ -57044,18 +57080,19 @@ class Solid extends remote_1.RemoteBase {
     /**
      * Get the connected Solid session
      *
-     * @returns {Session} that is being used by this instance
+     * @returns {Session} that is being used by this instance or null if Session is not connected
+     *
+     * @public
      */
     getSession() {
-        return (this.session.info && this.session.info.isLoggedIn) ? this.session : undefined;
+        return (this.session.info && this.session.info.isLoggedIn) ? this.session : null;
     }
     /**
      * Convert path to file URL
      *
      * @param {string} path - Path of the resource
      * @returns {string} Full URL of the resource on the pod
      *
-     *
      * @private
      */
     getFileURL(path) {
@@ -57101,7 +57138,7 @@ class Solid extends remote_1.RemoteBase {
                     statusCode: 200,
                     body: listing,
                     contentType: 'application/json; charset=UTF-8',
-                    // revision: ?
+                    // revision: ? Skipping ETag
                 });
             }).catch(error => {
                 if (error instanceof solid_client_1.FetchError) {