@terminalfour/terminalfour-js 1.0.0-rc.1

package/docs/content-types.md

@@ -0,0 +1,313 @@
+# Content Types
+
+Use `t4.contentTypes` to inspect and manage content type fields and layouts.
+
+## Contents
+
+- [List and read content types](#list-and-read-content-types)
+- [Create a content type](#create-a-content-type)
+- [Update a content type](#update-a-content-type)
+- [Add or remove fields](#add-or-remove-fields)
+- [Manage content layouts](#manage-content-layouts)
+
+## List and read content types
+
+### List content types
+
+```typescript
+const types = await t4.contentTypes.list();
+for (const contentType of types) {
+  console.log(contentType.id, contentType.name, Object.keys(contentType.fields).length);
+}
+```
+
+### Get a content type
+
+```typescript
+const news = await t4.contentTypes.get(44);
+```
+
+The returned `ContentType` includes these main properties:
+
+| Property | Example or purpose |
+|---|---|
+| `name` | `'News Article'` |
+| `description` | Content type description |
+| `minUserLevel` | `'contributor'` |
+| `workflow` | Assigned workflow |
+| `directEdit` | Direct edit setting |
+| `primaryGroup` | Primary group |
+| `sharedGroups` | Shared groups |
+| `fields` | Field definitions keyed by name |
+
+Each entry in `news.fields` can include:
+
+| Property | Meaning |
+|---|---|
+| `type` | Element type, such as `'Plain Text'` |
+| `required` | Whether a value is required |
+| `maxSize` | Maximum size, such as `200` |
+| `shown` | Whether the field is shown |
+| `listId` | List ID; `0` for non-list fields |
+| `listName` | Resolved list name when `listId > 0`; otherwise `''` |
+| `useAsFilename` | Whether the field supplies the filename |
+| `config` | Repeater settings, including `contentTypeName`, `minRepeats`, and `maxRepeats` |
+| `editor` | HTML editor, such as `'TinyMCE'` or `'Standard Textarea'` |
+
+```typescript
+for (const [name, field] of Object.entries(news.fields)) {
+  console.log(name, field.type, field.required, field.maxSize);
+}
+```
+
+## Create a content type
+
+```typescript
+const contentType = await t4.contentTypes.create({
+  name: 'Blog Post',
+  description: 'A blog post with title and body',
+  elements: [
+    { name: 'Title', type: 'Plain Text', required: true, maxSize: 200 },
+    { name: 'Body', type: 'HTML' },
+    { name: 'Summary', type: 'Plain Text', maxSize: 500, shown: false },
+  ],
+  minUserLevel: 'contributor',
+  directEdit: true,
+});
+```
+
+The SDK always inserts a `Name` element as the first element.
+
+### List-based fields
+
+`Select Box`, `Radio Button`, `Check Box`, `Multiple Select`, `Multi-select List`, `Cascading List`, and `Keyword Selector` fields require `listId`:
+
+```typescript
+await t4.contentTypes.create({
+  name: 'Categorised Article',
+  elements: [
+    { name: 'Title', type: 'Plain Text', required: true },
+    { name: 'Body', type: 'HTML' },
+    { name: 'Category', type: 'Select Box', listId: 71 },
+    { name: 'Tags', type: 'Check Box', listId: 72 },
+  ],
+});
+```
+
+### Repeater fields
+
+A Repeater requires the sub-content type that defines its fields:
+
+```typescript
+await t4.contentTypes.create({
+  name: 'Page with Slides',
+  elements: [
+    { name: 'Title', type: 'Plain Text', required: true },
+    {
+      name: 'Slides',
+      type: 'Repeater',
+      repeater: {
+        contentTypeId: 99,      // required: content type that defines repeater fields
+        layout: 'text/slides',  // optional; default: ''
+        minRepeats: 1,          // optional; default: 0
+        maxRepeats: 10,         // optional; default: 100
+      },
+    },
+  ],
+});
+```
+
+### HTML editors
+
+Set `editor` to choose the editor shown in the T4 content editing UI:
+
+```typescript
+await t4.contentTypes.create({
+  name: 'Article',
+  elements: [
+    { name: 'Title', type: 'Plain Text', required: true },
+    { name: 'Body', type: 'HTML', editor: 'TinyMCE' },
+    { name: 'Notes', type: 'HTML', editor: 'Standard Textarea' },
+  ],
+});
+```
+
+The editor name must exist on the T4 instance. An invalid name produces an error that lists the available options.
+
+## Update a content type
+
+### Direct update
+
+```typescript
+await t4.contentTypes.update(44, {
+  name: 'Renamed',
+  description: 'Updated',
+  directEdit: false,
+});
+```
+
+Add and remove fields in the same call:
+
+```typescript
+await t4.contentTypes.update(44, {
+  addFields: [
+    { name: 'Subtitle', type: 'Plain Text', maxSize: 200 },
+    {
+      name: 'Slides',
+      type: 'Repeater',
+      repeater: {
+        contentTypeId: 99,
+        layout: 'text/slides',
+        minRepeats: 1,
+        maxRepeats: 10,
+      },
+    },
+  ],
+  removeFields: ['Old Field'],
+});
+```
+
+### Mutable item
+
+```typescript
+const contentType = await t4.contentTypes.get(44);
+contentType.name = 'Renamed';
+contentType.description = 'Updated description';
+contentType.minUserLevel = 'moderator';
+contentType.fields['Title'].maxSize = 300;
+contentType.fields['Title'].required = false;
+contentType.fields['Body'].editor = 'Standard Textarea';
+await contentType.save();
+```
+
+Set an HTML field's `editor` to `null` when you want to use the instance default.
+
+## Add or remove fields
+
+`addField()` is asynchronous because it resolves the element type name to an ID. Field additions and removals take effect when you call `save()`.
+
+```typescript
+const contentType = await t4.contentTypes.get(44);
+
+await contentType.addField({
+  name: 'Subtitle',
+  type: 'Plain Text',
+  description: 'Optional subtitle',
+  maxSize: 200,
+  required: false,
+  shown: true,
+});
+
+await contentType.addField({
+  name: 'Category',
+  type: 'Select Box',
+  listId: 71,
+});
+
+await contentType.addField({
+  name: 'Slides',
+  type: 'Repeater',
+  repeater: {
+    contentTypeId: 99,
+    layout: 'text/slides',
+    minRepeats: 1,
+    maxRepeats: 10,
+  },
+});
+
+await contentType.addField({
+  name: 'Body',
+  type: 'HTML',
+  editor: 'TinyMCE',
+});
+
+contentType.removeField('Old Field');
+await contentType.save();
+```
+
+Delete a content type through the resource:
+
+```typescript
+await t4.contentTypes.delete(44);
+```
+
+## System content types
+
+System content types are managed by T4 and back core features. Removing or renaming their elements can break the instance, so the SDK blocks both on `save()` (and through `update({ removeFields })`):
+
+```typescript
+const systemType = await t4.contentTypes.get(systemTypeId);
+systemType.removeField('Some Element');
+await systemType.save();
+// Error: Cannot remove element "Some Element" from content type "..." because it
+// is a system content type. Removing elements from system content types is not allowed.
+```
+
+On a system content type you can still:
+
+- Add new elements with `addField()` or `update({ addFields })`
+- Change an element's `maxSize`
+- Change the content type's `description` and any element's `description`
+
+Two system content types are exempt, because removing and renaming their elements is safe: the **Section Metadata** content type and the **Extended User** content type. On those two, removal and renaming work exactly like a regular content type.
+
+The check runs when you call `save()` or `update()`, not when you call `removeField()`. Because `removeField()` only stages the change in memory, nothing is sent to T4 when the guard blocks a save.
+
+## Manage content layouts
+
+Access layouts through `layouts` on a `ContentType`. Layout operations use names; layout IDs are not exposed.
+
+### List and read layouts
+
+```typescript
+const contentType = await t4.contentTypes.get(44);
+const layouts = await contentType.layouts.list();
+// [{ name: 'text/html', lastModified: Date }]
+
+const layout = await contentType.layouts.get('text/html');
+console.log(layout.name);         // 'text/html'
+console.log(layout.code);         // '<h1>{{Title}}</h1>'
+console.log(layout.lastModified); // Date
+```
+
+### Create a layout
+
+```typescript
+await contentType.layouts.create({
+  name: 'text/json',
+  code: '{ "title": "{{Title}}" }',
+  syntax: 'HTML/XML',      // optional; default: 'HTML/XML'
+  processor: 'handlebars', // optional; default: 'handlebars'
+  extension: 'json',       // optional; default: ''
+});
+```
+
+Processor options are `'handlebars'`, `'t4-tags'`, and `'programmable-layouts'`. The default is `'handlebars'`. The SDK enforces unique layout names.
+
+### Direct update
+
+```typescript
+await contentType.layouts.update('text/html', {
+  code: '<div>{{Title}}</div>',
+  processor: 't4-tags',
+});
+```
+
+### Mutable item
+
+```typescript
+const layout = await contentType.layouts.get('text/html');
+layout.code = '<div>Updated</div>';
+layout.name = 'text/renamed';
+await layout.save();
+```
+
+### Delete a layout
+
+```typescript
+await contentType.layouts.delete('text/old-layout');
+```
+
+---
+
+**Previous:** [Content](./content.md) · **Next:** [Lists](./lists.md)

package/docs/content.md

@@ -0,0 +1,199 @@
+# Content
+
+Content operations are scoped to a section through `t4.section(id).content`.
+
+## Contents
+
+- [List and read content](#list-and-read-content)
+- [Create content](#create-content)
+- [Update content](#update-content)
+- [Approve, duplicate, move, or remove](#approve-duplicate-move-or-remove)
+- [Element values](#element-values)
+- [Values returned on read](#values-returned-on-read)
+
+## List and read content
+
+### List content
+
+```typescript
+const items = await t4.section(482).content.list();
+```
+
+Each summary contains `id`, `name`, `status`, `contentTypeID`, `version`, `lastModified`, `publishDate`, `expiryDate`, `reviewDate`, and `archiveSection`. Summaries do not contain `fields`; call `content.get(id)` to retrieve a full item with resolved fields.
+
+### Get a content item
+
+```typescript
+const item = await t4.section(482).content.get(9132);
+console.log(item.name);
+console.log(item.status);      // 'approved', 'pending', 'draft', 'inactive'
+console.log(item.fields);      // { Title: 'Hello', Category: 'Featured', ... }
+console.log(item.publishDate); // Date object or null
+```
+
+`get()` returns a mutable `ContentItem`:
+
+| Property | Type | Mutable | Description |
+|---|---|---|---|
+| `id` | `number` | no | Content ID |
+| `name` | `string` | yes | Content name |
+| `contentTypeID` | `number` | no | Content type ID |
+| `language` | `string` | no | Language code |
+| `status` | `string` | yes | `'approved'`, `'pending'`, `'draft'`, or `'inactive'` |
+| `version` | `number` | no | Version number |
+| `lastModified` | `Date \| null` | no | Last modification date |
+| `publishDate` | `Date \| null` | yes | Publish date |
+| `expiryDate` | `Date \| null` | yes | Expiry date |
+| `reviewDate` | `Date \| null` | yes | Review date |
+| `archiveSection` | `number \| null` | yes | Archive section ID |
+| `fields` | `Record<string, unknown>` | yes | Resolved content fields |
+
+## Create content
+
+```typescript
+const article = await t4.section(482).content.create({
+  type: 44,
+  name: 'My Article',
+  status: 'draft',                          // default: 'pending'
+  fields: {
+    Title: 'Breaking News',
+    Body: '<p>Article content.</p>',
+    Category: 'Featured',                   // list value by name
+    'Publish Date': new Date(),
+    'Hero Image': './photo.jpg',            // uploads the file automatically
+    Related: { sectionId: 500, linkText: 'More' }, // SS link
+  },
+  publishDate: new Date('2025-07-01'),
+  expiryDate: new Date('2025-12-31'),
+  archiveSection: 500,
+  owner: 38,
+});
+```
+
+The SDK maps field names to element keys, resolves list values to IDs, uploads files, creates link records, and builds the full request body. An unknown field name produces an error that lists the valid fields.
+
+Before creating or updating content, inspect the content type when you need its field constraints:
+
+```typescript
+const type = await t4.contentTypes.get(contentTypeId);
+console.log(type.fields);
+```
+
+Each field includes `name`, `type`, `required`, `maxSize`, `listId`, `listName`, and repeater configuration. Check these values to confirm maximum lengths, list assignments for Select Box or Radio Button fields, required fields, and Repeater sub-fields.
+
+## Update content
+
+### Direct update
+
+Pass only the values to change. `update()` fetches the existing item, merges your changes, and posts the full body:
+
+```typescript
+await t4.section(482).content.update(9132, {
+  name: 'Updated Name',
+  fields: { Title: 'New Title' },
+  status: 'approved',
+  publishDate: new Date('2025-08-01'),
+  expiryDate: null,     // clear the value
+  archiveSection: null, // clear the value
+});
+```
+
+### Mutable item
+
+Retrieve an item when you need to inspect or change several current values:
+
+```typescript
+const article = await t4.section(482).content.get(9132);
+article.name = 'Updated Name';
+article.fields['Title'] = 'New Title';
+article.status = 'approved';
+article.archiveSection = 236;
+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.
+
+## Approve, duplicate, move, or remove
+
+### Approve one item
+
+```typescript
+const article = await t4.section(482).content.get(9132);
+article.fields['Title'] = 'Reviewed Title';
+await article.approve(); // saves with status 'approved'
+```
+
+### Approve all pending items
+
+```typescript
+const count = await t4.section(482).content.approveAll();
+console.log(`Approved ${count} items`);
+```
+
+`approveAll()` lists the section content, filters pending items, and sends one bulk approval request. It returns `0` when no items are pending.
+
+### Duplicate an item
+
+```typescript
+const item = await t4.section(482).content.get(9132);
+
+await item.duplicate();    // same section: appends "(1)" to avoid a name collision
+await item.duplicate(500); // another section: keeps the original name
+```
+
+For duplicates in the same section, the SDK checks existing names and chooses the next available `(n)` suffix.
+
+### Delete, purge, or move
+
+```typescript
+await t4.section(482).content.delete(9132); // soft delete
+await t4.section(482).content.purge(9132);  // permanent removal
+
+const item = await t4.section(482).content.get(9132);
+await item.move(500); // move to section 500
+```
+
+## Element values
+
+| Type | Pass | SDK sends or performs |
+|---|---|---|
+| Plain Text | `"text"` | Pass-through |
+| HTML | `"<p>html</p>"` | Reverts SS link anchors to T4 tags on save; otherwise pass-through |
+| Date | `new Date()`, timestamp, or string | Millisecond timestamp |
+| Select Box | `"Large"` | `listId:itemId` |
+| Radio Button | `"Large"` | `listId:itemId` |
+| Checkbox | `["Large", "Small"]` | `listId:id1,id2` |
+| Multiple Select | `["Large", "Small"]` | `listId:id1,id2` |
+| Multi-Select List | `["Large", "Small"]` | `listId:id1;listId:id2` |
+| Cascading List | `["Soccer", "Liverpool"]` | Resolves sublists automatically |
+| Media | `10928` | String ID |
+| Media (inline) | `{ file: './photo.jpg', name: 'Photo', category: 391 }` | Uploads to the media library and uses the returned ID |
+| File / Image | `"./path.jpg"`, URL, Blob, or `{ file, filename }` | Uploads through `/upload/` |
+| Section/Content Link | `{ sectionId, contentId?, linkText? }` | Creates an SS record and T4 tag |
+| Decimal | `3.14` | Pass-through |
+| Whole Number | `42` | Pass-through |
+| Content Owner | `38` | String; resolves to user details on read |
+| Group Select | `[41, 34, 40]` | Comma-separated value; resolves to group objects on read |
+| Keyword Selector | `{ or: ["Large", { and: ["Small", "Other"] }] }` | Formats OR/AND groups |
+| Repeater | `[{ name: 'Slide 1', fields: { Heading: 'Hi' } }]` | Full nested resolution |
+
+## Values returned on read
+
+The SDK converts raw API values before assigning them to `ContentItem.fields`:
+
+| Element | Returned value |
+|---|---|
+| List | Names, such as `"Large"` instead of `"1:2"` |
+| Date | `Date` object |
+| Media | Object with `id`, `name`, `filename`, `description`, `mediaType`, `downloadLink`, `path`, `fileSize`, and `lastModified` |
+| File / Image | Object with `filename`, `fileSize`, and `downloadLink` |
+| SS link | `{ sectionId, contentId?, linkText, path }` |
+| HTML SS link | Inline `<a href="#" data-t4-sslink="..." data-section-id="..." data-content-id="...">linkText</a>` converted from a T4 `<t4 sslink_id="..." />` tag |
+| Content Owner | User object with `id`, `type`, `username`, `firstName`, `lastName`, and `emailAddress` |
+| Group Select | Array of `{ id, name, selected }` objects |
+| Keyword Selector | `{ or: [...] }` structure |
+| Repeater | Array of `{ name, fields }` with recursively resolved fields |
+
+---
+
+**Previous:** [Sections](./sections.md) · **Next:** [Content Types](./content-types.md)

package/docs/error-handling.md

@@ -0,0 +1,86 @@
+# Error Handling
+
+The SDK distinguishes API failures from client-side validation errors. Enable debug logging when you need request-level detail.
+
+## Handle API errors
+
+API failures throw `T4ApiError`. Check its properties to identify the failed request and response:
+
+```typescript
+import { T4Client, T4ApiError } from '@terminalfour/terminalfour-js';
+
+try {
+  await t4.section(482).content.get(99999);
+} catch (error) {
+  if (error instanceof T4ApiError) {
+    console.error(error.statusCode);    // 404
+    console.error(error.statusText);    // '404'
+    console.error(error.requestMethod); // 'GET'
+    console.error(error.requestUrl);    // full URL
+    console.error(error.responseBody);  // parsed response body
+    console.error(error.cause);         // original error for network failures
+  }
+}
+```
+
+| Property | Description |
+|---|---|
+| `statusCode` | HTTP status code |
+| `statusText` | HTTP status text |
+| `requestMethod` | Request method |
+| `requestUrl` | Full request URL |
+| `responseBody` | Parsed response body |
+| `cause` | Original error for network failures |
+
+## Handle validation errors
+
+Client-side validation throws standard `Error` instances. Messages include the value that failed and valid options when available.
+
+```typescript
+await t4.section(482).content.create({
+  type: 44,
+  name: 'Test',
+  fields: { Nonexistent: 'value' },
+});
+// Error: Unknown field "Nonexistent" on this content type.
+//        Valid fields are: "Title", "Body", "Category"
+```
+
+Other examples:
+
+```text
+Error: Invalid list value "Medium" for field "Size".
+       Valid options are: "Large", "Small"
+
+Error: Username is required
+```
+
+The final error can result from a call such as:
+
+```typescript
+await t4.users.create({ username: '', ... });
+```
+
+## Enable debug logging
+
+Set `T4_DEBUG=1` to print HTTP requests and internal warnings:
+
+```bash
+T4_DEBUG=1 node my-script.js
+```
+
+Graceful degradation paths, including failed media lookups and group name resolution, log through `debugWarn`. These messages appear only when `T4_DEBUG=1`.
+
+## Clear stale cache data
+
+After changing content types, lists, or other configuration, invalidate every SDK cache:
+
+```typescript
+t4.clearCache();
+```
+
+This clears cached content type templates, list values, element types, meta tags, group trees, and media types immediately.
+
+---
+
+**Previous:** [Handlebars](./handlebars.md) · **Next:** [TypeScript Reference](./typescript.md)