@terminalfour/terminalfour-js 1.0.2 → 1.1.0

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,45 @@ 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;
 /** 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,38 @@ 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.');
+    }
+}
 /**
  * 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:
@@ -167,6 +167,8 @@ await t4.contentTypes.update(44, {
 });
 ```
 
+> **Warning:** Removing a field deletes that element's content from every content item using this content type, and it cannot be recovered. Only remove a field when you're certain the data is no longer needed. To change a field's length, description, or name, use `updateFields` rather than removing and re-adding.
+
 Change properties of existing fields with `updateFields`. Fields are matched by `name`, and only the properties you supply are changed — anything you omit is left as-is. This is how you increase an element's length (`maxSize`):
 
 ```typescript
@@ -178,7 +180,20 @@ await t4.contentTypes.update(44, {
 });
 ```
 
-`updateFields` can change `maxSize`, `description`, `required`, and `shown`. It throws if a named field does not exist on the content type, and (like the other field operations) nothing is sent to T4 when it throws. To change a field's *type* or *name*, remove it and add a new one instead.
+Rename an existing element with `newName`. The field is matched by its current `name`, and you can rename and change other properties in the same entry:
+
+```typescript
+await t4.contentTypes.update(44, {
+  updateFields: [
+    { name: 'Title', newName: 'Headline' },
+    { name: 'Summary', newName: 'Teaser', maxSize: 300 },
+  ],
+});
+```
+
+After a rename, the returned content type is addressable by the new name (`ct.fields['Headline']`); the old key no longer exists.
+
+`updateFields` can change `maxSize`, `description`, `required`, `shown`, and `newName` (rename). It throws if a named field does not exist on the content type, and (like the other field operations) nothing is sent to T4 when it throws. Renaming an element on a system content type is blocked, except on the Section Meta Data and Extended User types (the same rule that applies to renames through the mutable pattern). It's currently not possible to change a field's *type*.
 
 `updateFields`, `removeFields`, and `addFields` can be combined in a single call; updates are applied first, then removals, then additions.
 
@@ -240,6 +255,8 @@ contentType.removeField('Old Field');
 await contentType.save();
 ```
 
+> **Warning:** `removeField()` deletes the element's content from every content item using this content type once you `save()`, and it cannot be recovered. Prefer `updateFields` (or mutating the field directly) to change a field's length, description, or name.
+
 Delete a content type through the resource:
 
 ```typescript

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

@@ -73,7 +73,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

package/docs/page-layouts.md

@@ -22,6 +22,8 @@ A full page layout includes:
 | `fileExtension` | Output file extension |
 | `syntax` | Syntax such as `'HTML/XML'` |
 | `processor` | Processor such as `'handlebars'` |
+| `primaryGroup` | Owning group ID. `0` means no primary group (Global). |
+| `sharedGroups` | Array of group IDs the layout is shared with |
 
 ## Create a page layout
 
@@ -34,11 +36,35 @@ await t4.pageLayouts.create({
   syntax: 'HTML/XML',      // optional
   processor: 'handlebars', // optional; default: 'handlebars'
   fileExtension: 'html',   // optional
+  primaryGroup: 35,        // optional; owning group ID
+  sharedGroups: [34, 40],  // optional; group IDs to share with
 });
 ```
 
 Processor options are `'handlebars'`, `'t4-tags'`, and `'programmable-layouts'`. The default is `'handlebars'`.
 
+## Group and visibility
+
+`primaryGroup` is the layout'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 layout = await t4.pageLayouts.get(5);
+console.log(layout.primaryGroup); // 35
+console.log(layout.sharedGroups); // [34, 40]
+
+layout.primaryGroup = 0;   // remove from its group (Global)
+layout.sharedGroups = [];
+await layout.save();
+```
+
+Or through `update()`:
+
+```typescript
+await t4.pageLayouts.update(5, { 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).
+
 ## Update a page layout
 
 ### Direct update

package/package.json

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