@terminalfour/terminalfour-js 1.1.0 → 1.1.1

package/dist/cjs/handlebars.js

@@ -25,6 +25,7 @@ class HandlebarsItem {
      * Always saves with approved status.
      */
     async save() {
+        (0, utils_js_1.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/cjs/models/content-item.js

@@ -502,6 +502,7 @@ class ContentItem {
      * save and approve in one step.
      */
     async save() {
+        (0, utils_js_1.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

package/dist/cjs/models/media-category-item.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.MediaCategoryItem = void 0;
+const utils_js_1 = require("../utils.js");
 /**
  * A mutable media category object. Modify properties and call save() to persist.
  */
@@ -17,6 +18,7 @@ class MediaCategoryItem {
     }
     /** Persists current property values to the server via PUT. */
     async save() {
+        (0, utils_js_1.assertRequired)(this.name, 'Media category name');
         const updated = {
             ...this._rawData,
             name: this.name,

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

@@ -80,6 +80,7 @@ class MediaItem {
      * If `content` has changed on non-binary media, the version is bumped.
      */
     async save() {
+        (0, utils_js_1.assertRequired)(this.name, 'Media name');
         const categoryId = this.categories[0];
         if (!categoryId) {
             throw new Error('Cannot save media item — no category assigned.');

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

@@ -34,6 +34,7 @@ class SectionItem {
     }
     /** Persists current property values to the server via PUT. */
     async save() {
+        (0, utils_js_1.assertRequired)(this.name, 'Section name');
         const statusCode = utils_js_1.STATUS_CODES[this.status] ?? Number(this._rawData.status) ?? 0;
         const updated = {
             ...this._rawData,

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

@@ -100,6 +100,7 @@ class ContentResource {
     }
     /** Creates a new content item in this section. */
     async create(data, options) {
+        (0, utils_js_1.assertRequired)(data.name, 'Content name');
         const language = (0, utils_js_1.resolveLanguage)(options?.language, this.defaultLanguage);
         const template = await this.getTemplate(data.type);
         const contentId = -Math.floor(Math.random() * 1000000);
@@ -135,6 +136,7 @@ class ContentResource {
     }
     /** Updates an existing content item's fields. */
     async update(id, data, options) {
+        (0, utils_js_1.assertNotEmptyIfPresent)(data.name, 'Content name');
         const language = (0, utils_js_1.resolveLanguage)(options?.language, this.defaultLanguage);
         // 1. Fetch the existing content (full body needed for the POST)
         const existing = await this.httpClient.request({

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

@@ -249,6 +249,7 @@ class ContentType {
                     return new Layout(raw, httpClient, contentTypeId, layoutElements, fetchLayouts, resolveSyntaxId, resolveProcessorId, resolveExtension);
                 },
                 update: async (layoutName, updateData) => {
+                    (0, utils_js_1.assertNotEmptyIfPresent)(updateData.name, 'Layout name');
                     const all = await fetchLayouts();
                     const match = all.find((l) => l.name === layoutName);
                     if (!match)
@@ -289,6 +290,7 @@ class ContentType {
                     return new Layout(response, httpClient, contentTypeId, layoutElements, fetchLayouts, resolveSyntaxId, resolveProcessorId, resolveExtension);
                 },
                 create: async (createData) => {
+                    (0, utils_js_1.assertRequired)(createData.name, 'Layout name');
                     // Check name uniqueness
                     const existing = await fetchLayouts();
                     if (existing.some((l) => l.name === createData.name)) {
@@ -590,6 +592,7 @@ class ContentType {
     }
     /** Persists current property values to the server via PUT. */
     async save() {
+        (0, utils_js_1.assertRequired)(this.name, 'Content type name');
         (0, utils_js_1.assertGroupsValid)(this.primaryGroup, this.sharedGroups);
         const authLevel = String(utils_js_1.AUTH_LEVEL_REVERSE[this.minUserLevel] ?? this._rawData.minAuthLevel ?? 2);
         // Sync field changes back to raw contentTypeElements

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

@@ -43,6 +43,7 @@ class Group {
     }
     /** Persists current property values to the server via PUT. */
     async save() {
+        (0, utils_js_1.assertRequired)(this.name, 'Group name');
         // Start from existing raw members
         let rawMembers = [...(this._rawData.members ?? [])];
         // Remove members

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

@@ -56,6 +56,7 @@ 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');
         }

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.js

@@ -1006,6 +1006,7 @@ 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);

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

@@ -31,6 +31,7 @@ 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;

package/dist/cjs/section-ref.js

@@ -568,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({
@@ -712,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',

package/dist/cjs/utils.d.ts

@@ -107,6 +107,23 @@ export declare function writeSharedGroups(ids?: number[]): Array<{
  * 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

@@ -47,6 +47,8 @@ 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;
@@ -258,6 +260,33 @@ function assertGroupsValid(primaryGroup, sharedGroups) {
             '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/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

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.js

@@ -1,4 +1,4 @@
-import { resolveLanguage, toTimestamp, STATUS_CODES } from '../utils.js';
+import { resolveLanguage, toTimestamp, STATUS_CODES, assertRequired, assertNotEmptyIfPresent } from '../utils.js';
 import { createContentItem } from '../models/content-item.js';
 import { ContentCache } from '../content-cache.js';
 /**
@@ -97,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);
@@ -132,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.js

@@ -1,4 +1,4 @@
-import { decodeHtmlEntities, AUTH_LEVEL_MAP, AUTH_LEVEL_REVERSE, debugWarn, DEFAULT_CACHE_TTL, getCacheEpoch, invalidateAllCaches, readPrimaryGroup, readSharedGroups, writePrimaryGroup, writeSharedGroups, assertGroupsValid } 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) {
@@ -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,7 @@ 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

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.js

@@ -1,5 +1,5 @@
 import { resolveLanguage } from '../utils.js';
-import { decodeHtmlEntities, readPrimaryGroup, readSharedGroups, writePrimaryGroup, writeSharedGroups, assertGroupsValid } 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) {
@@ -53,6 +53,7 @@ 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');
         }

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) {

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

@@ -1,4 +1,4 @@
-import { readPrimaryGroup, readSharedGroups, writePrimaryGroup, writeSharedGroups, assertGroupsValid } from '../utils.js';
+import { readPrimaryGroup, readSharedGroups, writePrimaryGroup, writeSharedGroups, assertGroupsValid, assertRequired } from '../utils.js';
 /** Maps SDK type codes to API type codes */
 const SDK_TO_API = {
     'a-to-z': 'a2z',
@@ -1003,6 +1003,7 @@ export class NavigationObject {
     }
     /** Persists current property values to the server via PUT. */
     async save() {
+        assertRequired(this.name, 'Navigation object name');
         assertGroupsValid(this.primaryGroup, this.sharedGroups);
         // Apply type-aware write transformation (coerce back to strings, derive hidden fields)
         const camelStringProps = transformPropertiesWrite(this.type, this.properties);

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

@@ -1,4 +1,4 @@
-import { decodeHtmlEntities, DEFAULT_CACHE_TTL, getCacheEpoch, readPrimaryGroup, readSharedGroups, writePrimaryGroup, writeSharedGroups, assertGroupsValid } from '../utils.js';
+import { decodeHtmlEntities, DEFAULT_CACHE_TTL, getCacheEpoch, readPrimaryGroup, readSharedGroups, writePrimaryGroup, writeSharedGroups, assertGroupsValid, assertRequired } from '../utils.js';
 /** Friendly processor keys mapped to API names for page layouts */
 const PAGE_PROCESSOR_MAP = {
     't4-tags': 'T4 Tag Page',
@@ -28,6 +28,7 @@ export class PageLayout {
     }
     /** Persists current property values to the server via PUT. */
     async save() {
+        assertRequired(this.name, 'Page layout name');
         assertGroupsValid(this.primaryGroup, this.sharedGroups);
         // Resolve syntax name to ID
         let syntaxId = this._rawData.syntaxType;

package/dist/esm/section-ref.js

@@ -1,4 +1,4 @@
-import { resolveLanguage, mapStatus, flattenGroups, STATUS_CODES, AUTH_LEVEL_MAP, debugWarn, DEFAULT_CACHE_TTL, getCacheEpoch } from './utils.js';
+import { resolveLanguage, mapStatus, flattenGroups, STATUS_CODES, AUTH_LEVEL_MAP, debugWarn, DEFAULT_CACHE_TTL, getCacheEpoch, assertRequired, assertNotEmptyIfPresent } from './utils.js';
 import { ContentResource } from './resources/content-resource.js';
 import { SectionItem } from './models/section-item.js';
 /** Per-client cache for meta tag definitions, keyed by HttpClient instance */
@@ -564,6 +564,7 @@ export class SectionRef {
      * If `data.customFields` is provided, creates and saves section metadata content.
      */
     async addSection(data, options) {
+        assertRequired(data.name, 'Section name');
         const language = resolveLanguage(options?.language, this.defaultLanguage);
         // Fetch this section's details to inherit config
         const parentSection = await this.httpClient.request({
@@ -708,6 +709,10 @@ export 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.
+        assertNotEmptyIfPresent(data.name, 'Section name');
         const language = resolveLanguage(options?.language, this.defaultLanguage);
         const section = await this.httpClient.request({
             method: 'GET',

package/dist/esm/utils.d.ts

@@ -107,6 +107,23 @@ export declare function writeSharedGroups(ids?: number[]): Array<{
  * 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/esm/utils.js

@@ -202,6 +202,33 @@ export function assertGroupsValid(primaryGroup, sharedGroups) {
             '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.
+ */
+export 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"`.
+ */
+export 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/docs/content-types.md

@@ -328,7 +328,7 @@ await contentType.layouts.create({
 });
 ```
 
-Processor options are `'handlebars'`, `'t4-tags'`, and `'programmable-layouts'`. The default is `'handlebars'`. The SDK enforces unique layout names.
+Processor options are `'handlebars'`, `'t4-tags'`, and `'programmable-layouts'`. The default is `'handlebars'`. The SDK enforces unique layout names. `name` is required (throws `Layout name is required` if empty); `code` is optional and may be empty. Renaming a layout to an empty string on update is rejected.
 
 ### Direct update
 

package/docs/error-handling.md

@@ -61,6 +61,32 @@ The final error can result from a call such as:
 await t4.users.create({ username: '', ... });
 ```
 
+### Required fields
+
+Creating an asset without its required `name` (or other required input) throws before any request is sent, so you get a clear message instead of an opaque API error:
+
+```text
+Error: Section name is required
+Error: Content name is required
+Error: Layout name is required
+Error: Media name is required
+Error: Media file is required
+```
+
+The same protection applies on update: you cannot blank out a name that is already set. Omitting `name` leaves it unchanged, but setting it to an empty or whitespace-only string is rejected — through both the resource `update()` method and the mutable `get()` → modify → `save()` pattern:
+
+```typescript
+const section = await t4.section(482).get();
+section.name = '';
+await section.save();
+// Error: Section name is required
+
+await t4.section(482).update({ name: '   ' });
+// Error: Section name cannot be empty
+```
+
+This covers content types, content items, sections, lists, groups, page layouts, media, media types, media categories, navigation objects, and Handlebars helpers/partials.
+
 ## Enable debug logging
 
 Set `T4_DEBUG=1` to print HTTP requests and internal warnings:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@terminalfour/terminalfour-js",
-  "version": "1.1.0",
+  "version": "1.1.1",
   "description": "JavaScript / TypeScript SDK for the Terminalfour Web Services REST API",
   "keywords": [
     "terminalfour",