@dotcms/client 1.7.1-next.2379 → 26.7.27-1

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.07.27-01";
+
+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;

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.07.27-01";
+
+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;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dotcms/client",
-  "version": "1.7.1-next.2379",
+  "version": "26.07.27-01",
   "description": "Official JavaScript library for interacting with DotCMS REST APIs.",
   "repository": {
     "type": "git",
@@ -53,4 +53,4 @@
   "module": "./index.esm.js",
   "main": "./index.cjs.js",
   "types": "./index.d.ts"
-}
+}

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/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;