@terminalfour/terminalfour-js 1.0.3 → 1.1.0

package/dist/cjs/content-cache.d.ts

@@ -0,0 +1,38 @@
+import { HttpClient } from './http-client.js';
+import { TypeRegistry } from './type-registry.js';
+import { ElementResolver, MediaCreateFn } from './element-resolver.js';
+import { TtlMap } from './utils.js';
+/**
+ * Client-level shared caches for content operations.
+ *
+ * A single instance is created per `T4Client` and threaded into every
+ * `ContentResource` (including the short-lived ones created by
+ * `SectionRef.get()` / `addSection()`). This ensures that traversing the
+ * hierarchy — which creates many `ContentResource` instances via
+ * `t4.section(id)` — does not re-fetch instance-wide data on every hop.
+ *
+ * Two things previously lived on each `ContentResource` and were rebuilt per
+ * section, causing repeated API calls (`GET /type/`, `GET /contenttype/{id}`,
+ * `GET /content/type/{ct}/{section}`):
+ *
+ * - The element `TypeRegistry` (`GET /type/`) — instance-wide, so shared here
+ *   as a single registry and a single `ElementResolver`.
+ * - Content type templates — split into:
+ *   - `contentTypeDefinitions`: the section-independent `GET /contenttype/{id}`
+ *     response, keyed by content type ID.
+ *   - `sectionTemplates`: the section-specific `GET /content/type/{ct}/{section}`
+ *     response (carries channels), keyed by `"{contentTypeId}:{sectionId}"`.
+ *
+ * All caches respect the global cache epoch, so `T4Client.clearCache()`
+ * invalidates them the same way it always has.
+ */
+export declare class ContentCache {
+    readonly typeRegistry: TypeRegistry;
+    readonly resolver: ElementResolver;
+    /** `GET /content/type/{ct}/{section}` responses, keyed by `"{ct}:{section}"`. */
+    readonly sectionTemplates: TtlMap<string, unknown>;
+    /** `GET /contenttype/{id}` responses, keyed by content type ID. */
+    readonly contentTypeDefinitions: TtlMap<number, unknown>;
+    constructor(httpClient: HttpClient, defaultLanguage: string, mediaCreateFn?: MediaCreateFn | null);
+}
+//# sourceMappingURL=content-cache.d.ts.map

package/dist/cjs/content-cache.js

@@ -0,0 +1,42 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ContentCache = void 0;
+const type_registry_js_1 = require("./type-registry.js");
+const element_resolver_js_1 = require("./element-resolver.js");
+const utils_js_1 = require("./utils.js");
+/**
+ * Client-level shared caches for content operations.
+ *
+ * A single instance is created per `T4Client` and threaded into every
+ * `ContentResource` (including the short-lived ones created by
+ * `SectionRef.get()` / `addSection()`). This ensures that traversing the
+ * hierarchy — which creates many `ContentResource` instances via
+ * `t4.section(id)` — does not re-fetch instance-wide data on every hop.
+ *
+ * Two things previously lived on each `ContentResource` and were rebuilt per
+ * section, causing repeated API calls (`GET /type/`, `GET /contenttype/{id}`,
+ * `GET /content/type/{ct}/{section}`):
+ *
+ * - The element `TypeRegistry` (`GET /type/`) — instance-wide, so shared here
+ *   as a single registry and a single `ElementResolver`.
+ * - Content type templates — split into:
+ *   - `contentTypeDefinitions`: the section-independent `GET /contenttype/{id}`
+ *     response, keyed by content type ID.
+ *   - `sectionTemplates`: the section-specific `GET /content/type/{ct}/{section}`
+ *     response (carries channels), keyed by `"{contentTypeId}:{sectionId}"`.
+ *
+ * All caches respect the global cache epoch, so `T4Client.clearCache()`
+ * invalidates them the same way it always has.
+ */
+class ContentCache {
+    constructor(httpClient, defaultLanguage, mediaCreateFn) {
+        /** `GET /content/type/{ct}/{section}` responses, keyed by `"{ct}:{section}"`. */
+        this.sectionTemplates = new utils_js_1.TtlMap();
+        /** `GET /contenttype/{id}` responses, keyed by content type ID. */
+        this.contentTypeDefinitions = new utils_js_1.TtlMap();
+        this.typeRegistry = new type_registry_js_1.TypeRegistry(httpClient);
+        this.resolver = new element_resolver_js_1.ElementResolver(httpClient, defaultLanguage, this.typeRegistry, mediaCreateFn);
+    }
+}
+exports.ContentCache = ContentCache;
+//# sourceMappingURL=content-cache.js.map

