@dotcms/client 26.7.21-1 → 26.7.27-1-next.2448

package/index.cjs.js

@@ -4,6 +4,90 @@ var consola = require('consola');
 var types = require('@dotcms/types');
 var internal = require('./internal.cjs.js');
 
+const SDK_VERSION = "26.7.27-1-next.2448";
+
+const DOTCMS_VERSION_HEADER = 'x-dotcms-version';
+const DOTCMS_MIN_SDK_HEADER = 'x-dotcms-min-sdk';
+let hasWarnedOutdatedSdk = false;
+let hasWarnedNewerSdk = false;
+/**
+ * Parses a date-lockstep version string (e.g. "26.7.14-1") into a flat array of numeric
+ * segments for ordered comparison. Returns null if any segment isn't a plain integer
+ * (e.g. an LTS-shaped version like "26.7.14_lts_v1"), so callers can skip the comparison
+ * instead of comparing unrelated formats.
+ */
+const parseVersionSegments = (version) => {
+    const segments = version
+        .trim()
+        .replace(/^v/i, '')
+        .split(/[.-]/)
+        .map((segment) => Number(segment));
+    return segments.some((segment) => !Number.isFinite(segment)) ? null : segments;
+};
+/**
+ * Compares two date-lockstep version strings segment by segment as numbers (not as
+ * strings), so e.g. "26.10.1" correctly compares greater than "26.7.13". Returns null
+ * (instead of throwing) if either version can't be parsed, so callers can fail open.
+ */
+const compareVersions = (a, b) => {
+    const segmentsA = parseVersionSegments(a);
+    const segmentsB = parseVersionSegments(b);
+    if (!segmentsA || !segmentsB) {
+        return null;
+    }
+    const length = Math.max(segmentsA.length, segmentsB.length);
+    for (let i = 0; i < length; i++) {
+        const partA = segmentsA[i] ?? 0;
+        const partB = segmentsB[i] ?? 0;
+        if (partA !== partB) {
+            return partA > partB ? 1 : -1;
+        }
+    }
+    return 0;
+};
+/**
+ * Reads the dotCMS server's advertised version and minimum supported SDK version off a
+ * response (see `SdkVersionWebInterceptor` on the server) and logs a console error/warning
+ * if this SDK is outside the compatible range:
+ *
+ * - `ownVersion < X-DotCMS-Min-SDK` → console.error, the SDK must be upgraded.
+ * - `ownVersion > X-DotCMS-Version` → console.warn, the SDK is ahead of this server and
+ *   may call APIs it doesn't have yet (e.g. a dev environment newer than the one it's
+ *   pointed at).
+ *
+ * Fails open by design: if the headers are absent (an older server that doesn't send
+ * them yet) or unparsable, this silently does nothing — it never throws and never
+ * changes request/response behavior. Each kind of warning logs at most once per session
+ * so it doesn't spam the console on every request.
+ */
+const checkSdkCompatibility = (headers, ownVersion) => {
+    try {
+        if (!ownVersion) {
+            return;
+        }
+        const serverVersion = headers.get(DOTCMS_VERSION_HEADER);
+        const minSdkVersion = headers.get(DOTCMS_MIN_SDK_HEADER);
+        if (!serverVersion || !minSdkVersion) {
+            return;
+        }
+        if (!hasWarnedOutdatedSdk && (compareVersions(ownVersion, minSdkVersion) ?? 0) < 0) {
+            hasWarnedOutdatedSdk = true;
+            console.error(`[dotCMS SDK] SDK ${ownVersion} is not supported by dotCMS ${serverVersion} ` +
+                `(minimum required: ${minSdkVersion}). Upgrade required: ` +
+                'https://www.dotcms.com/docs/latest/sdk-version-compatibility');
+        }
+        if (!hasWarnedNewerSdk && (compareVersions(ownVersion, serverVersion) ?? 0) > 0) {
+            hasWarnedNewerSdk = true;
+            console.warn(`[dotCMS SDK] SDK ${ownVersion} is newer than dotCMS ${serverVersion} ` +
+                'and may call APIs the server does not have yet.');
+        }
+    }
+    catch {
+        // Never let a compatibility-check failure break the actual request.
+    }
+};
+
+// Build-time constant — see sdkVersionPlugin in rollup.config.cjs.
 /**
  * HTTP client implementation using the Fetch API.
  *
@@ -71,6 +155,11 @@ class FetchHttpClient extends types.BaseHttpClient {
         try {
             // Use native fetch API - no additional configuration needed
             const response = await fetch(url, options);
+            // Fire-and-forget: reads X-DotCMS-Version / X-DotCMS-Min-SDK off the
+            // response and logs a console warning on mismatch. Fails open (no headers,
+            // e.g. an older server) and never throws, so this can't affect the actual
+            // request/response handling below.
+            checkSdkCompatibility(response.headers, SDK_VERSION);
             if (!response.ok) {
                 // Parse response body for error context
                 let errorBody;
@@ -143,7 +232,8 @@ function __classPrivateFieldSet(receiver, state, value, kind, f) {
 }
 
 /**
- * Utility functions for AI search parameter mapping and processing
+ * Utility functions for AI search parameter mapping and processing.
+ * This module provides functionality for mapping and appending parameters to a URLSearchParams object.
  */
 /**
  * Appends mapped parameters to URLSearchParams based on a mapping configuration.
@@ -2339,6 +2429,16 @@ async function fetchGraphQL({ baseURL, body, headers, httpClient }) {
     });
 }
 
+/**
+ * Logs a verbose DotCMS GraphQL error with rich contextual information.
+ *
+ * @param {string} url - The page or API URL associated with the error.
+ * @param {string} message - The main error message to log.
+ * @param {Object} details - Additional error details for debugging.
+ * @param {number} [details.status] - Optional status code associated with the error.
+ * @param {string} [details.code] - Optional error code describing the error type.
+ * @param {Record<string, unknown>} details.variables - The GraphQL variables used in the query.
+ */
 function logVerboseError(url, message, details) {
     const statusLine = details.status !== undefined ? `\n  status: ${details.status} | code: ${details.code}` : '';
     const variables = JSON.stringify(details.variables, null, 2).replace(/\n/g, '\n  ');

package/index.esm.js

@@ -2,6 +2,90 @@ import { consola } from 'consola';
 import { BaseHttpClient, DISTANCE_FUNCTIONS, DotHttpError, DotErrorAISearch, DotErrorContent, DotErrorNavigation, UVE_MODE, DotErrorPage } from '@dotcms/types';
 import { graphqlToPageEntity } from './internal.esm.js';
 
+const SDK_VERSION = "26.7.27-1-next.2448";
+
+const DOTCMS_VERSION_HEADER = 'x-dotcms-version';
+const DOTCMS_MIN_SDK_HEADER = 'x-dotcms-min-sdk';
+let hasWarnedOutdatedSdk = false;
+let hasWarnedNewerSdk = false;
+/**
+ * Parses a date-lockstep version string (e.g. "26.7.14-1") into a flat array of numeric
+ * segments for ordered comparison. Returns null if any segment isn't a plain integer
+ * (e.g. an LTS-shaped version like "26.7.14_lts_v1"), so callers can skip the comparison
+ * instead of comparing unrelated formats.
+ */
+const parseVersionSegments = (version) => {
+    const segments = version
+        .trim()
+        .replace(/^v/i, '')
+        .split(/[.-]/)
+        .map((segment) => Number(segment));
+    return segments.some((segment) => !Number.isFinite(segment)) ? null : segments;
+};
+/**
+ * Compares two date-lockstep version strings segment by segment as numbers (not as
+ * strings), so e.g. "26.10.1" correctly compares greater than "26.7.13". Returns null
+ * (instead of throwing) if either version can't be parsed, so callers can fail open.
+ */
+const compareVersions = (a, b) => {
+    const segmentsA = parseVersionSegments(a);
+    const segmentsB = parseVersionSegments(b);
+    if (!segmentsA || !segmentsB) {
+        return null;
+    }
+    const length = Math.max(segmentsA.length, segmentsB.length);
+    for (let i = 0; i < length; i++) {
+        const partA = segmentsA[i] ?? 0;
+        const partB = segmentsB[i] ?? 0;
+        if (partA !== partB) {
+            return partA > partB ? 1 : -1;
+        }
+    }
+    return 0;
+};
+/**
+ * Reads the dotCMS server's advertised version and minimum supported SDK version off a
+ * response (see `SdkVersionWebInterceptor` on the server) and logs a console error/warning
+ * if this SDK is outside the compatible range:
+ *
+ * - `ownVersion < X-DotCMS-Min-SDK` → console.error, the SDK must be upgraded.
+ * - `ownVersion > X-DotCMS-Version` → console.warn, the SDK is ahead of this server and
+ *   may call APIs it doesn't have yet (e.g. a dev environment newer than the one it's
+ *   pointed at).
+ *
+ * Fails open by design: if the headers are absent (an older server that doesn't send
+ * them yet) or unparsable, this silently does nothing — it never throws and never
+ * changes request/response behavior. Each kind of warning logs at most once per session
+ * so it doesn't spam the console on every request.
+ */
+const checkSdkCompatibility = (headers, ownVersion) => {
+    try {
+        if (!ownVersion) {
+            return;
+        }
+        const serverVersion = headers.get(DOTCMS_VERSION_HEADER);
+        const minSdkVersion = headers.get(DOTCMS_MIN_SDK_HEADER);
+        if (!serverVersion || !minSdkVersion) {
+            return;
+        }
+        if (!hasWarnedOutdatedSdk && (compareVersions(ownVersion, minSdkVersion) ?? 0) < 0) {
+            hasWarnedOutdatedSdk = true;
+            console.error(`[dotCMS SDK] SDK ${ownVersion} is not supported by dotCMS ${serverVersion} ` +
+                `(minimum required: ${minSdkVersion}). Upgrade required: ` +
+                'https://www.dotcms.com/docs/latest/sdk-version-compatibility');
+        }
+        if (!hasWarnedNewerSdk && (compareVersions(ownVersion, serverVersion) ?? 0) > 0) {
+            hasWarnedNewerSdk = true;
+            console.warn(`[dotCMS SDK] SDK ${ownVersion} is newer than dotCMS ${serverVersion} ` +
+                'and may call APIs the server does not have yet.');
+        }
+    }
+    catch {
+        // Never let a compatibility-check failure break the actual request.
+    }
+};
+
+// Build-time constant — see sdkVersionPlugin in rollup.config.cjs.
 /**
  * HTTP client implementation using the Fetch API.
  *
@@ -69,6 +153,11 @@ class FetchHttpClient extends BaseHttpClient {
         try {
             // Use native fetch API - no additional configuration needed
             const response = await fetch(url, options);
+            // Fire-and-forget: reads X-DotCMS-Version / X-DotCMS-Min-SDK off the
+            // response and logs a console warning on mismatch. Fails open (no headers,
+            // e.g. an older server) and never throws, so this can't affect the actual
+            // request/response handling below.
+            checkSdkCompatibility(response.headers, SDK_VERSION);
             if (!response.ok) {
                 // Parse response body for error context
                 let errorBody;
@@ -141,7 +230,8 @@ function __classPrivateFieldSet(receiver, state, value, kind, f) {
 }
 
 /**
- * Utility functions for AI search parameter mapping and processing
+ * Utility functions for AI search parameter mapping and processing.
+ * This module provides functionality for mapping and appending parameters to a URLSearchParams object.
  */
 /**
  * Appends mapped parameters to URLSearchParams based on a mapping configuration.
@@ -2337,6 +2427,16 @@ async function fetchGraphQL({ baseURL, body, headers, httpClient }) {
     });
 }
 
+/**
+ * Logs a verbose DotCMS GraphQL error with rich contextual information.
+ *
+ * @param {string} url - The page or API URL associated with the error.
+ * @param {string} message - The main error message to log.
+ * @param {Object} details - Additional error details for debugging.
+ * @param {number} [details.status] - Optional status code associated with the error.
+ * @param {string} [details.code] - Optional error code describing the error type.
+ * @param {Record<string, unknown>} details.variables - The GraphQL variables used in the query.
+ */
 function logVerboseError(url, message, details) {
     const statusLine = details.status !== undefined ? `\n  status: ${details.status} | code: ${details.code}` : '';
     const variables = JSON.stringify(details.variables, null, 2).replace(/\n/g, '\n  ');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dotcms/client",
-  "version": "26.07.21-01",
+  "version": "26.7.27-1-next.2448",
   "description": "Official JavaScript library for interacting with DotCMS REST APIs.",
   "repository": {
     "type": "git",

package/src/lib/utils/__mocks__/virtual-sdk-version.d.ts

@@ -0,0 +1 @@
+export declare const SDK_VERSION = "0.0.0-test";

package/src/lib/utils/params/utils.d.ts

@@ -1,5 +1,6 @@
 /**
- * Utility functions for AI search parameter mapping and processing
+ * Utility functions for AI search parameter mapping and processing.
+ * This module provides functionality for mapping and appending parameters to a URLSearchParams object.
  */
 /**
  * Appends mapped parameters to URLSearchParams based on a mapping configuration.

package/src/lib/utils/sdk-compatibility.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Compares two date-lockstep version strings segment by segment as numbers (not as
+ * strings), so e.g. "26.10.1" correctly compares greater than "26.7.13". Returns null
+ * (instead of throwing) if either version can't be parsed, so callers can fail open.
+ */
+export declare const compareVersions: (a: string, b: string) => number | null;
+/**
+ * Resets the once-per-session warning flags. Test-only — production code never needs
+ * to warn more than once per page load.
+ */
+export declare const resetSdkCompatibilityWarnings: () => void;
+/**
+ * Reads the dotCMS server's advertised version and minimum supported SDK version off a
+ * response (see `SdkVersionWebInterceptor` on the server) and logs a console error/warning
+ * if this SDK is outside the compatible range:
+ *
+ * - `ownVersion < X-DotCMS-Min-SDK` → console.error, the SDK must be upgraded.
+ * - `ownVersion > X-DotCMS-Version` → console.warn, the SDK is ahead of this server and
+ *   may call APIs it doesn't have yet (e.g. a dev environment newer than the one it's
+ *   pointed at).
+ *
+ * Fails open by design: if the headers are absent (an older server that doesn't send
+ * them yet) or unparsable, this silently does nothing — it never throws and never
+ * changes request/response behavior. Each kind of warning logs at most once per session
+ * so it doesn't spam the console on every request.
+ */
+export declare const checkSdkCompatibility: (headers: Headers, ownVersion: string) => void;