@terminalfour/terminalfour-js 1.0.3 → 1.1.1

package/dist/esm/element-resolver.js

@@ -79,11 +79,87 @@ export 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/esm/handlebars.js

@@ -1,4 +1,4 @@
-import { DEFAULT_CACHE_TTL, getCacheEpoch } from './utils.js';
+import { DEFAULT_CACHE_TTL, getCacheEpoch, assertRequired } from './utils.js';
 /**
  * A mutable Handlebars item (helper or partial).
  * Modify `name` and/or `code`, then call `save()` to persist.
@@ -22,6 +22,7 @@ export class HandlebarsItem {
      * Always saves with approved status.
      */
     async save() {
+        assertRequired(this.name, 'Name');
         // Update elements with current name and code
         const elements = { ...this._rawDTO.elements };
         for (const key of Object.keys(elements)) {

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

@@ -1,4 +1,4 @@
-import { formatFileSize, parseElementKey, mapStatus, flattenGroups, STATUS_CODES, AUTH_LEVEL_MAP, debugWarn, DEFAULT_CACHE_TTL, getCacheEpoch } from '../utils.js';
+import { formatFileSize, parseElementKey, mapStatus, flattenGroups, STATUS_CODES, AUTH_LEVEL_MAP, debugWarn, DEFAULT_CACHE_TTL, getCacheEpoch, assertRequired } from '../utils.js';
 /** Symbol used to restrict _init() access to the factory function in this module */
 const INIT = Symbol('ContentItem.init');
 /**
@@ -497,6 +497,7 @@ export class ContentItem {
      * save and approve in one step.
      */
     async save() {
+        assertRequired(this.name, 'Content name');
         // Start from the original raw elements (correct API format)
         const rawElements = { ...this._rawDTO.elements };
         // Re-resolve dirty fields through the ElementResolver so friendly values
@@ -526,7 +527,19 @@ export 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/esm/models/media-category-item.js

@@ -1,3 +1,4 @@
+import { assertRequired } from '../utils.js';
 /**
  * A mutable media category object. Modify properties and call save() to persist.
  */
@@ -14,6 +15,7 @@ export class MediaCategoryItem {
     }
     /** Persists current property values to the server via PUT. */
     async save() {
+        assertRequired(this.name, 'Media category name');
         const updated = {
             ...this._rawData,
             name: this.name,

package/dist/esm/models/media-item.js

@@ -1,4 +1,4 @@
-import { formatFileSize, parseElementKey, STATUS_MAP, resolveFileToBlob, deriveFilename } from '../utils.js';
+import { formatFileSize, parseElementKey, STATUS_MAP, resolveFileToBlob, deriveFilename, assertRequired } from '../utils.js';
 /** Extension → syntax type mapping for non-binary media */
 const EXTENSION_SYNTAX_MAP = {
     js: 1,
@@ -77,6 +77,7 @@ export class MediaItem {
      * If `content` has changed on non-binary media, the version is bumped.
      */
     async save() {
+        assertRequired(this.name, 'Media name');
         const categoryId = this.categories[0];
         if (!categoryId) {
             throw new Error('Cannot save media item — no category assigned.');

package/dist/esm/models/section-item.js

@@ -1,4 +1,4 @@
-import { mapStatus, STATUS_CODES } from '../utils.js';
+import { mapStatus, STATUS_CODES, assertRequired } from '../utils.js';
 import { ContentResource } from '../resources/content-resource.js';
 /**
  * A mutable section object. Modify properties and call save() to persist.
@@ -31,6 +31,7 @@ export class SectionItem {
     }
     /** Persists current property values to the server via PUT. */
     async save() {
+        assertRequired(this.name, 'Section name');
         const statusCode = STATUS_CODES[this.status] ?? Number(this._rawData.status) ?? 0;
         const updated = {
             ...this._rawData,

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

@@ -1,35 +1,42 @@
-import { resolveLanguage, toTimestamp, STATUS_CODES, TtlMap } from '../utils.js';
+import { resolveLanguage, toTimestamp, STATUS_CODES, assertRequired, assertNotEmptyIfPresent } 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) {
@@ -140,6 +97,7 @@ export class ContentResource {
     }
     /** Creates a new content item in this section. */
     async create(data, options) {
+        assertRequired(data.name, 'Content name');
         const language = resolveLanguage(options?.language, this.defaultLanguage);
         const template = await this.getTemplate(data.type);
         const contentId = -Math.floor(Math.random() * 1000000);
@@ -175,6 +133,7 @@ export class ContentResource {
     }
     /** Updates an existing content item's fields. */
     async update(id, data, options) {
+        assertNotEmptyIfPresent(data.name, 'Content name');
         const language = resolveLanguage(options?.language, this.defaultLanguage);
         // 1. Fetch the existing content (full body needed for the POST)
         const existing = await this.httpClient.request({

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[];

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, assertRequired, assertNotEmptyIfPresent } 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,
         },
@@ -245,6 +245,7 @@ export class ContentType {
                     return new Layout(raw, httpClient, contentTypeId, layoutElements, fetchLayouts, resolveSyntaxId, resolveProcessorId, resolveExtension);
                 },
                 update: async (layoutName, updateData) => {
+                    assertNotEmptyIfPresent(updateData.name, 'Layout name');
                     const all = await fetchLayouts();
                     const match = all.find((l) => l.name === layoutName);
                     if (!match)
@@ -285,6 +286,7 @@ export class ContentType {
                     return new Layout(response, httpClient, contentTypeId, layoutElements, fetchLayouts, resolveSyntaxId, resolveProcessorId, resolveExtension);
                 },
                 create: async (createData) => {
+                    assertRequired(createData.name, 'Layout name');
                     // Check name uniqueness
                     const existing = await fetchLayouts();
                     if (existing.some((l) => l.name === createData.name)) {
@@ -586,6 +588,8 @@ export class ContentType {
     }
     /** Persists current property values to the server via PUT. */
     async save() {
+        assertRequired(this.name, 'Content type name');
+        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 +657,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 +683,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();
@@ -862,6 +870,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) {
@@ -871,6 +882,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) {
@@ -989,11 +1001,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/group-resource.js

@@ -1,4 +1,4 @@
-import { AUTH_LEVEL_MAP } from '../utils.js';
+import { AUTH_LEVEL_MAP, assertRequired } from '../utils.js';
 /** A mutable group object. Modify properties and call save() to persist. */
 export class Group {
     constructor(raw, httpClient) {
@@ -40,6 +40,7 @@ export class Group {
     }
     /** Persists current property values to the server via PUT. */
     async save() {
+        assertRequired(this.name, 'Group name');
         // Start from existing raw members
         let rawMembers = [...(this._rawData.members ?? [])];
         // Remove members

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, assertRequired } 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);
@@ -53,9 +53,11 @@ export class List {
     }
     /** Persists current property values to the server via PUT. */
     async save() {
+        assertRequired(this.name, 'List name');
         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 +72,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 +147,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 +166,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/media-resource.js

@@ -1,5 +1,5 @@
 import { MediaItem } from '../models/media-item.js';
-import { resolveLanguage, resolveFileToBlob, deriveFilename, DEFAULT_CACHE_TTL, getCacheEpoch } from '../utils.js';
+import { resolveLanguage, resolveFileToBlob, deriveFilename, DEFAULT_CACHE_TTL, getCacheEpoch, assertRequired } from '../utils.js';
 /** Extension → syntax type mapping for non-binary media */
 const EXTENSION_SYNTAX_MAP = {
     js: 1,
@@ -50,10 +50,17 @@ export class MediaResource {
      * Returns the new media item.
      */
     async create(data) {
-        if (!data.name?.trim())
-            throw new Error('Media name is required');
+        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 = deriveFilename(data.file);
         const ext = getExtension(filename);

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

@@ -1,4 +1,4 @@
-import { formatFileSize, parseFileSize } from '../utils.js';
+import { formatFileSize, parseFileSize, assertRequired } from '../utils.js';
 function mapFromDetail(raw) {
     const layouts = (raw.formatters ?? []).map((f) => ({
         name: f.mediaLayout,
@@ -65,6 +65,7 @@ export class MediaType {
     }
     /** Persists current property values to the server via PUT. */
     async save() {
+        assertRequired(this.name, 'Media type name');
         // Sync defaultLayout into the layouts array
         if (this.defaultLayout) {
             for (const layout of this.layouts) {