package/dist/cjs/element-resolver.d.ts

@@ -83,6 +83,22 @@ export declare class ElementResolver {
      * Uses the TypeRegistry to look up type names instead of hardcoded IDs.
      */
     resolveValue(value: unknown, element: TemplateElement, language: string, allElements?: TemplateElement[], context?: ResolveContext): Promise<unknown>;
+    /**
+     * Builds the T4 elements map from developer-friendly field names and values.
+     * Resolves list values, dates, repeaters, etc. automatically.
+     *
+     * Shared by both write paths: `ContentResource` (create/update) and
+     * `ContentItem.save()`. Keeping a single implementation here prevents the two
+     * paths from drifting — the reason repeaters previously only resolved on one
+     * of them.
+     */
+    buildElements(fields: Record<string, unknown>, elements: TemplateElement[], name: string, language: string, sectionId: number, context?: ResolveContext): Promise<Record<string, unknown>>;
+    /**
+     * Builds a repeater value array from developer-friendly input.
+     * Each repeater item gets its own element key resolution using the
+     * repeater's sub-content-type elements from contentTypeElementConfiguration.
+     */
+    buildRepeaterValue(items: RepeaterInput[], element: TemplateElement, language: string, sectionId: number): Promise<unknown[]>;
     getList(listId: number, language: string): Promise<ListResponse>;
     private resolveItemName;
     private resolveDate;

package/dist/cjs/element-resolver.js

@@ -82,11 +82,87 @@ class ElementResolver {
             case 'Keyword Selector':
                 return this.resolveKeywordSelector(value, element.listId, language);
             case 'Repeater':
-                return value; // handled separately in buildElements
+                return value; // handled separately in buildElements / buildRepeaterValue
             default:
                 return value;
         }
     }
