@terminalfour/terminalfour-js 1.0.3 → 1.1.1

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

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

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

@@ -1,3 +1,4 @@
+import { readPrimaryGroup, readSharedGroups, writePrimaryGroup, writeSharedGroups, assertGroupsValid, assertRequired } from '../utils.js';
 /** Maps SDK type codes to API type codes */
 const SDK_TO_API = {
     'a-to-z': 'a2z',
@@ -985,6 +986,8 @@ export class NavigationObject {
         this.enabled = raw.isEnabled;
         this.cachingEnabled = raw.isCachingEnabled;
         this.previewEnabled = raw.isPreviewModeEnabled;
+        this.primaryGroup = readPrimaryGroup(raw.primaryGroup);
+        this.sharedGroups = readSharedGroups(raw.sharedGroups);
         // Convert properties to camelCase keys with string values
         const originalKeys = [];
         const rawCamelProps = {};
@@ -1000,6 +1003,8 @@ 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);
         // Rebuild properties in API format
@@ -1019,6 +1024,8 @@ export class NavigationObject {
             isEnabled: this.enabled,
             isCachingEnabled: this.cachingEnabled,
             isPreviewModeEnabled: this.previewEnabled,
+            primaryGroup: writePrimaryGroup(this.primaryGroup),
+            sharedGroups: writeSharedGroups(this.sharedGroups),
             properties: apiProperties,
         };
         await this._httpClient.request({
@@ -1235,6 +1242,7 @@ export class NavigationResource {
             throw new Error('Navigation object type is required');
         if (!NAVIGATION_TYPE_NAMES[data.type])
             throw new Error(`Unknown navigation type "${data.type}"`);
+        assertGroupsValid(data.primaryGroup ?? 0, data.sharedGroups);
         const apiType = SDK_TO_API[data.type];
         const properties = await this.buildProperties(data.type, (data.properties ?? {}));
         const body = {
@@ -1244,8 +1252,8 @@ export class NavigationResource {
             name: data.name,
             description: data.description ?? '',
             navigationType: apiType,
-            sharedGroups: [],
-            primaryGroup: { id: 0 },
+            sharedGroups: writeSharedGroups(data.sharedGroups),
+            primaryGroup: writePrimaryGroup(data.primaryGroup ?? 0),
             properties,
         };
         // CSS Selector quirk: requires "section-name": "on" at the top level
@@ -1289,6 +1297,10 @@ export class NavigationResource {
             nav.previewEnabled = data.previewEnabled;
         if (data.cachingEnabled !== undefined)
             nav.cachingEnabled = data.cachingEnabled;
+        if (data.primaryGroup !== undefined)
+            nav.primaryGroup = data.primaryGroup;
+        if (data.sharedGroups !== undefined)
+            nav.sharedGroups = data.sharedGroups;
         // Merge properties rather than replace — callers pass only what changes
         if (data.properties !== undefined) {
             nav.properties = {

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

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

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

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

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

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

package/dist/esm/section-ref.js

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

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

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

package/dist/esm/t4-client.js

@@ -13,6 +13,7 @@ import { PageLayoutResource } from './resources/page-layout-resource.js';
 import { MediaTypeResource } from './resources/media-type-resource.js';
 import { NavigationResource } from './resources/navigation-resource.js';
 import { Handlebars } from './handlebars.js';
+import { ContentCache } from './content-cache.js';
 import { invalidateAllCaches, normaliseBaseUrl, assertNotBrowser } from './utils.js';
 /**
  * Main entry point for the T4 SDK.
@@ -54,12 +55,16 @@ export 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 ContentCache(this.httpClient, this.defaultLanguage, this.mediaCreateFn);
     }
     /**
      * Returns a section reference scoped to the given section ID.
      */
     section(id) {
-        return new SectionRef(this.httpClient, id, this.defaultLanguage, this.mediaCreateFn);
+        return new SectionRef(this.httpClient, id, this.defaultLanguage, this.mediaCreateFn, this.contentCache);
     }
     /**
      * Returns a media category reference scoped to the given category ID.

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

@@ -170,6 +170,65 @@ export function flattenGroups(groups, map = new Map()) {
     }
     return map;
 }
+/** Reads the API `primaryGroup` object into a plain group id (0 = none). */
+export function readPrimaryGroup(raw) {
+    return raw?.group?.id ?? raw?.id ?? 0;
+}
+/** Reads the API `sharedGroups` array into a plain array of group ids. */
+export function readSharedGroups(raw) {
+    return (raw ?? []).map((g) => g.id);
+}
+/** Writes a plain group id back to the API `primaryGroup` shape (0/falsy = none). */
+export function writePrimaryGroup(id) {
+    return { id: id || null };
+}
+/** Writes a plain array of group ids back to the API `sharedGroups` shape. */
+export 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.
+ */
+export 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.
+ */
+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

@@ -36,8 +36,8 @@ The returned `ContentType` includes these main properties:
 | `minUserLevel` | `'contributor'` |
 | `workflow` | Assigned workflow |
 | `directEdit` | Direct edit setting |
-| `primaryGroup` | Primary group |
-| `sharedGroups` | Shared groups |
+| `primaryGroup` | Owning group ID (`0` = none) |
+| `sharedGroups` | Shared group IDs. Cannot contain `primaryGroup`. |
 | `fields` | Field definitions keyed by name |
 
 Each entry in `news.fields` can include:
@@ -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/content.md

@@ -113,6 +113,19 @@ await article.save();
 
 `save()` defaults the status to `'pending'` to match T4's approval workflow. Set `item.status = 'approved'` before saving if the item must remain approved.
 
+`save()` resolves every field type the same way `content.create()` and `content.update()` do — including Repeater fields. A repeater is read back as an array of `{ name, fields }` items (see [Values returned on read](#values-returned-on-read)), and you assign the same friendly shape back:
+
+```typescript
+const deck = await t4.section(482).content.get(9200);
+deck.fields['Slides'] = [
+  { name: 'Slide 1', fields: { Heading: 'Welcome' } },
+  { name: 'Slide 2', fields: { Heading: 'Agenda' } },
+];
+await deck.save();
+```
+
+Each repeater item's sub-fields are resolved into the API's element format automatically, so the mutable `get()` → modify → `save()` path and `content.update()` produce identical results.
+
 ## Approve, duplicate, move, or remove
 
 ### Approve one item

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:
@@ -73,7 +99,9 @@ Graceful degradation paths, including failed media lookups and group name resolu
 
 ## Clear stale cache data
 
-After changing content types, lists, or other configuration, invalidate every SDK cache:
+Content type writes through the SDK — `contentTypes.create()`, `contentTypes.update()`, `contentTypes.delete()`, and `ContentType.save()` (including `addField`/`removeField`) — clear the SDK's caches automatically, so a content type edit is reflected on the next read without any extra step.
+
+You still need to clear the cache manually when configuration changes **outside** this SDK instance — for example content type, list, or other changes made in the T4 UI or by another process while your client is running:
 
 ```typescript
 t4.clearCache();

package/docs/getting-started.md

@@ -141,6 +141,10 @@ The SDK caches content type templates, list values, element type definitions, an
 t4.clearCache();
 ```
 
+These caches are shared across the whole client, so reuse a single `T4Client` instance for the life of your task. Traversing the hierarchy — for example fetching and updating content across many sections with `t4.section(id)` — reuses cached element types and content type definitions instead of re-fetching them for each section. Creating a new `T4Client` per section would defeat this, so avoid that in loops.
+
+Editing a content type through this client (`contentTypes.update()`, `ContentType.save()`, and so on) clears these caches for you, so your changes show up on the next read. Call `clearCache()` manually only for changes made outside this client instance.
+
 ---
 
 **Next:** [Sections](./sections.md)

package/docs/lists.md

@@ -17,8 +17,8 @@ const list = await t4.lists.get(71);
 | `description` | List description |
 | `isForcedLanguage` | `false` |
 | `isDefaultLanguage` | `false` |
-| `primaryGroup` | `0` |
-| `sharedGroups` | `[]` |
+| `primaryGroup` | Owning group ID (`0` = none) |
+| `sharedGroups` | Shared group IDs. Cannot contain `primaryGroup`. |
 | `items` | Item definitions keyed by name |
 
 Items are keyed by name:

package/docs/navigation.md

@@ -34,6 +34,8 @@ console.log(navigation.type);            // 'a-to-z'
 console.log(navigation.enabled);         // true
 console.log(navigation.cachingEnabled);  // false
 console.log(navigation.previewEnabled);  // true
+console.log(navigation.primaryGroup);    // 1 (owning group ID; 0 = Global)
+console.log(navigation.sharedGroups);    // [34, 40]
 console.log(navigation.properties);      // properties vary by type
 ```
 
@@ -46,6 +48,8 @@ Type-specific properties use JavaScript booleans, numbers, and arrays. The SDK o
 | `enabled` | yes | Whether the navigation is active |
 | `cachingEnabled` | yes | Whether output caching is enabled |
 | `previewEnabled` | yes | Whether preview mode is enabled |
+| `primaryGroup` | yes | Owning group ID. `0` means no primary group (Global). |
+| `sharedGroups` | yes | Array of group IDs the object is shared with |
 | `properties` | yes | Type-specific configuration |
 
 ## Create a navigation object
@@ -63,7 +67,16 @@ await t4.navigation.create({
 });
 ```
 
-Only `type` and `name` are required. Properties have default values.
+Only `type` and `name` are required. Properties have default values. `create()` also accepts optional `primaryGroup` and `sharedGroups`:
+
+```typescript
+await t4.navigation.create({
+  type: 'breadcrumbs',
+  name: 'Main Breadcrumbs',
+  primaryGroup: 35,       // optional; owning group ID
+  sharedGroups: [34, 40], // optional; group IDs to share with
+});
+```
 
 ## Update a navigation object
 
@@ -99,6 +112,22 @@ navigation.properties.beforeHtml = '<div>';
 await navigation.save();
 ```
 
+## Group and visibility
+
+`primaryGroup` is the object's owning group and `sharedGroups` are the groups it is shared with. Both are read on `get()` and written on `save()`, `update()`, and `create()`. Set `primaryGroup` to `0` to remove the owning group (Global):
+
+```typescript
+const navigation = await t4.navigation.get(181);
+navigation.primaryGroup = 0;   // remove from its group (Global)
+navigation.sharedGroups = [];
+await navigation.save();
+
+// Or through update()
+await t4.navigation.update(181, { primaryGroup: 35, sharedGroups: [34] });
+```
+
+`sharedGroups` cannot contain the `primaryGroup` id: a group cannot be both the owning group and a shared group. The SDK throws a clear error before sending the request (Terminalfour otherwise returns an opaque 500).
+
 ## Delete a navigation object
 
 ```typescript