@terminalfour/terminalfour-js 1.0.3 → 1.1.1

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);
@@ -56,9 +56,11 @@ class List {
     }
     /** Persists current property values to the server via PUT. */
     async save() {
+        (0, utils_js_2.assertRequired)(this.name, 'List name');
         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 +75,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 +151,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 +170,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/media-resource.js

@@ -53,10 +53,17 @@ class MediaResource {
      * Returns the new media item.
      */
     async create(data) {
-        if (!data.name?.trim())
-            throw new Error('Media name is required');
+        (0, utils_js_1.assertRequired)(data.name, 'Media name');
         if (!data.category)
             throw new Error('Media category is required');
+        // A media item is meaningless without its file/binary. Guard the common
+        // empty cases: missing, or an empty { file } wrapper.
+        const fileValue = data.file && typeof data.file === 'object' && !(data.file instanceof Blob) && 'file' in data.file
+            ? data.file.file
+            : data.file;
+        if (fileValue === undefined || fileValue === null || fileValue === '') {
+            throw new Error('Media file is required');
+        }
         const language = data.language ?? 'smxx';
         const filename = (0, utils_js_1.deriveFilename)(data.file);
         const ext = getExtension(filename);

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

@@ -68,6 +68,7 @@ class MediaType {
     }
     /** Persists current property values to the server via PUT. */
     async save() {
+        (0, utils_js_1.assertRequired)(this.name, 'Media type name');
         // Sync defaultLayout into the layouts array
         if (this.defaultLayout) {
             for (const layout of this.layouts) {

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

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

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.NavigationResource = exports.NavigationObject = exports.NAVIGATION_TYPE_NAMES = void 0;
+const utils_js_1 = require("../utils.js");
 /** Maps SDK type codes to API type codes */
 const SDK_TO_API = {
     'a-to-z': 'a2z',
@@ -988,6 +989,8 @@ class NavigationObject {
         this.enabled = raw.isEnabled;
         this.cachingEnabled = raw.isCachingEnabled;
         this.previewEnabled = raw.isPreviewModeEnabled;
+        this.primaryGroup = (0, utils_js_1.readPrimaryGroup)(raw.primaryGroup);
+        this.sharedGroups = (0, utils_js_1.readSharedGroups)(raw.sharedGroups);
         // Convert properties to camelCase keys with string values
         const originalKeys = [];
         const rawCamelProps = {};
@@ -1003,6 +1006,8 @@ class NavigationObject {
     }
     /** Persists current property values to the server via PUT. */
     async save() {
+        (0, utils_js_1.assertRequired)(this.name, 'Navigation object name');
+        (0, utils_js_1.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
@@ -1022,6 +1027,8 @@ class NavigationObject {
             isEnabled: this.enabled,
             isCachingEnabled: this.cachingEnabled,
             isPreviewModeEnabled: this.previewEnabled,
+            primaryGroup: (0, utils_js_1.writePrimaryGroup)(this.primaryGroup),
+            sharedGroups: (0, utils_js_1.writeSharedGroups)(this.sharedGroups),
             properties: apiProperties,
         };
         await this._httpClient.request({
@@ -1239,6 +1246,7 @@ class NavigationResource {
             throw new Error('Navigation object type is required');
         if (!exports.NAVIGATION_TYPE_NAMES[data.type])
             throw new Error(`Unknown navigation type "${data.type}"`);
+        (0, utils_js_1.assertGroupsValid)(data.primaryGroup ?? 0, data.sharedGroups);
         const apiType = SDK_TO_API[data.type];
         const properties = await this.buildProperties(data.type, (data.properties ?? {}));
         const body = {
@@ -1248,8 +1256,8 @@ class NavigationResource {
             name: data.name,
             description: data.description ?? '',
             navigationType: apiType,
-            sharedGroups: [],
-            primaryGroup: { id: 0 },
+            sharedGroups: (0, utils_js_1.writeSharedGroups)(data.sharedGroups),
+            primaryGroup: (0, utils_js_1.writePrimaryGroup)(data.primaryGroup ?? 0),
             properties,
         };
         // CSS Selector quirk: requires "section-name": "on" at the top level
@@ -1293,6 +1301,10 @@ 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/cjs/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/cjs/resources/page-layout-resource.js

@@ -22,6 +22,8 @@ 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 = (0, utils_js_1.readPrimaryGroup)(raw.primaryGroup);
+        this.sharedGroups = (0, utils_js_1.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 });
@@ -29,6 +31,8 @@ class PageLayout {
     }
     /** Persists current property values to the server via PUT. */
     async save() {
+        (0, utils_js_1.assertRequired)(this.name, 'Page layout name');
+        (0, utils_js_1.assertGroupsValid)(this.primaryGroup, this.sharedGroups);
         // Resolve syntax name to ID
         let syntaxId = this._rawData.syntaxType;
         if (this._syntaxMap) {
@@ -53,6 +57,8 @@ class PageLayout {
             fileExtension: this.fileExtension,
             syntaxType: String(syntaxId),
             layoutProcessor: String(processorId),
+            primaryGroup: (0, utils_js_1.writePrimaryGroup)(this.primaryGroup),
+            sharedGroups: (0, utils_js_1.writeSharedGroups)(this.sharedGroups),
         };
         await this._httpClient.request({
             method: 'PUT',
@@ -136,6 +142,10 @@ 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;
     }
@@ -143,6 +153,7 @@ class PageLayoutResource {
     async create(data) {
         if (!data.name?.trim())
             throw new Error('Page layout name is required');
+        (0, utils_js_1.assertGroupsValid)(data.primaryGroup ?? 0, data.sharedGroups);
         const [syntaxMap, processorMap] = await Promise.all([
             this.getSyntaxMap(),
             this.getProcessorMap(),
@@ -196,8 +207,8 @@ class PageLayoutResource {
                 fileExtension: extensionValue,
                 syntaxType: syntaxId,
                 layoutProcessor: processorId,
-                sharedGroups: (data.sharedGroups ?? []).map((id) => ({ id })),
-                primaryGroup: { id: data.primaryGroup ?? null },
+                sharedGroups: (0, utils_js_1.writeSharedGroups)(data.sharedGroups),
+                primaryGroup: (0, utils_js_1.writePrimaryGroup)(data.primaryGroup ?? 0),
             },
         });
         return new PageLayout(raw, this.httpClient, syntaxMap, processorMap);

package/dist/cjs/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/cjs/section-ref.js

@@ -57,12 +57,13 @@ async function resolveMetaDataTypeId(httpClient, sectionMetaDataType) {
  * child section creation, and deletion — all from a single entry point.
  */
 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 content_resource_js_1.ContentResource(httpClient, sectionId, defaultLanguage, this.mediaCreateFn);
+        this.cache = cache;
+        this.content = new content_resource_js_1.ContentResource(httpClient, sectionId, defaultLanguage, this.mediaCreateFn, this.cache);
     }
     // ── Section metadata ──
     /** Returns a mutable section object. Modify properties and call save() to persist. */
@@ -77,7 +78,7 @@ class SectionRef {
         const meta = raw.metaData;
         if (meta?.enabled && meta.id) {
             try {
-                const metaContent = new content_resource_js_1.ContentResource(this.httpClient, this.sectionId, this.defaultLanguage, this.mediaCreateFn);
+                const metaContent = new content_resource_js_1.ContentResource(this.httpClient, this.sectionId, this.defaultLanguage, this.mediaCreateFn, this.cache);
                 const item = await metaContent.get(meta.id, { language });
                 customFields = stripNameField(item.fields ?? null);
             }
@@ -567,6 +568,7 @@ class SectionRef {
      * If `data.customFields` is provided, creates and saves section metadata content.
      */
     async addSection(data, options) {
+        (0, utils_js_1.assertRequired)(data.name, 'Section name');
         const language = (0, utils_js_1.resolveLanguage)(options?.language, this.defaultLanguage);
         // Fetch this section's details to inherit config
         const parentSection = await this.httpClient.request({
@@ -645,7 +647,7 @@ 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 content_resource_js_1.ContentResource(this.httpClient, newSectionId, this.defaultLanguage, this.mediaCreateFn);
+            const metadataContentResource = new content_resource_js_1.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,
@@ -711,6 +713,10 @@ class SectionRef {
      * Returns the updated SectionItem.
      */
     async update(data, options) {
+        // This path PUTs directly (it does not go through SectionItem.save()), so
+        // guard the name here. Present-only: omitting name is valid (e.g. delete()
+        // calls update({ status: 'inactive' })), but setting it blank is not.
+        (0, utils_js_1.assertNotEmptyIfPresent)(data.name, 'Section name');
         const language = (0, utils_js_1.resolveLanguage)(options?.language, this.defaultLanguage);
         const section = await this.httpClient.request({
             method: 'GET',
@@ -734,7 +740,7 @@ 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 content_resource_js_1.ContentResource(this.httpClient, this.sectionId, this.defaultLanguage, this.mediaCreateFn);
+            const contentResource = new content_resource_js_1.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/cjs/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.

package/dist/cjs/t4-client.js

@@ -16,6 +16,7 @@ const page_layout_resource_js_1 = require("./resources/page-layout-resource.js")
 const media_type_resource_js_1 = require("./resources/media-type-resource.js");
 const navigation_resource_js_1 = require("./resources/navigation-resource.js");
 const handlebars_js_1 = require("./handlebars.js");
+const content_cache_js_1 = require("./content-cache.js");
 const utils_js_1 = require("./utils.js");
 /**
  * Main entry point for the T4 SDK.
@@ -57,12 +58,16 @@ class T4Client {
             });
             return item.id;
         };
+        // Shared content caches (element TypeRegistry, content type templates).
+        // Threaded into every SectionRef/ContentResource so hierarchy traversal
+        // doesn't re-fetch instance-wide data on each t4.section(id) call.
+        this.contentCache = new content_cache_js_1.ContentCache(this.httpClient, this.defaultLanguage, this.mediaCreateFn);
     }
     /**
      * Returns a section reference scoped to the given section ID.
      */
     section(id) {
-        return new section_ref_js_1.SectionRef(this.httpClient, id, this.defaultLanguage, this.mediaCreateFn);
+        return new section_ref_js_1.SectionRef(this.httpClient, id, this.defaultLanguage, this.mediaCreateFn, this.contentCache);
     }
     /**
      * Returns a media category reference scoped to the given category ID.

package/dist/cjs/utils.d.ts

@@ -68,6 +68,62 @@ export declare function flattenGroups(groups: Array<{
     name: string;
     groupChildren?: unknown[];
 }>, map?: Map<number, string>): Map<number, string>;
+/**
+ * Group/visibility mapping helpers.
+ *
+ * The T4 API represents an asset's owning group as `primaryGroup` (an object,
+ * where the id may be direct or nested under `group`) and its shared groups as
+ * `sharedGroups` (an array of `{ id }`). The SDK exposes these as a plain
+ * `primaryGroup: number` (0 = none) and `sharedGroups: number[]`. These helpers
+ * centralise the read/write mapping so content types, lists, page layouts, and
+ * navigation objects all handle groups identically.
+ */
+/** Raw shape of the API `primaryGroup` field. */
+export interface RawPrimaryGroup {
+    id: number | null;
+    group?: {
+        id: number;
+    };
+}
+/** Reads the API `primaryGroup` object into a plain group id (0 = none). */
+export declare function readPrimaryGroup(raw?: RawPrimaryGroup): number;
+/** Reads the API `sharedGroups` array into a plain array of group ids. */
+export declare function readSharedGroups(raw?: Array<{
+    id: number;
+}>): number[];
+/** Writes a plain group id back to the API `primaryGroup` shape (0/falsy = none). */
+export declare function writePrimaryGroup(id: number): {
+    id: number | null;
+};
+/** Writes a plain array of group ids back to the API `sharedGroups` shape. */
+export declare function writeSharedGroups(ids?: number[]): Array<{
+    id: number;
+}>;
+/**
+ * Validates that group/visibility values are acceptable to the T4 API before a
+ * write. The API returns an opaque 500 when `sharedGroups` contains the same id
+ * as `primaryGroup` (a group cannot be both the owner and a shared group), so we
+ * catch it here with a clear message. A `primaryGroup` of 0 means "no owning
+ * group" and is never a conflict.
+ */
+export declare function assertGroupsValid(primaryGroup: number, sharedGroups?: number[]): void;
+/**
+ * Asserts that a required string value is present and not blank.
+ *
+ * Use on create paths where the field must always be provided. Throws
+ * `"<Label> is required"` when the value is missing, empty, or whitespace-only.
+ * Prevents opaque API 500s from malformed requests missing a required field.
+ */
+export declare function assertRequired(value: string | null | undefined, label: string): void;
+/**
+ * Asserts that a value, *if provided*, is not blank.
+ *
+ * Use on update paths where a field is optional (omitting it leaves the
+ * current value unchanged) but explicitly setting it to an empty or
+ * whitespace-only string is invalid. `undefined` passes (means "no change");
+ * `''` or whitespace throws `"<Label> cannot be empty"`.
+ */
+export declare function assertNotEmptyIfPresent(value: string | null | undefined, label: string): void;
 /** Accepted file input: a file path, URL, Blob, ReadableStream, or { file, filename } object */
 export type FileInput = string | Blob | NodeJS.ReadableStream | {
     file: string | Blob | NodeJS.ReadableStream;

package/dist/cjs/utils.js

@@ -42,6 +42,13 @@ exports.parseFileSize = parseFileSize;
 exports.parseElementKey = parseElementKey;
 exports.mapStatus = mapStatus;
 exports.flattenGroups = flattenGroups;
+exports.readPrimaryGroup = readPrimaryGroup;
+exports.readSharedGroups = readSharedGroups;
+exports.writePrimaryGroup = writePrimaryGroup;
+exports.writeSharedGroups = writeSharedGroups;
+exports.assertGroupsValid = assertGroupsValid;
+exports.assertRequired = assertRequired;
+exports.assertNotEmptyIfPresent = assertNotEmptyIfPresent;
 exports.resolveFileToBlob = resolveFileToBlob;
 exports.deriveFilename = deriveFilename;
 exports.debugWarn = debugWarn;
@@ -221,6 +228,65 @@ function flattenGroups(groups, map = new Map()) {
     }
     return map;
 }
+/** Reads the API `primaryGroup` object into a plain group id (0 = none). */
+function readPrimaryGroup(raw) {
+    return raw?.group?.id ?? raw?.id ?? 0;
+}
+/** Reads the API `sharedGroups` array into a plain array of group ids. */
+function readSharedGroups(raw) {
+    return (raw ?? []).map((g) => g.id);
+}
+/** Writes a plain group id back to the API `primaryGroup` shape (0/falsy = none). */
+function writePrimaryGroup(id) {
+    return { id: id || null };
+}
+/** Writes a plain array of group ids back to the API `sharedGroups` shape. */
+function writeSharedGroups(ids) {
+    return (ids ?? []).map((id) => ({ id }));
+}
+/**
+ * Validates that group/visibility values are acceptable to the T4 API before a
+ * write. The API returns an opaque 500 when `sharedGroups` contains the same id
+ * as `primaryGroup` (a group cannot be both the owner and a shared group), so we
+ * catch it here with a clear message. A `primaryGroup` of 0 means "no owning
+ * group" and is never a conflict.
+ */
+function assertGroupsValid(primaryGroup, sharedGroups) {
+    if (!primaryGroup)
+        return;
+    if ((sharedGroups ?? []).includes(primaryGroup)) {
+        throw new Error(`sharedGroups cannot contain the primaryGroup id (${primaryGroup}). ` +
+            'A group cannot be both the primary (owning) group and a shared group. ' +
+            'Remove it from sharedGroups or choose a different primaryGroup.');
+    }
+}
+/**
+ * Asserts that a required string value is present and not blank.
+ *
+ * Use on create paths where the field must always be provided. Throws
+ * `"<Label> is required"` when the value is missing, empty, or whitespace-only.
+ * Prevents opaque API 500s from malformed requests missing a required field.
+ */
+function assertRequired(value, label) {
+    if (!value || !value.trim()) {
+        throw new Error(`${label} is required`);
+    }
+}
+/**
+ * Asserts that a value, *if provided*, is not blank.
+ *
+ * Use on update paths where a field is optional (omitting it leaves the
+ * current value unchanged) but explicitly setting it to an empty or
+ * whitespace-only string is invalid. `undefined` passes (means "no change");
+ * `''` or whitespace throws `"<Label> cannot be empty"`.
+ */
+function assertNotEmptyIfPresent(value, label) {
+    if (value === undefined || value === null)
+        return;
+    if (!value.trim()) {
+        throw new Error(`${label} cannot be empty`);
+    }
+}
 /**
  * Resolves a file input (path, URL, Blob, or ReadableStream) to a Blob.
  */

package/dist/esm/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/esm/content-cache.js

@@ -0,0 +1,38 @@
+import { TypeRegistry } from './type-registry.js';
+import { ElementResolver } 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 class ContentCache {
+    constructor(httpClient, defaultLanguage, mediaCreateFn) {
+        /** `GET /content/type/{ct}/{section}` responses, keyed by `"{ct}:{section}"`. */
+        this.sectionTemplates = new TtlMap();
+        /** `GET /contenttype/{id}` responses, keyed by content type ID. */
+        this.contentTypeDefinitions = new TtlMap();
+        this.typeRegistry = new TypeRegistry(httpClient);
+        this.resolver = new ElementResolver(httpClient, defaultLanguage, this.typeRegistry, mediaCreateFn);
+    }
+}
+//# sourceMappingURL=content-cache.js.map

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