@hivedev/hivesdk 1.0.39 → 1.0.41

package/README.md

@@ -10,6 +10,7 @@ Every service in the Hive ecosystem (NoteHive, and any future service) is built
 
 - [Concepts](#concepts)
 - [Installation](#installation)
+- [ESM vs CJS — Which to Use](#esm-vs-cjs--which-to-use)
 - [Server SDK](#server-sdk)
   - [1. Initialising the Server](#1-initialising-the-server)
   - [2. Registering the Service](#2-registering-the-service)
@@ -54,9 +55,47 @@ npm install @hivedev/hivesdk
 ```
 
 The SDK ships three pre-built files:
-- `hive-server.js` — ESM bundle for Node.js backends
-- `hive-server.cjs` — CJS bundle for Node.js backends
-- `hive-client.js` — ESM bundle for browser frontends
+
+| File | Format | For |
+|------|--------|-----|
+| `hive-server.js` | ESM | Node.js backends with `"type": "module"` in `package.json` |
+| `hive-server.cjs` | CJS | Node.js backends without `"type": "module"` |
+| `hive-client.js` | ESM | Browser frontends only |
+
+> **Peer dependencies:** `nodemailer` and `mongodb` are not bundled into the SDK. Install them in your service:
+> ```bash
+> npm install nodemailer mongodb
+> ```
+
+---
+
+## ESM vs CJS — Which to Use
+
+The SDK provides both an ESM and a CJS build for the server. **You use one or the other depending on your own application's module system — never both.**
+
+**If your `package.json` has `"type": "module"`**, your project is ESM. Use `import`:
+
+```js
+import { initServer } from "@hivedev/hivesdk/server";
+```
+
+**If your `package.json` does not have `"type": "module"`** (or explicitly has `"type": "commonjs"`), your project is CJS. Use `require`:
+
+```js
+const { initServer } = require("@hivedev/hivesdk/server");
+```
+
+Mixing them will fail. Using `require()` in an ESM project throws:
+
+```
+ReferenceError: require is not defined in ES module scope
+```
+
+Using `import` in a CJS project throws a syntax error. Check your `package.json` once and use the matching syntax everywhere.
+
+All examples below show both variants. Use whichever matches your project.
+
+> **Note:** CJS does not support top-level `await`. All async SDK calls in CJS must be wrapped in an `async` function or an async IIFE — `(async () => { ... })()`. The examples below show this where needed.
 
 ---
 
@@ -71,10 +110,10 @@ Call `initServer` once at the very start of your service, before anything else.
 import { initServer } from "@hivedev/hivesdk/server";
 
 await initServer({
-    serviceName: "NoteHive",       // Must match the name registered in HivePortal
-    servicePort: 49161,            // The port this service listens on
-    remoteUrl: "",                 // Public-facing URL if accessible from outside LAN, empty string if LAN-only
-    serverPassword: ""             // Optional — see password resolution below
+    serviceName: "NoteHive",    // Must match the name registered in HivePortal
+    servicePort: 49161,         // The port this service listens on
+    remoteUrl: "",              // Public-facing URL if accessible from outside LAN, empty if LAN-only
+    serverPassword: ""          // Optional — see password resolution below
 });
 ```
 
@@ -82,19 +121,22 @@ await initServer({
 // CJS
 const { initServer } = require("@hivedev/hivesdk/server");
 
-await initServer({
-    serviceName: "NoteHive",
-    servicePort: 49161,
-    remoteUrl: "",
-    serverPassword: ""
-});
+(async () =>
+{
+    await initServer({
+        serviceName: "NoteHive",
+        servicePort: 49161,
+        remoteUrl: "",
+        serverPassword: ""
+    });
+})();
 ```
 
 **Password resolution order:**
 
 1. The `serverPassword` argument, if provided.
 2. The `SERVER_PASSWORD` environment variable, if set.
-3. An interactive terminal prompt, if neither of the above is available — it will ask the user to create a password on first run, or enter their existing password on subsequent runs.
+3. An interactive terminal prompt — asks the user to create a password on first run, or enter their existing password on subsequent runs.
 
 The password is used as the encryption key for all `.dat` configuration files. Losing it means losing access to the stored configuration.
 
@@ -117,34 +159,33 @@ await registerService();
 // CJS
 const { registerService } = require("@hivedev/hivesdk/server");
 
-await registerService();
+await registerService(); // inside an async function or IIFE
 ```
 
 What this does internally:
 
 1. Sets the service's local URL (`http://<hostIp>:<servicePort>`) and remote URL in the internal registry.
 2. POSTs to HivePortal's `/RegisterService` endpoint.
-3. If HivePortal accepts the request, begins polling HivePortal's `/Configuration` endpoint every 2 seconds.
-4. Once an administrator approves the service in HivePortal, the configuration payload is received, decrypted, and saved to disk via `saveConfiguration`.
+3. Begins polling HivePortal's `/Configuration` endpoint every 2 seconds.
+4. Once an administrator approves the service in HivePortal, the configuration payload is received, decrypted, and saved to disk.
 
 **On first run**, the terminal will show:
 
 ```
 Registering service...
 Service registration hasn't been approved yet. Please contact administrators!
-Service registration hasn't been approved yet. Please contact administrators!
 ...
 Configuration received.
 Saving configuration...
 Service registered.
 ```
 
-Once registered and approved, subsequent startups load configuration from disk directly via `loadConfiguration` and do not need to poll again, unless credentials change in HivePortal.
+Once registered and approved, subsequent startups load configuration from disk directly and do not need to poll again.
 
 > In a clustered setup, call `registerService` only from the primary process, after a short delay to allow workers to start up first.
 
 ```js
-// ESM
+// ESM — clustered
 import cluster from "cluster";
 import os from "os";
 import { initServer, registerService } from "@hivedev/hivesdk/server";
@@ -153,46 +194,29 @@ if (cluster.isPrimary)
 {
     await initServer({ serviceName: "NoteHive", servicePort: 49161, remoteUrl: "" });
 
-    setTimeout(async () =>
-    {
-        await registerService();
-    }, 3000);
+    setTimeout(async () => { await registerService(); }, 3000);
 
-    for (let i = 0; i < os.cpus().length; i++)
-    {
-        cluster.fork({ ...process.env });
-    }
-}
-else
-{
-    // Start your HTTP server in workers
+    for (let i = 0; i < os.cpus().length; i++) cluster.fork({ ...process.env });
 }
 ```
 
 ```js
-// CJS
+// CJS — clustered
 const cluster = require("cluster");
 const os = require("os");
 const { initServer, registerService } = require("@hivedev/hivesdk/server");
 
-if (cluster.isPrimary)
+(async () =>
 {
-    await initServer({ serviceName: "NoteHive", servicePort: 49161, remoteUrl: "" });
-
-    setTimeout(async () =>
+    if (cluster.isPrimary)
     {
-        await registerService();
-    }, 3000);
+        await initServer({ serviceName: "NoteHive", servicePort: 49161, remoteUrl: "" });
 
-    for (let i = 0; i < os.cpus().length; i++)
-    {
-        cluster.fork({ ...process.env });
+        setTimeout(async () => { await registerService(); }, 3000);
+
+        for (let i = 0; i < os.cpus().length; i++) cluster.fork({ ...process.env });
     }
-}
-else
-{
-    // Start your HTTP server in workers
-}
+})();
 ```
 
 ---
@@ -212,8 +236,6 @@ const app = express();
 app.use(express.json());
 app.use(cookieParser());
 app.use(handleHiveRequests);   // Must come before your own routes
-
-app.get("/my-route", (request, response) => { ... });
 ```
 
 ```js
@@ -227,22 +249,20 @@ const app = express();
 app.use(express.json());
 app.use(cookieParser());
 app.use(handleHiveRequests);
-
-app.get("/my-route", (request, response) => { ... });
 ```
 
 **Routes handled automatically by this middleware:**
 
 | Method | Route | What it does |
 |--------|-------|--------------|
-| `POST` | `/Login` | Proxies login credentials to HivePortal, sets session cookie and/or `x-session-token` header |
-| `POST` | `/Logout` | Proxies logout to HivePortal, clears session |
+| `POST` | `/Login` | Proxies credentials to HivePortal, sets session cookie and/or `x-session-token` header |
+| `POST` | `/Logout` | Proxies logout to HivePortal |
 | `GET` | `/ServiceUrls` | Returns local or remote URL for a named service |
 | `POST` | `/IsLoggedIn` | Checks if the current session is valid with HivePortal |
-| `POST` | `/IsLoggedInWithPermission` | Checks session validity and a specific named permission |
+| `POST` | `/IsLoggedInWithPermission` | Checks session validity and a named permission |
 | `POST` | `/SaveUserFilter` | Saves a user-defined data filter (requires `FILTER_OPERATIONS` permission) |
 | `POST` | `/PushNotificationToken` | Registers a push notification token for the current device |
-| `GET` | `/hive-client.js` | Serves the built client-side SDK bundle (see [Client SDK](#client-sdk)) |
+| `GET` | `/hive-client.js` | Serves the built client-side SDK bundle |
 
 You do not need to implement any of these routes yourself.
 
@@ -263,7 +283,7 @@ await loadConfiguration();
 // CJS
 const { loadConfiguration } = require("@hivedev/hivesdk/server");
 
-await loadConfiguration();
+await loadConfiguration(); // inside an async function or IIFE
 ```
 
 This populates the following environment variables (only those with saved `.dat` files on disk are loaded):
@@ -274,22 +294,33 @@ This populates the following environment variables (only those with saved `.dat`
 | `DATABASE_CREDENTIALS` | JSON string of database credentials, keyed by service name |
 | `PERMISSIONS` | JSON string of permission definitions |
 | `SMTP_CREDENTIALS` | JSON string of SMTP credentials |
-| `SMTP_PASSWORD` | Extracted SMTP password, ready for use in nodemailer |
+| `SMTP_PASSWORD` | Extracted SMTP password, ready for nodemailer |
 
-It also calls `DatabaseConnector.setCredentials` internally using the credentials stored under your service's name, so the database is ready to connect after this call.
+It also calls `DatabaseConnector.setCredentials` internally using the credentials for your service name, so the database is ready to connect after this call.
 
 If a `.dat` file does not exist yet (e.g. first run before registration is approved), that credential is silently skipped.
 
-> Call `loadConfiguration` before `registerService`. On first run the files won't exist yet and it will skip gracefully. Once `registerService` completes and the administrator approves it, files are written to disk and will be fully loaded on the next startup.
+> Call `loadConfiguration` before `registerService`. On first run the files won't exist yet and it will skip gracefully. Once the administrator approves the service and `registerService` saves the config, it will be fully loaded on the next startup.
 
 ---
 
 ### 5. Connecting to the Database
 
-After `loadConfiguration`, use `DatabaseConnector` to establish a MongoDB connection.
+`DatabaseConnector` supports two connection modes. **You use one or the other — not both at the same time.**
+
+#### Option A — MongoDB Atlas
+
+Set the `MONGODB_ATLAS_URL` environment variable to your Atlas connection string. When this variable is present, `connect()` uses it directly and skips the local credentials system entirely — no `setCredentials` call, no `loadConfiguration` needed for the database.
+
+The database name is read from the URL path if present (e.g. the `mydb` in `...mongodb.net/mydb`). If the URL has no path, the name falls back to whatever was set via `setCredentials`, or `"untitled"` if neither was called.
 
 ```js
-// ESM — import directly from the SDK's built file
+// Set in your environment before connect() is called
+process.env.MONGODB_ATLAS_URL = "mongodb+srv://user:pass@cluster.mongodb.net/mydb";
+```
+
+```js
+// ESM
 import DatabaseConnector from "./node_modules/@hivedev/hivesdk/DatabaseConnector.js";
 
 const connected = await DatabaseConnector.connect();
@@ -300,14 +331,35 @@ if (!connected)
     process.exit(1);
 }
 
-// DatabaseConnector.databaseObject is now a live MongoDB db instance
-const collection = DatabaseConnector.databaseObject.collection("my_collection");
+const collection = DatabaseConnector.getDatabase().collection("my_collection");
 ```
 
 ```js
 // CJS
 const DatabaseConnector = require("./node_modules/@hivedev/hivesdk/DatabaseConnector.js");
 
+(async () =>
+{
+    const connected = await DatabaseConnector.connect();
+
+    if (!connected)
+    {
+        console.error("Failed to connect to database.");
+        process.exit(1);
+    }
+
+    const collection = DatabaseConnector.getDatabase().collection("my_collection");
+})();
+```
+
+#### Option B — Self-hosted / Local MongoDB
+
+If `MONGODB_ATLAS_URL` is not set, `connect()` falls back to the local credentials flow. Credentials are set automatically by `loadConfiguration` using the service-name-keyed entry in the `DATABASE_CREDENTIALS` env var. If credentials have not been configured when `connect()` is called, it will attempt to call `loadConfiguration` itself.
+
+```js
+// ESM — credentials are loaded automatically via loadConfiguration()
+import DatabaseConnector from "./node_modules/@hivedev/hivesdk/DatabaseConnector.js";
+
 const connected = await DatabaseConnector.connect();
 
 if (!connected)
@@ -316,10 +368,38 @@ if (!connected)
     process.exit(1);
 }
 
-const collection = DatabaseConnector.databaseObject.collection("my_collection");
+const collection = DatabaseConnector.getDatabase().collection("my_collection");
+```
+
+```js
+// CJS
+const DatabaseConnector = require("./node_modules/@hivedev/hivesdk/DatabaseConnector.js");
+
+(async () =>
+{
+    const connected = await DatabaseConnector.connect();
+
+    if (!connected)
+    {
+        console.error("Failed to connect to database.");
+        process.exit(1);
+    }
+
+    const collection = DatabaseConnector.getDatabase().collection("my_collection");
+})();
 ```
 
-If `loadConfiguration` was not called first, `DatabaseConnector.connect()` will attempt to call it automatically.
+#### Accessing the Database Object
+
+Two equivalent ways to get the active database instance after a successful `connect()`:
+
+```js
+// Recommended — throws a clear error if not connected
+const db = DatabaseConnector.getDatabase();
+
+// Also works — direct field access, returns null if not connected
+const db = DatabaseConnector.databaseObject;
+```
 
 **Disconnecting:**
 
@@ -335,11 +415,11 @@ Use `isLoggedIn` and `isLoggedInWithPermission` to protect your own route handle
 
 When `bSendResponse` is `false`, the function returns a boolean and leaves the response untouched — use this to guard logic inside your own handlers.
 
-When `bSendResponse` is `true`, the function writes the result directly to the response — used internally by `handleHiveRequests` for the `/IsLoggedIn` and `/IsLoggedInWithPermission` endpoints.
+When `bSendResponse` is `true`, the function writes the result directly to the response — used internally by `handleHiveRequests`.
 
-Both functions handle **session refresh transparently** — if HivePortal signals that the session token should be refreshed, a new cookie and/or `x-session-token` header is set automatically before your handler continues.
+Both functions handle **session refresh transparently** — if HivePortal signals that the token should be refreshed, a new cookie and/or `x-session-token` header is set automatically before your handler continues.
 
-**Guarding a route with a login check:**
+**Login check:**
 
 ```js
 // ESM
@@ -379,7 +459,7 @@ app.get("/my-protected-route", async (request, response) =>
 });
 ```
 
-**Guarding a route with a permission check:**
+**Permission check:**
 
 The permission name must be set on `request.body.permissionName` before calling `isLoggedInWithPermission`.
 
@@ -436,8 +516,8 @@ import { sendMail } from "@hivedev/hivesdk/server";
 await sendMail(
     "sender@yourdomain.com",
     "recipient@example.com",
-    "Subject line here",
-    "<p>HTML body here</p>"
+    "Subject line",
+    "<p>HTML body</p>"
 );
 ```
 
@@ -448,137 +528,110 @@ const { sendMail } = require("@hivedev/hivesdk/server");
 await sendMail(
     "sender@yourdomain.com",
     "recipient@example.com",
-    "Subject line here",
-    "<p>HTML body here</p>"
+    "Subject line",
+    "<p>HTML body</p>"
 );
 ```
 
-Uses Gmail SMTP via nodemailer. The SMTP password is read from `process.env.SMTP_PASSWORD`, which is populated automatically by `loadConfiguration`. The sender Gmail address is currently hardcoded in `SendMail.js` — edit it there if needed.
+Uses Gmail SMTP via nodemailer. The SMTP password is read from `process.env.SMTP_PASSWORD`, populated automatically by `loadConfiguration`. The sender Gmail address is hardcoded in `SendMail.js` — edit it in the SDK source if needed.
 
 ---
 
 ### 8. Utility Functions
 
-All utilities are exported from `@hivedev/hivesdk/server`.
-
-**`getAppDataDirectory()`**
-
-Returns the platform-appropriate data directory for your service, creating it if it doesn't exist. On Windows this is `%APPDATA%\<ServiceName>`, on macOS `~/Library/Application Support/<ServiceName>`, on Linux `~/.config/<ServiceName>`.
+**`getAppDataDirectory()`** — Platform-appropriate data directory for your service. On Windows: `%APPDATA%\<ServiceName>`, macOS: `~/Library/Application Support/<ServiceName>`, Linux: `~/.config/<ServiceName>`.
 
 ```js
 // ESM
 import { getAppDataDirectory } from "@hivedev/hivesdk/server";
-const dataDir = getAppDataDirectory();
-// e.g. "/home/user/.config/NoteHive"
+const dataDir = getAppDataDirectory(); // e.g. "/home/user/.config/NoteHive"
 ```
-
 ```js
 // CJS
 const { getAppDataDirectory } = require("@hivedev/hivesdk/server");
 const dataDir = getAppDataDirectory();
 ```
 
-**`getHostIp()`**
+---
 
-Returns the first non-loopback IPv4 address of the host machine.
+**`getHostIp()`** — First non-loopback IPv4 address of the host machine.
 
 ```js
 // ESM
 import { getHostIp } from "@hivedev/hivesdk/server";
 const ip = getHostIp(); // e.g. "192.168.1.42"
 ```
-
 ```js
 // CJS
 const { getHostIp } = require("@hivedev/hivesdk/server");
 const ip = getHostIp();
 ```
 
-**`findService(serviceName)`**
+---
 
-Discovers another Hive service on the LAN via UDP to port 49153. Returns `{ name, urls: { local, remote } }` or `null` if not found within 3 seconds. Requires `HIVE_PORTAL_LAN_IP` environment variable to be set.
+**`findService(serviceName)`** — Discovers another Hive service on the LAN via UDP to port 49153. Returns `{ name, urls: { local, remote } }` or `null`. Requires `HIVE_PORTAL_LAN_IP` to be set.
 
 ```js
 // ESM
 import { findService } from "@hivedev/hivesdk/server";
-
 const service = await findService("NoteHive");
-
-if (service)
-{
-    console.log(service.urls.local); // "http://192.168.1.42:49161"
-}
+if (service) console.log(service.urls.local); // "http://192.168.1.42:49161"
 ```
-
 ```js
 // CJS
 const { findService } = require("@hivedev/hivesdk/server");
-
 const service = await findService("NoteHive");
-
-if (service)
-{
-    console.log(service.urls.local);
-}
+if (service) console.log(service.urls.local);
 ```
 
-**`extractConfigurationForService()`**
+---
 
-Parses `process.env` and returns the configuration as structured objects, extracting the correct database credentials for the current service name.
+**`extractConfigurationForService()`** — Parses `process.env` and returns the four credential sets as objects. Database credentials are extracted for the current service name specifically.
 
 ```js
 // ESM
 import { extractConfigurationForService } from "@hivedev/hivesdk/server";
-
 const { firebaseAdminCredentials, databaseCredentials, permissions, smtpCredentials } = extractConfigurationForService();
 ```
-
 ```js
 // CJS
 const { extractConfigurationForService } = require("@hivedev/hivesdk/server");
-
 const { firebaseAdminCredentials, databaseCredentials, permissions, smtpCredentials } = extractConfigurationForService();
 ```
 
-**`encryptAndStoreFile(data, fullPath, password)`**
+---
 
-Encrypts a string or Buffer with AES-256-CBC and writes it to disk. Creates the directory if it doesn't exist.
+**`encryptAndStoreFile(data, fullPath, password)`** — Encrypts a string or Buffer with AES-256-CBC and writes it to disk. Creates the directory if it doesn't exist.
 
 ```js
 // ESM
 import { encryptAndStoreFile } from "@hivedev/hivesdk/server";
-
-await encryptAndStoreFile("my secret data", "/path/to/file.dat", process.env.SERVER_PASSWORD);
+await encryptAndStoreFile("secret", "/path/to/file.dat", process.env.SERVER_PASSWORD);
 ```
-
 ```js
 // CJS
 const { encryptAndStoreFile } = require("@hivedev/hivesdk/server");
-
-await encryptAndStoreFile("my secret data", "/path/to/file.dat", process.env.SERVER_PASSWORD);
+await encryptAndStoreFile("secret", "/path/to/file.dat", process.env.SERVER_PASSWORD);
 ```
 
-**`decryptFileWithPassword(fullPath, password)`**
+---
 
-Reads and decrypts an encrypted `.dat` file. Returns the decrypted string, or `null` on failure.
+**`decryptFileWithPassword(fullPath, password)`** — Reads and decrypts an encrypted `.dat` file. Returns the decrypted string, or `null` on failure.
 
 ```js
 // ESM
 import { decryptFileWithPassword } from "@hivedev/hivesdk/server";
-
 const contents = await decryptFileWithPassword("/path/to/file.dat", process.env.SERVER_PASSWORD);
 ```
-
 ```js
 // CJS
 const { decryptFileWithPassword } = require("@hivedev/hivesdk/server");
-
 const contents = await decryptFileWithPassword("/path/to/file.dat", process.env.SERVER_PASSWORD);
 ```
 
-**`saveConfiguration(configurationObject)` / `loadConfiguration()`**
+---
 
-Normally called automatically by `registerService` and during startup respectively. Available for manual use if needed. `saveConfiguration` only writes keys that are present in the object — missing keys do not overwrite existing files.
+**`saveConfiguration(configurationObject)` / `loadConfiguration()`** — Normally called automatically. `saveConfiguration` only writes keys present in the object — missing keys do not overwrite existing files.
 
 ```js
 // ESM
@@ -591,7 +644,6 @@ await saveConfiguration({
 
 await loadConfiguration();
 ```
-
 ```js
 // CJS
 const { saveConfiguration, loadConfiguration } = require("@hivedev/hivesdk/server");
@@ -608,8 +660,6 @@ await loadConfiguration();
 
 ### Full Server Bootstrap Example
 
-This is the recommended startup sequence for any Hive microservice.
-
 ```js
 // ESM
 import express from "express";
@@ -731,13 +781,13 @@ app.get("/", (request, response) => response.redirect("/Client/Pages/HomePage.ht
 
 ## Client SDK
 
-The client SDK is a browser-only ESM bundle (`hive-client.js`). There is no CJS variant — it runs exclusively in the browser.
+The client SDK is a browser-only ESM bundle. There is no CJS variant — it runs exclusively in the browser.
 
 ### 1. Loading the Client Bundle
 
-The `handleHiveRequests` middleware automatically serves the client bundle at `/hive-client.js` by reading it from `node_modules/@hivedev/hivesdk/hive-client.js`. **This works as long as your service's Node.js process is started from the root of the package** (i.e. the directory that contains `node_modules`), which is the recommended setup.
+The `handleHiveRequests` middleware automatically serves the client bundle at `/hive-client.js` by reading it from `node_modules/@hivedev/hivesdk/hive-client.js`. **This works as long as your service's Node.js process is started from the root of the package** (the directory containing `node_modules`), which is the recommended setup.
 
-If your service is started from a different working directory, the automatic route will fail to locate the file. In that case, serve it yourself:
+If your service is started from a different working directory, the automatic route will fail to locate the file. In that case, serve it manually:
 
 ```js
 import path from "path";
@@ -745,26 +795,18 @@ import { createReadStream } from "fs";
 
 app.get("/hive-client.js", (request, response) =>
 {
-    const filePath = path.join("/absolute/path/to/node_modules/@hivedev/hivesdk/hive-client.js");
+    const filePath = "/absolute/path/to/node_modules/@hivedev/hivesdk/hive-client.js";
     response.setHeader("Content-Type", "application/javascript");
     createReadStream(filePath).pipe(response);
 });
 ```
 
-Include it in your HTML pages as a module script:
+Include it in your HTML pages:
 
 ```html
 <script type="module" src="/hive-client.js"></script>
 ```
 
-Or import from it in another module script on the page:
-
-```html
-<script type="module">
-    import { login } from "/hive-client.js";
-</script>
-```
-
 ---
 
 ### 2. Initialising the Client
@@ -777,8 +819,6 @@ import { initClient } from "/hive-client.js";
 await initClient({});
 ```
 
-`initClient` accepts one optional parameter:
-
 | Parameter | Type | Default | Description |
 |-----------|------|---------|-------------|
 | `loginTokenStorageMethod` | `sessionStorageMethod` enum | `HTTP_ONLY_COOKIE` | How session tokens are stored on the client |
@@ -787,7 +827,7 @@ await initClient({});
 
 ### 3. Login
 
-Call `login()` to open the HivePortal login page. The SDK handles the entire flow — the popup opens, the user enters their credentials, and on success the page reloads at `/`.
+Call `login()` to open the HivePortal login page. The SDK handles the entire flow — the popup opens, the user enters their credentials, and on success the page redirects to `/`.
 
 ```js
 import { login } from "/hive-client.js";
@@ -795,11 +835,9 @@ import { login } from "/hive-client.js";
 login();
 ```
 
-You can wire it to any element:
+Wire it to any element:
 
 ```js
-import { login } from "/hive-client.js";
-
 document.getElementById("login-button").addEventListener("click", login);
 ```
 
@@ -809,7 +847,7 @@ When running inside the native mobile app (detected automatically), the login po
 
 ### 4. Checking Login State
 
-`initClient` automatically starts a periodic login check (every 30 seconds, clamped between 10 and 60 seconds). Each check fires a `login-state-changed` custom event on `window`.
+`initClient` starts a periodic login check (every 30 seconds, clamped between 10 and 60 seconds). Each check fires a `login-state-changed` custom event on `window`.
 
 ```js
 window.addEventListener("login-state-changed", (event) =>
@@ -821,7 +859,7 @@ window.addEventListener("login-state-changed", (event) =>
 });
 ```
 
-The current login state is also available synchronously at any time:
+Current login state is also available synchronously at any time:
 
 ```js
 if (window.IS_LOGGED_IN)
@@ -874,8 +912,6 @@ if (window.IS_LOGGED_IN)
 
 ## Enumerations
 
-The SDK exports several enumerations used throughout the Hive ecosystem.
-
 **`userPrivileges`** — Numeric privilege levels assigned to users.
 
 | Key | Value |
@@ -921,7 +957,7 @@ The SDK exports several enumerations used throughout the Hive ecosystem.
 | `USER_REGISTERATION` | 0 |
 | `SERVICE_REGISTERATION` | 1 |
 
-**`filterTypes`**, **`filterOperators`**, **`userDataFetchFilterComparision`**, **`userFieldTypes`**, **`userFieldFormats`**, **`fileTreeNodeTypes`** — Domain-specific enumerations used for data querying, user field definitions, and file tree structures. Refer to their respective source files for values.
+**`filterTypes`**, **`filterOperators`**, **`userDataFetchFilterComparision`**, **`userFieldTypes`**, **`userFieldFormats`**, **`fileTreeNodeTypes`** — Domain-specific enumerations for data querying, user field definitions, and file tree structures. Refer to their respective source files for values.
 
 ---
 
@@ -934,6 +970,7 @@ The SDK exports several enumerations used throughout the Hive ecosystem.
 | `SERVICE_PORT` | `initServer` | Port this service listens on |
 | `REMOTE_URL` | `initServer` | Public-facing URL of this service (empty if LAN-only) |
 | `HIVE_PORTAL_LAN_IP` | External | LAN IP of HivePortal, used by `findService` for UDP discovery |
+| `MONGODB_ATLAS_URL` | External | Atlas connection string — if set, bypasses local DB credentials entirely |
 | `FIREBASE_ADMIN_CREDENTIALS` | `loadConfiguration` | JSON string of Firebase Admin credentials |
 | `DATABASE_CREDENTIALS` | `loadConfiguration` | JSON string of DB credentials keyed by service name |
 | `PERMISSIONS` | `loadConfiguration` | JSON string of permission definitions |
@@ -980,8 +1017,8 @@ Every authentication check a service performs is a proxied call to HivePortal. H
 
 ## Known Limitations
 
-- **`ScheduleServiceUrlUpdate`** — This function is currently a stub and does nothing. It is intended for future use to periodically re-broadcast service URLs to HivePortal if the host IP changes.
-- **`loginTokenStorageMethod`** — The `LOCAL_STORAGE` and `SESSION_STORAGE` options in the `sessionStorageMethod` enum are defined but not yet implemented. Only `HTTP_ONLY_COOKIE` (with the `x-session-token` header fallback for native app clients) is fully functional.
-- **SMTP sender address** — The sender Gmail address in `SendMail.js` is hardcoded. Edit it in the SDK source if your service needs a different address.
-- **MongoDB only** — `DatabaseConnector` is built for MongoDB. There is no support for other databases.
-- **MongoDB port hardcoded** — The MongoDB port is hardcoded to `27017`. The host is configurable via credentials but the port is not.
+- **`ScheduleServiceUrlUpdate`** — Currently a stub and does nothing. Intended for future use to re-broadcast service URLs if the host IP changes.
+- **`loginTokenStorageMethod`** — `LOCAL_STORAGE` and `SESSION_STORAGE` are defined in the enum but not yet implemented. Only `HTTP_ONLY_COOKIE` (with the `x-session-token` header fallback for native app clients) is fully functional.
+- **SMTP sender address** — Hardcoded in `SendMail.js`. Edit it in the SDK source if your service needs a different address.
+- **MongoDB only** — `DatabaseConnector` is built for MongoDB only.
+- **MongoDB port hardcoded** — For local connections, the port is fixed at `27017`. The host is configurable via credentials but the port is not. Use Atlas (`MONGODB_ATLAS_URL`) if you need a non-standard port.

package/hive-server.cjs

@@ -326,29 +326,52 @@ var DatabaseConnector = class _DatabaseConnector {
   static databaseObject = null;
   /**
    * Connects to the MongoDB database.
-   * If the database configuration is not set, it will call loadConfiguration() to load the configuration.
-   * If the database configuration is still not set after calling loadConfiguration(), it will return false.
-   * If the MongoClient object is not set, it will create a new MongoClient object with the database URL and credentials.
-   * It will then try to connect to the database using the MongoClient object.
-   * If the connection is successful, it will set the databaseObject to the database object returned by the MongoClient.
-   * If the connection fails, it will log an error message and return false.
-   * @returns {boolean} True if the connection is successful, false otherwise.
+   * 
+   * If the MONGODB_ATLAS_URL environment variable is set, it is used directly as the
+   * connection string and the local credentials configuration is bypassed entirely.
+   * The database name is parsed from the URL path if present (e.g. the "mydb" in
+   * "mongodb+srv://user:pass@cluster.mongodb.net/mydb"), otherwise the value set via
+   * setCredentials is used.
+   * 
+   * If MONGODB_ATLAS_URL is not set, the normal local credentials flow applies:
+   * if credentials have not been configured, loadConfiguration() is called first.
+   * 
+   * @returns {Promise<boolean>} True if the connection is successful, false otherwise.
    */
   static async connect() {
-    if (!_DatabaseConnector.#bConfigured) {
-      await loadConfiguration();
-      if (!_DatabaseConnector.#bConfigured) {
-        console.log("Database configuration is not set! Please provide database credentials first.");
-        return false;
+    const atlasUrl = process.env.MONGODB_ATLAS_URL;
+    if (atlasUrl) {
+      if (!_DatabaseConnector.#mongoClient) {
+        let databaseName = _DatabaseConnector.#databaseName;
+        try {
+          const parsedUrl = new URL(atlasUrl);
+          const nameFromUrl = parsedUrl.pathname.replace("/", "").trim();
+          if (nameFromUrl) {
+            databaseName = nameFromUrl;
+          }
+        } catch (error) {
+          console.error("DatabaseConnector: Failed to parse MONGODB_ATLAS_URL.", error);
+          return false;
+        }
+        _DatabaseConnector.#mongoClient = new import_mongodb.MongoClient(atlasUrl);
+        _DatabaseConnector.#databaseName = databaseName;
       }
-    }
-    if (!_DatabaseConnector.#mongoClient) {
-      _DatabaseConnector.#mongoClient = new import_mongodb.MongoClient(
-        _DatabaseConnector.#databaseUrl,
-        {
-          auth: { username: _DatabaseConnector.#username, password: _DatabaseConnector.#password }
+    } else {
+      if (!_DatabaseConnector.#bConfigured) {
+        await loadConfiguration();
+        if (!_DatabaseConnector.#bConfigured) {
+          console.log("Database configuration is not set! Please provide database credentials first.");
+          return false;
         }
-      );
+      }
+      if (!_DatabaseConnector.#mongoClient) {
+        _DatabaseConnector.#mongoClient = new import_mongodb.MongoClient(
+          _DatabaseConnector.#databaseUrl,
+          {
+            auth: { username: _DatabaseConnector.#username, password: _DatabaseConnector.#password }
+          }
+        );
+      }
     }
     try {
       await _DatabaseConnector.#mongoClient.connect();
@@ -375,7 +398,8 @@ var DatabaseConnector = class _DatabaseConnector {
     console.log("Disconnected from database");
   }
   /**
-   * Sets the database credentials for the DatabaseConnector
+   * Sets the database credentials for the DatabaseConnector.
+   * Used for local/self-hosted MongoDB instances. Not required when using MONGODB_ATLAS_URL.
    * @param {Object} obj - contains the database host, username, password, and name
    * @param {string} obj.host - The host of the database
    * @param {string} obj.username - The username of the database
@@ -394,6 +418,17 @@ var DatabaseConnector = class _DatabaseConnector {
     else throw new Error("Database name not set!");
     _DatabaseConnector.#bConfigured = true;
   }
+  /**
+   * Returns the active MongoDB database object.
+   * @returns {import("mongodb").Db} The active database object.
+   * @throws {Error} If connect() has not been called or the connection failed.
+   */
+  static getDatabase() {
+    if (!_DatabaseConnector.databaseObject) {
+      throw new Error("DatabaseConnector: No active database connection. Call connect() first.");
+    }
+    return _DatabaseConnector.databaseObject;
+  }
 };
 var DatabaseConnector_default = DatabaseConnector;
 

package/hive-server.js

@@ -299,29 +299,52 @@ var DatabaseConnector = class _DatabaseConnector {
   static databaseObject = null;
   /**
    * Connects to the MongoDB database.
-   * If the database configuration is not set, it will call loadConfiguration() to load the configuration.
-   * If the database configuration is still not set after calling loadConfiguration(), it will return false.
-   * If the MongoClient object is not set, it will create a new MongoClient object with the database URL and credentials.
-   * It will then try to connect to the database using the MongoClient object.
-   * If the connection is successful, it will set the databaseObject to the database object returned by the MongoClient.
-   * If the connection fails, it will log an error message and return false.
-   * @returns {boolean} True if the connection is successful, false otherwise.
+   * 
+   * If the MONGODB_ATLAS_URL environment variable is set, it is used directly as the
+   * connection string and the local credentials configuration is bypassed entirely.
+   * The database name is parsed from the URL path if present (e.g. the "mydb" in
+   * "mongodb+srv://user:pass@cluster.mongodb.net/mydb"), otherwise the value set via
+   * setCredentials is used.
+   * 
+   * If MONGODB_ATLAS_URL is not set, the normal local credentials flow applies:
+   * if credentials have not been configured, loadConfiguration() is called first.
+   * 
+   * @returns {Promise<boolean>} True if the connection is successful, false otherwise.
    */
   static async connect() {
-    if (!_DatabaseConnector.#bConfigured) {
-      await loadConfiguration();
-      if (!_DatabaseConnector.#bConfigured) {
-        console.log("Database configuration is not set! Please provide database credentials first.");
-        return false;
+    const atlasUrl = process.env.MONGODB_ATLAS_URL;
+    if (atlasUrl) {
+      if (!_DatabaseConnector.#mongoClient) {
+        let databaseName = _DatabaseConnector.#databaseName;
+        try {
+          const parsedUrl = new URL(atlasUrl);
+          const nameFromUrl = parsedUrl.pathname.replace("/", "").trim();
+          if (nameFromUrl) {
+            databaseName = nameFromUrl;
+          }
+        } catch (error) {
+          console.error("DatabaseConnector: Failed to parse MONGODB_ATLAS_URL.", error);
+          return false;
+        }
+        _DatabaseConnector.#mongoClient = new MongoClient(atlasUrl);
+        _DatabaseConnector.#databaseName = databaseName;
       }
-    }
-    if (!_DatabaseConnector.#mongoClient) {
-      _DatabaseConnector.#mongoClient = new MongoClient(
-        _DatabaseConnector.#databaseUrl,
-        {
-          auth: { username: _DatabaseConnector.#username, password: _DatabaseConnector.#password }
+    } else {
+      if (!_DatabaseConnector.#bConfigured) {
+        await loadConfiguration();
+        if (!_DatabaseConnector.#bConfigured) {
+          console.log("Database configuration is not set! Please provide database credentials first.");
+          return false;
         }
-      );
+      }
+      if (!_DatabaseConnector.#mongoClient) {
+        _DatabaseConnector.#mongoClient = new MongoClient(
+          _DatabaseConnector.#databaseUrl,
+          {
+            auth: { username: _DatabaseConnector.#username, password: _DatabaseConnector.#password }
+          }
+        );
+      }
     }
     try {
       await _DatabaseConnector.#mongoClient.connect();
@@ -348,7 +371,8 @@ var DatabaseConnector = class _DatabaseConnector {
     console.log("Disconnected from database");
   }
   /**
-   * Sets the database credentials for the DatabaseConnector
+   * Sets the database credentials for the DatabaseConnector.
+   * Used for local/self-hosted MongoDB instances. Not required when using MONGODB_ATLAS_URL.
    * @param {Object} obj - contains the database host, username, password, and name
    * @param {string} obj.host - The host of the database
    * @param {string} obj.username - The username of the database
@@ -367,6 +391,17 @@ var DatabaseConnector = class _DatabaseConnector {
     else throw new Error("Database name not set!");
     _DatabaseConnector.#bConfigured = true;
   }
+  /**
+   * Returns the active MongoDB database object.
+   * @returns {import("mongodb").Db} The active database object.
+   * @throws {Error} If connect() has not been called or the connection failed.
+   */
+  static getDatabase() {
+    if (!_DatabaseConnector.databaseObject) {
+      throw new Error("DatabaseConnector: No active database connection. Call connect() first.");
+    }
+    return _DatabaseConnector.databaseObject;
+  }
 };
 var DatabaseConnector_default = DatabaseConnector;
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@hivedev/hivesdk",
   "type": "module",
-  "version": "1.0.39",
+  "version": "1.0.41",
   "main": "dist/index.cjs",
   "module": "dist/index.js",
   "scripts": {