@dotcms/client 1.2.5-next.2 → 1.2.5-next.4

package/README.md

@@ -32,6 +32,7 @@ The `@dotcms/client` is a powerful JavaScript/TypeScript SDK designed to simplif
 -   [How-to Guides](#how-to-guides)
     -   [How to Fetch Complete Pages](#how-to-fetch-complete-pages)
     -   [How to Query Content Collections](#how-to-query-content-collections)
+        -   [Including System Host Content](#including-system-host-content)
     -   [How to Run Raw Lucene Content Queries](#how-to-run-raw-lucene-content-queries)
     -   [How to Use AI-Powered Search](#how-to-use-ai-powered-search)
     -   [How to Work with GraphQL](#how-to-work-with-graphql)
@@ -220,6 +221,33 @@ const products = await client.content
     .limit(10);
 ```
 
+#### Including System Host Content
+
+By default, `getCollection()` scopes queries to the configured `siteId`. Call `.includeSystemHost()` to also return content that belongs to the dotCMS **System Host** — shared content available across all sites.
+
+```typescript
+// Return content from both the configured site AND the System Host
+const blogs = await client.content
+    .getCollection('Blog')
+    .includeSystemHost()
+    .limit(10);
+```
+
+Under the hood, all positive `+conhost:` constraints in the assembled query are collected and grouped into a single `+(conhost:<siteId> conhost:SYSTEM_HOST)` OR group, so dotCMS returns content from any of the matched hosts.
+
+```typescript
+// Multiple sites + System Host (multisite scenario)
+const blogs = await client.content
+    .getCollection('Blog')
+    .query('+conhost:site-a')
+    .includeSystemHost()
+    .limit(10);
+// Resulting conhost constraint: +(conhost:site-a conhost:<configured-siteId> conhost:SYSTEM_HOST)
+```
+
+> [!NOTE]
+> Negative conhost exclusions (`-conhost:excluded-site`) in raw queries are preserved as-is and are not affected by `includeSystemHost()`.
+
 ### How to Run Raw Lucene Content Queries
 
 Use `client.content.query()` when you want to execute a **raw Lucene query string** (without the query-builder DSL), and you want full control over constraints like `contentType`, `live`, `languageId`, `conhost`, etc.

package/index.cjs.js

@@ -510,6 +510,11 @@ class AIClient extends BaseApiClient {
 /**
  * Default variant identifier used in the application.
  */
+/**
+ * Identifier for the dotCMS System Host.
+ * Used when building queries that should include content from the System Host.
+ */
+const SYSTEM_HOST = 'SYSTEM_HOST';
 /**
  * Fields that should not be formatted when sanitizing the query.
  * These fields are essential for maintaining the integrity of the content type.
@@ -879,6 +884,68 @@ function shouldAddSiteIdConstraint(query, siteId) {
     }
     return true;
 }
+/**
+ * @description
+ * Collects all positive `+conhost:` values from a fully assembled Lucene query,
+ * removes them from their original positions, adds SYSTEM_HOST to the set,
+ * and rebuilds a single grouped constraint at the end of the query.
+ *
+ * This function is designed to be called on the final assembled query string
+ * (after raw query has been appended) so that conhosts from all sources —
+ * auto-injected siteId, builder-path conhost, and raw-path conhost — are
+ * all visible and handled uniformly.
+ *
+ * @example
+ * ```ts
+ * // Single siteId + SYSTEM_HOST
+ * buildConhostWithSystemHost('+contentType:Blog +languageId:1 +live:true +conhost:site-123')
+ * // → '+contentType:Blog +languageId:1 +live:true +(conhost:site-123 conhost:SYSTEM_HOST)'
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Multiple conhosts (multisite) + SYSTEM_HOST
+ * buildConhostWithSystemHost('+contentType:Blog +live:true +conhost:site-a +conhost:site-b')
+ * // → '+contentType:Blog +live:true +(conhost:site-a conhost:site-b conhost:SYSTEM_HOST)'
+ * ```
+ *
+ * @example
+ * ```ts
+ * // No conhost in query (no siteId configured)
+ * buildConhostWithSystemHost('+contentType:Blog +languageId:1 +live:true')
+ * // → '+contentType:Blog +languageId:1 +live:true +conhost:SYSTEM_HOST'
+ * ```
+ *
+ * @export
+ * @param {string} query - The fully assembled Lucene query string to process.
+ * @returns {string} The query with all positive conhost constraints replaced by a single grouped constraint.
+ */
+function buildConhostWithSystemHost(query) {
+    // Collect all unique positive conhost values, excluding SYSTEM_HOST (we'll add it explicitly)
+    const conhostRegex = /\+conhost:([^\s)]+)/gi;
+    const values = [];
+    let match;
+    while ((match = conhostRegex.exec(query)) !== null) {
+        const value = match[1];
+        if (value.toUpperCase() !== SYSTEM_HOST && !values.includes(value)) {
+            values.push(value);
+        }
+    }
+    // Always include SYSTEM_HOST at the end
+    values.push(SYSTEM_HOST);
+    // Remove all existing +conhost: constraints from the query
+    const queryWithoutConhost = query
+        .replace(/\s*\+conhost:[^\s)]+/gi, '')
+        .replace(/\s+/g, ' ')
+        .trim();
+    // Build the final constraint:
+    // - Single value (only SYSTEM_HOST, no other conhost was present): simple form
+    // - Multiple values: grouped form so dotCMS treats them as OR
+    const conhostConstraint = values.length === 1
+        ? `+conhost:${values[0]}`
+        : `+(${values.map((v) => `conhost:${v}`).join(' ')})`;
+    return `${queryWithoutConhost} ${conhostConstraint}`.trim();
+}
 
 var _Field_query;
 /**
@@ -1381,7 +1448,7 @@ class QueryBuilder {
 }
 _QueryBuilder_query = new WeakMap();
 
-var _CollectionBuilder_contentType, _CollectionBuilder_defaultQuery, _CollectionBuilder_query, _CollectionBuilder_rawQuery, _CollectionBuilder_languageId, _CollectionBuilder_draft;
+var _CollectionBuilder_contentType, _CollectionBuilder_defaultQuery, _CollectionBuilder_query, _CollectionBuilder_rawQuery, _CollectionBuilder_languageId, _CollectionBuilder_draft, _CollectionBuilder_includeSystemHost;
 /**
  * Creates a Builder to filter and fetch content from the content API for a specific content type.
  *
@@ -1407,6 +1474,7 @@ class CollectionBuilder extends BaseBuilder {
         _CollectionBuilder_rawQuery.set(this, void 0);
         _CollectionBuilder_languageId.set(this, 1);
         _CollectionBuilder_draft.set(this, false);
+        _CollectionBuilder_includeSystemHost.set(this, false);
         __classPrivateFieldSet(this, _CollectionBuilder_contentType, params.contentType, "f");
         // Build the default query with the contentType field
         __classPrivateFieldSet(this, _CollectionBuilder_defaultQuery, new QueryBuilder().field('contentType').equals(__classPrivateFieldGet(this, _CollectionBuilder_contentType, "f")), "f");
@@ -1476,6 +1544,32 @@ class CollectionBuilder extends BaseBuilder {
         __classPrivateFieldSet(this, _CollectionBuilder_draft, true, "f");
         return this;
     }
+    /**
+     * Includes content from the dotCMS System Host in the query results.
+     *
+     * When enabled, content from the System Host is returned alongside content from
+     * the configured site. All positive `+conhost:` constraints present in the
+     * assembled query are collected and grouped into a single `+(conhost:X conhost:SYSTEM_HOST)`
+     * constraint, so dotCMS returns content from any of those hosts.
+     *
+     * Calling this method multiple times is idempotent — the constraint is only added once.
+     *
+     * @example
+     * ```ts
+     * client.content
+     *   .getCollection<Blog>('Blog')
+     *   .includeSystemHost()
+     *   .limit(10)
+     *   .then(({ contentlets }) => console.log(contentlets));
+     * ```
+     *
+     * @return {CollectionBuilder} A CollectionBuilder instance.
+     * @memberof CollectionBuilder
+     */
+    includeSystemHost() {
+        __classPrivateFieldSet(this, _CollectionBuilder_includeSystemHost, true, "f");
+        return this;
+    }
     /**
      * Filters the content by a variant ID for [Experiments](https://www.dotcms.com/docs/latest/experiments-and-a-b-testing)
      *
@@ -1587,10 +1681,17 @@ class CollectionBuilder extends BaseBuilder {
         const sanitizedQuery = sanitizeQueryForContentType(finalQuery, __classPrivateFieldGet(this, _CollectionBuilder_contentType, "f"));
         // Append raw query if provided (raw query is NOT sanitized for content type)
         const query = __classPrivateFieldGet(this, _CollectionBuilder_rawQuery, "f") ? `${sanitizedQuery} ${__classPrivateFieldGet(this, _CollectionBuilder_rawQuery, "f")}` : sanitizedQuery;
-        return sanitizeQuery(query);
+        const assembled = sanitizeQuery(query);
+        // If includeSystemHost is active, collect all +conhost: values from the fully
+        // assembled query (including those from the raw path), group them, and append
+        // SYSTEM_HOST so dotCMS returns content from any of the matched hosts.
+        if (__classPrivateFieldGet(this, _CollectionBuilder_includeSystemHost, "f")) {
+            return buildConhostWithSystemHost(assembled);
+        }
+        return assembled;
     }
 }
-_CollectionBuilder_contentType = new WeakMap(), _CollectionBuilder_defaultQuery = new WeakMap(), _CollectionBuilder_query = new WeakMap(), _CollectionBuilder_rawQuery = new WeakMap(), _CollectionBuilder_languageId = new WeakMap(), _CollectionBuilder_draft = new WeakMap();
+_CollectionBuilder_contentType = new WeakMap(), _CollectionBuilder_defaultQuery = new WeakMap(), _CollectionBuilder_query = new WeakMap(), _CollectionBuilder_rawQuery = new WeakMap(), _CollectionBuilder_languageId = new WeakMap(), _CollectionBuilder_draft = new WeakMap(), _CollectionBuilder_includeSystemHost = new WeakMap();
 
 var _RawQueryBuilder_rawQuery, _RawQueryBuilder_languageId;
 /**

package/index.esm.js

@@ -508,6 +508,11 @@ class AIClient extends BaseApiClient {
 /**
  * Default variant identifier used in the application.
  */
+/**
+ * Identifier for the dotCMS System Host.
+ * Used when building queries that should include content from the System Host.
+ */
+const SYSTEM_HOST = 'SYSTEM_HOST';
 /**
  * Fields that should not be formatted when sanitizing the query.
  * These fields are essential for maintaining the integrity of the content type.
@@ -877,6 +882,68 @@ function shouldAddSiteIdConstraint(query, siteId) {
     }
     return true;
 }
+/**
+ * @description
+ * Collects all positive `+conhost:` values from a fully assembled Lucene query,
+ * removes them from their original positions, adds SYSTEM_HOST to the set,
+ * and rebuilds a single grouped constraint at the end of the query.
+ *
+ * This function is designed to be called on the final assembled query string
+ * (after raw query has been appended) so that conhosts from all sources —
+ * auto-injected siteId, builder-path conhost, and raw-path conhost — are
+ * all visible and handled uniformly.
+ *
+ * @example
+ * ```ts
+ * // Single siteId + SYSTEM_HOST
+ * buildConhostWithSystemHost('+contentType:Blog +languageId:1 +live:true +conhost:site-123')
+ * // → '+contentType:Blog +languageId:1 +live:true +(conhost:site-123 conhost:SYSTEM_HOST)'
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Multiple conhosts (multisite) + SYSTEM_HOST
+ * buildConhostWithSystemHost('+contentType:Blog +live:true +conhost:site-a +conhost:site-b')
+ * // → '+contentType:Blog +live:true +(conhost:site-a conhost:site-b conhost:SYSTEM_HOST)'
+ * ```
+ *
+ * @example
+ * ```ts
+ * // No conhost in query (no siteId configured)
+ * buildConhostWithSystemHost('+contentType:Blog +languageId:1 +live:true')
+ * // → '+contentType:Blog +languageId:1 +live:true +conhost:SYSTEM_HOST'
+ * ```
+ *
+ * @export
+ * @param {string} query - The fully assembled Lucene query string to process.
+ * @returns {string} The query with all positive conhost constraints replaced by a single grouped constraint.
+ */
+function buildConhostWithSystemHost(query) {
+    // Collect all unique positive conhost values, excluding SYSTEM_HOST (we'll add it explicitly)
+    const conhostRegex = /\+conhost:([^\s)]+)/gi;
+    const values = [];
+    let match;
+    while ((match = conhostRegex.exec(query)) !== null) {
+        const value = match[1];
+        if (value.toUpperCase() !== SYSTEM_HOST && !values.includes(value)) {
+            values.push(value);
+        }
+    }
+    // Always include SYSTEM_HOST at the end
+    values.push(SYSTEM_HOST);
+    // Remove all existing +conhost: constraints from the query
+    const queryWithoutConhost = query
+        .replace(/\s*\+conhost:[^\s)]+/gi, '')
+        .replace(/\s+/g, ' ')
+        .trim();
+    // Build the final constraint:
+    // - Single value (only SYSTEM_HOST, no other conhost was present): simple form
+    // - Multiple values: grouped form so dotCMS treats them as OR
+    const conhostConstraint = values.length === 1
+        ? `+conhost:${values[0]}`
+        : `+(${values.map((v) => `conhost:${v}`).join(' ')})`;
+    return `${queryWithoutConhost} ${conhostConstraint}`.trim();
+}
 
 var _Field_query;
 /**
@@ -1379,7 +1446,7 @@ class QueryBuilder {
 }
 _QueryBuilder_query = new WeakMap();
 
-var _CollectionBuilder_contentType, _CollectionBuilder_defaultQuery, _CollectionBuilder_query, _CollectionBuilder_rawQuery, _CollectionBuilder_languageId, _CollectionBuilder_draft;
+var _CollectionBuilder_contentType, _CollectionBuilder_defaultQuery, _CollectionBuilder_query, _CollectionBuilder_rawQuery, _CollectionBuilder_languageId, _CollectionBuilder_draft, _CollectionBuilder_includeSystemHost;
 /**
  * Creates a Builder to filter and fetch content from the content API for a specific content type.
  *
@@ -1405,6 +1472,7 @@ class CollectionBuilder extends BaseBuilder {
         _CollectionBuilder_rawQuery.set(this, void 0);
         _CollectionBuilder_languageId.set(this, 1);
         _CollectionBuilder_draft.set(this, false);
+        _CollectionBuilder_includeSystemHost.set(this, false);
         __classPrivateFieldSet(this, _CollectionBuilder_contentType, params.contentType, "f");
         // Build the default query with the contentType field
         __classPrivateFieldSet(this, _CollectionBuilder_defaultQuery, new QueryBuilder().field('contentType').equals(__classPrivateFieldGet(this, _CollectionBuilder_contentType, "f")), "f");
@@ -1474,6 +1542,32 @@ class CollectionBuilder extends BaseBuilder {
         __classPrivateFieldSet(this, _CollectionBuilder_draft, true, "f");
         return this;
     }
+    /**
+     * Includes content from the dotCMS System Host in the query results.
+     *
+     * When enabled, content from the System Host is returned alongside content from
+     * the configured site. All positive `+conhost:` constraints present in the
+     * assembled query are collected and grouped into a single `+(conhost:X conhost:SYSTEM_HOST)`
+     * constraint, so dotCMS returns content from any of those hosts.
+     *
+     * Calling this method multiple times is idempotent — the constraint is only added once.
+     *
+     * @example
+     * ```ts
+     * client.content
+     *   .getCollection<Blog>('Blog')
+     *   .includeSystemHost()
+     *   .limit(10)
+     *   .then(({ contentlets }) => console.log(contentlets));
+     * ```
+     *
+     * @return {CollectionBuilder} A CollectionBuilder instance.
+     * @memberof CollectionBuilder
+     */
+    includeSystemHost() {
+        __classPrivateFieldSet(this, _CollectionBuilder_includeSystemHost, true, "f");
+        return this;
+    }
     /**
      * Filters the content by a variant ID for [Experiments](https://www.dotcms.com/docs/latest/experiments-and-a-b-testing)
      *
@@ -1585,10 +1679,17 @@ class CollectionBuilder extends BaseBuilder {
         const sanitizedQuery = sanitizeQueryForContentType(finalQuery, __classPrivateFieldGet(this, _CollectionBuilder_contentType, "f"));
         // Append raw query if provided (raw query is NOT sanitized for content type)
         const query = __classPrivateFieldGet(this, _CollectionBuilder_rawQuery, "f") ? `${sanitizedQuery} ${__classPrivateFieldGet(this, _CollectionBuilder_rawQuery, "f")}` : sanitizedQuery;
-        return sanitizeQuery(query);
+        const assembled = sanitizeQuery(query);
+        // If includeSystemHost is active, collect all +conhost: values from the fully
+        // assembled query (including those from the raw path), group them, and append
+        // SYSTEM_HOST so dotCMS returns content from any of the matched hosts.
+        if (__classPrivateFieldGet(this, _CollectionBuilder_includeSystemHost, "f")) {
+            return buildConhostWithSystemHost(assembled);
+        }
+        return assembled;
     }
 }
-_CollectionBuilder_contentType = new WeakMap(), _CollectionBuilder_defaultQuery = new WeakMap(), _CollectionBuilder_query = new WeakMap(), _CollectionBuilder_rawQuery = new WeakMap(), _CollectionBuilder_languageId = new WeakMap(), _CollectionBuilder_draft = new WeakMap();
+_CollectionBuilder_contentType = new WeakMap(), _CollectionBuilder_defaultQuery = new WeakMap(), _CollectionBuilder_query = new WeakMap(), _CollectionBuilder_rawQuery = new WeakMap(), _CollectionBuilder_languageId = new WeakMap(), _CollectionBuilder_draft = new WeakMap(), _CollectionBuilder_includeSystemHost = new WeakMap();
 
 var _RawQueryBuilder_rawQuery, _RawQueryBuilder_languageId;
 /**

package/package.json

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

package/src/lib/client/content/builders/collection/collection.d.ts

@@ -89,6 +89,29 @@ export declare class CollectionBuilder<T = unknown> extends BaseBuilder<T> {
      * @memberof CollectionBuilder
      */
     draft(): this;
+    /**
+     * Includes content from the dotCMS System Host in the query results.
+     *
+     * When enabled, content from the System Host is returned alongside content from
+     * the configured site. All positive `+conhost:` constraints present in the
+     * assembled query are collected and grouped into a single `+(conhost:X conhost:SYSTEM_HOST)`
+     * constraint, so dotCMS returns content from any of those hosts.
+     *
+     * Calling this method multiple times is idempotent — the constraint is only added once.
+     *
+     * @example
+     * ```ts
+     * client.content
+     *   .getCollection<Blog>('Blog')
+     *   .includeSystemHost()
+     *   .limit(10)
+     *   .then(({ contentlets }) => console.log(contentlets));
+     * ```
+     *
+     * @return {CollectionBuilder} A CollectionBuilder instance.
+     * @memberof CollectionBuilder
+     */
+    includeSystemHost(): this;
     /**
      * Filters the content by a variant ID for [Experiments](https://www.dotcms.com/docs/latest/experiments-and-a-b-testing)
      *

package/src/lib/client/content/shared/const.d.ts

@@ -2,6 +2,11 @@
  * Default variant identifier used in the application.
  */
 export declare const DEFAULT_VARIANT_ID = "DEFAULT";
+/**
+ * Identifier for the dotCMS System Host.
+ * Used when building queries that should include content from the System Host.
+ */
+export declare const SYSTEM_HOST = "SYSTEM_HOST";
 /**
  * Fields that should not be formatted when sanitizing the query.
  * These fields are essential for maintaining the integrity of the content type.

package/src/lib/client/content/shared/utils.d.ts

@@ -54,3 +54,40 @@ export declare function sanitizeQueryForContentType(query: string, contentType:
  * @returns {boolean} True if site ID constraint should be added, false otherwise
  */
 export declare function shouldAddSiteIdConstraint(query: string, siteId: string | number | null | undefined): boolean;
+/**
+ * @description
+ * Collects all positive `+conhost:` values from a fully assembled Lucene query,
+ * removes them from their original positions, adds SYSTEM_HOST to the set,
+ * and rebuilds a single grouped constraint at the end of the query.
+ *
+ * This function is designed to be called on the final assembled query string
+ * (after raw query has been appended) so that conhosts from all sources —
+ * auto-injected siteId, builder-path conhost, and raw-path conhost — are
+ * all visible and handled uniformly.
+ *
+ * @example
+ * ```ts
+ * // Single siteId + SYSTEM_HOST
+ * buildConhostWithSystemHost('+contentType:Blog +languageId:1 +live:true +conhost:site-123')
+ * // → '+contentType:Blog +languageId:1 +live:true +(conhost:site-123 conhost:SYSTEM_HOST)'
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Multiple conhosts (multisite) + SYSTEM_HOST
+ * buildConhostWithSystemHost('+contentType:Blog +live:true +conhost:site-a +conhost:site-b')
+ * // → '+contentType:Blog +live:true +(conhost:site-a conhost:site-b conhost:SYSTEM_HOST)'
+ * ```
+ *
+ * @example
+ * ```ts
+ * // No conhost in query (no siteId configured)
+ * buildConhostWithSystemHost('+contentType:Blog +languageId:1 +live:true')
+ * // → '+contentType:Blog +languageId:1 +live:true +conhost:SYSTEM_HOST'
+ * ```
+ *
+ * @export
+ * @param {string} query - The fully assembled Lucene query string to process.
+ * @returns {string} The query with all positive conhost constraints replaced by a single grouped constraint.
+ */
+export declare function buildConhostWithSystemHost(query: string): string;