@terminalfour/terminalfour-js 1.0.2 → 1.1.0

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

@@ -1,35 +1,42 @@
-import { resolveLanguage, toTimestamp, STATUS_CODES, TtlMap } from '../utils.js';
+import { resolveLanguage, toTimestamp, STATUS_CODES } from '../utils.js';
 import { createContentItem } from '../models/content-item.js';
-import { ElementResolver } from '../element-resolver.js';
-import { TypeRegistry } from '../type-registry.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.
  */
 export class ContentResource {
-    constructor(httpClient, sectionId, defaultLanguage, mediaCreateFn) {
-        /** Cache of content type templates keyed by content type ID */
-        this.templateCache = new TtlMap();
+    constructor(httpClient, sectionId, defaultLanguage, mediaCreateFn, cache) {
         this.httpClient = httpClient;
         this.sectionId = sectionId;
         this.defaultLanguage = defaultLanguage;
-        this.typeRegistry = new TypeRegistry(httpClient);
-        this.resolver = new 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 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) {
@@ -44,79 +51,29 @@ export 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/esm/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[];
@@ -242,11 +238,15 @@ export declare class ContentTypeResource {
         /**
          * Existing fields to modify, matched by `name`. Only the provided
          * properties are changed; omitted ones are left as-is. Use this to change
-         * an element's length (`maxSize`), description, or its `required`/`shown`
-         * flags. Throws if a named field does not exist on the content type.
+         * an element's length (`maxSize`), description, its `required`/`shown`
+         * flags, or to rename it with `newName`. Throws if a named field does not
+         * exist on the content type. Renaming an element on a system content type
+         * is blocked (except the Section Meta Data and Extended User types).
          */
         updateFields?: Array<{
             name: string;
+            /** New name for the element. Renames are blocked on system content types. */
+            newName?: string;
             maxSize?: number;
             description?: string;
             required?: boolean;

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

@@ -1,4 +1,4 @@
-import { decodeHtmlEntities, AUTH_LEVEL_MAP, AUTH_LEVEL_REVERSE, debugWarn, DEFAULT_CACHE_TTL, getCacheEpoch } from '../utils.js';
+import { decodeHtmlEntities, AUTH_LEVEL_MAP, AUTH_LEVEL_REVERSE, debugWarn, DEFAULT_CACHE_TTL, getCacheEpoch, invalidateAllCaches, readPrimaryGroup, readSharedGroups, writePrimaryGroup, writeSharedGroups, assertGroupsValid } from '../utils.js';
 /** The content type category ID that marks a system content type. */
 const SYSTEM_CONTENT_TYPE = 30;
 function resolveTypeName(type, typeMap) {
@@ -56,8 +56,8 @@ function mapContentType(raw, typeMap, editorMap) {
             description: decodeHtmlEntities(raw.description ?? ''),
             minUserLevel: 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: readSharedGroups(raw.sharedGroups),
+            primaryGroup: readPrimaryGroup(raw.primaryGroup),
             directEdit: raw.enableDirectEdit ?? true,
             fields: fieldsRecord,
         },
@@ -586,6 +586,7 @@ export class ContentType {
     }
     /** Persists current property values to the server via PUT. */
     async save() {
+        assertGroupsValid(this.primaryGroup, this.sharedGroups);
         const authLevel = String(AUTH_LEVEL_REVERSE[this.minUserLevel] ?? this._rawData.minAuthLevel ?? 2);
         // Sync field changes back to raw contentTypeElements
         let rawElements = (this._rawData.contentTypeElements ?? []);
@@ -653,8 +654,8 @@ export class ContentType {
             minAuthLevel: authLevel,
             workflow: String(this.workflow),
             enableDirectEdit: this.directEdit,
-            sharedGroups: this.sharedGroups.map((id) => ({ id })),
-            primaryGroup: { id: this.primaryGroup || null },
+            sharedGroups: writeSharedGroups(this.sharedGroups),
+            primaryGroup: writePrimaryGroup(this.primaryGroup),
             contentTypeElements: rawElements,
         };
         // Resolve useAsFilename → elementIdforFilename
@@ -679,6 +680,10 @@ export 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.
+        invalidateAllCaches();
         // Update raw data for next save
         this._rawData = updated;
         this._removedElementIds.clear();
@@ -818,6 +823,14 @@ export class ContentTypeResource {
                     field.required = change.required;
                 if (change.shown !== undefined)
                     field.shown = change.shown;
+                // Rename last: save() detects the change against the element's _elementId
+                // link and applies the system content type rename guard. Re-key the
+                // fields record so the returned model is addressable by the new name.
+                if (change.newName !== undefined && change.newName !== change.name) {
+                    field.name = change.newName;
+                    ct.fields[change.newName] = field;
+                    delete ct.fields[change.name];
+                }
             }
         }
         if (data.removeFields) {
@@ -854,6 +867,9 @@ export 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.
+        invalidateAllCaches();
     }
     /** Creates a new content type. */
     async create(data) {
@@ -863,6 +879,7 @@ export class ContentTypeResource {
         if (!data.elements?.length) {
             throw new Error('Content type must have at least one element');
         }
+        assertGroupsValid(data.primaryGroup ?? 0, data.sharedGroups);
         // Validate useAsFilename constraints
         const filenameElements = data.elements.filter((el) => el.useAsFilename);
         if (filenameElements.length > 1) {
@@ -981,11 +998,13 @@ export class ContentTypeResource {
                 warningMessage: '',
                 elementIdforFilename: elementIdForFilename,
                 conditionals: [],
-                sharedGroups: (data.sharedGroups ?? []).map((id) => ({ id })),
-                primaryGroup: { id: data.primaryGroup ?? 0 },
+                sharedGroups: writeSharedGroups(data.sharedGroups),
+                primaryGroup: writePrimaryGroup(data.primaryGroup ?? 0),
                 contentTypeElements,
             },
         });
+        // New content type may affect cached lookups; invalidate for consistency.
+        invalidateAllCaches();
         const editorMap = await this.getEditorMap();
         const result = mapContentType(raw, typeMap, editorMap);
         await this.resolveListNames([result.data]);

package/dist/esm/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/esm/resources/list-resource.js

@@ -1,5 +1,5 @@
 import { resolveLanguage } from '../utils.js';
-import { decodeHtmlEntities } from '../utils.js';
+import { decodeHtmlEntities, readPrimaryGroup, readSharedGroups, writePrimaryGroup, writeSharedGroups, assertGroupsValid } from '../utils.js';
 /** A mutable list object. Modify properties and call save() to persist. */
 export class List {
     constructor(raw, httpClient, language) {
@@ -8,8 +8,8 @@ export class List {
         this.description = 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 = readPrimaryGroup(raw.primaryGroup);
+        this.sharedGroups = readSharedGroups(raw.sharedGroups);
         this.items = {};
         for (const item of (raw.items ?? []).sort((a, b) => a.sequence - b.sequence)) {
             const friendlyName = decodeHtmlEntities(item.name);
@@ -56,6 +56,7 @@ export class List {
         if (this.isForcedLanguage && this.isDefaultLanguage) {
             throw new Error('isForcedLanguage and isDefaultLanguage cannot both be true');
         }
+        assertGroupsValid(this.primaryGroup, this.sharedGroups);
         const items = Object.values(this.items).map((item, i) => ({
             id: String(item._rawId ?? 0),
             name: item.name,
@@ -70,8 +71,8 @@ export class List {
             description: this.description,
             isForcedLanguage: this.isForcedLanguage,
             isDefaultLanguage: this.isDefaultLanguage,
-            primaryGroup: { id: this.primaryGroup || 0 },
-            sharedGroups: this.sharedGroups.map((id) => ({ id })),
+            primaryGroup: writePrimaryGroup(this.primaryGroup),
+            sharedGroups: writeSharedGroups(this.sharedGroups),
             items,
         };
         await this._httpClient.request({
@@ -145,6 +146,7 @@ export class ListResource {
         if (data.isForcedLanguage && data.isDefaultLanguage) {
             throw new Error('isForcedLanguage and isDefaultLanguage cannot both be true');
         }
+        assertGroupsValid(data.primaryGroup ?? 0, data.sharedGroups);
         const language = resolveLanguage(options?.language, this.defaultLanguage);
         const items = (data.items ?? []).map((item, i) => ({
             id: '0',
@@ -163,8 +165,8 @@ export class ListResource {
                 items,
                 isForcedLanguage: data.isForcedLanguage ?? false,
                 isDefaultLanguage: data.isDefaultLanguage ?? false,
-                sharedGroups: (data.sharedGroups ?? []).map((id) => ({ id })),
-                primaryGroup: { id: data.primaryGroup ?? 0 },
+                sharedGroups: writeSharedGroups(data.sharedGroups),
+                primaryGroup: writePrimaryGroup(data.primaryGroup ?? 0),
                 sortType: 0,
             },
         });

package/dist/esm/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>;
 }
 /**

package/dist/esm/resources/navigation-resource.js

@@ -1,3 +1,4 @@
+import { readPrimaryGroup, readSharedGroups, writePrimaryGroup, writeSharedGroups, assertGroupsValid } from '../utils.js';
 /** Maps SDK type codes to API type codes */
 const SDK_TO_API = {
     'a-to-z': 'a2z',
@@ -985,6 +986,8 @@ export class NavigationObject {
         this.enabled = raw.isEnabled;
         this.cachingEnabled = raw.isCachingEnabled;
         this.previewEnabled = raw.isPreviewModeEnabled;
+        this.primaryGroup = readPrimaryGroup(raw.primaryGroup);
+        this.sharedGroups = readSharedGroups(raw.sharedGroups);
         // Convert properties to camelCase keys with string values
         const originalKeys = [];
         const rawCamelProps = {};
@@ -1000,6 +1003,7 @@ export class NavigationObject {
     }
     /** Persists current property values to the server via PUT. */
     async save() {
+        assertGroupsValid(this.primaryGroup, this.sharedGroups);
         // Apply type-aware write transformation (coerce back to strings, derive hidden fields)
         const camelStringProps = transformPropertiesWrite(this.type, this.properties);
         // Rebuild properties in API format
@@ -1019,6 +1023,8 @@ export class NavigationObject {
             isEnabled: this.enabled,
             isCachingEnabled: this.cachingEnabled,
             isPreviewModeEnabled: this.previewEnabled,
+            primaryGroup: writePrimaryGroup(this.primaryGroup),
+            sharedGroups: writeSharedGroups(this.sharedGroups),
             properties: apiProperties,
         };
         await this._httpClient.request({
@@ -1235,6 +1241,7 @@ export class NavigationResource {
             throw new Error('Navigation object type is required');
         if (!NAVIGATION_TYPE_NAMES[data.type])
             throw new Error(`Unknown navigation type "${data.type}"`);
+        assertGroupsValid(data.primaryGroup ?? 0, data.sharedGroups);
         const apiType = SDK_TO_API[data.type];
         const properties = await this.buildProperties(data.type, (data.properties ?? {}));
         const body = {
@@ -1244,8 +1251,8 @@ export class NavigationResource {
             name: data.name,
             description: data.description ?? '',
             navigationType: apiType,
-            sharedGroups: [],
-            primaryGroup: { id: 0 },
+            sharedGroups: writeSharedGroups(data.sharedGroups),
+            primaryGroup: writePrimaryGroup(data.primaryGroup ?? 0),
             properties,
         };
         // CSS Selector quirk: requires "section-name": "on" at the top level
@@ -1289,6 +1296,10 @@ export class NavigationResource {
             nav.previewEnabled = data.previewEnabled;
         if (data.cachingEnabled !== undefined)
             nav.cachingEnabled = data.cachingEnabled;
+        if (data.primaryGroup !== undefined)
+            nav.primaryGroup = data.primaryGroup;
+        if (data.sharedGroups !== undefined)
+            nav.sharedGroups = data.sharedGroups;
         // Merge properties rather than replace — callers pass only what changes
         if (data.properties !== undefined) {
             nav.properties = {

package/dist/esm/resources/page-layout-resource.d.ts

@@ -1,4 +1,5 @@
 import { HttpClient } from '../http-client.js';
+import { RawPrimaryGroup } from '../utils.js';
 /** Raw page layout detail from GET /pageLayout/{id} */
 interface RawPageLayoutDetail {
     id: number;
@@ -10,6 +11,10 @@ interface RawPageLayoutDetail {
     fileExtension?: string;
     syntaxType?: number;
     layoutProcessor?: number;
+    primaryGroup?: RawPrimaryGroup;
+    sharedGroups?: Array<{
+        id: number;
+    }>;
     [key: string]: unknown;
 }
 /** A page layout summary returned from list() */
@@ -28,6 +33,10 @@ export declare class PageLayout {
     fileExtension: string;
     syntax: string;
     processor: string;
+    /** Owning group ID. 0 = no primary group (Global). */
+    primaryGroup: number;
+    /** Group IDs this page layout is shared with. */
+    sharedGroups: number[];
     private readonly _httpClient;
     private _rawData;
     private _syntaxMap;
@@ -63,6 +72,8 @@ export declare class PageLayoutResource {
         fileExtension?: string;
         syntax?: string;
         processor?: string;
+        primaryGroup?: number;
+        sharedGroups?: number[];
     }): Promise<PageLayout>;
     /** Creates a new page layout. */
     create(data: {

package/dist/esm/resources/page-layout-resource.js

@@ -1,4 +1,4 @@
-import { decodeHtmlEntities, DEFAULT_CACHE_TTL, getCacheEpoch } from '../utils.js';
+import { decodeHtmlEntities, DEFAULT_CACHE_TTL, getCacheEpoch, readPrimaryGroup, readSharedGroups, writePrimaryGroup, writeSharedGroups, assertGroupsValid } from '../utils.js';
 /** Friendly processor keys mapped to API names for page layouts */
 const PAGE_PROCESSOR_MAP = {
     't4-tags': 'T4 Tag Page',
@@ -19,6 +19,8 @@ export class PageLayout {
         const procName = processorMap.get(raw.layoutProcessor ?? 0) ?? '';
         const procEntry = Object.entries(PAGE_PROCESSOR_MAP).find(([, apiName]) => apiName === procName);
         this.processor = procEntry ? procEntry[0] : procName || `unknown (${raw.layoutProcessor})`;
+        this.primaryGroup = readPrimaryGroup(raw.primaryGroup);
+        this.sharedGroups = readSharedGroups(raw.sharedGroups);
         Object.defineProperty(this, '_httpClient', { value: httpClient, enumerable: false });
         Object.defineProperty(this, '_rawData', { value: raw, enumerable: false, writable: true });
         Object.defineProperty(this, '_syntaxMap', { value: syntaxMap, enumerable: false });
@@ -26,6 +28,7 @@ export class PageLayout {
     }
     /** Persists current property values to the server via PUT. */
     async save() {
+        assertGroupsValid(this.primaryGroup, this.sharedGroups);
         // Resolve syntax name to ID
         let syntaxId = this._rawData.syntaxType;
         if (this._syntaxMap) {
@@ -50,6 +53,8 @@ export class PageLayout {
             fileExtension: this.fileExtension,
             syntaxType: String(syntaxId),
             layoutProcessor: String(processorId),
+            primaryGroup: writePrimaryGroup(this.primaryGroup),
+            sharedGroups: writeSharedGroups(this.sharedGroups),
         };
         await this._httpClient.request({
             method: 'PUT',
@@ -132,6 +137,10 @@ export class PageLayoutResource {
             layout.syntax = data.syntax;
         if (data.processor !== undefined)
             layout.processor = data.processor;
+        if (data.primaryGroup !== undefined)
+            layout.primaryGroup = data.primaryGroup;
+        if (data.sharedGroups !== undefined)
+            layout.sharedGroups = data.sharedGroups;
         await layout.save();
         return layout;
     }
@@ -139,6 +148,7 @@ export class PageLayoutResource {
     async create(data) {
         if (!data.name?.trim())
             throw new Error('Page layout name is required');
+        assertGroupsValid(data.primaryGroup ?? 0, data.sharedGroups);
         const [syntaxMap, processorMap] = await Promise.all([
             this.getSyntaxMap(),
             this.getProcessorMap(),
@@ -192,8 +202,8 @@ export class PageLayoutResource {
                 fileExtension: extensionValue,
                 syntaxType: syntaxId,
                 layoutProcessor: processorId,
-                sharedGroups: (data.sharedGroups ?? []).map((id) => ({ id })),
-                primaryGroup: { id: data.primaryGroup ?? null },
+                sharedGroups: writeSharedGroups(data.sharedGroups),
+                primaryGroup: writePrimaryGroup(data.primaryGroup ?? 0),
             },
         });
         return new PageLayout(raw, this.httpClient, syntaxMap, processorMap);

package/dist/esm/section-ref.d.ts

@@ -3,6 +3,7 @@ import { LanguageOption, SectionChannel, Owner, AddSectionData } from './types.j
 import { ContentResource } from './resources/content-resource.js';
 import { SectionItem } from './models/section-item.js';
 import { MediaCreateFn } from './element-resolver.js';
+import { ContentCache } from './content-cache.js';
 /** A node in the section hierarchy tree */
 export interface SectionTreeNode {
     id: number;
@@ -23,7 +24,8 @@ export declare class SectionRef {
     private readonly sectionId;
     private readonly defaultLanguage;
     private readonly mediaCreateFn;
-    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);
     /** Returns a mutable section object. Modify properties and call save() to persist. */
     get(options?: LanguageOption): Promise<SectionItem>;
     /** Returns the list of channels associated with this section. */

package/dist/esm/section-ref.js

@@ -53,12 +53,13 @@ async function resolveMetaDataTypeId(httpClient, sectionMetaDataType) {
  * child section creation, and deletion — all from a single entry point.
  */
 export class SectionRef {
-    constructor(httpClient, sectionId, defaultLanguage, mediaCreateFn) {
+    constructor(httpClient, sectionId, defaultLanguage, mediaCreateFn, cache) {
         this.httpClient = httpClient;
         this.sectionId = sectionId;
         this.defaultLanguage = defaultLanguage;
         this.mediaCreateFn = mediaCreateFn ?? null;
-        this.content = new ContentResource(httpClient, sectionId, defaultLanguage, this.mediaCreateFn);
+        this.cache = cache;
+        this.content = new ContentResource(httpClient, sectionId, defaultLanguage, this.mediaCreateFn, this.cache);
     }
     // ── Section metadata ──
     /** Returns a mutable section object. Modify properties and call save() to persist. */
@@ -73,7 +74,7 @@ export class SectionRef {
         const meta = raw.metaData;
         if (meta?.enabled && meta.id) {
             try {
-                const metaContent = new ContentResource(this.httpClient, this.sectionId, this.defaultLanguage, this.mediaCreateFn);
+                const metaContent = new ContentResource(this.httpClient, this.sectionId, this.defaultLanguage, this.mediaCreateFn, this.cache);
                 const item = await metaContent.get(meta.id, { language });
                 customFields = stripNameField(item.fields ?? null);
             }
@@ -641,7 +642,7 @@ export class SectionRef {
         if (metaContentTypeId) {
             // Use a ContentResource on the new section to get full element resolution
             // (list values, SS links, file uploads, etc.)
-            const metadataContentResource = new ContentResource(this.httpClient, newSectionId, this.defaultLanguage, this.mediaCreateFn);
+            const metadataContentResource = new ContentResource(this.httpClient, newSectionId, this.defaultLanguage, this.mediaCreateFn, this.cache);
             // Create the metadata content item (ContentResource.create handles the full body)
             const metaItem = await metadataContentResource.create({
                 type: metaContentTypeId,
@@ -730,7 +731,7 @@ export class SectionRef {
             if (!metaDataTypeId) {
                 throw new Error('Cannot update customFields: no Section Meta Data content type is configured on this T4 instance');
             }
-            const contentResource = new ContentResource(this.httpClient, this.sectionId, this.defaultLanguage, this.mediaCreateFn);
+            const contentResource = new ContentResource(this.httpClient, this.sectionId, this.defaultLanguage, this.mediaCreateFn, this.cache);
             const metaContentId = meta?.id ?? 0;
             if (metaContentId > 0) {
                 await contentResource.update(metaContentId, { fields: data.customFields });

package/dist/esm/t4-client.d.ts

@@ -35,6 +35,7 @@ export declare class T4Client {
     private readonly httpClient;
     private readonly defaultLanguage;
     private readonly mediaCreateFn;
+    private readonly contentCache;
     constructor(config: T4ClientConfig);
     /**
      * Returns a section reference scoped to the given section ID.