astro-integration-pocketbase 0.2.0 → 1.0.0-next.1

package/README.md

@@ -1,7 +1,6 @@
 # astro-integration-pocketbase
 
-<!-- ![GitHub Actions Workflow Status](https://img.shields.io/github/actions/workflow/status/pawcoding/astro-integration-pocketbase/release.yaml?style=flat-square) -->
-
+![GitHub Actions Workflow Status](https://img.shields.io/github/actions/workflow/status/pawcoding/astro-integration-pocketbase/release.yaml?style=flat-square)
 [![NPM Version](https://img.shields.io/npm/v/astro-integration-pocketbase?style=flat-square)](https://www.npmjs.com/package/astro-integration-pocketbase)
 [![NPM Downloads](https://img.shields.io/npm/dw/astro-integration-pocketbase?style=flat-square)](https://www.npmjs.com/package/astro-integration-pocketbase)
 [![GitHub License](https://img.shields.io/github/license/pawcoding/astro-integration-pocketbase?style=flat-square)](https://github.com/pawcoding/astro-integration-pocketbase/blob/master/LICENSE)
@@ -11,9 +10,11 @@ This package provides an Astro toolbar for users of [astro-loader-pocketbase](ht
 
 ![PocketBase Toolbar](/assets/toolbar.png)
 
-> [!WARNING]
-> This package is still under development.
-> Until the first stable 1.0 release **breaking changes can occur at any time**.
+## Compatibility
+
+| Integration | Loader | Astro | PocketBase |
+| ----------- | ------ | ----- | ---------- |
+| 1.0.0       | 2.0.0  | 5.0.0 | >= 0.23.0  |
 
 ## Basic usage
 
@@ -40,6 +41,29 @@ If you click on the icon, you can see the PocketBase entity viewer.
 
 If a loader is found, the viewer will show a refresh button to reload all entries from the loaders.
 
+## Realtime updates
+
+PocketBase allows you to subscribe to collection changes via its [Realtime API](https://pocketbase.io/docs/api-realtime/).
+This integration allows you to subscribe to these changes and reload the entries / collections.
+Note that Node.js currently does not support the [EventSource](https://developer.mozilla.org/en-US/docs/Web/API/EventSource) API, so the integration uses the [eventsource](https://www.npmjs.com/package/eventsource) package to provide the same functionality.
+
+If you want realtime updates for collections with a [restricted list / search rule](https://pocketbase.io/docs/api-rules-and-filters/), you need to provide superuser credentials to the integration.
+
+```ts
+pocketbaseIntegration({
+  ...options,
+  // List of PocketBase collections to watch for changes
+  collectionsToWatch: ["posts", "comments"],
+  // Superuser credentials for restricted collections (optional)
+  superuserCredentials: {
+    email: "<superuser-email>",
+    password: "<superuser-password>"
+  }
+});
+```
+
+**Tip:** You can disable the realtime updates temporarily via the toolbar.
+
 ## Entity viewer
 
 To view the PocketBase entries inside the entity viewer, you need to use `Astro.props` to pass the entries to your page (and thus to the toolbar).
@@ -82,6 +106,8 @@ The integration will automatically detect PocketBase entries in the props and di
 
 ## All options
 
-| Option | Type     | Required | Description                          |
-| ------ | -------- | -------- | ------------------------------------ |
-| `url`  | `string` | x        | The URL of your PocketBase instance. |
+| Option                 | Type                                  | Required | Description                                                                                                                   |
+| ---------------------- | ------------------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------- |
+| `url`                  | `string`                              | x        | The URL of your PocketBase instance.                                                                                          |
+| `collectionsToWatch`   | `Array<string>`                       |          | Collections to watch for changes.                                                                                             |
+| `superuserCredentials` | `{ email: string, password: string }` |          | The email and password of a superuser of the PocketBase instance. This is used for realtime updates of restricted collection. |

package/index.ts

@@ -1,3 +1,5 @@
 import { pocketbaseIntegration } from "./src/pocketbase-integration";
+import type { PocketBaseIntegrationOptions } from "./src/types/pocketbase-integration-options.type";
 
 export { pocketbaseIntegration };
+export type { PocketBaseIntegrationOptions };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "astro-integration-pocketbase",
-  "version": "0.2.0",
+  "version": "1.0.0-next.1",
   "license": "MIT",
   "author": "Luis Wolf <development@pawcode.de> (https://pawcode.de)",
   "homepage": "https://github.com/pawcoding/astro-integration-pocketbase",
@@ -17,18 +17,20 @@
     "prepare": "husky"
   },
   "peerDependencies": {
-    "astro": "^4.0.0 || ^5.0.0"
+    "astro": "^5.0.0",
+    "eventsource": "^3.0.2"
   },
   "devDependencies": {
-    "@eslint/js": "^9.12.0",
-    "@stylistic/eslint-plugin": "^2.9.0",
-    "@types/node": "^22.7.4",
-    "astro": "^5.0.0-beta.3",
-    "eslint": "^9.12.0",
-    "globals": "^15.10.0",
-    "husky": "^9.1.6",
-    "typescript": "^5.6.2",
-    "typescript-eslint": "^8.8.0"
+    "@eslint/js": "^9.17.0",
+    "@stylistic/eslint-plugin": "^2.12.1",
+    "@types/node": "^22.10.2",
+    "astro": "^5.1.1",
+    "eslint": "^9.17.0",
+    "eventsource": "^3.0.2",
+    "globals": "^15.14.0",
+    "husky": "^9.1.7",
+    "typescript": "^5.7.2",
+    "typescript-eslint": "^8.18.2"
   },
   "keywords": [
     "astro",

package/src/core/index.ts

@@ -0,0 +1,2 @@
+export * from "./refresh-collections";
+export * from "./refresh-collections-realtime";

package/src/core/refresh-collections-realtime.ts

@@ -0,0 +1,134 @@
+import type { BaseIntegrationHooks } from "astro";
+import { EventSource } from "eventsource";
+import type { PocketBaseIntegrationOptions } from "../types/pocketbase-integration-options.type";
+import { getSuperuserToken } from "../utils/get-superuser-token";
+
+export function refreshCollectionsRealtime(
+  {
+    url,
+    superuserCredentials,
+    collectionsToWatch
+  }: PocketBaseIntegrationOptions,
+  {
+    logger,
+    refreshContent,
+    toolbar
+  }: Parameters<BaseIntegrationHooks["astro:server:setup"]>[0]
+): EventSource | undefined {
+  // Check if collections should be watched
+  if (!collectionsToWatch || collectionsToWatch.length === 0) {
+    return undefined;
+  }
+
+  // Check if content loader is used
+  if (!refreshContent) {
+    logger.warn(
+      "No content loader available, skipping subscription to PocketBase realtime API."
+    );
+    return undefined;
+  }
+
+  // Check if EventSource is available
+  if (!EventSource) {
+    logger.warn(
+      "EventSource is not available, skipping subscription to PocketBase realtime API.\n" +
+        "Please install the 'eventsource' package."
+    );
+    return undefined;
+  }
+
+  let refreshEnabled = true;
+  // Enable or disable real-time updates via the toolbar
+  toolbar.on("astro-integration-pocketbase:real-time", (enabled: boolean) => {
+    refreshEnabled = enabled;
+  });
+
+  const eventSource = new EventSource(`${url}/api/realtime`);
+  let wasConnectedOnce = false;
+  let isConnected = false;
+
+  // Log potential errors
+  eventSource.onerror = (error) => {
+    isConnected = false;
+
+    // Wait for 5 seconds in case of a connection error
+    setTimeout(() => {
+      if (isConnected) {
+        // Connection was automatically re-established, no need to log the error
+        return;
+      }
+
+      logger.error(
+        `Error while connecting to PocketBase realtime API: ${error.type}`
+      );
+    }, 5000);
+  };
+
+  // Add event listeners for all collections
+  for (const collection of collectionsToWatch) {
+    eventSource.addEventListener(`${collection}/*`, async () => {
+      // Do not refresh if the refresh is disabled
+      if (!refreshEnabled) {
+        return;
+      }
+
+      // Refresh the content
+      logger.info(`Received update for ${collection}. Refreshing content...`);
+      await refreshContent({
+        loaders: ["pocketbase-loader"],
+        // TODO: add context to refresh one or all collections
+        context: {}
+      });
+    });
+  }
+
+  // Add event listener for the connection event
+  eventSource.addEventListener("PB_CONNECT", async (event) => {
+    // Extract the clientId
+    const clientId = event.lastEventId;
+
+    // Get the superuser token if credentials are available
+    let superuserToken: string | undefined;
+    if (superuserCredentials) {
+      superuserToken = await getSuperuserToken(
+        url,
+        superuserCredentials,
+        logger
+      );
+    }
+
+    // Subscribe to the PocketBase realtime API
+    const result = await fetch(`${url}/api/realtime`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: superuserToken || ""
+      },
+      body: JSON.stringify({
+        clientId: clientId,
+        subscriptions: collectionsToWatch.map((collection) => `${collection}/*`)
+      })
+    });
+
+    // Log the connection status
+    if (!result.ok) {
+      logger.error(
+        `Error while subscribing to PocketBase realtime API: ${result.status}`
+      );
+      return;
+    }
+
+    if (!wasConnectedOnce) {
+      wasConnectedOnce = true;
+      logger.info(
+        `Subscribed to PocketBase realtime API. Waiting for updates on ${collectionsToWatch.join(
+          ", "
+        )}.`
+      );
+    }
+
+    isConnected = true;
+  });
+
+  return eventSource;
+}

package/src/core/refresh-collections.ts

@@ -0,0 +1,38 @@
+import type { BaseIntegrationHooks } from "astro";
+
+/**
+ * Listen for the refresh event of the toolbar.
+ * When the event is triggered in the toolbar, refresh the content loaded by the PocketBase loader.
+ */
+export function handleRefreshCollections({
+  toolbar,
+  refreshContent,
+  logger
+}: Parameters<BaseIntegrationHooks["astro:server:setup"]>[0]): void {
+  if (!refreshContent) {
+    return;
+  }
+
+  logger.info("Setting up refresh listener for PocketBase integration");
+
+  // Listen for the refresh event of the toolbar
+  toolbar.on("astro-integration-pocketbase:refresh", async () => {
+    // Send a loading state to the toolbar
+    toolbar.send("astro-integration-pocketbase:refresh", {
+      loading: true
+    });
+
+    // Refresh content loaded by the PocketBase loader
+    logger.info("Refreshing content loaded by PocketBase loader");
+    await refreshContent({
+      loaders: ["pocketbase-loader"],
+      // TODO: add context to refresh one or all collections
+      context: {}
+    });
+
+    // Reset the loading state in the toolbar
+    toolbar.send("astro-integration-pocketbase:refresh", {
+      loading: false
+    });
+  });
+}

package/src/pocketbase-integration.ts

@@ -1,11 +1,15 @@
 import type { AstroIntegration } from "astro";
+import { EventSource } from "eventsource";
 import { fileURLToPath } from "node:url";
+import { handleRefreshCollections, refreshCollectionsRealtime } from "./core";
+import type { ToolbarOptions } from "./toolbar/types/options";
+import type { PocketBaseIntegrationOptions } from "./types/pocketbase-integration-options.type";
+
+export function pocketbaseIntegration(
+  options: PocketBaseIntegrationOptions
+): AstroIntegration {
+  let eventSource: EventSource | undefined = undefined;
 
-export function pocketbaseIntegration({
-  url
-}: {
-  url: string;
-}): AstroIntegration {
   return {
     name: "pocketbase-integration",
     hooks: {
@@ -29,38 +33,27 @@ export function pocketbaseIntegration({
           entrypoint: fileURLToPath(new URL("./middleware", import.meta.url))
         });
       },
-      "astro:server:setup": ({ toolbar, logger, refreshContent }) => {
-        // Setup the listener for the refresh event if a loader is available
-        if (refreshContent) {
-          logger.info("Setting up refresh listener for PocketBase integration");
-          // Listen for the refresh event of the toolbar
-          toolbar.on("astro-integration-pocketbase:refresh", async () => {
-            // Send a loading state to the toolbar
-            toolbar.send("astro-integration-pocketbase:refresh", {
-              loading: true
-            });
-
-            // Refresh content loaded by the PocketBase loader
-            await refreshContent({
-              loaders: ["pocketbase-loader"],
-              // TODO: add context to refresh one or all collections
-              context: {}
-            });
+      "astro:server:setup": (setupOptions) => {
+        // Listen for the refresh event of the toolbar
+        handleRefreshCollections(setupOptions);
 
-            // Reset the loading state in the toolbar
-            toolbar.send("astro-integration-pocketbase:refresh", {
-              loading: false
-            });
-          });
-        }
+        // Subscribe to PocketBase realtime API
+        eventSource = refreshCollectionsRealtime(options, setupOptions);
 
         // Send settings to the toolbar on initialization
-        toolbar.onAppInitialized("pocketbase-entry", () => {
-          toolbar.send("astro-integration-pocketbase:settings", {
-            enabled: !!refreshContent,
-            baseUrl: url
-          });
+        setupOptions.toolbar.onAppInitialized("pocketbase-entry", () => {
+          setupOptions.toolbar.send("astro-integration-pocketbase:settings", {
+            hasContentLoader: !!setupOptions.refreshContent,
+            realtime: !!eventSource,
+            baseUrl: options.url
+          } satisfies ToolbarOptions);
         });
+      },
+      "astro:server:done": () => {
+        // Close the EventSource connection when the server is done
+        if (eventSource) {
+          eventSource.close();
+        }
       }
     }
   };

package/src/toolbar/dom/create-header.ts

@@ -2,12 +2,16 @@ import type { ToolbarServerHelpers } from "astro";
 import type { DevToolbarButton } from "astro/runtime/client/dev-toolbar/ui-library/button.js";
 import { default as packageJson } from "../../../package.json";
 
+export interface HeaderElements {
+  header: HTMLElement;
+  refresh: DevToolbarButton;
+  toggleContainer: HTMLDivElement;
+}
+
 /**
  * Creates the header for the PocketBase toolbar.
  */
-export function createHeader(
-  server: ToolbarServerHelpers
-): [HTMLElement, DevToolbarButton] {
+export function createHeader(server: ToolbarServerHelpers): HeaderElements {
   // Create the header
   const header = document.createElement("header");
   header.style.display = "grid";
@@ -26,18 +30,62 @@ export function createHeader(
   version.badgeStyle = "yellow";
   header.appendChild(version);
 
+  // Create the actions container
+  const actions = document.createElement("div");
+  actions.style.display = "flex";
+  actions.style.alignItems = "start";
+  actions.style.justifyContent = "flex-end";
+  actions.style.gap = "0.25rem";
+  header.appendChild(actions);
+
+  // Create the real-time toggle
+  const toggleContainer = document.createElement("div");
+  toggleContainer.style.alignItems = "center";
+  // The toggle container is hidden by default
+  toggleContainer.style.display = "none";
+  actions.appendChild(toggleContainer);
+
+  const toggleLabel = document.createElement("label");
+  toggleLabel.textContent = "Real-time updates";
+  toggleLabel.htmlFor = "real-time-toggle";
+  toggleLabel.style.fontSize = "0.8rem";
+  toggleContainer.appendChild(toggleLabel);
+
+  const toggle = document.createElement("astro-dev-toolbar-toggle");
+  toggle.input.id = "real-time-toggle";
+  // Set the toggle state based on the local storage, default to true
+  toggle.input.checked = !(
+    localStorage.getItem("astro-integration-pocketbase:real-time") === "false"
+  );
+  toggle.input.addEventListener("change", () => {
+    // Store the toggle state in the local storage
+    localStorage.setItem(
+      "astro-integration-pocketbase:real-time",
+      toggle.input.checked.toString()
+    );
+
+    // Send the toggle state to the server
+    server.send("astro-integration-pocketbase:real-time", toggle.input.checked);
+  });
+  // Send the initial toggle state to the server
+  server.send("astro-integration-pocketbase:real-time", toggle.input.checked);
+  toggleContainer.appendChild(toggle);
+
   // Create the refresh button
   const refresh = document.createElement("astro-dev-toolbar-button");
   refresh.size = "small";
   refresh.buttonStyle = "green";
-  refresh.style.marginLeft = "auto";
   refresh.textContent = "Refresh content";
   // The refresh button is hidden by default
   refresh.style.display = "none";
   refresh.addEventListener("click", () => {
     server.send("astro-integration-pocketbase:refresh", true);
   });
-  header.appendChild(refresh);
+  actions.appendChild(refresh);
 
-  return [header, refresh];
+  return {
+    header,
+    refresh,
+    toggleContainer
+  };
 }

package/src/toolbar/init-toolbar.ts

@@ -5,6 +5,7 @@ import type {
 import { createEntity, createHeader, createPlaceholder } from "./dom/";
 import { listenToNavigation } from "./page-navigation-listener";
 import type { Entity } from "./types/entity";
+import type { ToolbarOptions } from "./types/options";
 
 declare global {
   interface Window {
@@ -25,7 +26,7 @@ export async function initToolbar(
 
   const container = document.createElement("astro-dev-toolbar-window");
 
-  const [header, refresh] = createHeader(server);
+  const { header, refresh, toggleContainer } = createHeader(server);
   container.appendChild(header);
 
   // Container for the main content
@@ -101,12 +102,17 @@ export async function initToolbar(
 
   server.on(
     "astro-integration-pocketbase:settings",
-    ({ enabled, baseUrl }: { enabled: boolean; baseUrl: string }) => {
+    ({ hasContentLoader, realtime, baseUrl }: ToolbarOptions) => {
       // Show the refresh button if a loader is available
-      if (enabled) {
+      if (hasContentLoader) {
         refresh.style.display = "unset";
       }
 
+      // Show the real-time toggle if real-time updates are available
+      if (realtime) {
+        toggleContainer.style.display = "flex";
+      }
+
       // Store the base URL for later use
       pbUrl = baseUrl;
     }

package/src/toolbar/types/options.ts

@@ -0,0 +1,17 @@
+/**
+ * Options for the toolbar.
+ */
+export interface ToolbarOptions {
+  /**
+   * Whether a content loader is active.
+   */
+  hasContentLoader: boolean;
+  /**
+   * Whether a realtime connection to PocketBase is active.
+   */
+  realtime: boolean;
+  /**
+   * Base URL of the PocketBase instance.
+   */
+  baseUrl: string;
+}

package/src/types/pocketbase-integration-options.type.ts

@@ -0,0 +1,28 @@
+/**
+ * Options for the PocketBase integration.
+ */
+export interface PocketBaseIntegrationOptions {
+  /**
+   * URL of the PocketBase instance.
+   */
+  url: string;
+  /**
+   * Credentials of a superuser to get full access to the PocketBase instance.
+   * This is required to access all resources even if they are not public.
+   */
+  superuserCredentials?: {
+    /**
+     * Email of the superuser.
+     */
+    email: string;
+    /**
+     * Password of the superuser.
+     */
+    password: string;
+  };
+  /**
+   * List of PocketBase collections to watch for changes.
+   * When an entry in one of these collections changes, the content will be reloaded.
+   */
+  collectionsToWatch?: Array<string>;
+}

package/src/utils/get-superuser-token.ts

@@ -0,0 +1,46 @@
+import type { AstroIntegrationLogger } from "astro";
+
+/**
+ * This function will get a superuser token from the given PocketBase instance.
+ *
+ * @param url URL of the PocketBase instance
+ * @param superuserCredentials Credentials of the superuser
+ *
+ * @returns A superuser token to access all resources of the PocketBase instance.
+ */
+export async function getSuperuserToken(
+  url: string,
+  superuserCredentials: {
+    email: string;
+    password: string;
+  },
+  logger: AstroIntegrationLogger
+): Promise<string | undefined> {
+  // Build the URL for the login endpoint
+  const loginUrl = new URL(
+    `api/collections/_superusers/auth-with-password`,
+    url
+  ).href;
+
+  // Create a new FormData object to send the login data
+  const loginData = new FormData();
+  loginData.set("identity", superuserCredentials.email);
+  loginData.set("password", superuserCredentials.password);
+
+  // Send the login request to get a token
+  const loginRequest = await fetch(loginUrl, {
+    method: "POST",
+    body: loginData
+  });
+
+  // If the login request was not successful, print the error message and return undefined
+  if (!loginRequest.ok) {
+    const reason = await loginRequest.json().then((data) => data.message);
+    const errorMessage = `The given email / password for ${url} was not correct. Astro may not have access to all resources and permissions.\nReason: ${reason}`;
+    logger.error(errorMessage);
+    return undefined;
+  }
+
+  // Return the token
+  return await loginRequest.json().then((data) => data.token);
+}