@nomad-media/public 1.1.15 → 2026.9.2-beta.0

package/dist/nomad-media-sdk-debug.js

@@ -1,3 +1,175 @@
+/**
+ * @typedef {Object} SearchFilter
+ * @property {string} fieldName - The content field to filter on
+ * @property {string} operator - Comparison operator (e.g. "Equals", "Contains", "GreaterThan")
+ * @property {string|string[]} values - The value or array of values to match
+ */
+
+/**
+ * @typedef {Object} SortField
+ * @property {string} fieldName - The field to sort on
+ * @property {string} sortType - Sort direction: "Ascending" or "Descending"
+ */
+
+/**
+ * @typedef {Object} SearchResultField
+ * @property {string} name - Field name to include in results
+ * @property {SearchResultField[]} [SearchResultFields] - Nested sub-fields for object fields
+ */
+
+/**
+ * @typedef {Object} TagRef
+ * @property {string} id - Tag ID
+ * @property {string} [description] - Tag description
+ */
+
+/**
+ * @typedef {Object} CollectionRef
+ * @property {string} id - Collection ID
+ * @property {string} [description] - Collection description
+ */
+
+/**
+ * @typedef {Object} RelatedContentRef
+ * @property {string} id - Related content ID
+ * @property {string} [description] - Description
+ */
+
+/**
+ * @typedef {Object} AudioTrack
+ * @property {string} id - Audio track ID
+ * @property {string} [name] - Track name
+ * @property {string} [language] - Language code
+ */
+
+/**
+ * @typedef {Object} ExternalOutputProfile
+ * @property {string} id - Output profile ID
+ * @property {string} [name] - Profile name
+ * @property {string} [profileType] - Profile type identifier
+ */
+
+/**
+ * @typedef {Object} LiveInputSource
+ * @property {string} url - Source stream URL
+ * @property {string} [id] - Source ID
+ */
+
+/**
+ * @typedef {Object} LiveInputDestination
+ * @property {string} url - Destination stream URL
+ * @property {string} [id] - Destination ID
+ * @property {string} [name] - Destination name
+ */
+
+/**
+ * @typedef {Object} LiveOutputProfile
+ * @property {string} id - Output profile ID
+ * @property {string} [name] - Profile name
+ * @property {string} [type] - Profile type
+ */
+
+/**
+ * @typedef {Object} MediaSource
+ * @property {string} assetId - The asset ID to include in the composition
+ * @property {string} startTimeCode - Start timecode (HH:MM:SS:FF)
+ * @property {string} endTimeCode - End timecode (HH:MM:SS:FF)
+ * @property {string} [id] - Source segment ID
+ */
+
+/**
+ * @typedef {Object} MediaBuilderItem
+ * @property {string} sourceAssetId - The asset ID to use as the source for this media builder item
+ * @property {string} startTimeCode - Start timecode for the segment (HH:MM:SS:FF)
+ * @property {string} endTimeCode - End timecode for the segment (HH:MM:SS:FF)
+ */
+
+/**
+ * @typedef {Object} Annotation
+ * @property {string} [id] - Annotation ID
+ * @property {string} startTimeCode - Start timecode for the annotation (HH:MM:SS:FF)
+ * @property {string} [endTimeCode] - End timecode for the annotation (HH:MM:SS:FF)
+ * @property {Object} properties - Annotation properties (e.g. { title: "..." })
+ */
+
+/**
+ * @typedef {Object} ContentRef
+ * @property {string} id - Content ID
+ */
+
+/**
+ * @typedef {Object} NomadUser
+ * @property {string} [id] - User ID
+ */
+
+/**
+ * @typedef {Object} ExternalUser
+ * @property {string} email - External user email address
+ * @property {string} [id] - External user ID
+ * @property {string} [externalUserType] - Type of external user
+ */
+
+/**
+ * @typedef {Object} ContentField
+ * @property {string} contentFieldId - Unique identifier of the content field
+ * @property {Object} properties - Field property definitions (title, type, etc.)
+ */
+
+/**
+ * @typedef {Object} Transfer
+ * @property {string} id - The transfer id (UUID), which cancel, requeue and progress calls address
+ * @property {integer} direction - Which way the asset moves: 1 = Upload, 2 = Download
+ * @property {string} transferStatus - Lifecycle state: one of "Queued", "Downloading", "Uploading", "Error", "Complete", "Cancelled"
+ * @property {string} [displayName] - A human readable label, normally the file name
+ * @property {number} [completePercentage] - Percent complete, 0 to 100, when known
+ * @property {integer} bytesTransferred - Bytes moved so far
+ * @property {integer} bytesTotal - Total size of the transfer, or 0 when not known up front
+ * @property {integer} attemptCount - How many times this transfer has been attempted
+ * @property {string} [errorMessage] - The failure reason. Only populated for a failed transfer
+ * @property {string} createdDate - When the record was created (ISO 8601)
+ * @property {string} [queueDate] - When the transfer was queued (ISO 8601)
+ * @property {string} [startTransferDate] - When bytes first started moving (ISO 8601)
+ * @property {string} [completeTransferDate] - When the transfer finished successfully (ISO 8601)
+ * @property {string} [cancelledDate] - When the transfer was cancelled (ISO 8601)
+ * @property {string} [errorDate] - When the transfer failed (ISO 8601)
+ * @property {string} [lastProgressDate] - When progress was last recorded (ISO 8601)
+ * @property {string} [assetId] - The asset this transfer concerns (UUID), in either direction
+ * @property {boolean} [downloadProxy] - Whether a download is taking the proxy rendition rather than the original. Download only
+ * @property {string} [relatedAssetId] - The asset this upload is a related file of (UUID). Upload only
+ * @property {string} [displayObjectKey] - The destination object key as shown to a user. Upload only
+ * @property {string} [assetName] - The display name of the asset. Download only
+ * @property {string} [assetUrl] - The internal URL of the asset in `{bucketName}::{objectKey}` format. Download only
+ * @property {string} [fullPreviewUrl] - A signed URL of the asset's thumbnail image, when one is available
+ */
+
+/**
+ * @typedef {Object} UploadQueueItem
+ * @property {string} fileName - The file name, including its extension
+ * @property {integer} fileSize - The file size in bytes
+ * @property {string} [mimeType] - The MIME type, when known; otherwise inferred from the file name
+ * @property {string} [destinationFolderId] - The destination folder (UUID); omit for the configured default upload folder
+ * @property {integer} chunkSize - The multipart part size in bytes, e.g. 8388608
+ * @property {string} [uploadOverwriteOption] - How to treat an existing file: "continue", "replace" (default) or "cancel"
+ */
+
+/**
+ * @typedef {Object} TransferList
+ * @property {Array<Transfer>} items - The page of transfers
+ * @property {integer} totalItemCount - The number of transfers matching the filters; approximate for very large histories
+ * @property {string} [nextPageOffset] - The opaque cursor to pass back as `cursor` for the next page. A null value means the end has been reached
+ * @property {boolean} hasItems - Whether the items collection contains any items
+ * @property {string} [message] - An optional message providing additional information about the result
+ */
+
+/**
+ * @typedef {Object} TransferSummary
+ * @property {Object} [uploadCounts] - Per-status counts for uploads, keyed by status name (Queued, Downloading, Uploading, Error, Complete, Cancelled)
+ * @property {Object} [downloadCounts] - Per-status counts for downloads, keyed by status name
+ * @property {integer} activeCount - Number of transfers that have not reached a terminal state
+ * @property {integer} errorCount - Number of transfers that ended in failure
+ * @property {string} [changeToken] - A token that changes whenever any counted value changes; usable for If-None-Match polling
+ */
+
 // account
 
 
@@ -135,6 +307,10 @@
 
 
 
+
+
+
+
 
 
 
@@ -187,6 +363,20 @@
 
 
 
+
+
+
+
+
+
+
+
+
+
+
+
+
+
 
 
 
@@ -276,6 +466,10 @@
 
 
 
+import axios from "axios";
+
+
+
 /**
  * @class NomadSDK
  * @classdesc This class is used to interact with the Nomad API.
@@ -283,11 +477,16 @@
 
 class NomadMediaSDK {
     constructor(config = {}) {
-        if (NomadMediaSDK.instance) 
+        if (NomadMediaSDK.instance)
         {
             return NomadMediaSDK.instance;
         }
 
+        if (!config.serviceApiUrl || typeof config.serviceApiUrl !== "string")
+        {
+            throw new MissingCredentialsException(["serviceApiUrl"]);
+        }
+
         this.config = config;
         this.token = null;
         this.refreshTokenVal = null;
@@ -296,42 +495,104 @@ class NomadMediaSDK {
         this.id = null
         this.debug = config.debugMode || false;
 
+        // SSO login params
+        this.ssoProvider = this.config.ssoProvider || null;
+        this.ssoCode = this.config.ssoCode || null;
+        this.ssoState = this.config.ssoState || null;
+        this.ssoSessionState = this.config.ssoSessionState || null;
+        this.ssoRedirectUrl = this.config.ssoRedirectUrl || null;
+
         if (this.config.serviceApiUrl[this.config.serviceApiUrl.length - 1] === "/")
         {
             this.config.serviceApiUrl = this.config.serviceApiUrl.slice(0, -1);
         }
 
+        if (this.ssoProvider || this.ssoCode || this.ssoState || this.ssoSessionState || this.ssoRedirectUrl)
+        {
+            const missingCredentials = [];
+            const hasRedirectUrl = !!this.ssoRedirectUrl;
+            const hasAllFields = this.ssoProvider && this.ssoCode && this.ssoState && this.ssoSessionState;
+            if (!hasRedirectUrl && !hasAllFields) {
+                if (!this.ssoProvider) missingCredentials.push("ssoProvider");
+                if (!this.ssoCode) missingCredentials.push("ssoCode");
+                if (!this.ssoState) missingCredentials.push("ssoState");
+                if (!this.ssoSessionState) missingCredentials.push("ssoSessionState");
+
+                throw new MissingCredentialsException(missingCredentials, "SSO login requires either ssoRedirectUrl or all of ssoProvider, ssoCode, ssoState, ssoSessionState");
+            }
+        }
+        else if (!this.config.apiKey)
+        {
+            const missingCredentials = [];
+            if (!this.config.username) missingCredentials.push("username");
+            if (!this.config.password && !this.config.apiKey) missingCredentials.push("password");
+
+            if (missingCredentials.length > 0) {
+                throw new MissingCredentialsException(missingCredentials);
+            }
+        }
+
         if (this.config.singleton) NomadMediaSDK.instance = this;
-        
+
         return this;
-    } 
+    }
 
     /**
      * @function init
      * @async
      * @private
-     * @description Initializes the SDK. Logs in using the username and password from the config. 
+     * @description Initializes the SDK. Logs in using the username and password from the config.
      * Then schedules a token refresh for the duration set by the value returned in the login.
      * @returns {Promise<void>} - A promise that resolves when the SDK is initialized.
      * @throws {Error} - An error is thrown if the SDK fails to initialize.
      */