+    /**
+     * Builds the T4 elements map from developer-friendly field names and values.
+     * Resolves list values, dates, repeaters, etc. automatically.
+     *
+     * Shared by both write paths: `ContentResource` (create/update) and
+     * `ContentItem.save()`. Keeping a single implementation here prevents the two
+     * paths from drifting — the reason repeaters previously only resolved on one
+     * of them.
+     */
+    async buildElements(fields, elements, name, language, sectionId, context) {
+        const result = {};
+        // Name element
+        const nameEl = elements.find((el) => el.name.toLowerCase() === 'name');
+        if (nameEl) {
+            result[`${nameEl.name}#${nameEl.id}:${nameEl.type}`] = name;
+        }
+        for (const [fieldName, value] of Object.entries(fields)) {
+            const fieldLower = fieldName.toLowerCase();
+            const element = elements.find((el) => el.name.toLowerCase() === fieldLower
+                || (el.alias && el.alias.toLowerCase() === fieldLower));
+            if (!element) {
+                const validNames = elements
+                    .filter((el) => el.name.toLowerCase() !== 'name')
+                    .map((el) => `"${el.alias || el.name}"`)
+                    .join(', ');
+                throw new Error(`Unknown field "${fieldName}" on this content type. Valid fields are: ${validNames}`);
+            }
+            const key = `${element.name}#${element.id}:${element.type}`;
+            // Repeater — special handling (no maxSize validation)
+            const typeName = await this.typeRegistry.getNameById(element.type);
+            if (typeName === 'Repeater' && Array.isArray(value)) {
+                result[key] = await this.buildRepeaterValue(value, element, language, sectionId);
+                continue;
+            }
+            const resolved = await this.resolveValue(value, element, language, elements, context);
+            // Validate maxSize on the resolved value (what actually gets sent to the API)
+            if (element.maxSize) {
+                const resolvedStr = String(resolved ?? '');
+                if (resolvedStr.length > element.maxSize) {
+                    const friendlyName = element.alias || element.name;
+                    throw new Error(`Field "${friendlyName}" exceeds max size: ${resolvedStr.length} characters (max ${element.maxSize})`);
+                }
+            }
+            result[key] = resolved;
+        }
+        return result;
+    }
+    /**
+     * Builds a repeater value array from developer-friendly input.
+     * Each repeater item gets its own element key resolution using the
+     * repeater's sub-content-type elements from contentTypeElementConfiguration.
+     */
+    async buildRepeaterValue(items, element, language, sectionId) {
+        const config = element.contentTypeElementConfiguration;
+        const repeaterElements = config?.contentTypeDTO?.contentTypeElements;
+        if (!repeaterElements || repeaterElements.length === 0)
+            return items;
+        const result = [];
+        for (const item of items) {
+            const repeaterId = -Math.floor(Math.random() * 100000);
+            // Repeater items use their own repeaterId as fromContentId for SS links
+            const repeaterContext = {
+                fromSectionId: sectionId,
+                fromContentId: repeaterId,
+            };
+            const elements = await this.buildElements(item.fields, repeaterElements, item.name, language, sectionId, repeaterContext);
+            result.push({
+                repeaterId,
+                repeaterContent: {
+                    name: item.name,
+                    elements,
+                },
+            });
+        }
+        return result;
+    }
     // ── List fetching ──
     async getList(listId, language) {
         const cached = this.listCache.get(listId);

package/dist/cjs/models/content-item.js

@@ -531,7 +531,19 @@ class ContentItem {
             }
             let resolved;
             if (templateEl && this._resolver) {
-                resolved = await this._resolver.resolveValue(value, templateEl, this.language, this._templateElements ?? undefined, context);
+                // Repeater fields need the same dedicated resolution ContentResource
+                // uses on create/update — each item's sub-fields resolved into element
+                // keys and wrapped in { repeaterId, repeaterContent }. resolveValue()
+                // passes repeater arrays through untouched, so branch here explicitly.
+                const typeName = this._typeRegistry
+                    ? await this._typeRegistry.getNameById(templateEl.type)
+                    : null;
+                if (typeName === 'Repeater' && Array.isArray(value)) {
+                    resolved = await this._resolver.buildRepeaterValue(value, templateEl, this.language, this._sectionId);
+                }
+                else {
+                    resolved = await this._resolver.resolveValue(value, templateEl, this.language, this._templateElements ?? undefined, context);
+                }
             }
             else {
                 resolved = value;

package/dist/cjs/resources/content-resource.d.ts

@@ -2,6 +2,7 @@ import { HttpClient } from '../http-client.js';
 import { LanguageOption, CreateContentData, UpdateContentData } from '../types.js';
 import { ContentItem } from '../models/content-item.js';
 import { MediaCreateFn } from '../element-resolver.js';
+import { ContentCache } from '../content-cache.js';
 /**
  * Section-scoped resource for content CRUD operations.
  * All requests are scoped to the section ID provided at construction time.
@@ -10,23 +11,18 @@ export declare class ContentResource {
     private readonly httpClient;
     private readonly sectionId;
     private readonly defaultLanguage;
-    private readonly resolver;
-    private readonly typeRegistry;
-    /** Cache of content type templates keyed by content type ID */
-    private templateCache;
-    constructor(httpClient: HttpClient, sectionId: number, defaultLanguage: string, mediaCreateFn?: MediaCreateFn | null);
+    private readonly cache;
+    constructor(httpClient: HttpClient, sectionId: number, defaultLanguage: string, mediaCreateFn?: MediaCreateFn | null, cache?: ContentCache);
+    private get resolver();
+    private get typeRegistry();
     private getTemplate;
+    /** Fetches the section-independent content type definition, cached by content type ID. */
+    private getContentTypeDefinition;
     /**
      * Builds the T4 elements map from developer-friendly field names and values.
      * Resolves list values, dates, repeaters, etc. automatically.
      */
     private buildElements;
-    /**
-     * Builds repeater value array from developer-friendly input.
-     * Each repeater item gets its own element key resolution using the
-     * repeater's sub-content-type elements from contentTypeElementConfiguration.
-     */
-    private buildRepeaterValue;
     /** Lists all content items in this section. */
     list(options?: LanguageOption): Promise<ContentItem[]>;
     /** Retrieves a single content item by ID. */

package/dist/cjs/resources/content-resource.js

@@ -3,36 +3,43 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.ContentResource = void 0;
 const utils_js_1 = require("../utils.js");
 const content_item_js_1 = require("../models/content-item.js");
-const element_resolver_js_1 = require("../element-resolver.js");
-const type_registry_js_1 = require("../type-registry.js");
+const content_cache_js_1 = require("../content-cache.js");
 /**
  * Section-scoped resource for content CRUD operations.
  * All requests are scoped to the section ID provided at construction time.
  */
 class ContentResource {
-    constructor(httpClient, sectionId, defaultLanguage, mediaCreateFn) {
-        /** Cache of content type templates keyed by content type ID */
-        this.templateCache = new utils_js_1.TtlMap();
+    constructor(httpClient, sectionId, defaultLanguage, mediaCreateFn, cache) {
         this.httpClient = httpClient;
         this.sectionId = sectionId;
         this.defaultLanguage = defaultLanguage;
-        this.typeRegistry = new type_registry_js_1.TypeRegistry(httpClient);
-        this.resolver = new element_resolver_js_1.ElementResolver(httpClient, defaultLanguage, this.typeRegistry, mediaCreateFn);
+        // A shared cache is threaded in by T4Client so the element TypeRegistry and
+        // content type templates survive across sections during a traversal. When
+        // constructed standalone (e.g. in tests), fall back to a private cache so
+        // behaviour is unchanged.
+        this.cache = cache ?? new content_cache_js_1.ContentCache(httpClient, defaultLanguage, mediaCreateFn);
+    }
+    get resolver() {
+        return this.cache.resolver;
+    }
+    get typeRegistry() {
+        return this.cache.typeRegistry;
     }
     async getTemplate(contentTypeId) {
-        const cached = this.templateCache.get(contentTypeId);
+        const sectionKey = `${contentTypeId}:${this.sectionId}`;
+        const cached = this.cache.sectionTemplates.get(sectionKey);
         if (cached)
             return cached;
-        // Fetch both the new content template and the full content type definition
+        // The section template (channels etc.) is section-specific; the content type
+        // definition (alias, listId, repeater config) is instance-wide. Fetch each
+        // through its own shared cache so revisiting a section, or reusing a content
+        // type across sections, avoids re-fetching.
         const [template, rawContentType] = await Promise.all([
             this.httpClient.request({
                 method: 'GET',
                 path: `/content/type/${contentTypeId}/${this.sectionId}`,
             }),
-            this.httpClient.request({
-                method: 'GET',
-                path: `/contenttype/${contentTypeId}`,
-            }),
+            this.getContentTypeDefinition(contentTypeId),
         ]);
         // Merge alias and contentTypeElementConfiguration from the full content type
         for (const templateEl of template.contentType.contentTypeElements) {
@@ -47,79 +54,29 @@ class ContentResource {
                 }
             }
         }
-        this.templateCache.set(contentTypeId, template);
+        this.cache.sectionTemplates.set(sectionKey, template);
         return template;
     }
+    /** Fetches the section-independent content type definition, cached by content type ID. */
+    async getContentTypeDefinition(contentTypeId) {
+        const cached = this.cache.contentTypeDefinitions.get(contentTypeId);
+        if (cached)
+            return cached;
+        const rawContentType = await this.httpClient.request({
+            method: 'GET',
+            path: `/contenttype/${contentTypeId}`,
+        });
+        this.cache.contentTypeDefinitions.set(contentTypeId, rawContentType);
+        return rawContentType;
+    }
     /**
      * Builds the T4 elements map from developer-friendly field names and values.
      * Resolves list values, dates, repeaters, etc. automatically.
      */
     async buildElements(fields, elements, name, language, context) {
-        const result = {};
-        // Name element
-        const nameEl = elements.find((el) => el.name.toLowerCase() === 'name');
-        if (nameEl) {
-            result[`${nameEl.name}#${nameEl.id}:${nameEl.type}`] = name;
-        }
-        for (const [fieldName, value] of Object.entries(fields)) {
-            const fieldLower = fieldName.toLowerCase();
-            const element = elements.find((el) => el.name.toLowerCase() === fieldLower
-                || (el.alias && el.alias.toLowerCase() === fieldLower));
-            if (!element) {
-                const validNames = elements
-                    .filter((el) => el.name.toLowerCase() !== 'name')
-                    .map((el) => `"${el.alias || el.name}"`)
-                    .join(', ');
-                throw new Error(`Unknown field "${fieldName}" on this content type. Valid fields are: ${validNames}`);
-            }
-            const key = `${element.name}#${element.id}:${element.type}`;
-            // Repeater — special handling (no maxSize validation)
-            const typeName = await this.typeRegistry.getNameById(element.type);
-            if (typeName === 'Repeater' && Array.isArray(value)) {
-                result[key] = await this.buildRepeaterValue(value, element, language);
-                continue;
-            }
-            const resolved = await this.resolver.resolveValue(value, element, language, elements, context);
-            // Validate maxSize on the resolved value (what actually gets sent to the API)
-            if (element.maxSize) {
-                const resolvedStr = String(resolved ?? '');
-                if (resolvedStr.length > element.maxSize) {
-                    const friendlyName = element.alias || element.name;
-                    throw new Error(`Field "${friendlyName}" exceeds max size: ${resolvedStr.length} characters (max ${element.maxSize})`);
-                }
-            }
-            result[key] = resolved;
-        }
-        return result;
-    }
-    /**
-     * Builds repeater value array from developer-friendly input.
-     * Each repeater item gets its own element key resolution using the
-     * repeater's sub-content-type elements from contentTypeElementConfiguration.
-     */
-    async buildRepeaterValue(items, element, language) {
-        const config = element.contentTypeElementConfiguration;
-        const repeaterElements = config?.contentTypeDTO?.contentTypeElements;
-        if (!repeaterElements || repeaterElements.length === 0)
-            return items;
-        const result = [];
-        for (const item of items) {
-            const repeaterId = -Math.floor(Math.random() * 100000);
-            // Repeater items use their own repeaterId as fromContentId for SS links
-            const repeaterContext = {
-                fromSectionId: this.sectionId,
-                fromContentId: repeaterId,
-            };
-            const elements = await this.buildElements(item.fields, repeaterElements, item.name, language, repeaterContext);
-            result.push({
-                repeaterId,
-                repeaterContent: {
-                    name: item.name,
-                    elements,
-                },
-            });
-        }
-        return result;
+        // Delegates to the shared implementation on ElementResolver so this path
+        // and ContentItem.save() resolve fields (repeaters included) identically.
+        return this.resolver.buildElements(fields, elements, name, language, this.sectionId, context);
     }
     /** Lists all content items in this section. */
     async list(options) {

package/dist/cjs/resources/content-type-resource.d.ts

@@ -1,5 +1,6 @@
 import { HttpClient } from '../http-client.js';
 import { ContentTypeData, ContentTypeFieldDef } from '../types.js';
+import { RawPrimaryGroup } from '../utils.js';
 /** Raw content type element from the API response */
 interface ApiContentTypeElement {
     id?: number;
@@ -40,12 +41,7 @@ interface ApiContentType {
     sharedGroups?: Array<{
         id: number;
     }>;
-    primaryGroup?: {
-        id: number | null;
-        group?: {
-            id: number;
-        };
-    };
+    primaryGroup?: RawPrimaryGroup;
     enableDirectEdit?: boolean;
     elementIdforFilename?: number;
     contentTypeElements?: ApiContentTypeElement[];

package/dist/cjs/resources/content-type-resource.js

@@ -59,8 +59,8 @@ function mapContentType(raw, typeMap, editorMap) {
             description: (0, utils_js_1.decodeHtmlEntities)(raw.description ?? ''),
             minUserLevel: utils_js_1.AUTH_LEVEL_MAP[raw.minAuthLevel ?? 2] ?? `unknown (${raw.minAuthLevel})`,
             workflow: raw.workflow ?? 0,
-            sharedGroups: (raw.sharedGroups ?? []).map((g) => g.id),
-            primaryGroup: raw.primaryGroup?.group?.id ?? raw.primaryGroup?.id ?? 0,
+            sharedGroups: (0, utils_js_1.readSharedGroups)(raw.sharedGroups),
+            primaryGroup: (0, utils_js_1.readPrimaryGroup)(raw.primaryGroup),
             directEdit: raw.enableDirectEdit ?? true,
             fields: fieldsRecord,
         },
@@ -590,6 +590,7 @@ class ContentType {
     }
     /** Persists current property values to the server via PUT. */
     async save() {
+        (0, utils_js_1.assertGroupsValid)(this.primaryGroup, this.sharedGroups);
         const authLevel = String(utils_js_1.AUTH_LEVEL_REVERSE[this.minUserLevel] ?? this._rawData.minAuthLevel ?? 2);
         // Sync field changes back to raw contentTypeElements
         let rawElements = (this._rawData.contentTypeElements ?? []);
@@ -657,8 +658,8 @@ class ContentType {
             minAuthLevel: authLevel,
             workflow: String(this.workflow),
             enableDirectEdit: this.directEdit,
-            sharedGroups: this.sharedGroups.map((id) => ({ id })),
-            primaryGroup: { id: this.primaryGroup || null },
+            sharedGroups: (0, utils_js_1.writeSharedGroups)(this.sharedGroups),
+            primaryGroup: (0, utils_js_1.writePrimaryGroup)(this.primaryGroup),
             contentTypeElements: rawElements,
         };
         // Resolve useAsFilename → elementIdforFilename
@@ -683,6 +684,10 @@ class ContentType {
             path: `/contenttype/${this.id}`,
             body: updated,
         });
+        // The content type definition changed, so any cached copy (content type
+        // templates/definitions, element type maps, etc.) is now stale. Invalidate
+        // all caches via the global epoch so subsequent reads re-fetch.
+        (0, utils_js_1.invalidateAllCaches)();
         // Update raw data for next save
         this._rawData = updated;
         this._removedElementIds.clear();
@@ -867,6 +872,9 @@ class ContentTypeResource {
             method: 'DELETE',
             path: `/contenttype/${id}`,
         });
+        // A deleted content type may be cached; invalidate all caches so stale
+        // definitions/templates aren't served after the delete.
+        (0, utils_js_1.invalidateAllCaches)();
     }
     /** Creates a new content type. */
     async create(data) {
@@ -876,6 +884,7 @@ class ContentTypeResource {
         if (!data.elements?.length) {
             throw new Error('Content type must have at least one element');
         }
+        (0, utils_js_1.assertGroupsValid)(data.primaryGroup ?? 0, data.sharedGroups);
         // Validate useAsFilename constraints
         const filenameElements = data.elements.filter((el) => el.useAsFilename);
         if (filenameElements.length > 1) {
@@ -994,11 +1003,13 @@ class ContentTypeResource {
                 warningMessage: '',
                 elementIdforFilename: elementIdForFilename,
                 conditionals: [],
-                sharedGroups: (data.sharedGroups ?? []).map((id) => ({ id })),
-                primaryGroup: { id: data.primaryGroup ?? 0 },
+                sharedGroups: (0, utils_js_1.writeSharedGroups)(data.sharedGroups),
+                primaryGroup: (0, utils_js_1.writePrimaryGroup)(data.primaryGroup ?? 0),
                 contentTypeElements,
             },
         });
+        // New content type may affect cached lookups; invalidate for consistency.
+        (0, utils_js_1.invalidateAllCaches)();
         const editorMap = await this.getEditorMap();
         const result = mapContentType(raw, typeMap, editorMap);
         await this.resolveListNames([result.data]);

package/dist/cjs/resources/list-resource.d.ts

@@ -1,5 +1,6 @@
 import { HttpClient } from '../http-client.js';
 import { LanguageOption } from '../types.js';
+import { RawPrimaryGroup } from '../utils.js';
 /** Raw list item from GET /list/{id}/{language} */
 interface RawListItem {
     id: number;
@@ -18,12 +19,7 @@ interface RawListDetail {
     language: string;
     isForcedLanguage?: boolean;
     isDefaultLanguage?: boolean;
-    primaryGroup?: {
-        id: number | null;
-        group?: {
-            id: number;
-        };
-    };
+    primaryGroup?: RawPrimaryGroup;
     sharedGroups?: Array<{
         id: number;
     }>;

package/dist/cjs/resources/list-resource.js

@@ -11,8 +11,8 @@ class List {
         this.description = (0, utils_js_2.decodeHtmlEntities)(raw.description ?? '');
         this.isForcedLanguage = raw.isForcedLanguage ?? false;
         this.isDefaultLanguage = raw.isDefaultLanguage ?? false;
-        this.primaryGroup = raw.primaryGroup?.group?.id ?? raw.primaryGroup?.id ?? 0;
-        this.sharedGroups = (raw.sharedGroups ?? []).map((g) => g.id);
+        this.primaryGroup = (0, utils_js_2.readPrimaryGroup)(raw.primaryGroup);
+        this.sharedGroups = (0, utils_js_2.readSharedGroups)(raw.sharedGroups);
         this.items = {};
         for (const item of (raw.items ?? []).sort((a, b) => a.sequence - b.sequence)) {
             const friendlyName = (0, utils_js_2.decodeHtmlEntities)(item.name);
@@ -59,6 +59,7 @@ class List {
         if (this.isForcedLanguage && this.isDefaultLanguage) {
             throw new Error('isForcedLanguage and isDefaultLanguage cannot both be true');
         }
+        (0, utils_js_2.assertGroupsValid)(this.primaryGroup, this.sharedGroups);
         const items = Object.values(this.items).map((item, i) => ({
             id: String(item._rawId ?? 0),
             name: item.name,
@@ -73,8 +74,8 @@ class List {
             description: this.description,
             isForcedLanguage: this.isForcedLanguage,
             isDefaultLanguage: this.isDefaultLanguage,
-            primaryGroup: { id: this.primaryGroup || 0 },
-            sharedGroups: this.sharedGroups.map((id) => ({ id })),
+            primaryGroup: (0, utils_js_2.writePrimaryGroup)(this.primaryGroup),
+            sharedGroups: (0, utils_js_2.writeSharedGroups)(this.sharedGroups),
             items,
         };
         await this._httpClient.request({
@@ -149,6 +150,7 @@ class ListResource {
         if (data.isForcedLanguage && data.isDefaultLanguage) {
             throw new Error('isForcedLanguage and isDefaultLanguage cannot both be true');
         }
+        (0, utils_js_2.assertGroupsValid)(data.primaryGroup ?? 0, data.sharedGroups);
         const language = (0, utils_js_1.resolveLanguage)(options?.language, this.defaultLanguage);
         const items = (data.items ?? []).map((item, i) => ({
             id: '0',
@@ -167,8 +169,8 @@ class ListResource {
                 items,
                 isForcedLanguage: data.isForcedLanguage ?? false,
                 isDefaultLanguage: data.isDefaultLanguage ?? false,
-                sharedGroups: (data.sharedGroups ?? []).map((id) => ({ id })),
-                primaryGroup: { id: data.primaryGroup ?? 0 },
+                sharedGroups: (0, utils_js_2.writeSharedGroups)(data.sharedGroups),
+                primaryGroup: (0, utils_js_2.writePrimaryGroup)(data.primaryGroup ?? 0),
                 sortType: 0,
             },
         });

package/dist/cjs/resources/navigation-resource.d.ts

@@ -1,4 +1,5 @@
 import { HttpClient } from '../http-client.js';
+import { RawPrimaryGroup } from '../utils.js';
 /** SDK-friendly navigation type codes (consistent kebab-case) */
 export type NavigationType = 'a-to-z' | 'breadcrumbs' | 'css-selector' | 'generate-file' | 'keyword-search' | 'language-switcher' | 'link-menu' | 'pagination' | 'previous-next-fulltext' | 'publish-to-one-file' | 'related-content' | 'related-section-branch' | 'return-to-index' | 'section-details' | 'section-iterator' | 'section-meta-info' | 'site-map' | 'top-content' | 'top-stories';
 /** Human-readable type name mapping */
@@ -23,6 +24,10 @@ interface RawNavigationDetail {
     isPreviewModeEnabled: boolean;
     isCachingEnabled: boolean;
     date?: string;
+    primaryGroup?: RawPrimaryGroup;
+    sharedGroups?: Array<{
+        id: number;
+    }>;
     properties: Record<string, {
         value?: string;
         attribute: string;
@@ -42,6 +47,10 @@ export declare class NavigationObject {
     enabled: boolean;
     cachingEnabled: boolean;
     previewEnabled: boolean;
+    /** Owning group ID. 0 = no primary group (Global). */
+    primaryGroup: number;
+    /** Group IDs this navigation object is shared with. */
+    sharedGroups: number[];
     properties: Record<string, unknown>;
     private readonly _httpClient;
     private _rawData;
@@ -525,6 +534,10 @@ export interface CreateNavigationData {
     description?: string;
     enabled?: boolean;
     previewEnabled?: boolean;
+    /** Owning group ID. 0 = no primary group (Global). Defaults to 0. */
+    primaryGroup?: number;
+    /** Group IDs to share this navigation object with. Defaults to none. */
+    sharedGroups?: number[];
     properties?: A2ZProperties | BreadcrumbsProperties | CssSelectorProperties | GenerateFileProperties | LanguageSwitcherProperties | PaginationProperties | PreviousNextProperties | SectionIteratorProperties | RelatedSectionBranchProperties | ReturnToIndexProperties | SectionMetaInfoProperties | TopStoriesProperties | SiteMapProperties | SectionDetailsProperties | RelatedContentProperties | LinkMenuProperties | PublishToOneFileProperties | TopContentProperties | KeywordSearchProperties | Record<string, unknown>;
 }
 /**
@@ -538,6 +551,10 @@ export interface UpdateNavigationData {
     enabled?: boolean;
     previewEnabled?: boolean;
     cachingEnabled?: boolean;
+    /** Owning group ID. 0 = no primary group (Global). */
+    primaryGroup?: number;
+    /** Group IDs to share this navigation object with. */
+    sharedGroups?: number[];
     properties?: A2ZProperties | BreadcrumbsProperties | CssSelectorProperties | GenerateFileProperties | LanguageSwitcherProperties | PaginationProperties | PreviousNextProperties | SectionIteratorProperties | RelatedSectionBranchProperties | ReturnToIndexProperties | SectionMetaInfoProperties | TopStoriesProperties | SiteMapProperties | SectionDetailsProperties | RelatedContentProperties | LinkMenuProperties | PublishToOneFileProperties | TopContentProperties | KeywordSearchProperties | Record<string, unknown>;
 }
 /**