-    async _init() 
+    async _init()
+    {
+        // Calls made at the same time on a fresh SDK share one login instead of each starting their own.
+        if (!this._initPromise)
+        {
+            this._initPromise = this._runInit().finally(() => { this._initPromise = null; });
+        }
+        return this._initPromise;
+    }
+
+    async _runInit()
     {
         if (this.config.username && this.config.password)
         {
+            if (!this.config.serviceApiUrl)
+            {
+                throw new MissingCredentialsException(["serviceApiUrl"]);
+            }
             await this.login();
         }
+        else if (this.ssoProvider || this.ssoCode || this.ssoState || this.ssoSessionState || this.ssoRedirectUrl)
+        {
+            await this.authenticateWithSSO();
+        }
     }
-    
+
     // account functions
     /**
      * @function login
      * @async
-     * @description Logs in using the username and password from the config.
-     * @returns {Promise<void>} - A promise that resolves when the login is successful.
-     * Updates the token, refresh token, expiration seconds, and user session ID class variables. 
-     * @throws {Error} - An error is thrown if the login fails.
-     */ 
+     * @description Authenticate a user and obtain a JWT access token.
+     * Validates the user's credentials and, if successful, creates a new session and returns a JWT
+     * access token with a refresh token. Accounts that are disabled, expired, pending invitation,
+     * or pending approval will be rejected. Guest users must have a valid profile and permitted
+     * application access.
+     * @returns {Promise<Object>} Authentication response. User-identity fields (from the backend `AccountLoginResponseModel`): `id`, `userName`, `firstName`, `lastName`, `loginStatus`, `cookies`. Session/token fields consumed by the SDK: `token`, `refreshToken`, `expirationSeconds`, `userSessionId`. Note: there is no `userId` or `expiresIn` field; use `id` and `expirationSeconds` respectively.
+     * @throws {Error} 400 - The request body is null or missing required fields (UserName, Password)
+     * @throws {Error} 404 - Authentication failed — invalid credentials or user not found
+     * @throws {Error} 403 - User account is Disabled, Expired, PendingInvitation, or PendingApproval
+     * @example
+     * const response = await nomadSDK.login();
+     * console.log('Access Token:', response.token);
+     * console.log('User ID:', response.id);
+     * console.log('User Name:', response.userName);
+     * 
+     * @see {@link https://docs.nomad-cms.com/api/account/login Admin API} POST /account/login
+     */
     async login()
     {
 
@@ -339,17 +600,39 @@ class NomadMediaSDK {
 
         try
         {
-            const LOGIN_INFO = await _login(this);
-            if (!LOGIN_INFO) throw new Error("Login failed");
-            
+            // _login()'s underlying _sendRequest() now throws on any
+            // failure (e.g. a 409 "Invalid username or password") rather
+            // than resolving to a falsy value — but this method's own
+            // documented contract is to throw the specific, public
+            // LoginException on any login failure, not whatever generic
+            // error the transport layer happens to throw. Any failure here
+            // is treated as a login failure, matching this method's
+            // original behavior when _login() resolved to a falsy value
+            // for the same case.
+            let LOGIN_INFO;
+            let LOGIN_ERROR;
+            try
+            {
+                LOGIN_INFO = await _login(this);
+            }
+            catch (error)
+            {
+                LOGIN_INFO = null;
+                LOGIN_ERROR = error;
+            }
+            // The original error (network failure, 403 disabled account, ...) is kept
+            // on `.cause`, with its HTTP status on `.status`.
+            if (!LOGIN_INFO) throw new LoginException(undefined, LOGIN_ERROR);
+
             this.token = LOGIN_INFO["token"];
             this.refreshTokenVal = LOGIN_INFO["refreshToken"];
             this.expirationSeconds = LOGIN_INFO["expirationSeconds"];
             this.userSessionId = LOGIN_INFO["userSessionId"];
             this.id = LOGIN_INFO["id"];
             _printDatetime(`Login successful`);
+            return LOGIN_INFO;
         }
-        catch (error) 
+        catch (error)
         {
             _printDatetime(`Login failed`);
             throw error;
@@ -359,9 +642,16 @@ class NomadMediaSDK {
     /**
      * @function logout
      * @async
-     * @description Logs out the current user.
-     * @returns {Promise<null>} - A promise that resolves when the logout is successful.
-     * @throws {Error} - An error is thrown if the logout fails.
+     * @description Log out the currently authenticated user and end their session.
+     * Ends the user's active session and invalidates the authentication token. If a UserSessionId
+     * is provided, that specific session is terminated.
+     * @returns {Promise<Object>} Confirmation that the user was successfully logged out and the session was deleted
+     * @throws {Error} 401 - The caller is not authenticated
+     * @example
+     * await nomadSDK.logout();
+     * console.log('User logged out successfully');
+     * 
+     * @see {@link https://docs.nomad-cms.com/api/account/logout Admin API} POST /account/logout
      */
     async logout()
     {
@@ -374,14 +664,15 @@ class NomadMediaSDK {
 
         try
         {
-            await _logout(this);
+            const RESULT = await _logout(this);
             this.token = null;
             this.refreshTokenVal = null;
             this.expirationSeconds = null;
             this.userSessionId = null;
             this.id = null;
-            
+
             _printDatetime(`Logout successful`);
+            return RESULT;
         }
         catch (error)
         {
@@ -393,11 +684,20 @@ class NomadMediaSDK {
     /**
      * @function refreshToken
      * @async
-     * @description Refreshes the current token.
-     * @returns {Promise<void>} - A promise that resolves when the token is refreshed.
-     * Updates the token class variable.
-     * @throws {Error} - An error is thrown if the token refresh fails.
-     */ 
+     * @description Retrieve a new JWT access token using a refresh token.
+     * Exchanges a valid refresh token for a new JWT access token. Automatically updates the SDK
+     * instance's token property on success.
+     * @returns {Promise<boolean>} True if the token was successfully refreshed, false otherwise
+     * @throws {Error} 400 - The request body is null or RefreshToken is missing
+     * @throws {Error} 404 - The refresh token is invalid or has expired
+     * @example
+     * const success = await nomadSDK.refreshToken();
+     * if (success) {
+     *     console.log('Token refreshed successfully');
+     * }
+     * 
+     * @see {@link https://docs.nomad-cms.com/api/account/refresh-token Admin API} POST /account/refresh-token
+     */
     async refreshToken()
     {
         _printDatetime(`Refreshing token`);
@@ -411,6 +711,7 @@ class NomadMediaSDK {
         {
             const REFRESHED = await _refreshToken(this);
             if (REFRESHED) _printDatetime(`Token refresh successful`);
+            return REFRESHED;
         }
         catch (error)
         {
@@ -419,15 +720,59 @@ class NomadMediaSDK {
         }
     }
 
+    /**
+     * @function authenticateWithSSO
+     * @async
+     * @description Authenticates the user using SSO.
+     * @throws {LoginException} - If SSO authentication fails.
+     */
+    async authenticateWithSSO()
+    {
+        if (!this.ssoRedirectUrl)
+        {
+            this.ssoRedirectUrl = `${this.config.serviceApiUrl}/api/auth/${this.ssoProvider}/callback?code=${this.ssoCode}&state=${this.ssoState}&session_state=${this.ssoSessionState}`;
+        }
+
+       try
+        {
+            const response = await axios.get(this.ssoRedirectUrl, {
+                maxRedirects: 0,
+                timeout: 10000
+            });
+
+            throw new LoginException(`SSO authentication failed with status code: ${response.status}`);
+        }
+        catch (error)
+        {
+            if (error.response && error.response.status === 302) {
+                const location = error.response.headers['location'];
+                if (!location) {
+                    throw new LoginException('SSO authentication failed: Missing location header in redirect.');
+                }
+                this.token = location.split("azurePortal_token=")[1]?.split("&")[0] || null;
+                this.refreshTokenVal = location.split("azurePortal_refresh_token=")[1]?.split("&")[0] || null;
+                this.expirationSeconds = location.split("expires=")[1]?.split("&")[0] || null;
+                return;
+            }
+            throw new LoginException(`SSO config parameters are invalid: ${error.message}`);
+        }
+    }
+
     /**
      * @function forgotPassword
      * @async
-     * @description Sends a code to the email to the user to be used 
-     * be used to reset the password.
-     * @returns {Promise<void>}
-     * Sends email with code to reset password.
-     * @throws {Error} - An error is thrown if the code fails to send.
-     */  
+     * @description Trigger a password reset code to be sent to the user's email address.
+     * Initiates the password reset flow for the specified user account. If the account is active, a
+     * 6-digit verification code is sent to the user's email address. The code should then be
+     * submitted to the reset-password endpoint along with the new password.
+     * @returns {Promise<Object>} Response indicating the reset code was sent, or a pending account state
+     * @throws {Error} 400 - The request is null or UserName is missing
+     * @example
+     * const result = await nomadSDK.forgotPassword();
+     * console.log('Password reset code sent to email');
+     * 
+     * @see {@link https://docs.nomad-cms.com/api/account/forgot-password Admin API} POST /account/forgot-password
+     */
     async forgotPassword()
     {
         const USERNAME = this.config.username;
@@ -436,8 +781,9 @@ class NomadMediaSDK {
 
         try
         {
-            await _forgotPassword(this);
+            const RESULT = await _forgotPassword(this);
             _printDatetime(`Code sent to ${USERNAME}`);
+            return RESULT;
         }
         catch (error)
         {
@@ -449,14 +795,20 @@ class NomadMediaSDK {
     /**
      * @function resetPassword
      * @async
-     * @description Resets the password for the specified username.
-     * @param {string} CODE - The code to use to reset the password. Sent to the user's email
-     * by calling forgotPassword().
-     * @param {string} NEW_PASSWORD - The new password to set.
-     * @returns {Promise<void>}
-     * Resets the password for the specified username.
-     * @throws {Error} - An error is thrown if the password fails to reset.
-     */ 
+     * @description Reset the user's password using a verification code from the forgot-password email.
+     * Completes the password reset flow by validating the verification code from the
+     * forgot-password email and setting the new password. For accounts pending approval, this also
+     * completes the email verification step.
+     * @param {string} CODE - The 6-digit verification code from the forgot-password email
+     * @param {string} NEW_PASSWORD - The new password to set for the user
+     * @returns {Promise<Object>} Response confirming the password was successfully reset
+     * @throws {Error} 400 - The request is null, UserName is missing, reset token is invalid/expired, or user is disabled
+     * @example
+     * const result = await nomadSDK.resetPassword('123456', 'newSecurePassword!');
+     * console.log('Password reset successfully');
+     * 
+     * @see {@link https://docs.nomad-cms.com/api/account/reset-password Admin API} POST /account/reset-password
+     */
     async resetPassword(CODE, NEW_PASSWORD)
     {
         const USERNAME = this.config.username;
@@ -465,8 +817,9 @@ class NomadMediaSDK {
 
         try
         {
-            await _resetPassword(this, CODE, NEW_PASSWORD);
+            const RESULT = await _resetPassword(this, CODE, NEW_PASSWORD);
             _printDatetime(`Password reset for ${USERNAME}`);
+            return RESULT;
         }
         catch (error)
         {
@@ -479,14 +832,16 @@ class NomadMediaSDK {
     /**
      * @function clearContinueWatching
      * @async
-     * @description Delete continue watching markers.
-     * @param {string | null} USER_ID - The user ID of the user to clear the continue watching list.
-     * If not user Id is passed it clears the markers of the logged in user.
-     * @param {string | null} ASSET_ID - The asset ID of the asset to clear the continue watching
-     * list. If not asset Id is passed it clears the markers of all assets.
-     * @returns {Promise<void>} - A promise that resolves when the continue watching list is cleared.
-     * @throws {Error} - An error is thrown if the continue watching list fails to clear.
-     * @throws {Error} - An error is thrown if the API type is not portal.
+     * @description Clear a "continue watching" entry for a user.
+     * Removes a specific asset from the user's continue watching list.
+     * @param {string} USER_ID - The unique identifier of the user
+     * @param {string} [ASSET_ID] - The asset ID to remove from continue watching
+     * @returns {Promise<Object>} Response confirming the clearing
+     * @throws {Error} 401 - The caller is not authenticated
+     * @example
+     * await nomadSDK.clearContinueWatching("user-123", "asset-456");
+     * 
+     * @see {@link https://docs.nomad-cms.com/docs/api-guide/media-api/clear-continue-watching Portal API} POST /media/clear-watching
      */
     async clearContinueWatching(USER_ID, ASSET_ID)
     {
@@ -495,7 +850,7 @@ class NomadMediaSDK {
             await this._init();
         }
 
-        if (this.config.apiType !== "portal") 
+        if (this.config.apiType !== "portal")
         {
             throw new Error("This function is only available for portal API type.");
         }
@@ -504,8 +859,9 @@ class NomadMediaSDK {
 
         try
         {
-            await _clearContinueWatching(this, USER_ID, ASSET_ID);
+            const RESULT = await _clearContinueWatching(this, USER_ID, ASSET_ID);
             _printDatetime(`Continue watching cleared`);
+            return RESULT;
         }
         catch (error)
         {
@@ -517,12 +873,15 @@ class NomadMediaSDK {
     /**
      * @function clearWatchlist
      * @async
-     * @description Clears the watchlist.
-     * @param {string | null} USER_ID - The user ID of the user to clear the watchlist.
-     * If not user Id is passed it clears the watchlist of the logged in user.
-     * @returns {Promise<void>} - A promise that resolves when the watchlist is cleared.
-     * @throws {Error} - An error is thrown if the watchlist fails to clear.
-     * @throws {Error} - An error is thrown if the API type is not portal.
+     * @description Clear the user's entire watchlist.
+     * Removes all items from the specified user's watchlist.
+     * @param {string} USER_ID - The unique identifier of the user whose watchlist to clear
+     * @returns {Promise<Object>} Response confirming the watchlist was cleared
+     * @throws {Error} 401 - The caller is not authenticated
+     * @example
+     * await nomadSDK.clearWatchlist("user-123");
+     * 
+     * @see {@link https://docs.nomad-cms.com/docs/api-guide/media-api/clear-watchlist Portal API} POST /media/clear-watchlist
      */
     async clearWatchlist(USER_ID)
     {
@@ -532,7 +891,7 @@ class NomadMediaSDK {
         }
 
         if (this.config.apiType !== "portal")
-        {   
+        {
             throw new Error("This function is only available for portal API type.");
         }
 
@@ -542,8 +901,9 @@ class NomadMediaSDK {
         {
             USER_ID = USER_ID || this.id;
 
-            await _clearWatchlist(this, USER_ID);
+            const RESULT = await _clearWatchlist(this, USER_ID);
             _printDatetime(`Watchlist cleared`);
+            return RESULT;
         }
         catch (error)
         {
@@ -555,16 +915,20 @@ class NomadMediaSDK {
     /**
      * @function createForm
      * @async
-     * @description Gets media.
-     * @param {string} CONTENT_DEFINITION_ID - The ID of the content definition the form
-     * is going in.
-     * @param {JSON} FORM_INFO - The information of the form.
-     * JSON format: whatever key value pairs you want to add to the form.
-     * @returns {Promise<JSON>} - A promise that resolves when the from is created.
-     * Returns the id of the form.
-     * @throws {Error} - An error is thrown if the media fails to get.
-     * @throws {Error} - An error is thrown if the API type is not portal.
-     */ 
+     * @description Create a form submission for a content definition.
+     * Submits form data to create a new entry for the specified content definition. Used for
+     * user-generated content submissions through portal forms.
+     * @param {string} CONTENT_DEFINITION_ID - The content definition ID for the form type
+     * @param {Object} FORM_INFO - The form data to submit
+     * @returns {Promise<Object>} The created content entry
+     * @throws {Error} 401 - The caller is not authenticated
+     * @example
+     * const entry = await nomadSDK.createForm("def-123", {
+     *     title: "My Submission", description: "Description"
+     * });
+     * 
+     * @see {@link https://docs.nomad-cms.com/docs/api-guide/media-api/create-form Portal API} POST /media/form/{contentDefinitionId}
+     */
     async createForm(CONTENT_DEFINITION_ID, FORM_INFO)
     {
         if (this.token === null && this.config.username)
@@ -595,14 +959,17 @@ class NomadMediaSDK {
     /**
      * @function getContentCookies
      * @async
-     * @description Gets content cookies.
-     * @param {string} CONTENT_ID - The Id of the content to retrieve the cookies for. 
-     * This can be the ID for the content definition of the LiveChannel, or a folder asset 
-     * ID or a specific Asset ID.
-     * @returns {Promise<JSON>} - A promise that resolves when the content cookies are gotten.
-     * Returns the information of the gotten content cookies.
-     * @throws {Error} - An error is thrown if the content cookies fail to get.
-     * @throws {Error} - An error is thrown if the API type is not portal.
+     * @description Retrieve secure streaming cookies for portal media content.
+     * Gets signed cookies required for secure streaming of media content through the portal API.
+     * The cookies authorize CDN access to the media files.
+     * @param {string} CONTENT_ID - The unique identifier of the media content
+     * @returns {Promise<Object>} Streaming cookies and manifest URL for the content
+     * @throws {Error} 401 - The caller is not authenticated
+     * @throws {Error} 404 - The content was not found
+     * @example
+     * const cookies = await nomadSDK.getContentCookies("media-123");
+     * 
+     * @see {@link https://docs.nomad-cms.com/docs/api-guide/asset-api-1 Portal API} GET /media/set-cookies/{id}
      */
     async getContentCookies(CONTENT_ID)
     {
@@ -634,11 +1001,15 @@ class NomadMediaSDK {
     /**
      * @function getDefaultSiteConfig
      * @async
-     * @description Gets default site config.
-     * @returns {Promise<Array<JSON>>} - A promise that resolves when the default site config is gotten.
-     * Returns the information of the gotten dynamic content.
-     * @throws {Error} - An error is thrown if the dynamic content fails to get.
-     * @throws {Error} - An error is thrown if the API type is not portal.
+     * @description Retrieve the default site configuration.
+     * Gets the default portal site configuration used when no specific configuration ID is
+     * provided.
+     * @returns {Promise<Object>} The default site configuration object
+     * @throws {Error} 401 - The caller is not authenticated
+     * @example
+     * const config = await nomadSDK.getDefaultSiteConfig();
+     * 
+     * @see {@link https://docs.nomad-cms.com/docs/api-guide/media-api/get-default-site-config Portal API} GET /media/config
      */
     async getDefaultSiteConfig()
     {
@@ -670,12 +1041,17 @@ class NomadMediaSDK {
     /**
      * @function getDynamicContent
      * @async
-     * @description Gets dynamic content.
-     * @param {string} DYNAMIC_CONTENT_RECORD_ID - The dynamic content record ID.
-     * @returns {Promise<JSON>} - A promise that resolves when the dynamic content is gotten.
-     * Returns the information of the gotten dynamic content.
-     * @throws {Error} - An error is thrown if the dynamic content fails to get.
-     * @throws {Error} - An error is thrown if the API type is not portal.
+     * @description Retrieve a dynamic content item by its unique identifier.
+     * Gets a dynamically generated content item used for personalized or rule-based content display
+     * on the portal.
+     * @param {string} DYNAMIC_CONTENT_RECORD_ID - The unique identifier of the dynamic content
+     * @returns {Promise<Object>} The dynamic content object with its configuration and items
+     * @throws {Error} 401 - The caller is not authenticated
+     * @throws {Error} 404 - The dynamic content was not found
+     * @example
+     * const content = await nomadSDK.getDynamicContent("dynamic-123");
+     * 
+     * @see {@link https://docs.nomad-cms.com/docs/api-guide/media-api/get-dynamic-content Portal API} GET /media/content/{id}
      */
     async getDynamicContent(DYNAMIC_CONTENT_RECORD_ID)
     {
@@ -702,11 +1078,15 @@ class NomadMediaSDK {
     /**
      * @function getDynamicContents
      * @async
-     * @description Gets dynamic contents.
-     * @returns {Promise<Array<JSON>>} - A promise that resolves when the dynamic contents is gotten.
-     * Returns the information of the gotten dynamic content.
-     * @throws {Error} - An error is thrown if the dynamic content fails to get.
-     * @throws {Error} - An error is thrown if the API type is not portal.
+     * @description Retrieve all dynamic content items.
+     * Gets the list of all dynamic content configurations available for the portal front-end.
+     * @returns {Promise<Object>} Array of dynamic content objects
+     * @throws {Error} 401 - The caller is not authenticated
+     * @example
+     * const contents = await nomadSDK.getDynamicContents();
+     * contents.forEach(c => console.log(c.id, c.name));
+     * 
+     * @see {@link https://docs.nomad-cms.com/docs/api-guide/media-api/get-dynamic-contents Portal API} GET /media/content
      */
     async getDynamicContents()
     {
@@ -738,15 +1118,21 @@ class NomadMediaSDK {
     /**
      * @function getMediaGroup
      * @async
-     * @description Gets media group.
-     * @param {string} MEDIA_GROUP_ID - The ID of the media group.
-     * @param { Array<string> } FILTER_IDS - The IDs of the media group items to filter by.
-     * @returns {Promise<JSON>} - A promise that resolves when the media group is gotten.
-     * Returns the information of the gotten media group.
-     * @throws {Error} - An error is thrown if the media group fails to get.
-     * @throws {Error} - An error is thrown if the API type is not portal.
+     * @description Retrieve a media group by its unique identifier.
+     * Gets a media group and its contents with optional content filtering. Media groups organize
+     * content items for portal display.
+     * @param {string} MEDIA_GROUP_ID - The unique identifier of the media group
+     * @param {Array<string>} [FILTER_IDS] - Optional array of content IDs to filter results
+     * @param {string} [LANGUAGE_ID] - Optional language ID to localize the response
+     * @returns {Promise<Object>} The media group object with its contents
+     * @throws {Error} 401 - The caller is not authenticated
+     * @throws {Error} 404 - The media group was not found
+     * @example
+     * const group = await nomadSDK.getMediaGroup("group-123", ["item-1", "item-2"]);
+     * 
+     * @see {@link https://docs.nomad-cms.com/docs/api-guide/media-api/get-media-group Portal API} GET /media/group/{id}
      */
-    async getMediaGroup(MEDIA_GROUP_ID, FILTER_IDS)
+    async getMediaGroup(MEDIA_GROUP_ID, FILTER_IDS, LANGUAGE_ID)
     {
         if (this.token === null && this.config.username)
         {
@@ -762,7 +1148,7 @@ class NomadMediaSDK {
 
         try
         {
-            const GET_MEDIA_GROUP_INFO = await _getMediaGroup(this, MEDIA_GROUP_ID, FILTER_IDS);
+            const GET_MEDIA_GROUP_INFO = await _getMediaGroup(this, MEDIA_GROUP_ID, FILTER_IDS, LANGUAGE_ID);
             if (GET_MEDIA_GROUP_INFO) _printDatetime(`Media group gotten: ${MEDIA_GROUP_ID}`);
             return GET_MEDIA_GROUP_INFO;
         }
@@ -776,12 +1162,18 @@ class NomadMediaSDK {
     /**
      * @function getMediaItem
      * @async
-     * @description Gets media item.
-     * @param {string} MEDIA_ITEM_ID - The ID of the media item.
-     * @returns {Promise<JSON>} - A promise that resolves when the media item is gotten.
-     * Returns the information of the gotten media item.
-     * @throws {Error} - An error is thrown if the media item fails to get.
-     * @throws {Error} - An error is thrown if the API type is not portal.
+     * @description Retrieve a media item by its unique identifier.
+     * Gets the full media item details including metadata, content definitions, and playback
+     * information for the portal front-end.
+     * @param {string} MEDIA_ITEM_ID - The unique identifier of the media item
+     * @returns {Promise<Object>} The media item object with metadata and content details
+     * @throws {Error} 401 - The caller is not authenticated
+     * @throws {Error} 404 - The media item was not found
+     * @example
+     * const item = await nomadSDK.getMediaItem("item-123");
+     * console.log(item.title);
+     * 
+     * @see {@link https://docs.nomad-cms.com/docs/api-guide/media-api/get-media-item Portal API} GET /media/item/{id}
      */
     async getMediaItem(MEDIA_ITEM_ID)
     {
@@ -813,13 +1205,14 @@ class NomadMediaSDK {
     /**
      * @function getMyContent
      * @async
-     * @description Gets favorites and continue watching lists of IDs for the logged in user.
-     * @returns {Promise<JSON>} - A promise that resolves when the favorites and continue watching
-     * lists of IDs are gotten.
-     * Returns the information of the gotten favorites and continue watching lists of IDs.
-     * @throws {Error} - An error is thrown if the favorites and continue watching lists of IDs fail
-     * to get.
-     * @throws {Error} - An error is thrown if the API type is not portal.
+     * @description Retrieve the authenticated user's personal content.
+     * Gets all content items owned by or assigned to the currently authenticated user.
+     * @returns {Promise<Object>} Array of content items belonging to the user
+     * @throws {Error} 401 - The caller is not authenticated
+     * @example
+     * const myContent = await nomadSDK.getMyContent();
+     * 
+     * @see {@link https://docs.nomad-cms.com/docs/api-guide/media-api/get-my-content Portal API} GET /media/my-content
      */
     async getMyContent()
     {
@@ -830,7 +1223,7 @@ class NomadMediaSDK {
 
         if (this.config.apiType !== "portal")
         {
-            throw new Error("This function is not available for portal API type.");
+            throw new Error("This function is only available for portal API type.");
         }
 
         _printDatetime(`Getting my content`);
@@ -851,25 +1244,36 @@ class NomadMediaSDK {
     /**
      * @function getMyGroup
      * @async
-     * @description Gets user's group.
-     * @param {string} GROUP_ID - The ID of the group.
-     * @returns {Promise<JSON>} - A promise that resolves when the user's group is gotten.
-     * Returns the information of the gotten user's group.
-     * @throws {Error} - An error is thrown if the user's group fails to get.
-     * @throws {Error} - An error is thrown if the API type is not portal.
+     * @description Retrieve a personal content group by its unique identifier.
+     * Gets a content group from the user's personal groups, including its contents and
+     * configuration.
+     * @param {string} GROUP_ID - The unique identifier of the personal group
+     * @param {Array<string>} [FILTER_IDS] - Optional array of content IDs to filter results
+     * @returns {Promise<Object>} The personal group object with its contents
+     * @throws {Error} 401 - The caller is not authenticated
+     * @throws {Error} 404 - The group was not found
+     * @example
+     * const group = await nomadSDK.getMyGroup("group-123");
+     * 
+     * @see {@link https://docs.nomad-cms.com/docs/api-guide/media-api/get-my-group Portal API} GET /media/my-group/{id}
      */
-    async getMyGroup(GROUP_ID)
+    async getMyGroup(GROUP_ID, FILTER_IDS)
     {
         if (this.token === null && this.config.username)
         {
             await this._init();
         }
 
+        if (this.config.apiType !== "portal")
+        {
+            throw new Error("This function is only available for portal API type.");
+        }
+
         _printDatetime(`Getting my group: ${GROUP_ID}`);
 
         try
         {
-            const GET_MY_GROUP_INFO = await _getMyGroup(this, GROUP_ID);
+            const GET_MY_GROUP_INFO = await _getMyGroup(this, GROUP_ID, FILTER_IDS);
             if (GET_MY_GROUP_INFO) _printDatetime(`My group gotten: ${GROUP_ID}`);
             return GET_MY_GROUP_INFO;
         }
@@ -883,12 +1287,17 @@ class NomadMediaSDK {
     /**
      * @function getSiteConfig
      * @async
-     * @description Gets site config.
-     * @param {string} SITE_CONFIG_RECORD_ID - The site config record ID.
-     * @returns {Promise<JSON>} - A promise that resolves when the site config is gotten.
-     * Returns the information of the gotten site config.
-     * @throws {Error} - An error is thrown if the site config fails to get.
-     * @throws {Error} - An error is thrown if the API type is not portal.
+     * @description Retrieve a site configuration by its unique identifier.
+     * Gets the portal site configuration including theme, layout, navigation, and content display
+     * settings.
+     * @param {string} SITE_CONFIG_RECORD_ID - The unique identifier of the site configuration
+     * @returns {Promise<Object>} The site configuration object
+     * @throws {Error} 401 - The caller is not authenticated
+     * @throws {Error} 404 - The site configuration was not found
+     * @example
+     * const config = await nomadSDK.getSiteConfig("config-123");
+     * 
+     * @see {@link https://docs.nomad-cms.com/docs/api-guide/media-api/get-site-config Portal API} GET /media/config/{id}
      */
     async getSiteConfig(SITE_CONFIG_RECORD_ID)
     {
@@ -897,6 +1306,11 @@ class NomadMediaSDK {
             await this._init();
         }
 
+        if (this.config.apiType !== "portal")
+        {
+            throw new Error("This function is only available for portal API type.");
+        }
+
         _printDatetime(`Getting site config: ${SITE_CONFIG_RECORD_ID}`);
 
         try
@@ -915,18 +1329,23 @@ class NomadMediaSDK {
     /**
      * @function mediaSearch
      * @async
-     * @description Searches for media.
-     * @param {string | null} QUERY - The query of the search.
-     * @param {Array<string> | null} IDS - The IDs of the media to be searched.
-     * @param {Array<JSON> | null} SORT_FIELDS - The sort fields of the search.
-     * JSON format: [{"fieldName": "string", "sortType": ("Ascending" | "Descending")} ...]
-     * @param {number | null} OFFSET - The page offset of the search.
-     * @param {number | null} SIZE - The page size of the search.
-     * @returns {Promise<JSON>} - A promise that resolves when the media are searched.
-     * Returns the information of the searched media.
-     * @throws {Error} - An error is thrown if the media fail to search.
-     * @throws {Error} - An error is thrown if the API type is not portal.
-     */ 
+     * @description Search for media content using a query string and optional filters.
+     * Performs a search against the media index with support for pagination, sorting, and ID
+     * filtering. Defaults to page offset 0 and page size 100.
+     * @param {Object} QUERY - The search query object containing search criteria
+     * @param {Array<string>} [IDS] - Optional array of specific content IDs to filter by
+     * @param {Array<Object>} [SORT_FIELDS] - Optional array of sort field objects
+     * @param {number} [OFFSET] - The page offset for pagination (defaults to 0)
+     * @param {number} [SIZE] - The number of results per page (defaults to 100)
+     * @returns {Promise<Object>} Search results containing items array and pagination info
+     * @throws {Error} 401 - The caller is not authenticated
+     * @example
+     * const results = await nomadSDK.mediaSearch(
+     *     { query: "news" }, null, [{ fieldName: "date", order: "desc" }], 0, 25
+     * );
+     * 
+     * @see {@link https://docs.nomad-cms.com/docs/api-guide/media-api/media-search Portal API} POST /media/search
+     */
     async mediaSearch(QUERY, IDS, SORT_FIELDS, OFFSET, SIZE)
     {
         if (this.token === null && this.config.username)
@@ -1039,12 +1458,33 @@ export default NomadMediaSDK;
 
 
 
-async function _forgotPassword(instance) 
+/**
+ * Trigger a password reset code to be sent to the user's email address.
+ *
+ * Initiates the password reset flow for the specified user account. If the account is active,
+ * a 6-digit verification code is sent to the user's email address. The code should then be
+ * submitted to the reset-password endpoint along with the new password.
+ *
+ * **Authorization:** Public endpoint — no authentication required.
+ *
+ * **Side Effects:** Sends a password reset email with a 6-digit verification code to the user.
+ *
+ * @param {Object} instance - The SDK instance containing configuration (username)
+ * @returns {Promise<Object>} Response indicating the reset code was sent, or a pending account state
+ * @throws {Error} 400 - The request is null or UserName is missing
+ *
+ * @example
+ * const result = await nomadSDK.forgotPassword();
+ * console.log('Password reset code sent to email');
+ *
+ * @see {@link https://docs.nomad-cms.com/api/account/forgot-password Admin API} POST /account/forgot-password
+ */
+async function _forgotPassword(instance)
 {
 	const API_URL = `${instance.config.serviceApiUrl}/api/account/forgot-password`;
 
 	const BODY = {
-		username: instance.config.username
+		userName: instance.config.username
 	};
 
 	return await _sendRequest(instance, "Forgot Password", API_URL, "POST", undefined, BODY);
@@ -1053,6 +1493,41 @@ async function _forgotPassword(instance)
 
 
 
+/**
+ * Authenticate a user and obtain a JWT access token.
+ *
+ * Validates the user's credentials and, if successful, creates a new session and returns
+ * a JWT access token with a refresh token. Accounts that are disabled, expired, pending invitation, or pending
+ * approval will be rejected. Guest users must have a valid profile and permitted application access.
+ *
+ * **Authorization:** Public endpoint — no authentication required.
+ *
+ * **Side Effects:** Creates a new user session. The login event is recorded for auditing purposes.
+ *
+ * **Error Scenarios:**
+ * - Returns 400 if the request body is null or missing required fields
+ * - Returns 404 if authentication fails or the user cannot be found
+ * - Returns 403 if the user account is Disabled, Expired, PendingInvitation, or PendingApproval
+ * - LoginStatus on the response indicates the specific failure reason (e.g., IsDisabled, IsPendingEmailConfirmation, RequiresNewPassword)
+ *
+ * @param {Object} instance - The SDK instance containing configuration (username, password, serviceApiUrl, and optionally applicationId)
+ * @returns {Promise<Object>} Authentication response. User-identity fields (from the backend
+ *     `AccountLoginResponseModel`): `id`, `userName`, `firstName`, `lastName`, `loginStatus`,
+ *     `cookies`. Session/token fields consumed by the SDK: `token`, `refreshToken`,
+ *     `expirationSeconds`, `userSessionId`. Note: there is no `userId` or `expiresIn` field;
+ *     use `id` and `expirationSeconds` respectively.
+ * @throws {Error} 400 - The request body is null or missing required fields (UserName, Password)
+ * @throws {Error} 404 - Authentication failed — invalid credentials or user not found
+ * @throws {Error} 403 - User account is Disabled, Expired, PendingInvitation, or PendingApproval
+ *
+ * @example
+ * const response = await nomadSDK.login();
+ * console.log('Access Token:', response.token);
+ * console.log('User ID:', response.id);
+ * console.log('User Name:', response.userName);
+ *
+ * @see {@link https://docs.nomad-cms.com/api/account/login Admin API} POST /account/login
+ */
 async function _login(instance)
 {
     const API_URL = `${instance.config.serviceApiUrl}/api/account/login`;
@@ -1062,6 +1537,9 @@ async function _login(instance)
         "password": instance.config.password
     };
 
+    // Optional: ties the session to an application (config.applicationId), as ping and logout do.
+    if (instance.config.applicationId) BODY.applicationId = instance.config.applicationId;
+
     try
     {
         return await _sendRequest(instance, "Login", API_URL, "POST", undefined, BODY);
@@ -1083,11 +1561,38 @@ async function _login(instance)
 
 
 
+/**
+ * Log out the currently authenticated user and end their session.
+ *
+ * Ends the user's active session and invalidates the authentication token.
+ * If a UserSessionId is provided, that specific session is terminated.
+ *
+ * **Authorization:** Requires a valid Bearer token.
+ *
+ * **Side Effects:** Terminates the user session. The logout event is recorded for auditing purposes.
+ *
+ * @param {Object} instance - The SDK instance containing configuration and session information (the session ID and optional applicationId are sent in the request body)
+ * @returns {Promise<Object>} Confirmation that the user was successfully logged out and the session was deleted
+ * @throws {Error} 401 - The caller is not authenticated
+ *
+ * @example
+ * await nomadSDK.logout();
+ * console.log('User logged out successfully');
+ *
+ * @see {@link https://docs.nomad-cms.com/api/account/logout Admin API} POST /account/logout
+ */
 async function _logout(instance)
 {
     const API_URL = `${instance.config.serviceApiUrl}/api/account/logout`;
 
-    return await _sendRequest(instance, "Logout", API_URL, "POST", undefined, undefined);
+    // The API requires a request body; an empty body is rejected with 400.
+    // Undefined fields are dropped by JSON serialisation, so this is at worst "{}".
+    const BODY = {
+        userSessionId: instance.userSessionId ?? undefined,
+        applicationId: instance.config.applicationId ?? undefined
+    };
+
+    return await _sendRequest(instance, "Logout", API_URL, "POST", undefined, BODY);
 }
 
 
@@ -1096,7 +1601,30 @@ async function _logout(instance)
 
 
 
-async function _refreshToken(instance) 
+/**
+ * Retrieve a new JWT access token using a refresh token.
+ *
+ * Exchanges a valid refresh token for a new JWT access token. Automatically updates
+ * the SDK instance's token property on success.
+ *
+ * **Authorization:** Public endpoint — no authentication required. The refresh token itself serves as the credential.
+ *
+ * **Side Effects:** Updates the SDK instance's token property with the new access token.
+ *
+ * @param {Object} instance - The SDK instance containing configuration and refreshTokenVal
+ * @returns {Promise<boolean>} True if the token was successfully refreshed, false otherwise
+ * @throws {Error} 400 - The request body is null or RefreshToken is missing
+ * @throws {Error} 404 - The refresh token is invalid or has expired
+ *
+ * @example
+ * const success = await nomadSDK.refreshToken();
+ * if (success) {
+ *     console.log('Token refreshed successfully');
+ * }
+ *
+ * @see {@link https://docs.nomad-cms.com/api/account/refresh-token Admin API} POST /account/refresh-token
+ */
+async function _refreshToken(instance)
 {
     const API_URL = `${instance.config.serviceApiUrl}/api/account/refresh-token`;
 
@@ -1104,22 +1632,69 @@ async function _refreshToken(instance)
         refreshToken: instance.refreshTokenVal
     };
 
-    const TOKEN_INFO = await _sendRequest(instance, "Refreshing Token", API_URL, "POST", undefined, BODY);
-    instance.token = TOKEN_INFO.token;
+    // _sendRequest() now throws on failure (api-exception-handler.js) rather
+    // than resolving to a falsy value — but this function's own contract
+    // ("returns false, never throws" — see its own doc comment/callers)
+    // predates that and must be preserved regardless: _sendRequest()'s own
+    // 403-retry logic calls this and explicitly checks the boolean result to
+    // decide whether to fall back to a full re-login. Letting a failed
+    // refresh (e.g. an expired/already-used refresh token, a 409) throw
+    // uncaught here would crash that entire retry path instead of correctly
+    // falling through to login().
+    let TOKEN_INFO;
+    try
+    {
+        TOKEN_INFO = await _sendRequest(instance, "Refreshing Token", API_URL, "POST", undefined, BODY);
+    }
+    catch (error)
+    {
+        return false;
+    }
+
+    if (TOKEN_INFO && TOKEN_INFO.token)
+    {
+        instance.token = TOKEN_INFO.token;
+        return true;
+    }
 
-    return true;
+    return false;
 }
 
 
 
 
 
-async function _resetPassword(instance, CODE, NEW_PASSWORD) 
+/**
+ * Reset the user's password using a verification code from the forgot-password email.
+ *
+ * Completes the password reset flow by validating the verification code from the forgot-password
+ * email and setting the new password. For accounts pending approval, this also completes the
+ * email verification step.
+ *
+ * **Authorization:** Public endpoint — no authentication required. The reset token serves as the credential.
+ *
+ * **Side Effects:**
+ * - Updates the user's password
+ * - For pending-approval accounts, also verifies the email address
+ *
+ * @param {Object} instance - The SDK instance containing configuration (username)
+ * @param {string} CODE - The 6-digit verification code from the forgot-password email
+ * @param {string} NEW_PASSWORD - The new password to set for the user
+ * @returns {Promise<Object>} Response confirming the password was successfully reset
+ * @throws {Error} 400 - The request is null, UserName is missing, reset token is invalid/expired, or user is disabled
+ *
+ * @example
+ * const result = await nomadSDK.resetPassword('123456', 'newSecurePassword!');
+ * console.log('Password reset successfully');
+ *
+ * @see {@link https://docs.nomad-cms.com/api/account/reset-password Admin API} POST /account/reset-password
+ */
+async function _resetPassword(instance, CODE, NEW_PASSWORD)
 {
 	const API_URL = `${instance.config.serviceApiUrl}/api/account/reset-password`;
 
   	const BODY = {
-        userName: instance.username,
+        userName: instance.config.username,
         token: CODE,
         newPassword: NEW_PASSWORD
     };
@@ -1128,52 +1703,113 @@ async function _resetPassword(instance, CODE, NEW_PASSWORD)
 }
 
 
-function _apiExceptionHandler(error, message) 
+/**
+ * Builds and throws a real Error for a failed API call, instead of logging
+ * and swallowing it.
+ *
+ * This used to log via console.error and return null on every failure — a
+ * design that made a genuinely failed request indistinguishable, to any
+ * caller, from a real (if empty/falsy) success. Confirmed live to be the
+ * root cause of several serious bugs: createContent() reporting "Content
+ * created" for a record whose properties write had actually failed
+ * (a rejected Lookup Multi-Select shape), updateAsset() silently no-opping
+ * while an asset was still mid-upload, and getContent() returning `null`
+ * for a genuine 404 rather than letting a caller distinguish "not found"
+ * from "found, something else is wrong." Every one of those bugs required
+ * tracing through live server logs to find, specifically because nothing
+ * in this SDK's own return value or a thrown exception ever said so.
+ *
+ * @param {Error|Object|string} error - The underlying error (an Axios error,
+ *   a parsed error-response body, or a plain string message)
+ * @param {string} message - A human-readable prefix describing what failed
+ *   (e.g. "Update Content failed")
+ * @param {number} [status] - The HTTP status code, when known, attached to
+ *   the thrown error as `.status` so callers can distinguish e.g. a 404
+ *   from a 403 without parsing the message text.
+ * @throws {Error} Always — with `.message` built from `message` + whatever
+ *   detail could be extracted from `error`, `.cause` set to the original
+ *   `error` value, and `.status` set when provided.
+ */
+function _apiExceptionHandler(error, message, status)
 {
-    // Check if we have a response object and error message
-    if (!error) 
+    let detail;
+
+    if (!error)
     {
-        console.error(message);
+        detail = undefined;
     }
-
-    // Check if error is a string
-    if (typeof error === "string") 
+    else if (typeof error === "string")
     {
-        console.error(`${message}: ${error}`);
+        detail = error;
     }
     else if (error.errors)
     {
-        if (Array.isArray(error.errors)) 
+        if (Array.isArray(error.errors))
         {
             let errorString = "";
-            for (let errorIdx = 0; errorIdx < error.errors.length; errorIdx++) 
+            for (let errorIdx = 0; errorIdx < error.errors.length; errorIdx++)
             {
-                errorString += `${error.errors[errorIdx].code}: ${error.errors[errorIdx].field}: ${error.errors[errorIdx].message}\n`; 
+                errorString += `${error.errors[errorIdx].code}: ${error.errors[errorIdx].field}: ${error.errors[errorIdx].message}\n`;
             }
-            console.error(`${message}: ${errorString}`);
-        } 
-        else if (typeof error.errors === "object") 
+            detail = errorString;
+        }
+        else if (typeof error.errors === "object")
         {
             let errorString = "";
-            for (let key in error.errors) 
+            for (let key in error.errors)
             {
-                if (Object.prototype.hasOwnProperty.call(error.errors, key)) 
+                if (Object.prototype.hasOwnProperty.call(error.errors, key))
                 {
                     errorString += `${key}: ${error.errors[key]}\n`;
                 }
             }
-            console.error(`${message}: ${errorString}`);
+            detail = errorString;
         }
     }
     else
     {
-        console.error(`${message}: ${error.message}`);
+        detail = error.message;
+    }
+
+    const thrown = new Error(detail ? `${message}: ${detail}` : message);
+    thrown.cause = error;
+    if (status !== undefined && status !== null) thrown.status = status;
+    throw thrown;
+}
+
+
+class InvalidAPITypeException extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "InvalidAPITypeException";
     }
+}
 
-    return null;
+class MissingCredentialsException extends Error {
+    constructor(credentials = null, message = "Missing login credentials") {
+        if (credentials) {
+            message = `${message}: ${Array.isArray(credentials) ? credentials.join(", ") : credentials}`;
+        }
+        super(message);
+        this.name = "MissingCredentialsException";
+        this.credentials = credentials;
+    }
+}
+
+class LoginException extends Error {
+    constructor(message = "Login info incorrect", cause = undefined) {
+        super(message);
+        this.name = "LoginException";
+        if (cause !== undefined)
+        {
+            this.cause = cause;
+            if (cause && cause.status !== undefined) this.status = cause.status;
+        }
+    }
 }
 
 
+
 import { getRandomValues } from 'crypto';
 
 function _newGuid() 
@@ -1196,51 +1832,116 @@ function _printDatetime(msg)
 import { promises as fs } from 'fs';
 import path from 'path';
 
+/**
+ * Normalizes the file argument of an upload into the properties the upload
+ * needs, without reading the file's contents into memory.
+ *
+ * Accepts:
+ * - a file path (Node.js only), read part by part from disk
+ * - a browser `File`/`Blob`, read part by part with `slice()`
+ * - an object that already carries its bytes in `buffer` (for example a
+ *   multer file), plus `size` and a name
+ *
+ * @param {string|File|Blob|Object} FILE - The file to upload
+ * @returns {Promise<{originalName: string, size: number, path?: string, blob?: Blob, buffer?: Buffer|ArrayBuffer|Uint8Array}>}
+ *   The file's name and size, and the single source its parts are read from
+ * @throws {Error} When the path does not exist, or a path is given in a browser
+ */
 async function _processFile(FILE)
 {
-    let FILE_PATH = null;
     if (typeof FILE === "string")
     {
-        // if running in node
-        if (typeof window === "undefined")
+        if (typeof window !== "undefined")
         {
-            FILE_PATH = FILE;
-            FILE = await fs.stat(FILE);
-            FILE.originalName = path.basename(FILE_PATH);
-            if (!FILE.buffer)
-            {
-                FILE.buffer = await fs.readFile(FILE_PATH);
-            }
+            throw new Error("File path is not supported in browser");
         }
-        else
+
+        let stats;
+        try
         {
-            throw new Error("File path is not supported in browser");
+            stats = await fs.stat(FILE);
         }
-    }
-    else
-    {
-        FILE.originalName = FILE.name;
-        // if running in browser
-        if (!FILE.buffer)
+        catch (error)
         {
-            FILE.buffer = await _readFileAsArrayBuffer(FILE);
+            const notFound = new Error(`File not found: ${FILE}`);
+            notFound.code = error.code;
+            notFound.cause = error;
+            throw notFound;
         }
+
+        if (!stats.isFile())
+        {
+            throw new Error(`Not a file: ${FILE}`);
+        }
+
+        return { originalName: path.basename(FILE), size: stats.size, path: FILE };
     }
 
-    return FILE;
+    const originalName = FILE.originalName || FILE.name || FILE.originalname;
+
+    if (FILE.buffer)
+    {
+        const size = FILE.size ?? FILE.buffer.byteLength;
+        return { originalName, size, buffer: FILE.buffer };
+    }
+
+    if (typeof FILE.slice === "function")
+    {
+        return { originalName, size: FILE.size, blob: FILE };
+    }
+
+    throw new Error("Unsupported file: pass a file path, a File/Blob, or an object with a buffer");
 }
 
-async function _readFileAsArrayBuffer(file) 
+/**
+ * Opens a reader that returns the bytes of one part at a time.
+ *
+ * In Node.js a path is read with positional reads on a single file handle, so
+ * concurrent parts never share or move a file position. Blobs are sliced
+ * lazily and buffers are viewed without copying.
+ *
+ * @param {Object} FILE_PROPS - The result of `_processFile`
+ * @returns {Promise<{read: function(number, number): Promise<Buffer|Uint8Array|Blob>, close: function(): Promise<void>}>}
+ *   `read(start, end)` returns the bytes from `start` to `end` inclusive
+ */
+async function _openPartReader(FILE_PROPS)
 {
-    return new Promise((resolve, reject) => 
+    if (FILE_PROPS.path)
     {
-        /* eslint-disable no-undef */
-        const reader = new FileReader();
-        /* eslint-enable no-undef */
-        reader.onload = () => resolve(reader.result);
-        reader.onerror = reject;
-        reader.readAsArrayBuffer(file);
-    });
+        const HANDLE = await fs.open(FILE_PROPS.path, "r");
+        return {
+            async read(START, END)
+            {
+                const LENGTH = END + 1 - START;
+                const PART = Buffer.alloc(LENGTH);
+                let offset = 0;
+                while (offset < LENGTH)
+                {
+                    const { bytesRead } = await HANDLE.read(PART, offset, LENGTH - offset, START + offset);
+                    if (bytesRead === 0) throw new Error(`Unexpected end of file reading bytes ${START}-${END}`);
+                    offset += bytesRead;
+                }
+                return PART;
+            },
+            close: () => HANDLE.close()
+        };
+    }
+
+    if (FILE_PROPS.blob)
+    {
+        return {
+            read: async (START, END) => FILE_PROPS.blob.slice(START, END + 1),
+            close: async () => {}
+        };
+    }
+
+    const BYTES = FILE_PROPS.buffer instanceof ArrayBuffer
+        ? new Uint8Array(FILE_PROPS.buffer)
+        : FILE_PROPS.buffer;
+    return {
+        read: async (START, END) => BYTES.subarray(START, END + 1),
+        close: async () => {}
+    };
 }
 
 
@@ -1248,7 +1949,10 @@ async function _readFileAsArrayBuffer(file)
 
 
 
-import axios from 'axios';
+
+
+
+
 
 const MAX_RETRIES = 3;
 const TIMEOUT = 10000;
@@ -1263,8 +1967,22 @@ async function _sendRequest(instance, FUNCTION_NAME, URL, METHOD_TYPE, PARAMS, B
     if (instance.token) HEADERS["Authorization"] = `Bearer ${instance.token}`;
     else if (instance.config.apiKey) HEADERS["Authorization"] = `ApiKey ${instance.config.apiKey}`;
 
-    if (instance.debug && FUNCTION_NAME !== "Login") console.log(`URL: ${URL}\nMETHOD: ${METHOD_TYPE}` + (PARAMS && PARAMS.size === 0 ? `\nPARAMS: ${JSON.stringify(PARAMS, null, 4)}` : "")  + (BODY ? `\nBODY: ${JSON.stringify(BODY, null, 4)}` : ""));
+    // A missing required id argument would otherwise be sent to the server as ".../undefined".
+    // String(URL) so a caller that built a URL object does not crash the check.
+    const URL_PATH = String(URL).split("?")[0];
+    if (/\/(undefined|null)(\/|\?|$)/.test(URL_PATH))
+    {
+        _apiExceptionHandler(`a required id argument was not provided (${URL_PATH})`, `${FUNCTION_NAME} failed`);
+    }
+
+    const HAS_PARAMS = PARAMS && Object.keys(PARAMS).length > 0;
+    if (instance.debug && FUNCTION_NAME !== "Login") console.log(`URL: ${URL}\nMETHOD: ${METHOD_TYPE}` + (HAS_PARAMS ? `\nPARAMS: ${JSON.stringify(PARAMS, null, 4)}` : "")  + (BODY ? `\nBODY: ${JSON.stringify(BODY, null, 4)}` : ""));
+
+    // Only requests that are safe to repeat are retried after a timeout. A timed-out
+    // POST/PUT/DELETE may already have been applied by the server.
+    const IS_IDEMPOTENT = ["GET", "HEAD", "OPTIONS"].includes(String(METHOD_TYPE).toUpperCase());
 
+    let lastError = null;
     let retries = 0;
     let RESPONSE = null;
     let refreshedToken = false;
@@ -1288,32 +2006,58 @@ async function _sendRequest(instance, FUNCTION_NAME, URL, METHOD_TYPE, PARAMS, B
 
             throw new Error();
         } 
-        catch (error) 
+        catch (error)
         {
+            lastError = error;
+            const ERROR_MESSAGE = error.response?.data?.message ? error.response.data.message : error.message;
+
             if (retries >= MAX_RETRIES)
             {
-                return _apiExceptionHandler(error.response?.data.message ? error.response.data.message : error.message, `${FUNCTION_NAME} failed`);
+                _apiExceptionHandler(ERROR_MESSAGE, `${FUNCTION_NAME} failed`, error.response?.status);
             }
 
             if (error?.response?.status === 403 && FUNCTION_NAME !== "Refresh Token" && !refreshedToken)
             {
-                await instance.refreshToken();
-                HEADERS["Authorization"] = `Bearer ${instance.token}`;
-                refreshedToken = true;
+                if (!instance.refreshTokenVal)
+                {
+                    throw new LoginException();
+                }
+
+                const refreshSuccess = await instance.refreshToken();
+                if (refreshSuccess)
+                {
+                    HEADERS["Authorization"] = `Bearer ${instance.token}`;
+                    refreshedToken = true;
+                }
+                else
+                {
+                    // If refresh token is invalid, fall back to login
+                    await instance.login();
+                    HEADERS["Authorization"] = `Bearer ${instance.token}`;
+                    refreshedToken = false;
+                }
             }
-            else if (error.code === 'ECONNABORTED') 
+
+            else if (error.code === 'ECONNABORTED' && IS_IDEMPOTENT)
             {
                 await _sleep(SLEEP_TIME * 2 ** (retries + 1));
             }
-            else 
+            else
             {
-                return _apiExceptionHandler(error.response?.data.message ? error.response.data.message : error.message, `${FUNCTION_NAME} failed`);
+                _apiExceptionHandler(ERROR_MESSAGE, `${FUNCTION_NAME} failed`, error.response?.status);
             }
             ++retries;
         }
     } while ((!RESPONSE || RESPONSE.status < 200 || RESPONSE.status >= 300) && retries < MAX_RETRIES);
-    try { return RESPONSE.data; }
-    catch (error) { return; }
+
+    // Retries ran out without a successful response: fail loudly instead of returning undefined.
+    if (!RESPONSE || RESPONSE.status < 200 || RESPONSE.status >= 300)
+    {
+        _apiExceptionHandler(lastError?.response?.data?.message ?? lastError?.message ?? "no response received",
+            `${FUNCTION_NAME} failed`, lastError?.response?.status);
+    }
+
+    return RESPONSE.data;
 }
 
 
@@ -1352,9 +2096,91 @@ function _slugify(text)
 
 
 
+/**
+ * Strips read-only metadata the server adds when *reading back* a
+ * reference-type field, so a value read from `getContent()`/`getAsset()`/
+ * similar and resubmitted unchanged on a later update keeps the same shape
+ * it was originally written with.
+ *
+ * Confirmed live (this project's own Media Contributor app, dev-05): a
+ * Content Reference or Asset Reference field's read-back shape includes a
+ * `type` key (disambiguating what kind of thing is referenced — e.g. an
+ * Asset vs. another Content record) that no caller ever supplies on write.
+ * A read-modify-write update that resubmits a field's read-back value
+ * verbatim (because the caller didn't intend to change it) sends that
+ * `type` key back too — and on `Upload Batch.FolderId`, this triggered an
+ * OpenSearch mapping-type rejection ("failed to parse field
+ * [identifiers.folderId] of type [text]") that destroyed the *entire*
+ * document's searchability, not just that one field, with no error ever
+ * surfaced to the caller (see api-exception-handler.js's own history).
+ *
+ * `id` and `description`/`title` are left untouched — both appear in real,
+ * confirmed-working write shapes (e.g. a Lookup Multi-Select's
+ * `{id, description}`) — only `type` is confirmed read-only/write-unsafe.
+ *
+ * @param {*} value - A property value that may be a reference object
+ *   (`{id, type, ...}`), an array of them, or anything else (passed through
+ *   unchanged)
+ * @returns {*} The same shape with `type` removed from any object that has
+ *   both `id` and `type`
+ */
+function _stripReadOnlyReferenceMetadata(value)
+{
+    if (Array.isArray(value)) return value.map(_stripReadOnlyReferenceMetadata);
+    if (value && typeof value === 'object' && 'id' in value && 'type' in value)
+    {
+        const { type, ...rest } = value;
+        return rest;
+    }
+    return value;
+}
+
+
+
+/**
+ * Convert a list of IDs into the lookup objects the Nomad API expects.
+ *
+ * Fields such as tags, collections and related content are bound by the API as
+ * lookup objects and read each item's `id`; a bare string cannot be bound. Items
+ * that are already objects are passed through unchanged.
+ *
+ * @param {Array<string|Object>|null|undefined} VALUES - IDs, or lookup objects
+ * @returns {Array<Object>|null|undefined} `VALUES` unchanged when it is null or
+ *   undefined (the field is left as it is); otherwise one lookup object per item
+ */
+function _toLookupModels(VALUES)
+{
+    if (VALUES === null || VALUES === undefined) return VALUES;
+
+    return VALUES.map(VALUE => typeof VALUE === "string" ? { id: VALUE } : VALUE);
+}
+
+
 
 
-async function _clearContinueWatching(instance, USER_ID, ASSET_ID) 
+
+/**
+ * Clear a "continue watching" entry for a user.
+ *
+ * Removes a specific asset from the user's continue watching list.
+ *
+ * **Authorization:** Requires a valid Bearer token.
+ *
+ * **Side Effects:**
+ * - Removes the continue watching tracking data for the user/asset
+ *
+ * @param {Object} instance - The SDK instance containing configuration and auth token
+ * @param {string} USER_ID - The unique identifier of the user
+ * @param {string} [ASSET_ID] - The asset ID to remove from continue watching
+ * @returns {Promise<Object>} Response confirming the clearing
+ * @throws {Error} 401 - The caller is not authenticated
+ *
+ * @example
+ * await nomadSDK.clearContinueWatching("user-123", "asset-456");
+ *
+ * @see {@link https://docs.nomad-cms.com/docs/api-guide/media-api/clear-continue-watching Portal API} POST /media/clear-watching
+ */
+async function _clearContinueWatching(instance, USER_ID, ASSET_ID)
 {
     const API_URL = `${instance.config.serviceApiUrl}/api/media/clear-watching`;
 
@@ -1369,7 +2195,27 @@ async function _clearContinueWatching(instance, USER_ID, ASSET_ID)
 
 
 
-async function _clearWatchlist(instance, USER_ID) 
+/**
+ * Clear the user's entire watchlist.
+ *
+ * Removes all items from the specified user's watchlist.
+ *
+ * **Authorization:** Requires a valid Bearer token.
+ *
+ * **Side Effects:**
+ * - Removes all watchlist entries for the user
+ *
+ * @param {Object} instance - The SDK instance containing configuration and auth token
+ * @param {string} USER_ID - The unique identifier of the user whose watchlist to clear
+ * @returns {Promise<Object>} Response confirming the watchlist was cleared
+ * @throws {Error} 401 - The caller is not authenticated
+ *
+ * @example
+ * await nomadSDK.clearWatchlist("user-123");
+ *
+ * @see {@link https://docs.nomad-cms.com/docs/api-guide/media-api/clear-watchlist Portal API} POST /media/clear-watchlist
+ */
+async function _clearWatchlist(instance, USER_ID)
 {
     const API_URL = `${instance.config.serviceApiUrl}/api/media/clear-watchlist?userId=${USER_ID}`;
 
@@ -1379,7 +2225,32 @@ async function _clearWatchlist(instance, USER_ID)
 
 
 
-async function _createForm(instance, CONTENT_DEFINITION_ID, FORM_INFO) 
+/**
+ * Create a form submission for a content definition.
+ *
+ * Submits form data to create a new entry for the specified content
+ * definition. Used for user-generated content submissions through
+ * portal forms.
+ *
+ * **Authorization:** Requires a valid Bearer token.
+ *
+ * **Side Effects:**
+ * - Creates a new content entry from the form submission
+ *
+ * @param {Object} instance - The SDK instance containing configuration and auth token
+ * @param {string} CONTENT_DEFINITION_ID - The content definition ID for the form type
+ * @param {Object} FORM_INFO - The form data to submit
+ * @returns {Promise<Object>} The created content entry
+ * @throws {Error} 401 - The caller is not authenticated
+ *
+ * @example
+ * const entry = await nomadSDK.createForm("def-123", {
+ *     title: "My Submission", description: "Description"
+ * });
+ *
+ * @see {@link https://docs.nomad-cms.com/docs/api-guide/media-api/create-form Portal API} POST /media/form/{contentDefinitionId}
+ */
+async function _createForm(instance, CONTENT_DEFINITION_ID, FORM_INFO)
 {
     const API_URL = `${instance.config.serviceApiUrl}/api/media/form/${CONTENT_DEFINITION_ID}`;
 
@@ -1391,9 +2262,28 @@ async function _createForm(instance, CONTENT_DEFINITION_ID, FORM_INFO)
 
 
 
-async function _getContentCookies(instance, ID) 
+/**
+ * Retrieve secure streaming cookies for portal media content.
+ *
+ * Gets signed cookies required for secure streaming of media content through the
+ * portal API. The cookies authorize CDN access to the media files.
+ *
+ * **Authorization:** Requires a valid Bearer token.
+ *
+ * @param {Object} instance - The SDK instance containing configuration and auth token
+ * @param {string} CONTENT_ID - The unique identifier of the media content
+ * @returns {Promise<Object>} Streaming cookies and manifest URL for the content
+ * @throws {Error} 401 - The caller is not authenticated
+ * @throws {Error} 404 - The content was not found
+ *
+ * @example
+ * const cookies = await nomadSDK.getContentCookies("media-123");
+ *
+ * @see {@link https://docs.nomad-cms.com/docs/api-guide/asset-api-1 Portal API} GET /media/set-cookies/{id}
+ */
+async function _getContentCookies(instance, CONTENT_ID)
 {
-    const API_URL = `${instance.config.serviceApiUrl}/api/media/set-cookies/${ID}`;
+    const API_URL = `${instance.config.serviceApiUrl}/api/media/set-cookies/${CONTENT_ID}`;
 
     return await _sendRequest(instance, "Get Content Cookies", API_URL, "GET", undefined, undefined);
 }
@@ -1401,7 +2291,24 @@ async function _getContentCookies(instance, ID)
 
 
 
-async function _getDefaultSiteConfig(instance) 
+/**
+ * Retrieve the default site configuration.
+ *
+ * Gets the default portal site configuration used when no specific
+ * configuration ID is provided.
+ *
+ * **Authorization:** Requires a valid Bearer token.
+ *
+ * @param {Object} instance - The SDK instance containing configuration and auth token
+ * @returns {Promise<Object>} The default site configuration object
+ * @throws {Error} 401 - The caller is not authenticated
+ *
+ * @example
+ * const config = await nomadSDK.getDefaultSiteConfig();
+ *
+ * @see {@link https://docs.nomad-cms.com/docs/api-guide/media-api/get-default-site-config Portal API} GET /media/config
+ */
+async function _getDefaultSiteConfig(instance)
 {
     const API_URL = `${instance.config.serviceApiUrl}/api/media/config`;
 
@@ -1411,9 +2318,28 @@ async function _getDefaultSiteConfig(instance)
 
 
 
-async function _getDynamicContent(instance, ID) 
+/**
+ * Retrieve a dynamic content item by its unique identifier.
+ *
+ * Gets a dynamically generated content item used for personalized or
+ * rule-based content display on the portal.
+ *
+ * **Authorization:** Requires a valid Bearer token.
+ *
+ * @param {Object} instance - The SDK instance containing configuration and auth token
+ * @param {string} DYNAMIC_CONTENT_RECORD_ID - The unique identifier of the dynamic content
+ * @returns {Promise<Object>} The dynamic content object with its configuration and items
+ * @throws {Error} 401 - The caller is not authenticated
+ * @throws {Error} 404 - The dynamic content was not found
+ *
+ * @example
+ * const content = await nomadSDK.getDynamicContent("dynamic-123");
+ *
+ * @see {@link https://docs.nomad-cms.com/docs/api-guide/media-api/get-dynamic-content Portal API} GET /media/content/{id}
+ */
+async function _getDynamicContent(instance, DYNAMIC_CONTENT_RECORD_ID)
 {
-    const API_URL = `${instance.config.serviceApiUrl}/api/media/content/${ID}`;
+    const API_URL = `${instance.config.serviceApiUrl}/api/media/content/${DYNAMIC_CONTENT_RECORD_ID}`;
 
     return await _sendRequest(instance, "Get Dynamic Content", API_URL, "GET", undefined, undefined);
 }
@@ -1421,7 +2347,25 @@ async function _getDynamicContent(instance, ID)
 
 
 
-async function _getDynamicContents(instance) 
+/**
+ * Retrieve all dynamic content items.
+ *
+ * Gets the list of all dynamic content configurations available for
+ * the portal front-end.
+ *
+ * **Authorization:** Requires a valid Bearer token.
+ *
+ * @param {Object} instance - The SDK instance containing configuration and auth token
+ * @returns {Promise<Object>} Array of dynamic content objects
+ * @throws {Error} 401 - The caller is not authenticated
+ *
+ * @example
+ * const contents = await nomadSDK.getDynamicContents();
+ * contents.forEach(c => console.log(c.id, c.name));
+ *
+ * @see {@link https://docs.nomad-cms.com/docs/api-guide/media-api/get-dynamic-contents Portal API} GET /media/content
+ */
+async function _getDynamicContents(instance)
 {
     const API_URL = `${instance.config.serviceApiUrl}/api/media/content`;
 
@@ -1431,12 +2375,38 @@ async function _getDynamicContents(instance)
 
 
 
-async function _getMediaGroup(instance, ID, FILTER_IDS) 
+/**
+ * Retrieve a media group by its unique identifier.
+ *
+ * Gets a media group and its contents with optional content filtering.
+ * Media groups organize content items for portal display.
+ *
+ * **Authorization:** Requires a valid Bearer token.
+ *
+ * @param {Object} instance - The SDK instance containing configuration and auth token
+ * @param {string} MEDIA_GROUP_ID - The unique identifier of the media group
+ * @param {Array<string>} [FILTER_IDS] - Optional array of content IDs to filter results
+ * @param {string} [LANGUAGE_ID] - Optional language ID to localize the response
+ * @returns {Promise<Object>} The media group object with its contents
+ * @throws {Error} 401 - The caller is not authenticated
+ * @throws {Error} 404 - The media group was not found
+ *
+ * @example
+ * const group = await nomadSDK.getMediaGroup("group-123", ["item-1", "item-2"]);
+ *
+ * @see {@link https://docs.nomad-cms.com/docs/api-guide/media-api/get-media-group Portal API} GET /media/group/{id}
+ */
+async function _getMediaGroup(instance, MEDIA_GROUP_ID, FILTER_IDS, LANGUAGE_ID)
 {
-    let apiUrl = `${instance.config.serviceApiUrl}/api/media/group/${ID}`;
+    let apiUrl = `${instance.config.serviceApiUrl}/api/media/group/${MEDIA_GROUP_ID}`;
+
+    // filterIds is sent as repeated query keys (filterIds=a&filterIds=b)
+    const QUERY = [];
     if (FILTER_IDS && FILTER_IDS.length > 0) {
-        apiUrl += '?' + FILTER_IDS.map(id => `filterIds=${id}`).join('&');
+        QUERY.push(...FILTER_IDS.map(id => `filterIds=${encodeURIComponent(id)}`));
     }
+    if (LANGUAGE_ID) QUERY.push(`languageId=${encodeURIComponent(LANGUAGE_ID)}`);
+    if (QUERY.length > 0) apiUrl += '?' + QUERY.join('&');
 
     return await _sendRequest(instance, "Get Media Group", apiUrl, "GET", undefined, undefined);
 }
@@ -1444,9 +2414,29 @@ async function _getMediaGroup(instance, ID, FILTER_IDS)
 
 
 
-async function _getMediaItem(instance, ID) 
+/**
+ * Retrieve a media item by its unique identifier.
+ *
+ * Gets the full media item details including metadata, content definitions,
+ * and playback information for the portal front-end.
+ *
+ * **Authorization:** Requires a valid Bearer token.
+ *
+ * @param {Object} instance - The SDK instance containing configuration and auth token
+ * @param {string} MEDIA_ITEM_ID - The unique identifier of the media item
+ * @returns {Promise<Object>} The media item object with metadata and content details
+ * @throws {Error} 401 - The caller is not authenticated
+ * @throws {Error} 404 - The media item was not found
+ *
+ * @example
+ * const item = await nomadSDK.getMediaItem("item-123");
+ * console.log(item.title);
+ *
+ * @see {@link https://docs.nomad-cms.com/docs/api-guide/media-api/get-media-item Portal API} GET /media/item/{id}
+ */
+async function _getMediaItem(instance, MEDIA_ITEM_ID)
 {
-    const API_URL = `${instance.config.serviceApiUrl}/api/media/item/${ID}`;
+    const API_URL = `${instance.config.serviceApiUrl}/api/media/item/${MEDIA_ITEM_ID}`;
 
     return await _sendRequest(instance, "Get Media Item", API_URL, "GET", undefined, undefined);
 }
@@ -1454,7 +2444,24 @@ async function _getMediaItem(instance, ID)
 
 
 
-async function _getMyContent(instance) 
+/**
+ * Retrieve the authenticated user's personal content.
+ *
+ * Gets all content items owned by or assigned to the currently
+ * authenticated user.
+ *
+ * **Authorization:** Requires a valid Bearer token.
+ *
+ * @param {Object} instance - The SDK instance containing configuration and auth token
+ * @returns {Promise<Object>} Array of content items belonging to the user
+ * @throws {Error} 401 - The caller is not authenticated
+ *
+ * @example
+ * const myContent = await nomadSDK.getMyContent();
+ *
+ * @see {@link https://docs.nomad-cms.com/docs/api-guide/media-api/get-my-content Portal API} GET /media/my-content
+ */
+async function _getMyContent(instance)
 {
     const API_URL = `${instance.config.serviceApiUrl}/api/media/my-content`;
 
@@ -1464,9 +2471,34 @@ async function _getMyContent(instance)
 
 
 
-async function _getMyGroup(instance, ID) 
+/**
+ * Retrieve a personal content group by its unique identifier.
+ *
+ * Gets a content group from the user's personal groups, including its
+ * contents and configuration.
+ *
+ * **Authorization:** Requires a valid Bearer token.
+ *
+ * @param {Object} instance - The SDK instance containing configuration and auth token
+ * @param {string} GROUP_ID - The unique identifier of the personal group
+ * @param {Array<string>} [FILTER_IDS] - Optional array of content IDs to filter results
+ * @returns {Promise<Object>} The personal group object with its contents
+ * @throws {Error} 401 - The caller is not authenticated
+ * @throws {Error} 404 - The group was not found
+ *
+ * @example
+ * const group = await nomadSDK.getMyGroup("group-123");
+ *
+ * @see {@link https://docs.nomad-cms.com/docs/api-guide/media-api/get-my-group Portal API} GET /media/my-group/{id}
+ */
+async function _getMyGroup(instance, GROUP_ID, FILTER_IDS)
 {
-    const API_URL = `${instance.config.serviceApiUrl}/api/media/my-group/${ID}`;
+    let API_URL = `${instance.config.serviceApiUrl}/api/media/my-group/${GROUP_ID}`;
+
+    // filterIds is sent as repeated query keys (filterIds=a&filterIds=b)
+    if (FILTER_IDS && FILTER_IDS.length > 0) {
+        API_URL += '?' + FILTER_IDS.map(id => `filterIds=${encodeURIComponent(id)}`).join('&');
+    }
 
     return await _sendRequest(instance, "Get My Group", API_URL, "GET", undefined, undefined);
 }
@@ -1474,9 +2506,28 @@ async function _getMyGroup(instance, ID)
 
 
 
-async function _getSiteConfig(instance, ID) 
+/**
+ * Retrieve a site configuration by its unique identifier.
+ *
+ * Gets the portal site configuration including theme, layout, navigation,
+ * and content display settings.
+ *
+ * **Authorization:** Requires a valid Bearer token.
+ *
+ * @param {Object} instance - The SDK instance containing configuration and auth token
+ * @param {string} SITE_CONFIG_RECORD_ID - The unique identifier of the site configuration
+ * @returns {Promise<Object>} The site configuration object
+ * @throws {Error} 401 - The caller is not authenticated
+ * @throws {Error} 404 - The site configuration was not found
+ *
+ * @example
+ * const config = await nomadSDK.getSiteConfig("config-123");
+ *
+ * @see {@link https://docs.nomad-cms.com/docs/api-guide/media-api/get-site-config Portal API} GET /media/config/{id}
+ */
+async function _getSiteConfig(instance, SITE_CONFIG_RECORD_ID)
 {
-    const API_URL = `${instance.config.serviceApiUrl}/api/media/config/${ID}`;
+    const API_URL = `${instance.config.serviceApiUrl}/api/media/config/${SITE_CONFIG_RECORD_ID}`;
 
     return await _sendRequest(instance, "Get Site Config", API_URL, "GET", undefined, undefined);
 }
@@ -1484,19 +2535,43 @@ async function _getSiteConfig(instance, ID)
 
 
 
-async function _mediaSearch(instance, SEARCH_QUERY, IDS, SORT_FIELDS, 
-    PAGE_OFFSET, PAGE_SIZE) 
+/**
+ * Search for media content using a query string and optional filters.
+ *
+ * Performs a search against the media index with support for pagination,
+ * sorting, and ID filtering. Defaults to page offset 0 and page size 100.
+ *
+ * **Authorization:** Requires a valid Bearer token.
+ *
+ * @param {Object} instance - The SDK instance containing configuration and auth token
+ * @param {Object} QUERY - The search query object containing search criteria
+ * @param {Array<string>} [IDS] - Optional array of specific content IDs to filter by
+ * @param {Array<Object>} [SORT_FIELDS] - Optional array of sort field objects
+ * @param {number} [OFFSET=0] - The page offset for pagination (defaults to 0)
+ * @param {number} [SIZE=100] - The number of results per page (defaults to 100)
+ * @returns {Promise<Object>} Search results containing items array and pagination info
+ * @throws {Error} 401 - The caller is not authenticated
+ *
+ * @example
+ * const results = await nomadSDK.mediaSearch(
+ *     { query: "news" }, null, [{ fieldName: "date", order: "desc" }], 0, 25
+ * );
+ *
+ * @see {@link https://docs.nomad-cms.com/docs/api-guide/media-api/media-search Portal API} POST /media/search
+ */
+async function _mediaSearch(instance, QUERY, IDS, SORT_FIELDS,
+    OFFSET, SIZE)
 {
     const API_URL = `${instance.config.serviceApiUrl}/api/media/search`;
 
     const BODY = {  
-        searchQuery: SEARCH_QUERY,
+        searchQuery: QUERY,
         ids: IDS,
         sortFields: SORT_FIELDS
     };
 
-    PAGE_OFFSET ? BODY["pageOffset"] = PAGE_OFFSET : BODY["pageOffset"] = 0;
-    PAGE_SIZE ? BODY["pageSize"] = PAGE_SIZE : BODY["pageSize"] = 100;
+    OFFSET ? BODY["pageOffset"] = OFFSET : BODY["pageOffset"] = 0;
+    SIZE ? BODY["pageSize"] = SIZE : BODY["pageSize"] = 100;
 
     return await _sendRequest(instance, "Media Search", API_URL, "POST", undefined, BODY);
 }